详细参数

版本记录 2026-10-19：WebSocket 流协议新增 baseline_reset（type=15）上行信令，支持在对话过程中将数字人画面复位到闭口静息态。switch_avatar（type=16）上行信令，支持直播运行中播放转场视频并切换数字人形象。

创建会话

创建一次会话，Vidu 会用你传入的 customer_rtc 加入你的 RTC 频道，准备推送数字人画面。

请求头

POST /live/s_avatar/component
Authorization: Token vda_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

请求体示例

{
  "model": "vidu-s2",
  "resolution": "720p",
  "image_uri": "https://example.com/avatar.jpg",
  "managed_rtc": {},
  "action": {
    "enabled": true,
    "library_id": "<action_library_id>"
  }
}

请求字段说明

modelString

模型版本。vidu-s2（默认，最新模型）

personaString

数字人的人设，5万字以内。用于指导数字人做出更合理的动作

resolutionString

720p（默认）、1080p、2k

image_uristring条件

条件必填，image_uri和avatar_id二选一，数字人形象图片地址，支持图片 URL 和 base64。仅支持 1 张【单人】图片，支持全身 / 半身、各种风格。格式：PNG / JPG / JPEG / WEBP；图片大小 ≤ 50MB；base64 decode 后字节长度 < 20M，且需包含内容类型前缀，例如 data:image/png;base64,{base64_encode}

avatar_idString条件

条件必填，image_uri和avatar_id二选一，具体见图片上传

customer_rtcobject条件

条件必填，使用您提供的RTC 频道信息，具体见下表，customer_rtc和managed_rtc二选一

managed_rtcobject条件

条件必填，使用vidu s提供的RTC频道，具体见下表，customer_rtc和managed_rtc二选一

actionobject

用来控制是否对用户发言做运行时动作匹配，以及使用平台默认动作库还是自建动作库

customer_rtc 字段

providerenum必填

必填，artc（阿里）/ trtc（腾讯）/ agora（声网）/ volcengine（火山引擎）

app_idstring条件

条件必填，RTC 应用 ID，与服务端配置不同时传入覆盖（provider 是 artc 时可不填）

channel_idstring条件

条件必填，RTC 频道 ID，token 内已包含时可省略

user_idstring条件

条件必填，推流用户 ID，token 内已包含时可省略

tokenstring必填

必填，RTC 鉴权 token（ARTC Base64 Token / TRTC UserSig / Agora Token / 火山 RTC AccessToken）

agora_int_uiduint32

选填，使用声网RTC，且需要指定 int类型 uid 入会时，传此参数

managed_rtc 字段

providerenum

选填，托管 RTC 的供应商：artc（阿里，默认值）/ trtc（腾讯）/ agora（声网）/ volcengine（火山引擎）。

enable_recordingbool

选填，是否开启录播下载回显，默认 false。

action字段

enabledbool · false

是否启用运行时动作匹配。省略整个 action 或为 false 则不匹配

library_idString · "0"

自建动作库 ID；"0" 或不传表示平台默认库。库不存在或已删除返回 400，库不属于本账号返回 403，均不创建会话

调用示例：指定托管供应商并开启录播回显

curl -X POST "https://api.vidu.cn/live/v1/external-lives" \
  -H "Authorization: vda_<api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "image_uri": "https://example.com/avatar.jpg",
    "managed_rtc": {
      "provider": "trtc",
      "enable_recording": true
    }
  }'

调用示例：使用自带 RTC 频道

curl -X POST "https://api.vidu.cn/live/v1/external-lives" \
  -H "Authorization: vda_<api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "image_uri": "https://example.com/avatar.jpg",
    "customer_rtc": {
      "provider": "artc",
      "app_id": "<your_rtc_app_id>",
      "channel_id": "<your_channel_id>",
      "user_id": "<your_user_id>",
      "token": "<your_rtc_token>"
    }
  }'

响应体示例：使用平台托管的RTC频道

{
  "live": {
    "id": "<live_id>",
    "status": "waiting"
  },
  "client_secret": "<client_secret>",
  "managed_rtc": {
    "provider": "trtc",
    "app_id": "<rtc_app_id>",
    "channel_id": "<rtc_channel_id>",
    "user_id": "<rtc_user_id>",
    "token": "<rtc_token>",
    "token_expire_at": "<unix_timestamp_seconds>"
  }
}

响应体示例：使用自带的 RTC 频道

{
  "live": {
    "id": "1234567890",
    "status": "waiting",
    "call_mode": "video",
    "avatar": {
      "image_uri": "https://signed-url/avatar.jpg"
    },
    "created_at": "1710000000",
    "start_time": "0",
    "end_time": "0",
    "trace_id": "abc123",
    "creator_id": "10000"
  },
  "client_secret": "v1.xxxx.yyyy"
}

响应字段说明

字段	说明
live.id	直播 ID
live.status	waiting（数字人未就绪）；全部取值：waiting / prepared / on_live / ending / ended
live.trace_id	链路 ID
live.model	实际生效的模型（vidu-s2 / vidu-s1）
live.resolution	实际生效的分辨率（720p / 1080p / 2K）
client_secret	WebSocket 建连的短期签名 token（有效期 24h）
managed_rtc.provider	本次实际生效的供应商
managed_rtc.app_id	RTC 应用 ID
managed_rtc.channel_id	RTC 频道 ID
managed_rtc.user_id	分配给客户端的用户 ID（与推流端身份不同）
managed_rtc.token	客户端入会 token
managed_rtc.token_expire_at	token 到期时间，秒级 Unix 时间戳。有效期不少于 24 小时 10 分钟，覆盖单次组件版直播最长 24 小时的会话时长
live.action	回显运行时动作匹配配置

查询直播

GET /live/v1/lives/{live_id}
Authorization: Token vda_xxxxxxxxxxxxxxxxxxxx

响应体为 {"live": { ... }}，结构同创建响应中的 live 对象。

查询录播

平台托管 RTC 且 managed_rtc.enable_recording=true 时，直播结束后可查询录播文件下载地址。

curl -X GET "https://api.vidu.cn/live/v1/lives/<live_id>/recording" \
  -H "Authorization: vda_<api_key>"

WebSocket 流协议

WebSocket 是核心通道：既发控制信令，也上行 PCM 音频和转写文本。

建立连接

GET /live/v1/external-lives/{live_id}/stream?conn_id={conn_id}&client_secret={client_secret}
Connection: Upgrade
Upgrade: websocket

浏览器场景用 client_secret query 参数；服务端场景用 Authorization Header，二者任一即可；若同时提供，二者必须属于同一用户与同一 live，否则返回 403。

live_idstring必填

必填，路径参数，创建时返回

conn_idstring

客户端生成的连接 ID；缺省时服务端生成

client_secretstring

创建下发的短期签名 token（有效期 24h）

连接约定

项	约定
文本帧	TextMessage + JSON（WsSignal），最大 16 MiB
二进制帧	BinaryMessage（裸 PCM 音频），最大 16 MiB
首帧要求	必须为 `conn_init`；成功回执前上行的音频与控制信令会被丢弃（详见「信号类型」）
心跳	服务端约每 5s 发送 ping；约 15s 未回 pong 即断开（普通数据帧不续期）

通用消息格式

请求体示例

{
  "type": 1,
  "live_id": "1234567890",
  "conn_id": "app-conn-1",
  "seq_id": 1,
  "payload": { }
}

typeint

信号类型，见「信号类型」

live_idstring

须与路径一致

user_idstring

用户 ID；服务端下发的回执中会携带，客户端可不传

conn_idstring

客户端生成的连接 ID（与建连参数一致）

seq_idint

客户端自增序号；conn_init_ack 的 seq_id 为请求 seq_id + 1（其他回执不适用）

payloadobject

按 type 不同携带对应子结构

信号类型

客户端 → MaaS

type	名称	说明
1	conn_init	必填，连接初始化；首帧必须发送。成功回执前，上行 PCM 音频帧、audio_interrupted、prompt_operation、baseline_reset、switch_avatar 会被丢弃，call_hangup 与 type=9/10 仍会处理
5	call_hangup	主动挂断；直接关闭 WS 等效
7	audio_interrupted	打断数字人当前回复，最佳时机为每次 VAD 检测到用户开口时
9	input_transcription	驱动数字人动作的文本，content 为空则忽略
10	output_transcription	模型生成的回复文本；content 为空则忽略
11	prompt_operation	运行中增删参考图，仅 model=vidu-s2 支持；成功与失败均回 prompt_operation_ack（type=12）
15	baseline_reset	把数字人画面复位到闭口静息态；无载荷。成功与失败均不回执
16	switch_avatar	播放转场视频并切换数字人形象；成功不回执，失败下发 type=103 error

MaaS → 客户端

type	名称	说明
2	conn_init_ack	初始化回执
6	force_hangup	服务端强制挂断，随后服务端关闭 WS
12	prompt_operation_ack	参考图操作回执；成功与失败都会下发
103	error	switch_avatar 失败回执，payload.error.source 固定为 switch_avatar

信令示例

conn_init（type=1）

{
  "type": 1,
  "seq_id": 1,
  "payload": {
    "conn_init": { "version": 1 }
  }
}

conn_init_ack（type=2）— 成功

{
  "type": 2,
  "seq_id": 2,
  "payload": {
    "conn_init_ack": {
      "success": true,
      "error_code": "",
      "error_msg": "",
      "server_timestamp": 1710000000
    }
  }
}

input_transcription（type=9） — 驱动数字人动作的文本，或者你的 ASR 识别出的用户话：

{
  "type": 9,
  "seq_id": 10,
  "payload": {
    "text_msg": {
      "msg_id": "msg-001",
      "content": "比个心",
      "timestamp": 1710000000000
    }
  }
}

output_transcription（type=10） — 你的 LLM 生成的回复话：

{
  "type": 10,
  "seq_id": 11,
  "payload": {
    "text_msg": {
      "msg_id": "msg-002",
      "content": "你好！很高兴见到你。",
      "timestamp": 1710000001000
    }
  }
}

audio_interrupted（type=7）

{
  "type": 7,
  "seq_id": 12,
  "payload": { }
}

call_hangup（type=5）

{
  "type": 5,
  "seq_id": 13,
  "payload": {
    "hangup": { "hangup_reason": "client_hangup" }
  }
}

force_hangup（type=6）

{
  "type": 6,
  "payload": {
    "hangup": { "hangup_reason": "timeout" }
  }
}

prompt_operation（type=11）

直播运行中增删参考图（手持物 / 换装 / 换背景），仅 model=vidu-s2 的 video 直播支持；conn_init 成功前上行的 prompt_operation 会被丢弃。

请求字段

typeinteger必填

固定 11。

live_idstring必填

当前直播 ID。

conn_idstring可选

连接标识。

seq_idinteger可选

客户端自增序号，回执原样带回。

payload.prompt_operation.op_typestring可选

switch（默认）/ remove。remove 不带 images 时清除最近一张。

payload.prompt_operation.imagesobject[]条件

switch 必填 1~3 张；remove 可省略（清除最近一张）或传 1~3 个（按 image_id 定点清除）。

images[].image_uristring条件

switch 必填，支持图片 URL 和 base64（data URI）。

images[].image_idstring必填

1~128 字符，单次请求内不可重复。

images[].kindstring可选

object（手持物）/ garment（换装）/ background（换背景）；不传由服务端自动识别。

images[].user_textstring可选

该参考图的用户描述，作为上下文。

请求示例：

{
  "type": 11,
  "live_id": "1234567890",
  "conn_id": "<conn_id>",
  "seq_id": 20,
  "payload": {
    "prompt_operation": {
      "op_type": "switch",
      "images": [
        {
          "image_uri": "https://example.com/ref.png",
          "image_id": "img-1",
          "kind": "garment",
          "user_text": "换一件红色外套"
        }
      ]
    }
  }
}

回执：服务端始终回 prompt_operation_ack（type=12），成功与失败都会回执，seq_id 原样回填。

回执字段

typeinteger

固定 12。

live_idstring

当前直播 ID。

seq_idinteger

原样回带请求的 seq_id。

payload.prompt_operation_ack.successbool

是否执行成功。

payload.prompt_operation_ack.error_codestring

失败时的错误码，成功时为空。

payload.prompt_operation_ack.error_msgstring

失败原因，可读描述。

错误码：

错误码	触发条件
PROMPT_OP_PARAM_INVALID	入参非法（图片数量、image_id、image_uri 协议等）。
PROMPT_OP_MODEL_NOT_SUPPORTED	当前直播不是 vidu-s2 的 video 直播。
PROMPT_OP_IMAGE_TRANSFER_FAILED	参考图转存或签名失败（多图任一失败即整单失败）。
PROMPT_OP_RENDER_NOT_CONNECTED	渲染服务未就绪，暂时无法执行，可稍后重试。
PROMPT_OP_FAILED	其它失败。

baseline_reset（type=15）

客户端在对话过程中可随时触发，立即把数字人画面姿态复位到不说话的初始画面。

请求字段

typeinteger必填

固定 15。

live_idstring必填

当前直播 ID。

conn_idstring可选

连接标识。

seq_idinteger可选

客户端自增序号。

payloadobject可选

本信令不携带载荷；若误带，服务端忽略。

请求示例

{
  "type": 15,
  "live_id": "1234567890",
  "conn_id": "<conn_id>"
}

回执语义：无论成功或失败均不下发回执，请勿以是否收到回执判断执行结果。

重复触发是幂等的（等价于重复下发同一闭口姿态），但不建议无意义地高频连发。

switch_avatar（type=16）

直播运行中，客户端可让数字人播放一组转场视频，并在播放过程中把数字人切换为新的形象。

消息为 JSON 文本帧，type=16，外层结构与其他信令一致。

请求字段

typeinteger必填

固定 16。

live_idstring必填

当前直播 ID。

conn_idstring可选

连接标识。

seq_idinteger可选

客户端自增序号，失败回执会原样带回，便于关联请求。

payload.switch_avatar.switch_videosstring[]必填

转场视频地址列表，1~10 个，每项须为 http(s) 地址；单个视频时长 ≤30 分钟，累计 ≤60 分钟。按列表顺序播放，至少完整播放一轮。

payload.switch_avatar.avatar_idstring必填

资产库形象 ID（JSON 中为字符串）。

请求示例

{
  "type": 16,
  "live_id": "1234567890",
  "conn_id": "<conn_id>",
  "seq_id": 7,
  "payload": {
    "switch_avatar": {
      "switch_videos": [
        "https://example.com/transition_1.mp4",
        "https://example.com/transition_2.mp4"
      ],
      "avatar_id": "100012345"
    }
  }
}

回执语义：成功不下发任何回执（不要以 WS 是否写出成功判断执行结果）；失败时下发一帧 error。

失败回执字段

typeinteger

固定 103。

live_idstring

当前直播 ID。

seq_idinteger

原样回带请求的 seq_id。

payload.error.sourcestring

固定 switch_avatar。

payload.error.codestring

错误码，见下表。

payload.error.messagestring

可读描述。

错误码

错误码	触发条件
`SWITCH_AVATAR_PARAM_INVALID`	入参非法：switch_videos 为空、数量超过 10 个、含非 http(s) 地址或时长越界；avatar_id 未传；
`SWITCH_AVATAR_LIVE_NOT_ACTIVE`	直播未在运行中（或已结束 / 不可用）。
`SWITCH_AVATAR_MEDIA_TRANSFER_FAILED`	转场视频或新形象图片处理失败。
`SWITCH_AVATAR_RENDER_NOT_CONNECTED`	渲染服务未就绪，暂时无法切换，可稍后重试。
`SWITCH_AVATAR_FAILED`	其它失败。

注意事项

新形象在转场视频播放完成后生效；转场期间画面按视频列表顺序播放。
avatar_id 场景会一并应用该形象的形象描述。

音频二进制帧

通过 WebSocket BinaryMessage 发送，无 JSON 封装，直接传输原始 PCM 字节流。

参数	值
编码	PCM 16-bit 有符号小端（s16le）
采样率	24,000 Hz
声道	单声道（mono）
数据速率	48 字节 / 毫秒
建议帧大小	20ms（960 字节）或 100ms（4,800 字节）

动作库

自建动作库供创建会话时用 action.library_id 绑定。按账号 owner 隔离，同一用户下多个 API Key 共用一套库；每账号最多 20 个库，每库最多 100 条动作。均需 Authorization: Token vda_xxx，ID 在 JSON 中为 string。

方法	路径	说明
POST	`/action-libraries`	创建库。`name` 必填，超配额或重名返回 400
GET	`/action-libraries?pager.page=0&pager.pagesz=10`	列表，返回 `total` + `items`，创建时间倒序，只含本账号未删除库
GET	`/action-libraries/{id}`	库详情。他人库或不存在均返回 404
PATCH	`/action-libraries/{id}`	改 `name` / `description`，重名返回 400
DELETE	`/action-libraries/{id}`	删库，库内动作一并删除；进行中的会话不受影响
POST	`/action-libraries/{id}/actions`	新增动作，同步改写 `description` 后入库，常见耗时数秒
GET	`/action-libraries/{id}/actions[/{action_id}]`	列表 / 详情，可查看改写后的 `description`
PATCH	`/action-libraries/{id}/actions/{action_id}`	改 `name` 不触发改写；改 `description` 会先改写，失败则原记录不变
DELETE	`/action-libraries/{id}/actions/{action_id}`	删除一条动作

字段约束

字段	必填	说明
库 `name`	是	1~50 字符，同账号未删除范围内唯一
库 `description`	否	≤ 200，可空
动作 `name`	是	1~20 字符，库内未删除范围内唯一
动作 `description`	是	请求侧 5~500；服务端改写后再校验 5~500，改写失败则不入库，可重发同一请求重试

库对象另返回 id、action_count（未删除动作数）、created_at / updated_at（ISO 8601）；动作对象另返回 id、action_library_id 与同样的时间字段。

curl -X POST 'https://{host}/live/v1/action-libraries' \
  -H 'Authorization: Token vda_xxx' -H 'Content-Type: application/json' \
  -d '{"name":"默认手势库","description":"挥手点头等"}'

curl -X POST 'https://{host}/live/v1/action-libraries/<id>/actions' \
  -H 'Authorization: Token vda_xxx' -H 'Content-Type: application/json' \
  -d '{"name":"挥手","description":"双手向镜头挥手打招呼"}'

错误响应及说明

创建会话时与 RTC 来源相关的错误：

场景	HTTP 状态码	说明
`managed_rtc` 与 `customer_rtc` 同时传	`400`	字段定位 `managed_rtc`；不创建会话、不占用并发
`provider` 传入未定义取值	`400`	请求校验拦截
平台侧 `artc` 凭证未配置或 token 签发失败	`500`	创建失败，不回退其他供应商
平台侧 `trtc` / `agora` / `volcengine` 凭证未配置或 token 签发失败	`503`	创建失败，不回退其他供应商

建连被拒绝时返回 HTTP 状态码：

HTTP 状态码	场景	处理建议
`401`	header 与 `client_secret` 均缺失，或 `client_secret` 无效 / 过期	补充或更新相关信息
`403`	live 不属于当前用户	更换live或者API key
`400`	非外接 live、live 已结束、`live_id` 非法	确认live信息
`409`	该 live 已有活跃连接	查阅live状态

建连成功后，初始化结果通过 conn_init_ack 返回，其中的 error_code 取值如下：

error_code	场景	处理建议
`NOT_READY`	渲染服务未就绪	稍后重试 `conn_init`，无需重连 WS
`LIVE_ENDED`	live 已结束	需重新创建
`LIVE_CONN_INIT_FAILED`	其他初始化失败	关闭当前 WS，重新创建；仍失败则带 `live_id` / `trace_id` 反馈

接入要点

首帧必须是 conn_init；NOT_READY 属正常现象，重试 conn_init 即可，不要重连 WS。
保持心跳：及时响应服务端 ping；约 15s 未回 pong 会被判定为死连接并断开。
建议服务端代理 WebSocket 鉴权，避免 Vidu API Key 泄漏到浏览器端。
目前已支持阿里（artc）、腾讯（trtc）、声网（agora）和火山引擎（volcengine）的 RTC。
如不想自建 RTC 频道，可传 managed_rtc 使用平台托管 RTC。

定价信息

按秒计费，每秒1积分（0.03125元）
如果用户账户余额的最小积分数小于45积分（约1.4元），则无法发起任务
使用平台托管 RTC 不额外收费：不新增独立计费项、计费 SKU 或附加扣费，仍沿用上述组件版直播计费规则（任务类型 live）

FAQ

使用阿里RTC，容易进错入口，请使用这个地址：https://live.console.aliyun.com/#/liveRtc/list。具体操作为在视频直播控制台 → 左侧导航栏的 直播+ > 实时音视频 > 应用管理 > 创建应用。
创建完成后点「管理」，在基本信息页获取 AppID 与 AppKey。

当前Linux服务端不支持使用体验包，需要购买旗舰版且找客服开通权限才可使用。以下环境可以使用体验包且不需要客服: iOS, Android, HarmonyOS, Mac, Windows, Web,Electron, Flutter、 uni-app、微信小程序.
如需获取Linux sdk体验包可以填写申请问卷:https://cloud.tencent.com/apply/p/435hepcpuft，填写完成后，系统会在1-2天内免费开通30天的linux环境使用权。

详细参数

创建会话

请求头

请求体示例

查询直播

查询录播

WebSocket 流协议

建立连接

通用消息格式

请求体示例

信号类型

信令示例

prompt_operation（type=11）

payloadobject

images[]object

payloadobject

请求示例

payloadobject

请求示例

payloadobject

音频二进制帧

动作库

错误响应及说明

接入要点

定价信息

FAQ

Q1：阿里的ARTC入口在哪里。

Q2：在linux环境接入腾讯的TRTC，但无法连通