Qwen-LiveTranslate-Realtime WebSocket 接入
適用範圍
本文面向 Qwen-LiveTranslate-Realtime,示例模型為 qwen3.8-livetranslate-flash-realtime。系列指南還列有 qwen3.5-livetranslate-flash-realtime 和快照版 qwen3.5-livetranslate-flash-realtime-2026-05-19。3.8 與 3.5 的配置和事件欄位不同,按所選型號查閱事件參考。
- 使用所選地域和業務空間對應的 API Key 與 Workspace ID。
- 北京域名:
{WorkspaceId}.cn-beijing.maas.aliyuncs.com;新加坡域名:{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com。 - 長期 API Key 保存在服務端,不放入瀏覽器或移動端應用。
地址與鑒權
wss://WorkspaceId.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=qwen3.8-livetranslate-flash-realtimewss://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=qwen3.8-livetranslate-flash-realtime其他域名的說明請參見 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-livetranslate-flash-realtime,其他版本使用各自事件參考中的配置,不混用欄位層級。示例開啓即時聲音複刻,frequency: once 在會話開始時提取一次輸入音色並在後續復用,適合單人場景。詳情請參見聲音複刻。
{
"type": "session.update",
"session": {
"output_modalities": [
"text",
"audio"
],
"audio": {
"input": {
"turn_detection": {
"type": "speaker_detection",
"threshold": 0.5
}
}
},
"voice": "default",
"enable_voice_clone": true,
"voice_clone_options": {
"frequency": "once"
},
"translation": {
"language": "en",
"corpus": {
"phrases": {
"人工智能": "Artificial Intelligence",
"机器学习": "Machine Learning"
}
}
}
}
}
使用 qwen3.5-livetranslate-flash-realtime 時,配置和事件與上述 3.8 示例不同:
- 輸出模態使用
session中的modalities,可選值和預設值與 3.8 的output_modalities相同。 - 可透過
session的input_audio_transcription對象中的language指定源語種;省略時自動識別。 - 原文識別增量使用
conversation.item.input_audio_transcription.text;3.8 使用conversation.item.input_audio_transcription.delta。 - 僅輸出文本時,3.5 透過
response.text.text返回譯文增量,3.8 使用response.text.delta。輸出文本和音訊時,3.5 透過response.audio_transcript.text返回譯文增量,3.8 使用response.audio_transcript.delta。
完整欄位、預設值和事件參見用戶端事件、服務端事件和即時語音翻譯指南。
輸入、結果與結束
音訊透過 input_audio_buffer.append 發送;輸入格式、提交條件和圖像輸入限制見用戶端事件。處理服務端事件中的結果、狀態和錯誤,不將連接建立視為業務請求已完成。
即時翻譯使用本模型的翻譯配置和事件,不套用 Omni 的 response.create 對話流程。輸入結束後發送 session.finish,保持連接並繼續接收剩餘結果,收到 session.finished 後再關閉 WebSocket 連接。需要完整播放譯音時,先完成本地播放收尾。具體事件欄位見用戶端事件和服務端事件。
錯誤處理
握手失敗時,核對域名、地域、業務空間、API Key、模型名稱及模型開通狀態與權限。連接建立後,根據 error 事件定位問題,並參見錯誤碼。保留事件 ID 便於排查,不以無響應判定協議不支援。