实时交互数字人-组件版

实时交互数字人-组件版 | Vidu API

当前页面

当前页面

Vidu-S1 数字人

此版本面向自带 RTC 频道、自带实时语音能力 的客户，Vidu 只负责数字人渲染与推流。你把用户语音转写文本、模型回复的文本和模型回复的音频通过 WebSocket 喂给 Vidu，Vidu 把渲染好的数字人推到你自己的 RTC 频道。

与vidu s1 完整版（vidu集成版）的区别：

托管直播里 Vidu 负责 ASR / LLM / TTS 并用 Vidu 下发的 AliRTC token 推流；vidu s1 组件版（客户集成版）里这几件事都由你完成，RTC 频道也是你自己的，Vidu 通过你在创建时传入的 rtc_info 入会并推数字人。两种形态选其一即可。

能力	vidu s1 组件版（客户集成）	vidu s1 完整版（vidu集成）
ASR / LLM / TTS	你自己负责	Vidu 负责
RTC 频道	你自己的频道（artc / trtc / agora），传 rtc_info 给 Vidu 入会	Vidu 下发 AliRTC token
喂给 Vidu 的内容	用户转写文本 + 模型回复文本 + 裸 PCM 音频（模型回复的语音）	无需喂，Vidu 端到端处理
Vidu 职责	仅数字人渲染与推流	全链路 + 数字人渲染

一句话看懂接入全流程

创建外接直播（HTTP，带上你的 rtc_info）→ 拿到 live_id 和 client_secret → 建立 WebSocket 流并发送 conn_init → 收到 conn_init_ack.success=true 后进入直播 → 运行期持续发送 PCM 音频、用户转写文本（type=9）和模型回复文本（type=10），必要时发打断（type=7）→ 结束时发 call_hangup 或直接关闭 WebSocket。数字人画面由 Vidu 推到你自己的 RTC 频道。

Vidu S1 外接直播 · 快速开始使用说明

第 1 步 创建外接直播  → 传入你的 rtc_info，拿到 live_id 和 client_secret
第 2 步 建 WebSocket   → 连 stream 端点，首帧发 conn_init，等 conn_init_ack.success=true
第 3 步 运行期喂数据    → 持续发 PCM 音频 + input_transcription(9) + output_transcription(10)
第 4 步 结束           → 发 call_hangup(5) 或直接关闭 WebSocket

用你的 API Key 调用创建接口，把自己的 RTC 频道信息（rtc_info）一起传进去。Vidu 会用这份信息加入你的频道，准备推数字人画面。响应里的 live.id 后续 WebSocket、查询都要用；client_secret 用于浏览器场景的 WebSocket 建连。

连接

/live/v1/external-lives/{live_id}/stream

，连上后首帧必须发送 conn_init（在此之前发的其他信号都会被忽略）。收到 conn_init_ack.success=true 说明渲染侧就绪；若返回 NOT_READY，稍等片刻重试 conn_init 即可，无需重连 WebSocket。

就绪后，一边通过二进制帧发送裸 PCM 音频，一边通过文本帧发送用户转写文本（type=9）和模型回复文本（type=10）。检测到用户开口时，发送 audio_interrupted（type=7）打断数字人当前回复。数字人画面由 Vidu 实时推到你自己的 RTC 频道，你在客户端订阅并渲染。

下表列出全部对外接口。所有 HTTP 接口都需 Authorization: Token vda_xxx。下文路径均为网关路径（含 /live 前缀）；直连服务时去掉 /live。

方法	路径	用途
POST	/live/v1/external-lives	创建外接直播（核心入口，返回 live 与 client_secret）
GET	/live/v1/lives/{live_id}	查询单个直播状态
WebSocket	`/live/v1/external-lives/{live_id}/stream`	喂数据 + 控制信令（音频 / 转写 / 打断 / 挂断）

项目	约定
{host}	{host} 是域名，不含协议。国内环境为 api.vidu.cn，海外环境为 api.vidu.com。HTTP 用 https://{host}，WebSocket 用 wss://{host}。
网关前缀	下文路径含 /live 前缀（网关路径）；直连服务时去掉 /live。
JSON 字段	请求与响应字段使用 snake_case，例如 image_uri、rtc_info、client_secret。
ID 与时间	live_id、created_at 等 int64 字段建议前端按字符串处理，避免 JavaScript number 精度问题。
媒体传输	数字人画面由 Vidu 推到你自己的 RTC 频道；WebSocket 只承载控制信令、转写文本和你上行的 PCM 音频。

HTTP API 通过 Authorization 请求头携带 API Key：

Authorization: Token vda_xxxxxxxxxxxxxxxxxxxx

也可以直接传裸 vda_xxx（不带前缀），服务端会自动补 Token 前缀。

WebSocket 建连支持两种认证，任选其一：

同 HTTP 的 Authorization header（客户端支持自定义请求头时）；
创建接口下发的 client_secret（作为 query 参数，适合浏览器场景）。

两者皆缺时，WebSocket 建连返回 401。

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

POST /live/v1/external-lives
Authorization: Token vda_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

请求体：

{
  "image_uri": "https://example.com/avatar.jpg",
  "rtc_info": {
    "provider": "artc",
    "app_id": "your-rtc-app-id",
    "channel_id": "your-channel-id",
    "user_id": "uid-123",
    "token": "your-rtc-token"
  },
  "moderation": "disabled",
  "extra_motion": false
}

字段	类型	必填	说明
image_uri	string	是	数字人形象图片 URI，支持 http(s) URL / base64 data URI / s3://
avatar_id	String	是	image_uri和avatar_id二选一具体见图片上传章节
rtc_info	object	是	你的 RTC 频道信息，见下表
moderation	enum	否	strict / disabled，默认 strict
extra_motion	bool	否	默认 false；仅当 moderation=disabled 时，传入 true 才有效

未传 avatar_id ，仅提交 image_uri 时，服务会自动调用“照图片上传”接口，并在返回结果的 live.avatar_id 中回传该资产 avatar_id。

rtc_info** 字段：**

字段	类型	必填	说明
provider	enum	是	artc（阿里）/ trtc（腾讯）/ agora（声网）；其中ARTC请使用：https://live.console.aliyun.com/#/liveRtc/list，具体操作为在视频直播控制台 → 左侧导航栏的直播+ > 实时音视频 > 应用管理 > 创建应用
app_id	string	是	RTC 应用 ID（ provider是artc时，可不填）
channel_id	string	是	RTC 频道 ID
user_id	string	是	推流用户 ID
token	string	是	RTC 鉴权 token

响应体：

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

字段	说明
live.id	直播 ID，后续 WebSocket、查询都要用，务必保存
live.status	此时为 waiting，数字人还没准备好
live.trace_id	排查问题用的链路 ID，反馈问题时建议带上
client_secret	WebSocket 建连的短期签名 token（有效期 24h），浏览器场景经 query 传递

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

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

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

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

参数	类型	必填	说明
live_id	string	是	路径参数，创建时返回
conn_id	string	否	客户端生成的连接 ID；缺省时服务端生成
client_secret	string	否	创建下发的短期签名 token（有效期 24h），浏览器场景经 query 传递；客户端支持自定义请求头时也可用 Authorization: Token <api_key>

连接前校验失败返回 HTTP 错误（不升级为 WebSocket）：

状态码	场景
401	header 与 client_secret 均缺失，或 client_secret 无效 / 过期
403	live 不属于当前用户
400	非外接 live、live 已结束、live_id 非法
409	该 live 已有活跃连接

连接约定：

项	约定
文本帧	TextMessage + JSON（WsSignal），最大 64 KiB
二进制帧	BinaryMessage（裸 PCM 音频），最大 64 KiB
首帧要求	必须为 conn_init
心跳	服务端约 5s 发送 ping，约 15s 无响应则断开

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

字段	类型	说明
type	int	信号类型，见「信号类型」
live_id	string	须与路径一致
conn_id	string	客户端生成的连接 ID（与建连参数一致）
seq_id	int	客户端自增序号；ack 的 seq_id 为请求 seq_id + 1
payload	object	按 type 不同携带对应子结构

客户端 → MaaS：

type	名称	说明	是否必填
1	conn_init	连接初始化（首帧必须发送，成功前其他信号忽略）	是
5	call_hangup	主动挂断；直接关闭 WS 等效	否
7	audio_interrupted	打断数字人当前回复	否（建议接入，最佳时机为每次 VAD 检测到用户开口时）
9	input_transcription	用户语音转写文本；content 为空则忽略	是（不传无法驱动数字人）
10	output_transcription	模型生成的回复文本；content 为空则忽略	是（不传无法驱动数字人）

MaaS → 客户端：

type	名称	说明
2	conn_init_ack	初始化回执
6	force_hangup	服务端强制挂断（发送后约 500ms 断开 WS）

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" }
  }
}

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

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

通过这个接口你可以先把本地图片先上传到 Vidu，作为创建会话时的数字人图片。通过此方法作为数字人图片传入，可以极大节省创建数字人的时间。请注意，图片在90天后会被自动删除。

支持 URL 和 base64形式，仅支持 1 张【单人】图片，支持全身 / 半身、各种风格。格式：PNG / JPG / JPEG / WEBP；图片大小 ≤ 50MB；base64 decode 后字节长度 < 20M，且需包含内容类型前缀，例如

data:image/png;base64,{base64_encode}

方法	HTTP 请求	说明
Create	POST /live/v1/avatars	创建数字人设资产
Get	GET /live/v1/avatars/\{id\}	查询单个数字人设资产
Delete	DELETE /live/v1/avatars/\{id\}	删除数字人设资产
List	GET /live/v1/avatars	分页列表查询

POST /live/v1/avatars，请求体为 JSON。

重复提交同一张图片时，会创建新的资产记录，并直接复用已生成的描述（新记录状态为成功）；首次创建时，服务会异步为图片生成描述，处理进度与结果通过返回资产的 status 字段反映。

请求参数：

字段	类型	说明
image_uri	string	人设形象图片，支持公网 http(s) URL 或 data URI
name	string	可选展示名，不传为空

请求示例

返回字段

字段	类型	说明
id	string	数字人设资产 ID，作为avatar_id传入到“创建外界直播”接口里
image_uri	string	形象图片的访问地址
name	string	展示名
status	string	描述生成状态，取值见下方「status 枚举」
created_at	timestamp	创建时间
updated_at	timestamp	更新时间

status 枚举

值	含义
created（1）	已创建，等待生成描述
processing（6）	生成描述中
success（11）	生成成功
failed（12）	生成失败（终态，需重新创建）

GET /live/v1/avatars/{id}

路径参数 avatar_id（string）：数字人设资产 ID。返回对象字段见「数据结构 - 资产对象」。

DELETE /live/v1/avatars/{id}

删除数字人设资产；已引用该资产的内容不受影响。路径参数 avatar_id（string）：数字人设资产 ID。

删除成功返回空对象（HTTP 200）。

GET /live/v1/avatars，分页参数通过 query string 传递。

Query 参数	类型	说明
pager.page	integer	页码，从 0 开始，默认 0
pager.pagesz	integer	每页数量，默认 10，最大 100

返回：total（integer，总数）、items（数组，元素为资产对象，结构见「数据结构 - 资产对象」）。

WebSocket 建连前校验失败时返回 HTTP 错误、不升级连接，含义见「建立连接」小节的状态码表（401 / 403 / 400 / 409）。

当 conn_init_ack.success=false 时，按 error_code 处理：

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

收到 type=6 即被服务端强制挂断（发送后约 500ms 断开），常见 hangup_reason 有 timeout（会话超时）等。除监听 type=6 外，客户端还必须监听 WebSocket close / error 事件做兜底。

数字人要被驱动，三样缺一不可：PCM 音频（二进制帧）、用户转写文本（type=9）、模型回复文本（type=10）。
首帧必须是 conn_init；NOT_READY 属正常现象，重试 conn_init 即可，不要重连 WS。
保持心跳：约 15s 内无任何消息会被判定为死连接并断开。
建议服务端代理 WebSocket 鉴权，避免 Vidu API Key 泄漏到浏览器端。