云渲染 Android SDK 接口说明

最近更新时间:2026-02-02 18:21:21

我的收藏

当前版本号 2.2.7

配套使用 TRTC SDK 定制化版本,需要在 App 的 build.gradle 配置中增加指定版本的 TRTC 依赖。
dependencies {
implementation 'com.tencent.liteav.customize:LiteAVSDK_TRTC:13.0.0.19666'
... 其他依赖
}


1. Virtualman.init(VirtualmanParams,callback,WebSocketListener) 数智人初始化接口

VirtualmanParams 参数说明

参数名称
数据类型
参数类型
说明
appkey
String
必要参数
数智人 key,通过交互数智人平台创建的数智人的标识 appkey
accessToken
String
必要参数
数智人 accessToken,通过交互数智人平台创建的数智人的 accessToken
httpOrigin
String
可选参数
设置后 HTTP 请求都按这个 origin 设置,不设置时请求公有云地址
infoVisible
Boolean
可选参数
是否展示 session 信息,默认为 true 则展示 session 信息,设置为 false 隐藏
virtualmanProjectParams
VirtualmanProjectParams
可选参数
用于按 projectId 建流
注意:
如果 projectId 建流和 assetKey 建流都填写,以 projectId 建流优先。
assetVirtualmanParams
AssetVirtualmanParams
可选参数
用于按 assetKey 建流

VirtualmanProjectParams 参数说明

参数名称
数据类型
参数类型
说明
driverType
Int
可选参数
驱动方式。默认值 3。
virtualmanProjectId
String
必要参数
数智人项目 ID。
userId
String
可选参数
用户的唯一标识,由调用方自己维护,以相同的 UserId 创建新流,会导致上一个该 UserId 流关闭。默认使用 ANDROID_ID
注意:
当使用 TRTC 协议时,该参数为数智人进房用户,调用方自身进房用户不能与该用户相同,如果相同会将数智人踢出房间,导致断流。
extraInfo
ExtraInfo
可选参数
建流扩展参数。
protocolOption
ProtocolOption
可选参数
用于配置外部 TRTC 应用。

AssetVirtualmanParams 参数说明

参数名称
数据类型
参数类型
说明
driverType
Int
可选参数
驱动方式。默认值 3。
assetVirtualmanKey
String
必要参数
资产数智人 key(assetKey)。
userId
String
可选参数
用户的唯一标识,由调用方自己维护,以相同的 UserId 创建新流,会导致上一个该 UserId 流关闭。默认使用 ANDROID_ID。
注意:
当使用 TRTC 协议时,该参数为数智人进房用户,调用方自身进房用户不能与该用户相同,如果相同会将数智人踢出房间,导致断流。
extraInfo
ExtraInfo
可选参数
建流扩展参数。
protocolOption
ProtocolOption
可选参数
用于配置外部 TRTC 应用。

ExtraInfo 参数说明(可选)

参数名称
数据类型
参数类型
说明
alphaChannelEnable
Boolean
可选参数
是否开启透明通道。默认值 false。

ProtocolOption 参数说明(可选,用于配置外部 TRTC 应用)

参数名称
数据类型
参数类型
说明
trtcUseExternalApp
Boolean
可选参数
是否使用外部 TRTC AppId,如果不使用,将使用数智人平台统一的 TRTC AppId。
注意:
数智人平台统一的 TRTC AppId,仅用于调试阶段,投产时,由用户自行在腾讯云申请 TRTC AppId。
trtcAppId
String
条件必填
TRTC AppId(使用外部 TRTC AppId 时必填),获取方式请参见 实时音视频-应用概览
trtcRoomId
Int
条件必填
TRTC 数字房间号。使用外部 TRTC AppId 时,trtcRoomId 和 trtcStrRoomId 必填其一。数字房间号最大值为4294967294。
注意:
要和trtcAutoGenRoomIdType的房间号类型匹配。
trtcStrRoomId
String
条件必填
TRTC 数字房间号。使用外部 TRTC AppId 时,trtcRoomId 和 trtcStrRoomId 必填其一。
注意:
要和trtcAutoGenRoomIdType的房间号类型匹配。
trtcAutoGenRoomIdType
Int
可选参数
房间号类型。0:数字类型,1:字符串类型,默认数字类型。
trtcUserSig
String
条件必填
TRTC 数智人用户签名(使用外部 TRTC AppId 时必填,计算签名时使用的用户名要与上面的userld参数的值保持一致,数智人需要使用该签名才能加入房间),计算方式请参见 实时音视频-用户鉴权
trtcPrivateMapKey
String
可选参数
TRTC 数智人用户权限票据。
说明:
如果开启了TRTC 高级权限控制 功能,则需要正确的权限票据,否则数智人将无法加入房间。
未开启高级权限控制可不填,默认填 “dummy”。
clientUserId
String
条件必填
客户侧用户 ID。使用外部 TRTC AppId 时必填。
注意:
调用方自身进房用户,不能与数智人的 userId 相同,如果相同会将数智人踢出房间,导致断流。
clientUserSig
String
条件必填
客户侧用户签名(使用外部 TRTC AppId 时必填,计算签名时使用的用户名要与clientUserId参数的值保持一致),计算方式请参见 实时音视频-用户鉴权
clientPrivateMapKey
String
可选参数
客户侧用户权限票据。
说明:
如果开启了TRTC 高级权限控制 功能,则需要正确的权限票据,否则客户侧用户将无法加入房间。
未开启高级权限控制可不填,默认填 “dummy”。


代码示例


// 资产建流
mVirtualmanParams.appkey = Config.APP_KEY
mVirtualmanParams.accesstoken = Config.ACCESS_TOKEN
mVirtualmanParams.assetVirtualmanParams = AssetVirtualmanParams()
mVirtualmanParams.assetVirtualmanParams?.assetVirtualmanKey = Config.ASSET_VIRTUALMAN_KEY
mVirtualmanParams.assetVirtualmanParams?.extraInfo = ExtraInfo()
mVirtualmanParams.assetVirtualmanParams?.extraInfo?.alphaChannelEnable = false
mVirtualman.init(mVirtualmanParams, { result ->
Log.i(TAG, "---------------------------------------------------")
Log.i(TAG, result.toString())
}, StreamWebSocketListener())

// 项目建流
mVirtualmanParams.appkey = Config.APP_KEY
mVirtualmanParams.accesstoken = Config.ACCESS_TOKEN
mVirtualmanParams.virtualmanProjectParams = VirtualmanProjectParams()
mVirtualmanParams.virtualmanProjectParams?.virtualmanProjectId = Config.VIRTUALMAN_PROJECT_ID
mVirtualmanParams.virtualmanProjectParams?.extraInfo = ExtraInfo()
mVirtualmanParams.virtualmanProjectParams?.extraInfo?.alphaChannelEnable = true
mVirtualman.init(mVirtualmanParams, { result ->
Log.i(TAG, "---------------------------------------------------")
Log.i(TAG, result.toString())
}, StreamWebSocketListener())



callback 参数说明

初始化回调函数


WebSocketListener 参数说明(可选)

方法
说明
onClosed
关闭握手完成,连接正常关闭时调用。
onClosing
收到对方的关闭帧,但握手尚未完成时调用。
onFailure
连接异常断开(网络错误、超时等)时调用。
onMessage
在收到文本类型消息时调用。
onOpen
websocket连接成功时调用。
WebSocketListener onMessage 返回数据字段说明参考 长连接下行消息


2. Virtualman.sendText(params: SendTextParams) 发送文本接口

SendTextParams 参数说明

参数名称
数据类型
参数类型
说明
text
String
必要参数
对数智人要发送的文本。
isNewChat
Boolean
可选参数
是否开启新对话。默认值 false。
reqId
String
可选参数
单次驱动的唯一标识, 32位的 UUID(不包含‘-’)。
注意:
每次发送都新生成一个 ReqId。
videoSeiInfo
String
可选参数
需要在视频流 SEI 中携带的信息,字符串内容为 JSON 格式。发送后会在视频流播报本次响应时在 SEI 中携带。
当前仅支持 2D 形象,视频流中信息说明请参见 视频流嵌入信息说明


3. Virtualman.sendStreamText(SendStreamTextParams) 流式发送文本接口

SendStreamTextParams 参数说明

参数名称
数据类型
参数类型
说明
reqId
String
必要参数
单次驱动的唯一标识。每一段流式文本指定一个32位 UUID 值(不包含‘-’)。
注意:
每一段流式文本序列指定一个 ReqId,而不是每一次请求指定一个。
值得注意的是,在发送 final 包时仍然使用的是指定的这一个 ReqId,不需要再生成一个。
text
String
必要参数
流式文本内容,只需要发送增量的文本。每个片包字符串长度限制 2000 字节。
注意:
子句模式发送要求:
1. 输入文本应为完整的句子序列,例如以,。!?等标点符号分割的文本。
2. 单个子句长度应大于10个汉字或单词。
非子句模式发送要求:
1. 流式非子句不支持 Text 中带 SSML 标签。
2. 发送速度不能过慢,过慢会导致出现非预期的 SpeakStatus,推荐发送速度与大模型返回数据的速度一致。
seq
Int
必要参数
流式文本片包序号,序号必须从 1 开始。
isFinal
Boolean
可选参数
用于标记本次流式文本驱动是否结束,默认值 false。
注意:
1. 发送 final 包的时机:
当流式文本驱动指令的文本内容 Text 都已发送完毕后,需要再发送一个 IsFinal=true 的驱动指令(这里简称 final 包,Text 字段可带有文本内容也可以是空串),来结束当次流式文本驱动,使数字人回到静默状态。
2. 没有及时发送 final 包会出现的问题
对于流式文本驱动指令,包含子句模式与非子句模式,都可能会出现数智人播报期间卡顿的问题。
isSentence
Boolean
可选参数
是否是子句模式,缺省值:false。为 true 服务端不会做重新组句。
isInsertSentence
Boolean
可选参数
是否是插入的子句,缺省值:false。为 true 并且是子句模式则表示当前分片需要插播。
videoSeiInfo
String
可选参数
需要在视频流 SEI 中携带的信息,字符串内容为 JSON 格式。发送后会在视频流播报本次响应时在 SEI 中携带。
当前仅支持 2D 形象,视频流中信息说明请参见 视频流嵌入信息说明



4. Virtualman.textDrive(params: TextDriveParams) 纯文本驱动接口

在使用对话服务时,调用此接口用于使用不带对话服务的纯文本驱动,text 为文本驱动的内容。

TextDriveParams 参数说明

参数名称
数据类型
参数类型
说明
text
String
必要参数
纯文本驱动的内容。
reqId
String
可选参数
单次驱动的唯一标识, 32位的 UUID(不包含‘-’)。
注意:
每次发送都新生成一个 ReqId。
videoSeiInfo
String
可选参数
需要在视频流 SEI 中携带的信息,字符串内容为 JSON 格式。发送后会在视频流播报本次响应时在 SEI 中携带。
当前仅支持 2D 形象,视频流中信息说明请参见 视频流嵌入信息说明


5. Virtualman.sendAudio(SendAudioParams) 发送音频驱动接口

SendAudioParams 参数说明

参数名称
数据类型
参数类型
说明
reqId
String
必要参数
单次驱动的唯一标识。每一段音频指定一个32位 UUID 值(不包含‘-’)。
注意:
每一段流式音频序列指定一个 ReqId,而不是单独一次音频分片请求指定一个。
值得注意的是,在发送 final 包时仍然使用的是指定的这一个 ReqId,不需要再生成一个。
audio
String
必要参数
音频原始数据的 byte 数组,经 Base64 编码后的字符串。只支持:
格式:PCM
采样率:16kHz
采样位深:16bits
声道:单声道
可以使用 FFmpeg 工具对音频格式进行调整 FFmpeg。更多请参见 FFmpeg 转化音频格式说明
seq
Int
必要参数
流式文本片包序号,序号必须从 1 开始。
isFinal
Boolean
可选参数
用于标记本次音频驱动是否结束,默认值 false。
注意:
当数据包发送完毕后,必须再发送一个 IsFinal=true 的空数据包(Audio 字段填空串)结束当次音频驱动使数字人回到静默状态。

没有及时发送 final 包会出现的问题:
1. 可能会出现数智人播报期间卡顿的问题。
2. 后台在指定时间间隔(默认2秒)内既没收到音频包又没收到 IsFinal=true 的尾包,则后台会自动补一个 IsFinal=true 的尾包,使数智人进入静默状态。
videoSeiInfo
String
可选参数
需要在视频流 SEI 中携带的信息,字符串内容为 JSON 格式。发送后会在视频流播报本次响应时在 SEI 中携带。
当前仅支持 2D 形象,视频流中信息说明请参见 视频流嵌入信息说明



6. Virtualman.stop() 打断文本播报

在流式或非流式驱动播报时,调用此接口用于打断当前文本播报。
注意:
需要等到 WebSocket 下行消息返回 TextStart 标记后才可发送打断请求。

7. Virtualman.setSmartActionEnabled(value: Boolean) 开启智能动作

设置是否开启智能动作,缺省值:false。为 true 并且输入的文本或者话术增强后的文本没有动作标签则会生成智能动作。


8. Virtualman.statSession(callback) 查询当前会话的状态

用于查询当前会话的状态,callback 返回值参考 查询会话状态


9. Virtualman.listSessionOfUin(callback) 查询某个 uin 账号所有进行中的会话

用于查询当前 uin 账号所有进行中的会话,callback 返回值参考 查询 uin 下的会话列表


10. Virtualman.listSessionOfProjectid(callback) 查询数智人项目下的会话列表

用于查询当前数智人项目下的所有进行中的会话列表,callback 返回值参考 查询数智人项目下的会话列表


11. Virtualman.close() 数智人销毁接口

在 activity onDestroy 中或需要的时机调用关闭的方法以关闭数智人流,否则会占用后台资源。


12. Virtualman.isWebSocketConnected() 检查 WebSocket 连接状态

用于检查当前 WebSocket 是否处于连接状态。
返回值:Boolean,true 表示已连接,false 表示未连接或已断开。


13. Virtualman.reconnectWebSocket() 重新建立 WebSocket 连接

用于在 WebSocket 断开后重新建立连接。通常在网络恢复后调用。


14. Virtualman.setTRTCListener(listener: TRTCListener?) TRTC 事件监听回调

用于设置 TRTC 事件监听器。

TRTCListener 接口说明

方法
说明
onRecvSEIMsg(userId: String?, data: ByteArray?)
收到 SEI 消息的回调。详细参考
onFirstVideoFrame(userId: String?, streamType: Int, width: Int, height: Int)
开始渲染自己本地或远端用户的首帧画面。详细参考
onError(errCode: Int, errMsg: String?, extraInfo: Bundle?)
错误事件回调。详细参考
onConnectionLost()
TRTC与云端的连接已经断开。
onTryToReconnect()
TRTC正在尝试重新连接到云端。
onConnectionRecovery()
TRTC与云端的连接已经恢复。
onNetworkQuality(localQuality: TRTCQuality, remoteQuality: ArrayList?)
网络质量回调。详细参考
onStatistics(statistics: TRTCStatistics?)
网络和性能统计数据回调。 详细参考

代码示例

mVirtualman.setTRTCListener(object : TRTCListener {
override fun onRecvSEIMsg(userId: String?, data: ByteArray?) {
if (data != null && data.isNotEmpty()) {
Log.i(TAG, "收到SEI消息 - 用户ID: $userId, 消息大小: ${data.size}")
// 如果数据长度>=17,解析JSON部分
if (data.size >= 17) {
try {
val jsonBytes = data.sliceArray(16 until data.size)
val jsonString = String(jsonBytes, Charsets.UTF_8)
Log.i(TAG, "SEI JSON部分: $jsonString")

} catch (e: Exception) {
Log.e(TAG, "解析SEI JSON部分失败", e)
}
}
}
}
})


获取TRTC实例的方案

警告:
1. 由于SDK内部也用到TRTC实例,所以调用close之前,在使用过程不要轻易销毁TRTC实例。
2. 通过TRTC的addListener添加的监听,要注意适当时机调用removeListener方法。防止监听事件重复添加。
// 可以直接获取到trtc实例
trtcCloud = TRTCCloud.sharedInstance(applicationContext)
// 通过 addListener 添加 SEI 监听(演示外部直接使用 TRTC 实例)
trtcCloud?.addListener(object : TRTCCloudListener() {
override fun onRecvSEIMsg(userId: String?, data: ByteArray?) {
if (data != null && data.size > 16) {
val jsonData = String(data, 16, data.size - 16, Charsets.UTF_8)
Log.i(TAG, "[addListener] 收到SEI消息: userId=$userId, data=$jsonData")
}
}
})


SDK内部重连逻辑的介绍

1. init新建流时,如果建流成功在轮询流状态过程遇到网络异常,有10s的重试机制保证流能建立成功。如果超时失败,回调里会有对应的错误信息。
2. websocket的事件相关
会收到onFailure代表websocket断开了,不要调用send相关方法,会失败。
会收到onOpen代表websocket重连成功,可以继续调用send相关方法。
SDK内部会监听TRTC的onNetworkQuality事件,当websocket断开时,网络质量是1-5时,websocket会尝试重连。如果重连时流已经失效,onMessage事件里会有相关错误信息。