腾讯云智能数智人云渲染鸿蒙 SDK 接口说明

﻿SDK 下载链接﻿
﻿TrtcSdk 下载链接﻿
配套使用 TRTC HarmonyOS SDK 定制化版本，需要在 oh-package.json5 中配置 TRTC 依赖：
"dependencies": {
  "@tencentcloud/liteavsdk_trtc": "file:../libs/LiteAVSDK_TRTC_13.4.0.8928.har"
}
1. Virtualman.init 参数配置接口
init(params: VirtualmanParams): void
配置 SDK 鉴权参数和建流参数，不建流。
注意：
init 仅做参数存储，不会发起网络请求。实际建流请调用 open() 或 openByAsset()。
VirtualmanParams 参数说明
参数名称
数据类型
参数类型
说明
appkey
string
必要参数
数智人 key，通过交互数智人平台创建的数智人的标识 appkey
accesstoken
string
必要参数
数智人 accessToken，通过交互数智人平台创建的数智人的 accessToken
serverDomain
string
可选参数
服务器域名，不带协议头。默认值 "gw.tvs.qq.com"。私有化部署时填入对应域名。
disableTls
boolean
可选参数
是否禁用 TLS 加密。默认 false（使用 https/wss），设为 true 则使用 http/ws。私有化部署时按需设置。
virtualmanProjectParams
VirtualmanProjectParams
可选参数
项目型建流参数。配置后调用 open() 即可建流。与 assetVirtualmanParams 二选一。
assetVirtualmanParams
AssetVirtualmanParams
可选参数
资产型建流参数。配置后调用 openByAsset() 即可建流。与 virtualmanProjectParams 二选一。
VirtualmanProjectParams 参数说明
参数名称
数据类型
参数类型
说明
virtualmanProjectId
string
必要参数
数智人项目 ID。
userId
string
可选参数
用户的唯一标识，由调用方自己维护，以相同的 UserId 创建新流，会导致上一个该 UserId 流关闭。默认使用设备 ID。
注意：
当使用 TRTC 协议时，该参数为数智人进房用户，调用方自身进房用户不能与该用户相同，如果相同会将数智人踢出房间，导致断流。
extraInfo
ExtraInfo
可选参数
建流扩展参数。
protocolOption
ProtocolOption
可选参数
用于配置外部 TRTC 应用。
AssetVirtualmanParams 参数说明
参数名称
数据类型
参数类型
说明
assetVirtualmanKey
string
必要参数
资产数智人 key（assetKey）。
userId
string
可选参数
用户的唯一标识，由调用方自己维护，以相同的 UserId 创建新流，会导致上一个该 UserId 流关闭。默认使用设备 ID。
注意：
当使用 TRTC 协议时，该参数为数智人进房用户，调用方自身进房用户不能与该用户相同，如果相同会将数智人踢出房间，导致断流。
extraInfo
ExtraInfo
可选参数
建流扩展参数。
protocolOption
ProtocolOption
可选参数
用于配置外部 TRTC 应用。
ExtraInfo 参数说明（可选）
参数名称
数据类型
参数类型
说明
alphaChannelEnable
boolean
可选参数
是否开启透明通道。默认值 false。开启后 SDK 内部会自动设置 AlphaPadDisable。
ProtocolOption 参数说明（可选，用于配置外部 TRTC 应用）
参数名称
数据类型
参数类型
说明
trtcUseExternalApp
boolean
可选参数
是否使用外部 TRTC AppId，如果不使用，将使用数智人平台统一的 TRTC AppId。
注意：
数智人平台统一的 TRTC AppId，仅用于调试阶段，投产时，由用户自行在腾讯云申请 TRTC AppId。
trtcAppId
string
条件必填
TRTC AppId（使用外部 TRTC AppId 时必填），获取方式请参见 实时音视频-应用概览。
trtcRoomId
number
条件必填
TRTC 数字房间号。使用外部 TRTC AppId 时，trtcRoomId 和 trtcStrRoomId 必填其一。数字房间号最大值为4294967294。
注意：
要和 trtcAutoGenRoomIdType 的房间号类型匹配。
trtcStrRoomId
string
条件必填
TRTC 字符串房间号。使用外部 TRTC AppId 时，trtcRoomId 和 trtcStrRoomId 必填其一。
注意：
要和 trtcAutoGenRoomIdType 的房间号类型匹配。
trtcAutoGenRoomIdType
number
可选参数
房间号类型。0：数字类型，1：字符串类型，默认数字类型。
trtcUserSig
string
条件必填
TRTC 数智人用户签名（使用外部 TRTC AppId 时必填，计算签名时使用的用户名要与上面的 userId 参数的值保持一致），计算方式请参见 实时音视频-用户鉴权。
trtcPrivateMapKey
string
可选参数
TRTC 数智人用户权限票据。未开启高级权限控制可不填，默认填 "dummy"。
clientUserId
string
条件必填
客户侧用户 ID。使用外部 TRTC AppId 时必填。
注意：
调用方自身进房用户，不能与数智人的 userId 相同，如果相同会将数智人踢出房间，导致断流。
clientUserSig
string
条件必填
客户侧用户签名（使用外部 TRTC AppId 时必填），计算方式请参见 实时音视频-用户鉴权。
clientPrivateMapKey
string
可选参数
客户侧用户权限票据。未开启高级权限控制可不填，默认填 "dummy"。
2. Virtualman.open 建流接口
2.1 通过 ProjectId 建流
open(): Promise<InitResult>
使用 init 中配置的 virtualmanProjectParams 建流。返回 Promise，resolve 时携带 InitResult。
2.2 通过 AssetVirtualmanKey 建流
openByAsset(): Promise<InitResult>
使用 init 中配置的 assetVirtualmanParams 建流，返回值同上。
InitResult 说明
字段
类型
说明
success
boolean
是否建流成功
sessionId
string
会话 ID（成功时返回）
error
string
错误信息（失败时返回）
代码示例
// ArkTS 严格模式：参数对象必须用 new 创建，不可使用匿名对象字面量
const params = new VirtualmanParams()
params.appkey = Config.APP_KEY
params.accesstoken = Config.ACCESS_TOKEN
﻿
const projectParams = new VirtualmanProjectParams()
projectParams.virtualmanProjectId = Config.VIRTUALMAN_PROJECT_ID
const extra = new ExtraInfo()
extra.alphaChannelEnable = true
projectParams.extraInfo = extra
params.virtualmanProjectParams = projectParams
﻿
virtualman.init(params)
﻿
// 通过 ProjectId 建流
const result = await virtualman.open()
if (result.success) {
  console.info(`建流成功, sessionId: ${result.sessionId}`)
} else {
  console.error(`建流失败: ${result.error}`)
}
﻿
// 通过 AssetVirtualmanKey 建流
const result2 = await virtualman.openByAsset()
3. Virtualman.chat 对话接口
chat(params: ChatParams): boolean
用户发送文本，经平台 AI 处理后，数智人回答并播报。
ChatParams 参数说明
参数名称
数据类型
参数类型
说明
text
string
必要参数
对数智人要发送的文本。
isNewChat
boolean
可选参数
是否开启新对话。默认值 false。
reqId
string
可选参数
单次驱动的唯一标识, 32位的 UUID（不包含'-'）。
注意：
每次发送都新生成一个 ReqId。默认自动生成。
videoSeiInfo
string
可选参数
需要在视频流 SEI 中携带的信息，字符串内容为 JSON 格式。发送后会在视频流播报本次响应时在 SEI 中携带。
代码示例
virtualman.chat({ text: '你好', isNewChat: true })
4. Virtualman.sendText 纯文本驱动接口
sendText(params: TextParams): boolean
直接控制数智人播报指定文本，不经过对话服务。
TextParams 参数说明
参数名称
数据类型
参数类型
说明
text
string
必要参数
纯文本驱动的内容。
reqId
string
可选参数
单次驱动的唯一标识, 32位的 UUID（不包含'-'）。默认自动生成。
videoSeiInfo
string
可选参数
需要在视频流 SEI 中携带的信息，字符串内容为 JSON 格式。
代码示例
virtualman.sendText({ text: '要播报的文本' })
5. Virtualman.sendStreamText 流式文本驱动接口
sendStreamText(params: StreamTextParams): boolean
StreamTextParams 参数说明
参数名称
数据类型
参数类型
说明
reqId
string
必要参数
单次驱动的唯一标识。每一段流式文本指定一个32位 UUID 值(不包含'-')。
注意：
每一段流式文本序列指定一个 ReqId，而不是每一次请求指定一个。
text
string
必要参数
流式文本内容，只需要发送增量的文本。每个片包字符串长度限制 2000 字节。
seq
number
必要参数
流式文本片包序号，序号必须从 1 开始。
isFinal
boolean
可选参数
用于标记本次流式文本驱动是否结束，默认值 false。
注意：
当文本发送完毕后，需要再发送一个 isFinal=true 的驱动指令结束当次流式文本驱动。
isSentence
boolean
可选参数
是否是子句模式，缺省值 false。为 true 服务端不会做重新组句。
isInsertSentence
boolean
可选参数
是否是插入的子句，缺省值 false。为 true 并且是子句模式则表示当前分片需要插播。
videoSeiInfo
string
可选参数
需要在视频流 SEI 中携带的信息，字符串内容为 JSON 格式。
6. Virtualman.sendAudio 音频驱动接口
sendAudio(params: AudioParams): boolean
AudioParams 参数说明
参数名称
数据类型
参数类型
说明
reqId
string
必要参数
单次驱动的唯一标识。每一段音频指定一个32位 UUID 值(不包含'-')。
注意：
每一段流式音频序列指定一个 ReqId，而不是单独一次音频分片请求指定一个。
audio
string
必要参数
音频原始数据经 Base64 编码后的字符串。只支持：
- 格式：PCM
- 采样率：16kHz
- 采样位深：16bits
- 声道：单声道
seq
number
必要参数
音频片包序号，序号必须从 1 开始。
isFinal
boolean
可选参数
用于标记本次音频驱动是否结束，默认值 false。
注意：
当数据包发送完毕后，必须再发送一个 isFinal=true 的空数据包（audio 字段填空串）结束当次音频驱动使数字人回到静默状态。
videoSeiInfo
string
可选参数
需要在视频流 SEI 中携带的信息，字符串内容为 JSON 格式。
7. Virtualman.stop() 打断播报
stop(): boolean
在音频驱动、流式文本或非流式文本播报时，调用此接口用于打断当前播报。
支持的打断类型：
音频驱动打断：支持打断 sendAudio() 发起的音频驱动播报
流式文本打断：支持打断 sendStreamText() 发起的流式文本播报
普通文本打断：支持打断 sendText() 发起的文本播报
注意：
需要等到 WebSocket 下行消息返回 TextStart/AudioStart 标记后才可发送打断请求。
8. Virtualman.setSmartActionEnabled 开启智能动作
setSmartActionEnabled(enable: boolean): void
设置是否开启智能动作，缺省值 false。为 true 并且输入的文本或者话术增强后的文本没有动作标签则会生成智能动作。
9. Virtualman 事件回调
通过 Virtualman 实例的属性设置事件回调，感知连接状态变化和消息。
回调属性说明
属性
类型
说明
onError
(error: string) => void
错误回调。错误信息为字符串，包含 WebSocket、TRTC、会话失效等各类错误。
onMessage
(text: string) => void
收到 WebSocket 下行消息（JSON 字符串）。
onWsOpen
() => void
WebSocket 连接已建立，此时可以发送消息。
onWsClose
(code: number, reason: string) => void
WebSocket 连接关闭。
代码示例
virtualman.onError = (error) => {
  console.error(`错误: ${error}`)
}
virtualman.onMessage = (text) => {
  console.info(`WS消息: ${text}`)
}
virtualman.onWsOpen = () => {
  console.info('WebSocket 已连接，可以发送消息')
}
virtualman.onWsClose = (code, reason) => {
  console.info(`WebSocket 关闭: code=${code}`)
}
WebSocket 下行消息返回数据字段说明参考 长连接下行消息。
10. Virtualman.trtcListener TRTC 事件监听回调
通过 Virtualman 实例的 trtcListener 属性设置 TRTC 事件监听。
TRTCListener 接口说明
方法
说明
onRecvSEIMsg(userId: string, data: Uint8Array)
收到 SEI 消息的回调。详细参考﻿
onFirstVideoFrame(userId: string, streamType: number, w: number, h: number)
开始渲染远端用户的首帧画面。详细参考﻿
onError(errCode: number, errMsg: string, extraInfo: string)
错误事件回调。详细参考﻿
onConnectionLost()
TRTC 与云端的连接已经断开。
onTryToReconnect()
TRTC 正在尝试重新连接到云端。
onConnectionRecovery()
TRTC 与云端的连接已经恢复。
onNetworkQuality(localQuality: Object, remoteQuality: Object[])
网络质量回调。详细参考﻿
onStatistics(statistics: Object)
网络和性能统计数据回调。详细参考﻿
注意：
TRTCListener 所有方法均为可选实现。
代码示例
virtualman.trtcListener = {
  onFirstVideoFrame: (userId, streamType, w, h) => {
    console.info(`首帧: ${userId} ${w}x${h}`)
  },
  onConnectionLost: () => {
    console.warn('TRTC 连接断开')
  }
}
11. Virtualman.close() 数智人关流接口
close(): void
关闭当前数智人流。关流后可以再次调用 open() 或 openByAsset() 重新建流，无需重建 View。
注意：
 在页面销毁时或需要的时机调用关闭方法以关闭数智人流，否则会占用后台资源。VirtualmanView 在 aboutToDisappear 时会自动调用 close()。
SDK 内部重连逻辑
1. open 建流时，如果建流成功在轮询流状态过程遇到网络异常，有重试机制保证流能建立成功。如果超时失败，Promise 返回的 InitResult.error 里会有对应的错误信息。
2. WebSocket 自动重连：
SDK 内部监听 TRTC 网络状态，当检测到 WebSocket 断开且网络可用时，自动触发重连。
重连防重入：保证同一时刻只有一个重连请求在进行中。
终止条件：当收到 110014 错误码（流失效）时，停止重连。此时需要重新调用 open 建流。
3. WebSocket 状态感知：通过 virtualman.onWsOpen / virtualman.onWsClose / virtualman.onError 回调，可实时感知连接状态变化，用于 UI 提示用户当前是否可以交互。
﻿

参数名称	数据类型	参数类型	说明
appkey	string	必要参数	数智人 key，通过交互数智人平台创建的数智人的标识 appkey
accesstoken	string	必要参数	数智人 accessToken，通过交互数智人平台创建的数智人的 accessToken
serverDomain	string	可选参数	服务器域名，不带协议头。默认值 "gw.tvs.qq.com"。私有化部署时填入对应域名。
disableTls	boolean	可选参数	是否禁用 TLS 加密。默认 false（使用 https/wss），设为 true 则使用 http/ws。私有化部署时按需设置。
virtualmanProjectParams	VirtualmanProjectParams	可选参数	项目型建流参数。配置后调用 `open()` 即可建流。与 assetVirtualmanParams 二选一。
assetVirtualmanParams	AssetVirtualmanParams	可选参数	资产型建流参数。配置后调用 `openByAsset()` 即可建流。与 virtualmanProjectParams 二选一。

字段	类型	说明
success	boolean	是否建流成功
sessionId	string	会话 ID（成功时返回）
error	string	错误信息（失败时返回）

属性	类型	说明
onError	(error: string) => void	错误回调。错误信息为字符串，包含 WebSocket、TRTC、会话失效等各类错误。
onMessage	(text: string) => void	收到 WebSocket 下行消息（JSON 字符串）。
onWsOpen	() => void	WebSocket 连接已建立，此时可以发送消息。
onWsClose	(code: number, reason: string) => void	WebSocket 连接关闭。

方法	说明
onRecvSEIMsg(userId: string, data: Uint8Array)	收到 SEI 消息的回调。详细参考
onFirstVideoFrame(userId: string, streamType: number, w: number, h: number)	开始渲染远端用户的首帧画面。详细参考
onError(errCode: number, errMsg: string, extraInfo: string)	错误事件回调。详细参考
onConnectionLost()	TRTC 与云端的连接已经断开。
onTryToReconnect()	TRTC 正在尝试重新连接到云端。
onConnectionRecovery()	TRTC 与云端的连接已经恢复。
onNetworkQuality(localQuality: Object, remoteQuality: Object[])	网络质量回调。详细参考
onStatistics(statistics: Object)	网络和性能统计数据回调。详细参考

云渲染鸿蒙 SDK 接口说明

本页目录：

﻿SDK 下载链接﻿

﻿TrtcSdk 下载链接﻿

1. Virtualman.init 参数配置接口

VirtualmanParams 参数说明

VirtualmanProjectParams 参数说明

AssetVirtualmanParams 参数说明

ExtraInfo 参数说明（可选）

ProtocolOption 参数说明（可选，用于配置外部 TRTC 应用）

2. Virtualman.open 建流接口

2.1 通过 ProjectId 建流

2.2 通过 AssetVirtualmanKey 建流

InitResult 说明

代码示例

3. Virtualman.chat 对话接口

ChatParams 参数说明

代码示例

4. Virtualman.sendText 纯文本驱动接口

TextParams 参数说明

代码示例

5. Virtualman.sendStreamText 流式文本驱动接口

StreamTextParams 参数说明

6. Virtualman.sendAudio 音频驱动接口

AudioParams 参数说明

7. Virtualman.stop() 打断播报

8. Virtualman.setSmartActionEnabled 开启智能动作

9. Virtualman 事件回调

回调属性说明

代码示例

10. Virtualman.trtcListener TRTC 事件监听回调

TRTCListener 接口说明

代码示例

11. Virtualman.close() 数智人关流接口

SDK 内部重连逻辑

SDK 下载链接

TrtcSdk 下载链接