说明:
当前版本:5.1.2
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 类型说明
示例代码
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 |
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);}
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);
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 | 大模型时生效,控制是否开启新轮次对话 |
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 | 否 | Boolean | 默认值 false,代表是否是尾包 |
smartActionEnabled | 否 | Boolean | commad: stream 时有效 是否开启智能动作,缺省值:true。为 true 并且输入的文本或者话术增强后的文本没有动作标签则会生成智能动作。 |
isSentence | 否 | Boolean | commad: stream 时有效 是否是子句模式,缺省值:false。为 true 服务端不会做重新组句。 |
isInsertSentence | 否 | Boolean | commad: 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);}
事件监听
参数说明
参数名称 | 必选 | 类型 | 说明 |
event | 是 | String | 事件名 |
callback | 否 | Function | 回调函数 |
可监听的事件列表
事件名 | 必选 | 说明 |
error | 否 | 有错误发生时触发 |
canplay | 否 | video 的 canplay 事件,受浏览器兼容性影响,看实际需求监听 |
socket | 否 |
示例代码
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为异常 |
message | 是 | String | 对应的错误信息说明 |
path | 否 | String | 发送请求的 path 信息 |
requestId | 否 | String | 请求返回里的 RequestID 信息 |
sessionId | 否 | String | 请求返回里的 SessionID 信息 |
dialogId | 否 | String | 请求返回里的 DialogID 信息 |
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 | 客服对话的特殊消息内容,参考同上 |
附录说明
客服对话
选择题
/** 说明:样式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"}