云渲染 H5 SDK 接口说明

最近更新时间:2025-10-20 11:12:02

我的收藏
说明:
当前版本:5.4.1。

SDK API 接口/事件的说明

setPrivatization 定制设置

在 init 前设置,设置后在调用 init 方法时可以不传入 sign 参数,如果不设置则必须传入 sign 参数。
注意:
私有化部署环境必须设置。

参数说明

参数名称
必选
类型
说明
option
Option
自定义类型

Option 类型说明

参数名称
必选
类型
说明
appKey
String
参考 产品介绍 获取密钥,设置后本地鉴权
accessToken
String
参考 产品介绍 获取密钥,设置后本地鉴权
httpOrigin
String
可选配置,优先级高,设置后 HTTP 请求都按这个 origin 设置,不设置时请求公有云地址
wsOrigin
String
可选配置,优先级高,设置后 socket 请求都按这个 origin 设置,不设置时请求公有云地址

返回值说明

参数名称
必选
类型
说明
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
数智人项目 ID。(原来的 virtualmanKey)。参考 产品介绍 获取密钥。
传入后,才可用 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
当前状态对应的错误码,0为正常。错误码列表参考
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)
腾讯 智能体开发平台 的访客 ID。
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
实时返回数智人的播报状态,具体请参见 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", () => {
// 默认参数为true
IVH.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的error
if (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"
}