Qwen-Omni-Realtime API的客户端事件参考。
session.update
建立 WebSocket 连接后，发送此事件更新会话的默认配置。服务端收到 session.update 事件后校验参数，若参数不合法则返回错误，若参数合法则应用更改并返回会话配置。
typestring（必选） 事件类型，固定为 session.update。 | {
"event_id": "event_ToPZqeobitzUJnt3QqtWg",
"type": "session.update",
"session": {
"modalities": [
"text",
"audio"
],
"model": "qwen3.5-omni-flash-realtime",
"voice": "Tina",
"audio": {
"input": {
"format": {
"type": "pcm",
"sample_rate": 16000
}
},
"output": {
"format": {
"type": "wav",
"sample_rate": 24000
}
}
},
"instructions": "你是某五星级酒店的AI客服专员，请准确且友好地解答客户关于房型、设施、价格、预订政策的咨询。请始终以专业和乐于助人的态度回应，杜绝提供未经证实或超出酒店服务范围的信息。",
"turn_detection": {
"type": "server_vad",
"threshold": 0.5,
"silence_duration_ms": 800
},
"enable_search": false,
"tools": [
{
"type": "function",
"function": {
"name": "get_current_weather",
"description": "当你想查询指定城市的天气时非常有用。",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "城市或县区，比如北京市、杭州市、余杭区等。"
}
},
"required": ["location"]
}
}
}
],
"seed": 1314,
"max_tokens": 16384,
"repetition_penalty": 1.05,
"presence_penalty": 0.0,
"top_k": 50,
"top_p": 1.0,
"temperature": 0.9
}
}
|
sessionobject（可选） 会话配置。 Qwen3.8-Omni-Flash-Realtime 更新会话时必须提供 session。全部输入 Token 总数上限为 196608，输入长度计算规则与 Qwen3.5-Omni-Realtime 一致。 属性 modalitiesarray（可选） 模型输出模态设置，可选值：
-
["text"]
仅输出文本。
-
["text","audio"]（默认值）
同时输出文本和音频。
voicestring（可选） 模型生成音频的音色，支持的音色参见音色列表。 默认音色：
- Qwen3.8-Omni-Flash-Realtime：
Tina
- Qwen3.5-Omni-Realtime 系列模型：
Tina
- qwen3-omni-flash-realtime-2025-09-15：
Cherry
audioobject（可选） 输入和输出音频配置。未配置时沿用现有默认行为。 属性 inputobject（可选） 用户输入音频配置。 属性 formatobject（可选） 输入音频的格式和采样率。建议在会话 IDLE 阶段、发送首段音频前完成配置，音频输入开始后不可修改。 属性 typestring（可选） qwen3.5-omni-plus-realtime、qwen3.5-omni-flash-realtime 可选 pcm（默认值，单声道、16 bit 裸 PCM）或 wav（WAV 容器封装的单声道、16 bit PCM）。Qwen3.8-Omni-Flash-Realtime 的多通道输入只能使用 pcm，默认值为 pcm。
sample_rateinteger（可选） qwen3.5-omni-plus-realtime、qwen3.5-omni-flash-realtime 可选 8000、16000（默认值）、24000、48000 Hz。Qwen3.8-Omni-Flash-Realtime 的多通道输入只能使用 16000 Hz，默认值为 16000 Hz。
以下四个字段适用于 Qwen3.8-Omni-Flash-Realtime 的 WebSocket 多通道输入： sample_formatstring（可选） PCM 采样格式，只能为 s16le，默认值为 s16le。 channelsinteger（可选） 输入声道数，仅支持 1（默认值）、2、4。2、4 声道空间音频的输入 Token 数均为普通音频的 2 倍，详见Token 计算。 packingstring（可选） 多通道样本排列方式，只能为 interleaved，默认值为 interleaved。 channel_layoutstring（可选） 按 channels 确定默认值：1 声道为 mono，2 声道为 raw_mic_array，4 声道为 foa_ambix。显式提供时必须与 channels 匹配。 多通道输入必须使用 PCM、16000 Hz、s16le 和 interleaved；字段省略时使用上述默认值，一旦提供则必须符合类型和值约束，不得以 null 代替省略。 outputobject（可选） 模型输出音频配置。 属性 formatobject（可选） 模型输出音频的格式和采样率。建议在会话建立初期、尚未开始音频交互前完成配置。 属性 typestring（可选） qwen3.5-omni-plus-realtime、qwen3.5-omni-flash-realtime 可选 pcm（默认值，单声道、16 bit 裸 PCM）或 wav（WAV 容器封装的单声道、16 bit PCM）。
sample_rateinteger（可选） qwen3.5-omni-plus-realtime、qwen3.5-omni-flash-realtime 可选 8000、16000、24000（默认值）、48000 Hz。
voicestring（可选） Qwen3.8-Omni-Flash-Realtime 的输出音色，默认为 Tina。支持的音色及对应的 voice 参数值见音色列表。session.voice 是兼容旧接入的字段，新接入建议使用 session.audio.output.voice。如果两个字段都设置，输出音频使用 session.audio.output.voice 指定的音色。 input_audio_transcriptionobject｜null（可选） 输入音频转录配置。设为 null 可关闭。 属性 modelstring（必选） 固定为 qwen3-asr-flash-realtime；设置 {"model":"qwen3-asr-flash-realtime"} 可启用输入音频转录，不支持修改模型值。Python SDK 的 enable_input_audio_transcription 是 update_session 方法参数，不是 session.update 的顶层字段。 input_audio_formatstring（可选） 历史兼容字段，新增接入建议使用 audio.input.format 同时配置输入格式和采样率。 output_audio_formatstring（可选） 历史兼容字段，新增接入建议使用 audio.output.format 同时配置输出格式和采样率。 smooth_outputboolean｜null（可选） 仅在使用 qwen3-omni-flash-realtime-2025-09-15 时生效。控制回复风格。可选值：
-
true（默认值）：口语化风格。
-
false：书面化、正式风格。
难以朗读的内容可能效果不好。
-
null：模型自动选择口语化或书面化风格。
instructionsstring（可选） 系统消息，用于设定模型的目标或角色。 turn_detectionobject（可选） 语音活动检测（VAD）配置。设为 null 可禁用 VAD，改为手动触发模型响应。若不提供此字段，系统将使用默认参数启用 VAD。 属性 typestring（可选） VAD 类型，可选值：
server_vad（默认值）：基于声学特征检测语音结束。semantic_vad：基于语义有效性检测语音结束，可过滤回应语、背景音等无意义声音。Qwen3.8-Omni-Flash-Realtime 和 Qwen3.5-Omni-Realtime 系列模型支持。 thresholdfloat（可选） VAD 灵敏度。值越低，VAD 越灵敏，越容易将微弱声音（包括背景噪音）识别为语音；值越高，越不灵敏，需要更清晰、音量更大的语音才能触发。 取值范围：[-1.0, 1.0]，默认值为 0.5。 silence_duration_msinteger（可选） 语音结束后需保持静音的最短时间（毫秒），超时即触发模型响应。值越低，响应越快，但可能在短暂停顿时误触发。 取值范围：[200, 6000]，默认值为 800。 idle_timeout_msinteger（可选） 仅在使用 qwen3.5-omni-plus-realtime 或 qwen3.5-omni-flash-realtime 模型且 VAD 类型为 server_vad 时生效。静默超时时间（毫秒）。服务端完成音频播报且用户持续静默超过该时间（未触发 speech.started）后，模型将主动触发一轮响应，基于当前上下文引导用户继续对话。超时计时从上一条模型响应的音频播放完毕后开始。 取值范围：[5000, 30000]。 enable_searchboolean（可选） 适用于 Qwen3.8-Omni-Flash-Realtime 和 Qwen3.5-Omni-Realtime 系列模型。 是否启用联网搜索。设为 true 启用，默认为 false。启用后，模型可自主判断是否需要联网搜索来回答用户问题。
tools 和 enable_search 不兼容，不可同时开启。
search_optionsobject（可选） 联网搜索选项配置，需先启用 enable_search 才生效。 属性 enable_sourceboolean（可选） 是否在响应中返回搜索结果来源列表。设为 true 启用。 videoobject（可选） Qwen3.8-Omni-Flash-Realtime 的视频输入配置。 属性 inputobject（可选） 视频输入参数。 属性 representation_compactstring（可选） 视频输入表征聚合方式；会话初始默认 none，保留完整的细粒度视频输入表征。normal 聚合表征以降低计算开销，适用于对视觉细节要求不高的场景；相同视频输入的 Token 数为 none 模式的 1/4，详见Token 计算。应在发送首段音频前设置，音频输入开始后不可修改。 toolsarray（可选） 工具定义列表。配置后模型可根据用户输入自主决定是否调用工具。Qwen3.8-Omni-Flash-Realtime 可在同一会话中同时配置 Function Calling 和 MCP 工具，数组元素按 type 区分；tools 与 enable_search 不可同时开启。 Function Calling（type=function） typestring（必选） 固定为 function。 functionobject（必选） 自定义函数定义。 属性 namestring（必选） 工具函数名称，建议与函数名保持一致，例如 get_current_weather 或 get_current_time。 descriptionstring（可选） 对工具函数功能的描述，模型据此判断是否调用该工具。 parametersobject（可选） 对工具函数入参的描述，模型据此提取所需入参。函数无需入参时可不指定。 属性 typestring（必选） 固定为 object。 propertiesobject（可选） 按名称列出函数的入参定义。右侧示例中的 location 是自定义入参名称，其 type 和 description 分别描述数据类型和用途。 requiredarray（可选） 指定哪些入参为必填项。 MCP（type=mcp） 字段标为“必选”表示该 MCP 数组元素出现时必须提供。每次新增或更新 MCP 配置都必须同时提供 server_label 和 server_url，不能只传 server_label 复用已有配置；仅在没有活动 Response 时更新。MCP 连接、工具发现和调用受服务配额及超时限制，详见MCP 调用限制。 typestring（必选） 固定为 mcp。 server_labelstring（必选） MCP Server 的会话内唯一标识，1～64 位，仅允许字母、数字、下划线和连字符。 server_urlstring（必选） MCP Streamable HTTP 地址，必须为公网 HTTPS 443 地址，最长 4096 字符；不得包含用户名、密码或 URL fragment，域名解析结果必须为公网地址。 authorizationstring（可选） 出站 Authorization 值，最长 8192 字符，仅允许可打印 ASCII 字符。 headersobject（可选） 额外出站 HTTP Header，最多 16 个键值对。名称和值均为字符串。名称长 1～128 位，仅允许标准 HTTP Header 名称字符；值最长 8192 字符，仅允许可打印 ASCII 字符。 名称不得使用 mcp-、proxy-、x-forwarded- 前缀，也不得为 host、authorization、connection、content-length、transfer-encoding、accept、content-type、forwarded、cookie、origin、upgrade、te、trailer。 allowed_toolsarray[string]（可选） 工具发现后的白名单过滤。省略表示允许全部，空数组表示不暴露任何工具。每个工具名 1～64 位，仅允许字母、数字、下划线、点和连字符。 require_approvalstring（可选） 工具调用审批策略，可选 always（默认）或 never。 server_url、authorization 和 headers 仅用于服务端连接，不在 session.updated 中回显；客户端不应依赖该事件重建这些敏感配置。
temperaturefloat（可选） 采样温度，控制输出内容的多样性。值越高，输出越多样；值越低，输出越确定。 取值范围：[0, 2)。 由于 temperature 和 top_p 均可控制多样性，建议只设置其中一个。 默认值：
qwen3.8-omni-flash-realtime：0.6- Qwen3.5-Omni-Realtime 系列模型：0.7
qwen3-omni-flash-realtime-2025-09-15：0.9 top_pfloat（可选） 核采样概率阈值，控制输出内容的多样性。值越高，输出越多样；值越低，输出越确定。 取值范围：(0, 1.0]。 由于 temperature 和 top_p 均可控制多样性，建议只设置其中一个。 默认值：
qwen3.8-omni-flash-realtime：0.95- Qwen3.5-Omni-Realtime 系列模型：0.8
qwen3-omni-flash-realtime-2025-09-15：1.0 top_kinteger（可选） 采样候选集大小。例如设为 50 时，每步生成仅从得分最高的 50 个 Token 中采样。值越大，随机性越高；值越小，确定性越高。设为 null 或大于 100 时，禁用 top_k 策略，仅 top_p 生效。 取值需大于或等于 0。 默认值：
qwen3.8-omni-flash-realtime：20- Qwen3.5-Omni-Realtime 系列模型：20
qwen3-omni-flash-realtime-2025-09-15：50 max_tokensinteger（可选） 本次请求返回的最大 Token 数。
max_tokens 不影响模型的生成过程。若模型生成的 Token 数超过 max_tokens，响应将被截断。
qwen3.8-omni-flash-realtime 的取值范围为 [1, 65536]。其他模型的默认值和最大值均为模型的最大输出长度，各模型的最大输出长度参见模型列表。
适用于需要限制输出长度的场景，如生成摘要或关键词、控制成本、缩短响应时间等。 repetition_penaltyfloat（可选） 控制生成内容中连续序列的重复度。值越高，重复惩罚越强；1.0 表示不做惩罚。qwen3.8-omni-flash-realtime 支持取值 0；其他模型取值需大于 0，无严格上限。 默认值：
qwen3.8-omni-flash-realtime：0- Qwen3.5-Omni-Realtime 系列模型：1.0
qwen3-omni-flash-realtime-2025-09-15：1.05 presence_penalty float（可选） 控制生成内容的重复度。 取值范围：[-2.0, 2.0]。正数降低重复度，负数增加重复度。 默认值：
qwen3.8-omni-flash-realtime：1- Qwen3.5-Omni-Realtime 系列模型：1.5
qwen3-omni-flash-realtime-2025-09-15：0.0 适用场景： 较高值适合创意写作、头脑风暴等需要多样性和创造性的场景。 较低值适合技术文档等需要一致性和专业术语的场景。 seedinteger（可选） 提高生成过程的确定性，常用于在相同参数下复现相同结果。 每次调用时传入相同的 seed 值并保持其他参数不变，模型将尽可能返回相同的结果。 取值范围：0 到 231−1，默认值为 -1。 |
response.create
response.create 事件用于指示服务端生成模型响应。VAD 模式下，服务端通常根据语音活动自动开始响应；工具调用后的续答仍按下述流程显式触发。Function Calling 场景中，客户端通过 conversation.item.create 回传工具结果后，发送此事件触发模型续答。Qwen3.8-Omni-Flash-Realtime 的 MCP 工具由服务端执行；如需基于 MCP 结果续答，应在本次 MCP 调用所在 Response 的 response.done 事件到达后发送一次 response.create，不附带 MCP 结果。
服务端以 response.created 事件开始响应，随后发送一个或多个项和内容事件（如 conversation.item.created 和 response.content_part.added），最后以 response.done 事件表示响应完成。
typestring（必选） 事件类型，固定为 response.create。 | {
"type": "response.create",
"event_id": "event_1718624400000"
}
|
response.cancel
客户端发送此事件取消正在进行的响应。若当前无响应可取消，服务端将返回错误事件。
typestring（必选） 事件类型，固定为 response.cancel。 | {
"event_id": "event_B4o9RHSTWobB5OQdEHLTo",
"type": "response.cancel"
}
|
将音频字节追加到输入音频缓冲区。
typestring（必选） 事件类型，固定为 input_audio_buffer.append。 | {
"event_id": "event_B4o9RHSTWobB5OQdEHLTo",
"type": "input_audio_buffer.append",
"audio": "UklGR..."
}
|
audiostring（必选） Base64 编码的音频数据。 |
提交输入音频缓冲区，在对话中创建新的用户消息项。若音频缓冲区为空，服务端将返回错误事件。
提交音频缓冲区不会触发模型响应，服务端将以 input_audio_buffer.committed 事件响应。
若客户端已发送过 input_image_buffer.append 事件，input_audio_buffer.commit 事件将同时提交图像缓冲区。
typestring（必选） 事件类型，固定为 input_audio_buffer.commit。 | {
"event_id": "event_B4o9RHSTWobB5OQdEHLTo",
"type": "input_audio_buffer.commit"
}
|
清除音频缓冲区中的字节。服务端以 input_audio_buffer.cleared 事件响应。
typestring（必选） 事件类型，固定为 input_audio_buffer.clear。 | {
"event_id": "event_xxx",
"type": "input_audio_buffer.clear"
}
|
将图像数据添加到图像缓冲区。图像可来自本地文件，也可从视频流实时采集。
图片输入限制如下：
- 图像格式必须为 JPG 或 JPEG。建议分辨率为 480p 或 720p 以获得最佳性能，最高不超过 1080p。
- 单张图片经Base64编码后不得超过256KB，建议编码前原始图片大小不超过190KB。
- 图片数据需经过 Base64 编码。
- 建议以 1 张/秒的频率向服务端发送图像。
- 发送 input_image_buffer.append 事件前，至少已发送过一次 input_audio_buffer.append 事件。
图像缓冲区与音频缓冲区通过 input_audio_buffer.commit 事件一起提交。
typestring（必选） 事件类型，固定为 input_image_buffer.append。 | {
"event_id": "event_xxx",
"type": "input_image_buffer.append",
"image": "xxx"
}
|
imagestring（必选） Base64 编码的图像数据。 |
conversation.item.create
客户端发送此事件创建对话项，包括 Function Calling 的工具执行结果，以及 Qwen3.8-Omni-Flash-Realtime 的 MCP 审批回复。Function Calling 由客户端执行工具，再以 function_call_output 回传结果并发送 response.create；MCP 工具由服务端执行，审批回复使用 mcp_approval_response，续答时序见审批回复。
event_idstring（可选） 客户端生成的事件 ID，用于日志追踪。 typestring（必选） 事件类型，固定为 conversation.item.create。 | {
"event_id": "event_55099cddb51b4f208cb95d1a994eef80",
"type": "conversation.item.create",
"item": {
"id": "item_2a80d7682b4e473c9c2154da135041e9",
"type": "function_call_output",
"call_id": "call_62c24725afdb4c2680ac54",
"output": "北京今天天气为霾转晴，气温4/-4℃，微风"
}
}
|
itemobject（必选） 要创建的对话项，不能为空。 属性 idstring（可选） 对话项 ID。可预先指定以对齐本地状态；若未提供，由服务端生成。 typestring（必选） function_call_output（Function Calling 结果）或 mcp_approval_response（Qwen3.8-Omni-Flash-Realtime 的 MCP 审批回复）。
call_idstring（条件必选） 仅 function_call_output 必填；取 response.function_call_arguments.done 事件中返回的 call_id。 outputstring（条件必选） 仅 function_call_output 必填；工具函数的执行结果。 approval_request_idstring（条件必选） 仅 mcp_approval_response 必填；必须精确匹配一个尚未处理的 mcp_approval_request 的 item.id。 approveboolean（条件必选） 仅 mcp_approval_response 必填；true 允许执行，false 拒绝且本次调用进入 failed。 |
MCP 审批回复（Qwen3.8-Omni-Flash-Realtime）
当 MCP 配置的 require_approval 为 always 或省略时，服务端可能发送 mcp_approval_request。客户端以本节定义的 conversation.item.create 和 item.type="mcp_approval_response" 回复审批结果。服务端执行 MCP 工具；如需基于结果续答，等待本次 MCP 调用所在 Response 的 response.done 事件，再发送一次不附带 MCP 结果的 response.create。
服务端返回的审批请求 ID、对话项 ID 和事件 ID 均为不透明字符串，不应依赖其长度、前缀或生成规则。
示例：
{
"event_id": "event_client_xxx",
"type": "conversation.item.create",
"item": {
"type": "mcp_approval_response",
"approval_request_id": "opaque_approval_id",
"approve": true
}
}
另请参见： 实时（Qwen-Omni-Realtime） 。
