Qwen-Audio Realtime WebSocket API参考 - 大模型服务平台百炼

Qwen-Audio Realtime API 通过 WebSocket 协议提供实时语音对话能力。客户端通过发送和接收 JSON 事件与服务端交互，支持语音输入、文本输入、语音活动检测（VAD）、流式语音和文本输出等功能。

用户指南：实时语音对话（Qwen-Audio-Realtime）。客户端事件和服务端事件的详细说明，请参见客户端事件和服务端事件。

重要

阿里云百炼为华北2（北京）地域推出了业务空间专属域名，能够为推理请求提供卓越的性能和更高的稳定性，建议从 dashscope.aliyuncs.com 迁移至 {WorkspaceId}.cn-beijing.maas.aliyuncs.com。

{WorkspaceId}需要替换为真实的Workspace ID。现有域名仍可正常使用。

服务端点

WebSocket URL 固定如下，通过查询参数 model 指定要调用的模型名称（将 <model_name> 替换为实际的模型）：

华北2（北京）

wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>

调用时请将{WorkspaceId}替换为真实的Workspace ID。

重要

URL 必须使用 wss:// 协议。Authorization 在请求头中设置，模型通过 URL 查询参数 model 指定。

请求头

请求头中需添加如下信息：

参数	类型	是否必选	说明
Authorization	string	是	鉴权令牌，格式为 `Bearer <your_api_key>`，将 `<your_api_key>` 替换为实际的 API Key。
user-agent	string	否	客户端标识，便于服务端追踪来源。
X-DashScope-WorkSpace	string	否	阿里云百炼业务空间 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 连接失败、存储故障