通过 AOQ 接入 qwen-audio-3.0-tts-flash,分段发送文本并实时播放合成语音。客户端代码以 Android Java 为例。
方案概述
qwen-audio-3.0-tts-flash 支持 AOQ Inference 事件协议。本教程选择该模型演示通过 AOQ 进行流式语音合成:客户端通过 Data 轨发送 run-task、continue-task 和 finish-task,服务端通过 Audio 轨流式返回音频,并通过 Data 轨返回任务事件。
同一任务可以多次发送 continue-task。完整语句会尽快合成,不完整语句会暂存在服务端,直到后续文本补全或客户端发送 finish-task。该方式适合移动端播报、长文本分段输入和低延迟语音输出。
准备工作
- 开通阿里云百炼,并按获取与配置 API Key。API Key 只保存在业务 AppServer,不要写入客户端代码或提交到代码仓库。
- 根据业务部署地域确认 AOQ Endpoint。地域和接入地址的选择方法请参见选择地域、服务部署范围和接入域名。
- 从SDK 下载获取最新版 AOQ Client SDK。
- 搭建业务 AppServer,并按Token 鉴权实现服务端代理鉴权。每次建立新连接前,客户端都应从 AppServer 获取新的连接凭证。
导入 SDK
根据开发平台导入对应 SDK。后续客户端代码以 Android Java 为例,其他平台使用相同的接口设计和事件流程。本文以 PCM 音频流为例;如果业务选择 Opus,请按 SDK 下载文档导入对应插件。
- Android
- iOS
- HarmonyOS
- Linux (Python)
- 将 AoqClientSdk-release.aar 放入 app/libs,并在 app/build.gradle 中配置依赖和 SDK 支持的 ABI:
- 在 AndroidManifest.xml 中声明以下权限:
- 本场景不需要申请麦克风或摄像头权限。
体验 Demo
阿里云百炼提供适用于 Android 平台的 Demo,可用于快速验证 AOQ 接入效果。下载 APK 并配置 API Key 和 workspaceId 后,即可体验部分模型。
扫描以下二维码下载 Demo:

实现流程
- AppServer 通过 Inference Token 地址获取 qwen-audio-3.0-tts-flash 的 AOQ 连接参数。
- 客户端发布 Data 轨,订阅 Audio 和 Data 轨,并按 run-task 中选择的输出音频格式配置 SDK 解码参数。
- 客户端启动本地播放器并建立 AOQ 连接;连接成功后使用新的 task_id 发送 run-task。
- 收到 task-started 后,按业务节奏发送一个或多个 continue-task 文本片段。
- 所有文本发送完成后发送 finish-task。服务端继续返回剩余音频,最终返回 task-finished。
- 收到 task-finished 后,可在同一 AOQ 连接上使用新的 task_id 开始下一轮合成,或断开连接并销毁引擎。

AppServer 获取 Token
在 AppServer 设置 DASHSCOPE_API_KEY,并使用所选地域的 Endpoint 发送请求。clientIp 为客户端的真实公网 IP;该字段可选,但建议传入,以便服务分配合适的 Relay 接入点。
响应字段 | SDK 字段 |
aoqTokenForClient | AoqConnectConfig.token |
sid | AoqConnectConfig.sid |
clientRelayCertFingerprint | AoqConnectConfig.certFingerprint |
clientRelayEndpoints | AoqConnectConfig.relayEndpoints |
extraInfo.workspaceIdHash | AoqConnectConfig.workspaceIdHash |
实现 Android 客户端
客户端从 AppServer 获取 AoqConnectConfig 后,按以下步骤实现 Android 端流式语音合成。
1. 创建引擎并设置回调
创建 AOQ 单例引擎并注册连接与 Data 轨事件回调。客户需要在连接状态回调中维护可用状态,并把任务事件交给业务状态机。
2. 启动音频播放
TTS 场景不采集麦克风,只需初始化本地播放器。客户可以选择默认使用扬声器或听筒;服务端 Audio 轨音频由 SDK 自动播放。
3. 配置解码器、轨道并建立连接
按 run-task 中选择的输出音频格式配置 SDK 解码参数,然后发布 Data 轨、订阅 Audio 和 Data 轨。以下数值仅为本教程的 PCM 示例配置。AoqConnectConfig 的连接字段由客户根据 AppServer Token 响应填写。
4. 调用 sendDataMsg 发送 run-task 事件
连接成功后为本轮生成新的 UUID task_id,并配置模型、音色、文本类型、音频格式和采样率。其他可选参数请参见客户端事件。
5. 调用 sendDataMsg 发送 continue-task 事件
只能在收到 task-started 后发送 continue-task。同一任务可连续发送多个片段;单次最多 20,000 个字符,累计最多 200,000 个字符。客户应及时发送后续片段或结束任务,不要依赖固定的连接超时秒数。
6. 处理服务端事件
在 onDataMsg 中读取 header.event,维护任务状态并处理失败。result-generated 只表示句子已合成,音频仍通过 Audio 轨返回。完整字段请参见服务端事件。
7. 调用 sendDataMsg 发送 finish-task 事件
发送完全部文本后立即发送 finish-task,以合成服务端缓存的不完整语句,并等待 task-finished。详细规则请参见客户端事件。
8. 断开连接并销毁引擎
不要在发送 finish-task 后立即断开。收到 task-finished 或 task-failed 后,如不再发起下一轮任务,再断开连接并销毁引擎。SDK 会自动关闭音频播放器。
主要服务端事件
事件 | 说明 |
task-started | 任务已启动,可以发送 continue-task |
result-generated | 一个完整语句已合成,对应音频通过 Audio 轨返回 |
task-finished | 所有缓存文本已处理,任务结束 |
task-failed | 任务失败,应读取错误码和错误消息 |
完整示例
以下类接收由 AppServer Token 响应转换完成的 AoqConnectConfig。连接成功后调用 synthesize(text, voice);生产代码还需补充权限、UI 状态和重连逻辑。
运行并验证
- 收到 task-started 后才提交文本。
- 完整语句的音频通过 Audio 轨连续播放;不完整语句在 finish-task 后补充合成。
- 所有音频完成后收到 task-finished;随后可以使用新的 task_id 开始下一轮。
典型场景
同一连接多次合成
收到 task-finished 后,可在同一 AOQ 连接上使用新的 task_id 再次发送 run-task,无需重新申请 Token;如果连接已断开,则必须获取新的连接凭证。
切换音色
每个 run-task 都可以通过 parameters.voice 选择系统音色或有效的 voice_id,因此可在同一连接的不同任务间切换音色。
扬声器或听筒
通过 AoqAudioPlaybackConfig.isDefaultSpeaker 设置默认输出设备;运行中可调用 enableSpeakerphone 切换。
常见问题
问题 | 处理方法 |
连接成功但任务不启动 | 确认通过 Inference Token 地址获取凭证,并检查 run-task 的模型名、task_id 和 Data 轨发布配置。 |
continue-task 被拒绝 | 等待 task-started 后再发送,并确保 run-task、continue-task、finish-task 使用同一个 task_id。 |
任务成功但没有声音 | 确认已订阅 Audio 轨并启动播放器,同时检查 SDK 解码配置是否与 run-task 中选择的输出音频格式一致。 |
末尾文本没有音频 | 所有文本发送完毕后必须发送 finish-task,并等待剩余音频和 task-finished 后再断开。 |