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。
- 长期 API Key 保存在服务端,不放入浏览器或移动端应用。
地址与鉴权
接入地址:wss://maas.qianwenaiapi.com/api-ws/v1/realtime?model=qwen3.8-livetranslate-flash-realtime
其他域名的说明请参见 Python SDK。
在 WebSocket 握手请求头中设置 Authorization: Bearer <API_KEY>。替换实际模型名称;不要把长期 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,开启音频和图片输入。仅发送音频时,可省略 input_modalities 或设为 ["audio"]。
示例还开启实时声音复刻。frequency: once 在会话开始时提取一次输入音色,供后续翻译复用,适合单人场景。详情参见声音复刻。
qwen3.5-livetranslate-flash-realtime 时,按客户端事件中的 3.5 示例构造请求。配置和事件与 3.8 有以下差异:
- 输出模态使用
session中的modalities,可选值和默认值与 3.8 的output_modalities相同。 - 使用顶层
session.voice设置音色。 - 可通过
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 发送;输入格式、提交条件和图像输入限制见客户端事件。处理服务端事件中的结果、状态和错误,不将连接建立视为业务请求已完成。
使用 qwen3.8-livetranslate-flash-realtime 时,按 PCM 24 kHz 播放译音。
实时翻译使用本模型的翻译配置和事件,不套用 Omni 的 response.create 对话流程。输入结束后发送 session.finish,保持连接并继续接收剩余结果,收到 session.finished 后再关闭 WebSocket 连接。需要完整播放译音时,先完成本地播放收尾。具体事件字段见客户端事件和服务端事件。
错误处理
握手失败时,核对域名、业务空间、API Key、模型名称及模型开通状态与权限。连接建立后,根据 error 事件定位问题,并参见错误码。保留事件 ID 便于排查,不以无响应判定协议不支持。