文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>腾讯云智能数智人>数智人 SDK 接入模式>端渲染 SDK 接入（3D形象)>端渲染 Windows SDK 接入>浮层网页 JS SDK 协议文档

浮层网页 JS SDK 协议文档

最近更新时间：2025-06-03 10:40:22

我的收藏

本页目录：

1. JSSDK 介绍

Windows 端渲染 SDK 提供了在数智人窗口上叠加透明网页的能力，浮层透明网页用来展示与数智人交互的内容。

2. JS API

内嵌网页中，提供了 JS API 可以控制数智人。

2.1 全局对象 TVH

内嵌网页的主 Frame 会提供一个全局对象 TVH，所有操作数智人的方法都在这个全局对象上。
对象内置了一系列变量存储了和数智人相关的信息，可以直接读取和设置：
变量名称
类型
读写
描述
version
String
只读
数智人 Windows 端渲染 SDK 的版本
connectedNodeList
Array
只读
连接到端渲染 SDK 的其他应用程序列表（如 ASR, 多模识别， 配置工具等）
enableLog
bool
读写
是否在控制台输出日志，默认 false
enableLogHeartbeat
bool
读写
输出日志打开时，是否输出心跳日志，默认 false

2.2 已连接应用列表

Windows 端渲染 sdk 会和其他的应用配合使用，启动其他应用后并连接后，会出现在已连接应用列表中。
其他应用启动和连接的状态， 会通过 TVH.connectedNodeList 列表来表示。
例如：
[
    {
        "nodeId": "debug_tools",
        "nodeRole": "debug_tools",
        "ip": "127.0.0.1",
        "port": 54921,
        "dataType": "NODE_DATA_TYPE_PROTOBUF",
        "extendedInfoJson": "{}"
    }
]
变量名称
类型
描述
nodeId
String
连接节点 ID
nodeRole
String
连接节点角色
ip
String
连接节点 IP 地址
port
Number
连接节点的 UDP 端口
dataType
String
通讯协议的数据类型，可选值有:
NODE_DATA_TYPE_PROTOBUF : PB二进制数据
NODE_DATA_TYPE_JSON : Json 数据
extendedInfoJson
String
连接节点的额外信息，是 Json字符串

2.3 监听事件

通过 on 方法监听事件。
TVH.on("事件名称", 回调函数);
事件有：
事件名称
描述
package
收到 数智人的命名数据包
connectedNodeListChanged
当连接到端渲染 SDK 的其他应用列表信息发生变化时，会触发此事件
示例：

var callback = function(package){
    console.log(package);
};

TVH.on("package", callback);
其中 package 的内容和指令，下一章：3. 数智人指令。

2.4 移除监听事件

通过 removeListener 移除监听事件
TVH.removeListener("事件名称", 回调函数);
示例：
TVH.removeListener("package", callback);
也可以通过 removeAllListeners 移除所有监听事件, 不填事件名称，则为移除所有事件的监听。
TVH.removeAllListeners(["事件名称"]);
示例：
TVH.removeAllListeners("package");

TVH.removeAllListeners();

2.5 发送指令

通过 sendPackage 发送指令控制数智人端渲染 SDK
TVH.sendPackage(指令包);
其中 指令包的内容和指令，参见下一章：3. 数智人指令。

3. 数智人指令

3.1 播报命令（1010 - speakCommand）

播报命令用来控制数智人播报对应的文本，可以配合动作。
TVH.sendPackage({
    "speakCommand":{
        "actorName":"xiaowei",
        "text":"你好呀,<insert-action type=\\"left_side1\\"/> 我正在做动作",
        "isSmartAction":true
    }
});
参数说明：
参数名称
必选
类型
描述
actorName
是
String
演员名称， 现在数智人只有一个演员，统一填写 "xiaowei"
text
是
String
要播报的文本，可以带动作标签
isSmartAction
是
Bool
是否开启智能动作
播报命令发送后， 数智人会回复播报的状态指令。回复的播报状态，请通过 TVH.on("package", callback) 进行监听。




如需要插入动作，请获取动作名称列表， 并在播报文本中插入动作标签。 动作标签格式为：
<insert-action type="2hands_forward2" />你好啊</insert-action>

回复指令： 完成回复（1021 - replyFinishCommand）

用户可以在数智人平台配置进行播报内容的替换。
收到此命令表示数智人平台干预了播报内容。不是每次播报都会收到此命令，如果是原样播报则没有此命令。
如果回复内容过长，会被拆分，可能会收到多条命令。
{
    "replyFinishCommand": {
        "actorName": "xiaowei",
        "nlpResult": "{\\"Header\\":{\\"RequestID\\":\\"191cd2024a9446968a1360443bcf6434\\",\\"SessionID\\":\\"bjed97692a17150632309977895\\",\\"Code\\":0,\\"Message\\":\\"\\"},\\"Payload\\":{\\"ReplyType\\":\\"enhanceText\\",\\"ReplyPro\\":\\"你好呀，请问有什么问题要问我吗？\\",\\"ReplyDisplay\\":\\"你好呀，请问有什么问题要问我吗？\\",\\"InteractionType\\":\\"\\",\\"InteractionContent\\":\\"\\",\\"Uninterrupt\\":true,\\"Muted\\":false,\\"SeqNo\\":1,\\"ContentType\\":0,\\"TtsSupport\\":true,\\"IsFinal\\":true,\\"IsHighLight\\":true}}"
    }
}
参数名称
必选
类型
描述
actorName
是
String
演员名称， 现在数智人只有一个演员，一定是 "xiaowei"
nlpResult
是
String
对话平台返回的结果，详情见 3.4 节 关于 nlpResult 的介绍

回复指令： 播报开始（1012 - speakStartCommand）

表示开始说话。
{
    "speakStartCommand":{
        "actorName":"xiaowei"
    }
}
参数名称
必选
类型
描述
actorName
是
String
演员名称， 现在数智人只有一个演员，一定是 "xiaowei"

回复指令：播报内容（1015 - speakContentCommand）

表示正在说话的内容，并带了说话的时间戳， 可以方便显示字幕。 如果文本很长，会收到多条播报内容指令。
{
    "speakContentCommand":{
        "actorName":"xiaowei",
        "ttsResult":"[{\\"Word\\":\\"你好\\",\\"T1\\":\\"300000\\",\\"T2\\":\\"4100000\\"},{\\"Word\\":\\"呀\\",\\"T1\\":\\"4100000\\",\\"T2\\":\\"7000000\\"}]"
    }
}
参数名称
必选
类型
描述
actorName
是
String
演员名称， 现在数智人只有一个演员，一定是 "xiaowei"
ttsResult
是
String
TTS 的结果， Json 字符串， 其中 T1 为开始时间， T2 为结束时间，时间数值/10000 为单位 ms，相当于单位为 0.1 us

回复指令： 播报结束（1013 - speakFinishCommand）

表示播报结束。
{
    "speakFinishCommand":{
        "actorName":"xiaowei"
    }
}
参数名称
必选
类型
描述
actorName
是
String
演员名称， 现在数智人只有一个演员，一定是 "xiaowei"

回复指令： 播报错误（1014 - speakErrorCommand）

表示播报错误。
{
    "speakErrorCommand": {
        "actorName": "xiaowei", 
        "errorMessage": "AssetImageExpired: 该数智人形象已经过期，请您申请延期或者加购", 
        "errorCode": 100015
    }
}
参数名称
必选
类型
描述
actorName
是
String
演员名称， 现在数智人只有一个演员，一定是 "xiaowei"
errorCode
是
Number
错误码
errorMessage
是
String
错误消息

3.2 流式播报命令（1011 - streamSpeakCommand）

流式播报命令用来控制数智人流式播报对应的文本。
TVH.sendPackage({
    "sessionId":"ADCD00D146E07C72D64261AA40F345A2",
    "traceId":"7C424255435E9675E5E6DE94C3BAC0A1",
    "streamSpeakCommand":{
        "actorName":"xiaowei",
        "text":"大家好，",
        "sequenceNumber":1,
        "isFinal":false,
        "isSmartAction":true
    }
});
TVH.sendPackage({
    "sessionId":"ADCD00D146E07C72D64261AA40F345A2",
    "traceId":"7C424255435E9675E5E6DE94C3BAC0A1",
    "streamSpeakCommand":{
        "actorName":"xiaowei",
        "text":"我是虚拟分身主播，",
        "sequenceNumber":2,
        "isFinal":false,
        "isSmartAction":true
    }
});
TVH.sendPackage({
    "sessionId":"ADCD00D146E07C72D64261AA40F345A2",
    "traceId":"7C424255435E9675E5E6DE94C3BAC0A1",
    "streamSpeakCommand":{
        "actorName":"xiaowei",
        "text":"很高兴认识大家。",
        "sequenceNumber":3,
        "isFinal":true,
        "isSmartAction":true
    }
});
参数说明：
参数名称
必选
类型
描述
actorName
是
String
演员名称， 现在数智人只有一个演员，统一填写 "xiaowei"
text
是
String
要播报的文本，可以带动作标签
sequenceNumber
是
Int
流式请求分片的序号
isFinal
是
Bool
是否最后一个流式分片
isSmartAction
是
Bool
是否开启智能动作
isSentence
否
Bool
是否开启流式子句，只有开启流式子句才会收到 speakSentenceStartCommand 等指令。
流式播报命令发送后， 数智人会回复播报的状态指令。回复的播报状态，请-通过 TVH.on("package", callback) 进行监听。
数智人平台会对流式文本请求进行重新组句等操作，并将结果通过replyFinishCommand返回，和3.1节中非流式文本请求一致。
重新组句后的子句个数和发送的文本请求数不一定相等，每个子句都会对应一个replyFinishCommand。数智人还会回复子句级别的状态，如 speakSentenceStartCommand和 speakSentenceOverCommand。




注意事项：
1. 流式播报命令 streamSpeakCommand 的多个子句的 traceId 需要保持一致，sessionId 也需要保持一致, 建议使用32位的UUID。当一个流式播报结束后（isFinal 为 true），需要更换 traceId。
2. 重组后的每个子句都有speakSentenceStartCommand 和 speakSentenceOverCommand。
3. 流式播报命令中不能在播报文本中插入动作标签，只能使用 isSmartAction: true 开启智能动作。

回复指令： 播报子句开始（1016 - speakSentenceStartCommand）

表示播报子句开始。
{
    "speakSentenceStartCommand":{
        "actorName":"xiaowei",
        "sequenceNumber":1
    }
}
参数名称
必选
类型
描述
actorName
是
String
演员名称， 现在数智人只有一个演员，一定是 "xiaowei"
sequenceNumber
是
Int
流式请求分片的序号

回复指令： 播报子句结束（1017 - speakSentenceOverCommand）

表示播报子句结束。
{
    "speakSentenceOverCommand":{
        "actorName":"xiaowei",
        "sequenceNumber":1
    }
}
参数名称
必选
类型
描述
actorName
是
String
演员名称， 现在数智人只有一个演员，一定是 "xiaowei"
sequenceNumber
是
Int
流式请求分片的序号

3.3 停止播报指令 （1030 - stopSpeakCommand）

停止播报指令用来在播报过程中停止播报。
TVH.sendPackage({
    "stopSpeakCommand":{
        "actorName":"xiaowei"
    }
});
参数名称
必选
类型
描述
actorName
是
String
演员名称， 现在数智人只有一个演员，一定是 "xiaowei"
发送停止播报指令后，会收到停止完成的指令。
同时之前播报指令也会返回播报完成的指令。




3.4 请求对话指令（1020 - answerCommand）

请求对话指令，用来让数智人回答问题， 问题可以在数智人平台配置。
TVH.sendPackage({
    "answerCommand":{
        "actorName":"xiaowei",
        "text":"请介绍下你自己",
        "newRound":true,
        "isSmartAction":true
    }
});
参数说明：
参数名称
必选
类型
描述
actorName
是
String
演员名称， 现在数智人只有一个演员，统一填写 "xiaowei"
text
是
String
要问的问题文本，为纯文本
newRound
是
Bool
是否新一轮对话， 每一轮对话有自己的上下文。 如果需要新开一轮对话， 请传 true. 第一次发送对话请求时， 一定要传 true.
isSmartAction
是
Bool
是否开启智能动作
发送请求对话指令后， 会收到对话结果指令和播报相关的指令。




回复指令： 问答完成指令（1021 - replyFinishCommand）

{
    "replyFinishCommand": {
        "actorName": "xiaowei",
        "nlpResult": "{\\"Header\\":{\\"RequestID\\":\\"191cd2024a9446968a1360443bcf6434\\",\\"SessionID\\":\\"bjed97692a17150632309977895\\",\\"Code\\":0,\\"Message\\":\\"\\"},\\"Payload\\":{\\"ReplyType\\":\\"yunxiaowei\\",\\"ReplyPro\\":\\"你好呀，请问有什么问题要问我吗？\\",\\"ReplyDisplay\\":\\"你好呀，请问有什么问题要问我吗？\\",\\"InteractionType\\":\\"\\",\\"InteractionContent\\":\\"\\",\\"Uninterrupt\\":true,\\"Muted\\":false,\\"SeqNo\\":1,\\"ContentType\\":0,\\"TtsSupport\\":true,\\"IsFinal\\":true,\\"IsHighLight\\":true}}"
    }
}
参数名称
必选
类型
描述
actorName
是
String
演员名称， 现在数智人只有一个演员，统一填写 "xiaowei"
nlpResult
是
String
问答回复的结果
回复的问答结果是在对话平台配置的， 可以配置额外的指令。
其中 nlpResult 数据格式：
{
    "Header": {
        "RequestID": "191cd2024a9446968a1360443bcf6434",
        "SessionID": "bjed97692a17150632309977895",
        "Code": 0,
        "Message": ""
    },
    "Payload": {
        "ReplyType": "yunxiaowei",
        "ReplyPro": "你好呀，请问有什么问题要问我吗？",
        "ReplyDisplay": "你好呀，请问有什么问题要问我吗？",
        "InteractionType": "",
        "InteractionContent": "",
        "Uninterrupt": true,
        "Muted": false,
        "SeqNo": 1,
        "ContentType": 0,
        "TtsSupport": true,
        "IsFinal": true,
        "IsHighLight": true
    }
}
参数名称
必选
类型
描述
ReplyType
是
String
回复语类型 ：
cloudAiGpt：腾讯云大模型对话
yunxiaowei：云小微客服
cloudAiWaiting: 首包超时等待话术
cloudAiTimeOut: 超时未返回话术，会话结束
sensitive：敏感内容固定话术
input：纯文本输入或流式文本输入的内容
enhanceText：纯文本驱动匹配上了话术管理中的内容
ReplyPro
是
String
用于播报的内容，含ssml标签和动作
ReplyDisplay
是
String
用于展示在端上的内容，含富文本标签
InteractionType
是
String
特殊消息类型
InteractionContent
是
String
特殊消息内容，用于下发弹窗、图片等非文本类的特殊消息
Uninterrupt
是
String
当前播报句是否可打断
Muted
是
String
播报当前句时是否关闭收音
SeqNo
是
Number
子句序号，大模型正常文本SeqNo从1开始，兜底话术从0开始
ContentType
是
Number
区分内容类型：
0：未知
1：普通字符串
2：有序列表
3：无序列表
4：图片链接
5：http链接
6：表格
7：代码块
TtsSupport
是
String
当前子句是否播报
IsFinal
是
String
是否为最后一句
IsHighLight
是
String
是否需要高亮展示

回复指令： 对话错误（1022 - answerErrorCommand）

表示对话错误。
{
    "answerErrorCommand": {
        "actorName": "xiaowei", 
        "errorCode": 100015,
        "errorMessage": "gateway: 4f314d55e44c47f0a705d96746f481c8 | 100015 | AssetImageExpired: 该数智人形象已经过期，请您申请延期或者加购"
    }
}
参数名称
必选
类型
描述
actorName
是
String
演员名称， 现在数智人只有一个演员，一定是 "xiaowei"
errorCode
是
Number
错误码
errorMessage
是
String
错误消息

3.5 获取数智人配置 (1060 getCurrentSettingCommand)

获取数智人的配置。
TVH.sendPackage({
    "getCurrentSettingCommand":{}
});

回复指令： 获取数智人配置完成 (1061 - getCurrentSettingFinishCommand)

返回数智人的配置信息
{
    "getCurrentSettingFinishCommand": {
        "currentSetting": {
            "globalSetting": {
                "driverServerUrl": "gw.tvs.qq.com", 
                "appKey": "xxxxxxxxxx", 
                "accessToken": "xxxxxxxxx", 
                "isDisableTls": false
            }, 
            "masterOutputSetting": {
                "outputType": "output_type_none", 
                "resolutionWidth": 1920, 
                "resolutionHeight": 1080, 
                "frameRate": 25, 
                "streamName": ""
            }, 
            "imageBoardBackgroundSetting": {
                "backgroundUrl":"c:\\\\background\\\\bg.png",
                "width": 1080,
                "height": 1920,
            }, 
            "actorSettingList": [
                {
                    "actorName": "xiaowei", 
                    "modelName": "youyou3", 
                    "clotheName": "xifutaoqun", 
                    "clotheColor": 74590, 
                    "shoeColor": 16777215, 
                    "shirtColor": 16777215, 
                    "optionMap": {
                        "chenyiColor": {
                            "colorValue": 16777214
                        }, 
                        "xieziColor": {
                            "colorValue": 16777214
                        }, 
                        "zhuse": {
                            "colorValue": 3812650
                        }, 
                        "yifuColor": {
                            "colorValue": 9486836
                        }
                    }, 
                    "location": {
                        "x": 0, 
                        "y": 0, 
                        "z": 0
                    }, 
                    "rotation": {
                        "x": 0, 
                        "y": 0, 
                        "z": 0
                    }, 
                    "scale": 1, 
                    "speaker": 33, 
                    "speakSpeed": 100, 
                    "speakVoiceType": 10001, 
                    "speakStyle": "2", 
                    "speakThType": "3D_metaa2e_chi_youyou3", 
                    "enableVctts": true, 
                    "virtualHumanKey": "7ef6f89745894efdafca615b16479c7b"
                }
            ], 
            "cameraSetting": {
                "location": {
                    "x": 13.459745439609492, 
                    "y": 2102.5260271584707, 
                    "z": 136.0542929452815
                }, 
                "rotation": {
                    "x": 1.9803832718014034e-16, 
                    "y": -0.9999999999999998, 
                    "z": -0.4000010000000458
                }, 
                "fovAngle": 10, 
                "humanBox": {
                    "top": 0,
                    "left": 0,
                    "bottom": 1, 
                    "right": 1
                }
            }, 
        }
    }
}
全局设置 (globalSetting)
参数名称
必选
类型
描述
driverServerUrl
是
String
驱动服务的域名， 默认公有云 gw.tvs.qq.com
appKey
是
String
数智人平台申请的 AppKey
accessToken
是
String
数智人平台申请的 AccessToken
isDisableTls
是
String
是否禁止 TLS, 如果是私有化内网部署，
设置为 true 走 http 和 ws 协议， false 走 https 和 wss 协议
主输出设置 (masterOutputSetting)
JS SDK 不使用视频流输出，请忽略此配置。
参数名称
必选
类型
描述
outputType
是
String
输出类型 。由于 JS 模式使用游戏视口，没有额外的输出，值为 output_type_none
resolutionWidth
是
Number
输出视频流宽度
resolutionHeight
是
Number
输出视频流高度
frameRate
是
Number
输出视频流帧率
streamName
是
String
输出视频流的名称
图片背景板设置 (imageBoardBackgroundSetting)
可以在人物背后叠加一个背景图片，可选。
参数名称
必选
类型
描述
backgroundUrl
是
String
背景图片的地址
width
是
Number
背景图片宽度
height
是
Number
背景图片高度
演员设置 (actorSettingList)
舞台上可能有多个数智人演员， 这里是个数组。
现阶段只有1个演员，演员名字为 xiaowei。
参数名称
必选
类型
描述
actorName
是
String
演员名称，用来标记多名演员， 现阶段只有1个演员，固定为 xiaowei
modelName
是
String
加载的数智人模型名称
clotheName
是
String
加载的数智人衣服名称， 一个数智人可能有多套服装
clotheColor
否
Number
【已废弃】 衣服颜色
shoeColor
否
Number
【已废弃】鞋子颜色
shirtColor
否
Number
【已废弃】 衬衫颜色
optionMap
是
Object
人物选项配置，可以设置衣服颜色，控制配饰的显示和隐藏等。
location
是
Object
演员在 3D 舞台的位置
rotation
是
Object
演员 3D 旋转的角度
scale
是
Number
演员的缩放比例
speaker
是
Number
演员说话的发音人ID
speakSpeed
是
Number
演员说话的语速
speakVoiceType
是
Number
演员说话的音色，1 多人多风格；2 新闻；3 客服；4聊天情绪
speakStyle
是
String
演员说话风格
speakThType
是
String
演员驱动说话的口型参数
enableVctts
是
Boolean
是否允许声音驱动
virtualHumanKey
是
String
数智人平台用来标识一个人物的唯一Key
摄像机设置 (cameraSetting)
参数名称
必选
类型
描述
location
是
String
摄像机的位置 3D 坐标
rotation
是
Number
摄像机的旋转角度 3D 角度
fovAngle
是
Number
摄像机的可视角
humanBox
是
Number
人物框, 归一化的值，表示距离上下左右的百分比。

4. ASR 命令

4.1 开始和停止 ASR (2000 - asrControlCommand)

ASR 程序启动就自动开始收音， 可以在配置界面进行修改， 也可以通过此命令开始和停止收音。 
TVH.sendPackage({
    "asrControlCommand":{
        "enableAsr": true,
    }
});
参数说明：
参数名称
必选
类型
描述
enableAsr
是
bool
启动或停止 ASR 收音

4.2 监听指令：语音识别结果 (2002 - asrResultUpdateCommand)

ASR 程序会持续发出语音的识别结果，包括中间结果。
{
    "asrResultUpdateCommand":{
        "text": "今天天气不错",
        "sentenceComplete": false
    }
}
参数说明：
参数名称
必选
类型
描述
text
是
String
识别的文本
sentenceComplete
是
bool
是否是一个完整的句子

5. 多模客户端 命令

5.1 动作检测窗口保持在屏幕顶层 (2003 - bodyAnalysisWindowStayOnTopCommand)

如果需要将动作检测窗口保持在屏幕顶层，在浏览器/播放器/游戏窗口全屏后，需要通过此对动作检测窗口置顶。
TVH.sendPackage({
    "bodyAnalysisWindowStayOnTopCommand":{
        "stayOnTop": true,
    }
});
参数说明：
参数名称
必选
类型
描述
stayOnTop
是
bool
动作检测窗口保持在屏幕顶层

5.2 监听指令：人脸和手势识别更新 (2004 - bodyAnalysisResultUpdateCommand)

多模客户端检测到人脸和手势的变更后，会通过此命令更新识别结果。
{
    "bodyAnalysisResultUpdateCommand":{
        "faceCount": 1,
        "faceRect": {
            "x": 100.0,
            "y": 100.0,
            "width": 60.0,
            "height": 60.0
        },
        "gestureName": "label_ok",
        "probability": 0.9,
        "gestureRect": {
            "x": 300.0,
            "y": 50.0,
            "width": 40.0,
            "height": 40.0
        }
    }
}
参数说明：
参数名称
必选
类型
描述
faceCount
是
int
人脸张数
faceRect
否
BodyAnalysisRect
选中人脸的位置 (face_count 为0时无效)
gestureName
是
String
识别的手势名
probability
是
Float
识别手势的置信度
gestureRect
否
BodyAnalysisRect
手势的位置 (gesture_name 为空时无效)

中国站
目录