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 保存在服務端,不放入瀏覽器或移動端應用。
地址與鑒權
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。
會話配置
建立連接並收到 session.created 後發送 session.update。收到 session.updated 確認後再發送輸入;錯誤透過 error 事件處理。
以下示例對應 qwen3.8-omni-flash-realtime,其他版本使用各自事件參考中的配置,不混用欄位層級。
{
"type": "session.update",
"session": {
"modalities": [
"text",
"audio"
],
"voice": "Tina",
"turn_detection": {
"type": "server_vad"
}
}
}
輸入、結果與結束
音訊透過 input_audio_buffer.append 發送;輸入格式、提交條件和圖像輸入限制見用戶端事件。處理服務端事件中的結果、狀態和錯誤,不將連接建立視為業務請求已完成。
自動輪次與 Manual 模式、Function Calling 和 MCP 的時序見交互流程。接收完所需結果後關閉 WebSocket 連接。
錯誤處理
握手失敗時,核對域名、地域、業務空間、API Key、模型名稱及模型開通狀態與權限。連接建立後,根據 error 事件定位問題,並參見錯誤碼。保留事件 ID 便於排查,不以無響應判定協議不支援。