一、集成指南

#1. 兼容性说明

目前仅支持 XRTC 协议，兼容性请参照 xrtc web sdk 兼容性 https://voipconference.xfyun.cn/book/#/web/README?id=%e6%94%af%e6%8c%81%e7%9a%84%e5%b9%b3%e5%8f%b0

#2. 引入 SDK 库

①、复制 vms-web-sdk-2.0.0 文件夹到项目的 JS 第三方库（如 src/libs）目录下

②、因虚拟人相关服务不支持跨域，故本地开发和上线部署时，都需要配置代理，本地代理具体如下：

ReactJS版本：

VueJS版本：

部署上线 nginx 配置代理可参照如下：

location ^~/vmss/ {
  proxy_pass http://vms.cn-huadong-1.xf-yun.com/;
  proxy_set_header Host $proxy_host;
  proxy_http_version 1.1;
}

其他方式代理，本意如上所示，形式不限，根据技术方案做具体调整即可_

③、在需要的页面引入 sdk js 文件：

#二、接口使用及调用流程

#1. 启动

启动虚拟人服务

#1）接口

如上代码所示，SDK 初始化参数中vmsConfig必填，其中appId、apiKey、apiSecret和avatarId、streamDomId为必填项。

如需设置背景或者开启后处理，请先上传资源，请参考 “7.上传个性化资源” 完成上传，再将得到的 res_id 传入 start 方法

#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. 音频驱动

输入音频数据，驱动虚拟人，音频驱动需先进行初始化，在间隔合适的时间（默认 40ms）流式传入音频数据

#3.1 初始化音频驱动

#1）接口

#2）参数

参数	类型	必填	说明	默认值
frameSize	number	否	每帧数据大小	1280
sendInterval	number	否	数据发送间隔	40

#3）调用示例

#3.2 发送音频数据

#1）接口

#2）参数

① parameter，非必填

参数	类型	取值范围	必填	说明	默认值
vms_dispatch	Object		否	服务别名
realtime_status	Object		否	实时返回状态数据
vmr_status	number	0,1	否	渲染引擎文本实时响应状态 0 关闭 1 打开	0
vmr_action_status	number	0,1	否	渲染引擎动作实时响应状态 0 关闭 1 打开	0

② payload，必填

参数	类型	必填	说明
audio	Object	是	音频数据
ctrl_t	Object	否	动作控制段
ctrl_postproc	Object	否	后处理控制段

audio

参数	类型	取值范围	必填	说明	默认值
encoding	string	raw,lame, opus-wb, speex-wb	否	音频编码	raw
sample_rate	number	16000	否	采样率	16000
audio	Array	最小尺寸:1B, 最大尺寸:10485760B	是	音频数据

ctrl_t

参数	类型	取值范围	必填	说明	默认值
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 }]})

具体动作指令参数，请参照虚拟人服务接口文档 https://aidocs.xfyun.cn/docs/vms/实时交互服务接口文档.html

ctrl_postproc

参数	类型	取值范围	必填	说明	默认值
encoding	string	utf8	否	音频编码	utf8
compress	string	raw	否	采样率	raw
format	string	json	否	采样率	json
text	string	最小尺寸:0B, 最大尺寸:1048576B	是	后处理控制指令

#3）调用示例

#4. 文本驱动

输入文本数据，驱动虚拟人

#1）接口

#2）参数

① parameter，必传：

属性	类型	必填	说明
tts	Object	是	合成控制段参数

tts

参数	类型	取值范围	必填	说明	默认值
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

② payload，必填

参数	类型	必填	说明
text	Object	是	文本数据描述数据
ctrl_w	Object	否	动作控制段
ctrl_postproc	Object	否	后处理控制段

text

参数	类型	取值范围	必填	说明	默认值
encoding	string	utf8	否	文本编码	utf8
compress	string	raw	否	文本压缩格式	raw
format	string	json	否	文本格式	json
text	string	最小尺寸:0B, 最大尺寸:65536B	是	合成的文本数据，文本大小：0-64k

ctrl_w

参数	类型	取值范围	必填	说明	默认值
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 }]})

具体动作指令参数，请参照虚拟人服务接口文档 https://aidocs.xfyun.cn/docs/vms/实时交互服务接口文档.html

ctrl_postproc

参数	类型	取值范围	必填	说明	默认值
encoding	string	utf8	否	文本编码	utf8
compress	string	raw	否	文本压缩格式	raw
format	string	json	否	文本格式	json
text	string	最小尺寸:0B, 最大尺寸:1048576B	是	后处理控制指令

#3）调用示例

#5. 流式文本驱动

适用于大模型场景下，流式交互，输入文本数据，驱动虚拟人

####5.1 文本驱动初始化

#1）接口

#2）参数

#3）调用示例

####5.2 发送数据

#1）接口

#2）参数

① parameter，必传：

属性	类型	必填	说明
tts	Object	是	合成控制段参数
vms_dispatch	Object	否	流式控制参数

tts

参数	类型	取值范围	必填	说明	默认值
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

vms_dispatch

参数	类型	取值范围	必填	说明	默认值
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

② payload，必填

参数	类型	必填	说明
text	Object	是	文本数据描述数据
ctrl_w	Object	否	动作控制段
ctrl_postproc	Object	否	后处理控制段

text

参数	类型	取值范围	必填	说明	默认值
encoding	string	utf8	否	文本编码	utf8
compress	string	raw	否	文本压缩格式	raw
format	string	json	否	文本格式	json
text	string	最小尺寸:0B, 最大尺寸:65536B	是	合成的文本数据，文本大小：0-64k

ctrl_w

参数	类型	取值范围	必填	说明	默认值
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 }]})

具体动作指令参数，请参照虚拟人服务接口文档 https://aidocs.xfyun.cn/docs/vms/实时交互服务接口文档.html

ctrl_postproc

参数	类型	取值范围	必填	说明	默认值
encoding	string	utf8	否	文本编码	utf8
compress	string	raw	否	文本压缩格式	raw
format	string	json	否	文本格式	json
text	string	最小尺寸:0B, 最大尺寸:1048576B	是	后处理控制指令

#3）调用示例

#6. 打断/重置接口

中断驱动，如果是流式驱动则会断开ws连接

#1）接口

#2）参数

无

#3）调用示例

_注意：如需使用 uploadResourceData 需配置代理 _ 本地开发代理配置如下：

部署上线 nginx 配置可参考如下：

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）参数

① 鉴权参数 vmsConfig，必传：

属性	类型	必填	说明
appId	String	是	应用 id
apiKey	String	是	apiKey
appSecret	String	是	appSecret
resourceBase64Str	String	是	资源 base64 字符串
type	String	否	资源描述信息，可选：，默认图片：'background_data'

② 个性化参数 resId，非必传支持自定义，如果不传，服务返回一个生成的 res_id

#3）调用示例

_注意：如需使用 uploadResourceData 需配置代理 _ 本地开发代理配置如下：

部署上线 nginx 配置可参考如下：

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	此项错误比较特殊：浏览器安全限制，需用户与页面交互才可启动播放

#四、移动端兼容性

此版本目前仅完整支持 pc web，不支持移动端，安卓、IOS请请使用对应的SDK

Web SDK 2.0 接入指南

一、集成指南#

#1. 兼容性说明#

#2. 引入 SDK 库#

#二、接口使用及调用流程#

#1. 启动#

#1）接口#

#2）参数#

#3）调用示例#

#2. 结束#

#1）接口#

#2）调用示例#

#3. 音频驱动#

#3.1 初始化音频驱动#

#1）接口#

#2）参数#

#3）调用示例#

#3.2 发送音频数据#

#1）接口#

#2）参数#

#3）调用示例#

#4. 文本驱动#

#1）接口#

#2）参数#

#3）调用示例#

#5. 流式文本驱动#

#1）接口#

#2）参数#

#3）调用示例#

#1）接口#

#2）参数#

#3）调用示例#

#6. 打断/重置接口#

#1）接口#

#2）参数#

#3）调用示例#

#7. 上传个性化资源#

#1）接口#

#2）参数#

#3）调用示例#

#三、错误码#

#四、移动端兼容性#

一、集成指南

#1. 兼容性说明

#2. 引入 SDK 库

#二、接口使用及调用流程

#1. 启动

#1）接口

#2）参数

#3）调用示例

#2. 结束

#1）接口

#2）调用示例

#3. 音频驱动

#3.1 初始化音频驱动

#1）接口

#2）参数

#3）调用示例

#3.2 发送音频数据

#1）接口

#2）参数

#3）调用示例

#4. 文本驱动

#1）接口

#2）参数

#3）调用示例

#5. 流式文本驱动

#1）接口

#2）参数

#3）调用示例

#1）接口

#2）参数

#3）调用示例

#6. 打断/重置接口

#1）接口

#2）参数

#3）调用示例

#7. 上传个性化资源

#1）接口

#2）参数

#3）调用示例

#三、错误码

#四、移动端兼容性