AI 助理
文档备案控制台
官方文档
首页 大模型服务平台百炼 模型 API 音频 语音对话 实时语音对话 Qwen-Audio-Realtime 客户端事件

Qwen-Audio 实时语音对话客户端事件

更新时间：
复制 MD 格式
产品详情
我的收藏

Qwen-Audio Realtime API的客户端事件参考。

用户指南：实时语音对话（Qwen-Audio-Realtime）。如需了解事件交互时序，请参见WebSocket API。

session.update

说明：建立连接后，发送此事件更新会话的默认配置。仅包含需要变更的字段，未传字段保持原值。服务端收到后校验参数，若参数不合法则返回错误，若参数合法则应用更改并返回完整配置。

说明turn_detection 仅在首次发送音频之前（IDLE 状态）允许修改。

typestring（必选）

事件类型，固定为 session.update。

sessionobject（可选）

会话配置。

属性

modalitiesarray（可选）

模型输出模态设置，可选值：

  • ["text"]

    仅输出文本。

  • ["audio", "text"]（默认值）

    同时输出文本和音频。

voicestring（可选）

TTS 音色名称。3.1 Plus/Flash 的默认值为 longanqian_v3.1，3.0 Plus/Flash 的默认值为 longanqian。支持系统音色和声音复刻音色，仅可在第一次 session.update 中设置，后续传入将被忽略。

  • 3.1 Plus/Flash 系统音色：可选值包括 longanqian_v3.1 和 3.1 TTS Plus/Flash 音色列表中的全部音色，完整范围请参见音色配置。
  • 3.0 Plus/Flash 系统音色：可选值：longanqian、longanlingxin、longanlingxi、longanxiaoxin、longanlufeng。
  • 声音复刻音色：通过声音复刻 API 创建，将返回的 voice_id 填入此参数。详见音色配置。

连接 qwen-audio-3.1-realtime-plus 或 qwen-audio-3.1-realtime-flash 后，在首次 session.update 中设置音色，例如：

{
    "type": "session.update",
    "session": {
        "voice": "longanqian_v3.1"
    }
}

speech_ratefloat（可选）

模型音频输出语速。取值范围：[0.5, 2.0]，默认值：1.0。值越小，语速越慢；值越大，语速越快。适用于 qwen-audio-3.1-realtime-plus、qwen-audio-3.1-realtime-flash、qwen-audio-3.0-realtime-plus、qwen-audio-3.0-realtime-flash。

enable_speech_emotionboolean（可选）

是否开启情绪增强功能。开启后，回复音色的情绪变化更明显。默认值：true。可选值：true、false。

instructionsstring（可选）

系统指令，用于设定模型的角色身份、回答风格和行为偏好。对整个会话生效。

input_audio_formatstring（可选）

输入音频格式。当前仅支持 pcm（16kHz 16bit 单声道），为默认值。仅在首次发送音频之前（IDLE 状态）允许修改。

output_audio_formatstring（可选）

输出音频格式。当前仅支持 pcm（24kHz 16bit 单声道），为默认值。

input_audio_transcriptionobject（可选）

输入音频转写配置。适用于 qwen-audio-3.1-realtime-plus 和 qwen-audio-3.1-realtime-flash。

属性

languagestring（可选）

输入音频的源语种。

可选值：

  • zh：中文
  • en：英语
  • ja：日语
  • ko：韩语
  • vi：越南语
  • th：泰语
  • id：印尼语
  • ar：阿拉伯语
  • fr：法语
  • de：德语
  • es：西班牙语
  • pt：葡萄牙语
  • ru：俄语
  • it：意大利语

output_audioobject（可选）

输出音频配置。适用于 qwen-audio-3.1-realtime-plus 和 qwen-audio-3.1-realtime-flash。

属性

languagestring（可选）

输出音频的目标语种。

该参数作用于语音合成（TTS）：会尽可能让语音输出使用目标语种，但不保证一定生效，也不会改变模型回复文本的语种。如需模型生成目标语种的文本，请在提示词中明确要求，例如通过 instructions 指定回答语言。

可选值：

  • zh：中文
  • en：英语
  • fr：法语
  • de：德语
  • ja：日语
  • ko：韩语
  • ru：俄语
  • pt：葡萄牙语
  • th：泰语
  • id：印尼语
  • vi：越南语
  • es：西班牙语
  • it：意大利语
  • ar：阿拉伯语

max_history_turnsinteger（可选）

允许单次请求的最大历史 QA 轮数。取值范围为 1-50，默认值为 20。

enable_searchboolean（可选）

适用于 qwen-audio-3.1-realtime-plus、qwen-audio-3.1-realtime-flash、qwen-audio-3.0-realtime-plus 和 qwen-audio-3.0-realtime-flash 模型。

是否开启联网搜索。默认值：false。开启后，模型可根据实时问题自主判断是否进行联网搜索。

qwen-audio-3.1-realtime-flash 支持同时启用 tools 和 enable_search；qwen-audio-3.1-realtime-plus、qwen-audio-3.0-realtime-plus 和 qwen-audio-3.0-realtime-flash 不支持同时启用。

search_optionsobject（可选）

联网搜索配置，仅在 enable_search 为 true 时生效。

属性

enable_sourceboolean（可选）

是否返回搜索结果来源。设置为 true 时返回。

toolsarray（可选）

Function Calling 工具定义列表。配置后模型可根据用户输入自主决定是否调用工具。

属性

typestring（必选）

固定为 function。

function.namestring（必选）

工具函数名称。

function.descriptionstring（可选）

对工具函数功能的描述，模型据此判断是否调用该工具。

function.parametersobject（可选）

对工具函数入参的描述，模型据此提取所需入参。若函数无需入参，可不指定。

属性

typestring（必选）

固定为 object。

propertiesobject（可选）

描述各入参的名称、数据类型与说明。

requiredarray（可选）

指定哪些入参为必填项。

turn_detectionobject|null（可选）

以下轮次检测字段说明适用于 qwen-audio-3.1-realtime-plus、qwen-audio-3.1-realtime-flash、qwen-audio-3.0-realtime-plus 和 qwen-audio-3.0-realtime-flash。

轮次检测配置。设为 null 可切换为 push-to-talk 模式（手动提交音频并触发推理）。若不提供此字段，系统将使用默认参数启用 VAD。

属性

typestring（可选）

VAD 类型，可选值：

  • server_vad（默认值）：基于声学特征检测语音起止，自动触发推理。
  • smart_turn：融合声学感知与语义理解的智能轮次检测，通过声学与语义双重判断轮次边界。无语义的声音（如”嗯”、”啊”）不会触发对话轮或打断模型播报。
  • smart_turn_v2（推荐使用）：在 smart_turn 基础上增强对话上下文理解，更好地判断多人场景中的交互意图。减少旁人说话或无关插话造成的误回复、误打断。

thresholdfloat（可选）

VAD 灵敏度。适用于 server_vad、smart_turn 和 smart_turn_v2。值越低，越容易将微弱声音（包括背景噪音）识别为语音；值越高，越需要清晰、响亮的语音才能触发检测。

取值范围为[-1.0, 1.0]，默认值为 0.5。

silence_duration_msinteger（可选）

语音结束后的最短静音时间（毫秒）。仅在 server_vad 模式下生效（smart_turn / smart_turn_v2 模式下无效）。静音达到该时长后，触发模型响应。值越低，响应越快，但短暂停顿也可能误触发。

取值范围为[200, 6000]，默认值为 800。对话场景推荐 400-800。

voiceprint_audio_urlsarray（可选）

仅在 smart_turn / smart_turn_v2 模式下生效。目标用户预录音频的公网可访问 URL 列表，用于说话人增强。模型通过这些音频在双工对话中锁定目标说话人，忽略旁人声音和背景噪声。最多支持 5 个 URL。音频格式要求：16kHz PCM 或 WAV。

重要该参数仅在第一次发送 session.update 事件时可配置，后续传入该字段将被忽略。

以下示例适用于 qwen-audio-3.1-realtime-plus 和 qwen-audio-3.1-realtime-flash，显式选择系统音色 longanqian_v3.1。

{
    "type": "session.update",
    "session": {
        "modalities": [
            "text",
            "audio"
        ],
        "voice": "longanqian_v3.1",
        "speech_rate": 1.2,
        "turn_detection": {
            "type": "server_vad",
            "threshold": 0.5,
            "silence_duration_ms": 800
        }
    }
}
语言配置（qwen-audio-3.1-realtime-plus / qwen-audio-3.1-realtime-flash）

连接 qwen-audio-3.1-realtime-plus 或 qwen-audio-3.1-realtime-flash 后，可发送以下 session.update 事件，分别将输入音频源语种设置为中文、输出音频目标语种设置为英语。

{
    "type": "session.update",
    "session": {
        "input_audio_transcription": {
            "language": "zh"
        },
        "output_audio": {
            "language": "en"
        }
    }
}

Function Calling：

{
    "type": "session.update",
    "session": {
        "modalities": [
            "text",
            "audio"
        ],
        "voice": "longanqian_v3.1",
        "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_v2",
            "voiceprint_audio_urls": [
                "https://example.com/speaker1.pcm",
                "https://example.com/speaker2.wav"
            ]
        }
    }
}

input_audio_buffer.append

说明：追加音频数据到输入缓冲区。应持续、高频发送（如每 20~40 ms 一帧）。此事件无服务端确认回包。

typestring（必选）

事件类型，固定为 input_audio_buffer.append。

audiostring（必选）

Base64 编码的音频数据。

{
    "type": "input_audio_buffer.append",
    "audio": "<base64 编码的音频数据>"
}

input_audio_buffer.commit

说明：仅 push-to-talk 模式。将缓冲区音频提交为一条用户消息。提交后不会自动触发推理，需要发送 response.create 手动触发。

server_vad / smart_turn / smart_turn_v2 模式下此事件被忽略。

typestring（必选）

事件类型，固定为 input_audio_buffer.commit。

{
    "type": "input_audio_buffer.commit"
}

input_audio_buffer.clear

说明：仅 push-to-talk 模式。清空缓冲区中尚未提交的音频。server_vad / smart_turn / smart_turn_v2 模式下此事件被忽略。服务端以 input_audio_buffer.cleared 事件响应。

typestring（必选）

事件类型，固定为 input_audio_buffer.clear。

{
    "type": "input_audio_buffer.clear"
}

conversation.item.create

说明：手动向对话上下文插入一条对话项。可用于注入历史上下文、补充文本信息，或写回 Function Calling 的工具执行结果。

说明若 item.id 已存在于对话中，会返回错误并拒绝创建。

typestring（必选）

事件类型，固定为 conversation.item.create。

previous_item_idstring（可选）

指定新项插入到哪条对话项之后。不传时追加到对话末尾。

itemobject（必选）

要创建的对话项。

属性

idstring（可选）

对话项的唯一标识符。不传时由服务端自动生成。若指定的 ID 已存在于对话中，会返回错误。

typestring（必选）

对话项类型，可选值：

  • message：普通对话消息。
  • function_call：函数调用请求。通常由服务端生成，客户端也可用于补充历史上下文。
  • function_call_output：工具执行结果。客户端收到 function_call 后执行工具，并用该类型写回结果。

rolestring（message 类型必选）

消息角色，可选值：system、user、assistant。

contentarray（message 类型必选）

消息内容列表。每个元素包含 type 和对应的数据字段。

各 role 支持的 content 类型

system

input_text：系统消息，必填字段 text。

user
  • input_text：用户文本输入，必填字段 text。
  • input_audio：用户音频输入，必填字段 audio（Base64 编码）。
assistant

output_text：助手文本输出，必填字段 text。

call_idstring（function_call / function_call_output 类型必选）

函数调用的唯一标识符，用于关联请求和结果。

namestring（function_call 类型必选）

要调用的函数名称。

argumentsstring（function_call 类型必选）

函数调用参数，JSON 字符串格式。

outputstring（function_call_output 类型必选）

工具执行结果，JSON 字符串格式。

注入用户文本消息：

{
    "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\":\"晴\"}"
    }
}

conversation.item.retrieve

说明：查询服务端存储的某条对话项。返回的音频类型 content 仅包含转写文本（transcript），不包含原始音频数据。

typestring（必选）

事件类型，固定为 conversation.item.retrieve。

item_idstring（必选）

要查询的对话项 ID。服务端以 conversation.item.retrieved 事件返回查询结果。

{
    "type": "conversation.item.retrieve",
    "item_id": "item_xxx"
}

conversation.item.delete

说明：从对话上下文中删除指定对话项。服务端以 conversation.item.deleted 事件确认。

typestring（必选）

事件类型，固定为 conversation.item.delete。

item_idstring（必选）

要删除的对话项 ID。

{
    "type": "conversation.item.delete",
    "item_id": "item_xxx"
}

response.create

说明：显式触发一次模型推理。各模式下的行为如下：

  • push-to-talk 模式：必须手动调用，需先通过 input_audio_buffer.commit 提交缓冲区音频或写入 function_call_output 后触发。当前有响应正在生成时不允许重复触发。
  • server_vad 模式：通常由服务端自动触发。当前无响应正在生成时，客户端也允许手动调用；有响应正在生成时不允许重复触发。
  • smart_turn / smart_turn_v2 模式：等待用户下一轮输入时允许调用。当前处于一个 turn 内时（收到 input_audio_buffer.speech_started 到 response.done 期间）不允许重复触发。

response 字段可选，用于覆盖本轮推理的会话默认配置。Function Calling 场景下，客户端写入 function_call_output 后也通过该事件触发二轮推理。

说明server_vad / smart_turn / smart_turn_v2 模式下，手动触发的推理仍可能被新语音打断。

typestring（必选）

事件类型，固定为 response.create。

responseobject（可选）

用于覆盖本轮推理的会话默认配置。不传时使用当前会话配置。

属性

modalitiesarray（可选）

覆盖本轮的输出模态设置。可选值与 session.update 中的 modalities 一致。

voicestring（可选）

覆盖本轮的 TTS 音色。

{
    "type": "response.create",
    "response": {
        "modalities": ["audio", "text"]
    }
}

response.cancel

说明：取消当前正在进行的推理。已输出的部分文本会写入 item 链表，服务端返回 status=cancelled 的 response.done。

若当前无进行中的推理，返回错误。

typestring（必选）

事件类型，固定为 response.cancel。

{
    "type": "response.cancel"
}
上一篇：模型接入方式下一篇：服务端事件