通過 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 後再斷開。 |