用户指南：实时语音对话（Qwen-Audio-Realtime）。如需了解事件交互时序，请参见WebSocket API。
session.update
说明：建立连接后，发送此事件更新会话的默认配置。仅包含需要变更的字段，未传字段保持原值。服务端收到后校验参数，若参数不合法则返回错误，若参数合法则应用更改并返回完整配置。
说明
turn_detection 仅在首次发送音频之前（IDLE 状态）允许修改。
|
type string（必选）
事件类型，固定为 session.update。
|
{
"type": "session.update",
"session": {
"modalities": [
"text",
"audio"
],
"voice": "longanqian",
"turn_detection": {
"type": "server_vad",
"threshold": 0.5,
"silence_duration_ms": 800
}
}
}
Function Calling： {
"type": "session.update",
"session": {
"modalities": [
"text",
"audio"
],
"voice": "longanqian",
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "查询指定城市天气",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"title": "城市"
}
},
"required": ["city"]
}
}
}
],
"turn_detection": {
"type": "server_vad",
"threshold": 0.5,
"silence_duration_ms": 800
}
}
}
声纹注册（voiceprint_audio_urls）： {
"type": "session.update",
"session": {
"turn_detection": {
"type": "smart_turn",
"voiceprint_audio_urls": [
"https://example.com/speaker1.pcm",
"https://example.com/speaker2.wav"
]
}
}
}
|
|
session object（可选）
会话配置。
属性
modalities array（可选）
模型输出模态设置，可选值：
-
["text"]
仅输出文本。
-
["audio", "text"]（默认值）
同时输出文本和音频。
voice string（可选）
TTS 音色名称，默认值为 longanqian。支持两种类型，仅可在第一次 session.update 中设置，后续传入将被忽略。
instructions string（可选）
系统指令，用于设定模型的角色身份、回答风格和行为偏好。对整个会话生效。
input_audio_format string（可选）
输入音频格式。当前仅支持 pcm（16kHz 16bit 单声道），为默认值。仅在首次发送音频之前（IDLE 状态）允许修改。
output_audio_format string（可选）
输出音频格式。当前仅支持 pcm（24kHz 16bit 单声道），为默认值。
max_history_turns integer（可选）
允许单次请求的最大历史 QA 轮数。取值范围为 1-50，默认值为 20。
tools array（可选）
Function Calling 工具定义列表。配置后模型可根据用户输入自主决定是否调用工具。
属性
type string（必选）
固定为 function。
function.name string（必选）
工具函数名称。
function.description string（可选）
对工具函数功能的描述，模型据此判断是否调用该工具。
function.parameters object（可选）
对工具函数入参的描述，模型据此提取所需入参。若函数无需入参，可不指定。
属性
type string（必选）
固定为 object。
properties object（可选）
描述各入参的名称、数据类型与说明。
required array（可选）
指定哪些入参为必填项。
turn_detection object|null（可选）
轮次检测配置。设为 null 可切换为 push-to-talk 模式（手动提交音频并触发推理）。若不提供此字段，系统将使用默认参数启用 VAD。
属性
type string（可选）
VAD 类型，可选值：
threshold float（可选）
VAD灵敏度，仅在 server_vad 模式下生效（smart_turn 模式下无效）。值越低，VAD越灵敏，越容易将微弱声音（包括背景噪音）识别为语音；值越高，越不灵敏，需要更清晰、音量更大的语音才能触发。
取值范围为[-1.0, 1.0]，默认值为 0.5。
silence_duration_ms integer（可选）
语音结束后需保持静音的最短时间（毫秒），仅在 server_vad 模式下生效（smart_turn 模式下无效）。超时即触发模型响应。值越低，响应越快，但可能在短暂停顿时误触发。
取值范围为[200, 6000]，默认值为 800。对话场景推荐 400-800。
voiceprint_audio_urls array（可选）
仅在 smart_turn 模式下生效。目标用户预录音频的公网可访问 URL 列表，用于说话人增强。传入后，模型将在双工对话中精准锁定目标说话人，有效忽略旁人声音与背景噪声。最多支持 5 个 URL。音频格式要求：16kHz PCM 或 WAV。
重要
该参数仅在第一次发送 session.update 事件时可配置，后续传入该字段将被忽略。
|
input_audio_buffer.append
说明：追加音频数据到输入缓冲区。应持续、高频发送（如每 20~40 ms 一帧）。此事件无服务端确认回包。
|
type string（必选）
事件类型，固定为 input_audio_buffer.append。
|
{
"type": "input_audio_buffer.append",
"audio": "<base64 编码的音频数据>"
}
|
|
audio string（必选）
Base64 编码的音频数据。
|
input_audio_buffer.commit
说明：仅 push-to-talk 模式。将缓冲区音频提交为一条用户消息。提交后不会自动触发推理，需要发送 response.create 手动触发。
server_vad / smart_turn 模式下此事件被忽略。
|
type string（必选）
事件类型，固定为 input_audio_buffer.commit。
|
{
"type": "input_audio_buffer.commit"
}
|
input_audio_buffer.clear
说明：仅 push-to-talk 模式。清空缓冲区中尚未提交的音频。server_vad / smart_turn 模式下此事件被忽略。服务端以 input_audio_buffer.cleared 事件响应。
|
type string（必选）
事件类型，固定为 input_audio_buffer.clear。
|
{
"type": "input_audio_buffer.clear"
}
|
conversation.item.create
说明：手动向对话上下文插入一条对话项。可用于注入历史上下文、补充文本信息，或写回 Function Calling 的工具执行结果。
说明
若 item.id 已存在于对话中，会返回错误并拒绝创建。
|
type string（必选）
事件类型，固定为 conversation.item.create。
|
注入用户文本消息： {
"type": "conversation.item.create",
"previous_item_id": "item_xxx",
"item": {
"id": "my_item_001",
"type": "message",
"role": "user",
"content": [
{
"type": "input_text",
"text": "请帮我总结一下上次的对话"
}
]
}
}
写回 Function Calling 结果： {
"type": "conversation.item.create",
"item": {
"type": "function_call_output",
"call_id": "call_xxx",
"output": "{\"temperature\":18,\"condition\":\"晴\"}"
}
}
|
|
previous_item_id string（可选）
指定新项插入到哪条对话项之后。不传时追加到对话末尾。
|
|
item object（必选）
要创建的对话项。
属性
id string（可选）
对话项的唯一标识符。不传时由服务端自动生成。若指定的 ID 已存在于对话中，会返回错误。
type string（必选）
对话项类型，可选值：
role string（message 类型必选）
消息角色，可选值：system、user、assistant。
content array（message 类型必选）
消息内容列表。每个元素包含 type 和对应的数据字段。
各 role 支持的 content 类型
system
input_text：系统消息，必填字段 text。
assistant
output_text：助手文本输出，必填字段 text。
call_id string（function_call / function_call_output 类型必选）
函数调用的唯一标识符，用于关联请求和结果。
name string（function_call 类型必选）
要调用的函数名称。
arguments string（function_call 类型必选）
函数调用参数，JSON 字符串格式。
output string（function_call_output 类型必选）
工具执行结果，JSON 字符串格式。
|
conversation.item.retrieve
说明：查询服务端存储的某条对话项。返回的音频类型 content 仅包含转写文本（transcript），不包含原始音频数据。
|
type string（必选）
事件类型，固定为 conversation.item.retrieve。
|
{
"type": "conversation.item.retrieve",
"item_id": "item_xxx"
}
|
|
item_id string（必选）
要查询的对话项 ID。服务端以 conversation.item.retrieved 事件返回查询结果。
|
conversation.item.delete
说明：从对话上下文中删除指定对话项。服务端以 conversation.item.deleted 事件确认。
|
type string（必选）
事件类型，固定为 conversation.item.delete。
|
{
"type": "conversation.item.delete",
"item_id": "item_xxx"
}
|
|
item_id string（必选）
要删除的对话项 ID。
|
response.create
说明：显式触发一次模型推理。各模式下的行为如下：
-
push-to-talk 模式：必须手动调用，需先通过 input_audio_buffer.commit 提交缓冲区音频或写入 function_call_output 后触发。当前有响应正在生成时不允许重复触发。
-
server_vad 模式：通常由服务端自动触发。当前无响应正在生成时，客户端也允许手动调用；有响应正在生成时不允许重复触发。
-
smart_turn 模式：等待用户下一轮输入时允许调用。当前处于一个 turn 内时（收到 input_audio_buffer.speech_started 到 response.done 期间）不允许重复触发。
response 字段可选，用于覆盖本轮推理的会话默认配置。Function Calling 场景下，客户端写入 function_call_output 后也通过该事件触发二轮推理。
说明
server_vad / smart_turn 模式下，手动触发的推理仍可能被新语音打断。
|
type string（必选）
事件类型，固定为 response.create。
|
{
"type": "response.create",
"response": {
"modalities": ["audio", "text"]
}
}
|
|
response object（可选）
用于覆盖本轮推理的会话默认配置。不传时使用当前会话配置。
属性
modalities array（可选）
覆盖本轮的输出模态设置。可选值与 session.update 中的 modalities 一致。
voice string（可选）
覆盖本轮的 TTS 音色。
|
response.cancel
说明：取消当前正在进行的推理。已输出的部分文本会写入 item 链表，服务端返回 status=cancelled 的 response.done。
若当前无进行中的推理，返回错误。
|
type string（必选）
事件类型，固定为 response.cancel。
|
{
"type": "response.cancel"
}
|