用户指南：实时语音对话（Qwen-Audio-Realtime）。客户端事件和服务端事件的详细说明，请参见客户端事件和服务端事件。
接口地址
WebSocket URL 固定如下，通过查询参数 model 指定要调用的模型名称（将 <model_name> 替换为实际的模型）：
wss://maas.qianwenaiapi.com/api-ws/v1/realtime?model=<model_name>
URL 必须使用 wss:// 协议。Authorization 在请求头中设置，模型通过 URL 查询参数 model 指定。
请求头
请求头中需添加如下信息：
| 参数 | 类型 | 是否必选 | 说明 |
|---|
| Authorization | string | 是 | 鉴权令牌，格式为 Bearer $DASHSCOPE_API_KEY，将 $DASHSCOPE_API_KEY 替换为实际的 API Key。 |
| user-agent | string | 否 | 客户端标识，便于服务端追踪来源。 |
| X-DashScope-WorkSpace | string | 否 | 千问AI平台业务空间 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 连接失败、存储故障 |
按时间顺序，客户端与服务端的交互流程如下：
与 server_vad 模式的主要区别：
按时间顺序，客户端与服务端的交互流程如下：