实时API客户端事件及请求参数说明-大模型服务平台百炼-阿里云

本文介绍 Qwen-Omni-Realtime API 的客户端事件。

session.update

客户端建立 WebSocket 连接后，需首先发送该事件，用于更新会话的默认配置。服务端收到 session.update 事件后会校验参数。如果参数不合法，则返回错误；如果参数合法，则更新并返回完整的配置。

type string (必选)

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

{
    "event_id": "event_ToPZqeobitzUJnt3QqtWg",
    "type": "session.update",
    "session": {
        "modalities": [
            "text",
            "audio"
        ],
        "voice": "Chelsie",
        "input_audio_format": "pcm16",
        "output_audio_format": "pcm24",
        "instructions": "你是某五星级酒店的AI客服专员，请准确且友好地解答客户关于房型、设施、价格、预订政策的咨询。请始终以专业和乐于助人的态度回应，杜绝提供未经证实或超出酒店服务范围的信息。",
        "turn_detection": {
            "type": "server_vad",
            "threshold": 0.5,
            "silence_duration_ms": 800
        },
        "seed": 1314,
        "max_tokens": 16384,
        "repetition_penalty": 1.05,
        "presence_penalty": 0.0,
        "top_k": 50,
        "top_p": 1.0,
        "temperature": 0.9
    }
}

session object （可选）

会话配置。

属性

modalities array （可选）

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

["text"]
仅输出文本。
["text","audio"]（默认值）
输出文本与音频。

voice string （可选）

模型生成音频的音色，支持的音色参见音色列表。

默认音色：

Qwen3-Omni-Flash-Realtime：Cherry
Qwen-Omni-Turbo-Realtime：Chelsie

input_audio_format string （可选）

用户输入音频格式，当前仅支持设为pcm16。

output_audio_format string （可选）

输出音频格式，当前仅支持设为pcm24。

smooth_output boolean｜null （可选）

仅在使用 Qwen3-Omni-Flash-Realtime系列模型时生效。

是否开启口语化回复风格。可选值：

true（默认值）：获得口语化的回复；
false：获得更书面化、正式的回复；
难以朗读的内容可能效果不好。
null：模型自动选择口语化或书面化的回复风格。

instructions string （可选）

系统消息，用于设定模型的目标或角色。

turn_detection object （可选）

语音活动检测（VAD）的配置。设置为 null 表示禁用 VAD，由用户手动触发模型响应。若未提供本字段，系统将使用以下默认参数启用 VAD。

属性

type string （可选）

服务端VAD类型，需设置为server_vad。默认值为server_vad。

threshold float （可选）

VAD的灵敏度。值越低，VAD越敏感，更容易将微弱声音（包括背景噪音）识别为语音；值越高，越不敏感，需要更清晰、音量更大的语音才能触发。

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

silence_duration_ms integer （可选）

语音结束后需保持静音的最短时间，超时即触发模型响应。值越低，响应越快，但可能在语音短暂停顿时误触发模型响应。

默认值为800，参数范围[200, 6000]。

temperature float （可选）

采样温度，控制模型生成内容的多样性。

temperature越高，生成的内容更多样，反之，生成的内容更确定。

取值范围： [0, 2)

由于temperature与top_p均可以控制生成内容的多样性，因此建议您只设置其中一个值。

temperature默认值：

qwen3-omni-flash-realtime系列：0.9
qwen-omni-turbo-realtime系列：1.0

top_p float （可选）

核采样的概率阈值，控制模型生成内容的多样性。

top_p越高，生成的内容更多样。反之，生成的内容更确定。

取值范围：（0,1.0]

由于temperature与top_p均可以控制生成内容的多样性，因此建议您只设置其中一个值。

top_p默认值：

qwen3-omni-flash-realtime系列：1.0
qwen-omni-turbo-realtime系列：0.01

top_k integer （可选）

生成过程中采样候选集的大小。例如，取值为50时，仅将单次生成中得分最高的50个Token组成随机采样的候选集。取值越大，生成的随机性越高；取值越小，生成的确定性越高。取值为null或当top_k大于100时，表示不启用top_k策略，此时仅有top_p策略生效。

取值需要大于或等于0。

top_k默认值：

qwen3-omni-flash-realtime系列：50
qwen-omni-turbo-realtime系列：20

max_tokens integer （可选）

本次请求返回的最大 Token 数。

默认值和最大值都是模型的最大输出长度。关于各模型的最大输出长度，请参见模型列表。

max_tokens参数适用于需要限制字数（如生成摘要、关键词）、控制成本或减少响应时间的场景。

repetition_penalty float （可选）

模型生成时连续序列中的重复度。提高repetition_penalty时可以降低模型生成的重复度，1.0表示不做惩罚。没有严格的取值范围，只要大于0即可。

默认值1.05。

presence_penalty float （可选）

控制模型生成内容时的重复度。

默认值为0.0，取值范围：[-2.0, 2.0]。正数会减少重复度，负数会增加重复度。

适用场景：

较高的presence_penalty适用于要求多样性、趣味性或创造性的场景，如创意写作或头脑风暴。

较低的presence_penalty适用于要求一致性或专业术语的场景，如技术文档或其他正式文档。

seed integer （可选）

设置seed参数会使大模型的生成过程更具有确定性，通常用于使模型每次运行的结果一致。

在每次模型调用时传入相同的seed值（由您指定），并保持其他参数不变，模型将尽可能返回相同的结果。

取值范围：0到2³¹−1，默认值-1。

response.create

response.create 事件用于指示服务端创建模型响应。在VAD模式下，服务端会自动创建模型响应，无需发送该事件。

服务端使用 response.created 事件、一个或多个项和内容事件（如 conversation.item.created 和 response.content_part.added）进行响应，最后用一个 response.done 事件表示响应已完成。

type string （必选）

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

{
    "type": "response.create",
    "event_id": "event_1718624400000"
}

response.cancel

客户端发送此事件用以取消正在进行的响应。如果没有任何响应可供取消，服务端将响应错误事件。

type string (必选)

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

{
    "event_id": "event_B4o9RHSTWobB5OQdEHLTo",
    "type": "response.cancel"
}

input_audio_buffer.append

用于将音频字节追加到输入音频缓冲区。

type string (必选)

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

{
    "event_id": "event_B4o9RHSTWobB5OQdEHLTo",
    "type": "input_audio_buffer.append",
    "audio": "UklGR..."
}

audio string (必选)

Base64 编码的音频数据。

input_audio_buffer.commit

用于提交用户输入音频缓冲区，在对话中创建新的用户消息项。如果输入的音频缓冲区为空，服务端会返回错误事件。

VAD 模式：客户端不需要发送此事件，服务端会自动提交音频缓冲区。
Manual 模式：客户端必须提交音频缓冲区才能创建用户消息项。

提交输入音频缓冲区不会从模型创建响应，服务端将使用 input_audio_buffer.committed 事件进行响应。

type string (必选)

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

{
    "event_id": "event_B4o9RHSTWobB5OQdEHLTo",
    "type": "input_audio_buffer.commit"
}

input_audio_buffer.clear

用于清除缓冲区中的音频字节。服务端发送input_audio_buffer.cleared 事件进行响应。

type string (必选)

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

{
    "event_id": "event_xxx",
    "type": "input_audio_buffer.clear"
}

input_image_buffer.append

用于将图像数据添加到图像缓冲区。图像可来自本地文件，或从视频流实时采集。

目前对图片输入有以下限制：

图像格式必须为 JPG 或 JPEG。建议分辨率为 480p 或 720p以获得最佳性能，最高不超过 1080p；
单张图片大小不大于500KB（Base64编码前）；
图片数据需要经过Base64编码；
以不超过每秒 2 张的频率向服务端发送图像；
发送 input_image_buffer.append 事件前，至少发送过一次 input_audio_buffer.append 事件。

type string (必选)

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

{
    "event_id": "event_xxx",
    "type": "input_image_buffer.append",
    "image": "xxx"
}

image string (必选)

Base64 编码的图像数据。