Web SDK 2.0 接入指南
一、集成指南
#1. 兼容性说明
#2. 引入 SDK 库
location ^~/vmss/ {
proxy_pass http://vms.cn-huadong-1.xf-yun.com/;
proxy_set_header Host $proxy_host;
proxy_http_version 1.1;
}
#二、接口使用及调用流程
#1. 启动
#1)接口
vmsConfig
必填,其中appId、apiKey、apiSecret
和avatarId、streamDomId
为必填项。#2)参数
参数 | 类型 | 必填 | 说明 | 默认值 |
---|---|---|---|---|
appID | String | 是 | 应用 ID | |
apiKey | String | 是 | 引擎托管平台创建应用后,生成的唯一应用标识 | |
apiSecret | String | 是 | 引擎托管平台创建应用后,生成的唯一应用秘钥 | |
streamDomId | String | 是 | 虚拟人视频流要渲染的 Dom Id | |
avatarId | String | 是 | 形象 ID | |
width | number | 否 | 宽度,可 取 1920、1280、720 | 1920 |
height | number | 否 | 高度,可取 1080、720、405 | 1080 |
moveH | number | 否 | 水平位移 | |
moveV | number | 否 | 纵向位移 | |
scale | number | 否 | 缩放 | |
maskRegion | string | 否 | 裁切,如:'[0,154,1080,1472]' | |
resId | string | 否 | 背景资源 id,上传图片至个性化系统返回得到 | |
isSsl | boolean | 否 | 是否启用 ssl(https,wss) | 否 |
interactiveScene | string | 否 | 交互场景 | |
templateId | string | 否 | 后处理模板id | |
transparent | boolean | 否 | 是否开启透明通道 | 否 |
#3)调用示例
#2. 结束
#1)接口
#2)调用示例
#3. 音频驱动
#3.1 初始化音频驱动
#1)接口
#2)参数
参数 | 类型 | 必填 | 说明 | 默认值 |
---|---|---|---|---|
frameSize | number | 否 | 每帧数据大小 | 1280 |
sendInterval | number | 否 | 数据发送间隔 | 40 |
#3)调用示例
#3.2 发送音频数据
#1)接口
#2)参数
参数 | 类型 | 取值范围 | 必填 | 说明 | 默认值 |
---|---|---|---|---|---|
vms_dispatch | Object | 否 | 服务别名 | ||
realtime_status | Object | 否 | 实时返回状态数据 | ||
vmr_status | number | 0,1 | 否 | 渲染引擎文本实时响应状态 0 关闭 1 打开 | 0 |
vmr_action_status | number | 0,1 | 否 | 渲染引擎动作实时响应状态 0 关闭 1 打开 | 0 |
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
audio | Object | 是 | 音频数据 |
ctrl_t | Object | 否 | 动作控制段 |
ctrl_postproc | Object | 否 | 后处理控制段 |
参数 | 类型 | 取值范围 | 必填 | 说明 | 默认值 |
---|---|---|---|---|---|
encoding | string | raw,lame, opus-wb, speex-wb | 否 | 音频编码 | raw |
sample_rate | number | 16000 | 否 | 采样率 | 16000 |
audio | Array | 最小尺寸:1B, 最大尺寸:10485760B | 是 | 音频数据 |
参数 | 类型 | 取值范围 | 必填 | 说明 | 默认值 |
---|---|---|---|---|---|
encoding | string | utf8 | 否 | 文本编码 | utf8 |
compress | string | raw | 否 | 文本压缩格式 | raw |
format | string | json | 否 | 压缩格式 | json |
text | string | 最小尺寸:0B, 最大尺寸:1048576B | 是 | 驱动指令,base64 字符串,如:Base64.encode({avatar:[{ type: 'action', value: 'A_LH_introduced_O', wb: 3, we: 5 }]}) |
参数 | 类型 | 取值范围 | 必填 | 说明 | 默认值 |
---|---|---|---|---|---|
encoding | string | utf8 | 否 | 音频编码 | utf8 |
compress | string | raw | 否 | 采样率 | raw |
format | string | json | 否 | 采样率 | json |
text | string | 最小尺寸:0B, 最大尺寸:1048576B | 是 | 后处理控制指令 |
#3)调用示例
#4. 文本驱动
#1)接口
#2)参数
属性 | 类型 | 必填 | 说明 |
---|---|---|---|
tts | Object | 是 | 合成控制段参数 |
参数 | 类型 | 取值范围 | 必填 | 说明 | 默认值 |
---|---|---|---|---|---|
vcn | string | x4_xiaoxuan x4_panting x4_yezi x4_xiaoguo x4_yifei x4_mingge x4_chaoge | 是 | 合成发言人 | |
speed | number | 最小值:0, 最大值:100 | 否 | 语速:50 正常语速,0 对应默认语速的 1/2,100 对应默认语速的 2 倍 | 50 |
volume | number | 最小值:0, 最大值:100 | 否 | 音量:50 正常音量,0 是静音,1 对应默认音量 1/2,100 对应默认音量的 2 倍 | 50 |
pitch | number | 最小值:0, 最大值:100 | 否 | 语调:50 正常语调,0 对应默认语速的 1/2,100 对应默认语速的 2 倍 | 50 |
rhy | number | 可选0,1,3 | 否 | 控制是否返回拼音标注。0: 不返回拼音,1: 返回拼音(支持的引擎: xtts1.0-cpu, xtts1.0-gpu, xtts2.0-gpu, xtts2-gpu中是每句话一次性返回)拼音标注的时间xtts2.0要乘以5ms | 1 |
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
text | Object | 是 | 文本数据描述数据 |
ctrl_w | Object | 否 | 动作控制段 |
ctrl_postproc | Object | 否 | 后处理控制段 |
参数 | 类型 | 取值范围 | 必填 | 说明 | 默认值 |
---|---|---|---|---|---|
encoding | string | utf8 | 否 | 文本编码 | utf8 |
compress | string | raw | 否 | 文本压缩格式 | raw |
format | string | json | 否 | 文本格式 | json |
text | string | 最小尺寸:0B, 最大尺寸:65536B | 是 | 合成的文本数据,文本大小:0-64k |
参数 | 类型 | 取值范围 | 必填 | 说明 | 默认值 |
---|---|---|---|---|---|
encoding | string | utf8 | 否 | 文本编码 | utf8 |
compress | string | raw | 否 | 文本压缩格式 | raw |
format | string | json | 否 | 文本格式 | json |
text | string | 最小尺寸:0B, 最大尺寸:1048576B | 是 | 驱动指令,base64 字符串,如:Base64.encode({avatar:[{ type: 'action', value: 'A_LH_introduced_O', wb: 3, we: 5 }]}) |
参数 | 类型 | 取值范围 | 必填 | 说明 | 默认值 |
---|---|---|---|---|---|
encoding | string | utf8 | 否 | 文本编码 | utf8 |
compress | string | raw | 否 | 文本压缩格式 | raw |
format | string | json | 否 | 文本格式 | json |
text | string | 最小尺寸:0B, 最大尺寸:1048576B | 是 | 后处理控制指令 |
#3)调用示例
#5. 流式文本驱动
#1)接口
#2)参数
#3)调用示例
#1)接口
#2)参数
属性 | 类型 | 必填 | 说明 |
---|---|---|---|
tts | Object | 是 | 合成控制段参数 |
vms_dispatch | Object | 否 | 流式控制参数 |
参数 | 类型 | 取值范围 | 必填 | 说明 | 默认值 |
---|---|---|---|---|---|
vcn | string | x4_xiaoxuan x4_panting x4_yezi x4_xiaoguo x4_yifei x4_mingge x4_chaoge | 是 | 合成发言人 | |
speed | number | 最小值:0, 最大值:100 | 否 | 语速:50 正常语速,0 对应默认语速的 1/2,100 对应默认语速的 2 倍 | 50 |
volume | number | 最小值:0, 最大值:100 | 否 | 音量:50 正常音量,0 是静音,1 对应默认音量 1/2,100 对应默认音量的 2 倍 | 50 |
pitch | number | 最小值:0, 最大值:100 | 否 | 语调:50 正常语调,0 对应默认语速的 1/2,100 对应默认语速的 2 倍 | 50 |
rhy | number | 可 选0,1,3 | 否 | 控制是否返回拼音标注。0: 不返回拼音,1: 返回拼音(支持的引擎: xtts1.0-cpu, xtts1.0-gpu, xtts2.0-gpu, xtts2-gpu中是每句话一次性返回)拼音标注的时间xtts2.0要乘以5ms | 1 |
参数 | 类型 | 取值范围 | 必填 | 说明 | 默认值 |
---|---|---|---|---|---|
realtime_status | Object | 否 | 实时返回状态数据 | ||
tts_status | number | 0,1 | 否 | 文本合成状态 0 关闭 1 打开 | 0 |
vmr_status | number | 0,1 | 否 | 渲染引擎文本实时响应状态 0 关闭 1 打开 | 0 |
vmr_action_status | number | 0,1 | 否 | 渲染引擎动作实时响应状态 0 关闭 1 打开 | 0 |
interactive_mode | number | 0,1 | 否 | 是否打断模式 1 打断 0 追加 | 1 |
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
text | Object | 是 | 文本数据描述数据 |
ctrl_w | Object | 否 | 动作控制段 |
ctrl_postproc | Object | 否 | 后处理控制段 |
参数 | 类型 | 取值范围 | 必填 | 说明 | 默认值 |
---|---|---|---|---|---|
encoding | string | utf8 | 否 | 文本编码 | utf8 |
compress | string | raw | 否 | 文本压缩格式 | raw |
format | string | json | 否 | 文本格式 | json |
text | string | 最小尺寸:0B, 最大尺寸:65536B | 是 | 合成的文本数据,文本大小:0-64k |
参数 | 类型 | 取值范围 | 必填 | 说明 | 默认值 |
---|---|---|---|---|---|
encoding | string | utf8 | 否 | 文本编码 | utf8 |
compress | string | raw | 否 | 文本压缩格式 | raw |
format | string | json | 否 | 文本格式 | json |
text | string | 最小尺寸:0B, 最大尺寸:1048576B | 是 | 驱动指令,base64 字符串,如:Base64.encode({avatar:[{ type: 'action', value: 'A_LH_introduced_O', wb: 3, we: 5 }]}) |
参数 | 类型 | 取值范围 | 必填 | 说明 | 默认值 |
---|---|---|---|---|---|
encoding | string | utf8 | 否 | 文本编码 | utf8 |
compress | string | raw | 否 | 文本压缩格式 | raw |
format | string | json | 否 | 文本格式 | json |
text | string | 最小尺寸:0B, 最大尺寸:1048576B | 是 | 后处理控制指令 |
#3)调用示例
#6. 打断/重置接口
#1)接口
#2)参数
#3)调用示例
Location ^~/individuation/ {
proxy_pass http://evo-hu.xf-yun.com;
proxy_set_header Host $proxy_host;
proxy_http_version 1.1;
}
#7. 上传个性化资源
#1)接口
vmsConfig
为必填项。#2)参数
属性 | 类型 | 必填 | 说明 |
---|---|---|---|
appId | String | 是 | 应用 id |
apiKey | String | 是 | apiKey |
appSecret | String | 是 | appSecret |
resourceBase64Str | String | 是 | 资源 base64 字符串 |
type | String | 否 | 资源描述信息,可选:,默认图片:'background_data' |
#3)调用示例
Location ^~/individuation/ {
proxy_pass http://evo-hu.xf-yun.com;
proxy_set_header Host $proxy_host;
proxy_http_version 1.1;
}
#三、错误码
错误码 | 描述 |
---|---|
29001 | 加入房间失败 |
29002 | 播放视频流失败 |
29003 | 订阅远端流失败 |
29004 | 启动虚拟人服务失败,具体失败原因可查看错误返回信息 |
29005 | 上传资源失败 |
29006 | 停止虚拟人服务失败 |
29007 | 浏览器不支持WebSocket |
29008 | WebSocket连接异常 |
29010 | 文本驱动文本不可为空 |
29011 | 非流式文本驱动异常 |
0x4043 | 此项错误比较特殊:浏览器安全限制,需用户与页面交互才可启动播放 |
#四、移动端兼容性
修改于 2023-12-19 06:18:53