OpenAI Realtime 客户端事件

Realtime 客户端事件

OpenAI Realtime WebSocket 服务端接受客户端发送的以下事件。

session.update

发送此事件更新会话配置。 客户端可随时发送此事件更新字段， 但 voice 和 model 除外；voice 仅在尚未有任何音频输出时可更新。

服务端收到 session.update 后，会响应 session.updated，展示完整的生效配置。 仅更新 session.update 中实际出现的字段。清空 instructions 等字段时，传空字符串；清空 tools 等字段时，传空数组。 清空 turn_detection 等字段时，传 null。

要关闭输入音频降噪，发送以下 Realtime 事件：

{"type":"session.update","session":{"type":"realtime","audio":{"input":{"noise_reduction":null}}}}

对于转录会话，在 session 中使用 "type":"transcription"。 更新中省略 audio.input.noise_reduction 会保留当前设置。

结构定义

模式名称：RealtimeClientEventSessionUpdate

• session: RealtimeSessionCreateRequest or RealtimeTranscriptionSessionCreateRequest

更新 Realtime 会话，选择 realtime 会话或转录会话。

• RealtimeSessionCreateRequest object { type, audio, include, 11 more }

Realtime 会话对象配置。

• type: "realtime"

要创建的会话类型。对于 Realtime API，固定为 realtime。

• "realtime"

• audio: optional RealtimeAudioConfig

输入和输出音频的配置。

• input: optional RealtimeAudioConfigInput

• format: optional RealtimeAudioFormats

输入音频格式。

• PCMAudio object { rate, type }

PCM 音频格式，仅支持 24kHz 采样率。

• rate: optional 24000

音频采样率，固定为 24000。

• 24000

• type: optional "audio/pcm"

音频格式，固定为 audio/pcm。

• "audio/pcm"

• PCMUAudio object { type }

G.711 μ-law 格式。

• type: optional "audio/pcmu"

音频格式，固定为 audio/pcmu。

• "audio/pcmu"

• PCMAAudio object { type }

G.711 A-law 格式。

• type: optional "audio/pcma"

音频格式，固定为 audio/pcma。

• "audio/pcma"

• noise_reduction: optional object { strength, type }

输入音频降噪配置，设为 null 可关闭。 降噪会在音频发送给 VAD 和模型前，对加入输入缓冲区的音频进行过滤。 过滤音频能改善模型对输入的感知，提高 VAD 和话轮检测的准确率、减少误报，并改善模型表现。

• strength: optional number (default: 1)

输入噪声抑制强度，值越大抑制越强。 首次启用降噪时默认为 1。在会话更新中省略 strength 会保留当前强度。

minimum: 0, maximum: 1

• type: optional NoiseReductionType

降噪类型。near_field 适用于耳机等近讲麦克风，far_field 适用于笔记本或会议室等远场麦克风。

• "near_field"

• "far_field"

• transcription: optional AudioTranscription

输入音频转录配置，默认关闭，开启后可设为 null 再次关闭。模型直接处理音频，输入音频转录不是模型的原生处理过程。转录通过 /audio/transcriptions 接口异步进行，应视为输入音频内容的参考，不能当作模型实际听到内容的精确表示。客户端可以选择设置转录语言和提示词，为转录服务提供额外引导。

• delay: optional "minimal" or "low" or "medium" or 2 more

控制模型在输出转录文本前等待的时间。 较高值可能提高转录准确率，但会增加延迟。 仅在正式版 Realtime 会话使用 gpt-realtime-whisper 时支持。

• "minimal"

• "low"

• "medium"

• "high"

• "xhigh"

• keywords: optional array of string

用于引导输入音频转录的词语或短语，gpt-transcribe 和 gpt-live-transcribe 支持。

• language: optional string

输入音频的语言。以 ISO-639-1 格式（例如 en）提供语言 可改善准确率和延迟。

• languages: optional array of string

输入音频可能使用的语言，采用 ISO-639-1 格式。gpt-transcribe 和 gpt-live-transcribe 支持。

minItems: 1

• model: optional string or "whisper-1" or "gpt-transcribe" or "gpt-live-transcribe" or 5 more

转录模型，可选 whisper-1、gpt-transcribe、gpt-live-transcribe、gpt-4o-mini-transcribe、gpt-4o-mini-transcribe-2025-12-15、gpt-4o-transcribe、gpt-4o-transcribe-diarize 和 gpt-realtime-whisper。需要说话人标签时，可用 gpt-4o-transcribe-diarize。

• string

• "whisper-1" or "gpt-transcribe" or "gpt-live-transcribe" or 5 more

转录模型，可选 whisper-1、gpt-transcribe、gpt-live-transcribe、gpt-4o-mini-transcribe、gpt-4o-mini-transcribe-2025-12-15、gpt-4o-transcribe、gpt-4o-transcribe-diarize 和 gpt-realtime-whisper。需要说话人标签时，可用 gpt-4o-transcribe-diarize。

• "whisper-1"

• "gpt-transcribe"

• "gpt-live-transcribe"

• "gpt-4o-mini-transcribe"

• "gpt-4o-mini-transcribe-2025-12-15"

• "gpt-4o-transcribe"

• "gpt-4o-transcribe-diarize"

• "gpt-realtime-whisper"

• prompt: optional string

可选文本，用于引导模型的表达风格，或续接此前的音频 片段。 对于 whisper-1，提示词为关键词列表。 对于 gpt-4o-transcribe 系列（不含 gpt-4o-transcribe-diarize），提示词是自由文本，例如“预计包含技术相关词语”。 正式版 Realtime 会话使用 gpt-realtime-whisper 时不支持提示词。

• turn_detection: optional RealtimeAudioInputTurnDetection or null

轮次检测配置，可使用服务端 VAD 或语义 VAD。设为 null 可关闭，此时客户端须手动触发模型响应。

服务端 VAD 根据音量检测语音开始和结束，并在用户讲话结束时响应。

语义 VAD 更进一步，结合 VAD 使用轮次检测模型，从语义上估计用户是否讲完，再根据该概率动态设置超时。例如，用户以“嗯……”拖尾时，模型会认为轮次结束的概率较低，等待更长时间让用户继续讲话。这有助于使对话更自然，但可能增加延迟。

对于 gpt-realtime-whisper 转录会话，轮次检测须 设为 null，因为不支持 VAD。

• ServerVad object { type, create_response, idle_timeout_ms, 4 more }

服务端语音活动检测（VAD），在检测到用户语音时开启，在一段静音后关闭。

• type: "server_vad" (default: "server_vad")

轮次检测类型，设为 server_vad 可开启简单的服务端 VAD。

• "server_vad"

• create_response: optional boolean (default: true)

发生 VAD 停止事件时，是否自动生成响应。如果 interrupt_response 为 false，且模型正在响应，可能无法创建响应。

如果 create_response 和 interrupt_response 均为 false，模型不会自动响应，但仍会发出 VAD 事件。

• idle_timeout_ms: optional integer or null

可选的超时时长，超时后自动触发模型响应。适合 不希望用户长时间停顿的场景，例如电话 通话。模型会根据当前上下文， 提示用户继续对话。

从上一次模型响应的音频播放完毕后开始计算超时， 即超时起点为 response.done 的时间加上音频播放时长。

达到超时时，会发出 input_audio_buffer.timeout_triggered 事件，以及 与该响应关联的事件。 空闲超时目前仅支持 server_vad 模式。

minimum: 5000, maximum: 30000

• interrupt_response: optional boolean (default: true)

发生 VAD 开始事件时，是否自动打断（取消）正在进行且输出到默认 对话（即 conversation 为 auto）的响应。为 true 时取消响应，否则继续直至完成。

如果 create_response 和 interrupt_response 均为 false，模型不会自动响应，但仍会发出 VAD 事件。

• prefix_padding_ms: optional integer

仅用于 server_vad 模式。VAD 检测到语音前要包含的音频时长，单位为 毫秒，默认为 300 毫秒。

• silence_duration_ms: optional integer

仅用于 server_vad 模式。判断语音结束所需的静音时长，单位为毫秒。默认值 为 500 毫秒。较短的时长可加快响应， 但可能在用户短暂停顿时提前插入响应。

• threshold: optional number

仅用于 server_vad 模式。VAD 激活阈值，范围为 0.0–1.0，默认为 0.5。 较高阈值要求更大的音量才能激活模型， 因此可能更适合嘈杂环境。

• SemanticVad object { type, create_response, eagerness, interrupt_response }

服务端语义轮次检测，使用模型判断用户何时讲完。

• type: "semantic_vad"

轮次检测类型，设为 semantic_vad 可开启语义 VAD。

• "semantic_vad"

• create_response: optional boolean (default: true)

发生 VAD 停止事件时，是否自动生成响应。

• eagerness: optional "low" or "medium" or "high" or "auto" (default: "auto")

仅用于 semantic_vad 模式，控制模型响应的积极程度。low 会等待更久，让用户继续讲话；high 响应更快。默认为 auto，等同于 medium。low、medium、high 的最大超时分别为 8 秒、4 秒和 2 秒。

• "low"

• "medium"

• "high"

• "auto"

• interrupt_response: optional boolean (default: true)

发生 VAD 开始事件时，是否自动打断正在进行且输出到默认 对话（即 conversation 为 auto）的响应。

• output: optional RealtimeAudioConfigOutput

• format: optional RealtimeAudioFormats

输出音频格式。

• speed: optional number (default: 1)

模型语音响应的速度，以原始语速的倍数表示。 默认语速为 1.0，最小值为 0.25，最大值为 1.5。只能在模型轮次之间更改，不能在响应进行中更改。

此参数在音频生成后进行后处理调整；也可以 通过提示词让模型说得更快或更慢。

minimum: 0.25, maximum: 1.5

• voice: optional string or "alloy" or "ash" or "ballad" or 7 more or ID { id } (default: "alloy")

模型响应使用的音色。支持的内置音色包括 alloy, ash, ballad, coral, echo, sage, shimmer, verse, marin 和 cedar。也可以提供包含 id 的自定义音色对象，例如 { "id": "voice_1234" }。模型至少输出过一次音频后， 该会话期间不能再更改音色。 自定义音色须通过音频样本创建。通过文本提示词创建的音色仅适用于 Live。 建议使用 marin 和 cedar，以获得最佳质量。

• string

• "alloy" or "ash" or "ballad" or 7 more

• "alloy"

• "ash"

• "ballad"

• "coral"

• "echo"

• "sage"

• "shimmer"

• "verse"

• "marin"

• "cedar"

• ID object { id }

自定义音色引用。

• id: string

自定义音色 ID，例如 voice_1234。

• include: optional array of "item.input_audio_transcription.logprobs"

服务端输出中需要包含的额外字段。

item.input_audio_transcription.logprobs：包含输入音频转录的对数概率。

• "item.input_audio_transcription.logprobs"

• instructions: optional string

模型调用前添加的默认系统指令，即系统消息。此字段允许客户端引导模型生成期望的响应。可指定内容与格式，例如“极其简洁”“态度友好”“以下是优质响应示例”，也可指定音频表现，例如“说快一点”“让声音带有情感”“经常笑”。模型不保证遵循这些指令，但它们能引导模型表现出期望的行为。

注意：未设置此字段时，服务器会使用默认指令；会话开始时的 session.created 事件中可以查看这些指令。

• max_output_tokens: optional number or "inf"

单次助手响应的最大输出词元数， 包括工具调用。提供 1–4096 之间的整数可 限制输出词元数，或使用 inf 表示给定模型 可用的最大词元数。默认为 inf。

• number

• "inf"

• "inf"

• model: optional string or "gpt-realtime" or "gpt-realtime-1.5" or "gpt-realtime-2" or 16 more

此会话使用的 Realtime 模型。

• string

• "gpt-realtime" or "gpt-realtime-1.5" or "gpt-realtime-2" or 16 more

此会话使用的 Realtime 模型。

• "gpt-realtime"

• "gpt-realtime-1.5"

• "gpt-realtime-2"

• "gpt-realtime-2.1"

• "gpt-realtime-2.1-mini"

• "gpt-realtime-2025-08-28"

• "gpt-4o-realtime-preview"

• "gpt-4o-realtime-preview-2024-10-01"

• "gpt-4o-realtime-preview-2024-12-17"

• "gpt-4o-realtime-preview-2025-06-03"

• "gpt-4o-mini-realtime-preview"

• "gpt-4o-mini-realtime-preview-2024-12-17"

• "gpt-realtime-mini"

• "gpt-realtime-mini-2025-10-06"

• "gpt-realtime-mini-2025-12-15"

• "gpt-audio-1.5"

• "gpt-audio-mini"

• "gpt-audio-mini-2025-10-06"

• "gpt-audio-mini-2025-12-15"

• output_modalities: optional array of "text" or "audio" (default: ["audio"])

模型可使用的响应模态，默认为 ["audio"]，表示 模型输出音频及其转录文本。使用 ["text"] 可让 模型仅输出文本。不能同时请求 text 和 audio。

• "text"

• "audio"

• parallel_tool_calls: optional boolean

模型是否可以并行调用多个工具。仅支持 gpt-realtime-2 等具有推理能力的 Realtime 模型。

• prompt: optional ResponsePrompt or null

对提示词模板及其变量的引用。 了解更多。

• id: string

要使用的提示词模板的唯一标识。

• variables: optional map[string or ResponseInputText or ResponseInputImage or ResponseInputFile] or null

可选的值映射，用于替换提示词中的 变量。替换值可以是字符串，也可以是其他 Responses 输入类型，例如图像或文件。

• string

• ResponseInputText object { text, type, prompt_cache_breakpoint }

输入模型的文本。

• text: string

输入模型的文本。

• type: "input_text" (default: "input_text")

输入条目类型，固定为 input_text。

• "input_text"

• prompt_cache_breakpoint: optional object { mode, ttl }

标记可复用提示词前缀的精确结束位置。省略 ttl 时，断点继承请求中的 prompt_cache_options.ttl；该边界不会按词元块取整。

• mode: "explicit" (default: "explicit")

断点模式，固定为 explicit。

• "explicit"

• ttl: optional "30m" or "12h"

此缓存断点的最短存续时间，默认为请求的 TTL。

• "30m"

• "12h"

• ResponseInputImage object { detail, type, file_id, 2 more }

输入模型的图像。参阅图像输入。

• detail: ImageDetail

发送给模型的图像细节级别，可选 high、low、auto 或 original，默认为 auto。

• "low"

• "high"

• "auto"

• "original"

• type: "input_image" (default: "input_image")

输入条目类型，固定为 input_image。

• "input_image"

• file_id: optional string or null

要发送给模型的文件 ID。

• image_url: optional string or null

要发送给模型的图像 URL，可以是完整 URL，或包含 Base64 编码图像的 data URL。

format: uri

• prompt_cache_breakpoint: optional object { mode, ttl }

标记可复用提示词前缀的精确结束位置。省略 ttl 时，断点继承请求中的 prompt_cache_options.ttl；该边界不会按词元块取整。

• mode: "explicit" (default: "explicit")

断点模式，固定为 explicit。

• "explicit"

• ttl: optional "30m" or "12h"

此缓存断点的最短存续时间，默认为请求的 TTL。

• "30m"

• "12h"

• ResponseInputFile object { type, detail, file_data, 4 more }

输入模型的文件。

• type: "input_file" (default: "input_file")

输入条目类型，固定为 input_file。

• "input_file"

• detail: optional "auto" or "low" or "high"

发送给模型的文件细节级别。使用 auto 由系统选择；对于 GPT-5.6 及后续模型，auto 使用高质量渲染，可能增加输入词元用量。使用 low 进行成本较低的渲染，或使用 high 以更高质量渲染文件。默认为 auto。

• "auto"

• "low"

• "high"

• file_data: optional string

要发送给模型的文件内容。

• file_id: optional string or null

要发送给模型的文件 ID。

• file_url: optional string

要发送给模型的文件 URL。

format: uri

• filename: optional string

要发送给模型的文件名。

• prompt_cache_breakpoint: optional object { mode, ttl }

标记可复用提示词前缀的精确结束位置。省略 ttl 时，断点继承请求中的 prompt_cache_options.ttl；该边界不会按词元块取整。

• mode: "explicit" (default: "explicit")

断点模式，固定为 explicit。

• "explicit"

• ttl: optional "30m" or "12h"

此缓存断点的最短存续时间，默认为请求的 TTL。

• "30m"

• "12h"

• version: optional string or null

提示词模板的可选版本。

• reasoning: optional RealtimeReasoning

gpt-realtime-2 等具有推理能力的 Realtime 模型的配置。

• effort: optional RealtimeReasoningEffort (default: "low")

限制具有推理能力的 Realtime 模型的推理强度，例如 gpt-realtime-2.

• "minimal"

• "low"

• "medium"

• "high"

• "xhigh"

• tool_choice: optional RealtimeToolChoiceConfig (default: "auto")

模型选择工具的方式。提供一种字符串模式，或强制调用指定的 函数或 MCP 工具。

• ToolChoiceOptions = "none" or "auto" or "required"

控制模型调用哪个工具，或是否调用工具。

none 表示模型不调用工具，而是生成消息。

auto 表示模型可以选择生成消息，或调用一个或 多个工具。

required 表示模型必须调用一个或多个工具。

• "none"

• "auto"

• "required"

• ToolChoiceFunction object { name, type }

使用此选项强制模型调用指定函数。

• name: string

要调用的函数名称。

• type: "function"

对于函数调用，类型固定为 function。

• "function"

• ToolChoiceMcp object { server_label, type, name }

使用此选项强制模型调用远程 MCP 服务器上的指定工具。

• server_label: string

要使用的 MCP 服务器标签。

• type: "mcp"

对于 MCP 工具，类型固定为 mcp。

• "mcp"

• name: optional string or null

要在服务器上调用的工具名称。

• tools: optional RealtimeToolsConfig

模型可用的工具。

• RealtimeFunctionTool object { description, name, parameters, type }

• description: optional string

函数描述，包括何时以及如何 调用该函数的指导，以及调用时应向用户说明什么 内容，如需说明。

• name: optional string

函数名称。

• parameters: optional unknown

以 JSON Schema 描述的函数参数。

• type: optional "function"

工具类型，即 function。

• "function"

• McpTool object { server_label, type, allowed_callers, 9 more }

通过远程模型上下文协议（MCP）服务器， 向模型提供额外工具。了解 MCP。

• server_label: string

此 MCP 服务器的标签，用于在工具调用中标识服务器。

• type: "mcp"

MCP 工具类型，固定为 mcp。

• "mcp"

• allowed_callers: optional array of "direct" or "programmatic" or null

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• allowed_tools: optional array of string or McpToolFilter { read_only, tool_names } or null

允许的工具名称列表或筛选对象。

• McpAllowedTools = array of string

允许的工具名称组成的字符串数组。

• McpToolFilter object { read_only, tool_names }

用于指定允许哪些工具的筛选对象。

• read_only: optional boolean

表示工具会修改数据还是只读。如果 MCP 服务器标注了 readOnlyHint， 就会与此筛选条件匹配。

• tool_names: optional array of string

允许的工具名称列表。

• authorization: optional string

可用于远程 MCP 服务器的 OAuth 访问令牌，既可 配合自定义 MCP 服务器 URL，也可配合服务连接器。你的应用 须处理 OAuth 授权流程，并在此提供令牌。

• connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more

服务连接器的标识，例如 ChatGPT 中提供的连接器。须提供 server_url、connector_id 或 tunnel_id 中的一项。更多 服务连接器信息参阅此处。

对于 2026 年 9 月 1 日之后发布的模型，此字段已弃用。 使用 server_url 连接远程 MCP 服务器，或使用 tunnel_id 通过安全 MCP 隧道连接。

当前支持的 connector_id 值如下：

• Dropbox：connector_dropbox
• Gmail：connector_gmail
• Google 日历：connector_googlecalendar
• Google 云端硬盘：connector_googledrive
• Microsoft Teams：connector_microsoftteams
• Outlook 日历：connector_outlookcalendar
• Outlook 邮箱：connector_outlookemail
• SharePoint：connector_sharepoint

• "connector_dropbox"

• "connector_gmail"

• "connector_googlecalendar"

• "connector_googledrive"

• "connector_microsoftteams"

• "connector_outlookcalendar"

• "connector_outlookemail"

• "connector_sharepoint"

• defer_loading: optional boolean

此 MCP 工具是否延迟加载并通过工具搜索发现。

• headers: optional map[string] or null

可选的发送给 MCP 服务器的 HTTP 请求头，用于认证 或其他用途。

• require_approval: optional McpToolApprovalFilter { always, never } or "always" or "never" or null (default: "always")

指定 MCP 服务器的哪些工具需要批准。

• McpToolApprovalFilter object { always, never }

指定 MCP 服务器的哪些工具需要批准。可以是 always、never，或与需要批准的工具关联的 筛选对象。

• always: optional object { read_only, tool_names }

用于指定允许哪些工具的筛选对象。

• read_only: optional boolean

表示工具会修改数据还是只读。如果 MCP 服务器标注了 readOnlyHint， 就会与此筛选条件匹配。

• tool_names: optional array of string

允许的工具名称列表。

• never: optional object { read_only, tool_names }

用于指定允许哪些工具的筛选对象。

• read_only: optional boolean

表示工具会修改数据还是只读。如果 MCP 服务器标注了 readOnlyHint， 就会与此筛选条件匹配。

• tool_names: optional array of string

允许的工具名称列表。

• McpToolApprovalSetting = "always" or "never"

为所有工具指定统一的批准策略，可选 always 或 never。设为 always 时，所有工具均需要批准； 设为 never 时，所有工具均不需要批准。

• "always"

• "never"

• server_description: optional string

MCP 服务器的可选描述，用于提供更多上下文。

• server_url: optional string

MCP 服务器的 URL。须提供 server_url、connector_id 或 tunnel_id 中的一项。

format: uri

• tunnel_id: optional string

用来替代直接服务器 URL 的安全 MCP 隧道 ID。须提供 server_url、connector_id 或 tunnel_id 中的一项。

pattern: ^tunnel_[a-z0-9]{32}$

• tracing: optional RealtimeTracingConfig or null

Realtime API 可以将会话追踪记录写入追踪控制台。设为 null 可禁用追踪。一旦 为会话启用追踪，就不能修改配置。

auto 会使用默认的工作流名称、分组 ID 和元数据 为会话创建追踪记录。

• Auto = "auto"

启用追踪，并使用追踪配置选项的默认值，固定为 auto。

• "auto"

• TracingConfiguration object { group_id, metadata, workflow_name }

追踪的细粒度配置。

• group_id: optional string

要附加到此追踪记录的分组 ID，以便在追踪控制台中筛选和 分组。

• metadata: optional unknown

要附加到此追踪记录的任意元数据，以便在追踪控制台中 筛选。

• workflow_name: optional string

要附加到此追踪记录的工作流名称，用于在追踪控制台中 为追踪记录命名。

• truncation: optional RealtimeTruncation

对话词元数超过模型的输入词元上限时，会截断对话，即从最早的消息开始，将部分消息排除在模型上下文之外。对于上下文为 32k、最大输出为 4,096 个词元的模型，发生截断前最多只能在上下文中包含 28,224 个词元。

客户端可以将截断所用的最大词元数设得更低，以控制词元用量和成本。

截断会从上下文开头丢弃消息，因此会减少下一轮的缓存词元数，导致缓存失效。但客户端也可以配置截断，使保留消息的词元数不超过最大上下文大小的一定比例，从而减少后续截断次数，提高缓存命中率。

可以完全禁用截断。此时服务端不会截断；如果对话超过模型的输入词元上限，会返回错误。

• "auto" or "disabled"

会话使用的截断策略，默认为 auto。disabled 会禁用截断，在对话超过输入词元上限时报告错误。

• "auto"

• "disabled"

• RetentionRatioTruncation object { retention_ratio, type, token_limits }

对话超过输入词元上限时，保留一定比例的对话词元。这样可以将截断成本分摊到多个轮次，有助于改善缓存词元的使用情况。

• retention_ratio: number

对话超过输入词元上限时，在指令之后的对话词元中保留的比例，范围为 0.0–1.0。设为 0.8 时，持续丢弃消息，直到词元数降至允许最大值的 80%，有助于降低截断频率、提高缓存命中率。

minimum: 0, maximum: 1

• type: "retention_ratio"

使用保留比例截断策略。

• "retention_ratio"

• token_limits: optional object { post_instructions }

此截断策略可选的自定义词元上限。未提供时，使用模型的默认词元上限。

• post_instructions: optional integer

指令之后的对话允许的最大词元数，其中指令包含工具定义。例如设为 5,000，则指令之后的对话超过 5,000 个词元时发生截断。此值不能高于模型上下文窗口大小减去最大输出词元数。

minimum: 0

• RealtimeTranscriptionSessionCreateRequest object { type, audio, include }

Realtime 转录会话对象配置。

• type: "transcription"

要创建的会话类型。对于转录会话，固定为 transcription。

• "transcription"

• audio: optional RealtimeTranscriptionSessionAudio

输入和输出音频的配置。

• input: optional RealtimeTranscriptionSessionAudioInput

• format: optional RealtimeAudioFormats

PCM 音频格式，仅支持 24kHz 采样率。

• noise_reduction: optional object { strength, type }

输入音频降噪配置，设为 null 可关闭。 降噪会在音频发送给 VAD 和模型前，对加入输入缓冲区的音频进行过滤。 过滤音频能改善模型对输入的感知，提高 VAD 和话轮检测的准确率、减少误报，并改善模型表现。

• strength: optional number (default: 1)

输入噪声抑制强度，值越大抑制越强。 首次启用降噪时默认为 1。在会话更新中省略 strength 会保留当前强度。

minimum: 0, maximum: 1

• type: optional NoiseReductionType

降噪类型。near_field 适用于耳机等近讲麦克风，far_field 适用于笔记本或会议室等远场麦克风。

• transcription: optional AudioTranscription

输入音频转录配置，默认关闭，开启后可设为 null 再次关闭。模型直接处理音频，输入音频转录不是模型的原生处理过程。转录通过 /audio/transcriptions 接口异步进行，应视为输入音频内容的参考，不能当作模型实际听到内容的精确表示。客户端可以选择设置转录语言和提示词，为转录服务提供额外引导。

• turn_detection: optional RealtimeTranscriptionSessionAudioInputTurnDetection or null

轮次检测配置，可使用服务端 VAD 或语义 VAD。设为 null 可关闭，此时客户端须手动触发模型响应。

服务端 VAD 根据音量检测语音开始和结束，并在用户讲话结束时响应。

语义 VAD 更进一步，结合 VAD 使用轮次检测模型，从语义上估计用户是否讲完，再根据该概率动态设置超时。例如，用户以“嗯……”拖尾时，模型会认为轮次结束的概率较低，等待更长时间让用户继续讲话。这有助于使对话更自然，但可能增加延迟。

对于 gpt-realtime-whisper 转录会话，轮次检测须 设为 null，因为不支持 VAD。

• ServerVad object { type, create_response, idle_timeout_ms, 4 more }

服务端语音活动检测（VAD），在检测到用户语音时开启，在一段静音后关闭。

• type: "server_vad" (default: "server_vad")

轮次检测类型，设为 server_vad 可开启简单的服务端 VAD。

• "server_vad"

• create_response: optional boolean (default: true)

发生 VAD 停止事件时，是否自动生成响应。如果 interrupt_response 为 false，且模型正在响应，可能无法创建响应。

如果 create_response 和 interrupt_response 均为 false，模型不会自动响应，但仍会发出 VAD 事件。

• idle_timeout_ms: optional integer or null

可选的超时时长，超时后自动触发模型响应。适合 不希望用户长时间停顿的场景，例如电话 通话。模型会根据当前上下文， 提示用户继续对话。

从上一次模型响应的音频播放完毕后开始计算超时， 即超时起点为 response.done 的时间加上音频播放时长。

达到超时时，会发出 input_audio_buffer.timeout_triggered 事件，以及 与该响应关联的事件。 空闲超时目前仅支持 server_vad 模式。

minimum: 5000, maximum: 30000

• interrupt_response: optional boolean (default: true)

发生 VAD 开始事件时，是否自动打断（取消）正在进行且输出到默认 对话（即 conversation 为 auto）的响应。为 true 时取消响应，否则继续直至完成。

如果 create_response 和 interrupt_response 均为 false，模型不会自动响应，但仍会发出 VAD 事件。

• prefix_padding_ms: optional integer

仅用于 server_vad 模式。VAD 检测到语音前要包含的音频时长，单位为 毫秒，默认为 300 毫秒。

• silence_duration_ms: optional integer

仅用于 server_vad 模式。判断语音结束所需的静音时长，单位为毫秒。默认值 为 500 毫秒。较短的时长可加快响应， 但可能在用户短暂停顿时提前插入响应。

• threshold: optional number

仅用于 server_vad 模式。VAD 激活阈值，范围为 0.0–1.0，默认为 0.5。 较高阈值要求更大的音量才能激活模型， 因此可能更适合嘈杂环境。

• SemanticVad object { type, create_response, eagerness, interrupt_response }

服务端语义轮次检测，使用模型判断用户何时讲完。

• type: "semantic_vad"

轮次检测类型，设为 semantic_vad 可开启语义 VAD。

• "semantic_vad"

• create_response: optional boolean (default: true)

发生 VAD 停止事件时，是否自动生成响应。

• eagerness: optional "low" or "medium" or "high" or "auto" (default: "auto")

仅用于 semantic_vad 模式，控制模型响应的积极程度。low 会等待更久，让用户继续讲话；high 响应更快。默认为 auto，等同于 medium。low、medium、high 的最大超时分别为 8 秒、4 秒和 2 秒。

• "low"

• "medium"

• "high"

• "auto"

• interrupt_response: optional boolean (default: true)

发生 VAD 开始事件时，是否自动打断正在进行且输出到默认 对话（即 conversation 为 auto）的响应。

• include: optional array of "item.input_audio_transcription.logprobs"

服务端输出中需要包含的额外字段。

item.input_audio_transcription.logprobs：包含输入音频转录的对数概率。

• "item.input_audio_transcription.logprobs"

• type: "session.update"

事件类型，须为 session.update。

• "session.update"

• event_id: optional string

客户端生成的可选事件 ID，可以是任意字符串。事件发生错误时会回传，但对应的 session.updated 事件不会包含它。

maxLength: 512

示例

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "instructions": "你是一名协助完成设计任务的创意助手。",
    "tools": [
      {
        "type": "function",
        "name": "display_color_palette",
        "description": "用户请求配色方案时调用此函数。",
        "parameters": {
          "type": "object",
          "properties": {
            "theme": {
              "type": "string",
              "description": "配色方案的主题描述。"
            },
            "colors": {
              "type": "array",
              "description": "根据主题生成的五个十六进制颜色代码组成的数组。",
              "items": {
                "type": "string",
                "description": "十六进制颜色代码"
              }
            }
          },
          "required": [
            "theme",
            "colors"
          ]
        }
      }
    ],
    "tool_choice": "auto"
  }
}

input_audio_buffer.append

向输入音频缓冲区追加音频字节时发送此事件。音频 缓冲区是可以写入并稍后提交的临时存储。提交会用缓冲区内容在对话历史中创建新的 用户消息条目，然后清空缓冲区。 缓冲区提交时，会生成输入音频转录，如已启用。

启用 VAD 时，音频缓冲区用于检测语音，由服务端决定 何时提交。关闭服务端 VAD 时，须手动提交音频 缓冲区。输入音频降噪会作用于写入缓冲区的音频。

客户端可以选择每个事件包含多少音频，最大 为 15 MiB。例如，从客户端流式发送较小的块，可使 VAD 更灵敏。与大多数其他客户端事件不同，服务端 不会对此事件发送确认响应。

结构定义

模式名称：RealtimeClientEventInputAudioBufferAppend

• audio: string

Base64 编码的音频字节，须采用会话配置中 input_audio_format 字段指定的格式。

• type: "input_audio_buffer.append"

事件类型，须为 input_audio_buffer.append。

• "input_audio_buffer.append"

• event_id: optional string

客户端生成的可选 ID，用于标识此事件。

maxLength: 512

示例

{
    "event_id": "event_456",
    "type": "input_audio_buffer.append",
    "audio": "Base64EncodedAudioData"
}

input_audio_buffer.commit

发送此事件可提交用户输入音频缓冲区，并在对话中创建新的用户消息条目。缓冲区为空时会报错。服务端 VAD 模式下，客户端无需发送此事件，由服务端自动提交。

提交输入音频缓冲区会触发输入音频转录，如会话配置已启用，但不会创建模型响应。服务端会响应 input_audio_buffer.committed。

结构定义

模式名称：RealtimeClientEventInputAudioBufferCommit

• type: "input_audio_buffer.commit"

事件类型，须为 input_audio_buffer.commit。

• "input_audio_buffer.commit"

• event_id: optional string

客户端生成的可选 ID，用于标识此事件。

maxLength: 512

示例

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

input_audio_buffer.clear

要清空缓冲区中的音频字节时，发送此事件。服务端会 响应 input_audio_buffer.cleared。

结构定义

模式名称：RealtimeClientEventInputAudioBufferClear

• type: "input_audio_buffer.clear"

事件类型，须为 input_audio_buffer.clear。

• "input_audio_buffer.clear"

• event_id: optional string

客户端生成的可选 ID，用于标识此事件。

maxLength: 512

示例

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

conversation.item.create

向对话上下文添加新条目，包括消息、函数 调用和函数调用响应。此事件既可填充对话 历史，也可在流式对话中途添加条目；但目前 不支持填充助手音频消息。

成功时，服务端会发出 conversation.item.added，并在 条目最终确定时发出 conversation.item.done。否则会发送 error 事件。

结构定义

模式名称：RealtimeClientEventConversationItemCreate

• item: ConversationItem

Realtime 对话中的单个条目。

• RealtimeConversationItemSystemMessage object { content, role, type, 3 more }

Realtime 对话中的系统消息可用于提供额外上下文或指令。它与对话开始时的指令提示词类似但有所不同：系统消息可在对话任意时刻添加。对话行为的重大更改应使用 instructions；较小的更新，例如“用户现在询问另一个话题”，可使用系统消息。

• content: array of object { text, type }

消息内容。

• text: optional string

文本内容。

• type: optional "input_text"

内容类型。对于系统消息，固定为 input_text。

• "input_text"

• role: "system"

消息发送者的角色，固定为 system。

• "system"

• type: "message"

条目类型，固定为 message。

• "message"

• id: optional string

条目的唯一 ID，可由客户端提供，也可由服务端生成。

• object: optional "realtime.item"

返回的 API 对象的标识，固定为 realtime.item。创建新条目时可选。

• "realtime.item"

• status: optional "completed" or "incomplete" or "in_progress"

条目状态，不影响对话。

• "completed"

• "incomplete"

• "in_progress"

• RealtimeConversationItemUserMessage object { content, role, type, 3 more }

Realtime 对话中的用户消息条目。

• content: array of object { audio, detail, image_url, 3 more }

消息内容。

• audio: optional string

Base64 编码的音频字节，适用于 input_audio，按会话输入音频类型配置中的格式解析。未指定时，默认为 16 位、24kHz、单声道 PCM。

• detail: optional "auto" or "low" or "high" (default: "auto")

图像细节级别，适用于 input_image。auto 默认采用 high。

• "auto"

• "low"

• "high"

• image_url: optional string

以 data URI 提供的 Base64 编码图像字节，适用于 input_image，例如 data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...。支持 PNG 和 JPEG。

format: uri

• text: optional string

文本内容，适用于 input_text。

• transcript: optional string

音频转录文本，适用于 input_audio。此文本不会发送给模型，而是附加到消息条目中供参考。

• type: optional "input_text" or "input_audio" or "input_image"

内容类型：input_text、input_audio 或 input_image。

• "input_text"

• "input_audio"

• "input_image"

• role: "user"

消息发送者的角色，固定为 user。

• "user"

• type: "message"

条目类型，固定为 message。

• "message"

• id: optional string

条目的唯一 ID，可由客户端提供，也可由服务端生成。

• object: optional "realtime.item"

返回的 API 对象的标识，固定为 realtime.item。创建新条目时可选。

• "realtime.item"

• status: optional "completed" or "incomplete" or "in_progress"

条目状态，不影响对话。

• "completed"

• "incomplete"

• "in_progress"

• RealtimeConversationItemAssistantMessage object { content, role, type, 3 more }

Realtime 对话中的助手消息条目。

• content: array of object { audio, text, transcript, type }

消息内容。

• audio: optional string

Base64 编码的音频字节，按会话输出音频类型配置中的格式解析。未指定时，默认为 16 位、24kHz、单声道 PCM。

• text: optional string

文本内容。

• transcript: optional string

音频内容的转录文本，输出类型为 audio 时始终提供。

• type: optional "output_text" or "output_audio"

内容类型，根据会话的 output_modalities 配置，为 output_text 或 output_audio。

• "output_text"

• "output_audio"

• role: "assistant"

消息发送者的角色，固定为 assistant。

• "assistant"

• type: "message"

条目类型，固定为 message。

• "message"

• id: optional string

条目的唯一 ID，可由客户端提供，也可由服务端生成。

• object: optional "realtime.item"

返回的 API 对象的标识，固定为 realtime.item。创建新条目时可选。

• "realtime.item"

• status: optional "completed" or "incomplete" or "in_progress"

条目状态，不影响对话。

• "completed"

• "incomplete"

• "in_progress"

• RealtimeConversationItemFunctionCall object { arguments, name, type, 4 more }

Realtime 对话中的函数调用条目。

• arguments: string

函数调用的参数，以 JSON 编码字符串表示，例如 {"arg1": "value1", "arg2": 42}。

• name: string

被调用的函数名称。

• type: "function_call"

条目类型，固定为 function_call。

• "function_call"

• id: optional string

条目的唯一 ID，可由客户端提供，也可由服务端生成。

• call_id: optional string

函数调用 ID。

• object: optional "realtime.item"

返回的 API 对象的标识，固定为 realtime.item。创建新条目时可选。

• "realtime.item"

• status: optional "completed" or "incomplete" or "in_progress"

条目状态，不影响对话。

• "completed"

• "incomplete"

• "in_progress"

• RealtimeConversationItemFunctionCallOutput object { call_id, output, type, 3 more }

Realtime 对话中的函数调用输出条目。

• call_id: string

此输出对应的函数调用的 ID。

• output: string

函数调用输出，为自由文本，可包含任意信息，也可为空。

• type: "function_call_output"

条目类型，固定为 function_call_output。

• "function_call_output"

• id: optional string

条目的唯一 ID，可由客户端提供，也可由服务端生成。

• object: optional "realtime.item"

返回的 API 对象的标识，固定为 realtime.item。创建新条目时可选。

• "realtime.item"

• status: optional "completed" or "incomplete" or "in_progress"

条目状态，不影响对话。

• "completed"

• "incomplete"

• "in_progress"

• RealtimeMcpApprovalResponse object { id, approval_request_id, approve, 2 more }

回应 MCP 批准请求的 Realtime 条目。

• id: string

批准响应的唯一 ID。

• approval_request_id: string

所回应的批准请求的 ID。

• approve: boolean

请求是否获准。

• type: "mcp_approval_response"

类型，固定为 mcp_approval_response。

• "mcp_approval_response"

• reason: optional string or null

决定的可选理由。

• RealtimeMcpListTools object { server_label, tools, type, id }

列出 MCP 服务器可用工具的 Realtime 条目。

• server_label: string

MCP 服务器标签。

• tools: array of object { input_schema, name, annotations, description }

服务器可用的工具。

• input_schema: unknown

描述工具输入的 JSON Schema。

• name: string

工具名称。

• annotations: optional unknown or null

工具的额外注解。

• description: optional string or null

工具描述。

• type: "mcp_list_tools"

类型，固定为 mcp_list_tools。

• "mcp_list_tools"

• id: optional string

列表的唯一 ID。

• RealtimeMcpToolCall object { id, arguments, name, 5 more }

表示调用 MCP 服务器上工具的 Realtime 条目。

• id: string

工具调用的唯一 ID。

• arguments: string

传给工具的参数组成的 JSON 字符串。

• name: string

已运行的工具名称。

• server_label: string

运行工具的 MCP 服务器标签。

• type: "mcp_call"

类型，固定为 mcp_call。

• "mcp_call"

• approval_request_id: optional string or null

关联批准请求的 ID，如有。

• error: optional RealtimeMcpProtocolError or RealtimeMcpToolExecutionError or RealtimeMcphttpError or null

工具调用的错误，如有。

• RealtimeMcpProtocolError object { code, message, type }

• code: integer

• message: string

• type: "protocol_error"

• "protocol_error"

• RealtimeMcpToolExecutionError object { message, type }

• message: string

• type: "tool_execution_error"

• "tool_execution_error"

• RealtimeMcphttpError object { code, message, type }

• code: integer

• message: string

• type: "http_error"

• "http_error"

• output: optional string or null

工具调用的输出。

• RealtimeMcpApprovalRequest object { id, arguments, name, 2 more }

请求人工批准工具调用的 Realtime 条目。

• id: string

批准请求的唯一 ID。

• arguments: string

工具参数的 JSON 字符串。

• name: string

要运行的工具名称。

• server_label: string

发出请求的 MCP 服务器标签。

• type: "mcp_approval_request"

类型，固定为 mcp_approval_request。

• "mcp_approval_request"

• type: "conversation.item.create"

事件类型，须为 conversation.item.create。

• "conversation.item.create"

• event_id: optional string

客户端生成的可选 ID，用于标识此事件。

maxLength: 512

• previous_item_id: optional string

新条目要插入在哪个条目之后，即前一个条目的 ID。未设置时追加到对话末尾。

设为 root 时，新条目添加到对话开头。

设为已有 ID 时，可将条目插入对话中间。如果找不到该 ID，会返回错误，且不会添加条目。

示例

{
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "嗨"
      }
    ]
  }
}

conversation.item.retrieve

要获取服务端保存的某个对话历史条目时，发送此事件。例如，可用于检查经降噪和 VAD 处理后的用户音频。 服务端将响应 conversation.item.retrieved 事件， 如果对话历史中不存在该条目，则 返回错误。

结构定义

模式名称：RealtimeClientEventConversationItemRetrieve

• item_id: string

要获取的条目的 ID。

• type: "conversation.item.retrieve"

事件类型，须为 conversation.item.retrieve。

• "conversation.item.retrieve"

• event_id: optional string

客户端生成的可选 ID，用于标识此事件。

maxLength: 512

示例

{
    "event_id": "event_901",
    "type": "conversation.item.retrieve",
    "item_id": "item_003"
}

conversation.item.truncate

要截断此前助手消息的音频时，发送此事件。服务端 生成音频的速度快于实时播放，因此用户打断时，可用此事件 截去已经发送给客户端但尚未 播放的音频，以同步服务端对音频的理解与 客户端的播放状态。

截断音频会删除服务端的文本转录，以确保 上下文中没有用户尚未听到的文本。

成功时，服务端会响应 conversation.item.truncated 事件。

结构定义

模式名称：RealtimeClientEventConversationItemTruncate

• audio_end_ms: integer

音频保留到的时长，单位为毫秒，包含该边界。如果 audio_end_ms 超过实际音频时长，服务端 将返回错误。

• content_index: integer

要截断的内容部分的索引，须设为 0。

• item_id: string

要截断的助手消息条目的 ID。只能截断助手 消息条目。

• type: "conversation.item.truncate"

事件类型，须为 conversation.item.truncate。

• "conversation.item.truncate"

• event_id: optional string

客户端生成的可选 ID，用于标识此事件。

maxLength: 512

示例

{
    "event_id": "event_678",
    "type": "conversation.item.truncate",
    "item_id": "item_002",
    "content_index": 0,
    "audio_end_ms": 1500
}

conversation.item.delete

要从对话历史中删除任意条目时，发送此 事件。服务端会响应 conversation.item.deleted； 如果对话历史中不存在该条目，则 返回错误。

结构定义

模式名称：RealtimeClientEventConversationItemDelete

• item_id: string

要删除的条目的 ID。

• type: "conversation.item.delete"

事件类型，须为 conversation.item.delete。

• "conversation.item.delete"

• event_id: optional string

客户端生成的可选 ID，用于标识此事件。

maxLength: 512

示例

{
    "event_id": "event_901",
    "type": "conversation.item.delete",
    "item_id": "item_003"
}

response.create

此事件指示服务端创建响应，即触发 模型推理。在服务端 VAD 模式下，服务端会 自动创建响应。

响应至少包含一个条目，也可能包含两个；此时 第二个条目为函数调用。默认将这些条目追加到 对话历史。

服务端会发出 response.created，然后发出生成条目和内容的 相关事件，最后用 response.done 表示 响应已结束。

response.create 包含 instructions、tools 等 推理配置。如设置，仅在本次响应中覆盖 会话配置。

可以在默认对话之外创建带外响应，即提供 任意输入，并可禁止将输出写入对话。 同时只能有一个响应写入默认对话；除此之外，可并行创建多个 响应。可使用 metadata 字段 区分同时存在的多个响应。

将 conversation 设为 none，可创建不写入默认 对话的响应。使用 input 数组提供任意输入，数组接受 原始条目和已有条目的引用。

结构定义

模式名称：RealtimeClientEventResponseCreate

• type: "response.create"

事件类型，须为 response.create。

• "response.create"

• event_id: optional string

客户端生成的可选 ID，用于标识此事件。

maxLength: 512

• response: optional RealtimeResponseCreateParams

使用这些参数创建新的 Realtime 响应。

• audio: optional RealtimeResponseCreateAudioOutput

音频输入和输出配置。

• output: optional object { format, voice }

• format: optional RealtimeAudioFormats

输出音频格式。

• PCMAudio object { rate, type }

PCM 音频格式，仅支持 24kHz 采样率。

• rate: optional 24000

音频采样率，固定为 24000。

• 24000

• type: optional "audio/pcm"

音频格式，固定为 audio/pcm。

• "audio/pcm"

• PCMUAudio object { type }

G.711 μ-law 格式。

• type: optional "audio/pcmu"

音频格式，固定为 audio/pcmu。

• "audio/pcmu"

• PCMAAudio object { type }

G.711 A-law 格式。

• type: optional "audio/pcma"

音频格式，固定为 audio/pcma。

• "audio/pcma"

• voice: optional string or "alloy" or "ash" or "ballad" or 7 more or ID { id } (default: "alloy")

模型响应使用的音色。支持的内置音色包括 alloy, ash, ballad, coral, echo, sage, shimmer, verse, marin 和 cedar。也可以提供包含 id 的自定义音色对象，例如 { "id": "voice_1234" }。模型至少输出过一次音频后， 该会话期间不能再更改音色。 自定义音色须通过音频样本创建。通过文本提示词创建的音色仅适用于 Live。 建议使用 marin 和 cedar，以获得最佳质量。

• string

• "alloy" or "ash" or "ballad" or 7 more

• "alloy"

• "ash"

• "ballad"

• "coral"

• "echo"

• "sage"

• "shimmer"

• "verse"

• "marin"

• "cedar"

• ID object { id }

自定义音色引用。

• id: string

自定义音色 ID，例如 voice_1234。

• conversation: optional string or "auto" or "none"

控制将响应添加到哪个对话。当前支持 auto 和 none，默认为 auto。auto 表示响应内容添加到默认 对话。设为 none 可创建带外响应， 不向默认对话添加条目。

• string

• "auto" or "none"

控制将响应添加到哪个对话。当前支持 auto 和 none，默认为 auto。auto 表示响应内容添加到默认 对话。设为 none 可创建带外响应， 不向默认对话添加条目。

• "auto"

• "none"

• input: optional array of RealtimeResponseInputMessageSystem { content, role, type, 2 more } or RealtimeResponseInputMessageDeveloper { content, role, type, 2 more } or RealtimeResponseInputMessageUser { content, role, type, 2 more } or 4 more

要包含在模型提示词中的输入条目。使用此字段， 会为本次响应创建新上下文，而不使用默认 对话。空数组 [] 会清空本次响应的上下文。 注意，可用 ID 引用此前出现在会话中的 条目。

• RealtimeResponseInputMessageSystem object { content, role, type, 2 more }

• content: array of object { text, type }

minItems: 1, maxItems: 1

• text: string

maxLength: 256000

• type: "input_text"

• "input_text"

• role: "system"

• "system"

• type: "message"

• "message"

• id: optional string or null

可选的客户端 ID，root 为保留值。

pattern: ^[a-zA-Z0-9_-]+$, minLength: 1, maxLength: 32

• status: optional "completed" or "incomplete" or null (default: "completed")

可选的输入状态。省略或设为 null 时默认为 completed。

• "completed"

• "incomplete"

• RealtimeResponseInputMessageDeveloper object { content, role, type, 2 more }

• content: array of object { text, type }

minItems: 1, maxItems: 1

• text: string

maxLength: 256000

• type: "input_text"

• "input_text"

• role: "developer"

• "developer"

• type: "message"

• "message"

• id: optional string or null

可选的客户端 ID，root 为保留值。

pattern: ^[a-zA-Z0-9_-]+$, minLength: 1, maxLength: 32

• status: optional "completed" or "incomplete" or null (default: "completed")

可选的输入状态。省略或设为 null 时默认为 completed。

• "completed"

• "incomplete"

• RealtimeResponseInputMessageUser object { content, role, type, 2 more }

• content: array of InputText { text, type } or InputAudio { audio, type, transcript } or InputImage { image_url, type, detail }

minItems: 1

• InputText object { text, type }

• text: string

maxLength: 256000

• type: "input_text"

• "input_text"

• InputAudio object { audio, type, transcript }

• audio: string

采用会话输入音频格式的 Base64 编码音频字节。

minLength: 1

• type: "input_audio"

• "input_audio"

• transcript: optional string or null

可选的与输入音频关联的文本。

• InputImage object { image_url, type, detail }

• image_url: string

具有图像 MIME 类型的 Base64 data URL，须使用 PNG 或 JPEG。

pattern: ^data:image/[^;,]+;base64,.+, format: uri

• type: "input_image"

• "input_image"

• detail: optional "low" or "high" or "auto" or null (default: "auto")

• "low"

• "high"

• "auto"

• role: "user"

• "user"

• type: "message"

• "message"

• id: optional string or null

可选的客户端 ID，root 为保留值。

pattern: ^[a-zA-Z0-9_-]+$, minLength: 1, maxLength: 32

• status: optional "completed" or "incomplete" or null (default: "completed")

可选的输入状态。省略或设为 null 时默认为 completed。

• "completed"

• "incomplete"

• RealtimeResponseInputMessageAssistant object { content, role, type, 2 more }

• content: array of object { text, type }

minItems: 1

• text: string

maxLength: 256000

• type: "output_text"

• "output_text"

• role: "assistant"

• "assistant"

• type: "message"

• "message"

• id: optional string or null

可选的客户端 ID，root 为保留值。

pattern: ^[a-zA-Z0-9_-]+$, minLength: 1, maxLength: 32

• status: optional "completed" or "incomplete" or null (default: "completed")

可选的输入状态。省略或设为 null 时默认为 completed。

• "completed"

• "incomplete"

• FunctionCall object { arguments, call_id, name, 3 more }

作为 Realtime 响应输入提供的函数调用。

• arguments: string

maxLength: 1048576

• call_id: string

pattern: ^[a-zA-Z0-9_-]+$, minLength: 1, maxLength: 32

• name: string

pattern: ^[a-zA-Z0-9_-]+$, minLength: 1, maxLength: 64

• type: "function_call"

• "function_call"

• id: optional string or null

pattern: ^[a-zA-Z0-9_-]+$, minLength: 1, maxLength: 32

• status: optional "completed" or "incomplete" or null (default: "completed")

• "completed"

• "incomplete"

• FunctionCallOutput object { call_id, output, type, 2 more }

作为 Realtime 响应输入提供的函数调用结果。

• call_id: string

pattern: ^[a-zA-Z0-9_-]+$, minLength: 1, maxLength: 32

• output: string

maxLength: 1048576

• type: "function_call_output"

• "function_call_output"

• id: optional string or null

pattern: ^[a-zA-Z0-9_-]+$, minLength: 1, maxLength: 32

• status: optional "completed" or "incomplete" or null (default: "completed")

• "completed"

• "incomplete"

• ResponseItemReference object { id, type }

在 response.create 输入中引用此 Realtime 会话的已有条目。 仅响应的 input 数组接受条目引用，不能将其作为新的 对话条目添加。

• id: string

同一 Realtime 会话中已有条目的 ID。

pattern: ^[a-zA-Z0-9_-]+$, minLength: 1, maxLength: 32

• type: "item_reference"

此条目类型，固定为 item_reference。

• "item_reference"

• instructions: optional string

模型调用前添加的默认系统指令，即系统消息。此字段允许客户端引导模型生成期望的响应。可指定内容与格式，例如“极其简洁”“态度友好”“以下是优质响应示例”，也可指定音频表现，例如“说快一点”“让声音带有情感”“经常笑”。模型不保证遵循这些指令，但它们能引导模型表现出期望的行为。 注意：未设置此字段时，服务器会使用默认指令；会话开始时的 session.created 事件中可以查看这些指令。

• max_output_tokens: optional number or "inf"

单次助手响应的最大输出词元数， 包括工具调用。提供 1–4096 之间的整数可 限制输出词元数，或使用 inf 表示给定模型 可用的最大词元数。默认为 inf。

• number

• "inf"

• "inf"

• metadata: optional Metadata or null

可附加到对象的元数据，最多包含 16 组键值对，可 以结构化方式存储对象的额外信息， 并通过 API 或控制台查询对象。

键为最多 64 个字符的字符串，值为 最多 512 个字符的字符串。

• output_modalities: optional array of "text" or "audio"

模型响应使用的模态集合，目前可用值仅为 [\"audio\"] 或 [\"text\"]。音频输出始终包含文本转录。将 输出模式设为 text 会禁用模型音频输出。

• "text"

• "audio"

• parallel_tool_calls: optional boolean

模型是否可以并行调用多个工具。仅支持 gpt-realtime-2 等具有推理能力的 Realtime 模型。

• prompt: optional ResponsePrompt or null

对提示词模板及其变量的引用。 了解更多。

• id: string

要使用的提示词模板的唯一标识。

• variables: optional map[string or ResponseInputText or ResponseInputImage or ResponseInputFile] or null

可选的值映射，用于替换提示词中的 变量。替换值可以是字符串，也可以是其他 Responses 输入类型，例如图像或文件。

• string

• ResponseInputText object { text, type, prompt_cache_breakpoint }

输入模型的文本。

• text: string

输入模型的文本。

• type: "input_text" (default: "input_text")

输入条目类型，固定为 input_text。

• "input_text"

• prompt_cache_breakpoint: optional object { mode, ttl }

标记可复用提示词前缀的精确结束位置。省略 ttl 时，断点继承请求中的 prompt_cache_options.ttl；该边界不会按词元块取整。

• mode: "explicit" (default: "explicit")

断点模式，固定为 explicit。

• "explicit"

• ttl: optional "30m" or "12h"

此缓存断点的最短存续时间，默认为请求的 TTL。

• "30m"

• "12h"

• ResponseInputImage object { detail, type, file_id, 2 more }

输入模型的图像。参阅图像输入。

• detail: ImageDetail

发送给模型的图像细节级别，可选 high、low、auto 或 original，默认为 auto。

• "low"

• "high"

• "auto"

• "original"

• type: "input_image" (default: "input_image")

输入条目类型，固定为 input_image。

• "input_image"

• file_id: optional string or null

要发送给模型的文件 ID。

• image_url: optional string or null

要发送给模型的图像 URL，可以是完整 URL，或包含 Base64 编码图像的 data URL。

format: uri

• prompt_cache_breakpoint: optional object { mode, ttl }

标记可复用提示词前缀的精确结束位置。省略 ttl 时，断点继承请求中的 prompt_cache_options.ttl；该边界不会按词元块取整。

• mode: "explicit" (default: "explicit")

断点模式，固定为 explicit。

• "explicit"

• ttl: optional "30m" or "12h"

此缓存断点的最短存续时间，默认为请求的 TTL。

• "30m"

• "12h"

• ResponseInputFile object { type, detail, file_data, 4 more }

输入模型的文件。

• type: "input_file" (default: "input_file")

输入条目类型，固定为 input_file。

• "input_file"

• detail: optional "auto" or "low" or "high"

发送给模型的文件细节级别。使用 auto 由系统选择；对于 GPT-5.6 及后续模型，auto 使用高质量渲染，可能增加输入词元用量。使用 low 进行成本较低的渲染，或使用 high 以更高质量渲染文件。默认为 auto。

• "auto"

• "low"

• "high"

• file_data: optional string

要发送给模型的文件内容。

• file_id: optional string or null

要发送给模型的文件 ID。

• file_url: optional string

要发送给模型的文件 URL。

format: uri

• filename: optional string

要发送给模型的文件名。

• prompt_cache_breakpoint: optional object { mode, ttl }

标记可复用提示词前缀的精确结束位置。省略 ttl 时，断点继承请求中的 prompt_cache_options.ttl；该边界不会按词元块取整。

• mode: "explicit" (default: "explicit")

断点模式，固定为 explicit。

• "explicit"

• ttl: optional "30m" or "12h"

此缓存断点的最短存续时间，默认为请求的 TTL。

• "30m"

• "12h"

• version: optional string or null

提示词模板的可选版本。

• reasoning: optional RealtimeReasoning

gpt-realtime-2 等具有推理能力的 Realtime 模型的配置。

• effort: optional RealtimeReasoningEffort (default: "low")

限制具有推理能力的 Realtime 模型的推理强度，例如 gpt-realtime-2.

• "minimal"

• "low"

• "medium"

• "high"

• "xhigh"

• tool_choice: optional ToolChoiceOptions or ToolChoiceFunction or ToolChoiceMcp (default: "auto")

模型选择工具的方式。提供一种字符串模式，或强制调用指定的 函数或 MCP 工具。

• ToolChoiceOptions = "none" or "auto" or "required"

控制模型调用哪个工具，或是否调用工具。

none 表示模型不调用工具，而是生成消息。

auto 表示模型可以选择生成消息，或调用一个或 多个工具。

required 表示模型必须调用一个或多个工具。

• "none"

• "auto"

• "required"

• ToolChoiceFunction object { name, type }

使用此选项强制模型调用指定函数。

• name: string

要调用的函数名称。

• type: "function"

对于函数调用，类型固定为 function。

• "function"

• ToolChoiceMcp object { server_label, type, name }

使用此选项强制模型调用远程 MCP 服务器上的指定工具。

• server_label: string

要使用的 MCP 服务器标签。

• type: "mcp"

对于 MCP 工具，类型固定为 mcp。

• "mcp"

• name: optional string or null

要在服务器上调用的工具名称。

• tools: optional array of RealtimeFunctionTool or McpTool { server_label, type, allowed_callers, 9 more }

模型可用的工具。

• RealtimeFunctionTool object { description, name, parameters, type }

• description: optional string

函数描述，包括何时以及如何 调用该函数的指导，以及调用时应向用户说明什么 内容，如需说明。

• name: optional string

函数名称。

• parameters: optional unknown

以 JSON Schema 描述的函数参数。

• type: optional "function"

工具类型，即 function。

• "function"

• McpTool object { server_label, type, allowed_callers, 9 more }

通过远程模型上下文协议（MCP）服务器， 向模型提供额外工具。了解 MCP。

• server_label: string

此 MCP 服务器的标签，用于在工具调用中标识服务器。

• type: "mcp"

MCP 工具类型，固定为 mcp。

• "mcp"

• allowed_callers: optional array of "direct" or "programmatic" or null

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• allowed_tools: optional array of string or McpToolFilter { read_only, tool_names } or null

允许的工具名称列表或筛选对象。

• McpAllowedTools = array of string

允许的工具名称组成的字符串数组。

• McpToolFilter object { read_only, tool_names }

用于指定允许哪些工具的筛选对象。

• read_only: optional boolean

表示工具会修改数据还是只读。如果 MCP 服务器标注了 readOnlyHint， 就会与此筛选条件匹配。

• tool_names: optional array of string

允许的工具名称列表。

• authorization: optional string

可用于远程 MCP 服务器的 OAuth 访问令牌，既可 配合自定义 MCP 服务器 URL，也可配合服务连接器。你的应用 须处理 OAuth 授权流程，并在此提供令牌。

• connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more

服务连接器的标识，例如 ChatGPT 中提供的连接器。须提供 server_url、connector_id 或 tunnel_id 中的一项。更多 服务连接器信息参阅此处。

对于 2026 年 9 月 1 日之后发布的模型，此字段已弃用。 使用 server_url 连接远程 MCP 服务器，或使用 tunnel_id 通过安全 MCP 隧道连接。

当前支持的 connector_id 值如下：

• Dropbox：connector_dropbox
• Gmail：connector_gmail
• Google 日历：connector_googlecalendar
• Google 云端硬盘：connector_googledrive
• Microsoft Teams：connector_microsoftteams
• Outlook 日历：connector_outlookcalendar
• Outlook 邮箱：connector_outlookemail
• SharePoint：connector_sharepoint

• "connector_dropbox"

• "connector_gmail"

• "connector_googlecalendar"

• "connector_googledrive"

• "connector_microsoftteams"

• "connector_outlookcalendar"

• "connector_outlookemail"

• "connector_sharepoint"

• defer_loading: optional boolean

此 MCP 工具是否延迟加载并通过工具搜索发现。

• headers: optional map[string] or null

可选的发送给 MCP 服务器的 HTTP 请求头，用于认证 或其他用途。

• require_approval: optional McpToolApprovalFilter { always, never } or "always" or "never" or null (default: "always")

指定 MCP 服务器的哪些工具需要批准。

• McpToolApprovalFilter object { always, never }

指定 MCP 服务器的哪些工具需要批准。可以是 always、never，或与需要批准的工具关联的 筛选对象。

• always: optional object { read_only, tool_names }

用于指定允许哪些工具的筛选对象。

• read_only: optional boolean

表示工具会修改数据还是只读。如果 MCP 服务器标注了 readOnlyHint， 就会与此筛选条件匹配。

• tool_names: optional array of string

允许的工具名称列表。

• never: optional object { read_only, tool_names }

用于指定允许哪些工具的筛选对象。

• read_only: optional boolean

表示工具会修改数据还是只读。如果 MCP 服务器标注了 readOnlyHint， 就会与此筛选条件匹配。

• tool_names: optional array of string

允许的工具名称列表。

• McpToolApprovalSetting = "always" or "never"

为所有工具指定统一的批准策略，可选 always 或 never。设为 always 时，所有工具均需要批准； 设为 never 时，所有工具均不需要批准。

• "always"

• "never"

• server_description: optional string

MCP 服务器的可选描述，用于提供更多上下文。

• server_url: optional string

MCP 服务器的 URL。须提供 server_url、connector_id 或 tunnel_id 中的一项。

format: uri

• tunnel_id: optional string

用来替代直接服务器 URL 的安全 MCP 隧道 ID。须提供 server_url、connector_id 或 tunnel_id 中的一项。

pattern: ^tunnel_[a-z0-9]{32}$

示例

// 使用默认对话，不传额外参数，触发响应
{
  "type": "response.create"
}

// 触发不写入默认对话的带外响应
{
  "type": "response.create",
  "response": {
    "instructions": "给出简洁的回答。",
    "tools": [], // 清空会话工具
    "conversation": "none",
    "output_modalities": ["text"],
    "metadata": {
      "response_purpose": "summarization"
    },
    "input": [
      {
        "type": "item_reference",
        "id": "item_12345"
      },
      {
        "type": "message",
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "用一句话总结上述消息。"
          }
        ]
      }
    ]
  }
}

response.cancel

发送此事件以取消正在进行的响应。服务端将响应 response.done，状态为 response.status=cancelled。如果 没有可取消的响应，则返回错误。即使没有响应正在进行， 调用 response.cancel 也是安全的：会返回错误， 但不影响会话。

结构定义

模式名称：RealtimeClientEventResponseCancel

• type: "response.cancel"

事件类型，须为 response.cancel。

• "response.cancel"

• event_id: optional string

客户端生成的可选 ID，用于标识此事件。

maxLength: 512

• response_id: optional string

要取消的具体响应 ID。未提供时，取消默认对话中 正在进行的响应。

示例

{
    "type": "response.cancel",
    "response_id": "resp_12345"
}

output_audio_buffer.clear

仅限 WebRTC/SIP：发出此事件以截断当前音频响应，触发服务端 停止生成音频并发出 output_audio_buffer.cleared。 此前应先发送 response.cancel 客户端事件， 停止当前响应的生成。 了解更多。

结构定义

模式名称：RealtimeClientEventOutputAudioBufferClear

• type: "output_audio_buffer.clear"

事件类型，须为 output_audio_buffer.clear。

• "output_audio_buffer.clear"

• event_id: optional string

用于错误处理的客户端事件的唯一 ID。

示例

{
    "event_id": "optional_client_event_id",
    "type": "output_audio_buffer.clear"
}