Qwen-Audio Realtime WebSocket API參考 - Alibaba Cloud Model Studio

Qwen-Audio Realtime API 通過 WebSocket 通訊協定提供即時語音對話能力。用戶端通過發送和接收 JSON 事件與服務端互動，支援語音輸入、文本輸入、語音活動檢測（VAD）、流式語音和文本輸出等功能。

使用者指南：即時語音對話（Qwen-Audio-Realtime）。用戶端事件和服務端事件的詳細說明，請參見用戶端事件和服務端事件。

重要

阿里雲百鍊為華北2（北京）地區推出了業務空間專屬網域名稱，能夠為推理請求提供卓越的效能和更高的穩定性，建議從 dashscope.aliyuncs.com 遷移至 {WorkspaceId}.cn-beijing.maas.aliyuncs.com。

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

服務端點

WebSocket URL 固定如下，通過查詢參數 model 指定要調用的模型名稱（將 <model_name> 替換為實際的模型）：

華北2（北京）

wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>

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

重要

URL 必須使用 wss:// 協議。Authorization 在要求標頭中設定，模型通過 URL 查詢參數 model 指定。

要求標頭

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

參數	類型	是否必選	說明
Authorization	string	是	鑒權令牌，格式為 `Bearer <your_api_key>`，將 `<your_api_key>` 替換為實際的 API Key。
user-agent	string	否	用戶端標識，便於服務端追蹤來源。
X-DashScope-WorkSpace	string	否	阿里雲百鍊業務空間 ID。

重要

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

核心概念

Session（會話）：一次 WebSocket 串連對應一個會話，會話內維護配置和對話上下文。
Conversation Item（對話項）：對話中的每條訊息，按鏈表順序組織。
Response（響應）：一次模型推理產生的輸出，包含一個或多個輸出項，輸出項可以是助手訊息，也可以是函數調用。
Function Call（函數調用）：模型請求用戶端執行工具函數時產生的輸出項。用戶端執行完成後通過 function_call_output 寫回結果，再用 response.create 觸發下一輪推理。
Turn Detection（輪次檢測）：控制何時觸發推理。

互動模式

Qwen-Audio Realtime API 支援三種互動模式，通過 session.update 事件的 turn_detection.type 參數配置：

模式	turn_detection.type	描述	適用情境
server_vad	`server_vad`	服務端 VAD 檢測語音起止，自動觸發推理。	免提對話、語音助手
smart_turn	`smart_turn`	融合聲學感知與語義理解判斷輪次邊界，而非僅依賴人聲訊號。無語義的聲音（如”嗯”、”啊”）不會觸發對話輪或打斷模型播報。	低延遲自然對話、高品質打斷
push-to-talk	`null`	用戶端手動提交音頻、手動觸發推理。	按鍵說話、精確控制

互動流程

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

server_vad 模式

服務端對傳入的音頻進行語音活動檢測，檢測到語音結束後自動觸發推理。

啟用方式：配置 session.update 事件的 turn_detection.type 為 server_vad。

一輪完整對話

下圖展示了 server_vad 模式下的典型互動時序：

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

用戶端建立 WebSocket 串連，服務端返回 session.created 事件。
用戶端發送 session.update 配置會話參數，服務端返回 session.updated。
用戶端持續發送 input_audio_buffer.append 追加音頻資料。
服務端檢測到語音開始，返回 input_audio_buffer.speech_started，同時流式返回 ASR 轉寫增量 conversation.item.input_audio_transcription.delta。
服務端檢測到語音結束，返回 input_audio_buffer.speech_stopped、input_audio_buffer.committed 和 conversation.item.created。
服務端自動產生響應，流式返迴文本和音頻增量（response.audio_transcript.delta、response.audio.delta），最終返回 response.done。

使用者打斷

模型播報期間，若 VAD 檢測到使用者開始說話，服務端會取消當前響應（返回 response.done，狀態為 cancelled），隨後開始新一輪語音輸入和響應。下圖展示了使用者打斷的互動時序：

smart_turn 模式

融合聲學感知與語義理解檢測語音結束，可過濾回應語、背景音等無意義聲音。無語義的聲音通過 conversation.item.ambient_audio_transcription.delta 事件透傳，不觸發對話輪。

啟用方式：配置 session.update 事件的 turn_detection.type 為 smart_turn。

一輪完整對話

下圖展示了 smart_turn 模式下的典型互動時序：

與 server_vad 模式的主要區別：

無語義聲音（“嗯”、“啊”等）不會觸發推理，而是通過 ambient_audio_transcription 事件返回。
已判定有效語音可能被撤回（input_audio_buffer.speech_stopped 返回 reason=turn_invalid），此時不觸發推理。
在等待使用者下一輪輸入時，用戶端可顯式發送 response.create 觸發推理。

使用者打斷

與 server_vad 模式的打斷處理基本一致。下圖展示了使用者打斷的互動時序：

無效輪次

已判定有效語音可能被撤回（input_audio_buffer.speech_stopped 返回 reason=turn_invalid），此時不觸發推理，用戶端應繼續發送音頻等待下一輪有效語音。下圖展示了無效輪次的互動時序：

說話人增強配置流程

在 smart_turn 模式下，首次 session.update 中傳入 voiceprint_audio_urls 時，服務端將非同步執行聲紋註冊（載入目標說話人音頻特徵），並通過事件通知註冊進度。聲紋註冊失敗不阻塞正常對話流程。

按時間順序，聲紋註冊的互動流程如下：

用戶端發送 session.update，在 turn_detection.voiceprint_audio_urls 中傳入聲紋音頻 URL，服務端返回 session.created。
服務端立即非同步啟動聲紋註冊，在 session.updated 返回之前先推送 voiceprint_audio_list.in_progress 事件，攜帶本次註冊任務的唯一標識 item_id。
服務端返回 session.updated，確認會話配置已生效。
聲紋註冊完成後，服務端推送終態事件（item_id 與步驟 2 一致）：
- 註冊成功：voiceprint_audio_list.completed。
- 註冊失敗：voiceprint_audio_list.failed，附帶 reason 欄位說明失敗原因（如音頻 URL 無法下載）。

說明

voiceprint_audio_urls 僅在第一次 session.update 時生效，後續傳入該欄位將被忽略。

push-to-talk 模式

用戶端手動控制音頻提交和推理觸發，適用於按鍵說話情境。

啟用方式：配置 session.update 事件的 turn_detection 為 null。

一輪完整對話

下圖展示了 push-to-talk 模式下的典型互動時序：

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

用戶端持續發送 input_audio_buffer.append 追加音頻資料。
使用者說完話後，用戶端發送 input_audio_buffer.commit 提交緩衝區。
用戶端發送 response.create 手動觸發推理。
服務端產生響應，流式返迴文本和音頻。

使用者打斷

用戶端發送 response.cancel 取消當前響應，服務端返回 response.done（狀態為 cancelled，原因為 client_cancelled）。下圖展示了使用者打斷的互動時序：

各模式操作約束

操作	push-to-talk	server_vad	smart_turn
session.update	IDLE 時全部可改；非 IDLE 時部分受限	IDLE 時全部可改；非 IDLE 時部分受限	IDLE 時全部可改；非 IDLE 時部分受限
input_audio_buffer.append	允許	允許	允許
input_audio_buffer.commit	允許	忽略	忽略
input_audio_buffer.clear	允許	忽略	忽略
response.create	允許（需先通過 `input_audio_buffer.commit` 提交緩衝區音頻；當前有響應正在產生時不允許重複觸發）	當前無響應正在產生時允許；有響應正在產生時不允許重複觸發	等待使用者下一輪輸入時允許；當前處於一個 turn 內時（收到 `input_audio_buffer.speech_started` 到 `response.done` 期間）不允許重複觸發
response.cancel	允許（推理中）	允許（推理中）	允許（推理中）
conversation.item.create/delete/retrieve	允許	允許	允許

說明

turn_detection 和 input_audio_format 僅在首次發送音頻之前（IDLE 狀態）允許修改。

錯誤處理

類型	行為	樣本
用戶端錯誤（`invalid_request_error`）	串連保持，僅通知	參數不合法、狀態不允許、item_id 重複
服務端錯誤（`server_error`）	串連終止	LLM 串連失敗、儲存故障