Realtime API的客户端事件_大模型服务平台百炼(Model Studio)-阿里云帮助中心

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

相关文档：实时多模态。

客户端事件

session.update

通常来说，客户端在新建立的 websocket链接上发送的第一个事件是 session.update，用以更新本次会话交互的默认配置。

在您建立链接，服务端会及时返回用于此会话的默认输出输入配置。如果您需要更新默认会话配置，我们也推荐您总是在建立链接后即刻发送此事件，

服务端在收到session.update事件后，会进行参数校验，如果参数不合法则返回错误，否则更新服务端侧的会话配置，并返回完整的所有会话配置。

参数	类型	说明
type	string	事件类型，该事件下固定为`session.update`。
event_id	string	本次事件的标识。
session	object	session的配置。
session.modalities	array	模型输出模态设置，支持设置["text"]（仅输出文本）或["text","audio"]（输出音频和文本）。
session.voice	string	模型生成音频的音色，支持："Chelsie", "Serena", "Ethan", "Cherry"。音色效果请参见：支持的音频音色。
session.input_audio_format	string	用户输入音频的格式，当前只支持设置为"pcm16"。
session.output_audio_format	string	模型输出音频的格式，当前只支持设置为"pcm16"。
session.turn_detection	object	语音活动检测(VAD)的配置。设置为 None 表示不启用 VAD，由用户手动发送音频。
session.turn_detection.type	string	服务端VAD类型，目前固定为"server_vad"。
session.turn_detection.threshold	float	VAD检测阈值。建议在嘈杂的环境中增加，在安静的环境中降低。取值越接近-1，噪音被判定为语音的概率越大。取值越接近1，噪音被判定为语音的概率越小。默认为 0.2, 参数范围：[-1.0, 1.0]。
session.turn_detection.silence_duration_ms	integer	检测语音停止的静音持续时间，超过此值后会触发模型响应。默认值为800，参数范围[200, 6000]。

{
    "event_id": "event_ToPZqeobitzUJnt3QqtWg",
    "type": "session.update",
    "session": {
        "modalities": [
            "text",
            "audio"
        ],
        "voice": "Chelsie",
        "input_audio_format": "pcm16",
        "output_audio_format": "pcm16",
        "turn_detection": {
            "type": "server_vad",
            "threshold": 0.5,
            "silence_duration_ms": 800,
            "create_response": true,
            "interrupt_response": true
        }
    }
}

response.create

response.create 事件用于指示服务器创建模型响应。在"server_vad"模式下配置会话时，服务器会自动创建模型响应。

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

参数	类型	说明
type	string	事件类型，该事件下固定为`response.create`。
response	object	Realtime API 的参数。
response.instructions	string	对模型回复方式的指引。
response.modalities	array	模型输出模态设置，支持设置["text"]（仅输出文本）或["text","audio"]（输出音频和文本）。
event_id	string	本次事件的标识。

{
    "type": "response.create",
    "response": {
        "instructions": "Hello",
        "modalities": ["text", "audio"]
    },
    "event_id": "event_1718624400000"
}

response.cancel

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

参数	类型	说明
type	string	事件类型，该事件下固定为`response.cancel`。
event_id	string	本次事件的标识。

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

input_audio_buffer.append

用于将音频字节追加到输入音频缓冲区。音频缓冲区是你可以写入并稍后提交的临时存储。

在"server_vad"模式下，音频缓冲区用于检测语音，服务器决定何时提交。禁用"server_vad"模式后，客户端可以选择每个事件中放置多少音频量，最多放置 15 MiB。例如，从客户端流式处理较小的数据块可以让 VAD 响应更迅速。

与进行其他客户端事件不同，服务器不会向客户端 input_audio_buffer.append 事件发送确认响应。

参数	类型	说明
type	string	事件类型，该事件下固定为`input_audio_buffer.append`。
event_id	string	本次事件的标识。
audio	string	Base64 编码的音频数据。

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

input_audio_buffer.commit

用于提交用户输入音频缓冲区，从而在对话中创建新的用户消息项。如果输入的音频缓冲区为空，此事件将产生错误。处于"server_vad"模式时，客户端不需要发送此事件，服务器会自动提交音频缓冲区。如果没有处于"server_vad"模式，客户端必须提交音频缓冲区才能创建用户消息项。

如果 input_audio_transcription为会话配置了音频转录，系统会转录音频。

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

如果客户端发送过input_image_buffer.append事件，input_audio_buffer.commit 事件会将视频缓存区一起提交。

参数	类型	说明
type	string	事件类型，该事件下固定为`input_audio_buffer.commit`。
event_id	string	本次事件的标识。

{
    "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	string	本次事件的标识。

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

input_image_buffer.append

用于将图片数据添加到视频缓冲区。图片数据可以是本地的图片，或从视频流实时采集的图片数据。

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

图片格式需要为JPG或JPEG，建议传入的图片分辨率为480P或720P，最大1080P；
单张图片大小不大于500KB；
图片数据需要经过Base64编码；
建议您以 2张/秒的频率向服务端发送图片；
您需要先发送音频数据，再发送图片数据；

视频缓存区通过 input_audio_buffer.commit提交。

参数	类型	说明
type	string	事件类型，该事件下固定为`input_image_buffer.append`。
event_id	string	本次事件的标识。
image	string	经过 Base64 编码的图像数据。

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