音频事件参考

实时事件用于在客户端和服务器之间实时音频应用程序中进行通信。 这些事件以 JSON 对象的形式发送到各种终结点，例如 WebSocket 或 WebRTC。 这些事件用于实时管理聊天、音频缓冲区和响应。

可以将音频客户端和服务器事件与以下 API 配合使用：

• Azure OpenAI 实时 API
• Azure AI 语音实时 API

除非另行指定，否则本文档中描述的事件适用于这两个 API。

客户端事件

可以从客户端发送到服务器的客户端事件有九种：

实时客户端事件对话项创建

客户端 conversation.item.create 事件用于向对话的上下文添加新项，包括消息、函数调用和函数调用响应。 此事件可用于填充对话历史记录以及在中途添加新项。 目前，此事件无法填充助手音频消息。

如果成功，服务器将使用 conversation.item.created 事件进行响应，否则将发送 error 事件。

事件结构

{
  "type": "conversation.item.create",
  "previous_item_id": "<previous_item_id>"
}

属性

RealtimeClientEventConversationItemDelete

客户端 conversation.item.delete 事件用于从对话历史记录中删除项。

服务器使用 conversation.item.deleted 事件进行响应，除非对话历史记录中不存在该项（在这种情况下，服务器将以一个错误进行响应）。

事件结构

{
  "type": "conversation.item.delete",
  "item_id": "<item_id>"
}

属性

实时客户端事件会话项检索

客户端 conversation.item.retrieve 事件用于检索服务器在会话历史记录中特定项的表示形式。 例如，此事件可用于在消除噪音和 VAD 后检查用户音频。

如果客户端事件成功，服务器将使用 conversation.item.retrieved 事件进行响应。 如果会话历史记录中不存在该项，服务器将响应错误。

事件结构

{
  "type": "conversation.item.retrieve",
  "item_id": "<item_id>",
  "event_id": "<event_id>"
}

属性

RealtimeClientEventConversationItemTruncate

客户端 conversation.item.truncate 事件用于截断先前助手消息的音频。 服务器生成音频的速度比实时速度快，因此当用户进行中断以截断已发送到客户端但尚未播放的音频时，此事件非常有用。 服务器对音频的理解与客户端的播放是同步的。

截断音频会删除服务器端文本脚本，以确保上下文中不存在用户不知道的文本。

如果客户端事件成功，服务器将使用 conversation.item.truncated 事件进行响应。

事件结构

{
  "type": "conversation.item.truncate",
  "item_id": "<item_id>",
  "content_index": 0,
  "audio_end_ms": 0
}

属性

实时客户端事件输入音频缓冲区追加

客户端 input_audio_buffer.append 事件用于将音频字节追加到输入音频缓冲区。 音频缓冲区是你可以写入并稍后提交的临时存储。

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

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

事件结构

{
  "type": "input_audio_buffer.append",
  "audio": "<audio>"
}

属性

实时客户端事件输入音频缓冲区清除

客户端 input_audio_buffer.clear 事件用于清除缓冲区中的音频字节。

服务器使用 input_audio_buffer.cleared 事件进行响应。

事件结构

{
  "type": "input_audio_buffer.clear"
}

属性

实时客户端事件输入音频缓冲提交

客户端 input_audio_buffer.commit 事件用于提交用户输入音频缓冲区，从而在对话中创建新的用户消息项。 如果 input_audio_transcription 为会话配置了音频，则系统会转录音频。

处于服务器 VAD 模式时，客户端不需要发送此事件，服务器会自动提交音频缓冲区。 如果没有服务器 VAD，客户端必须提交音频缓冲区才能创建用户消息项。 如果输入音频缓冲区为空，则此客户端事件将生成错误。

提交输入音频缓冲区不会从模型创建响应。

服务器使用 input_audio_buffer.committed 事件进行响应。

事件结构

{
  "type": "input_audio_buffer.commit"
}

属性

RealtimeClientEventOutputAudioBufferClear

客户端 output_audio_buffer.clear 事件用于清除缓冲区中的音频字节。

此事件之前应是 response.cancel 客户端事件，以停止生成当前响应。

服务器停止生成音频，并使用事件 output_audio_buffer.cleared 进行响应。

事件结构

{
  "type": "output_audio_buffer.clear"
}

属性

实时客户端事件响应取消

客户端 response.cancel 事件用于取消正在进行的响应。

服务器将使用 response.cancelled 事件进行响应；如果没有任何响应可供取消，服务器将以一个错误进行响应。

事件结构

{
  "type": "response.cancel"
}

属性

实时客户端事件响应创建

客户端 response.create 事件用于指示服务器通过模型推理创建响应。 在服务器 VAD 模式下配置会话时，服务器会自动创建响应。

响应至少包含一个 item，可以包含两个（在这种情况下，第二个是函数调用）。 这些项将追加到对话历史记录中。

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

事件结构

{
  "type": "response.create"
}

属性

实时客户端事件会话更新

客户端 session.update 事件用于更新会话的默认配置。 客户端可以随时发送此事件来更新会话配置，并且，除了语音之外，任何字段都可以随时更新。

仅更新存在的字段。 若要清除字段（例如 instructions），请传递一个空字符串。

服务器使用一个包含完整有效配置的 session.updated 事件进行响应。

事件结构

{
  "type": "session.update"
}

属性

服务器事件

可以从服务器接收的服务器事件有 28 种：

实时服务器事件会话已创建

在创建会话后会立即返回服务器 conversation.created 事件。 每个会话创建一个对话。

事件结构

{
  "type": "conversation.created",
  "conversation": {
    "id": "<id>",
    "object": "<object>"
  }
}

属性

对话属性

实时服务器事件会话项目已创建

创建对话项时，将返回服务器 conversation.item.created 事件。 有几种情况会产生此事件：

• 服务器正在生成响应，如果成功，则生成一个或两个项，其类型为 message（角色 assistant）或 function_call。
• 输入音频缓冲区由客户端或服务器（在 server_vad 模式下）提交。 服务器获取输入音频缓冲区的内容并将其添加到新的用户消息项中。
• 客户端发送了 conversation.item.create 事件，以向对话添加新项。

事件结构

{
  "type": "conversation.item.created",
  "previous_item_id": "<previous_item_id>"
}

属性

实时服务器事件会话项目已检索

检索会话项时，将返回服务器 conversation.item.retrieved 事件。

事件结构

{
  "type": "conversation.item.retrieved",
  "previous_item_id": "<previous_item_id>"
}

属性

实时服务器事件对话项已删除

客户端使用 conversation.item.deleted 事件删除对话中的项时，系统会返回服务器 conversation.item.delete 事件。 此事件用于将服务器对对话历史记录的理解与客户端的视图进行同步。

事件结构

{
  "type": "conversation.item.deleted",
  "item_id": "<item_id>"
}

属性

实时服务器事件会话项目输入音频转录已完成

服务器 conversation.item.input_audio_transcription.completed 事件是写入音频缓冲区的语音听录的结果。

当输入音频缓冲区由客户端或服务器（在 server_vad 模式下）提交时，听录开始。 听录与响应创建异步运行，因此该事件可以发生在响应事件之前或之后。

实时 API 模型能够直接处理音频，因此输入的转录是通过一个单独的语音识别模型（如 whisper-1）进行的独立过程。 因此，脚本可能与模型的解释有所不同，应将其视为粗略指南。

事件结构

{
  "type": "conversation.item.input_audio_transcription.completed",
  "item_id": "<item_id>",
  "content_index": 0,
  "transcript": "<transcript>"
}

属性

实时服务器事件会话项输入音频转录失败

配置了输入音频听录并且用户消息的听录请求失败时，系统会返回服务器 conversation.item.input_audio_transcription.failed 事件。 此事件是与其他 error 事件分开的，以便客户端能够识别相关项。

事件结构

{
  "type": "conversation.item.input_audio_transcription.failed",
  "item_id": "<item_id>",
  "content_index": 0,
  "error": {
    "code": "<code>",
    "message": "<message>",
    "param": "<param>"
  }
}

属性

错误属性

RealtimeServerEventConversationItemTruncated

客户端使用 conversation.item.truncated 事件截断先前的助手音频消息项时，系统会返回服务器 conversation.item.truncate 事件。 此事件用于将服务器对对话历史记录的理解与客户端的播放进行同步。

此事件会截断音频并删除服务器端文本脚本，以确保上下文中不存在用户不知道的文本。

事件结构

{
  "type": "conversation.item.truncated",
  "item_id": "<item_id>",
  "content_index": 0,
  "audio_end_ms": 0
}

属性

实时服务器事件错误

发生错误时，系统会返回服务器 error 事件（可能是客户端问题，也可能是服务器问题）。 大多数错误都是可恢复的，并且会话将保持打开状态。

事件结构

{
  "type": "error",
  "error": {
    "code": "<code>",
    "message": "<message>",
    "param": "<param>",
    "event_id": "<event_id>"
  }
}

属性

错误属性

实时服务器事件输入音频缓冲区已清除

客户端使用 input_audio_buffer.cleared 事件清除输入音频缓冲区时，系统会返回服务器 input_audio_buffer.clear 事件。

事件结构

{
  "type": "input_audio_buffer.cleared"
}

属性

RealtimeServerEventInputAudioBufferCommitted

当输入音频缓冲区由客户端提交或在服务器 VAD 模式下自动提交时，系统会返回服务器 input_audio_buffer.committed 事件。 item_id 属性是创建的用户消息项的 ID。 因此，conversation.item.created 事件也会发送到客户端。

事件结构

{
  "type": "input_audio_buffer.committed",
  "previous_item_id": "<previous_item_id>",
  "item_id": "<item_id>"
}

属性

实时服务器事件输入音频缓冲区语音已开始

在音频缓冲区中检测到语音时，系统会以 input_audio_buffer.speech_started 模式返回服务器 server_vad 事件。 每当音频添加到缓冲区时，此事件都可能发生（除非已检测到语音）。

当语音停止时，客户端应会期望收到 input_audio_buffer.speech_stopped 事件。 item_id 属性是语音停止时创建的用户消息项的 ID。 除非客户端在 VAD 激活期间手动提交音频缓冲区，否则 item_id 也包含在 input_audio_buffer.speech_stopped 事件中。

事件结构

{
  "type": "input_audio_buffer.speech_started",
  "audio_start_ms": 0,
  "item_id": "<item_id>"
}

属性

RealtimeServerEventInputAudioBufferSpeechStopped

input_audio_buffer.speech_stopped 模式下服务器在音频缓冲区中检测到语音结束时，系统会返回服务器 server_vad 事件。

服务器还发送一个 conversation.item.created 事件，其中包含从音频缓冲区创建的用户消息项。

事件结构

{
  "type": "input_audio_buffer.speech_stopped",
  "audio_end_ms": 0,
  "item_id": "<item_id>"
}

属性

实时服务器事件输出音频缓冲区已清除

清除输出音频缓冲区时，将返回服务器 output_audio_buffer.cleared 事件。

当用户中断（input_audio_buffer.speech_started）或客户端发出 output_audio_buffer.clear 事件以手动切断当前音频响应时，就会在 VAD 模式下发生这种情况。

事件结构

{
  "type": "output_audio_buffer.cleared"
}

属性

实时服务器事件输出音频缓冲开始

当服务器开始将音频流式传输到客户端时，会返回 output_audio_buffer.started 事件。 在向响应添加音频内容部件（response.content_part.added）后发出此事件。

事件结构

{
  "type": "output_audio_buffer.started",
  "event_id": "<item_id>",
  "response_id": "<response_id>"
}

属性

实时服务器事件输出音频缓冲已停止

当输出音频缓冲区在服务器上完全耗尽时，将返回服务器 output_audio_buffer.stopped 事件，并且不会再显示任何音频。

在通过 response.done 事件将完整响应数据发送到客户端之后，此事件将被返回。

事件结构

{
  "type": "output_audio_buffer.stopped",
  "audio_end_ms": 0,
  "item_id": "<item_id>"
}

属性

实时服务器事件速率限制已更新

响应开始时发出的服务器 rate_limits.updated 事件，用于指示已更新的速率限制。

创建响应时，某些词元 (Token) 将保留用于输出词元。 此处显示的速率限制反映这种保留，保留随后会在响应完成后相应地得到调整。

事件结构

{
  "type": "rate_limits.updated",
  "rate_limits": [
    {
      "name": "<name>",
      "limit": 0,
      "remaining": 0,
      "reset_seconds": 0
    }
  ]
}

属性

RealtimeServerEventResponseAudioDelta

更新模型生成的音频时，系统将返回服务器 response.audio.delta 事件。

事件结构

{
  "type": "response.audio.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "delta": "<delta>"
}

属性

实时服务器事件响应音频完成

模型生成完音频后，系统将返回服务器 response.audio.done 事件。

当响应中断、不完整或取消时，系统也会返回此事件。

事件结构

{
  "type": "response.audio.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0
}

属性

RealtimeServerEventResponseAudioTranscriptDelta

更新模型生成的音频输出听录时，系统会返回服务器 response.audio_transcript.delta 事件。

事件结构

{
  "type": "response.audio_transcript.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "delta": "<delta>"
}

属性

实时服务器事件响应音频转录完成

模型生成的音频输出听录完成流式处理时，系统会返回服务器 response.audio_transcript.done 事件。

当响应中断、不完整或取消时，系统也会返回此事件。

事件结构

{
  "type": "response.audio_transcript.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "transcript": "<transcript>"
}

属性

实时服务器事件响应内容部件已添加

在响应生成期间将新的内容部分添加到助手消息项时，系统会返回服务器 response.content_part.added 事件。

事件结构

{
  "type": "response.content_part.added",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0
}

属性

部分属性

实时服务器事件响应内容部分完成

当内容部分在助手消息项中完成流式处理时，系统会返回服务器 response.content_part.done 事件。

当响应中断、不完整或取消时，系统也会返回此事件。

事件结构

{
  "type": "response.content_part.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0
}

属性

部分属性

实时服务器事件响应已创建

创建新响应时，系统会返回服务器 response.created 事件。 这是响应创建的第一个事件，其中响应处于初始状态 in_progress。

事件结构

{
  "type": "response.created"
}

属性

实时服务器事件响应完成

当响应完成流式处理时，系统会返回服务器 response.done 事件。 无论最终状态如何，始终发出此事件。 response.done 事件中包含的响应对象包括响应中的所有输出项，但省略原始音频数据。

事件结构

{
  "type": "response.done"
}

属性

RealtimeServerEventResponseFunctionCallArgumentsDelta

更新模型生成的函数调用参数时，系统会返回服务器 response.function_call_arguments.delta 事件。

事件结构

{
  "type": "response.function_call_arguments.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "call_id": "<call_id>",
  "delta": "<delta>"
}

属性

实时服务器事件响应函数调用参数完成

模型生成的函数调用参数完成流式处理时，系统会返回服务器 response.function_call_arguments.done 事件。

当响应中断、不完整或取消时，系统也会返回此事件。

事件结构

{
  "type": "response.function_call_arguments.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "call_id": "<call_id>",
  "arguments": "<arguments>"
}

属性

RealtimeServerEventResponseOutputItemAdded

在响应生成过程中创建新项时，系统会返回服务器 response.output_item.added 事件。

事件结构

{
  "type": "response.output_item.added",
  "response_id": "<response_id>",
  "output_index": 0
}

属性

实时服务器事件响应输出项目完成

当项完成流式处理时，系统会返回服务器 response.output_item.done 事件。

当响应中断、不完整或取消时，系统也会返回此事件。

事件结构

{
  "type": "response.output_item.done",
  "response_id": "<response_id>",
  "output_index": 0
}

属性

RealtimeServerEventResponseTextDelta

更新模型生成的文本时，系统会返回服务器 response.text.delta 事件。 文本对应于助手消息项的 text 内容部分。

事件结构

{
  "type": "response.text.delta",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "delta": "<delta>"
}

属性

实时服务器事件响应文本完成

当模型生成的文本完成流式处理时，系统会返回服务器 response.text.done 事件。 文本对应于助手消息项的 text 内容部分。

当响应中断、不完整或取消时，系统也会返回此事件。

事件结构

{
  "type": "response.text.done",
  "response_id": "<response_id>",
  "item_id": "<item_id>",
  "output_index": 0,
  "content_index": 0,
  "text": "<text>"
}

属性

实时服务器事件会话已创建

当你建立与实时 API 的新连接时，服务器 session.created 事件是第一个服务器事件。 此事件创建并返回具有默认会话配置的新会话。

事件结构

{
  "type": "session.created"
}

属性

实时服务器事件会话更新

客户端更新会话时，系统会返回服务器 session.updated 事件。 如果出现错误，服务器将改为发送 error 事件。

事件结构

{
  "type": "session.updated"
}

属性

组件

实时音频格式

允许的值：

• pcm16
• g711_ulaw
• g711_alaw

实时音频输入转录模型

允许的值：

• whisper-1
• gpt-4o-transcribe
• gpt-4o-mini-transcribe
• gpt-4o-transcribe-diarize

实时音频输入转录设置

实时音频输入音频噪声降低设置 (RealtimeAudioInputAudioNoiseReductionSettings)

RealtimeClientEvent

实时客户端事件类型

允许的值：

• session.update
• input_audio_buffer.append
• input_audio_buffer.commit
• input_audio_buffer.clear
• conversation.item.create
• conversation.item.delete
• conversation.item.truncate
• response.create
• response.cancel

实时内容部分

实时内容部分类型

允许的值：

• input_text
• input_audio
• text
• audio

实时对话项目基础 (RealtimeConversationItemBase)

要添加到对话中的项。

下表介绍了所有 RealtimeConversationItem 属性。 每个事件适用的属性取决于 RealtimeItemType。

实时对话请求项

使用 RealtimeConversationRequestItem 对象通过 conversation.item.create 事件在对话中创建新项。

实时对话响应项 (RealtimeConversationResponseItem)

RealtimeConversationResponseItem 对象表示对话中的项。 它用于某些服务器事件，例如：

• 对话项目已创建
• 响应.output_item.已添加
• response.output_item.done
• response.created（通过 response 属性类型 RealtimeResponse）
• response.done（通过 response 属性类型 RealtimeResponse）

RealtimeFunctionTool

实时终结点使用的函数工具的定义。

实时项目状态

允许的值：

• in_progress
• completed
• incomplete

实时项目类型

允许的值：

• message
• function_call
• function_call_output

RealtimeMessageRole

允许的值：

• system
• user
• assistant

RealtimeRequestAssistantMessageItem 实时请求助手消息项

RealtimeRequestAudioContentPart

实时请求函数调用条目

实时请求函数调用输出项

RealtimeRequestMessageItem

实时请求消息引用项

RealtimeRequestSession

如果要通过 RealtimeRequestSession 事件更新会话配置，请使用 对象。

RealtimeRequestSystemMessageItem

实时请求文本内容部分

RealtimeRequestUserMessageItem

RealtimeResponse

实时响应音频内容部分

RealtimeResponseBase

响应资源。

实时响应函数调用项

实时响应函数调用输出项

RealtimeResponseMessageItem

实时响应选项

RealtimeResponseSession

RealtimeResponseSession 对象表示实时 API 中的会话。 它用于某些服务器事件，例如：

• session.created
• session.updated

实时响应状态

允许的值：

• in_progress
• completed
• cancelled
• incomplete
• failed

实时响应状态详情

RealtimeResponseTextContentPart

实时服务器事件

RealtimeServerEventRateLimitsUpdatedRateLimitsItem

实时服务器事件类型

允许的值：

• session.created
• session.updated
• conversation.created
• conversation.item.created
• conversation.item.deleted
• conversation.item.truncated
• response.created
• response.done
• rate_limits.updated
• response.output_item.added
• response.output_item.done
• response.content_part.added
• response.content_part.done
• response.audio.delta
• response.audio.done
• response.audio_transcript.delta
• response.audio_transcript.done
• response.text.delta
• response.text.done
• response.function_call_arguments.delta
• response.function_call_arguments.done
• input_audio_buffer.speech_started
• input_audio_buffer.speech_stopped
• conversation.item.input_audio_transcription.completed
• conversation.item.input_audio_transcription.failed
• input_audio_buffer.committed
• input_audio_buffer.cleared
• error

RealtimeServerVadTurnDetection

RealtimeSessionBase

实时会话对象配置。

RealtimeTool

实时工具定义的基准表示形式。

RealtimeToolChoice

实时 tool_choice 参数的可用表示形式的组合集，包含“auto”等字符串字面量选项和对已定义工具的结构化引用。

RealtimeToolChoiceFunctionObject

实时 tool_choice（用于选择命名函数工具）的表示形式。

RealtimeToolChoiceLiteral

实时终结点的一组可用的模式级字符串字面量 tool_choice 选项。

允许的值：

• auto
• none
• required

RealtimeToolChoiceObject

实时 tool_choice（用于选择命名工具）的基准表示形式。

实时工具类型

实时工具支持的工具类型鉴别器。 目前仅支持“function”工具。

允许的值：

• function

实时转向检测

实时转向检测类型

允许的值：

• semantic_vad - 语义 VAD 根据用户说出的字词来检测用户何时结束讲话。 输入音频是根据用户完成说话的概率评分的。 当概率较低时，模型将等待超时时间。 如果概率较高，则无需等待。
• server_vad - 服务器对来自客户端的用户音频进行评估。 检测到语音结束时，服务器会自动使用该音频在适用的对话上启动响应生成。

RealtimeVoice

允许的值：

• alloy
• ash
• ballad
• coral
• echo
• sage
• shimmer
• verse

相关内容

• 开始使用实时 API 快速入门。
• 详细了解如何使用实时 API。