说明:
当前版本:5.4.1。
SDK API 接口/事件的说明
setPrivatization 定制设置
在 init 前设置,设置后在调用 init 方法时可以不传入 sign 参数,如果不设置则必须传入 sign 参数。
注意:
私有化部署环境必须设置。
参数说明
参数名称 | 必选 | 类型 | 说明 |
option | 是 | Option | 自定义类型 |
Option 类型说明
返回值说明
参数名称 | 必选 | 类型 | 说明 |
data | 是 | Boolean | true:代表设置成功 false:代表设置失败 |
示例代码
const result = IVH.setPrivatization({appKey: '密钥里的appkey',accessToken: '密钥里的accesstoken',httpOrigin: 'http://www.test.com',wsOrigin: 'ws://www.test.com',});console.log(result);
init 初始化
参数说明
参数名称 | 必选 | 类型 | 说明 |
option | 是 | Option | 自定义类型 |
Option 类型说明
参数名称 | 必选 | 类型 | 说明 |
element | 是 | Element/String | 容器元素对象,或者为找到容器元素的 selector,例如“#元素 id” |
virtualmanProjectId | 否 | String | 传入后,才可用 createSession 接口建流。 |
assetVirtualmanKey | 否 | String | 数智人资产 Key。在资产管理 > 形象资产里获取。 传入后,才可用 createSessionByAsset 接口建流。 |
sign | 否 | String | 如果不设置,必须 setPrivatization 里设置 appKey 和 accessToken。 没 setPrivatization, 且设置了 sign,为公有云鉴权 |
示例代码
IVH.init({sign: 'xxxxxxx',element: document.querySelector('.video-area'),virtualmanProjectId: 'xxxxxx',});
createSession 新建直播会话
参数说明
参数名称 | 必选 | 类型 | 说明 |
option | 是 | Option | 自定义类型 |
Option 类型说明
参数名称 | 必选 | 类型 | 说明 |
driverType | 否 | Int | 数智人驱动方式。 1:纯文本驱动 3:音频驱动(原声),此模式下支持发送音频和文本两种驱动模式。 |
userId | 否 | String | 用户的唯一标识,由调用方自己维护。以相同的 UserId 创建新流,会导致上一个该 UserId 流关闭。不传会本地生成一个复用 |
customPlayStreamAddrFunc | 否 | Function | 用户自定义修改直播拉流 URL 的函数。 注意: 1. 使用第三方账号下的腾讯云直播服务时请定义此函数。 2. 自定义云直播推流地址时,这里自行设置拉流地址。 |
protocolOption | 否 | ProtocolOption | |
extraInfo | 否 | ExtraInfo | |
streamMaxInterval | 否 | Int | 流式文本非子句模式或音频驱动时数据上送最大间隔时长,范围为2000 - 6000,默认为2000,单位为 ms。 |
customPlayStreamAddrFunc 函数说明
// 会把请求返回的playStreamAddr信息当参数传入function customPlayStreamAddrFunc(addr) {// 自行操作addr信息const newAddr = custom(addr)// 一定要有返回,否则会引发后续逻辑错误return newAddr}
ProtocolOption类型局部举例
参数名称 | 必选 | 类型 | 说明 |
cssCustomPushUrl | 否 | String | 自定义云直播推流地址 |
... | ... | ... | ... |
返回值说明
参数名称 | 必选 | 类型 | 说明 |
data | 是 | Promise<Data/Null> | 自定义类型。为 null 时代表失败,请监听 error 事件看具体信息 |
Data 类型说明
参数名称 | 必选 | 类型 | 说明 |
sessionId | 是 | String | 会话的唯一标识 |
playStreamAddr | 是 | String | 直播流地址 注意: 自定义云直播推流地址时,拉流地址在customPlayStreamAddrFunc 里自行设置,这里后台接口会返回空。 |
示例代码
const result = await IVH.createSession();if (result) {console.log(result);}
createSessionByAsset 新建直播会话
参数说明
参数名称 | 必选 | 类型 | 说明 |
option | 是 | Option | 自定义类型 |
Option 类型说明
参数名称 | 必选 | 类型 | 说明 |
driverType | 否 | Int | 数智人驱动方式。 1:纯文本驱动 3:音频驱动(原声),此模式下支持发送音频和文本两种驱动模式 |
userId | 否 | String | 用户的唯一标识,由调用方自己维护。以相同的 UserId 创建新流,会导致上一个该 UserId 流关闭。不传会本地生成一个复用 |
customPlayStreamAddrFunc | 否 | Function | 用户自定义修改直播拉流URL的函数。 注意: 1. 使用第三方账号下的腾讯云直播服务时请定义此函数。 2. 自定义云直播推流地址时,这里自行设置拉流地址。 |
protocolOption | 否 | ProtocolOption | |
speechParam | 否 | SpeechParam | |
extraInfo | 否 | ExtraInfo | |
backgrounds | 否 | Array<VideoLayer> | |
foregrounds | 否 | Array<VideoLayer> | |
streamMaxInterval | 否 | Int | 流式文本非子句模式或音频驱动时数据上送最大间隔时长,范围为2000 - 6000,默认为2000,单位为 ms。 |
customPlayStreamAddrFunc 函数说明
// 会把请求返回的playStreamAddr信息当参数传入function customPlayStreamAddrFunc(addr) {// 自行操作addr信息const newAddr = custom(addr)// 一定要有返回,否则会引发后续逻辑错误return newAddr}
ProtocolOption 类型局部举例
参数名称 | 必选 | 类型 | 说明 |
cssCustomPushUrl | 否 | String | 自定义云直播推流地址 |
... | ... | ... | ... |
SpeechParam 类型局部举例
参数名称 | 必选 | 类型 | 说明 |
speed | 否 | Float | 语速(1.0为正常语速,范围[0.5-1.5],值为0.5时播报语速最慢,值为1.5时播报语速最快,DriverType 为音频驱动类型时,语速控制不生效) |
timbreKey | 否 | String | 音色 key,默认使用形象自有音色 |
volume | 否 | Int | 音量大小,范围[0,10],对应音量大小。默认为0,代表正常音量,值越大音量越高。 |
... | ... | ... | ... |
返回值说明
参数名称 | 必选 | 类型 | 说明 |
data | 是 | Promise<Data/Null> | 自定义类型。为 null 时代表失败,请监听 error 事件看具体信息 |
Data 类型说明
参数名称 | 必选 | 类型 | 说明 |
sessionId | 是 | String | 会话的唯一标识 |
playStreamAddr | 是 | String | 直播流地址 注意: 自定义云直播推流地址时,拉流地址在customPlayStreamAddrFunc 里自行设置,这里后台接口会返回空。 |
示例代码
const result = await IVH.createSessionByAsset();if (result) {console.log(result);}
startSession 开启当前会话
返回值说明
参数名称 | 必选 | 类型 | 说明 |
data | 是 | Promise<Boolean> | true 正常,false 异常,请监听 error 事件看具体信息 |
示例代码
const result = await IVH.startSession();console.log(result);
statSession 查询会话状态
参数说明
参数名称 | 必选 | 类型 | 说明 |
sessionId | 是 | String | 会话唯一标识 |
返回值说明
参数名称 | 必选 | 类型 | 说明 |
data | 是 | Promise<Data/Null> | 自定义类型。为 null 时代表失败,请监听 error 事件看具体信息 |
Data 类型说明
参数名称 | 必选 | 类型 | 说明 |
reqId | 是 | String | 单次请求唯一标识 |
sessionStatus | 是 | Int | 流状态。1:进行中,2:已关闭,3:准备中,4:建流失败 |
playStreamAddr | 否 | String | 流播放地址,建流成功后返回 |
speakStatus | 否 | String | 数智人状态。Initial:初始状态。 WaitingTextStart:等待文本播报开始。TextStart:文本播报中。 WaitingTextOver:等待文本播报结束。TextOver:文本播报结束。 WaitingAudioStart:等待音频开始播报。AudioStart:音频开始播报。 WaitingAudioOver:等待音频播报结束。AudioOver:音频播报结束。 Error:驱动错误。 |
isSessionStarted | 是 | Boolean | 是否已经开启会话,只有开启状态,才可以发送驱动指令。 |
errorCode | 是 | Int | |
errorMessage | 否 | String | 当前状态对应的错误信息。 |
closeType | 是 | Int | 流退出原因。 1:正常退出 2:超时退出 3:下游退出 4:服务重启关流 5:同 userId 剔除 |
示例代码
const result = await IVH.statSession('xxxxxx');if (result) {console.log(result);}
closeSession 关闭当前直播会话,并销毁对应页面元素
返回值说明
参数名称 | 必选 | 类型 | 说明 |
data | 是 | Promise<Boolean> | true 正常,false 异常,请监听 error 事件看具体信息 |
示例代码
const result = await IVH.closeSession();console.log(result);
closeSessionBySessionId 关闭指定的流
参数说明
参数名称 | 必选 | 类型 | 说明 |
sessionId | 是 | String | 会话唯一标识 |
返回值说明
参数名称 | 必选 | 类型 | 说明 |
data | 是 | Promise<Boolean> | true 正常,false 异常,请监听 error 事件看具体信息 |
示例代码
const result = await IVH.closeSessionBySessionId('xxxxxx');console.log(result);
listSessionOfProjectId 查询数智人项目下的会话列表
参数说明
参数名称 | 必选 | 类型 | 说明 |
virtualmanProjectId | 否 | String | 数智人项目 ID,不传默认会用初始化时的 virtualmanProjectId。 |
返回值说明
参数名称 | 必选 | 类型 | 说明 |
data | 是 | Promise<Data[]>/Null | 自定义类型。为 null 时代表失败,请监听 error 事件看具体信息 |
Data 类型说明(局部)
参数名称 | 必选 | 类型 | 说明 |
userId | 是 | String | 用户的唯一标识 |
sessionId | 是 | String | 会话唯一标识 |
sessionStatus | 是 | Int | 流状态。1:进行中,2:已关闭,3:准备中,4:建流失败 |
playStreamAddr | 否 | String | 流播放地址,建流成功后返回 |
driverType | 是 | String | 数智人类型。1:文本驱动;3:语音驱动(原声)。 |
isSessionStarted | 是 | Boolean | 是否已经开启会话,只有开启状态,才可以发送驱动指令。 |
示例代码
const result = await IVH.listSessionOfProjectId('xxxxxx');console.log(result);
listSessionOfAssetVK 查询个人资产形象下的会话列表
参数说明
参数名称 | 必选 | 类型 | 说明 |
assetVirtualmanKey | 否 | String | 数智人资产 key,不传默认会用初始化时的 assetVirtualmanKey。 |
返回值说明
参数名称 | 必选 | 类型 | 说明 |
data | 是 | Promise<Data[]>/Null | 自定义类型。为 null 时代表失败,请监听 error 事件看具体信息 |
Data 类型说明(局部)
参数名称 | 必选 | 类型 | 说明 |
userId | 是 | String | 用户的唯一标识 |
sessionId | 是 | String | 会话唯一标识 |
sessionStatus | 是 | Int | 流状态。1:进行中,2:已关闭,3:准备中,4:建流失败 |
playStreamAddr | 否 | String | 流播放地址,建流成功后返回 |
driverType | 是 | String | 数智人类型。1:文本驱动;3:语音驱动(原声)。 |
isSessionStarted | 是 | Boolean | 是否已经开启会话,只有开启状态,才可以发送驱动指令。 |
示例代码
const result = await IVH.listSessionOfAssetVK('xxxxxx');console.log(result);
listSessionOfUin 查询 uin 下的会话列表
返回值说明
参数名称 | 必选 | 类型 | 说明 |
data | 是 | Promise<Data/Null> | 自定义类型。为 null 时代表失败,请监听 error 事件看具体信息 |
Data 类型说明(局部)
参数名称 | 必选 | 类型 | 说明 |
userId | 是 | String | 用户的唯一标识 |
sessionId | 是 | String | 会话唯一标识 |
sessionStatus | 是 | Int | 流状态。1:进行中,2:已关闭,3:准备中,4:建流失败 |
playStreamAddr | 否 | String | 流播放地址,建流成功后返回 |
driverType | 是 | String | 数智人类型。1:文本驱动;3:语音驱动(原声)。 |
isSessionStarted | 是 | Boolean | 是否已经开启会话,只有开启状态,才可以发送驱动指令。 |
示例代码
const result = await IVH.listSessionOfUin();console.log(result);
play 发送内容
参数说明
command 取值不同,对应参数组合不同。返回内容监听 socket 事件得到
text:文本驱动。
audio:音频驱动。
stream:流式文本驱动。
command=text
参数名称 | 必选 | 类型 | 说明 |
command | 是 | String | text:文本驱动。 |
data | 是 | String | 内容字符串 |
chatCommand | 否 | String | 对话指令类型 ,当数智人项目绑定对话/大模型 bot 时生效。 NotUseChat:客服 bot 配置不生效,数智人播报发送的内容。 传空或不传:客服 bot 配置生效,数智人播报对应的答案内容。 |
isNewChat | 否 | Boolean | 大模型时生效,控制是否开启新轮次对话 |
chatRoundId | 否 | String | 传值时会导致 isNewChat 无效,人为标识是否为同一个会话(用于多端查询)。 注意: 大模型对话时客户传入,长度不超过64位的字符串。 |
cloudAiVisitorBizId | 否 | String(64) | |
smartActionEnabled | 否 | Boolean | 是否开启智能动作,缺省值:true。为 true 并且输入的文本或者话术增强后的文本没有动作标签则会生成智能动作。 |
command=audio
参数名称 | 必选 | 类型 | 说明 |
command | 是 | String | audio:音频驱动。 |
data | 是 | String | 音频原始数据的 byte 数组,经Base64 编码后的字符串。格式:PCM,采样率:16kHz,采样位深:16bits,声道:单声道,传输速率:5120B 160ms |
seq | 是 | Int | 包序号,序号必须从1开始 |
isFinal | 否 | Boolean | 是否最后一个音频包,头包和过程包不填采用默认值 false,最后一个音频包填写空串,本字段填写 true,会触发结束音频驱动回到静默态 |
command=stream
参数名称 | 必选 | 类型 | 说明 |
command | 是 | String | stream:流式文本驱动。 |
data | 是 | String | 流式内容 |
seq | 是 | Int | 包序号,序号必须从1开始。 说明: 当上一次发送的 isFinal 参数为 true 时,且在 socket 监听事件中收到 TextOver 标记时,表示上一个流式已播报结束,此时再开启下一个流式驱动时,seq 要设置为1。 |
isFinal | 否 | Boolean | 默认值 false,代表是否是当前流式的尾包,当设置为 true 时表示当前流式结束。 |
smartActionEnabled | 否 | Boolean | 是否开启智能动作,缺省值:true。为 true 并且输入的文本或者话术增强后的文本没有动作标签则会生成智能动作。 |
isSentence | 否 | Boolean | command: stream 时有效 是否是子句模式,缺省值:false。为 true 服务端不会做重新组句。 |
isInsertSentence | 否 | Boolean | command: stream 时有效 是否是插入的子句,缺省值:false。为 true 并且是子句模式则表示当前分片需要插播。 |
示例代码
IVH.play({command: 'text',data: '现在几点了',});IVH.play({command: 'audio',data: 'xxxxxx',seq: 1,});IVH.play({command: 'stream',data: 'xxxxxx',seq: 1,});
stop 打断当前播报
示例代码
IVH.stop();
info 版本信息
返回值说明
参数名称 | 必选 | 类型 | 说明 |
data | 是 | Data | 自定义类型 |
Data 类型说明
参数名称 | 必选 | 类型 | 说明 |
version | 是 | String | 版本号 |
示例代码
IVH.info();
setVolume 设置音量
参数说明
参数名称 | 必选 | 类型 | 说明 |
val | 是 | Number | 音量 0 - 1的范围 |
示例代码
let volume = 1;document.querySelector('#btn2').onclick = function (e) {volume = 1 - volume;IVH.setVolume(volume);}
reconnect 重连视频源
5.3.0+版本支持
示例代码
/** 重新播放数智人视频流(前提是该视频流还未失效)*/document.querySelector('#btn').onclick = function (e) {IVH.reconnect();}
事件监听
参数说明
参数名称 | 必选 | 类型 | 说明 |
event | 是 | String | 事件名 |
callback | 否 | Function | 回调函数 |
可监听的事件列表
事件名 | 必选 | 说明 |
error | 否 | 有错误发生时触发 |
canplay | 否 | video 的 canplay 事件,受浏览器兼容性影响,看实际需求监听 |
socket | 否 | |
webrtcevent | 否 | 5.3.0+支持 会透传 tcplayer 播放 webrtc 时的事件集合 |
示例代码
IVH.on('error', e => {console.log('error:', e);});IVH.on('canplay', e => {console.log('canplay:', e);});IVH.on('socket', e => {console.log('socket:', e);});
error 事件
回调数据的结构说明
参数名称 | 必有 | 类型 | 说明 |
code | 是 | Int | 0为正常,非0为异常 当 code = 3001/3002时,仅透传 tcplayer 的 webrtcevent 事件的1006/1009 状态码。5.2.0+版本后可以直接监控 webrtcevent 事件,忽略这2个 error code。 |
message | 是 | String | 对应的错误信息说明 |
path | 否 | String | 发送请求的 path 信息 |
requestId | 否 | String | 请求返回里的 RequestID 信息 |
sessionId | 否 | String | 请求返回里的 SessionID 信息 |
dialogId | 否 | String | 请求返回里的 DialogID 信息 |
data | 否 | Object | 5.3.0+支持 当 code=3003 时,透传 tcplayer 的 error 数据 |
canplay 事件
回调数据的结构说明
参数名称 | 必有 | 类型 | 说明 |
code | 是 | Int | 0为正常,非0为异常 |
message | 是 | String | 对应的错误信息说明 |
socket 事件
参数名称 | 必有 | 类型 | 说明 |
errorCode | 是 | Int | 0为正常,非0为异常 |
errorMsg | 是 | String | 对应的错误信息说明 |
type | 是 | Int | 返回的数据类型。1:输入文本。2:播报内容。3:播报状态。4:大模型的答案。5:风险控制提示。7:由于当前播报句不可打断而被遗弃输入文本 |
speakStatus | 否 | String | 当 type 为3时有此字段。 Initial:初始状态。 WaitingTextStart:等待文本播报开始。 TextStart:文本播报中。 WaitingTextOver:等待文本播报结束。 TextOver:文本播报结束。 WaitingAudioStart:等待音频开始播报。 AudioStart:音频开始播报。 WaitingAudioOver:等待音频播报结束。 AudioOver:音频播报结束。 SentenceNext:流式的子句模式返回该状态,客户端收到该状态表示可以发送下一条子句。 Error:驱动错误。 |
uninterrupt | 否 | Boolean | true:不可打断,false:可打断。 |
interruptResult | 否 | Int | 当 type 为1时有此字段。仅在请求参数 interrupt 为 true 时需要关注此字段。 1 - 成功,2 - 失败。 |
interruptMessage | 否 | String | 当 type 为1时有此字段。仅在请求参数 interrupt 为 true 且打断失败时需要关注此字段。打断失败的原因。 |
text | 否 | String | 当 type 为1、2、7时有此字段。输入文本/播报文本 |
textDisplay | 否 | String | 配置端配置的内容,html 语法 |
textPro | 否 | String | TTS 播报的内容,ssml 语法 |
interactionType | 否 | String | 客服对话的特殊消息类型,参考下面的客服对话说明 |
interactionContent | 否 | String | 客服对话的特殊消息内容,参考同上 |
webrtcevent 事件
状态码 | 回调参数 | 介绍 |
1001 | 无 | 开始拉流。 |
1002 | 无 | 已经连接服务器。 |
1003 | 无 | 视频播放开始。 |
1004 | 无 | 停止拉流,结束视频播放。 |
1005 | 无 | 连接服务器失败,已启动自动重连恢复。 |
1006 | 无 | 获取流数据为空。 |
1007 | localSdp | 开始请求信令服务器。 |
1008 | remoteSdp | 请求信令服务器成功。 |
1009 | 无 | 拉流卡顿等待缓冲中。 |
1010 | 无 | 拉流卡顿结束恢复播放。 |
常见问题
无法自动播放
浏览器要在用户的主动行为事件中触发视频播放,如果没有在主动行为里触发会报如下错误。

正确的播放逻辑参考如下
// 在用户主动行为事件里btnEnterElt.addEventListener("click", () => {// 默认参数为trueIVH.startSession();})
特殊情况:在iOS 16版本及以下的 Safari 浏览器里,视频的播放逻辑不能嵌套调用,需要在用户主动行为里单独调用播放逻辑。
// 传入false,IVH.startSession(false).then(result => {if (result) {// 点击播放的按钮元素btnEnterElt.style.display = "block";})// 在用户主动行为事件里,手动执行video的play事件btnEnterElt.addEventListener("click", () => {IVH.tcplayerPlay();})
网络中断后的自动续播
1、视频流地址还有效, 网络中断后恢复
IVH.on('error', e => {// 监控错误码3003,该错误码是透传tcplayer的errorif (e.code == 3003) {// tcplayer的自动重连失效if (e.data.code == -2004) {// pc端基本直接自动调用即可, 但是某些移动端可能需要手动触发IVH.reconnect();}}});
2、视频流地址已经失效, 网络中断后恢复
警告:
注意这种逻辑会导致该页面的并发持续被占用,仅供有此需求的客户参考
IVH.on('error', async e => {// 代表流已经失效,需要重新建流/开流if (e.code == 110014) {const result = await IVH.createSession();if (result) {IVH.startSession();}}});
附录说明
客服对话
选择题
/** 说明:样式1:style=1;样式2:style=2;样式3:style=3;*/{InteractionContent: "{\\"style\\":1,\\"options\\":[\\"选项1\\",\\"选项2\\",\\"选项3\\"]}",InteractionType: "OptionInfo"}
图片
{InteractionContent: "{\\"url\\":\\"https://virtualhuman-cos-test-1251316161.cos.ap-nanjing.myqcloud.com/virtualman-config/0cbb2231-1afd-4cd5-8414-b1bc3d600a2f-王冰冰.png\\"}",InteractionType: "Image"}
弹窗
{InteractionContent: "{\\"title\\":\\"这是弹窗标题\\",\\"content\\":\\"这是弹窗内容\\",\\"button\\":\\"这是弹窗按钮\\"}",InteractionType: "Popup"}
视频
{InteractionContent: "{\\"url\\":\\"https://virtualhuman-cos-test-1251316161.cos.ap-nanjing.myqcloud.com/virtualman-config/0417e732-1d64-4c65-a2c4-cac23ed454e2-1cd396fb-86a9-480f-814f-cbdf14055cdd.mp4\\"}",InteractionType: "Video"}
图片 + 选择题
/** 说明:样式1:style=1;样式2:style=2;样式3:style=3;*/{InteractionContent: "{\\"url\\":\\"https://virtualhuman-cos-test-1251316161.cos.ap-nanjing.myqcloud.com/virtualman-config/22f4c069-cddb-4753-b482-02a20755b2ba-王冰冰.png\\",\\"style\\":1,\\"options\\":[\\"选项1\\",\\"选项2\\"]}",InteractionType: "ImageOption"}
自定义
{InteractionContent: "{\\"name\\":\\"这是标题\\",\\"contents\\":[\\"这里是内容\\"]}",InteractionType: "Customize"}