图像生成大模型
图像生成大模型
文档指南
请输入
- 文档首页
图像生成大模型图像生成大模型实时互动数字人大模型实时互动数字人SDK实时互动数字人 Android SDK-接口文档
复制全文
下载 pdf实时互动数字人 Android SDK-接口文档
文档反馈
问问助手0.前置准备
- 您已获取账号的AccessKey、SecretKey，具体步骤，请参见获取AccessKey、SecretKey。
1. 集成指南
1.1 环境要求
使用 数字人 Android SDK 之前，请先确认你的应用满足以下要求：
1.2 组件依赖
1.2.1 添加 Maven 仓库
- 首先在 Android Studio 左上角将工程视图切换为 Project 模式，在项目根目录的 settings.gradle 文件配置 Maven 仓库地址
- 如果你的 Android Gradle Plugin 版本低于 v7.1.0，则应在项目根目录的 build.gradle 文件配置 Maven 仓库地址
两种接入方式：
1.2.2 远程接入（推荐，自动处理依赖）
- 在你 app 模块下的 build.gradle 增加 implementation，version 替换成最新版本：
1.2.3 本地接入（需要手动引入额外依赖）
- 将 SDK AAR 文件放入宿主工程的 libs 目录，例如：
在应用模块中添加本地 AAR 仓库目录，并引入 AAR 文件。
如果你的 AAR 文件名不同，请把 BDAvatarSDK 替换为实际文件名。
- 添加 OkHttp 依赖（替换成你的版本）：
- 添加 RTC 依赖：
- 在项目根目录的 gradle.properties 文件中添加 android.enableJetifier=true，解决兼容性问题
1.3 权限声明
SDK 涉及网络通信与语音采集，因此宿主应用至少需要声明以下权限：
Android 12 及以上补充权限
如果你的应用在 Android 12（API 31）及以上需要配合蓝牙耳机、蓝牙音频设备进行语音交互，需要同时声明：
运行时权限
RECORD_AUDIO 属于重要权限。即使已经在 AndroidManifest.xml 中声明，仍然需要在运行时向用户申请授权
示例：
1.4 混淆说明
如果你以标准方式接入 AAR，SDK 自带的 consumer proguard 规则会自动参与合并，通常你不需要额外配置。如遇问题，可手动添加以下规则：
如果你的应用开启了 R8 / Proguard，但回调收不到、枚举行为异常或初始化后接口表现不稳定，优先检查是否误删了以上 keep 规则。
2. 调用流程
本节以一个典型的实时数字人会话场景为例，演示如何完成从初始化到释放资源的完整接入流程。
2.1 创建 SDK 配置并初始化
SDK 全局入口类为 BDAvatar。你需要先构建 BDAvatarConfig，再调用 BDAvatar.init(...) 完成初始化。
BDAvatar
接口 | 参数 | 说明 |
setAccessKey | accessKey: String? | 设置访问凭证 Access Key，按鉴权方案提供 |
setSecretKey | secretKey: String? | 设置访问凭证 Secret Key，按鉴权方案提供 |
setStsToken | stsToken: String? | 对于采用临时accessKey/secretKey/stsToken的场景，stsToken不能为空 |
setWssToken since v1.0.1 | wssToken: String? | 设置 WebSocket 鉴权 Token。鉴权优先级：accessKey/secretKey 均非空时本地计算签名，否则使用 wssToken |
setEnvironment | environment: BDAvatarEnv | 环境类型（CN：国内环境），默认CN |
setLogDelegate | logDelegate: BDAvatarLogDelegate? | 日志代理，可接入你自己的日志系统 |
setEnableInternalLogs | enable: Boolean | 是否开启内部日志记录，默认关闭 |
putExtra | key: String value: String | 额外参数（选填） |
updateTempAkSk since v1.0.1 | accessKey: String? secretKey: String? stsToken: String? | BDAvatar 实例方法。运行时原子刷新临时 accessKey/secretKey/stsToken 三元组，下一次建连时生效 |
updateWssToken since v1.0.1 | wssToken: String? | BDAvatar 实例方法。运行时刷新 wssToken，下一次建连时生效 |
认证方式
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：updateTempAKSK(accessKey,secretKey,stsToken)
- 更新 WSS Token：updateWssToken(wssToken)
更新后的凭证将在下次创建会话时生效，不会影响当前正在进行的会话。
带LogDelegate的完整示例代码：
2.2 创建数字人会话
BDAvatarSessionConfig.Builder 用于构建单次会话配置。常用字段如下：
avatarImageUrl为数字人形象图片的https URL，推荐的图片比例为 16:9 或者 4:3。speaker 为数字人音色，支持的SC2.0音色，参考：音色列表。其中SC 2.0版本和O 2.0版本的音色皆支持。
BDAvatarSessionConfig.Builder
示例代码：
支持的动作列表
actionList 支持的动作标识符如下：
2.3 设置回调与渲染画布
会话对象创建后，建议先设置 BDAvatarSessionDelegate，再绑定视频渲染视图
BDAvatarSessionDelegate
接口 | 参数 | 说明 |
onSessionStart | session: BDAvatarSession | 会话成功建立，数字人已就绪，可以开始交互 |
onSessionStop | session: BDAvatarSession error: Throwable? | 会话结束 error 为 null 表示正常挂断，非 null 表示异常断开（含错误原因） |
onAudioCaptureStart | session: BDAvatarSession | 麦克风采集已开启（用户侧音频开始上行） |
onAudioCaptureStop | session: BDAvatarSession | 麦克风采集已停止（静音或通话结束） |
onAudioCaptureFail | session: BDAvatarSession error: Throwable | 音频采集发生错误，含失败原因（如权限被拒、设备占用等） |
onAvatarSpeakingChange | session: BDAvatarSession speaking: Boolean reason: String | 数字人说话状态变化 speaking=true 开始说话，false 停止 reason 说明触发原因（如用户打断、正常结束等） 有默认空实现，非必须覆写 |
onRemoteVideoReady | session: BDAvatarSession avatarId: String | 数字人视频流已就绪可渲染 avatarId 标识对应的数字人 有默认空实现，非必须覆写 |
示例代码：
2.4 启动会话并开始语音交互
BDAvatarSession
单次数字人会话管理类。
接口 | 参数 | 说明 |
setDelegate | delegate: BDAvatarSessionDelegate? | 设置会话回调代理，用于接收状态变化与事件通知 |
startSession | 无 | 启动数字人会话 |
finishSession | 无 | 结束数字人会话 |
setAvatarVideoCanvas | view: View mode: RenderMode | 绑定数字人视频画布与渲染模式 |
startAudioCapture | 无 | 开始本地音频采集 |
stopAudioCapture | 无 | 停止本地音频采集 |
isAudioCapturing | 无 | 查询当前是否正在进行音频采集 |
release | 无 | 释放会话相关资源 |
推荐流程如下：
- 调用 session.startSession() 建立会话
- 在 onSessionStart(...) 回调收到成功通知后，申请录音权限，开启麦克风
- 权限授予成功后，再调用 session.startAudioCapture() 开始本地语音采集
示例：
如果你需要暂停与恢复用户语音采集，可以使用：
startAudioCapture() 应在会话已成功启动后调用。过早调用容易触发状态错误，导致录音启动失败。
2.5 结束会话并释放资源
不再需要数字人会话时，请先结束会话：
如果你在页面生命周期中持有会话对象，建议在页面销毁时兜底释放：
3. 常见问题
4.1 会话已经启动，但没有声音或无法采集麦克风
优先检查以下项：
- 是否已经在运行时申请并授予 RECORD_AUDIO
- Android 12 及以上是否需要补充 BLUETOOTH_CONNECT
- 是否在 onSessionStart(...) 之后才调用 startAudioCapture()
- 是否误调用了 stopAudioCapture()
4.2 引入 AAR 后编译通过，但运行时回调异常或接口行为异常
优先检查以下项：
- 是否遗漏了 OkHttp 依赖
- 是否 RTC 依赖版本正确，且未误引入其他不需要的 RTC SDK
- 是否在自定义混淆配置中裁掉了 SDK 的公开接口与回调实现类
- 是否在会话结束后又复用了已经 release() 的对象
4. 最小接入清单
- 将 SDK AAR 放入宿主工程 libs 目录
- 在 Gradle 中引入本地 AAR
- 添加 OkHttp 依赖
- 添加 VolcEngineRTC：3.60.104.300
- 在 AndroidManifest.xml 中声明 INTERNET、RECORD_AUDIO，并按需补充 BLUETOOTH_CONNECT
- 在应用启动阶段调用 BDAvatar.init(...)
- 创建 BDAvatarSessionConfig，通过 BDAvatar.avatarSessionWithConfig(...) 创建会话
- 设置 delegate，绑定画布，启动会话
- 在权限通过后调用 startAudioCapture()
- 结束时调用 finishSession() 和 release()
如需查看更完整的页面接入方式、权限处理和调用时序，请参见随 SDK 一同提供的 Demo 源码工程。
5.附录
SDK资源下载
WSS Token获取示例
最近更新时间：2026.08.13 11:21:51
这个页面对您有帮助吗？
有用
有用
无用
无用