WebSocket API參考

本文介紹通過WebSocket串連訪問CosyVoice即時語音合成服務的互動流程、服務端點和要求標頭。

DashScope SDK目前僅支援Java和Python。使用其他程式設計語言時，可通過WebSocket串連與服務進行通訊。

服務端點

WebSocket URL固定如下：

wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference

調用時請將{WorkspaceId}替換為真實的Workspace ID。

wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference

調用時請將{WorkspaceId}替換為真實的Workspace ID。

重要

URL 必須使用 wss:// 協議，且固定不變。Authorization 在要求標頭中設定（參見要求標頭）。

重要

阿里雲百鍊為華北2（北京）、新加坡地區推出了業務空間專屬網域名稱，能夠為推理請求提供卓越的效能和更高的穩定性，建議遷移至新網域名稱：

華北2（北京）地區：從 dashscope.aliyuncs.com 遷移至 {WorkspaceId}.cn-beijing.maas.aliyuncs.com
新加坡地區：從 dashscope-intl.aliyuncs.com 遷移至 {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

{WorkspaceId}需要替換為真實的Workspace ID。現有網域名稱仍可正常使用。

要求標頭中需添加如下資訊：

參數	類型	是否必選	說明
Authorization	string	是	鑒權令牌，格式為 `Bearer <your_api_key>`，將 `<your_api_key>` 替換為實際的 API Key。
user-agent	string	否	用戶端標識，便於服務端追蹤來源。
X-DashScope-WorkSpace	string	否	阿里雲百鍊業務空間ID。
X-DashScope-DataInspection	string	否	是否啟用資料合規檢測功能。預設不傳或設為`enable`。如非必要，請勿啟用該參數。

重要

Authorization 鑒權在 WebSocket 握手階段驗證。如果 API Key 無效或缺失，握手將失敗並返回 HTTP 401/403 錯誤。

用戶端事件和服務端事件的詳細說明，請參見用戶端事件和服務端事件。

按時間順序，用戶端與服務端的互動流程如下：

建立串連：用戶端與服務端建立WebSocket串連。
開啟任務：用戶端發送run-task事件以開啟任務。
等待確認：用戶端收到服務端返回的task-started事件，標誌著任務已成功開啟，可以進行後續步驟。
發送待合成文本：

用戶端按順序向服務端發送一個或多個包含待合成文本的continue-task事件，服務端接收到完整語句後返回result-generated事件和音頻流（文本長度有約束，詳情參見continue-task事件中text欄位描述）。
說明
支援多次發送continue-task事件，按順序提交文本片段。服務端接收文本片段後自動進行分句：
- 完整語句立即合成，此時用戶端能夠接收到服務端返回的音頻
- 不完整語句緩衝至完整後合成，語句不完整時服務端不返迴音頻
當發送finish-task事件時，服務端會強制合成所有緩衝內容。
接收音頻：通過 binary 通道接收音頻流
通知服務端結束任務：

待文本發送完畢後，用戶端發送finish-task事件通知服務端結束任務，並繼續接收服務端返回的音頻流。此步驟不可省略，否則可能導致語音資料不完整。
任務結束：

用戶端收到服務端返回的task-finished事件，標誌著任務結束。
關閉串連：用戶端關閉WebSocket串連。

為提高資源使用率，建議複用 WebSocket 串連處理多個任務，而非為每個任務建立新串連。

重要

同一次合成任務中，run-task、所有 continue-task、finish-task 必須使用相同的 task_id。每次發起新任務時產生新的 task_id（如使用 UUID）。使用不同 task_id 會導致音頻錯亂或任務失敗。