帮你快速理解、总结文档立即下载

端渲染 H5 SDK 接口说明

最近更新时间:2026-03-27 15:10:24
我的收藏
说明:
当前版本:3.7.4。

兼容性支持

终端设备
系统版本/浏览器版本
PC 桌面端
兼容 Chromium 100+ 的浏览器(如 Chrome/Edge)
iOS 移动端
iOS 15.0+
Android 移动端
兼容 Chromium 100+ 的浏览器

SDK 包的文件说明

一个 SDK 文件:TXIVHSDK_Web_Client_Vx.x.x_Release.js
一个文件夹 unzip(3.4.0+ 版本才有):内包含 unzip_worker.js,unzip_wasm.js,unzip_wasm_bg.wasm。 用来解压 zip 用的,使用方式请参见 初始化解压功能。

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://客户自己的私域域名',
wsOrigin: 'ws://客户自己的私域域名',
});
console.log(result);

init 初始化

说明:
3.4.0+ 版本支持传入 zip 文件路径,具体请参见 初始化解压功能(需要 initUnzip 后才可以传入 zip 文件路径),可减少网络加载文件的时间。

参数说明

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

Option 类型说明

参数名称
必选
类型
说明
element
是
Element/String
容器元素对象,或者为找到容器元素的 selector,例如“#元素 ID”。
virtualmanProjectId
是
String
请参见 获取密钥
sign
否
String
请参见 获取密钥。
如果不设置,必须 setPrivatization 里设置 appKey 和 accessToken。
没 setPrivatization,且设置了 sign,为公有云鉴权。
modelPath
否
String
模型地址,相对地址/绝对地址均可。
说明:
可支持 zip 链接,请参见 初始化解压功能。
actionPath
否
Array
动作地址,相对地址/绝对地址都可
说明:
可支持 zip 链接,请参见 初始化解压功能。
当传入动作文件的 zip 时,数组里第一个值为 URL 链接即可,其他值会忽略

使用zip模式时
指定静默动作:把 zip 包里的 “对应动作.json” 改名为“default_action_idle.json”。
如果不想要静默动作,保证压缩包里没有名为“default_action_idle.json”动作。
指定开场动作:把 zip 包里的 “对应动作.json” 改名为“opening_action_once.json”。
如果不想要开场动作,保证压缩包里没有名为“opening_action_once.json”动作。
注意:
使用非 zip 模式时。
不要把静默动作和开场动作改名。
defaultActionIdx
否
Int
非 zip 格式时,指定动作 JSON 数组里的下标,会当成静默动作,默认值为0。
不想有静默动作时,defaultActionIdx 设置为-1。
注意:
zip 模式时,该参数不生效。
非 zip 模式时,设置静默时不要改名,以免出现多个静默冲突的情况。
openingActionIdx
否
Int
非 zip 格式时,指定动作 JSON 数组里的下标,不能和静默动作一样且值有效,会在 init 后执行一遍该动作。
注意:
zip 模式时,该参数不生效。
非 zip 模式时,设置开场时不要改名,以免出现多个开场冲突的情况。
modelOption
否
ModelOption
模型渲染参数
configPath
否
String
配置文件地址,相对地址/绝对地址都可。
注意:
如果下载的模型资产压缩包内有配置文件,请 init 时加载进去。
isIntl
否
Boolean
是否是国际版,默认值为 false(国内版)
警告:
国内 | 国际版账号和接口不通用,如果不匹配会导致接口异常。

ModelOption 类型说明

参数名称
必选
类型
说明
mode
否
Array<String>
模式集合
说明:
'position':定位模式,配置后可自由调整位置。 示例: ['position']

示例代码

// 初始化
IVH.init({
element: '#model',
virtualmanProjectId: 'xxxxxxxxxxxxxxxxxx',
sign: 'xxxxxxxxxxxxxxxxxx',
modelPath: `./model/yangxiaoyun/200.glb`,
actionPath: [
`./model/yangxiaoyun/action/hands_drooping.json`,
],
defaultActionIdx: 0
});

加载动作

注意:
要保证在 init 后执行。

参数说明

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

Option 类型说明

参数名称
必选
类型
说明
actionPath
否
Array
动作地址, 相对地址/绝对地址均可。

示例代码

IVH.on('init', e => {
console.log('init:', e);
IVH.loadAction({
actionPath: [
`./model/yangxiaoyun/action/welcome.json`,
],
});
});

初始化 AudioContext

示例代码

说明:
由于 iOS 的音频自动播放限制,必须在行为事件的回调里 init。
正确示例,在用户行为事件回调函数的层级里调用 initAudio。
document.querySelector('#btn').onclick = function (e) {
IVH.initAudio();
const txt = document.querySelector('#txt').value.trim();
if (txt) {
setTimeout(() => {
IVH.play(txt);
}, 1000);
}
}
错误示例,在其他函数层级里initAudio,这时 iOS 系统会认为是非用户行为。
document.querySelector('#btn').onclick = function (e) {
const txt = document.querySelector('#txt').value.trim();
if (txt) {
setTimeout(() => {
IVH.initAudio();
IVH.play(txt);
}, 1000);
}
}

播报 play

注意:
每次调用前先执行 initAudio。

参数说明

参数名称
必选
类型
说明
text
是
Object
要播放的文本,支持 SSML 规范。(纯动作标签只支持单动作)
option
是
Option
自定义类型。

Option 类型说明

参数名称
必选
类型
说明
isChat
否
Boolean
是否开启对话模式, 默认值是 false,纯文本驱动。
为 true 时,启动对应的对话模式,客服对话/大模型。
isNew
否
Boolean
isChat 为 true 时有效。
是否属于同一个会话(多轮),会影响多轮会话的结果。
isStream
否
Boolean
isChat 为 false 时有效。
为 true 时,为流式文本驱动。默认值为 false。
警告:
流式文本不支持 SSML 格式。
seqNo
否
Int
isStream 生效时必传。
流式文本分片序号,从1开始计数。
isFinal
否
Boolean
isStream 生效时必传。
流式文本的结束标记(每一段流式文本结束必须传入结束标记)。
streamId
否
String
isStream 生效时必传。
流式文本的请求 ID,长度为32的 UUID,用来标识是同一个流。
chatRoundId
否
String
isChat 为 true 时有效,传值时会导致 isNew 无效,人为标识是否为同一个会话(用于多端查询)。
注意:
大模型对话时客户传入,长度不超过64位的字符串。
smartActionEnabled
否
Boolean
是否开启智能动作,默认值是 true。

示例代码

document.querySelector('#btn').onclick = function (e) {
const txt = document.querySelector('#txt').value.trim();
if (txt) {
IVH.initAudio();
IVH.play(txt, {
isChat: true,
});
}
}

// 模拟流式接口测试用例, 仅供参考
document.querySelector('#btn7').addEventListener('click', e => {
const arr = [
'今天天气不错,',
'风和日丽的,',
'可以出去玩了。'
];
IVH.initAudio();
const streamId = crypto.randomUUID().replace(/-/g, '')
for (let i = 0; i < arr.length; i++) {
IVH.play(arr[i], {
isStream: true,
seqNo: i + 1,
isFinal: i === arr.length - 1,
streamId,
})
}
})

版本信息

返回值

参数名称
必选
类型
说明
result
是
Object
一个 JSON 对象,里面还有版本信息对象。
{
version: '1.0.0'
}

示例代码

/**
* @returns Object
* * @property {String} version:版本信息,例如:'1.0.0'
*/
IVH.info()

设置音量

参数说明

参数名称
必选
类型
说明
val
是
Number
音量 0 - 1的范围。

示例代码

let volume = 1;
document.querySelector('#btn2').onclick = function (e) {
volume = 1 - volume;
IVH.setVolume(volume);
}

打断播报

示例代码

document.querySelector('#btn3').onclick = function (e) {
IVH.stop();
}

获取指令配置

版本 3.1.0+ 支持

参数说明

参数名称
必选
类型
说明
key
是
String
指令 key,根据它获取已经配置好的指令信息。

返回值

参数名称
必选
类型
说明
result
是
Promise<Object>
异步返回的 JSON 对象,关键字段请参见 附录说明。

示例代码

const result = await IVH.getActionConfig('xxx');
console.log(result);

获取配置信息

版本 3.2.0+ 支持。

返回值

参数名称
必选
类型
说明
result
是
Object
返回一个 JSON 数据,一般在调整模型位置后,存成 conf.json,下次 init 时加载,可调整模型的初始位置。

示例代码

const result = IVH.getConfig();
console.log(result);

重置位置信息

版本 3.2.0+ 支持,如果 init 时有自定义位置,调用此方法可 reset。

示例代码

IVH.resetPositionInfo();

清除实例,释放内存占用

版本 3.3.0+ 支持,用来清除实例释放内存占用。
注意:
destroy 后想要再次渲染需要重新 init 对应方法。

示例代码

IVH.destroy();

初始化解压功能

版本 3.4.0+ 支持,初始化后模型和动作文件可以传入 zip 文件,减少网络请求时间。
注意:
只支持 zip 文件,Deflate 压缩算法。
桌面端 Chrome 同等内核版本100+,移动端 iOS 15.0+,Chrome for Android 100+ 支持。

参数说明

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

Option 类型说明

参数名称
必选
类型
说明
path
是
String
解压相关文件所在的文件路径。
解压相关文件有三个,分别是 unzip_worker.js,unzip_wasm.js,unzip_wasm_bg.wasm。把它们放在同一个文件夹里,然后把路径传给 path。例如:http://xxx.com/unzip/或者是相对路径 ./unzip/ 之类的。
hosts
否
Array<String>
3.7.4+ 版本支持
不设置,默认只能拉取所在 host 下的 zip 数据。
想拉取其他 host 下的数据,请设置在白名单数组里。

返回值

参数名称
必选
类型
说明
result
是
Promise<Boolean>
异步返回的 Boolean,true 成功 / false 失败,失败时 error 事件里会有相关错误信息。

示例代码

// 需要保证initUnzip返回true,才可传入zip链接。
(async () => {
const result = await IVH.initUnzip({
path: './unzip'
});
result && IVH.init({
element: '#xxxx',
sign: 'xxxxx',
virtualmanProjectId: 'xxxxx',
modelPath: './model/model.zip',
// 动作文件的zip,只看数组里一个url链接,后续值会忽略。使用zip时指定静默动作,是把zip包里的”对应动作.json“改名为”default_action_idle.json“,系统会把这个命名的动作当作静默。
actionPath: [
'./model/action.zip',
],
});
})();

加载组件数据

版本 3.5.0+ 支持,模型 init 和 initUnzip 后,可以加载组件数据(例如:带道具模型的配套动作)。

参数说明

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

Option 类型说明

参数名称
必选
类型
说明
zipPath
是
String
组件压缩文件所在的文件路径。
由于道具配套动作相关文件较多,缺失可能会引发后续异常,所以加载时会做文件校验。
如异常会在 error 事件里返回相关异常信息;如成功会在 actionLoad 事件中返回相关加载信息。

示例代码

// 需要保证init和initUnzip都已初始化完毕
(async () => {
const result = await IVH.initUnzip({
path: './unzip'
});
IVH.on('init', e => {
IVH.loadComponent({
zipPath: './model/aiyun/aiyun.zip',
})
});
result && IVH.init({
element: '#xxxx',
sign: 'xxxxx',
virtualmanProjectId: 'xxxxx',
modelPath: './model/model.zip',
// 当传入动作文件的zip时,数组里第一个值为url链接即可,其他值会忽略
actionPath: [
'./model/action.zip',
],
});
})();

事件监听

参数说明

参数名称
必选
类型
说明
event
是
String
事件名
callback
否
Function
回调函数

可监听的事件列表(参数event的可选取值)

事件名
必选
说明
error
否
有错误发生时触发,回调函数会返回信息对象,可查看 message 属性获知具体错误信息。
init
否
模型初始化完毕后触发,回调函数会返回信息对象。
actionLoad
否
动作数据加载后触发,回调函数会返回信息对象。
actionEnd
否
动作执行完毕后触发,回调函数会返回信息对象。
play
否
TTS语音播完后触发,回调函数会返回信息对象。
nlp
否
对话的返回结果,用于富文本的展示。
具体说明参考 附录说明。
sentence
否
大模型模式下的分句播报信息,回调函数会返回信息对象。
seqNo 对应 nlp 事件里返回的 seqNo。
status 播放状态: start 开始/over 结束。

示例代码

IVH.on('error', e => {
console.log('error:', e.code, e.message);
});
IVH.on('init', e => {
console.log('init:', e.code, e.message);
});

指引

两个模型切换,来达成换装效果

示例代码

// 先初始化A服饰模型
IVH.init({
element: '#model',
virtualmanProjectId: 'xxxxxxxxxxxxxxxxxx',
sign: 'xxxxxxxxxxxxxxxxxx',
modelPath: `./model/modelA.glb`,
actionPath: [
`./model/actionA/xxxx.json`,
]
});

// 当要切换时,销毁之前的A服饰模型
IVH.destroy();
// 重新初始化B服饰模型
IVH.init({
element: '#model',
virtualmanProjectId: 'xxxxxxxxxxxxxxxxxx',
sign: 'xxxxxxxxxxxxxxxxxx',
modelPath: `./model/modelB.glb`,
actionPath: [
`./model/actionB/xxxx.json`,
]
});

如何调整模型的起始位置和大小

示例代码

// 1、先初始化, 打开定位模式
IVH.init({
element: '#model',
virtualmanProjectId: 'xxxxxxxxxxxxxxxxxx',
sign: 'xxxxxxxxxxxxxxxxxx',
modelPath: `./model/model.glb`,
actionPath: [
`./model/action/xxxx.json`,
],
modelOption: {
mode: ['position']
}
});

// 2、可以鼠标滚轮放缩模型大小, 鼠标右键拖拽模型位置, 确认好后调用getConf保存为conf.json
getConf.addEventListener('click', e => {
const blob = new Blob([JSON.stringify(IVH.getConf())], { type: 'application/json' });
// 下载的文件名
const filename = 'conf.json';
// 创建隐藏的可下载链接
const eleLink = document.createElement('a');
eleLink.download = filename;
eleLink.style.display = 'none';
// 下载内容转变成blob地址
eleLink.href = URL.createObjectURL(blob);
// 触发点击
document.body.appendChild(eleLink);
eleLink.click();
// 然后移除
document.body.removeChild(eleLink);
URL.revokeObjectURL(eleLink.href);
});

// 3、重新init模型, 加载configPath/configData, 模型会按照之前保存的信息渲染
IVH.init({
element: '#model',
virtualmanProjectId: 'xxxxxxxxxxxxxxxxxx',
sign: 'xxxxxxxxxxxxxxxxxx',
modelPath: `./model/model.glb`,
actionPath: [
`./model/action/xxxx.json`,
],
configPath: './model/conf.json',
});

附录说明

大模型

nlp 事件返回数据的关键字段说明。
属性名
说明
replyType
回复语类型。
1. cloudAiGpt:腾讯云大模型对话
2. yunxiaowei:云小微客服对话
3. cloudAiWaiting:首包超时等待话术
4. cloudAiTimeOut:超时未响应话术,会话结束
5. sensitive:输入文本或回复语中包含敏感内容时,返回的固定话术
6. input:InputText 为纯文本或流式文本时输入的内容
7. enhanceText:未配置对话服务时,匹配到话术管理的内容
8. cloudAiThought:腾讯云大模型思考过程内容
cloudAiExtra
JSON 文本格式的字符串,大模型的额外补充字段。
replyType=cloudAiGpt,isFinal=true 时有值。
-- record_id
cloudAiExtra 的属性。
消息 ID,可以用来 评价消息。
-- references
cloudAiExtra 的属性。
答案来源,相关字段说明。
seqNo
子句序号,当 replyType 为 cloudAiGpt时,正常回复语序号从1开始,其余固定话术从0开始。
isFinal
是否是最后一句。
isHighLight
高亮标识。
contentType
回复语内容类型
0:未知
1:普通字符串
2:有序列表
3:无序列表
4:图片链接
5:http链接
6:表格
8:标题
9:SSML

客服对话

nlp 事件返回数据的关键字段说明(2.3.1及以后版本统一为小写开头)
属性名
说明
replyDisplay
配置端配置的内容,HTML 语法。
replyPro
TTS 播报的内容,SSML 语法。
interactionType
特殊消息类型,参考下面的特殊消息说明。
interactionContent
特殊消息内容,参考同上。

特殊消息说明

通过腾讯云智能数智人话术管理模块,可针对不同的回复语配置特殊消息类型,可辅助集成方快速配置特殊消息内容,以下为实现前端特殊消息类型代码示例,SDK 本身不包含前端交互样式。
注意:
SDK 本身不包含前端交互样式,如需使用特殊消息类型,需集成方进行代码开发。

选择题

/*
* 说明:样式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"
}