端渲染 H5 SDK 接口说明

最近更新时间:2025-07-21 11:26:42

我的收藏
说明:
当前版本: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
cloudAiGpt:腾讯云大模型对话。
yunxiaowei:云小微客服。
cloudAiWaiting:首包超时等待话术。
cloudAiTimeOut:超时未返回话术,会话结束。
sensitive:敏感内容固定话术。
input:纯文本输入或流式文本输入的内容。
enhanceText:纯文本驱动匹配上了话术管理中的内容。
cloudAiExtra
JSON 文本格式的字符串,大模型的额外补充字段。
replyType=cloudAiGpt,isFinal=true 时有值。
-- record_id
cloudAiExtra 的属性。
消息 ID,可以用来 评价消息
-- references
cloudAiExtra 的属性。
答案来源,相关字段说明
seqNo
子句序号。
isFinal
是否是最后一句。
isHighLight
高亮标识。
contentType
md 格式时的类型。
0:未知
1:普通字符串
2:有序列表
3:无序列表
4:图片链接
5:HTTP 链接
6:表格
7:代码块

客服对话

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"
}