图像生成大模型
图像生成大模型
文档指南
请输入
- 文档首页
图像生成大模型图像生成大模型实时互动数字人大模型实时互动数字人SDK实时互动数字人 Web SDK-接口文档
复制全文
下载 pdf实时互动数字人 Web SDK-接口文档
文档反馈
问问助手1. 集成指南
1.1 环境要求
- 安全上下文：SDK 需要在 HTTPS 或 localhost 环境下运行（WebRTC 和 Web Audio API 要求）
1.2 安装方式
npm 安装
2. 调用流程
2.1 创建 AvatarSDK 实例
调用数字人服务，你首先需要创建 AvatarSDK 实例，通常而言，一个应用只需要创建一个实例。我们推荐你将这个实例作为单例持有，以确保全局唯一性。SDK 实例负责管理全局信息，如会话认证、日志记录、事件通知等。
认证方式说明
SDK 支持三种认证方式：
推荐使用 WSS Token 认证方式，无需暴露 AK/SK，安全性更高。
认证方式示例
方式一：WSS Token 认证（推荐，短期有效）
不需要 AK/SK，直接使用 WSS Token 进行认证。安全性更高，无需暴露密钥。WSS Token 有过期时间，需要在过期前刷新。WSS Token由后端生成，通过接口下发到客户端。文末我们提供了一个WSS Token生成的示例代码：wss_token_volc.zip，供参考。
方式二：永久 AK/SK 认证（长期有效）
使用长期有效的 AppKey/SecretKey，无需刷新。
方式三：临时 AK/SK + STS Token 认证（短期有效）
使用临时凭证的场景，必须配置 stsToken。三者具有相同的过期时间，需要一起刷新。
Token 刷新说明
对于使用临时 AK/SK + STS Token 或 WSS Token 的场景，凭证具有时效性。为确保后续连接顺利，请在凭证过期前调用对应的更新接口：
- 更新临时 AK/SK + STS：avatarSDK.updateTempAKSK(appKey, secretKey, stsToken)
- 更新 WSS Token：avatarSDK.updateWssToken(wssToken)
更新后的凭证将在下次创建会话时生效，不会影响当前正在进行的会话。
2.2 创建数字人会话
AvatarSession 实例表示一个数字人会话，每个会话对应一个数字人实例。通过 AvatarSDK.createSession() 方法创建会话。
示例代码如下：
其中SC 2.0版本和O 2.0版本的音色皆支持。
2.3 注册会话事件监听
通过事件监听接收会话生命周期及音频事件回调。
示例代码如下：
2.4 启动数字人会话
会话创建成功后，调用 start() 方法开启会话。
示例代码如下：
2.5 设置数字人视图
为会话设置渲染视图容器，会话启动成功后调用 setAvatarVideoCanvas() 方法显示数字人视频流。
示例代码如下：
2.6 语音交互
会话启动成功后，调用 startAudioCapture() 方法开始采集麦克风输入与数字人交互。
示例代码如下：
会话期间，可以调用 stopAudioCapture() 方法停止采集，调用 startAudioCapture() 方法重新开始采集。
2.7 结束会话
不需要时调用 end() 方法结束会话，释放会话资源。
示例代码如下：
3. 接口详情
3.1 AvatarSDKConfig (SDK 实例创建配置)
SDK 初始化配置接口。
对于采用临时 appKey/secretKey 的场景，stsToken 不能为空。
3.2 LogLevel (日志级别)
3.3 Environment (环境类型)
3.4 AvatarSDK (SDK 实例)
SDK 的核心管理类。
构造函数
- 参数: config - AvatarSDKConfig 对象。
- 说明: 最佳实践是在应用程序的生命周期中创建一个实例并将其作为单例使用。初始化后配置对象变为不可变，任何后续修改将不会生效。
createSession()
通过配置创建数字人会话实例。
- 参数: config - AvatarSessionConfig 对象。
- 返回值: 返回一个初始化的 AvatarSession 实例。
3.5 AvatarSessionConfig (会话配置)
数字人会话相关的参数配置。
支持的动作列表
actionList 支持的动作标识符如下：
3.6 AvatarSessionState (会话状态)
状态 | 描述 |
idle | 空闲状态，会话尚未启动 |
starting | 会话正在启动中 |
started | 会话已启动，可进行交互 |
ending | 会话正在结束中 |
ended | 会话已结束 |
3.7 RenderMode (渲染模式)
3.8 AudioFrame (音频帧)
3.9 AvatarSessionEvents (事件类型)
3.10 AvatarSession (会话管理)
管理单个数字人会话的生命周期、渲染和麦克风控制。
属性
start()
启动数字人会话。
- 返回值: Promise，会话启动成功时 resolve。
- 说明: 如果会话已经处于 starting 或 started 状态，此方法将忽略请求。
end()
结束数字人会话。
- 返回值: Promise，会话结束时 resolve。
- 说明: 如果会话已经处于 idle、ending 或 ended 状态，此方法将忽略请求。调用此方法后，会话对象变为无效，不能重新使用。如需启动新会话，需通过 AvatarSDK.createSession() 创建新实例。
setAvatarVideoCanvas()
设置数字人视频渲染画布。
- 参数:
- container (HTMLDivElement): 用于渲染数字人视频的 DOM 容器。传入 null 取消画布。
- mode (RenderMode): 渲染模式。
- 说明: 建议在 start 事件触发后调用此方法。
startAudioCapture()
启动本地麦克风音频采集。
- 返回值: Promise，音频采集启动成功时 resolve。
- 异常: 如果会话未启动或音频采集失败，Promise 将 reject。
- 说明: 音频格式为：单声道、16000Hz 采样率、int16 采样格式、小端字节序。
stopAudioCapture()
停止本地麦克风音频采集。
- 返回值: Promise，音频采集停止成功时 resolve。
4. 错误处理
SDK 使用 AvatarError 类统一处理错误，包含错误码和详细信息。
4.1 AvatarError (错误类)
4.2 错误处理示例
5. 示例代码
- avatar-web-sdk-quick-start-demo_Volc.zip
- wss_token_volc.zip
最近更新时间：2026.08.13 11:21:34
这个页面对您有帮助吗？
有用
有用
无用
无用