云渲染 iOS SDK 接口说明

最近更新时间:2026-06-01 16:53:00

我的收藏
配套使用 TRTC SDK 定制化版本,需要在 Podfile 中增加指定版本的 TRTC 依赖:
pod 'TXLiteAVSDK_TRTC', :podspec => 'https://liteav.sdk.qcloud.com/pod/liteavsdkspec/customer/TXLiteAVSDK_TRTC_shuziren_13.0.20262.podspec'

1. Virtualman.initSDK 参数配置接口

func initSDK(params: VirtualmanParams)
配置 SDK 鉴权参数,不建流。调用后即可使用 listSessionOfUin / listSessionOfProjectid / listSessionOfAssetVK 等查询接口。
注意:
initSDK 仅做参数存储,不会发起网络请求。实际建流请调用 open(completion:)openByAsset(completion:)

VirtualmanParams 参数说明

参数名称
数据类型
参数类型
说明
appkey
String
必要参数
数智人 key,通过交互数智人平台创建的数智人的标识 appkey
accesstoken
String
必要参数
数智人 accessToken,通过交互数智人平台创建的数智人的 accessToken
serverDomain
String
可选参数
服务器域名,不带协议头。默认值 "gw.tvs.qq.com"。私有化部署时填入对应域名。
disableTls
Bool
可选参数
是否禁用 TLS 加密。默认 false(使用 https/wss),设为 true 则使用 http/ws。私有化部署时按需设置。
virtualmanProjectParams
VirtualmanProjectParams?
可选参数
Project 建流所需参数。配置后可调用 open 建流及 listSessionOfProjectid
assetVirtualmanParams
AssetVirtualmanParams?
可选参数
Asset 建流所需参数。配置后可调用 openByAsset 建流及 listSessionOfAssetVK

VirtualmanProjectParams 参数说明

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

AssetVirtualmanParams 参数说明

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

ExtraInfo 参数说明(可选)

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

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

参数名称
数据类型
参数类型
说明
trtcUseExternalApp
Bool?
可选参数
是否使用外部 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 时必填,计算签名时使用的用户名要与上面的 userId 参数的值保持一致),计算方式请参见 实时音视频-用户鉴权
trtcPrivateMapKey
String
可选参数
TRTC 数智人用户权限票据。未开启高级权限控制可不填,默认填 "dummy"。
clientUserId
String
条件必填
客户侧用户 ID。使用外部 TRTC AppId 时必填。
注意:
调用方自身进房用户,不能与数智人的 userId 相同,如果相同会将数智人踢出房间,导致断流。
clientUserSig
String?
条件必填
客户侧用户签名(使用外部 TRTC AppId 时必填),计算方式请参见 实时音视频-用户鉴权
clientPrivateMapKey
String
可选参数
客户侧用户权限票据。未开启高级权限控制可不填,默认填 "dummy"。

代码示例

let params = VirtualmanParams(appkey: Config.APP_KEY, accesstoken: Config.ACCESS_TOKEN)

// 方式一:Project 建流
let projParams = VirtualmanProjectParams(virtualmanProjectId: Config.VIRTUALMAN_PROJECT_ID)
projParams.extraInfo = ExtraInfo(alphaChannelEnable: true)
params.virtualmanProjectParams = projParams

// 方式二:Asset 建流
let assetParams = AssetVirtualmanParams(assetVirtualmanKey: Config.ASSET_VIRTUALMAN_KEY)
assetParams.extraInfo = ExtraInfo(alphaChannelEnable: true)
params.assetVirtualmanParams = assetParams

virtualman.initSDK(params: params)

2. Virtualman.open 建流接口

2.1 通过 ProjectId 建流

func open(completion: @escaping (_ sessionId: String?, _ error: String?) -> Void)
通过数智人项目 ID 建流,ProjectId 从 initSDK 时配置的 VirtualmanProjectParams.virtualmanProjectId 中读取。建流完成后回调 completion:成功时 sessionId 有值、error 为 nil;失败时 sessionId 为 nil、error 包含错误信息。

2.2 通过 AssetVirtualmanKey 建流

func openByAsset(completion: @escaping (_ sessionId: String?, _ error: String?) -> Void)
通过资产数智人 key 建流,assetVirtualmanKey 从 initSDK 时配置的 AssetVirtualmanParams.assetVirtualmanKey 中读取。回调同上。

代码示例

// 方式一:通过 ProjectId 建流
virtualman.open { sessionId, error in
if let sessionId = sessionId {
print("建流成功, sessionId: \\(sessionId)")
} else {
print("建流失败: \\(error ?? "unknown")")
}
}

// 方式二:通过 AssetVirtualmanKey 建流
virtualman.openByAsset { sessionId, error in
if let sessionId = sessionId {
print("建流成功, sessionId: \\(sessionId)")
} else {
print("建流失败: \\(error ?? "unknown")")
}
}

3. Virtualman.chat(_ params: ChatParams) 对话接口

用户发送文本,经平台 AI 处理后,数智人回答并播报。

ChatParams 参数说明

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

代码示例

virtualman.chat(ChatParams(text: "你好", isNewChat: true))

4. Virtualman.sendText(_ params: TextParams) 纯文本驱动接口

直接控制数智人播报指定文本,不经过对话服务。

TextParams 参数说明

参数名称
数据类型
参数类型
说明
text
String
必要参数
纯文本驱动的内容。
reqId
String
可选参数
单次驱动的唯一标识, 32位的 UUID(不包含'-')。默认自动生成。
videoSeiInfo
String?
可选参数
需要在视频流 SEI 中携带的信息,字符串内容为 JSON 格式。

代码示例

virtualman.sendText(TextParams(text: "要播报的文本"))

5. Virtualman.sendStreamText(_ params: StreamTextParams) 流式文本驱动接口

StreamTextParams 参数说明

参数名称
数据类型
参数类型
说明
reqId
String
必要参数
单次驱动的唯一标识。每一段流式文本指定一个32位 UUID 值(不包含'-')。
注意:
每一段流式文本序列指定一个 ReqId,而不是每一次请求指定一个。
text
String
必要参数
流式文本内容,只需要发送增量的文本。每个片包字符串长度限制 2000 字节。
seq
Int
必要参数
流式文本片包序号,序号必须从 1 开始。
isFinal
Bool
可选参数
用于标记本次流式文本驱动是否结束,默认值 false。
注意:
当文本发送完毕后,需要再发送一个 isFinal=true 的驱动指令结束当次流式文本驱动。
isSentence
Bool
可选参数
是否是子句模式,缺省值 false。为 true 服务端不会做重新组句。
isInsertSentence
Bool
可选参数
是否是插入的子句,缺省值 false。为 true 并且是子句模式则表示当前分片需要插播。
videoSeiInfo
String?
可选参数
需要在视频流 SEI 中携带的信息,字符串内容为 JSON 格式。

6. Virtualman.sendAudio(_ params: AudioParams) 音频驱动接口

AudioParams 参数说明

参数名称
数据类型
参数类型
说明
reqId
String
必要参数
单次驱动的唯一标识。每一段音频指定一个32位 UUID 值(不包含'-')。
注意:
每一段流式音频序列指定一个 ReqId,而不是单独一次音频分片请求指定一个。
audio
String
必要参数
音频原始数据的 Data,经 Base64 编码后的字符串。只支持:
- 格式:PCM
- 采样率:16kHz
- 采样位深:16bits
- 声道:单声道
seq
Int
必要参数
音频片包序号,序号必须从 1 开始。
isFinal
Bool
可选参数
用于标记本次音频驱动是否结束,默认值 false。
注意:
当数据包发送完毕后,必须再发送一个 isFinal=true 的空数据包(audio 字段填空串)结束当次音频驱动使数字人回到静默状态。
videoSeiInfo
String?
可选参数
需要在视频流 SEI 中携带的信息,字符串内容为 JSON 格式。

7. Virtualman.stop() 打断播报

在音频驱动、流式文本或非流式文本播报时,调用此接口用于打断当前播报。
支持的打断类型:
音频驱动打断:支持打断 sendAudio() 发起的音频驱动播报
流式文本打断:支持打断 sendStreamText() 发起的流式文本播报
普通文本打断:支持打断 sendText() 发起的文本播报
注意:
需要等到 WebSocket 下行消息返回 TextStart/AudioStart 标记后才可发送打断请求。

8. Virtualman.setSmartActionEnabled(_ value: Bool) 开启智能动作

设置是否开启智能动作,缺省值 false。为 true 并且输入的文本或者话术增强后的文本没有动作标签则会生成智能动作。
注意:
该设置与流绑定,需在 open / openByAsset 建流后调用。close 后再次 open 时需重新设置。

9. Virtualman.setWsDelegate(_ delegate: VirtualmanWsDelegate?) WebSocket 事件监听

用于设置 WebSocket 连接生命周期事件的监听代理,感知连接状态变化。

VirtualmanWsDelegate 协议说明

方法
说明
onWsOpen()
WebSocket 连接已建立,此时可以发送消息。
onWsMessage(_ text: String)
收到 WebSocket 下行消息(JSON 字符串)。
onWsClosed(code: UInt16, reason: String)
WebSocket 连接正常关闭。
onWsFailure(_ error: Error?)
WebSocket 连接异常断开。SDK 会自动尝试重连。
说明:
VirtualmanWsDelegate 所有方法均为可选实现(@objc optional)。

代码示例

class ViewController: UIViewController, VirtualmanWsDelegate {
override func viewDidLoad() {
super.viewDidLoad()
virtualman.setWsDelegate(self)
}

func onWsOpen() {
print("WebSocket 已连接,可以发送消息")
}

func onWsMessage(_ text: String) {
// 处理下行消息
}

func onWsClosed(code: UInt16, reason: String) {
print("WebSocket 已断开,等待自动重连")
}

func onWsFailure(_ error: Error?) {
print("WebSocket 连接失败,等待自动重连")
}
}
WebSocket 下行消息返回数据字段说明参考 长连接下行消息

10. Virtualman.setDelegate(_ delegate: VirtualmanDelegate?) TRTC 事件监听回调

用于设置 TRTC 事件监听代理。

VirtualmanDelegate 协议说明

方法
说明
onRecvSEIMsg(_ userId: String, message: Data)
收到 SEI 消息的回调。详细参考
onFirstVideoFrame(_ userId: String, streamType: Int32, width: Int32, height: Int32)
开始渲染远端用户的首帧画面。详细参考
onError(_ errCode: Int32, errMsg: String?)
错误事件回调。详细参考
onConnectionLost()
TRTC 与云端的连接已经断开。
onTryToReconnect()
TRTC 正在尝试重新连接到云端。
onConnectionRecovery()
TRTC 与云端的连接已经恢复。
onNetworkQuality(localQuality: Int, remoteQuality: [Int])
网络质量回调。详细参考
onStatistics(_ statistics: TRTCStatistics)
网络和性能统计数据回调。详细参考
说明:
VirtualmanDelegate 所有方法均为可选实现(@objc optional)。

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

用于查询当前会话的状态,需要先调用 open 建流。callback 返回值参考 查询会话状态

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

用于查询当前 uin 账号所有进行中的会话,调用 initSDK 后即可使用,无需建流。callback 返回值参考 查询 uin 下的会话列表

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

用于查询当前数智人项目下的所有进行中的会话列表,调用 initSDK 后即可使用,无需建流。projectId 从 initSDK 时传入的 VirtualmanProjectParams.virtualmanProjectId 中读取;未配置时调用会返回错误提示。callback 返回值参考 查询数智人项目下的会话列表
virtualman.listSessionOfProjectid { result in
print(result)
}

14. Virtualman.listSessionOfAssetVK(callback:) 查询个人资产形象下的会话列表

用于查询指定个人资产形象下的所有进行中的会话列表,调用 initSDK 后即可使用,无需建流。assetVirtualmanKey 从 initSDK 时传入的 AssetVirtualmanParams.assetVirtualmanKey 中读取;未配置时调用会返回错误提示。callback 返回值参考查询个人资产形象下的会话列表
virtualman.listSessionOfAssetVK { result in
print(result)
}

15. Virtualman.sdkVersion 获取 SDK 版本号

let version = Virtualman.sdkVersion // 例:"1.1.0"
静态属性,无需实例化即可读取。

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

在页面销毁时或需要的时机调用关闭的方法以关闭数智人流,否则会占用后台资源。
注意:
Virtualman 在 deinit 时会自动调用 close()。但建议在明确不再使用时主动调用,不要依赖 deinit 时机。

SDK 内部重连逻辑

1. open 建流时,如果建流成功在轮询流状态过程遇到网络异常,有重试机制保证流能建立成功。如果超时失败,回调的 error 参数里会有对应的错误信息。
2. WebSocket 自动重连:
SDK 内部监听 TRTC 的 onNetworkQuality 事件(每 2 秒触发一次),当检测到 WebSocket 断开且网络质量正常(1-5)时,自动触发重连。
心跳机制:SDK 每 45 秒发送一次心跳,如果发送失败会自动触发重连。
重连防重入:通过原子操作保证同一时刻只有一个重连请求在进行中。
终止条件:当收到 110014 错误码(流失效)时,停止重连和心跳。此时需要重新调用 open 建流。
3. WebSocket 状态感知:通过 setWsDelegate 设置 VirtualmanWsDelegate,可实时感知连接状态变化(连接/断开/失败),用于 UI 提示用户当前是否可以交互。