Qwen-Omni-Realtime WebSocket 接入
適用範圍
本文面向 Qwen-Omni-Realtime。示例模型為 qwen3.8-omni-flash-realtime,qwen3.5-omni-plus-realtime、qwen3.5-omni-flash-realtime 的配置參見事件參考。歷史型號 qwen3-omni-flash-realtime-2025-09-15 的參數參見 Python SDK。
- 使用所選地域和業務空間對應的 API Key 與 Workspace ID。
- 新加坡域名:
{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com。 - 長期 API Key 保存在服務端,不放入瀏覽器或移動端應用。
地址與鑒權
WebSocket
wss://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=qwen3.8-omni-flash-realtimeqwen3.8-omni-flash-realtime 必須使用業務空間專屬域名。舊型號可繼續使用原域名:北京為 wss://dashscope.aliyuncs.com,新加坡為 wss://dashscope-intl.aliyuncs.com。詳情參見 Python SDK。
在 WebSocket 握手請求頭中設置 Authorization: Bearer <API_KEY>。替換業務空間 ID 和實際模型名稱;不要把長期 API Key 放入瀏覽器或移動端。
可選的 user-agent 請求頭用於標識用戶端。通用 WebSocket 接入資料還列有 X-DashScope-WorkSpace(業務空間 ID)和 X-DashScope-DataInspection(資料合規檢查配置),這兩個請求頭按模型要求使用。
臨時 API Key 的生成方式和權限說明參見生成臨時 API Key。
以下業務空間位址以 qwen3.5-omni-plus-realtime 為例。
- 華北2(北京)
wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=qwen3.5-omni-plus-realtime - 新加坡
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=qwen3.5-omni-plus-realtime
{WorkspaceId} 替換為所選地域的業務空間 ID。
會話配置
建立連接並收到 session.created 後發送 session.update。收到 session.updated 確認後再發送輸入;錯誤透過 error 事件處理。
以下示例對應 qwen3.8-omni-flash-realtime,其他版本使用各自事件參考中的配置,不混用欄位層級。
輸入、結果與結束
音訊透過 input_audio_buffer.append 發送;輸入格式、提交條件和圖像輸入限制見用戶端事件。處理服務端事件中的結果、狀態和錯誤,不將連接建立視為業務請求已完成。
自動輪次與 Manual 模式、Function Calling 和 MCP 的時序見交互流程。接收完所需結果後關閉 WebSocket 連接。
交互流程
VAD 模式
將用戶端事件事件的session.turn_detection.type 設為"server_vad"以啓用 VAD 模式。在 VAD 模式下,服務端對傳入的音訊進行語音活動檢測,並在檢測到作出響應。此模式適用於用戶端到服務器始終發送音訊的情況,也是當前的預設模式。
- 服務端在檢測到語音開始時發送
input_audio_buffer.speech_started事件。 - 用戶端隨時可以選擇透過發送
input_audio_buffer.append事件將音訊追加到緩衝區。 - 服務端在檢測到語音結束時發送
input_audio_buffer.speech_stopped事件。 - 服務端透過發送
input_audio_buffer.committed事件來提交輸入音訊緩衝區。 - 服務端發送
conversation.item.created事件,其中包含從音訊緩衝區建立的用戶消息項。
Function Calling 流程
在 VAD 模式下,當服務端生成的響應需要用戶端執行 Function Calling 工具時,遵循以下交互流程:
- 服務端在檢測到語音結束並生成響應時,識別到需要呼叫工具。
- 服務端發送
response.function_call_arguments.delta事件,包含工具呼叫參數的增量資料。 - 服務端發送
response.function_call_arguments.done事件,表示工具呼叫參數傳遞完成。 - 用戶端執行工具呼叫並獲取結果。
- 用戶端透過
conversation.item.create事件發送工具呼叫結果。 - 用戶端發送
response.create事件,觸發服務端基於工具呼叫結果生成響應。
Manual 模式
將用戶端事件事件的session.turn_detection 設為 null 以啓用 Manual 模式。此模式下,用戶端透過顯式發送input_audio_buffer.commit 和response.create事件請求服務器響應。適用於按下即說場景,如聊天軟件中的發送語音。
- 用戶端可以透過發送
input_audio_buffer.append事件將音訊追加到緩衝區。 - 用戶端透過發送
input_audio_buffer.commit事件來提交輸入音訊緩衝區。 該提交會在對話中建立一個新的用戶消息項。 - 服務器透過發送
input_audio_buffer.committed事件進行響應。 - 用戶端發送
response.create事件,觸發模型生成最終響應。 - 服務器透過發送
conversation.item.created事件進行響應。
Function Calling 流程
- 用戶端發送
response.create事件後,服務端生成響應並識別到需要呼叫工具。 - 服務端發送
response.function_call_arguments.delta事件,包含工具呼叫參數的增量資料。 - 服務端發送
response.function_call_arguments.done事件,表示工具呼叫參數傳遞完成。 - 用戶端執行工具呼叫並獲取結果。
- 用戶端透過
conversation.item.create事件發送工具呼叫結果。 - 用戶端發送
response.create事件,觸發模型生成最終響應。 - 服務端基於工具呼叫結果生成響應,並透過
response.audio.delta或response.text.delta事件返回給用戶端。
MCP 工具呼叫
以下流程適用於 Qwen3.8-Omni-Flash-Realtime,可與上述 VAD 或 Manual 模式配合使用。
Function Calling 與 MCP 可以在同一會話的 session.tools 中配置,不能同時啓用聯網搜索(enable_search)。百鍊不額外收取 MCP 工具呼叫費,模型推理仍按模型價格計費。
MCP 由服務端執行工具,前述 Function Calling 流程則由用戶端執行工具,兩者的結果回傳方式不同。
工具發現
用戶端透過 session.update 配置 MCP 服務後,由 Realtime 服務異步發現工具,交互流程如下:

opt 表示滿足條件時執行,alt 表示按條件選擇不同分支,par 表示並行處理。
session.updated僅表示 MCP 配置已接受,不表示工具已經可用。mcp_list_tools.in_progress可能早於session.updated到達。- 用戶端可以在工具發現完成前繼續發送音訊或
response.create;但只有發現完成後的 Response 才能使用對應 MCP 工具。 - 工具發現成功時,服務端先發送包含最終工具列表的
conversation.item.created,再發送mcp_list_tools.completed。 - 工具發現失敗時,服務端先發送包含 error 的
conversation.item.created,再發送mcp_list_tools.failed。
MCP 呼叫與續答
模型選擇 MCP 工具後,由 Realtime 服務執行工具呼叫;需要審批時,用戶端先回覆審批結果。交互流程如下:

response.mcp_call.failed,不執行工具,也不會經過 response.mcp_call.in_progress。無需審批或審批透過時,典型事件順序如下:
response.done。其中 response.output 已包含最終 mcp_call 快照:成功項為 completed 並包含 output;失敗項為 failed 並包含 error。
如果需要模型基於 MCP 結果繼續生成回答,用戶端應在收到父 response.done 後發送一次不附帶 MCP 結果的 response.create。
參見用戶端 MCP 工具配置、審批回覆、MCP 服務端事件和MCP 對話項。
使用限制
以下為每個會話的 MCP 預設約束:
| 項目 | 預設值 |
|---|---|
| MCP 服務數 | 8 |
| MCP 工具數 | 128 |
| 工具發現超時 | 30 秒 |
| 審批超時 | 60 秒 |
| 工具執行超時 | 30 秒 |
| 單次上游響應大小 | 2 MB |
| 累計工具結果大小 | 8 MB |
| 累計工具呼叫數 | 256 |
錯誤處理
握手失敗時,核對域名、地域、業務空間、API Key、模型名稱及模型開通狀態與權限。連接建立後,根據 error 事件定位問題,並參見錯誤碼。保留事件 ID 便於排查,不以無響應判定協議不支援。