OpenAI Realtime 接口参考

Realtime 资源

连接

Realtime API 可用于构建低延迟的多模态对话体验，目前支持文本和音频输入、文本和音频输出，以及函数调用。

此 API 的主要优势包括：

• 原生语音到语音：无需经过中间文本形式，延迟更低，输出也能保留细腻的表达。
• 自然且可引导的音色：模型具有自然的语调变化，可以笑、低声说话，并遵循语气指导。
• 同时输出多种模态：文本便于审核；快于实时速度生成音频，有助于稳定播放。

Realtime API 是通过 WebSocket 通信的有状态、基于事件的 API。 启动 Realtime 对话时，在连接 URL 中设置 model；加入已有呼叫时，改为设置 call_id。转录会话使用 intent=transcription。

使用下方 URL 打开 WebSocket 连接，在握手时提供路径参数、查询参数和认证信息。连接后，以 JSON 消息发送客户端事件、接收服务端事件，结束后关闭连接。

WebSocket：wss://api.openai.com/v1/realtime

认证

使用 Bearer 认证，通过 Authorization 请求头提供凭据。

连接参数

• model：查询参数，字符串，可选。

• call_id：查询参数，字符串，可选。

• intent：查询参数，枚举，可选，值为 realtime 或 transcription。

选择会话类型。转录会话须设为 transcription，并省略 model。省略时，如提供了客户端密钥，则采用其中的会话类型；否则 intent 为 realtime。

事件

客户端事件

服务端事件

资源类型

音频转录

• AudioTranscription object { delay, keywords, language, 3 more }

• 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 时不支持提示词。

对话创建事件

• ConversationCreatedEvent object { conversation, event_id, type }

对话创建后返回，在会话创建后立即发出。

• conversation: object { id, object }

对话资源。

• id: optional string

对话的唯一 ID。

• object: optional string

对象类型，须为 realtime.conversation。

• event_id: string

服务端事件的唯一 ID。

• type: "conversation.created"

事件类型，须为 conversation.created。

• "conversation.created"

对话条目

• ConversationItem = RealtimeConversationItemSystemMessage or RealtimeConversationItemUserMessage or RealtimeConversationItemAssistantMessage or 6 more

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"

对话条目添加

• ConversationItemAdded object { event_id, item, type, previous_item_id }

服务端向默认对话添加条目时发送，可能出现在以下情况：

• 客户端发送 conversation.item.create 事件。
• 输入音频缓冲区被提交。此时，条目是包含缓冲区音频的用户消息。
• 模型正在生成响应。模型开始生成具体条目时发送 conversation.item.added，因此此时尚无内容，且 status 为 in_progress。

除模型正在生成响应的情况外，此事件包含条目的完整内容，但不包含音频数据。如有需要，可用 conversation.item.retrieve 单独获取音频。

• event_id: string

服务端事件的唯一 ID。

• 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.added"

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

• "conversation.item.added"

• previous_item_id: optional string or null

此条目前一个条目的 ID，如有，用于 维护插入条目时的顺序。

对话条目创建事件

• ConversationItemCreateEvent object { item, type, event_id, previous_item_id }

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

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

• 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，会返回错误，且不会添加条目。

对话条目创建事件

• ConversationItemCreatedEvent object { event_id, item, type, previous_item_id }

对话条目创建后返回，可能由以下情况产生：

• 服务端正在生成响应，成功时会生成 一个或两个条目，类型为 message （角色为 assistant）或 function_call。
• 输入音频缓冲区由客户端或 服务端（server_vad 模式）提交。服务端取出缓冲区内容， 添加到新的用户消息条目。
• 客户端发送 conversation.item.create，向 对话添加新条目。

• event_id: string

服务端事件的唯一 ID。

• 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.created"

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

• "conversation.item.created"

• previous_item_id: optional string or null

对话上下文中前一个条目的 ID，可让 客户端了解对话顺序。条目没有前驱时，可以为 null。

对话条目删除事件

• ConversationItemDeleteEvent object { item_id, type, event_id }

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

• item_id: string

要删除的条目的 ID。

• type: "conversation.item.delete"

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

• "conversation.item.delete"

• event_id: optional string

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

maxLength: 512

对话条目删除事件

• ConversationItemDeletedEvent object { event_id, item_id, type }

客户端通过 conversation.item.delete 删除 对话条目后返回。此事件用于同步 服务端与客户端所理解的对话历史。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

已删除条目的 ID。

• type: "conversation.item.deleted"

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

• "conversation.item.deleted"

对话条目完成

• ConversationItemDone object { event_id, item, type, previous_item_id }

对话条目最终确定后返回。

此事件包含条目的完整内容，但不包含音频数据。如有需要，可通过 conversation.item.retrieve 单独获取音频。

• event_id: string

服务端事件的唯一 ID。

• 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.done"

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

• "conversation.item.done"

• previous_item_id: optional string or null

此条目前一个条目的 ID，如有，用于 维护插入条目时的顺序。

对话条目输入音频转录完成事件

• ConversationItemInputAudioTranscriptionCompletedEvent object { content_index, event_id, item_id, 5 more }

此事件是写入用户音频缓冲区的 用户音频的转录输出。输入音频缓冲区由 客户端或服务端（启用 VAD 时）提交后，开始转录。转录与 响应创建异步执行，因此此事件可能在响应事件之前 或之后出现。

Realtime API 模型原生接受音频，因此输入转录是 由独立 ASR（自动语音识别）模型运行的单独过程。 转录可能与模型对音频的理解有所差别， 应仅作为大致参考。

• content_index: integer

包含音频的内容部分的索引。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

包含待转录音频的条目的 ID。

• transcript: string

转录文本。

• type: "conversation.item.input_audio_transcription.completed"

事件类型，须为 conversation.item.input_audio_transcription.completed.

• "conversation.item.input_audio_transcription.completed"

• usage: Tokens { input_tokens, output_tokens, total_tokens, 2 more } or Duration { seconds, type }

转录的用量统计。按 ASR 模型的价格计费，而非 Realtime 模型的价格。

• Tokens object { input_tokens, output_tokens, total_tokens, 2 more }

按词元计费的模型用量统计。

• input_tokens: integer

此请求计费的输入词元数量。

• output_tokens: integer

生成的输出词元数量。

• total_tokens: integer

使用的词元总数，为输入与输出之和。

• type: "tokens"

用量对象的类型，此变体固定为 tokens。

• "tokens"

• input_token_details: optional object { audio_tokens, text_tokens }

此请求计费输入词元的明细。

• audio_tokens: optional integer

此请求计费的音频词元数量。

• text_tokens: optional integer

此请求计费的文本词元数量。

• Duration object { seconds, type }

按音频输入时长计费的模型用量统计。

• seconds: number

输入音频时长，单位为秒。

format: double

• type: "duration"

用量对象的类型，此变体固定为 duration。

• "duration"

• languages: optional array of TranscriptionLanguage

音频中检测到的语言，由 gpt-transcribe 返回。空数组表示未能可靠识别语言。

• code: string

音频中检测到的语言代码。

• logprobs: optional array of LogProbProperties or null

转录的对数概率。

• token: string

用于生成对数概率的词元。

• bytes: array of number

用于生成对数概率的字节。

• logprob: number

词元的对数概率。

对话条目输入音频转录增量事件

• ConversationItemInputAudioTranscriptionDeltaEvent object { event_id, item_id, type, 3 more }

输入音频转录内容部分的文本值被增量转录结果更新时返回。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

包含待转录音频的条目的 ID。

• type: "conversation.item.input_audio_transcription.delta"

事件类型，须为 conversation.item.input_audio_transcription.delta。

• "conversation.item.input_audio_transcription.delta"

• content_index: optional integer

内容部分在条目 content 数组中的索引。

• delta: optional string

文本增量。

• logprobs: optional array of LogProbProperties or null

转录的对数概率。可通过会话配置 "include": ["item.input_audio_transcription.logprobs"] 启用。数组中每项对应这一转录片段选取某个词元的对数概率，有助于识别该片段是否可能存在多个有效选项。

• token: string

用于生成对数概率的词元。

• bytes: array of number

用于生成对数概率的字节。

• logprob: number

词元的对数概率。

对话条目输入音频转录失败事件

• ConversationItemInputAudioTranscriptionFailedEvent object { content_index, error, event_id, 2 more }

已配置输入音频转录，但用户消息的 转录请求失败时返回。这类事件独立于其他 error 事件，以便客户端识别关联条目。

• content_index: integer

包含音频的内容部分的索引。

• error: object { code, message, param, type }

转录错误详情。

• code: optional string

错误代码（如有）。

• message: optional string

便于人类阅读的错误消息。

• param: optional string

与错误有关的参数（如有）。

• type: optional string

错误类型。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

用户消息条目的 ID。

• type: "conversation.item.input_audio_transcription.failed"

事件类型，须为 conversation.item.input_audio_transcription.failed.

• "conversation.item.input_audio_transcription.failed"

对话条目输入音频转录分段

• ConversationItemInputAudioTranscriptionSegment object { id, content_index, end, 6 more }

识别出条目的输入音频转录分段时返回。

• id: string

分段标识。

• content_index: integer

输入音频内容部分在条目中的索引。

• end: number

分段结束时间，单位为秒。

format: double

• event_id: string

服务端事件的唯一 ID。

• item_id: string

包含输入音频内容的条目的 ID。

• speaker: string

为此分段检测到的说话人标签。

• start: number

分段开始时间，单位为秒。

format: double

• text: string

此分段的文本。

• type: "conversation.item.input_audio_transcription.segment"

事件类型，须为 conversation.item.input_audio_transcription.segment。

• "conversation.item.input_audio_transcription.segment"

对话条目获取事件

• ConversationItemRetrieveEvent object { item_id, type, event_id }

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

• item_id: string

要获取的条目的 ID。

• type: "conversation.item.retrieve"

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

• "conversation.item.retrieve"

• event_id: optional string

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

maxLength: 512

对话条目截断事件

• ConversationItemTruncateEvent object { audio_end_ms, content_index, item_id, 2 more }

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

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

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

• 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

对话条目截断事件

• ConversationItemTruncatedEvent object { audio_end_ms, content_index, event_id, 2 more }

客户端通过 conversation.item.truncate 截断 此前的助手音频消息条目后返回。此事件用于 同步服务端对音频的理解与客户端播放状态。

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

• audio_end_ms: integer

音频截断到的时长，单位为毫秒。

• content_index: integer

被截断的内容部分的索引。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

被截断的助手消息条目的 ID。

• type: "conversation.item.truncated"

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

• "conversation.item.truncated"

对话条目带有引用

• ConversationItemWithReference object { id, arguments, call_id, 7 more }

要添加到对话的条目。

• id: optional string

对于 message、function_call 或 function_call_output 类型的条目， 此字段允许客户端分配唯一 ID。 非必填，未提供时由服务端生成。

对于 item_reference 类型的条目，此字段必填， 引用此前曾存在于对话中的任意条目。

• arguments: optional string

函数调用参数，适用于 function_call 条目。

• call_id: optional string

函数调用 ID，适用于 function_call 和 function_call_output 条目。如果在 function_call_output 条目中提供，服务端会检查对话历史中是否存在相同 ID 的 function_call 条目。

• content: optional array of object { id, audio, text, 2 more }

消息内容，适用于 message 条目。

• system 角色的消息条目仅支持 input_text 内容。
• user 角色的消息条目支持 input_text 和 input_audio 内容。
• assistant 角色的消息条目支持 text 内容。

• id: optional string

要引用的此前对话条目的 ID，适用于 response.create 事件中的 item_reference 内容类型。可引用客户端 或服务端创建的条目。

• audio: optional string

Base64 编码的音频字节，用于 input_audio 内容类型。

• text: optional string

文本内容，用于 input_text 和 text 内容类型。

• transcript: optional string

音频转录文本，用于 input_audio 内容类型。

• type: optional "input_audio" or "input_text" or "item_reference" or "text"

内容类型：input_text、input_audio、item_reference 或 text。

• "input_audio"

• "input_text"

• "item_reference"

• "text"

• name: optional string

被调用的函数名称，适用于 function_call 条目。

• object: optional "realtime.item"

返回的 API 对象标识，固定为 realtime.item。

• "realtime.item"

• output: optional string

函数调用的输出，适用于 function_call_output 条目。

• role: optional "user" or "assistant" or "system"

消息发送者角色，可选 user、assistant 或 system，仅 适用于 message 条目。

• "user"

• "assistant"

• "system"

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

条目状态，可选 completed、incomplete 或 in_progress，不影响 对话，但为与 conversation.item.created 事件保持一致而接受这些值。

• "completed"

• "incomplete"

• "in_progress"

• type: optional "message" or "function_call" or "function_call_output"

条目类型：message、function_call、function_call_output 或 item_reference。

• "message"

• "function_call"

• "function_call_output"

输入音频缓冲区追加事件

• InputAudioBufferAppendEvent object { audio, type, event_id }

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

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

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

• 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

输入音频缓冲区清空事件

• InputAudioBufferClearEvent object { type, event_id }

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

• type: "input_audio_buffer.clear"

事件类型，须为 input_audio_buffer.clear。

• "input_audio_buffer.clear"

• event_id: optional string

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

maxLength: 512

输入音频缓冲区清空事件

• InputAudioBufferClearedEvent object { event_id, type }

客户端通过 input_audio_buffer.clear 清空输入音频缓冲区后返回。

• event_id: string

服务端事件的唯一 ID。

• type: "input_audio_buffer.cleared"

事件类型，须为 input_audio_buffer.cleared。

• "input_audio_buffer.cleared"

输入音频缓冲区提交事件

• InputAudioBufferCommitEvent object { type, event_id }

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

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

• type: "input_audio_buffer.commit"

事件类型，须为 input_audio_buffer.commit。

• "input_audio_buffer.commit"

• event_id: optional string

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

maxLength: 512

输入音频缓冲区提交事件

• InputAudioBufferCommittedEvent object { event_id, item_id, type, previous_item_id }

输入音频缓冲区由客户端提交，或在服务端 VAD 模式中 自动提交后返回。item_id 是将要创建的用户 消息条目的 ID，因此也会向客户端发送 conversation.item.created。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

将创建的用户消息条目的 ID。

• type: "input_audio_buffer.committed"

事件类型，须为 input_audio_buffer.committed。

• "input_audio_buffer.committed"

• previous_item_id: optional string or null

新条目要插入在哪个条目之后，即前一个条目的 ID。 条目没有前驱时，可以为 null。

输入音频缓冲区 DTMF 接收事件

• InputAudioBufferDtmfEventReceivedEvent object { event, received_at, type }

仅限 SIP：收到 DTMF 事件后返回。DTMF 事件表示 电话键盘按键，取值为 0–9、*、# 或 A–D。event 属性 是用户按下的键，received_at 是服务端收到事件时的 UTC Unix 时间戳。

• event: string

用户按下的电话键盘按键。

• received_at: integer

服务端收到 DTMF 事件时的 UTC Unix 时间戳。

• type: "input_audio_buffer.dtmf_event_received"

事件类型，须为 input_audio_buffer.dtmf_event_received。

• "input_audio_buffer.dtmf_event_received"

输入音频缓冲区语音开始事件

• InputAudioBufferSpeechStartedEvent object { audio_start_ms, event_id, item_id, type }

在 server_vad 模式下，服务端发送此事件，表示 在音频缓冲区检测到语音。向缓冲区追加音频时，随时可能发生， 但已处于检测到语音状态时除外。客户端可用此事件 打断音频播放，或向用户提供视觉反馈。

语音停止时，客户端应收到 input_audio_buffer.speech_stopped。 item_id 为语音停止时将创建的用户消息条目的 ID， 也会包含在 input_audio_buffer.speech_stopped 中，但客户端在 VAD 活动期间 手动提交音频缓冲区的情况除外。

• audio_start_ms: integer

首次检测到语音时，相对于会话期间写入缓冲区的 全部音频开头的毫秒数。这对应发送给模型的 音频的起点，因此包含会话中配置的 prefix_padding_ms。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

语音停止时将创建的用户消息条目的 ID。

• type: "input_audio_buffer.speech_started"

事件类型，须为 input_audio_buffer.speech_started。

• "input_audio_buffer.speech_started"

输入音频缓冲区语音停止事件

• InputAudioBufferSpeechStoppedEvent object { audio_end_ms, event_id, item_id, type }

在 server_vad 模式下，服务端检测到音频缓冲区中 语音结束时返回。服务端也会发送 conversation.item.created， 其中包含根据音频缓冲区创建的用户消息条目。

• audio_end_ms: integer

语音停止时，自会话开始起的毫秒数。这对应发送给模型的 音频的终点，因此包含会话中配置的 min_silence_duration_ms。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

将创建的用户消息条目的 ID。

• type: "input_audio_buffer.speech_stopped"

事件类型，须为 input_audio_buffer.speech_stopped。

• "input_audio_buffer.speech_stopped"

输入音频缓冲区超时触发

• InputAudioBufferTimeoutTriggered object { audio_end_ms, audio_start_ms, event_id, 2 more }

输入音频缓冲区的服务端 VAD 超时触发时返回，通过会话 turn_detection 设置中的 idle_timeout_ms 配置，表示 在配置的时长内没有检测到语音。

audio_start_ms 和 audio_end_ms 标识上次模型响应之后到超时触发 时的音频片段，数值为相对于写入输入音频缓冲区的 音频开头的偏移量。因此它划分出静音片段， 开始与结束值之差大致等于配置的超时时长。

静音音频会作为 input_audio 条目提交到对话，并发出 input_audio_buffer.committed，随后生成模型响应。音频中可能有 未触发 VAD 但仍能被模型检测到的语音，因此模型可能给出 与对话相关的响应，或提示用户继续讲话。

• audio_end_ms: integer

超时触发时，相对于写入输入音频缓冲区的音频开头的毫秒偏移量。

• audio_start_ms: integer

上次模型响应播放结束后，相对于写入输入音频缓冲区的音频开头的毫秒偏移量。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

与此片段关联的条目 ID。

• type: "input_audio_buffer.timeout_triggered"

事件类型，须为 input_audio_buffer.timeout_triggered。

• "input_audio_buffer.timeout_triggered"

对数概率属性

• LogProbProperties object { token, bytes, logprob }

对数概率对象。

• token: string

用于生成对数概率的词元。

• bytes: array of number

用于生成对数概率的字节。

• logprob: number

词元的对数概率。

MCP 工具列表完成

• McpListToolsCompleted object { event_id, item_id, type }

条目的 MCP 工具列表获取完成时返回。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

MCP 工具列表条目的 ID。

• type: "mcp_list_tools.completed"

事件类型，须为 mcp_list_tools.completed。

• "mcp_list_tools.completed"

MCP 工具列表失败

• McpListToolsFailed object { event_id, item_id, type }

条目的 MCP 工具列表获取失败时返回。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

MCP 工具列表条目的 ID。

• type: "mcp_list_tools.failed"

事件类型，须为 mcp_list_tools.failed。

• "mcp_list_tools.failed"

MCP 工具列表进行中

• McpListToolsInProgress object { event_id, item_id, type }

条目的 MCP 工具列表正在获取时返回。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

MCP 工具列表条目的 ID。

• type: "mcp_list_tools.in_progress"

事件类型，须为 mcp_list_tools.in_progress。

• "mcp_list_tools.in_progress"

降噪类型

• NoiseReductionType = "near_field" or "far_field"

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

• "near_field"

• "far_field"

输出音频缓冲区清空事件

• OutputAudioBufferClearEvent object { type, event_id }

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

• type: "output_audio_buffer.clear"

事件类型，须为 output_audio_buffer.clear。

• "output_audio_buffer.clear"

• event_id: optional string

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

速率限制更新事件

• RateLimitsUpdatedEvent object { event_id, rate_limits, type }

在响应开始时发出，表示更新后的速率限制。 创建响应时，会为输出预留部分词元； 此处的速率限制反映该预留，随后 在响应完成时相应调整。

• event_id: string

服务端事件的唯一 ID。

• rate_limits: array of object { limit, name, remaining, reset_seconds }

速率限制信息列表。

• limit: optional integer

速率限制允许的最大值。

• name: optional "requests" or "tokens"

速率限制名称：requests 或 tokens。

• "requests"

• "tokens"

• remaining: optional integer

达到限制前的剩余额度。

• reset_seconds: optional number

速率限制重置前的秒数。

• type: "rate_limits.updated"

事件类型，须为 rate_limits.updated。

• "rate_limits.updated"

Realtime 音频配置

• RealtimeAudioConfig object { input, output }

输入和输出音频的配置。

• 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。

Realtime 音频配置输入

• RealtimeAudioConfigInput object { format, noise_reduction, transcription, turn_detection }

• 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）的响应。

Realtime 音频配置输出

• RealtimeAudioConfigOutput object { format, speed, 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"

• 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。

Realtime 音频格式

• RealtimeAudioFormats = PCMAudio { rate, type } or PCMUAudio { type } or PCMAAudio { type }

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

• 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"

Realtime 音频输入轮次检测

• RealtimeAudioInputTurnDetection = ServerVad { type, create_response, idle_timeout_ms, 4 more } or SemanticVad { type, create_response, eagerness, interrupt_response }

轮次检测配置，可使用服务端 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）的响应。

Realtime 客户端事件

• RealtimeClientEvent = ConversationItemCreateEvent or ConversationItemDeleteEvent or ConversationItemRetrieveEvent or 8 more

Realtime 客户端事件。

• ConversationItemCreateEvent object { item, type, event_id, previous_item_id }

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

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

• 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，会返回错误，且不会添加条目。

• ConversationItemDeleteEvent object { item_id, type, event_id }

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

• item_id: string

要删除的条目的 ID。

• type: "conversation.item.delete"

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

• "conversation.item.delete"

• event_id: optional string

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

maxLength: 512

• ConversationItemRetrieveEvent object { item_id, type, event_id }

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

• item_id: string

要获取的条目的 ID。

• type: "conversation.item.retrieve"

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

• "conversation.item.retrieve"

• event_id: optional string

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

maxLength: 512

• ConversationItemTruncateEvent object { audio_end_ms, content_index, item_id, 2 more }

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

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

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

• 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

• InputAudioBufferAppendEvent object { audio, type, event_id }

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

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

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

• 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

• InputAudioBufferClearEvent object { type, event_id }

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

• type: "input_audio_buffer.clear"

事件类型，须为 input_audio_buffer.clear。

• "input_audio_buffer.clear"

• event_id: optional string

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

maxLength: 512

• OutputAudioBufferClearEvent object { type, event_id }

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

• type: "output_audio_buffer.clear"

事件类型，须为 output_audio_buffer.clear。

• "output_audio_buffer.clear"

• event_id: optional string

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

• InputAudioBufferCommitEvent object { type, event_id }

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

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

• type: "input_audio_buffer.commit"

事件类型，须为 input_audio_buffer.commit。

• "input_audio_buffer.commit"

• event_id: optional string

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

maxLength: 512

• ResponseCancelEvent object { type, event_id, response_id }

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

• type: "response.cancel"

事件类型，须为 response.cancel。

• "response.cancel"

• event_id: optional string

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

maxLength: 512

• response_id: optional string

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

• ResponseCreateEvent object { type, event_id, response }

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

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

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

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

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

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

• 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}$

• SessionUpdateEvent object { session, type, event_id }

发送此事件更新会话配置。 客户端可随时发送此事件更新字段， 但 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 会保留当前设置。

• 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

输入音频格式。

• 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

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

• reasoning: optional RealtimeReasoning

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

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

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

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

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

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

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

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

• ToolChoiceFunction object { name, type }

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

• ToolChoiceMcp object { server_label, type, name }

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

• tools: optional RealtimeToolsConfig

模型可用的工具。

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

• 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

Realtime 对话条目：助手消息

• 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"

Realtime 对话条目函数调用

• 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"

Realtime 对话条目函数调用输出

• 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"

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"

Realtime 对话条目：用户消息

• 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"

Realtime 错误

• RealtimeError object { message, type, code, 2 more }

错误详情。

• message: string

便于人类阅读的错误消息。

• type: string

错误类型，例如 "invalid_request_error" 或 "server_error"。

• code: optional string or null

错误代码（如有）。

• event_id: optional string or null

导致错误的客户端事件 event_id（如适用）。

• param: optional string or null

与错误有关的参数（如有）。

Realtime 错误事件

• RealtimeErrorEvent object { error, event_id, type }

发生错误时返回，错误可能来自客户端或服务端 问题。大多数错误可恢复，会话会保持打开。 建议默认监控并记录错误消息。

• error: RealtimeError

错误详情。

• message: string

便于人类阅读的错误消息。

• type: string

错误类型，例如 "invalid_request_error" 或 "server_error"。

• code: optional string or null

错误代码（如有）。

• event_id: optional string or null

导致错误的客户端事件 event_id（如适用）。

• param: optional string or null

与错误有关的参数（如有）。

• event_id: string

服务端事件的唯一 ID。

• type: "error"

事件类型，须为 error。

• "error"

Realtime 函数工具

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

• description: optional string

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

• name: optional string

函数名称。

• parameters: optional unknown

以 JSON Schema 描述的函数参数。

• type: optional "function"

工具类型，即 function。

• "function"

Realtime MCP 批准请求

• 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"

Realtime MCP 批准响应

• 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

决定的可选理由。

Realtime MCP 工具列表

• 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。

Realtime MCP 协议错误

• RealtimeMcpProtocolError object { code, message, type }

• code: integer

• message: string

• type: "protocol_error"

• "protocol_error"

Realtime MCP工具调用

• 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

工具调用的输出。

Realtime MCP 工具执行错误

• RealtimeMcpToolExecutionError object { message, type }

• message: string

• type: "tool_execution_error"

• "tool_execution_error"

Realtime MCP HTTP 错误

• RealtimeMcphttpError object { code, message, type }

• code: integer

• message: string

• type: "http_error"

• "http_error"

Realtime 推理

• RealtimeReasoning object { effort }

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

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

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

• "minimal"

• "low"

• "medium"

• "high"

• "xhigh"

Realtime 推理强度

• RealtimeReasoningEffort = "minimal" or "low" or "medium" or 2 more

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

• "minimal"

• "low"

• "medium"

• "high"

• "xhigh"

Realtime 响应

• RealtimeResponse object { id, audio, conversation_id, 8 more }

响应资源。

• id: optional string

响应的唯一 ID，形式类似 resp_1234。

• audio: optional object { output }

音频输出配置。

• 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 (default: "alloy")

模型响应使用的音色。在模型至少输出过一次音频后， 该会话期间不能再更改音色。当前 音色选项包括 alloy、ash、ballad、coral、echo、sage、 shimmer、verse、marin 和 cedar。建议使用 marin 和 cedar， 以获得最佳质量。

• string

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

模型响应使用的音色。在模型至少输出过一次音频后， 该会话期间不能再更改音色。当前 音色选项包括 alloy、ash、ballad、coral、echo、sage、 shimmer、verse、marin 和 cedar。建议使用 marin 和 cedar， 以获得最佳质量。

• "alloy"

• "ash"

• "ballad"

• "coral"

• "echo"

• "sage"

• "shimmer"

• "verse"

• "marin"

• "cedar"

• conversation_id: optional string

响应添加到哪个对话，由 response.create 中的 conversation 字段决定。为 auto 时，响应添加到 默认对话，conversation_id 为类似 conv_1234 的 ID。为 none 时，不添加到任何对话， conversation_id 为 null。如果响应由 VAD 自动触发，则添加到默认对话。

• max_output_tokens: optional number or "inf"

单次助手响应的最大输出词元数， 包括工具调用在内，本次响应使用的内容。

• number

• "inf"

• "inf"

• metadata: optional Metadata or null

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

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

• object: optional "realtime.response"

对象类型，须为 realtime.response。

• "realtime.response"

• output: optional array of ConversationItem

响应生成的输出条目列表。

• 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"

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

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

• "text"

• "audio"

• status: optional "completed" or "cancelled" or "failed" or 2 more

响应最终状态，可选 completed、cancelled、failed 或 incomplete, in_progress).

• "completed"

• "cancelled"

• "failed"

• "incomplete"

• "in_progress"

• status_details: optional RealtimeResponseStatus

状态的额外详情。

• error: optional object { code, message, type }

导致响应失败的错误的描述， 在 status 为 failed 时填充。

• code: optional string

错误代码（如有）。

• message: optional string

便于人类阅读的错误消息。

• type: optional string

错误类型。

• reason: optional "turn_detected" or "client_cancelled" or "max_output_tokens" or "content_filter"

响应未正常完成的原因。对于 cancelled，可为 turn_detected，即服务端 VAD 检测到新的语音开始，或 client_cancelled，即客户端发送取消事件。对于 incomplete，可为 max_output_tokens，或 content_filter，即服务端安全过滤器触发并截断响应。

• "turn_detected"

• "client_cancelled"

• "max_output_tokens"

• "content_filter"

• type: optional "completed" or "cancelled" or "failed" or "incomplete"

导致响应失败的错误类型，对应 status 字段的 completed、cancelled、incomplete、 failed).

• "completed"

• "cancelled"

• "failed"

• "incomplete"

• usage: optional RealtimeResponseUsage

响应的用量统计，对应计费。Realtime API 会话会维护对话上下文，并向对话追加新 条目，因此此前轮次的输出（文本和 音频词元）会成为后续轮次的输入。

• input_token_details: optional RealtimeResponseUsageInputTokenDetails

本次响应的输入词元详情。缓存词元是此前对话轮次中作为当前响应上下文的词元。缓存词元是输入词元的子集，因此输入词元包含缓存和未缓存词元。

• audio_tokens: optional integer

本次响应用作输入的音频词元数。

• cached_tokens: optional integer

本次响应用作输入的缓存词元数。

• cached_tokens_details: optional object { audio_tokens, image_tokens, text_tokens }

本次响应用作输入的缓存词元详情。

• audio_tokens: optional integer

本次响应用作输入的缓存音频词元数。

• image_tokens: optional integer

本次响应用作输入的缓存图像词元数。

• text_tokens: optional integer

本次响应用作输入的缓存文本词元数。

• image_tokens: optional integer

本次响应用作输入的图像词元数。

• text_tokens: optional integer

本次响应用作输入的文本词元数。

• input_tokens: optional integer

本次响应的输入词元数，包括文本和 音频词元。

• output_token_details: optional RealtimeResponseUsageOutputTokenDetails

本次响应的输出词元详情。

• audio_tokens: optional integer

本次响应使用的音频词元数。

• text_tokens: optional integer

本次响应使用的文本词元数。

• output_tokens: optional integer

本次响应发送的输出词元数，包括文本和 音频词元。

• total_tokens: optional integer

本次响应的词元总数，包括输入与输出的 文本和音频词元。

Realtime 响应创建音频输出

• RealtimeResponseCreateAudioOutput object { output }

音频输入和输出配置。

• 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。

Realtime 响应创建参数

• RealtimeResponseCreateParams object { audio, conversation, input, 9 more }

使用这些参数创建新的 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}$

Realtime 响应状态

• RealtimeResponseStatus object { error, reason, type }

状态的额外详情。

• error: optional object { code, message, type }

导致响应失败的错误的描述， 在 status 为 failed 时填充。

• code: optional string

错误代码（如有）。

• message: optional string

便于人类阅读的错误消息。

• type: optional string

错误类型。

• reason: optional "turn_detected" or "client_cancelled" or "max_output_tokens" or "content_filter"

响应未正常完成的原因。对于 cancelled，可为 turn_detected，即服务端 VAD 检测到新的语音开始，或 client_cancelled，即客户端发送取消事件。对于 incomplete，可为 max_output_tokens，或 content_filter，即服务端安全过滤器触发并截断响应。

• "turn_detected"

• "client_cancelled"

• "max_output_tokens"

• "content_filter"

• type: optional "completed" or "cancelled" or "failed" or "incomplete"

导致响应失败的错误类型，对应 status 字段的 completed、cancelled、incomplete、 failed).

• "completed"

• "cancelled"

• "failed"

• "incomplete"

Realtime 响应用量

• RealtimeResponseUsage object { input_token_details, input_tokens, output_token_details, 2 more }

响应的用量统计，对应计费。Realtime API 会话会维护对话上下文，并向对话追加新 条目，因此此前轮次的输出（文本和 音频词元）会成为后续轮次的输入。

• input_token_details: optional RealtimeResponseUsageInputTokenDetails

本次响应的输入词元详情。缓存词元是此前对话轮次中作为当前响应上下文的词元。缓存词元是输入词元的子集，因此输入词元包含缓存和未缓存词元。

• audio_tokens: optional integer

本次响应用作输入的音频词元数。

• cached_tokens: optional integer

本次响应用作输入的缓存词元数。

• cached_tokens_details: optional object { audio_tokens, image_tokens, text_tokens }

本次响应用作输入的缓存词元详情。

• audio_tokens: optional integer

本次响应用作输入的缓存音频词元数。

• image_tokens: optional integer

本次响应用作输入的缓存图像词元数。

• text_tokens: optional integer

本次响应用作输入的缓存文本词元数。

• image_tokens: optional integer

本次响应用作输入的图像词元数。

• text_tokens: optional integer

本次响应用作输入的文本词元数。

• input_tokens: optional integer

本次响应的输入词元数，包括文本和 音频词元。

• output_token_details: optional RealtimeResponseUsageOutputTokenDetails

本次响应的输出词元详情。

• audio_tokens: optional integer

本次响应使用的音频词元数。

• text_tokens: optional integer

本次响应使用的文本词元数。

• output_tokens: optional integer

本次响应发送的输出词元数，包括文本和 音频词元。

• total_tokens: optional integer

本次响应的词元总数，包括输入与输出的 文本和音频词元。

Realtime 响应用量：输入词元详情

• RealtimeResponseUsageInputTokenDetails object { audio_tokens, cached_tokens, cached_tokens_details, 2 more }

本次响应的输入词元详情。缓存词元是此前对话轮次中作为当前响应上下文的词元。缓存词元是输入词元的子集，因此输入词元包含缓存和未缓存词元。

• audio_tokens: optional integer

本次响应用作输入的音频词元数。

• cached_tokens: optional integer

本次响应用作输入的缓存词元数。

• cached_tokens_details: optional object { audio_tokens, image_tokens, text_tokens }

本次响应用作输入的缓存词元详情。

• audio_tokens: optional integer

本次响应用作输入的缓存音频词元数。

• image_tokens: optional integer

本次响应用作输入的缓存图像词元数。

• text_tokens: optional integer

本次响应用作输入的缓存文本词元数。

• image_tokens: optional integer

本次响应用作输入的图像词元数。

• text_tokens: optional integer

本次响应用作输入的文本词元数。

Realtime 响应用量：输出词元详情

• RealtimeResponseUsageOutputTokenDetails object { audio_tokens, text_tokens }

本次响应的输出词元详情。

• audio_tokens: optional integer

本次响应使用的音频词元数。

• text_tokens: optional integer

本次响应使用的文本词元数。

Realtime 服务端事件

• RealtimeServerEvent = ConversationCreatedEvent or ConversationItemCreatedEvent or ConversationItemDeletedEvent or 43 more

Realtime 服务端事件。

• ConversationCreatedEvent object { conversation, event_id, type }

对话创建后返回，在会话创建后立即发出。

• conversation: object { id, object }

对话资源。

• id: optional string

对话的唯一 ID。

• object: optional string

对象类型，须为 realtime.conversation。

• event_id: string

服务端事件的唯一 ID。

• type: "conversation.created"

事件类型，须为 conversation.created。

• "conversation.created"

• ConversationItemCreatedEvent object { event_id, item, type, previous_item_id }

对话条目创建后返回，可能由以下情况产生：

• 服务端正在生成响应，成功时会生成 一个或两个条目，类型为 message （角色为 assistant）或 function_call。
• 输入音频缓冲区由客户端或 服务端（server_vad 模式）提交。服务端取出缓冲区内容， 添加到新的用户消息条目。
• 客户端发送 conversation.item.create，向 对话添加新条目。

• event_id: string

服务端事件的唯一 ID。

• 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.created"

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

• "conversation.item.created"

• previous_item_id: optional string or null

对话上下文中前一个条目的 ID，可让 客户端了解对话顺序。条目没有前驱时，可以为 null。

• ConversationItemDeletedEvent object { event_id, item_id, type }

客户端通过 conversation.item.delete 删除 对话条目后返回。此事件用于同步 服务端与客户端所理解的对话历史。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

已删除条目的 ID。

• type: "conversation.item.deleted"

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

• "conversation.item.deleted"

• ConversationItemInputAudioTranscriptionCompletedEvent object { content_index, event_id, item_id, 5 more }

此事件是写入用户音频缓冲区的 用户音频的转录输出。输入音频缓冲区由 客户端或服务端（启用 VAD 时）提交后，开始转录。转录与 响应创建异步执行，因此此事件可能在响应事件之前 或之后出现。

Realtime API 模型原生接受音频，因此输入转录是 由独立 ASR（自动语音识别）模型运行的单独过程。 转录可能与模型对音频的理解有所差别， 应仅作为大致参考。

• content_index: integer

包含音频的内容部分的索引。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

包含待转录音频的条目的 ID。

• transcript: string

转录文本。

• type: "conversation.item.input_audio_transcription.completed"

事件类型，须为 conversation.item.input_audio_transcription.completed.

• "conversation.item.input_audio_transcription.completed"

• usage: Tokens { input_tokens, output_tokens, total_tokens, 2 more } or Duration { seconds, type }

转录的用量统计。按 ASR 模型的价格计费，而非 Realtime 模型的价格。

• Tokens object { input_tokens, output_tokens, total_tokens, 2 more }

按词元计费的模型用量统计。

• input_tokens: integer

此请求计费的输入词元数量。

• output_tokens: integer

生成的输出词元数量。

• total_tokens: integer

使用的词元总数，为输入与输出之和。

• type: "tokens"

用量对象的类型，此变体固定为 tokens。

• "tokens"

• input_token_details: optional object { audio_tokens, text_tokens }

此请求计费输入词元的明细。

• audio_tokens: optional integer

此请求计费的音频词元数量。

• text_tokens: optional integer

此请求计费的文本词元数量。

• Duration object { seconds, type }

按音频输入时长计费的模型用量统计。

• seconds: number

输入音频时长，单位为秒。

format: double

• type: "duration"

用量对象的类型，此变体固定为 duration。

• "duration"

• languages: optional array of TranscriptionLanguage

音频中检测到的语言，由 gpt-transcribe 返回。空数组表示未能可靠识别语言。

• code: string

音频中检测到的语言代码。

• logprobs: optional array of LogProbProperties or null

转录的对数概率。

• token: string

用于生成对数概率的词元。

• bytes: array of number

用于生成对数概率的字节。

• logprob: number

词元的对数概率。

• ConversationItemInputAudioTranscriptionDeltaEvent object { event_id, item_id, type, 3 more }

输入音频转录内容部分的文本值被增量转录结果更新时返回。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

包含待转录音频的条目的 ID。

• type: "conversation.item.input_audio_transcription.delta"

事件类型，须为 conversation.item.input_audio_transcription.delta。

• "conversation.item.input_audio_transcription.delta"

• content_index: optional integer

内容部分在条目 content 数组中的索引。

• delta: optional string

文本增量。

• logprobs: optional array of LogProbProperties or null

转录的对数概率。可通过会话配置 "include": ["item.input_audio_transcription.logprobs"] 启用。数组中每项对应这一转录片段选取某个词元的对数概率，有助于识别该片段是否可能存在多个有效选项。

• token: string

用于生成对数概率的词元。

• bytes: array of number

用于生成对数概率的字节。

• logprob: number

词元的对数概率。

• ConversationItemInputAudioTranscriptionFailedEvent object { content_index, error, event_id, 2 more }

已配置输入音频转录，但用户消息的 转录请求失败时返回。这类事件独立于其他 error 事件，以便客户端识别关联条目。

• content_index: integer

包含音频的内容部分的索引。

• error: object { code, message, param, type }

转录错误详情。

• code: optional string

错误代码（如有）。

• message: optional string

便于人类阅读的错误消息。

• param: optional string

与错误有关的参数（如有）。

• type: optional string

错误类型。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

用户消息条目的 ID。

• type: "conversation.item.input_audio_transcription.failed"

事件类型，须为 conversation.item.input_audio_transcription.failed.

• "conversation.item.input_audio_transcription.failed"

• ConversationItemRetrieved object { event_id, item, type }

用 conversation.item.retrieve 获取对话条目时返回，用于取得服务端保存的条目，例如访问降噪和 VAD 处理后的音频数据。包含条目完整内容及音频数据。

• event_id: string

服务端事件的唯一 ID。

• item: ConversationItem

Realtime 对话中的单个条目。

• type: "conversation.item.retrieved"

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

• "conversation.item.retrieved"

• ConversationItemTruncatedEvent object { audio_end_ms, content_index, event_id, 2 more }

客户端通过 conversation.item.truncate 截断 此前的助手音频消息条目后返回。此事件用于 同步服务端对音频的理解与客户端播放状态。

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

• audio_end_ms: integer

音频截断到的时长，单位为毫秒。

• content_index: integer

被截断的内容部分的索引。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

被截断的助手消息条目的 ID。

• type: "conversation.item.truncated"

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

• "conversation.item.truncated"

• RealtimeErrorEvent object { error, event_id, type }

发生错误时返回，错误可能来自客户端或服务端 问题。大多数错误可恢复，会话会保持打开。 建议默认监控并记录错误消息。

• error: RealtimeError

错误详情。

• message: string

便于人类阅读的错误消息。

• type: string

错误类型，例如 "invalid_request_error" 或 "server_error"。

• code: optional string or null

错误代码（如有）。

• event_id: optional string or null

导致错误的客户端事件 event_id（如适用）。

• param: optional string or null

与错误有关的参数（如有）。

• event_id: string

服务端事件的唯一 ID。

• type: "error"

事件类型，须为 error。

• "error"

• InputAudioBufferClearedEvent object { event_id, type }

客户端通过 input_audio_buffer.clear 清空输入音频缓冲区后返回。

• event_id: string

服务端事件的唯一 ID。

• type: "input_audio_buffer.cleared"

事件类型，须为 input_audio_buffer.cleared。

• "input_audio_buffer.cleared"

• InputAudioBufferCommittedEvent object { event_id, item_id, type, previous_item_id }

输入音频缓冲区由客户端提交，或在服务端 VAD 模式中 自动提交后返回。item_id 是将要创建的用户 消息条目的 ID，因此也会向客户端发送 conversation.item.created。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

将创建的用户消息条目的 ID。

• type: "input_audio_buffer.committed"

事件类型，须为 input_audio_buffer.committed。

• "input_audio_buffer.committed"

• previous_item_id: optional string or null

新条目要插入在哪个条目之后，即前一个条目的 ID。 条目没有前驱时，可以为 null。

• InputAudioBufferDtmfEventReceivedEvent object { event, received_at, type }

仅限 SIP：收到 DTMF 事件后返回。DTMF 事件表示 电话键盘按键，取值为 0–9、*、# 或 A–D。event 属性 是用户按下的键，received_at 是服务端收到事件时的 UTC Unix 时间戳。

• event: string

用户按下的电话键盘按键。

• received_at: integer

服务端收到 DTMF 事件时的 UTC Unix 时间戳。

• type: "input_audio_buffer.dtmf_event_received"

事件类型，须为 input_audio_buffer.dtmf_event_received。

• "input_audio_buffer.dtmf_event_received"

• InputAudioBufferSpeechStartedEvent object { audio_start_ms, event_id, item_id, type }

在 server_vad 模式下，服务端发送此事件，表示 在音频缓冲区检测到语音。向缓冲区追加音频时，随时可能发生， 但已处于检测到语音状态时除外。客户端可用此事件 打断音频播放，或向用户提供视觉反馈。

语音停止时，客户端应收到 input_audio_buffer.speech_stopped。 item_id 为语音停止时将创建的用户消息条目的 ID， 也会包含在 input_audio_buffer.speech_stopped 中，但客户端在 VAD 活动期间 手动提交音频缓冲区的情况除外。

• audio_start_ms: integer

首次检测到语音时，相对于会话期间写入缓冲区的 全部音频开头的毫秒数。这对应发送给模型的 音频的起点，因此包含会话中配置的 prefix_padding_ms。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

语音停止时将创建的用户消息条目的 ID。

• type: "input_audio_buffer.speech_started"

事件类型，须为 input_audio_buffer.speech_started。

• "input_audio_buffer.speech_started"

• InputAudioBufferSpeechStoppedEvent object { audio_end_ms, event_id, item_id, type }

在 server_vad 模式下，服务端检测到音频缓冲区中 语音结束时返回。服务端也会发送 conversation.item.created， 其中包含根据音频缓冲区创建的用户消息条目。

• audio_end_ms: integer

语音停止时，自会话开始起的毫秒数。这对应发送给模型的 音频的终点，因此包含会话中配置的 min_silence_duration_ms。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

将创建的用户消息条目的 ID。

• type: "input_audio_buffer.speech_stopped"

事件类型，须为 input_audio_buffer.speech_stopped。

• "input_audio_buffer.speech_stopped"

• RateLimitsUpdatedEvent object { event_id, rate_limits, type }

在响应开始时发出，表示更新后的速率限制。 创建响应时，会为输出预留部分词元； 此处的速率限制反映该预留，随后 在响应完成时相应调整。

• event_id: string

服务端事件的唯一 ID。

• rate_limits: array of object { limit, name, remaining, reset_seconds }

速率限制信息列表。

• limit: optional integer

速率限制允许的最大值。

• name: optional "requests" or "tokens"

速率限制名称：requests 或 tokens。

• "requests"

• "tokens"

• remaining: optional integer

达到限制前的剩余额度。

• reset_seconds: optional number

速率限制重置前的秒数。

• type: "rate_limits.updated"

事件类型，须为 rate_limits.updated。

• "rate_limits.updated"

• ResponseAudioDeltaEvent object { content_index, delta, event_id, 4 more }

模型生成的音频更新时返回。

• content_index: integer

内容部分在条目 content 数组中的索引。

• delta: string

Base64 编码的音频数据增量。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

条目 ID。

• output_index: integer

输出条目在响应中的索引。

• response_id: string

响应 ID。

• type: "response.output_audio.delta"

事件类型，须为 response.output_audio.delta。

• "response.output_audio.delta"

• ResponseAudioDoneEvent object { content_index, event_id, item_id, 3 more }

模型生成的音频结束时返回。响应被 打断、未完成或取消时也会发出。

• content_index: integer

内容部分在条目 content 数组中的索引。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

条目 ID。

• output_index: integer

输出条目在响应中的索引。

• response_id: string

响应 ID。

• type: "response.output_audio.done"

事件类型，须为 response.output_audio.done。

• "response.output_audio.done"

• ResponseAudioTranscriptDeltaEvent object { content_index, delta, event_id, 4 more }

模型生成的输出音频转录文本更新时返回。

• content_index: integer

内容部分在条目 content 数组中的索引。

• delta: string

转录文本增量。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

条目 ID。

• output_index: integer

输出条目在响应中的索引。

• response_id: string

响应 ID。

• type: "response.output_audio_transcript.delta"

事件类型，须为 response.output_audio_transcript.delta。

• "response.output_audio_transcript.delta"

• ResponseAudioTranscriptDoneEvent object { content_index, event_id, item_id, 4 more }

模型生成的输出音频转录流式 传输结束时返回。响应被打断、未完成或 取消时也会发出。

• content_index: integer

内容部分在条目 content 数组中的索引。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

条目 ID。

• output_index: integer

输出条目在响应中的索引。

• response_id: string

响应 ID。

• transcript: string

最终的音频转录文本。

• type: "response.output_audio_transcript.done"

事件类型，须为 response.output_audio_transcript.done。

• "response.output_audio_transcript.done"

• ResponseContentPartAddedEvent object { content_index, event_id, item_id, 4 more }

生成响应时，向助手消息条目添加新的内容部分， 会返回此事件。

• content_index: integer

内容部分在条目 content 数组中的索引。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

添加此内容部分的条目的 ID。

• output_index: integer

输出条目在响应中的索引。

• part: object { audio, text, transcript, type }

添加的内容部分。

• audio: optional string

Base64 编码的音频数据，适用于 type 为 "audio" 的情况。

• text: optional string

文本内容，适用于 type 为 "text" 的情况。

• transcript: optional string

音频转录文本，适用于 type 为 "audio" 的情况。

• type: optional "audio" or "text"

内容类型："text" 或 "audio"。

• "audio"

• "text"

• response_id: string

响应 ID。

• type: "response.content_part.added"

事件类型，须为 response.content_part.added。

• "response.content_part.added"

• ResponseContentPartDoneEvent object { content_index, event_id, item_id, 4 more }

助手消息条目中的内容部分流式传输结束时返回。 响应被打断、未完成或取消时也会发出。

• content_index: integer

内容部分在条目 content 数组中的索引。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

条目 ID。

• output_index: integer

输出条目在响应中的索引。

• part: object { audio, text, transcript, type }

已完成的内容部分。

• audio: optional string

Base64 编码的音频数据，适用于 type 为 "audio" 的情况。

• text: optional string

文本内容，适用于 type 为 "text" 的情况。

• transcript: optional string

音频转录文本，适用于 type 为 "audio" 的情况。

• type: optional "audio" or "text"

内容类型："text" 或 "audio"。

• "audio"

• "text"

• response_id: string

响应 ID。

• type: "response.content_part.done"

事件类型，须为 response.content_part.done。

• "response.content_part.done"

• ResponseCreatedEvent object { event_id, response, type }

新响应创建时返回，是响应创建过程的第一个事件， 此时响应处于初始 in_progress 状态。

• event_id: string

服务端事件的唯一 ID。

• response: RealtimeResponse

响应资源。

• id: optional string

响应的唯一 ID，形式类似 resp_1234。

• audio: optional object { output }

音频输出配置。

• 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 (default: "alloy")

模型响应使用的音色。在模型至少输出过一次音频后， 该会话期间不能再更改音色。当前 音色选项包括 alloy、ash、ballad、coral、echo、sage、 shimmer、verse、marin 和 cedar。建议使用 marin 和 cedar， 以获得最佳质量。

• string

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

模型响应使用的音色。在模型至少输出过一次音频后， 该会话期间不能再更改音色。当前 音色选项包括 alloy、ash、ballad、coral、echo、sage、 shimmer、verse、marin 和 cedar。建议使用 marin 和 cedar， 以获得最佳质量。

• "alloy"

• "ash"

• "ballad"

• "coral"

• "echo"

• "sage"

• "shimmer"

• "verse"

• "marin"

• "cedar"

• conversation_id: optional string

响应添加到哪个对话，由 response.create 中的 conversation 字段决定。为 auto 时，响应添加到 默认对话，conversation_id 为类似 conv_1234 的 ID。为 none 时，不添加到任何对话， conversation_id 为 null。如果响应由 VAD 自动触发，则添加到默认对话。

• max_output_tokens: optional number or "inf"

单次助手响应的最大输出词元数， 包括工具调用在内，本次响应使用的内容。

• number

• "inf"

• "inf"

• metadata: optional Metadata or null

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

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

• object: optional "realtime.response"

对象类型，须为 realtime.response。

• "realtime.response"

• output: optional array of ConversationItem

响应生成的输出条目列表。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• "text"

• "audio"

• status: optional "completed" or "cancelled" or "failed" or 2 more

响应最终状态，可选 completed、cancelled、failed 或 incomplete, in_progress).

• "completed"

• "cancelled"

• "failed"

• "incomplete"

• "in_progress"

• status_details: optional RealtimeResponseStatus

状态的额外详情。

• error: optional object { code, message, type }

导致响应失败的错误的描述， 在 status 为 failed 时填充。

• code: optional string

错误代码（如有）。

• message: optional string

便于人类阅读的错误消息。

• type: optional string

错误类型。

• reason: optional "turn_detected" or "client_cancelled" or "max_output_tokens" or "content_filter"

响应未正常完成的原因。对于 cancelled，可为 turn_detected，即服务端 VAD 检测到新的语音开始，或 client_cancelled，即客户端发送取消事件。对于 incomplete，可为 max_output_tokens，或 content_filter，即服务端安全过滤器触发并截断响应。

• "turn_detected"

• "client_cancelled"

• "max_output_tokens"

• "content_filter"

• type: optional "completed" or "cancelled" or "failed" or "incomplete"

导致响应失败的错误类型，对应 status 字段的 completed、cancelled、incomplete、 failed).

• "completed"

• "cancelled"

• "failed"

• "incomplete"

• usage: optional RealtimeResponseUsage

响应的用量统计，对应计费。Realtime API 会话会维护对话上下文，并向对话追加新 条目，因此此前轮次的输出（文本和 音频词元）会成为后续轮次的输入。

• input_token_details: optional RealtimeResponseUsageInputTokenDetails

本次响应的输入词元详情。缓存词元是此前对话轮次中作为当前响应上下文的词元。缓存词元是输入词元的子集，因此输入词元包含缓存和未缓存词元。

• audio_tokens: optional integer

本次响应用作输入的音频词元数。

• cached_tokens: optional integer

本次响应用作输入的缓存词元数。

• cached_tokens_details: optional object { audio_tokens, image_tokens, text_tokens }

本次响应用作输入的缓存词元详情。

• audio_tokens: optional integer

本次响应用作输入的缓存音频词元数。

• image_tokens: optional integer

本次响应用作输入的缓存图像词元数。

• text_tokens: optional integer

本次响应用作输入的缓存文本词元数。

• image_tokens: optional integer

本次响应用作输入的图像词元数。

• text_tokens: optional integer

本次响应用作输入的文本词元数。

• input_tokens: optional integer

本次响应的输入词元数，包括文本和 音频词元。

• output_token_details: optional RealtimeResponseUsageOutputTokenDetails

本次响应的输出词元详情。

• audio_tokens: optional integer

本次响应使用的音频词元数。

• text_tokens: optional integer

本次响应使用的文本词元数。

• output_tokens: optional integer

本次响应发送的输出词元数，包括文本和 音频词元。

• total_tokens: optional integer

本次响应的词元总数，包括输入与输出的 文本和音频词元。

• type: "response.created"

事件类型，须为 response.created。

• "response.created"

• ResponseDoneEvent object { event_id, response, type }

响应流式传输结束时返回，无论最终 状态如何都会发出。response.done 中的响应对象 包含全部输出条目，但省略原始音频数据。

客户端须检查响应的 status，判断是成功 （completed），还是 cancelled、failed 或 incomplete。

响应会包含生成过程中产生的全部输出条目， 但不包含音频内容。

• event_id: string

服务端事件的唯一 ID。

• response: RealtimeResponse

响应资源。

• type: "response.done"

事件类型，须为 response.done。

• "response.done"

• ResponseFunctionCallArgumentsDeltaEvent object { call_id, delta, event_id, 4 more }

模型生成的函数调用参数更新时返回。

• call_id: string

函数调用 ID。

• delta: string

参数增量，以 JSON 字符串表示。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

函数调用条目的 ID。

• output_index: integer

输出条目在响应中的索引。

• response_id: string

响应 ID。

• type: "response.function_call_arguments.delta"

事件类型，须为 response.function_call_arguments.delta。

• "response.function_call_arguments.delta"

• ResponseFunctionCallArgumentsDoneEvent object { arguments, call_id, event_id, 5 more }

模型生成的函数调用参数流式传输结束时返回。 响应被打断、未完成或取消时也会发出。

• arguments: string

最终参数，以 JSON 字符串表示。

• call_id: string

函数调用 ID。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

函数调用条目的 ID。

• name: string

已调用的函数名称。

• output_index: integer

输出条目在响应中的索引。

• response_id: string

响应 ID。

• type: "response.function_call_arguments.done"

事件类型，须为 response.function_call_arguments.done。

• "response.function_call_arguments.done"

• ResponseOutputItemAddedEvent object { event_id, item, output_index, 2 more }

响应生成期间创建新条目时返回。

• event_id: string

服务端事件的唯一 ID。

• item: ConversationItem

Realtime 对话中的单个条目。

• output_index: integer

输出条目在响应中的索引。

• response_id: string

条目所属响应的 ID。

• type: "response.output_item.added"

事件类型，须为 response.output_item.added。

• "response.output_item.added"

• ResponseOutputItemDoneEvent object { event_id, item, output_index, 2 more }

条目流式传输结束时返回。响应被 打断、未完成或取消时也会发出。

• event_id: string

服务端事件的唯一 ID。

• item: ConversationItem

Realtime 对话中的单个条目。

• output_index: integer

输出条目在响应中的索引。

• response_id: string

条目所属响应的 ID。

• type: "response.output_item.done"

事件类型，须为 response.output_item.done。

• "response.output_item.done"

• ResponseTextDeltaEvent object { content_index, delta, event_id, 4 more }

"output_text" 内容部分的文本值更新时返回。

• content_index: integer

内容部分在条目 content 数组中的索引。

• delta: string

文本增量。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

条目 ID。

• output_index: integer

输出条目在响应中的索引。

• response_id: string

响应 ID。

• type: "response.output_text.delta"

事件类型，须为 response.output_text.delta。

• "response.output_text.delta"

• ResponseTextDoneEvent object { content_index, event_id, item_id, 4 more }

"output_text" 内容部分的文本值流式传输结束时返回。响应被 打断、未完成或取消时也会发出。

• content_index: integer

内容部分在条目 content 数组中的索引。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

条目 ID。

• output_index: integer

输出条目在响应中的索引。

• response_id: string

响应 ID。

• text: string

最终文本内容。

• type: "response.output_text.done"

事件类型，须为 response.output_text.done。

• "response.output_text.done"

• SessionCreatedEvent object { event_id, session, type }

会话创建时返回。在新连接 建立时自动作为第一个服务端事件发出，包含 默认会话配置。

• event_id: string

服务端事件的唯一 ID。

• session: RealtimeSessionCreateResponse or RealtimeTranscriptionSessionCreateResponse

会话配置。

• RealtimeSessionCreateResponse object { id, object, type, 13 more }

Realtime 会话配置对象。

• id: string

会话唯一标识，类似 sess_1234567890abcdef。

• object: "realtime.session"

对象类型，固定为 realtime.session。

• "realtime.session"

• type: "realtime"

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

• "realtime"

• audio: optional object { input, output }

输入和输出音频的配置。

• input: optional object { format, noise_reduction, transcription, turn_detection }

• format: optional RealtimeAudioFormats

输入音频格式。

• noise_reduction: optional object { strength, type } or null (default: null)

输入音频降噪配置，设为 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 object { keywords, language, languages, 2 more } or null

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

• keywords: optional array of string

已配置的、用于引导输入音频转录的词语或短语。

• language: optional string or null

输入音频的语言。

• languages: optional array of string

为转录配置的输入音频可能使用的语言，采用 ISO-639-1 格式。

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。

• 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。

• "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

为输入音频转录配置的提示词（如有）。

• turn_detection: optional ServerVad { type, create_response, idle_timeout_ms, 4 more } or SemanticVad { type, create_response, eagerness, interrupt_response } 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 object { format, speed, voice }

• 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 (default: "alloy")

模型响应使用的音色。在模型至少输出过一次音频后， 该会话期间不能再更改音色。当前 音色选项包括 alloy、ash、ballad、coral、echo、sage、 shimmer、verse、marin 和 cedar。建议使用 marin 和 cedar， 以获得最佳质量。

• string

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

模型响应使用的音色。在模型至少输出过一次音频后， 该会话期间不能再更改音色。当前 音色选项包括 alloy、ash、ballad、coral、echo、sage、 shimmer、verse、marin 和 cedar。建议使用 marin 和 cedar， 以获得最佳质量。

• "alloy"

• "ash"

• "ballad"

• "coral"

• "echo"

• "sage"

• "shimmer"

• "verse"

• "marin"

• "cedar"

• expires_at: optional integer

会话过期的 Unix 时间戳，单位为秒。

format: unixtime

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

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

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"

• 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}$

• tracing: optional "auto" or TracingConfiguration { group_id, metadata, workflow_name } 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

• RealtimeTranscriptionSessionCreateResponse object { id, object, type, 3 more }

Realtime 转录会话配置对象。

• id: string

会话唯一标识，类似 sess_1234567890abcdef。

• object: string

对象类型，固定为 realtime.transcription_session。

• type: "transcription"

会话类型。对于转录会话，固定为 transcription。

• "transcription"

• audio: optional object { input }

会话的输入音频配置。

• input: optional object { format, noise_reduction, transcription, turn_detection }

• format: optional RealtimeAudioFormats

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

• noise_reduction: optional object { strength, type } or null

输入音频降噪配置。

• strength: optional number (default: 1)

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

minimum: 0, maximum: 1

• type: optional NoiseReductionType

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

• transcription: optional object { keywords, language, languages, 2 more } or null

转录模型配置。

• keywords: optional array of string

已配置的、用于引导输入音频转录的词语或短语。

• language: optional string or null

输入音频的语言。

• languages: optional array of string

为转录配置的输入音频可能使用的语言，采用 ISO-639-1 格式。

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。

• 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。

• "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

为输入音频转录配置的提示词（如有）。

• turn_detection: optional RealtimeTranscriptionSessionTurnDetection or null

话轮检测配置，可设为 null 关闭。服务端 VAD 表示模型根据 音量，并在用户讲话结束时响应。对于 gpt-realtime-whisper，此项必须为 null，因为不支持 VAD。

• prefix_padding_ms: optional integer

在 VAD 检测到语音之前一并保留的音频时长，单位为 毫秒，默认为 300 毫秒。

• silence_duration_ms: optional integer

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

• threshold: optional number

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

• type: optional string

话轮检测类型，目前仅支持 server_vad。

• expires_at: optional integer

会话过期的 Unix 时间戳，单位为秒。

format: unixtime

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

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

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

• "item.input_audio_transcription.logprobs"

• type: "session.created"

事件类型，须为 session.created。

• "session.created"

• SessionUpdatedEvent object { event_id, session, type }

通过 session.update 更新会话后返回，除非 发生错误。

• event_id: string

服务端事件的唯一 ID。

• session: RealtimeSessionCreateResponse or RealtimeTranscriptionSessionCreateResponse

会话配置。

• RealtimeSessionCreateResponse object { id, object, type, 13 more }

Realtime 会话配置对象。

• RealtimeTranscriptionSessionCreateResponse object { id, object, type, 3 more }

Realtime 转录会话配置对象。

• type: "session.updated"

事件类型，须为 session.updated。

• "session.updated"

• OutputAudioBufferStarted object { event_id, response_id, type }

仅限 WebRTC/SIP：服务端开始向客户端流式发送音频时发出。在响应中 已添加音频内容部分（response.content_part.added） 之后发出。 了解更多。

• event_id: string

服务端事件的唯一 ID。

• response_id: string

生成该音频的响应的唯一 ID。

• type: "output_audio_buffer.started"

事件类型，须为 output_audio_buffer.started。

• "output_audio_buffer.started"

• OutputAudioBufferStopped object { event_id, response_id, type }

仅限 WebRTC/SIP：服务端输出音频缓冲区完全排空， 且不再有后续音频时发出。在完整响应数据 已发送给客户端（response.done）之后发出。 了解更多。

• event_id: string

服务端事件的唯一 ID。

• response_id: string

生成该音频的响应的唯一 ID。

• type: "output_audio_buffer.stopped"

事件类型，须为 output_audio_buffer.stopped。

• "output_audio_buffer.stopped"

• OutputAudioBufferCleared object { event_id, response_id, type }

仅限 WebRTC/SIP：输出音频缓冲区被清空时发出。可能是在 VAD 模式下用户打断（input_audio_buffer.speech_started）， 或客户端发出 output_audio_buffer.clear，手动 截断当前音频响应。 了解更多。

• event_id: string

服务端事件的唯一 ID。

• response_id: string

生成该音频的响应的唯一 ID。

• type: "output_audio_buffer.cleared"

事件类型，须为 output_audio_buffer.cleared。

• "output_audio_buffer.cleared"

• ConversationItemAdded object { event_id, item, type, previous_item_id }

服务端向默认对话添加条目时发送，可能出现在以下情况：

• 客户端发送 conversation.item.create 事件。
• 输入音频缓冲区被提交。此时，条目是包含缓冲区音频的用户消息。
• 模型正在生成响应。模型开始生成具体条目时发送 conversation.item.added，因此此时尚无内容，且 status 为 in_progress。

除模型正在生成响应的情况外，此事件包含条目的完整内容，但不包含音频数据。如有需要，可用 conversation.item.retrieve 单独获取音频。

• event_id: string

服务端事件的唯一 ID。

• item: ConversationItem

Realtime 对话中的单个条目。

• type: "conversation.item.added"

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

• "conversation.item.added"

• previous_item_id: optional string or null

此条目前一个条目的 ID，如有，用于 维护插入条目时的顺序。

• ConversationItemDone object { event_id, item, type, previous_item_id }

对话条目最终确定后返回。

此事件包含条目的完整内容，但不包含音频数据。如有需要，可通过 conversation.item.retrieve 单独获取音频。

• event_id: string

服务端事件的唯一 ID。

• item: ConversationItem

Realtime 对话中的单个条目。

• type: "conversation.item.done"

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

• "conversation.item.done"

• previous_item_id: optional string or null

此条目前一个条目的 ID，如有，用于 维护插入条目时的顺序。

• InputAudioBufferTimeoutTriggered object { audio_end_ms, audio_start_ms, event_id, 2 more }

输入音频缓冲区的服务端 VAD 超时触发时返回，通过会话 turn_detection 设置中的 idle_timeout_ms 配置，表示 在配置的时长内没有检测到语音。

audio_start_ms 和 audio_end_ms 标识上次模型响应之后到超时触发 时的音频片段，数值为相对于写入输入音频缓冲区的 音频开头的偏移量。因此它划分出静音片段， 开始与结束值之差大致等于配置的超时时长。

静音音频会作为 input_audio 条目提交到对话，并发出 input_audio_buffer.committed，随后生成模型响应。音频中可能有 未触发 VAD 但仍能被模型检测到的语音，因此模型可能给出 与对话相关的响应，或提示用户继续讲话。

• audio_end_ms: integer

超时触发时，相对于写入输入音频缓冲区的音频开头的毫秒偏移量。

• audio_start_ms: integer

上次模型响应播放结束后，相对于写入输入音频缓冲区的音频开头的毫秒偏移量。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

与此片段关联的条目 ID。

• type: "input_audio_buffer.timeout_triggered"

事件类型，须为 input_audio_buffer.timeout_triggered。

• "input_audio_buffer.timeout_triggered"

• ConversationItemInputAudioTranscriptionSegment object { id, content_index, end, 6 more }

识别出条目的输入音频转录分段时返回。

• id: string

分段标识。

• content_index: integer

输入音频内容部分在条目中的索引。

• end: number

分段结束时间，单位为秒。

format: double

• event_id: string

服务端事件的唯一 ID。

• item_id: string

包含输入音频内容的条目的 ID。

• speaker: string

为此分段检测到的说话人标签。

• start: number

分段开始时间，单位为秒。

format: double

• text: string

此分段的文本。

• type: "conversation.item.input_audio_transcription.segment"

事件类型，须为 conversation.item.input_audio_transcription.segment。

• "conversation.item.input_audio_transcription.segment"

• McpListToolsInProgress object { event_id, item_id, type }

条目的 MCP 工具列表正在获取时返回。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

MCP 工具列表条目的 ID。

• type: "mcp_list_tools.in_progress"

事件类型，须为 mcp_list_tools.in_progress。

• "mcp_list_tools.in_progress"

• McpListToolsCompleted object { event_id, item_id, type }

条目的 MCP 工具列表获取完成时返回。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

MCP 工具列表条目的 ID。

• type: "mcp_list_tools.completed"

事件类型，须为 mcp_list_tools.completed。

• "mcp_list_tools.completed"

• McpListToolsFailed object { event_id, item_id, type }

条目的 MCP 工具列表获取失败时返回。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

MCP 工具列表条目的 ID。

• type: "mcp_list_tools.failed"

事件类型，须为 mcp_list_tools.failed。

• "mcp_list_tools.failed"

• ResponseMcpCallArgumentsDelta object { delta, event_id, item_id, 4 more }

生成响应期间，MCP 工具调用参数更新时返回。

• delta: string

JSON 编码的参数增量。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

MCP 工具调用条目的 ID。

• output_index: integer

输出条目在响应中的索引。

• response_id: string

响应 ID。

• type: "response.mcp_call_arguments.delta"

事件类型，须为 response.mcp_call_arguments.delta。

• "response.mcp_call_arguments.delta"

• obfuscation: optional string or null

如提供此字段，表示增量文本已作混淆处理。

• ResponseMcpCallArgumentsDone object { arguments, event_id, item_id, 3 more }

生成响应期间，MCP 工具调用参数最终确定时返回。

• arguments: string

最终的 JSON 编码参数字符串。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

MCP 工具调用条目的 ID。

• output_index: integer

输出条目在响应中的索引。

• response_id: string

响应 ID。

• type: "response.mcp_call_arguments.done"

事件类型，须为 response.mcp_call_arguments.done。

• "response.mcp_call_arguments.done"

• ResponseMcpCallInProgress object { event_id, item_id, output_index, type }

MCP 工具调用已开始且正在进行时返回。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

MCP 工具调用条目的 ID。

• output_index: integer

输出条目在响应中的索引。

• type: "response.mcp_call.in_progress"

事件类型，须为 response.mcp_call.in_progress。

• "response.mcp_call.in_progress"

• ResponseMcpCallCompleted object { event_id, item_id, output_index, type }

MCP 工具调用成功完成时返回。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

MCP 工具调用条目的 ID。

• output_index: integer

输出条目在响应中的索引。

• type: "response.mcp_call.completed"

事件类型，须为 response.mcp_call.completed。

• "response.mcp_call.completed"

• ResponseMcpCallFailed object { event_id, item_id, output_index, type }

MCP 工具调用失败时返回。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

MCP 工具调用条目的 ID。

• output_index: integer

输出条目在响应中的索引。

• type: "response.mcp_call.failed"

事件类型，须为 response.mcp_call.failed。

• "response.mcp_call.failed"

Realtime 会话

• RealtimeSession object { id, expires_at, include, 17 more }

beta 接口的 Realtime 会话对象。

• id: optional string

会话唯一标识，类似 sess_1234567890abcdef。

• expires_at: optional integer

会话过期的 Unix 时间戳，单位为秒。

format: unixtime

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

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

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

• "item.input_audio_transcription.logprobs"

• input_audio_format: optional "pcm16" or "g711_ulaw" or "g711_alaw" (default: "pcm16")

输入音频格式，可选 pcm16、g711_ulaw 或 g711_alaw。 使用 pcm16 时，输入必须是 24 kHz 采样率的 16 位 PCM 音频， 采用单声道和小端字节序。

• "pcm16"

• "g711_ulaw"

• "g711_alaw"

• input_audio_noise_reduction: optional object { type }

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

• type: optional NoiseReductionType

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

• "near_field"

• "far_field"

• input_audio_transcription: optional object { keywords, language, languages, 2 more } or null

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

• keywords: optional array of string

已配置的、用于引导输入音频转录的词语或短语。

• language: optional string or null

输入音频的语言。

• languages: optional array of string

为转录配置的输入音频可能使用的语言，采用 ISO-639-1 格式。

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。

• 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。

• "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

为输入音频转录配置的提示词（如有）。

• instructions: optional string

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

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

• max_response_output_tokens: optional number or "inf"

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

• number

• "inf"

• "inf"

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

模型可用于响应的模态集合。如需禁用音频， 设为 ["text"]。

• "text"

• "audio"

• model: optional string or "gpt-realtime" or "gpt-realtime-1.5" or "gpt-realtime-2025-08-28" or 13 more

此会话使用的 Realtime 模型。

• string

• "gpt-realtime" or "gpt-realtime-1.5" or "gpt-realtime-2025-08-28" or 13 more

此会话使用的 Realtime 模型。

• "gpt-realtime"

• "gpt-realtime-1.5"

• "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"

• object: optional "realtime.session"

对象类型，固定为 realtime.session。

• "realtime.session"

• output_audio_format: optional "pcm16" or "g711_ulaw" or "g711_alaw" (default: "pcm16")

输出音频格式，可选 pcm16、g711_ulaw 或 g711_alaw。 对于 pcm16，输出音频采样率为 24kHz。

• "pcm16"

• "g711_ulaw"

• "g711_alaw"

• 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

提示词模板的可选版本。

• speed: optional number (default: 1)

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

minimum: 0.25, maximum: 1.5

• temperature: optional number (default: 0.8)

模型采样温度，限制在 [0.6, 1.2]。对于音频模型，强烈建议使用 0.8，以获得最佳表现。

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

模型选择工具的方式，可选 auto、none、required，或 指定一个函数。

• tools: optional array of RealtimeFunctionTool

模型可用的工具（函数）。

• description: optional string

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

• name: optional string

函数名称。

• parameters: optional unknown

以 JSON Schema 描述的函数参数。

• type: optional "function"

工具类型，即 function。

• "function"

• tracing: optional "auto" or TracingConfiguration { group_id, metadata, workflow_name } or null

追踪配置选项。设为 null 可禁用追踪。一旦 为会话启用追踪，就不能修改配置。

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

• "auto"

会话的默认追踪模式。

• "auto"

• TracingConfiguration object { group_id, metadata, workflow_name }

追踪的细粒度配置。

• group_id: optional string

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

• metadata: optional unknown

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

• workflow_name: optional string

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

• turn_detection: optional ServerVad { type, create_response, idle_timeout_ms, 4 more } or SemanticVad { type, create_response, eagerness, interrupt_response } 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）的响应。

• voice: optional string or "alloy" or "ash" or "ballad" or 7 more

模型响应使用的音色。在模型至少输出过一次音频后， 该会话期间不能再更改音色。当前 音色选项包括 alloy、ash、ballad、coral、echo、sage、 shimmer 和 verse。

• string

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

模型响应使用的音色。在模型至少输出过一次音频后， 该会话期间不能再更改音色。当前 音色选项包括 alloy、ash、ballad、coral、echo、sage、 shimmer 和 verse。

• "alloy"

• "ash"

• "ballad"

• "coral"

• "echo"

• "sage"

• "shimmer"

• "verse"

• "marin"

• "cedar"

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

Realtime 工具选择配置

• RealtimeToolChoiceConfig = ToolChoiceOptions or ToolChoiceFunction or ToolChoiceMcp

模型选择工具的方式。提供一种字符串模式，或强制调用指定的 函数或 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

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

Realtime 工具配置

• RealtimeToolsConfig = array of RealtimeToolsConfigUnion

模型可用的工具。

• 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}$

Realtime 工具配置联合类型

• RealtimeToolsConfigUnion = RealtimeFunctionTool or McpTool { server_label, type, allowed_callers, 9 more }

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

• 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}$

Realtime 追踪配置

• RealtimeTracingConfig = "auto" or TracingConfiguration { group_id, metadata, workflow_name }

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

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

Realtime 转录会话音频

• RealtimeTranscriptionSessionAudio object { input }

输入和输出音频的配置。

• input: optional RealtimeTranscriptionSessionAudioInput

• format: optional RealtimeAudioFormats

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

• 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 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）的响应。

Realtime 转录会话音频输入

• RealtimeTranscriptionSessionAudioInput object { format, noise_reduction, transcription, turn_detection }

• format: optional RealtimeAudioFormats

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

• 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 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）的响应。

Realtime 转录会话音频输入轮次检测

• RealtimeTranscriptionSessionAudioInputTurnDetection = ServerVad { type, create_response, idle_timeout_ms, 4 more } or SemanticVad { type, create_response, eagerness, interrupt_response }

轮次检测配置，可使用服务端 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）的响应。

Realtime 转录会话创建请求

• RealtimeTranscriptionSessionCreateRequest object { type, audio, include }

Realtime 转录会话对象配置。

• type: "transcription"

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

• "transcription"

• audio: optional RealtimeTranscriptionSessionAudio

输入和输出音频的配置。

• input: optional RealtimeTranscriptionSessionAudioInput

• format: optional RealtimeAudioFormats

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

• 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 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"

Realtime 翻译客户端事件

• RealtimeTranslationClientEvent = RealtimeTranslationSessionUpdateEvent or RealtimeTranslationInputAudioBufferAppendEvent or RealtimeTranslationSessionCloseEvent

Realtime 翻译客户端事件。

• RealtimeTranslationSessionUpdateEvent object { session, type, event_id }

发送此事件更新翻译会话配置。翻译 会话支持更新 audio.output.language、audio.input.transcription 和 audio.input.noise_reduction。

• session: RealtimeTranslationSessionUpdateRequest

要更新的翻译会话字段。会话的 type 和 model 在 创建时设置，不能通过 session.update 更改。

• audio: optional object { input, output }

翻译输入与输出音频的配置。

• input: optional object { noise_reduction, transcription }

• noise_reduction: optional object { type, strength } or null

可选的输入降噪配置，设为 null 可禁用。

• type: NoiseReductionType

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

• "near_field"

• "far_field"

• strength: optional number (default: 1)

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

minimum: 0, maximum: 1

• transcription: optional object { model } or null

可选的源语言转录配置。配置后，服务器输出 session.input_transcript.delta 事件。翻译本身仍然直接基于 输入音频流。

• model: string

用于生成源语言转录文本增量的转录模型。

• output: optional object { language }

• language: optional string

翻译后音频与文本增量的目标语言。

• type: "session.update"

事件类型，须为 session.update。

• "session.update"

• event_id: optional string

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

maxLength: 512

• RealtimeTranslationInputAudioBufferAppendEvent object { audio, type, event_id }

发送此事件，向翻译会话的输入音频缓冲区追加音频字节。

WebSocket 翻译会话接受 Base64 编码、24 kHz、PCM16、单声道、 小端序的原始音频字节。不支持的 WebSocket 音频格式会返回 校验错误，因为较低质量的音频会显著降低 翻译质量。

翻译按 200 毫秒的引擎帧处理音频。为获得最佳实时表现，建议以 200 毫秒的块追加音频。较短的块会在服务端缓冲，直到 足够组成一帧；较长的块会拆为 200 毫秒帧，连续加入队列。

会话活动期间须持续追加静音。如果客户端停止发送 音频后又恢复，模型时间会将恢复后的音频视为与 先前音频连续，而不是真实世界中的停顿。

• audio: string

Base64 编码、24 kHz、PCM16、单声道音频字节。

• type: "session.input_audio_buffer.append"

事件类型，须为 session.input_audio_buffer.append。

• "session.input_audio_buffer.append"

• event_id: optional string

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

maxLength: 512

• RealtimeTranslationSessionCloseEvent object { type, event_id }

正常关闭 Realtime 翻译会话。服务端会处理完待处理的 输入音频，发出剩余翻译输出，然后关闭 会话。

• type: "session.close"

事件类型，须为 session.close。

• "session.close"

• event_id: optional string

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

maxLength: 512

Realtime 翻译客户端密钥创建请求

• RealtimeTranslationClientSecretCreateRequest object { session, expires_after }

为 Realtime API 创建翻译会话和客户端密钥。

• session: RealtimeTranslationSessionCreateRequest

Realtime 翻译会话配置。翻译会话持续以流式方式接收源 音频，并输出翻译后的音频和增量文本。

• model: string

此会话使用的 Realtime 翻译模型。

• audio: optional object { input, output }

翻译输入与输出音频的配置。

• input: optional object { noise_reduction, transcription }

• noise_reduction: optional object { type, strength } or null

可选的输入降噪配置，设为 null 可禁用。

• type: NoiseReductionType

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

• "near_field"

• "far_field"

• strength: optional number (default: 1)

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

minimum: 0, maximum: 1

• transcription: optional object { model } or null

可选的源语言转录配置。配置后，服务器输出 session.input_transcript.delta 事件。翻译本身仍然直接基于 输入音频流。

• model: string

用于生成源语言转录文本增量的转录模型。

• output: optional object { language }

• language: optional string

翻译后音频与文本增量的目标语言。

• expires_after: optional object { anchor, seconds }

客户端密钥过期配置。过期时间表示此时间之后 无法再用该密钥创建会话。已经启动的会话本身 可以继续运行。在密钥过期之前，可使用同一个密钥创建多个会话， 直至密钥过期。

• anchor: optional "created_at" (default: "created_at")

客户端密钥过期时间的基准点。将 seconds 加到密钥的 created_at 时间上即可得到过期时间戳。目前仅支持 created_at。

• "created_at"

• seconds: optional integer (default: 600)

从基准点到过期时间的秒数，可选 10–7200 秒（2 小时），省略时默认为 600 秒（10 分钟）。

format: int64, minimum: 10, maximum: 7200

Realtime 翻译客户端密钥创建响应

• RealtimeTranslationClientSecretCreateResponse object { expires_at, session, value }

创建 Realtime 翻译会话及客户端密钥的响应。

• expires_at: integer

客户端密钥过期的 Unix 时间戳，单位为秒。

format: unixtime

• session: RealtimeTranslationSession

Realtime 翻译会话。会话会持续将输入 音频翻译成配置的输出语言。

• id: string

会话唯一标识，类似 sess_1234567890abcdef。

• audio: object { input, output }

翻译输入与输出音频的配置。

• input: optional object { noise_reduction, transcription }

• noise_reduction: optional object { type, strength } or null

可选的输入降噪配置。

• type: NoiseReductionType

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

• "near_field"

• "far_field"

• strength: optional number (default: 1)

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

minimum: 0, maximum: 1

• transcription: optional object { model } or null

可选的源语言转录配置。配置后，服务器输出 session.input_transcript.delta 事件。翻译本身仍然直接基于 输入音频流。

• model: string

用于生成源语言转录文本增量的转录模型。

• output: optional object { language }

• language: optional string

翻译后音频与文本增量的目标语言。

• expires_at: integer

会话过期的 Unix 时间戳，单位为秒。

format: unixtime

• model: string

此会话使用的 Realtime 翻译模型。此字段在 创建会话时设置，无法通过 session.update 修改。

• type: "translation"

会话类型，Realtime 翻译会话固定为 translation。

• "translation"

• value: string

生成的客户端密钥值。

Realtime 翻译输入音频缓冲区追加事件

• RealtimeTranslationInputAudioBufferAppendEvent object { audio, type, event_id }

发送此事件，向翻译会话的输入音频缓冲区追加音频字节。

WebSocket 翻译会话接受 Base64 编码、24 kHz、PCM16、单声道、 小端序的原始音频字节。不支持的 WebSocket 音频格式会返回 校验错误，因为较低质量的音频会显著降低 翻译质量。

翻译按 200 毫秒的引擎帧处理音频。为获得最佳实时表现，建议以 200 毫秒的块追加音频。较短的块会在服务端缓冲，直到 足够组成一帧；较长的块会拆为 200 毫秒帧，连续加入队列。

会话活动期间须持续追加静音。如果客户端停止发送 音频后又恢复，模型时间会将恢复后的音频视为与 先前音频连续，而不是真实世界中的停顿。

• audio: string

Base64 编码、24 kHz、PCM16、单声道音频字节。

• type: "session.input_audio_buffer.append"

事件类型，须为 session.input_audio_buffer.append。

• "session.input_audio_buffer.append"

• event_id: optional string

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

maxLength: 512

Realtime 翻译输入转录增量事件

• RealtimeTranslationInputTranscriptDeltaEvent object { delta, event_id, type, elapsed_ms }

可选的源语言转录文本可用时返回。此事件 仅在配置 audio.input.transcription 后发出。

转录文本增量是只能追加的文本片段。客户端不应 在增量之间无条件插入空格。

• delta: string

只能追加的源语言转录文本。

• event_id: string

服务端事件的唯一 ID。

• type: "session.input_transcript.delta"

事件类型，须为 session.input_transcript.delta。

• "session.input_transcript.delta"

• elapsed_ms: optional integer or null

用于流对齐的时间元数据，来源于翻译帧 （如可用）。时间以 200 毫秒递增，但多个文本 增量可能具有相同的 elapsed_ms。应将其视为对齐元数据， 不能将其视为文本增量的唯一标识。

Realtime 翻译输出音频增量事件

• RealtimeTranslationOutputAudioDeltaEvent object { delta, event_id, type, 4 more }

翻译后的输出音频可用时返回。delta 包含 长度可能变化的 PCM16 音频块。客户端应解码并将 完整增量加入队列，不应假定固定字节数或采样数。

• delta: string

Base64 编码的翻译后音频数据。

• event_id: string

服务端事件的唯一 ID。

• type: "session.output_audio.delta"

事件类型，须为 session.output_audio.delta。

• "session.output_audio.delta"

• channels: optional integer (default: 1)

音频声道数。

• elapsed_ms: optional integer or null

用于流对齐的时间元数据，来源于翻译帧 （如可用）。elapsed_ms 是对齐元数据，不是唯一 事件标识。

• format: optional "pcm16"

音频增量 delta 的编码。

• "pcm16"

• sample_rate: optional integer (default: 24000)

音频增量的采样率。

Realtime 翻译输出转录增量事件

• RealtimeTranslationOutputTranscriptDeltaEvent object { delta, event_id, type, elapsed_ms }

翻译后的转录文本可用时返回。

转录文本增量是只能追加的文本片段。客户端不应 在增量之间无条件插入空格。

• delta: string

只能追加的、与翻译后输出音频对应的转录文本。

• event_id: string

服务端事件的唯一 ID。

• type: "session.output_transcript.delta"

事件类型，须为 session.output_transcript.delta。

• "session.output_transcript.delta"

• elapsed_ms: optional integer or null

用于流对齐的时间元数据，来源于翻译帧 （如可用）。时间以 200 毫秒递增，但多个文本 增量可能具有相同的 elapsed_ms。应将其视为对齐元数据， 不能将其视为文本增量的唯一标识。

Realtime 翻译服务端事件

• RealtimeTranslationServerEvent = RealtimeErrorEvent or RealtimeTranslationSessionCreatedEvent or RealtimeTranslationSessionUpdatedEvent or 4 more

Realtime 翻译服务端事件。

• RealtimeErrorEvent object { error, event_id, type }

发生错误时返回，错误可能来自客户端或服务端 问题。大多数错误可恢复，会话会保持打开。 建议默认监控并记录错误消息。

• error: RealtimeError

错误详情。

• message: string

便于人类阅读的错误消息。

• type: string

错误类型，例如 "invalid_request_error" 或 "server_error"。

• code: optional string or null

错误代码（如有）。

• event_id: optional string or null

导致错误的客户端事件 event_id（如适用）。

• param: optional string or null

与错误有关的参数（如有）。

• event_id: string

服务端事件的唯一 ID。

• type: "error"

事件类型，须为 error。

• "error"

• RealtimeTranslationSessionCreatedEvent object { event_id, session, type }

创建翻译会话时返回。在建立 新连接后自动发出，作为第一个服务端事件。事件包含 默认翻译会话配置。

• event_id: string

服务端事件的唯一 ID。

• session: RealtimeTranslationSession

翻译会话配置。

• id: string

会话唯一标识，类似 sess_1234567890abcdef。

• audio: object { input, output }

翻译输入与输出音频的配置。

• input: optional object { noise_reduction, transcription }

• noise_reduction: optional object { type, strength } or null

可选的输入降噪配置。

• type: NoiseReductionType

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

• "near_field"

• "far_field"

• strength: optional number (default: 1)

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

minimum: 0, maximum: 1

• transcription: optional object { model } or null

可选的源语言转录配置。配置后，服务器输出 session.input_transcript.delta 事件。翻译本身仍然直接基于 输入音频流。

• model: string

用于生成源语言转录文本增量的转录模型。

• output: optional object { language }

• language: optional string

翻译后音频与文本增量的目标语言。

• expires_at: integer

会话过期的 Unix 时间戳，单位为秒。

format: unixtime

• model: string

此会话使用的 Realtime 翻译模型。此字段在 创建会话时设置，无法通过 session.update 修改。

• type: "translation"

会话类型，Realtime 翻译会话固定为 translation。

• "translation"

• type: "session.created"

事件类型，须为 session.created。

• "session.created"

• RealtimeTranslationSessionUpdatedEvent object { event_id, session, type }

通过 session.update 事件更新翻译会话后返回， 发生错误时除外。

• event_id: string

服务端事件的唯一 ID。

• session: RealtimeTranslationSession

翻译会话配置。

• type: "session.updated"

事件类型，须为 session.updated。

• "session.updated"

• RealtimeTranslationSessionClosedEvent object { event_id, type }

实时翻译会话关闭时返回。

• event_id: string

服务端事件的唯一 ID。

• type: "session.closed"

事件类型，须为 session.closed。

• "session.closed"

• RealtimeTranslationInputTranscriptDeltaEvent object { delta, event_id, type, elapsed_ms }

可选的源语言转录文本可用时返回。此事件 仅在配置 audio.input.transcription 后发出。

转录文本增量是只能追加的文本片段。客户端不应 在增量之间无条件插入空格。

• delta: string

只能追加的源语言转录文本。

• event_id: string

服务端事件的唯一 ID。

• type: "session.input_transcript.delta"

事件类型，须为 session.input_transcript.delta。

• "session.input_transcript.delta"

• elapsed_ms: optional integer or null

用于流对齐的时间元数据，来源于翻译帧 （如可用）。时间以 200 毫秒递增，但多个文本 增量可能具有相同的 elapsed_ms。应将其视为对齐元数据， 不能将其视为文本增量的唯一标识。

• RealtimeTranslationOutputTranscriptDeltaEvent object { delta, event_id, type, elapsed_ms }

翻译后的转录文本可用时返回。

转录文本增量是只能追加的文本片段。客户端不应 在增量之间无条件插入空格。

• delta: string

只能追加的、与翻译后输出音频对应的转录文本。

• event_id: string

服务端事件的唯一 ID。

• type: "session.output_transcript.delta"

事件类型，须为 session.output_transcript.delta。

• "session.output_transcript.delta"

• elapsed_ms: optional integer or null

用于流对齐的时间元数据，来源于翻译帧 （如可用）。时间以 200 毫秒递增，但多个文本 增量可能具有相同的 elapsed_ms。应将其视为对齐元数据， 不能将其视为文本增量的唯一标识。

• RealtimeTranslationOutputAudioDeltaEvent object { delta, event_id, type, 4 more }

翻译后的输出音频可用时返回。delta 包含 长度可能变化的 PCM16 音频块。客户端应解码并将 完整增量加入队列，不应假定固定字节数或采样数。

• delta: string

Base64 编码的翻译后音频数据。

• event_id: string

服务端事件的唯一 ID。

• type: "session.output_audio.delta"

事件类型，须为 session.output_audio.delta。

• "session.output_audio.delta"

• channels: optional integer (default: 1)

音频声道数。

• elapsed_ms: optional integer or null

用于流对齐的时间元数据，来源于翻译帧 （如可用）。elapsed_ms 是对齐元数据，不是唯一 事件标识。

• format: optional "pcm16"

音频增量 delta 的编码。

• "pcm16"

• sample_rate: optional integer (default: 24000)

音频增量的采样率。

Realtime 翻译会话

• RealtimeTranslationSession object { id, audio, expires_at, 2 more }

Realtime 翻译会话。会话会持续将输入 音频翻译成配置的输出语言。

• id: string

会话唯一标识，类似 sess_1234567890abcdef。

• audio: object { input, output }

翻译输入与输出音频的配置。

• input: optional object { noise_reduction, transcription }

• noise_reduction: optional object { type, strength } or null

可选的输入降噪配置。

• type: NoiseReductionType

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

• "near_field"

• "far_field"

• strength: optional number (default: 1)

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

minimum: 0, maximum: 1

• transcription: optional object { model } or null

可选的源语言转录配置。配置后，服务器输出 session.input_transcript.delta 事件。翻译本身仍然直接基于 输入音频流。

• model: string

用于生成源语言转录文本增量的转录模型。

• output: optional object { language }

• language: optional string

翻译后音频与文本增量的目标语言。

• expires_at: integer

会话过期的 Unix 时间戳，单位为秒。

format: unixtime

• model: string

此会话使用的 Realtime 翻译模型。此字段在 创建会话时设置，无法通过 session.update 修改。

• type: "translation"

会话类型，Realtime 翻译会话固定为 translation。

• "translation"

Realtime 翻译会话关闭事件

• RealtimeTranslationSessionCloseEvent object { type, event_id }

正常关闭 Realtime 翻译会话。服务端会处理完待处理的 输入音频，发出剩余翻译输出，然后关闭 会话。

• type: "session.close"

事件类型，须为 session.close。

• "session.close"

• event_id: optional string

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

maxLength: 512

Realtime 翻译会话关闭事件

• RealtimeTranslationSessionClosedEvent object { event_id, type }

实时翻译会话关闭时返回。

• event_id: string

服务端事件的唯一 ID。

• type: "session.closed"

事件类型，须为 session.closed。

• "session.closed"

Realtime 翻译会话创建请求

• RealtimeTranslationSessionCreateRequest object { model, audio }

Realtime 翻译会话配置。翻译会话持续以流式方式接收源 音频，并输出翻译后的音频和增量文本。

• model: string

此会话使用的 Realtime 翻译模型。

• audio: optional object { input, output }

翻译输入与输出音频的配置。

• input: optional object { noise_reduction, transcription }

• noise_reduction: optional object { type, strength } or null

可选的输入降噪配置，设为 null 可禁用。

• type: NoiseReductionType

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

• "near_field"

• "far_field"

• strength: optional number (default: 1)

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

minimum: 0, maximum: 1

• transcription: optional object { model } or null

可选的源语言转录配置。配置后，服务器输出 session.input_transcript.delta 事件。翻译本身仍然直接基于 输入音频流。

• model: string

用于生成源语言转录文本增量的转录模型。

• output: optional object { language }

• language: optional string

翻译后音频与文本增量的目标语言。

Realtime 翻译会话创建事件

• RealtimeTranslationSessionCreatedEvent object { event_id, session, type }

创建翻译会话时返回。在建立 新连接后自动发出，作为第一个服务端事件。事件包含 默认翻译会话配置。

• event_id: string

服务端事件的唯一 ID。

• session: RealtimeTranslationSession

翻译会话配置。

• id: string

会话唯一标识，类似 sess_1234567890abcdef。

• audio: object { input, output }

翻译输入与输出音频的配置。

• input: optional object { noise_reduction, transcription }

• noise_reduction: optional object { type, strength } or null

可选的输入降噪配置。

• type: NoiseReductionType

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

• "near_field"

• "far_field"

• strength: optional number (default: 1)

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

minimum: 0, maximum: 1

• transcription: optional object { model } or null

可选的源语言转录配置。配置后，服务器输出 session.input_transcript.delta 事件。翻译本身仍然直接基于 输入音频流。

• model: string

用于生成源语言转录文本增量的转录模型。

• output: optional object { language }

• language: optional string

翻译后音频与文本增量的目标语言。

• expires_at: integer

会话过期的 Unix 时间戳，单位为秒。

format: unixtime

• model: string

此会话使用的 Realtime 翻译模型。此字段在 创建会话时设置，无法通过 session.update 修改。

• type: "translation"

会话类型，Realtime 翻译会话固定为 translation。

• "translation"

• type: "session.created"

事件类型，须为 session.created。

• "session.created"

Realtime 翻译会话更新事件

• RealtimeTranslationSessionUpdateEvent object { session, type, event_id }

发送此事件更新翻译会话配置。翻译 会话支持更新 audio.output.language、audio.input.transcription 和 audio.input.noise_reduction。

• session: RealtimeTranslationSessionUpdateRequest

要更新的翻译会话字段。会话的 type 和 model 在 创建时设置，不能通过 session.update 更改。

• audio: optional object { input, output }

翻译输入与输出音频的配置。

• input: optional object { noise_reduction, transcription }

• noise_reduction: optional object { type, strength } or null

可选的输入降噪配置，设为 null 可禁用。

• type: NoiseReductionType

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

• "near_field"

• "far_field"

• strength: optional number (default: 1)

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

minimum: 0, maximum: 1

• transcription: optional object { model } or null

可选的源语言转录配置。配置后，服务器输出 session.input_transcript.delta 事件。翻译本身仍然直接基于 输入音频流。

• model: string

用于生成源语言转录文本增量的转录模型。

• output: optional object { language }

• language: optional string

翻译后音频与文本增量的目标语言。

• type: "session.update"

事件类型，须为 session.update。

• "session.update"

• event_id: optional string

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

maxLength: 512

Realtime 翻译会话更新请求

• RealtimeTranslationSessionUpdateRequest object { audio }

可通过 session.update 更新的 Realtime 翻译会话字段。

• audio: optional object { input, output }

翻译输入与输出音频的配置。

• input: optional object { noise_reduction, transcription }

• noise_reduction: optional object { type, strength } or null

可选的输入降噪配置，设为 null 可禁用。

• type: NoiseReductionType

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

• "near_field"

• "far_field"

• strength: optional number (default: 1)

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

minimum: 0, maximum: 1

• transcription: optional object { model } or null

可选的源语言转录配置。配置后，服务器输出 session.input_transcript.delta 事件。翻译本身仍然直接基于 输入音频流。

• model: string

用于生成源语言转录文本增量的转录模型。

• output: optional object { language }

• language: optional string

翻译后音频与文本增量的目标语言。

Realtime 翻译会话更新事件

• RealtimeTranslationSessionUpdatedEvent object { event_id, session, type }

通过 session.update 事件更新翻译会话后返回， 发生错误时除外。

• event_id: string

服务端事件的唯一 ID。

• session: RealtimeTranslationSession

翻译会话配置。

• id: string

会话唯一标识，类似 sess_1234567890abcdef。

• audio: object { input, output }

翻译输入与输出音频的配置。

• input: optional object { noise_reduction, transcription }

• noise_reduction: optional object { type, strength } or null

可选的输入降噪配置。

• type: NoiseReductionType

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

• "near_field"

• "far_field"

• strength: optional number (default: 1)

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

minimum: 0, maximum: 1

• transcription: optional object { model } or null

可选的源语言转录配置。配置后，服务器输出 session.input_transcript.delta 事件。翻译本身仍然直接基于 输入音频流。

• model: string

用于生成源语言转录文本增量的转录模型。

• output: optional object { language }

• language: optional string

翻译后音频与文本增量的目标语言。

• expires_at: integer

会话过期的 Unix 时间戳，单位为秒。

format: unixtime

• model: string

此会话使用的 Realtime 翻译模型。此字段在 创建会话时设置，无法通过 session.update 修改。

• type: "translation"

会话类型，Realtime 翻译会话固定为 translation。

• "translation"

• type: "session.updated"

事件类型，须为 session.updated。

• "session.updated"

Realtime 截断

• RealtimeTruncation = "auto" or "disabled" or RetentionRatioTruncation { retention_ratio, type, token_limits }

对话词元数超过模型的输入词元上限时，会截断对话，即从最早的消息开始，将部分消息排除在模型上下文之外。对于上下文为 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

响应音频增量事件

• ResponseAudioDeltaEvent object { content_index, delta, event_id, 4 more }

模型生成的音频更新时返回。

• content_index: integer

内容部分在条目 content 数组中的索引。

• delta: string

Base64 编码的音频数据增量。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

条目 ID。

• output_index: integer

输出条目在响应中的索引。

• response_id: string

响应 ID。

• type: "response.output_audio.delta"

事件类型，须为 response.output_audio.delta。

• "response.output_audio.delta"

响应音频完成事件

• ResponseAudioDoneEvent object { content_index, event_id, item_id, 3 more }

模型生成的音频结束时返回。响应被 打断、未完成或取消时也会发出。

• content_index: integer

内容部分在条目 content 数组中的索引。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

条目 ID。

• output_index: integer

输出条目在响应中的索引。

• response_id: string

响应 ID。

• type: "response.output_audio.done"

事件类型，须为 response.output_audio.done。

• "response.output_audio.done"

响应音频转录增量事件

• ResponseAudioTranscriptDeltaEvent object { content_index, delta, event_id, 4 more }

模型生成的输出音频转录文本更新时返回。

• content_index: integer

内容部分在条目 content 数组中的索引。

• delta: string

转录文本增量。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

条目 ID。

• output_index: integer

输出条目在响应中的索引。

• response_id: string

响应 ID。

• type: "response.output_audio_transcript.delta"

事件类型，须为 response.output_audio_transcript.delta。

• "response.output_audio_transcript.delta"

响应音频转录完成事件

• ResponseAudioTranscriptDoneEvent object { content_index, event_id, item_id, 4 more }

模型生成的输出音频转录流式 传输结束时返回。响应被打断、未完成或 取消时也会发出。

• content_index: integer

内容部分在条目 content 数组中的索引。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

条目 ID。

• output_index: integer

输出条目在响应中的索引。

• response_id: string

响应 ID。

• transcript: string

最终的音频转录文本。

• type: "response.output_audio_transcript.done"

事件类型，须为 response.output_audio_transcript.done。

• "response.output_audio_transcript.done"

响应取消事件

• ResponseCancelEvent object { type, event_id, response_id }

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

• type: "response.cancel"

事件类型，须为 response.cancel。

• "response.cancel"

• event_id: optional string

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

maxLength: 512

• response_id: optional string

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

响应内容部分添加事件

• ResponseContentPartAddedEvent object { content_index, event_id, item_id, 4 more }

生成响应时，向助手消息条目添加新的内容部分， 会返回此事件。

• content_index: integer

内容部分在条目 content 数组中的索引。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

添加此内容部分的条目的 ID。

• output_index: integer

输出条目在响应中的索引。

• part: object { audio, text, transcript, type }

添加的内容部分。

• audio: optional string

Base64 编码的音频数据，适用于 type 为 "audio" 的情况。

• text: optional string

文本内容，适用于 type 为 "text" 的情况。

• transcript: optional string

音频转录文本，适用于 type 为 "audio" 的情况。

• type: optional "audio" or "text"

内容类型："text" 或 "audio"。

• "audio"

• "text"

• response_id: string

响应 ID。

• type: "response.content_part.added"

事件类型，须为 response.content_part.added。

• "response.content_part.added"

响应内容部分完成事件

• ResponseContentPartDoneEvent object { content_index, event_id, item_id, 4 more }

助手消息条目中的内容部分流式传输结束时返回。 响应被打断、未完成或取消时也会发出。

• content_index: integer

内容部分在条目 content 数组中的索引。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

条目 ID。

• output_index: integer

输出条目在响应中的索引。

• part: object { audio, text, transcript, type }

已完成的内容部分。

• audio: optional string

Base64 编码的音频数据，适用于 type 为 "audio" 的情况。

• text: optional string

文本内容，适用于 type 为 "text" 的情况。

• transcript: optional string

音频转录文本，适用于 type 为 "audio" 的情况。

• type: optional "audio" or "text"

内容类型："text" 或 "audio"。

• "audio"

• "text"

• response_id: string

响应 ID。

• type: "response.content_part.done"

事件类型，须为 response.content_part.done。

• "response.content_part.done"

响应创建事件

• ResponseCreateEvent object { type, event_id, response }

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

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

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

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

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

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

• 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}$

响应创建事件

• ResponseCreatedEvent object { event_id, response, type }

新响应创建时返回，是响应创建过程的第一个事件， 此时响应处于初始 in_progress 状态。

• event_id: string

服务端事件的唯一 ID。

• response: RealtimeResponse

响应资源。

• id: optional string

响应的唯一 ID，形式类似 resp_1234。

• audio: optional object { output }

音频输出配置。

• 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 (default: "alloy")

模型响应使用的音色。在模型至少输出过一次音频后， 该会话期间不能再更改音色。当前 音色选项包括 alloy、ash、ballad、coral、echo、sage、 shimmer、verse、marin 和 cedar。建议使用 marin 和 cedar， 以获得最佳质量。

• string

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

模型响应使用的音色。在模型至少输出过一次音频后， 该会话期间不能再更改音色。当前 音色选项包括 alloy、ash、ballad、coral、echo、sage、 shimmer、verse、marin 和 cedar。建议使用 marin 和 cedar， 以获得最佳质量。

• "alloy"

• "ash"

• "ballad"

• "coral"

• "echo"

• "sage"

• "shimmer"

• "verse"

• "marin"

• "cedar"

• conversation_id: optional string

响应添加到哪个对话，由 response.create 中的 conversation 字段决定。为 auto 时，响应添加到 默认对话，conversation_id 为类似 conv_1234 的 ID。为 none 时，不添加到任何对话， conversation_id 为 null。如果响应由 VAD 自动触发，则添加到默认对话。

• max_output_tokens: optional number or "inf"

单次助手响应的最大输出词元数， 包括工具调用在内，本次响应使用的内容。

• number

• "inf"

• "inf"

• metadata: optional Metadata or null

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

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

• object: optional "realtime.response"

对象类型，须为 realtime.response。

• "realtime.response"

• output: optional array of ConversationItem

响应生成的输出条目列表。

• 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"

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

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

• "text"

• "audio"

• status: optional "completed" or "cancelled" or "failed" or 2 more

响应最终状态，可选 completed、cancelled、failed 或 incomplete, in_progress).

• "completed"

• "cancelled"

• "failed"

• "incomplete"

• "in_progress"

• status_details: optional RealtimeResponseStatus

状态的额外详情。

• error: optional object { code, message, type }

导致响应失败的错误的描述， 在 status 为 failed 时填充。

• code: optional string

错误代码（如有）。

• message: optional string

便于人类阅读的错误消息。

• type: optional string

错误类型。

• reason: optional "turn_detected" or "client_cancelled" or "max_output_tokens" or "content_filter"

响应未正常完成的原因。对于 cancelled，可为 turn_detected，即服务端 VAD 检测到新的语音开始，或 client_cancelled，即客户端发送取消事件。对于 incomplete，可为 max_output_tokens，或 content_filter，即服务端安全过滤器触发并截断响应。

• "turn_detected"

• "client_cancelled"

• "max_output_tokens"

• "content_filter"

• type: optional "completed" or "cancelled" or "failed" or "incomplete"

导致响应失败的错误类型，对应 status 字段的 completed、cancelled、incomplete、 failed).

• "completed"

• "cancelled"

• "failed"

• "incomplete"

• usage: optional RealtimeResponseUsage

响应的用量统计，对应计费。Realtime API 会话会维护对话上下文，并向对话追加新 条目，因此此前轮次的输出（文本和 音频词元）会成为后续轮次的输入。

• input_token_details: optional RealtimeResponseUsageInputTokenDetails

本次响应的输入词元详情。缓存词元是此前对话轮次中作为当前响应上下文的词元。缓存词元是输入词元的子集，因此输入词元包含缓存和未缓存词元。

• audio_tokens: optional integer

本次响应用作输入的音频词元数。

• cached_tokens: optional integer

本次响应用作输入的缓存词元数。

• cached_tokens_details: optional object { audio_tokens, image_tokens, text_tokens }

本次响应用作输入的缓存词元详情。

• audio_tokens: optional integer

本次响应用作输入的缓存音频词元数。

• image_tokens: optional integer

本次响应用作输入的缓存图像词元数。

• text_tokens: optional integer

本次响应用作输入的缓存文本词元数。

• image_tokens: optional integer

本次响应用作输入的图像词元数。

• text_tokens: optional integer

本次响应用作输入的文本词元数。

• input_tokens: optional integer

本次响应的输入词元数，包括文本和 音频词元。

• output_token_details: optional RealtimeResponseUsageOutputTokenDetails

本次响应的输出词元详情。

• audio_tokens: optional integer

本次响应使用的音频词元数。

• text_tokens: optional integer

本次响应使用的文本词元数。

• output_tokens: optional integer

本次响应发送的输出词元数，包括文本和 音频词元。

• total_tokens: optional integer

本次响应的词元总数，包括输入与输出的 文本和音频词元。

• type: "response.created"

事件类型，须为 response.created。

• "response.created"

响应完成事件

• ResponseDoneEvent object { event_id, response, type }

响应流式传输结束时返回，无论最终 状态如何都会发出。response.done 中的响应对象 包含全部输出条目，但省略原始音频数据。

客户端须检查响应的 status，判断是成功 （completed），还是 cancelled、failed 或 incomplete。

响应会包含生成过程中产生的全部输出条目， 但不包含音频内容。

• event_id: string

服务端事件的唯一 ID。

• response: RealtimeResponse

响应资源。

• id: optional string

响应的唯一 ID，形式类似 resp_1234。

• audio: optional object { output }

音频输出配置。

• 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 (default: "alloy")

模型响应使用的音色。在模型至少输出过一次音频后， 该会话期间不能再更改音色。当前 音色选项包括 alloy、ash、ballad、coral、echo、sage、 shimmer、verse、marin 和 cedar。建议使用 marin 和 cedar， 以获得最佳质量。

• string

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

模型响应使用的音色。在模型至少输出过一次音频后， 该会话期间不能再更改音色。当前 音色选项包括 alloy、ash、ballad、coral、echo、sage、 shimmer、verse、marin 和 cedar。建议使用 marin 和 cedar， 以获得最佳质量。

• "alloy"

• "ash"

• "ballad"

• "coral"

• "echo"

• "sage"

• "shimmer"

• "verse"

• "marin"

• "cedar"

• conversation_id: optional string

响应添加到哪个对话，由 response.create 中的 conversation 字段决定。为 auto 时，响应添加到 默认对话，conversation_id 为类似 conv_1234 的 ID。为 none 时，不添加到任何对话， conversation_id 为 null。如果响应由 VAD 自动触发，则添加到默认对话。

• max_output_tokens: optional number or "inf"

单次助手响应的最大输出词元数， 包括工具调用在内，本次响应使用的内容。

• number

• "inf"

• "inf"

• metadata: optional Metadata or null

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

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

• object: optional "realtime.response"

对象类型，须为 realtime.response。

• "realtime.response"

• output: optional array of ConversationItem

响应生成的输出条目列表。

• 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"

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

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

• "text"

• "audio"

• status: optional "completed" or "cancelled" or "failed" or 2 more

响应最终状态，可选 completed、cancelled、failed 或 incomplete, in_progress).

• "completed"

• "cancelled"

• "failed"

• "incomplete"

• "in_progress"

• status_details: optional RealtimeResponseStatus

状态的额外详情。

• error: optional object { code, message, type }

导致响应失败的错误的描述， 在 status 为 failed 时填充。

• code: optional string

错误代码（如有）。

• message: optional string

便于人类阅读的错误消息。

• type: optional string

错误类型。

• reason: optional "turn_detected" or "client_cancelled" or "max_output_tokens" or "content_filter"

响应未正常完成的原因。对于 cancelled，可为 turn_detected，即服务端 VAD 检测到新的语音开始，或 client_cancelled，即客户端发送取消事件。对于 incomplete，可为 max_output_tokens，或 content_filter，即服务端安全过滤器触发并截断响应。

• "turn_detected"

• "client_cancelled"

• "max_output_tokens"

• "content_filter"

• type: optional "completed" or "cancelled" or "failed" or "incomplete"

导致响应失败的错误类型，对应 status 字段的 completed、cancelled、incomplete、 failed).

• "completed"

• "cancelled"

• "failed"

• "incomplete"

• usage: optional RealtimeResponseUsage

响应的用量统计，对应计费。Realtime API 会话会维护对话上下文，并向对话追加新 条目，因此此前轮次的输出（文本和 音频词元）会成为后续轮次的输入。

• input_token_details: optional RealtimeResponseUsageInputTokenDetails

本次响应的输入词元详情。缓存词元是此前对话轮次中作为当前响应上下文的词元。缓存词元是输入词元的子集，因此输入词元包含缓存和未缓存词元。

• audio_tokens: optional integer

本次响应用作输入的音频词元数。

• cached_tokens: optional integer

本次响应用作输入的缓存词元数。

• cached_tokens_details: optional object { audio_tokens, image_tokens, text_tokens }

本次响应用作输入的缓存词元详情。

• audio_tokens: optional integer

本次响应用作输入的缓存音频词元数。

• image_tokens: optional integer

本次响应用作输入的缓存图像词元数。

• text_tokens: optional integer

本次响应用作输入的缓存文本词元数。

• image_tokens: optional integer

本次响应用作输入的图像词元数。

• text_tokens: optional integer

本次响应用作输入的文本词元数。

• input_tokens: optional integer

本次响应的输入词元数，包括文本和 音频词元。

• output_token_details: optional RealtimeResponseUsageOutputTokenDetails

本次响应的输出词元详情。

• audio_tokens: optional integer

本次响应使用的音频词元数。

• text_tokens: optional integer

本次响应使用的文本词元数。

• output_tokens: optional integer

本次响应发送的输出词元数，包括文本和 音频词元。

• total_tokens: optional integer

本次响应的词元总数，包括输入与输出的 文本和音频词元。

• type: "response.done"

事件类型，须为 response.done。

• "response.done"

响应函数调用参数增量事件

• ResponseFunctionCallArgumentsDeltaEvent object { call_id, delta, event_id, 4 more }

模型生成的函数调用参数更新时返回。

• call_id: string

函数调用 ID。

• delta: string

参数增量，以 JSON 字符串表示。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

函数调用条目的 ID。

• output_index: integer

输出条目在响应中的索引。

• response_id: string

响应 ID。

• type: "response.function_call_arguments.delta"

事件类型，须为 response.function_call_arguments.delta。

• "response.function_call_arguments.delta"

响应函数调用参数完成事件

• ResponseFunctionCallArgumentsDoneEvent object { arguments, call_id, event_id, 5 more }

模型生成的函数调用参数流式传输结束时返回。 响应被打断、未完成或取消时也会发出。

• arguments: string

最终参数，以 JSON 字符串表示。

• call_id: string

函数调用 ID。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

函数调用条目的 ID。

• name: string

已调用的函数名称。

• output_index: integer

输出条目在响应中的索引。

• response_id: string

响应 ID。

• type: "response.function_call_arguments.done"

事件类型，须为 response.function_call_arguments.done。

• "response.function_call_arguments.done"

响应条目引用

• 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"

响应MCP调用参数增量

• ResponseMcpCallArgumentsDelta object { delta, event_id, item_id, 4 more }

生成响应期间，MCP 工具调用参数更新时返回。

• delta: string

JSON 编码的参数增量。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

MCP 工具调用条目的 ID。

• output_index: integer

输出条目在响应中的索引。

• response_id: string

响应 ID。

• type: "response.mcp_call_arguments.delta"

事件类型，须为 response.mcp_call_arguments.delta。

• "response.mcp_call_arguments.delta"

• obfuscation: optional string or null

如提供此字段，表示增量文本已作混淆处理。

响应MCP调用参数完成

• ResponseMcpCallArgumentsDone object { arguments, event_id, item_id, 3 more }

生成响应期间，MCP 工具调用参数最终确定时返回。

• arguments: string

最终的 JSON 编码参数字符串。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

MCP 工具调用条目的 ID。

• output_index: integer

输出条目在响应中的索引。

• response_id: string

响应 ID。

• type: "response.mcp_call_arguments.done"

事件类型，须为 response.mcp_call_arguments.done。

• "response.mcp_call_arguments.done"

响应MCP调用完成

• ResponseMcpCallCompleted object { event_id, item_id, output_index, type }

MCP 工具调用成功完成时返回。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

MCP 工具调用条目的 ID。

• output_index: integer

输出条目在响应中的索引。

• type: "response.mcp_call.completed"

事件类型，须为 response.mcp_call.completed。

• "response.mcp_call.completed"

响应MCP调用失败

• ResponseMcpCallFailed object { event_id, item_id, output_index, type }

MCP 工具调用失败时返回。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

MCP 工具调用条目的 ID。

• output_index: integer

输出条目在响应中的索引。

• type: "response.mcp_call.failed"

事件类型，须为 response.mcp_call.failed。

• "response.mcp_call.failed"

响应MCP调用进行中

• ResponseMcpCallInProgress object { event_id, item_id, output_index, type }

MCP 工具调用已开始且正在进行时返回。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

MCP 工具调用条目的 ID。

• output_index: integer

输出条目在响应中的索引。

• type: "response.mcp_call.in_progress"

事件类型，须为 response.mcp_call.in_progress。

• "response.mcp_call.in_progress"

响应输出条目添加事件

• ResponseOutputItemAddedEvent object { event_id, item, output_index, 2 more }

响应生成期间创建新条目时返回。

• event_id: string

服务端事件的唯一 ID。

• 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"

• output_index: integer

输出条目在响应中的索引。

• response_id: string

条目所属响应的 ID。

• type: "response.output_item.added"

事件类型，须为 response.output_item.added。

• "response.output_item.added"

响应输出条目完成事件

• ResponseOutputItemDoneEvent object { event_id, item, output_index, 2 more }

条目流式传输结束时返回。响应被 打断、未完成或取消时也会发出。

• event_id: string

服务端事件的唯一 ID。

• 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"

• output_index: integer

输出条目在响应中的索引。

• response_id: string

条目所属响应的 ID。

• type: "response.output_item.done"

事件类型，须为 response.output_item.done。

• "response.output_item.done"

响应文本增量事件

• ResponseTextDeltaEvent object { content_index, delta, event_id, 4 more }

"output_text" 内容部分的文本值更新时返回。

• content_index: integer

内容部分在条目 content 数组中的索引。

• delta: string

文本增量。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

条目 ID。

• output_index: integer

输出条目在响应中的索引。

• response_id: string

响应 ID。

• type: "response.output_text.delta"

事件类型，须为 response.output_text.delta。

• "response.output_text.delta"

响应文本完成事件

• ResponseTextDoneEvent object { content_index, event_id, item_id, 4 more }

"output_text" 内容部分的文本值流式传输结束时返回。响应被 打断、未完成或取消时也会发出。

• content_index: integer

内容部分在条目 content 数组中的索引。

• event_id: string

服务端事件的唯一 ID。

• item_id: string

条目 ID。

• output_index: integer

输出条目在响应中的索引。

• response_id: string

响应 ID。

• text: string

最终文本内容。

• type: "response.output_text.done"

事件类型，须为 response.output_text.done。

• "response.output_text.done"

会话创建事件

• SessionCreatedEvent object { event_id, session, type }

会话创建时返回。在新连接 建立时自动作为第一个服务端事件发出，包含 默认会话配置。

• event_id: string

服务端事件的唯一 ID。

• session: RealtimeSessionCreateResponse or RealtimeTranscriptionSessionCreateResponse

会话配置。

• RealtimeSessionCreateResponse object { id, object, type, 13 more }

Realtime 会话配置对象。

• id: string

会话唯一标识，类似 sess_1234567890abcdef。

• object: "realtime.session"

对象类型，固定为 realtime.session。

• "realtime.session"

• type: "realtime"

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

• "realtime"

• audio: optional object { input, output }

输入和输出音频的配置。

• input: optional object { format, noise_reduction, transcription, turn_detection }

• 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 } or null (default: null)

输入音频降噪配置，设为 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 object { keywords, language, languages, 2 more } or null

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

• keywords: optional array of string

已配置的、用于引导输入音频转录的词语或短语。

• language: optional string or null

输入音频的语言。

• languages: optional array of string

为转录配置的输入音频可能使用的语言，采用 ISO-639-1 格式。

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。

• 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。

• "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

为输入音频转录配置的提示词（如有）。

• turn_detection: optional ServerVad { type, create_response, idle_timeout_ms, 4 more } or SemanticVad { type, create_response, eagerness, interrupt_response } 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 object { format, speed, voice }

• 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 (default: "alloy")

模型响应使用的音色。在模型至少输出过一次音频后， 该会话期间不能再更改音色。当前 音色选项包括 alloy、ash、ballad、coral、echo、sage、 shimmer、verse、marin 和 cedar。建议使用 marin 和 cedar， 以获得最佳质量。

• string

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

模型响应使用的音色。在模型至少输出过一次音频后， 该会话期间不能再更改音色。当前 音色选项包括 alloy、ash、ballad、coral、echo、sage、 shimmer、verse、marin 和 cedar。建议使用 marin 和 cedar， 以获得最佳质量。

• "alloy"

• "ash"

• "ballad"

• "coral"

• "echo"

• "sage"

• "shimmer"

• "verse"

• "marin"

• "cedar"

• expires_at: optional integer

会话过期的 Unix 时间戳，单位为秒。

format: unixtime

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

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

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"

• 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}$

• tracing: optional "auto" or TracingConfiguration { group_id, metadata, workflow_name } 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

• RealtimeTranscriptionSessionCreateResponse object { id, object, type, 3 more }

Realtime 转录会话配置对象。

• id: string

会话唯一标识，类似 sess_1234567890abcdef。

• object: string

对象类型，固定为 realtime.transcription_session。

• type: "transcription"

会话类型。对于转录会话，固定为 transcription。

• "transcription"

• audio: optional object { input }

会话的输入音频配置。

• input: optional object { format, noise_reduction, transcription, turn_detection }

• format: optional RealtimeAudioFormats

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

• noise_reduction: optional object { strength, type } or null

输入音频降噪配置。

• strength: optional number (default: 1)

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

minimum: 0, maximum: 1

• type: optional NoiseReductionType

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

• transcription: optional object { keywords, language, languages, 2 more } or null

转录模型配置。

• keywords: optional array of string

已配置的、用于引导输入音频转录的词语或短语。

• language: optional string or null

输入音频的语言。

• languages: optional array of string

为转录配置的输入音频可能使用的语言，采用 ISO-639-1 格式。

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。

• 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。

• "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

为输入音频转录配置的提示词（如有）。

• turn_detection: optional RealtimeTranscriptionSessionTurnDetection or null

话轮检测配置，可设为 null 关闭。服务端 VAD 表示模型根据 音量，并在用户讲话结束时响应。对于 gpt-realtime-whisper，此项必须为 null，因为不支持 VAD。

• prefix_padding_ms: optional integer

在 VAD 检测到语音之前一并保留的音频时长，单位为 毫秒，默认为 300 毫秒。

• silence_duration_ms: optional integer

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

• threshold: optional number

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

• type: optional string

话轮检测类型，目前仅支持 server_vad。

• expires_at: optional integer

会话过期的 Unix 时间戳，单位为秒。

format: unixtime

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

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

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

• "item.input_audio_transcription.logprobs"

• type: "session.created"

事件类型，须为 session.created。

• "session.created"

会话更新事件

• SessionUpdateEvent object { session, type, event_id }

发送此事件更新会话配置。 客户端可随时发送此事件更新字段， 但 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 会保留当前设置。

• 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

会话更新事件

• SessionUpdatedEvent object { event_id, session, type }

通过 session.update 更新会话后返回，除非 发生错误。

• event_id: string

服务端事件的唯一 ID。

• session: RealtimeSessionCreateResponse or RealtimeTranscriptionSessionCreateResponse

会话配置。

• RealtimeSessionCreateResponse object { id, object, type, 13 more }

Realtime 会话配置对象。

• id: string

会话唯一标识，类似 sess_1234567890abcdef。

• object: "realtime.session"

对象类型，固定为 realtime.session。

• "realtime.session"

• type: "realtime"

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

• "realtime"

• audio: optional object { input, output }

输入和输出音频的配置。

• input: optional object { format, noise_reduction, transcription, turn_detection }

• 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 } or null (default: null)

输入音频降噪配置，设为 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 object { keywords, language, languages, 2 more } or null

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

• keywords: optional array of string

已配置的、用于引导输入音频转录的词语或短语。

• language: optional string or null

输入音频的语言。

• languages: optional array of string

为转录配置的输入音频可能使用的语言，采用 ISO-639-1 格式。

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。

• 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。

• "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

为输入音频转录配置的提示词（如有）。

• turn_detection: optional ServerVad { type, create_response, idle_timeout_ms, 4 more } or SemanticVad { type, create_response, eagerness, interrupt_response } 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 object { format, speed, voice }

• 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 (default: "alloy")

模型响应使用的音色。在模型至少输出过一次音频后， 该会话期间不能再更改音色。当前 音色选项包括 alloy、ash、ballad、coral、echo、sage、 shimmer、verse、marin 和 cedar。建议使用 marin 和 cedar， 以获得最佳质量。

• string

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

模型响应使用的音色。在模型至少输出过一次音频后， 该会话期间不能再更改音色。当前 音色选项包括 alloy、ash、ballad、coral、echo、sage、 shimmer、verse、marin 和 cedar。建议使用 marin 和 cedar， 以获得最佳质量。

• "alloy"

• "ash"

• "ballad"

• "coral"

• "echo"

• "sage"

• "shimmer"

• "verse"

• "marin"

• "cedar"

• expires_at: optional integer

会话过期的 Unix 时间戳，单位为秒。

format: unixtime

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

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

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"

• 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}$

• tracing: optional "auto" or TracingConfiguration { group_id, metadata, workflow_name } 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

• RealtimeTranscriptionSessionCreateResponse object { id, object, type, 3 more }

Realtime 转录会话配置对象。

• id: string

会话唯一标识，类似 sess_1234567890abcdef。

• object: string

对象类型，固定为 realtime.transcription_session。

• type: "transcription"

会话类型。对于转录会话，固定为 transcription。

• "transcription"

• audio: optional object { input }

会话的输入音频配置。

• input: optional object { format, noise_reduction, transcription, turn_detection }

• format: optional RealtimeAudioFormats

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

• noise_reduction: optional object { strength, type } or null

输入音频降噪配置。

• strength: optional number (default: 1)

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

minimum: 0, maximum: 1

• type: optional NoiseReductionType

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

• transcription: optional object { keywords, language, languages, 2 more } or null

转录模型配置。

• keywords: optional array of string

已配置的、用于引导输入音频转录的词语或短语。

• language: optional string or null

输入音频的语言。

• languages: optional array of string

为转录配置的输入音频可能使用的语言，采用 ISO-639-1 格式。

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。

• 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。

• "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

为输入音频转录配置的提示词（如有）。

• turn_detection: optional RealtimeTranscriptionSessionTurnDetection or null

话轮检测配置，可设为 null 关闭。服务端 VAD 表示模型根据 音量，并在用户讲话结束时响应。对于 gpt-realtime-whisper，此项必须为 null，因为不支持 VAD。

• prefix_padding_ms: optional integer

在 VAD 检测到语音之前一并保留的音频时长，单位为 毫秒，默认为 300 毫秒。

• silence_duration_ms: optional integer

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

• threshold: optional number

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

• type: optional string

话轮检测类型，目前仅支持 server_vad。

• expires_at: optional integer

会话过期的 Unix 时间戳，单位为秒。

format: unixtime

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

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

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

• "item.input_audio_transcription.logprobs"

• type: "session.updated"

事件类型，须为 session.updated。

• "session.updated"

转录会话更新

• TranscriptionSessionUpdate object { session, type, event_id }

发送此事件更新转录会话。

• session: object { include, input_audio_format, input_audio_noise_reduction, 2 more }

Realtime 转录会话对象配置。

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

转录结果中需要包含的项目，目前可用项目如下。 item.input_audio_transcription.logprobs

• "item.input_audio_transcription.logprobs"

• input_audio_format: optional "pcm16" or "g711_ulaw" or "g711_alaw" (default: "pcm16")

输入音频格式，可选 pcm16、g711_ulaw 或 g711_alaw。 使用 pcm16 时，输入必须是 24 kHz 采样率的 16 位 PCM 音频， 采用单声道和小端字节序。

• "pcm16"

• "g711_ulaw"

• "g711_alaw"

• input_audio_noise_reduction: optional object { type }

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

• type: optional NoiseReductionType

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

• "near_field"

• "far_field"

• input_audio_transcription: optional AudioTranscription

输入音频转录配置。客户端可设置语言和提示词，为转录服务提供额外引导。

• 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 object { prefix_padding_ms, silence_duration_ms, threshold, type }

话轮检测配置，设为 null 可关闭。服务端 VAD 根据音量检测语音开始和结束，并在用户说话结束时响应。

• prefix_padding_ms: optional integer

在 VAD 检测到语音之前一并保留的音频时长，单位为 毫秒，默认为 300 毫秒。

• silence_duration_ms: optional integer

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

• threshold: optional number

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

• type: optional "server_vad"

话轮检测类型，转录会话目前仅支持 server_vad。

• "server_vad"

• type: "transcription_session.update"

事件类型，须为 transcription_session.update。

• "transcription_session.update"

• event_id: optional string

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

转录会话更新事件

• TranscriptionSessionUpdatedEvent object { event_id, session, type }

通过 transcription_session.update 更新转录会话后返回，除非 发生错误。

• event_id: string

服务端事件的唯一 ID。

• session: object { client_secret, input_audio_format, input_audio_transcription, 2 more }

新的 Realtime 转录会话配置。

通过 REST API 在服务端创建会话时，会话对象 还包含临时密钥，其默认 TTL 为 10 分钟。通过 WebSocket API 更新会话时，不提供此属性。

• client_secret: object { expires_at, value }

API 返回的临时密钥，仅在通过服务端 REST API 创建会话时提供。

• expires_at: integer

令牌过期的时间戳。目前所有令牌均在 一分钟后过期。

format: unixtime

• value: string

供客户端环境验证连接身份的临时密钥， 用于 Realtime API。客户端应使用该临时密钥。 标准 API 令牌仅供服务端使用。

• input_audio_format: optional string

输入音频格式，可选 pcm16、g711_ulaw 或 g711_alaw。

• input_audio_transcription: optional object { keywords, language, languages, 2 more }

转录模型配置。

• keywords: optional array of string

已配置的、用于引导输入音频转录的词语或短语。

• language: optional string or null

输入音频的语言。

• languages: optional array of string

为转录配置的输入音频可能使用的语言，采用 ISO-639-1 格式。

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。

• 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。

• "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

为输入音频转录配置的提示词（如有）。

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

模型可用于响应的模态集合。如需禁用音频， 设为 ["text"]。

• "text"

• "audio"

• turn_detection: optional object { prefix_padding_ms, silence_duration_ms, threshold, type }

话轮检测配置，可设为 null 关闭。服务端 VAD 表示模型根据 音量检测语音的开始与结束，并在用户说话结束时响应。

• prefix_padding_ms: optional integer

在 VAD 检测到语音之前一并保留的音频时长，单位为 毫秒，默认为 300 毫秒。

• silence_duration_ms: optional integer

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

• threshold: optional number

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

• type: optional string

话轮检测类型，目前仅支持 server_vad。

• type: "transcription_session.updated"

事件类型，须为 transcription_session.updated。

• "transcription_session.updated"

Calls 呼叫资源

接听呼叫

post /realtime/calls/{call_id}/accept

接听 SIP 来电，并配置用于处理该呼叫的 Realtime 会话。

路径参数

• call_id: string

由以下 webhook 提供的呼叫标识： realtime.call.incoming 事件。

请求体参数

内容类型：application/json

• 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 (default: 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

示例

## 设置 OPENAI_API_KEY，并按接口替换呼叫 ID、会话参数和请求数据。
curl https://api.openai.com/v1/realtime/calls/$CALL_ID/accept \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
          "type": "realtime"
        }'

示例

## 设置 OPENAI_API_KEY，并按接口替换呼叫 ID、会话参数和请求数据。
curl -X POST https://api.openai.com/v1/realtime/calls/$CALL_ID/accept \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "type": "realtime",
        "model": "gpt-realtime",
        "instructions": "你是 Alex，Example Corp. 一位友好的礼宾服务助手。"
      }'

创建呼叫

post /realtime/calls

通过 WebRTC 创建新的 Realtime API 呼叫，并获取完成对等连接 所需的 SDP 应答。

请求体参数

内容类型为 multipart/form-data。

• sdp: string

呼叫方生成的 WebRTC 会话描述协议（SDP）提议。

• session: optional RealtimeSessionCreateRequest

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

请求体参数

内容类型：application/sdp

• body: string

WebRTC SDP 提议。在此前已创建临时 会话令牌且使用该令牌认证请求时，使用此变体。 Realtime 会话参数将从会话令牌中获取。

示例

## 设置 OPENAI_API_KEY，并按接口替换呼叫 ID、会话参数和请求数据。
curl https://api.openai.com/v1/realtime/calls \
    -H 'Content-Type: multipart/form-data' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -F sdp=sdp

示例

## 设置 OPENAI_API_KEY，并按接口替换呼叫 ID、会话参数和请求数据。
curl -X POST https://api.openai.com/v1/realtime/calls \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F "sdp=<offer.sdp;type=application/sdp" \
  -F 'session={"type":"realtime","model":"gpt-realtime"};type=application/json'

响应示例

v=0
o=- 4227147428 1719357865 IN IP4 127.0.0.1
s=-
c=IN IP4 0.0.0.0
t=0 0
a=group:BUNDLE 0 1
a=msid-semantic:WMS *
a=fingerprint:sha-256 CA:92:52:51:B4:91:3B:34:DD:9C:0B:FB:76:19:7E:3B:F1:21:0F:32:2C:38:01:72:5D:3F:78:C7:5F:8B:C7:36
m=audio 9 UDP/TLS/RTP/SAVPF 111 0 8
a=mid:0
a=ice-ufrag:kZ2qkHXX/u11
a=ice-pwd:uoD16Di5OGx3VbqgA3ymjEQV2kwiOjw6
a=setup:active
a=rtcp-mux
a=rtpmap:111 opus/48000/2
a=candidate:993865896 1 udp 2130706431 4.155.146.196 3478 typ host ufrag kZ2qkHXX/u11
a=candidate:1432411780 1 tcp 1671430143 4.155.146.196 443 typ host tcptype passive ufrag kZ2qkHXX/u11
m=application 9 UDP/DTLS/SCTP webrtc-datachannel
a=mid:1
a=sctp-port:5000

挂断呼叫

post /realtime/calls/{call_id}/hangup

结束正在进行的 Realtime API 呼叫，无论该呼叫通过 SIP 还是 WebRTC 发起。

路径参数

• call_id: string

呼叫标识。对于 SIP 呼叫，使用 realtime.call.incoming webhook 提供的值。对于 WebRTC 会话，复用创建呼叫时 Location 响应头中返回的呼叫 ID；创建接口为 POST /v1/realtime/calls。

示例

## 设置 OPENAI_API_KEY，并按接口替换呼叫 ID、会话参数和请求数据。
curl https://api.openai.com/v1/realtime/calls/$CALL_ID/hangup \
    -X POST \
    -H "Authorization: Bearer $OPENAI_API_KEY"

示例

## 设置 OPENAI_API_KEY，并按接口替换呼叫 ID、会话参数和请求数据。
curl -X POST https://api.openai.com/v1/realtime/calls/$CALL_ID/hangup \
  -H "Authorization: Bearer $OPENAI_API_KEY"

转接呼叫

post /realtime/calls/{call_id}/refer

使用 SIP REFER 方法，将正在进行的 SIP 呼叫转接到新目标。

路径参数

• call_id: string

由以下 webhook 提供的呼叫标识： realtime.call.incoming 事件。

请求体参数

内容类型：application/json

• target_uri: string

应放入 SIP Refer-To 头中的 URI，支持以下形式： tel:+14155550123 或 sip:agent@example.com。

示例

## 设置 OPENAI_API_KEY，并按接口替换呼叫 ID、会话参数和请求数据。
curl https://api.openai.com/v1/realtime/calls/$CALL_ID/refer \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
          "target_uri": "tel:+14155550123"
        }'

示例

## 设置 OPENAI_API_KEY，并按接口替换呼叫 ID、会话参数和请求数据。
curl -X POST https://api.openai.com/v1/realtime/calls/$CALL_ID/refer \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_uri": "tel:+14155550123"}'

拒接呼叫

post /realtime/calls/{call_id}/reject

向呼叫方返回 SIP 状态码，以拒绝 SIP 来电。

路径参数

• call_id: string

由以下 webhook 提供的呼叫标识： realtime.call.incoming 事件。

请求体参数

内容类型：application/json

• status_code: optional integer

要返回给呼叫方的 SIP 响应码。省略时默认为 603，即拒绝 （Decline）。

示例

## 设置 OPENAI_API_KEY，并按接口替换呼叫 ID、会话参数和请求数据。
curl https://api.openai.com/v1/realtime/calls/$CALL_ID/reject \
    -X POST \
    -H "Authorization: Bearer $OPENAI_API_KEY"

示例

## 设置 OPENAI_API_KEY，并按接口替换呼叫 ID、会话参数和请求数据。
curl -X POST https://api.openai.com/v1/realtime/calls/$CALL_ID/reject \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status_code": 486}'

Client Secrets 客户端密钥资源

创建客户端密钥

post /realtime/client_secrets

创建 Realtime 客户端密钥，并关联会话配置。

客户端密钥是短期令牌，可传递给客户端应用， 例如网页前端或移动客户端；它允许访问 Realtime API， 同时不泄露主 API 密钥。可以为每个客户端密钥配置自定义 TTL。

也可以将会话配置选项附加到客户端密钥上， 使用该密钥创建的会话会应用这些选项，但客户端连接也可以 覆盖它们。

了解使用客户端密钥通过 WebRTC 进行认证。

返回创建的客户端密钥与实际生效的会话对象。客户端密钥是类似 ek_1234 的字符串。

请求体参数

内容类型：application/json

• expires_after: optional object { anchor, seconds }

客户端密钥过期配置。过期时间表示此时间之后 无法再用该密钥创建会话。已经启动的会话本身 可以继续运行。在密钥过期之前，可使用同一个密钥创建多个会话， 直至密钥过期。

• anchor: optional "created_at" (default: "created_at")

客户端密钥过期时间的基准点。将 seconds 加到密钥的 created_at 时间上即可得到过期时间戳。目前仅支持 created_at。

• "created_at"

• seconds: optional integer (default: 600)

从基准点到过期时间的秒数，可选 10–7200 秒（2 小时），省略时默认为 600 秒（10 分钟）。

format: int64, minimum: 10, maximum: 7200

• session: optional RealtimeSessionCreateRequest or RealtimeTranscriptionSessionCreateRequest

客户端密钥使用的会话配置。选择 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"

返回值

• expires_at: integer

客户端密钥过期的 Unix 时间戳，单位为秒。

format: unixtime

• session: RealtimeSessionCreateResponse or RealtimeTranscriptionSessionCreateResponse

realtime 会话或转录会话的配置。

• RealtimeSessionCreateResponse object { id, object, type, 13 more }

Realtime 会话配置对象。

• id: string

会话唯一标识，类似 sess_1234567890abcdef。

• object: "realtime.session"

对象类型，固定为 realtime.session。

• "realtime.session"

• type: "realtime"

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

• "realtime"

• audio: optional object { input, output }

输入和输出音频的配置。

• input: optional object { format, noise_reduction, transcription, turn_detection }

• 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 } or null (default: null)

输入音频降噪配置，设为 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 object { keywords, language, languages, 2 more } or null

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

• keywords: optional array of string

已配置的、用于引导输入音频转录的词语或短语。

• language: optional string or null

输入音频的语言。

• languages: optional array of string

为转录配置的输入音频可能使用的语言，采用 ISO-639-1 格式。

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。

• 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。

• "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

为输入音频转录配置的提示词（如有）。

• turn_detection: optional ServerVad { type, create_response, idle_timeout_ms, 4 more } or SemanticVad { type, create_response, eagerness, interrupt_response } 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 object { format, speed, voice }

• 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 (default: "alloy")

模型响应使用的音色。在模型至少输出过一次音频后， 该会话期间不能再更改音色。当前 音色选项包括 alloy、ash、ballad、coral、echo、sage、 shimmer、verse、marin 和 cedar。建议使用 marin 和 cedar， 以获得最佳质量。

• string

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

模型响应使用的音色。在模型至少输出过一次音频后， 该会话期间不能再更改音色。当前 音色选项包括 alloy、ash、ballad、coral、echo、sage、 shimmer、verse、marin 和 cedar。建议使用 marin 和 cedar， 以获得最佳质量。

• "alloy"

• "ash"

• "ballad"

• "coral"

• "echo"

• "sage"

• "shimmer"

• "verse"

• "marin"

• "cedar"

• expires_at: optional integer

会话过期的 Unix 时间戳，单位为秒。

format: unixtime

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

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

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"

• 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}$

• tracing: optional "auto" or TracingConfiguration { group_id, metadata, workflow_name } 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

• RealtimeTranscriptionSessionCreateResponse object { id, object, type, 3 more }

Realtime 转录会话配置对象。

• id: string

会话唯一标识，类似 sess_1234567890abcdef。

• object: string

对象类型，固定为 realtime.transcription_session。

• type: "transcription"

会话类型。对于转录会话，固定为 transcription。

• "transcription"

• audio: optional object { input }

会话的输入音频配置。

• input: optional object { format, noise_reduction, transcription, turn_detection }

• format: optional RealtimeAudioFormats

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

• noise_reduction: optional object { strength, type } or null

输入音频降噪配置。

• strength: optional number (default: 1)

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

minimum: 0, maximum: 1

• type: optional NoiseReductionType

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

• transcription: optional object { keywords, language, languages, 2 more } or null

转录模型配置。

• keywords: optional array of string

已配置的、用于引导输入音频转录的词语或短语。

• language: optional string or null

输入音频的语言。

• languages: optional array of string

为转录配置的输入音频可能使用的语言，采用 ISO-639-1 格式。

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。

• 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。

• "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

为输入音频转录配置的提示词（如有）。

• turn_detection: optional RealtimeTranscriptionSessionTurnDetection or null

话轮检测配置，可设为 null 关闭。服务端 VAD 表示模型根据 音量，并在用户讲话结束时响应。对于 gpt-realtime-whisper，此项必须为 null，因为不支持 VAD。

• prefix_padding_ms: optional integer

在 VAD 检测到语音之前一并保留的音频时长，单位为 毫秒，默认为 300 毫秒。

• silence_duration_ms: optional integer

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

• threshold: optional number

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

• type: optional string

话轮检测类型，目前仅支持 server_vad。

• expires_at: optional integer

会话过期的 Unix 时间戳，单位为秒。

format: unixtime

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

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

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

• "item.input_audio_transcription.logprobs"

• value: string

生成的客户端密钥值。

示例

## 设置 OPENAI_API_KEY，并按接口替换呼叫 ID、会话参数和请求数据。
curl https://api.openai.com/v1/realtime/client_secrets \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{}'

200 响应示例

{
  "expires_at": 0,
  "session": {
    "id": "id",
    "object": "realtime.session",
    "type": "realtime",
    "audio": {
      "input": {
        "format": {
          "rate": 24000,
          "type": "audio/pcm"
        },
        "noise_reduction": {
          "strength": 0,
          "type": "near_field"
        },
        "transcription": {
          "keywords": [
            "string"
          ],
          "language": "language",
          "languages": [
            "string"
          ],
          "model": "gpt-transcribe",
          "prompt": "prompt"
        },
        "turn_detection": {
          "type": "server_vad",
          "create_response": true,
          "idle_timeout_ms": 5000,
          "interrupt_response": true,
          "prefix_padding_ms": 0,
          "silence_duration_ms": 0,
          "threshold": 0
        }
      },
      "output": {
        "format": {
          "rate": 24000,
          "type": "audio/pcm"
        },
        "speed": 0.25,
        "voice": "ash"
      }
    },
    "expires_at": 0,
    "include": [
      "item.input_audio_transcription.logprobs"
    ],
    "instructions": "instructions",
    "max_output_tokens": "inf",
    "model": "gpt-realtime-1.5",
    "output_modalities": [
      "text"
    ],
    "prompt": {
      "id": "id",
      "variables": {
        "foo": "string"
      },
      "version": "version"
    },
    "reasoning": {
      "effort": "minimal"
    },
    "tool_choice": "none",
    "tools": [
      {
        "description": "description",
        "name": "name",
        "parameters": {},
        "type": "function"
      }
    ],
    "tracing": "auto",
    "truncation": "auto"
  },
  "value": "value"
}

示例

## 设置 OPENAI_API_KEY，并按接口替换呼叫 ID、会话参数和请求数据。
curl -X POST https://api.openai.com/v1/realtime/client_secrets \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expires_after": {
      "anchor": "created_at",
      "seconds": 600
    },
    "session": {
      "type": "realtime",
      "model": "gpt-realtime",
      "instructions": "你是一名友好的助手。"
    }
  }'

响应示例

{
  "value": "ek_68af296e8e408191a1120ab6383263c2",
  "expires_at": 1756310470,
  "session": {
    "type": "realtime",
    "object": "realtime.session",
    "id": "sess_C9CiUVUzUzYIssh3ELY1d",
    "model": "gpt-realtime",
    "output_modalities": [
      "audio"
    ],
    "instructions": "你是一名友好的助手。",
    "tools": [],
    "tool_choice": "auto",
    "max_output_tokens": "inf",
    "tracing": null,
    "truncation": "auto",
    "prompt": null,
    "expires_at": 0,
    "audio": {
      "input": {
        "format": {
          "type": "audio/pcm",
          "rate": 24000
        },
        "transcription": null,
        "noise_reduction": null,
        "turn_detection": {
          "type": "server_vad"
        }
      },
      "output": {
        "format": {
          "type": "audio/pcm",
          "rate": 24000
        },
        "voice": "alloy",
        "speed": 1.0
      }
    },
    "include": null
  }
}

资源类型

客户端密钥创建响应

• ClientSecretCreateResponse object { expires_at, session, value }

创建 Realtime API 会话与客户端密钥后返回的响应。

• expires_at: integer

客户端密钥过期的 Unix 时间戳，单位为秒。

format: unixtime

• session: RealtimeSessionCreateResponse or RealtimeTranscriptionSessionCreateResponse

realtime 会话或转录会话的配置。

• RealtimeSessionCreateResponse object { id, object, type, 13 more }

Realtime 会话配置对象。

• id: string

会话唯一标识，类似 sess_1234567890abcdef。

• object: "realtime.session"

对象类型，固定为 realtime.session。

• "realtime.session"

• type: "realtime"

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

• "realtime"

• audio: optional object { input, output }

输入和输出音频的配置。

• input: optional object { format, noise_reduction, transcription, turn_detection }

• 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 } or null (default: null)

输入音频降噪配置，设为 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 object { keywords, language, languages, 2 more } or null

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

• keywords: optional array of string

已配置的、用于引导输入音频转录的词语或短语。

• language: optional string or null

输入音频的语言。

• languages: optional array of string

为转录配置的输入音频可能使用的语言，采用 ISO-639-1 格式。

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。

• 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。

• "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

为输入音频转录配置的提示词（如有）。

• turn_detection: optional ServerVad { type, create_response, idle_timeout_ms, 4 more } or SemanticVad { type, create_response, eagerness, interrupt_response } 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 object { format, speed, voice }

• 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 (default: "alloy")

模型响应使用的音色。在模型至少输出过一次音频后， 该会话期间不能再更改音色。当前 音色选项包括 alloy、ash、ballad、coral、echo、sage、 shimmer、verse、marin 和 cedar。建议使用 marin 和 cedar， 以获得最佳质量。

• string

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

模型响应使用的音色。在模型至少输出过一次音频后， 该会话期间不能再更改音色。当前 音色选项包括 alloy、ash、ballad、coral、echo、sage、 shimmer、verse、marin 和 cedar。建议使用 marin 和 cedar， 以获得最佳质量。

• "alloy"

• "ash"

• "ballad"

• "coral"

• "echo"

• "sage"

• "shimmer"

• "verse"

• "marin"

• "cedar"

• expires_at: optional integer

会话过期的 Unix 时间戳，单位为秒。

format: unixtime

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

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

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"

• 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}$

• tracing: optional "auto" or TracingConfiguration { group_id, metadata, workflow_name } 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

• RealtimeTranscriptionSessionCreateResponse object { id, object, type, 3 more }

Realtime 转录会话配置对象。

• id: string

会话唯一标识，类似 sess_1234567890abcdef。

• object: string

对象类型，固定为 realtime.transcription_session。

• type: "transcription"

会话类型。对于转录会话，固定为 transcription。

• "transcription"

• audio: optional object { input }

会话的输入音频配置。

• input: optional object { format, noise_reduction, transcription, turn_detection }

• format: optional RealtimeAudioFormats

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

• noise_reduction: optional object { strength, type } or null

输入音频降噪配置。

• strength: optional number (default: 1)

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

minimum: 0, maximum: 1

• type: optional NoiseReductionType

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

• transcription: optional object { keywords, language, languages, 2 more } or null

转录模型配置。

• keywords: optional array of string

已配置的、用于引导输入音频转录的词语或短语。

• language: optional string or null

输入音频的语言。

• languages: optional array of string

为转录配置的输入音频可能使用的语言，采用 ISO-639-1 格式。

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。

• 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。

• "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

为输入音频转录配置的提示词（如有）。

• turn_detection: optional RealtimeTranscriptionSessionTurnDetection or null

话轮检测配置，可设为 null 关闭。服务端 VAD 表示模型根据 音量，并在用户讲话结束时响应。对于 gpt-realtime-whisper，此项必须为 null，因为不支持 VAD。

• prefix_padding_ms: optional integer

在 VAD 检测到语音之前一并保留的音频时长，单位为 毫秒，默认为 300 毫秒。

• silence_duration_ms: optional integer

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

• threshold: optional number

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

• type: optional string

话轮检测类型，目前仅支持 server_vad。

• expires_at: optional integer

会话过期的 Unix 时间戳，单位为秒。

format: unixtime

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

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

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

• "item.input_audio_transcription.logprobs"

• value: string

生成的客户端密钥值。

Realtime 会话创建响应

• RealtimeSessionCreateResponse object { id, object, type, 13 more }

Realtime 会话配置对象。

• id: string

会话唯一标识，类似 sess_1234567890abcdef。

• object: "realtime.session"

对象类型，固定为 realtime.session。

• "realtime.session"

• type: "realtime"

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

• "realtime"

• audio: optional object { input, output }

输入和输出音频的配置。

• input: optional object { format, noise_reduction, transcription, turn_detection }

• 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 } or null (default: null)

输入音频降噪配置，设为 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 object { keywords, language, languages, 2 more } or null

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

• keywords: optional array of string

已配置的、用于引导输入音频转录的词语或短语。

• language: optional string or null

输入音频的语言。

• languages: optional array of string

为转录配置的输入音频可能使用的语言，采用 ISO-639-1 格式。

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。

• 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。

• "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

为输入音频转录配置的提示词（如有）。

• turn_detection: optional ServerVad { type, create_response, idle_timeout_ms, 4 more } or SemanticVad { type, create_response, eagerness, interrupt_response } 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 object { format, speed, voice }

• 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 (default: "alloy")

模型响应使用的音色。在模型至少输出过一次音频后， 该会话期间不能再更改音色。当前 音色选项包括 alloy、ash、ballad、coral、echo、sage、 shimmer、verse、marin 和 cedar。建议使用 marin 和 cedar， 以获得最佳质量。

• string

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

模型响应使用的音色。在模型至少输出过一次音频后， 该会话期间不能再更改音色。当前 音色选项包括 alloy、ash、ballad、coral、echo、sage、 shimmer、verse、marin 和 cedar。建议使用 marin 和 cedar， 以获得最佳质量。

• "alloy"

• "ash"

• "ballad"

• "coral"

• "echo"

• "sage"

• "shimmer"

• "verse"

• "marin"

• "cedar"

• expires_at: optional integer

会话过期的 Unix 时间戳，单位为秒。

format: unixtime

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

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

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"

• 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}$

• tracing: optional "auto" or TracingConfiguration { group_id, metadata, workflow_name } 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

Realtime 转录会话创建响应

• RealtimeTranscriptionSessionCreateResponse object { id, object, type, 3 more }

Realtime 转录会话配置对象。

• id: string

会话唯一标识，类似 sess_1234567890abcdef。

• object: string

对象类型，固定为 realtime.transcription_session。

• type: "transcription"

会话类型。对于转录会话，固定为 transcription。

• "transcription"

• audio: optional object { input }

会话的输入音频配置。

• input: optional object { format, noise_reduction, transcription, turn_detection }

• format: optional RealtimeAudioFormats

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

• 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 } or null

输入音频降噪配置。

• strength: optional number (default: 1)

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

minimum: 0, maximum: 1

• type: optional NoiseReductionType

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

• "near_field"

• "far_field"

• transcription: optional object { keywords, language, languages, 2 more } or null

转录模型配置。

• keywords: optional array of string

已配置的、用于引导输入音频转录的词语或短语。

• language: optional string or null

输入音频的语言。

• languages: optional array of string

为转录配置的输入音频可能使用的语言，采用 ISO-639-1 格式。

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。

• 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。

• "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

为输入音频转录配置的提示词（如有）。

• turn_detection: optional RealtimeTranscriptionSessionTurnDetection or null

话轮检测配置，可设为 null 关闭。服务端 VAD 表示模型根据 音量，并在用户讲话结束时响应。对于 gpt-realtime-whisper，此项必须为 null，因为不支持 VAD。

• prefix_padding_ms: optional integer

在 VAD 检测到语音之前一并保留的音频时长，单位为 毫秒，默认为 300 毫秒。

• silence_duration_ms: optional integer

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

• threshold: optional number

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

• type: optional string

话轮检测类型，目前仅支持 server_vad。

• expires_at: optional integer

会话过期的 Unix 时间戳，单位为秒。

format: unixtime

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

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

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

• "item.input_audio_transcription.logprobs"

Realtime 转录会话轮次检测

• RealtimeTranscriptionSessionTurnDetection object { prefix_padding_ms, silence_duration_ms, threshold, type }

话轮检测配置，可设为 null 关闭。服务端 VAD 表示模型根据 音量，并在用户讲话结束时响应。对于 gpt-realtime-whisper，此项必须为 null，因为不支持 VAD。

• prefix_padding_ms: optional integer

在 VAD 检测到语音之前一并保留的音频时长，单位为 毫秒，默认为 300 毫秒。

• silence_duration_ms: optional integer

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

• threshold: optional number

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

• type: optional string

话轮检测类型，目前仅支持 server_vad。

Sessions 会话资源

创建会话

post /realtime/sessions

创建供客户端应用使用的临时 API 令牌，用于 Realtime API。会话参数与 session.update 客户端事件中可配置的参数相同。

响应包含会话对象和 client_secret 字段，其中包含 可用于浏览器客户端身份验证的临时 API 令牌， 用于访问 Realtime API。

返回创建的 Realtime 会话对象以及临时密钥。

请求体参数

内容类型：application/json

• client_secret: object { expires_at, value }

API 返回的临时密钥。

• expires_at: integer

令牌过期的时间戳。目前所有令牌均在 一分钟后过期。

format: unixtime

• value: string

供客户端环境验证连接身份的临时密钥， 用于 Realtime API。客户端应使用该临时密钥。 标准 API 令牌仅供服务端使用。

• input_audio_format: optional string

输入音频格式，可选 pcm16、g711_ulaw 或 g711_alaw。

• input_audio_transcription: optional object { model }

输入音频转录配置，默认关闭；开启后可以 设为 null 再次关闭。输入音频转录不是模型的原生处理过程， 因为模型直接处理音频。转录以 异步方式执行，只能作为内容的大致参考， 不能视为模型实际理解内容的表示。

• model: optional string

转录使用的模型。

• instructions: optional string

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

• max_response_output_tokens: optional number or "inf"

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

• number

• "inf"

• "inf"

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

模型可用于响应的模态集合。如需禁用音频， 设为 ["text"]。

• "text"

• "audio"

• output_audio_format: optional string

输出音频格式，可选 pcm16、g711_ulaw 或 g711_alaw。

• 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

提示词模板的可选版本。

• speed: optional number (default: 1)

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

minimum: 0.25, maximum: 1.5

• temperature: optional number

模型采样温度，限制在 [0.6, 1.2]，默认为 0.8。

• tool_choice: optional string

模型选择工具的方式，可选 auto、none、required，或 指定一个函数。

• tools: optional array of object { description, name, parameters, type }

模型可用的工具（函数）。

• description: optional string

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

• name: optional string

函数名称。

• parameters: optional unknown

以 JSON Schema 描述的函数参数。

• type: optional "function"

工具类型，即 function。

• "function"

• tracing: optional "auto" or TracingConfiguration { group_id, metadata, workflow_name }

追踪配置选项。设为 null 可禁用追踪。一旦 为会话启用追踪，就不能修改配置。

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

• "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

• turn_detection: optional object { prefix_padding_ms, silence_duration_ms, threshold, type }

话轮检测配置，可设为 null 关闭。服务端 VAD 表示模型根据 音量检测语音的开始与结束，并在用户说话结束时响应。

• prefix_padding_ms: optional integer

在 VAD 检测到语音之前一并保留的音频时长，单位为 毫秒，默认为 300 毫秒。

• silence_duration_ms: optional integer

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

• threshold: optional number

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

• type: optional string

话轮检测类型，目前仅支持 server_vad。

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

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

• 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。

返回值

• id: optional string

会话唯一标识，类似 sess_1234567890abcdef。

• audio: optional object { input, output }

会话的输入和输出音频配置。

• input: optional object { format, noise_reduction, transcription, turn_detection }

• format: optional RealtimeAudioFormats

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

• 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 { type } or null

输入音频降噪配置。

• type: optional NoiseReductionType

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

• "near_field"

• "far_field"

• transcription: optional object { keywords, language, languages, 2 more }

输入音频转录配置。

• keywords: optional array of string

已配置的、用于引导输入音频转录的词语或短语。

• language: optional string or null

输入音频的语言。

• languages: optional array of string

为转录配置的输入音频可能使用的语言，采用 ISO-639-1 格式。

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。

• 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。

• "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

为输入音频转录配置的提示词（如有）。

• turn_detection: optional object { prefix_padding_ms, silence_duration_ms, threshold, type } or null

轮次检测配置。

• prefix_padding_ms: optional integer

• silence_duration_ms: optional integer

• threshold: optional number

• type: optional string

话轮检测类型，目前仅支持 server_vad。

• output: optional object { format, speed, voice }

• format: optional RealtimeAudioFormats

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

• speed: optional number

• voice: optional string or "alloy" or "ash" or "ballad" or 7 more

• string

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

• "alloy"

• "ash"

• "ballad"

• "coral"

• "echo"

• "sage"

• "shimmer"

• "verse"

• "marin"

• "cedar"

• expires_at: optional integer

会话过期的 Unix 时间戳，单位为秒。

format: unixtime

• 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

此会话使用的 Realtime 模型。

• object: optional string

对象类型，固定为 realtime.session。

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

模型可用于响应的模态集合。如需禁用音频， 设为 ["text"]。

• "text"

• "audio"

• tool_choice: optional string

模型选择工具的方式，可选 auto、none、required，或 指定一个函数。

• tools: optional array of RealtimeFunctionTool

模型可用的工具（函数）。

• description: optional string

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

• name: optional string

函数名称。

• parameters: optional unknown

以 JSON Schema 描述的函数参数。

• type: optional "function"

工具类型，即 function。

• "function"

• tracing: optional "auto" or TracingConfiguration { group_id, metadata, workflow_name }

追踪配置选项。设为 null 可禁用追踪。一旦 为会话启用追踪，就不能修改配置。

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

• "auto"

会话的默认追踪模式。

• "auto"

• TracingConfiguration object { group_id, metadata, workflow_name }

追踪的细粒度配置。

• group_id: optional string

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

• metadata: optional unknown

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

• workflow_name: optional string

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

• turn_detection: optional object { prefix_padding_ms, silence_duration_ms, threshold, type } or null

话轮检测配置，可设为 null 关闭。服务端 VAD 表示模型根据 音量检测语音的开始与结束，并在用户说话结束时响应。

• prefix_padding_ms: optional integer

在 VAD 检测到语音之前一并保留的音频时长，单位为 毫秒，默认为 300 毫秒。

• silence_duration_ms: optional integer

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

• threshold: optional number

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

• type: optional string

话轮检测类型，目前仅支持 server_vad。

示例

## 设置 OPENAI_API_KEY，并按接口替换呼叫 ID、会话参数和请求数据。
curl https://api.openai.com/v1/realtime/sessions \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
          "client_secret": {
            "expires_at": 0,
            "value": "value"
          }
        }'

200 响应示例

{
  "id": "id",
  "audio": {
    "input": {
      "format": {
        "rate": 24000,
        "type": "audio/pcm"
      },
      "noise_reduction": {
        "type": "near_field"
      },
      "transcription": {
        "keywords": [
          "string"
        ],
        "language": "language",
        "languages": [
          "string"
        ],
        "model": "gpt-transcribe",
        "prompt": "prompt"
      },
      "turn_detection": {
        "prefix_padding_ms": 0,
        "silence_duration_ms": 0,
        "threshold": 0,
        "type": "type"
      }
    },
    "output": {
      "format": {
        "rate": 24000,
        "type": "audio/pcm"
      },
      "speed": 0,
      "voice": "ash"
    }
  },
  "expires_at": 0,
  "include": [
    "item.input_audio_transcription.logprobs"
  ],
  "instructions": "instructions",
  "max_output_tokens": "inf",
  "model": "model",
  "object": "object",
  "output_modalities": [
    "text"
  ],
  "tool_choice": "tool_choice",
  "tools": [
    {
      "description": "description",
      "name": "name",
      "parameters": {},
      "type": "function"
    }
  ],
  "tracing": "auto",
  "turn_detection": {
    "prefix_padding_ms": 0,
    "silence_duration_ms": 0,
    "threshold": 0,
    "type": "type"
  }
}

示例

## 设置 OPENAI_API_KEY，并按接口替换呼叫 ID、会话参数和请求数据。
curl -X POST https://api.openai.com/v1/realtime/sessions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-realtime",
    "modalities": ["audio", "text"],
    "instructions": "你是一名友好的助手。"
  }'

响应示例

{
  "id": "sess_001",
  "object": "realtime.session",
  "model": "gpt-realtime-2025-08-25",
  "modalities": ["audio", "text"],
  "instructions": "你是一名友好的助手。",
  "voice": "alloy",
  "input_audio_format": "pcm16",
  "output_audio_format": "pcm16",
  "input_audio_transcription": {
      "model": "whisper-1"
  },
  "turn_detection": null,
  "tools": [],
  "tool_choice": "none",
  "temperature": 0.7,
  "max_response_output_tokens": 200,
  "speed": 1.1,
  "tracing": "auto",
  "client_secret": {
    "value": "ek_abc123", 
    "expires_at": 1234567890
  }
}

资源类型

会话创建响应

• SessionCreateResponse object { id, audio, expires_at, 10 more }

Realtime 会话配置对象。

• id: optional string

会话唯一标识，类似 sess_1234567890abcdef。

• audio: optional object { input, output }

会话的输入和输出音频配置。

• input: optional object { format, noise_reduction, transcription, turn_detection }

• format: optional RealtimeAudioFormats

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

• 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 { type } or null

输入音频降噪配置。

• type: optional NoiseReductionType

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

• "near_field"

• "far_field"

• transcription: optional object { keywords, language, languages, 2 more }

输入音频转录配置。

• keywords: optional array of string

已配置的、用于引导输入音频转录的词语或短语。

• language: optional string or null

输入音频的语言。

• languages: optional array of string

为转录配置的输入音频可能使用的语言，采用 ISO-639-1 格式。

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。

• 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。

• "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

为输入音频转录配置的提示词（如有）。

• turn_detection: optional object { prefix_padding_ms, silence_duration_ms, threshold, type } or null

轮次检测配置。

• prefix_padding_ms: optional integer

• silence_duration_ms: optional integer

• threshold: optional number

• type: optional string

话轮检测类型，目前仅支持 server_vad。

• output: optional object { format, speed, voice }

• format: optional RealtimeAudioFormats

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

• speed: optional number

• voice: optional string or "alloy" or "ash" or "ballad" or 7 more

• string

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

• "alloy"

• "ash"

• "ballad"

• "coral"

• "echo"

• "sage"

• "shimmer"

• "verse"

• "marin"

• "cedar"

• expires_at: optional integer

会话过期的 Unix 时间戳，单位为秒。

format: unixtime

• 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

此会话使用的 Realtime 模型。

• object: optional string

对象类型，固定为 realtime.session。

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

模型可用于响应的模态集合。如需禁用音频， 设为 ["text"]。

• "text"

• "audio"

• tool_choice: optional string

模型选择工具的方式，可选 auto、none、required，或 指定一个函数。

• tools: optional array of RealtimeFunctionTool

模型可用的工具（函数）。

• description: optional string

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

• name: optional string

函数名称。

• parameters: optional unknown

以 JSON Schema 描述的函数参数。

• type: optional "function"

工具类型，即 function。

• "function"

• tracing: optional "auto" or TracingConfiguration { group_id, metadata, workflow_name }

追踪配置选项。设为 null 可禁用追踪。一旦 为会话启用追踪，就不能修改配置。

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

• "auto"

会话的默认追踪模式。

• "auto"

• TracingConfiguration object { group_id, metadata, workflow_name }

追踪的细粒度配置。

• group_id: optional string

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

• metadata: optional unknown

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

• workflow_name: optional string

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

• turn_detection: optional object { prefix_padding_ms, silence_duration_ms, threshold, type } or null

话轮检测配置，可设为 null 关闭。服务端 VAD 表示模型根据 音量检测语音的开始与结束，并在用户说话结束时响应。

• prefix_padding_ms: optional integer

在 VAD 检测到语音之前一并保留的音频时长，单位为 毫秒，默认为 300 毫秒。

• silence_duration_ms: optional integer

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

• threshold: optional number

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

• type: optional string

话轮检测类型，目前仅支持 server_vad。

转录会话资源

创建转录会话

post /realtime/transcription_sessions

创建供客户端应用使用的临时 API 令牌，用于 Realtime API 的实时转录。 可使用与客户端事件 transcription_session.update 相同的会话参数。

响应包含会话对象和 client_secret 字段，其中包含 可用于浏览器客户端身份验证的临时 API 令牌， 用于访问 Realtime API。

返回创建的 Realtime 转录会话对象及临时密钥。

请求体参数

内容类型：application/json

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

转录结果中需要包含的项目，目前可用项目如下。 item.input_audio_transcription.logprobs

• "item.input_audio_transcription.logprobs"

• input_audio_format: optional "pcm16" or "g711_ulaw" or "g711_alaw" (default: "pcm16")

输入音频格式，可选 pcm16、g711_ulaw 或 g711_alaw。 使用 pcm16 时，输入必须是 24 kHz 采样率的 16 位 PCM 音频， 采用单声道和小端字节序。

• "pcm16"

• "g711_ulaw"

• "g711_alaw"

• input_audio_noise_reduction: optional object { type }

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

• type: optional NoiseReductionType

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

• "near_field"

• "far_field"

• input_audio_transcription: optional AudioTranscription

输入音频转录配置。客户端可设置语言和提示词，为转录服务提供额外引导。

• 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 object { prefix_padding_ms, silence_duration_ms, threshold, type }

话轮检测配置，设为 null 可关闭。服务端 VAD 根据音量检测语音开始和结束，并在用户说话结束时响应。

• prefix_padding_ms: optional integer

在 VAD 检测到语音之前一并保留的音频时长，单位为 毫秒，默认为 300 毫秒。

• silence_duration_ms: optional integer

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

• threshold: optional number

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

• type: optional "server_vad"

话轮检测类型，转录会话目前仅支持 server_vad。

• "server_vad"

返回值

• client_secret: object { expires_at, value }

API 返回的临时密钥，仅在通过服务端 REST API 创建会话时提供。

• expires_at: integer

令牌过期的时间戳。目前所有令牌均在 一分钟后过期。

format: unixtime

• value: string

供客户端环境验证连接身份的临时密钥， 用于 Realtime API。客户端应使用该临时密钥。 标准 API 令牌仅供服务端使用。

• input_audio_format: optional string

输入音频格式，可选 pcm16、g711_ulaw 或 g711_alaw。

• input_audio_transcription: optional object { keywords, language, languages, 2 more }

转录模型配置。

• keywords: optional array of string

已配置的、用于引导输入音频转录的词语或短语。

• language: optional string or null

输入音频的语言。

• languages: optional array of string

为转录配置的输入音频可能使用的语言，采用 ISO-639-1 格式。

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。

• 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。

• "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

为输入音频转录配置的提示词（如有）。

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

模型可用于响应的模态集合。如需禁用音频， 设为 ["text"]。

• "text"

• "audio"

• turn_detection: optional object { prefix_padding_ms, silence_duration_ms, threshold, type }

话轮检测配置，可设为 null 关闭。服务端 VAD 表示模型根据 音量检测语音的开始与结束，并在用户说话结束时响应。

• prefix_padding_ms: optional integer

在 VAD 检测到语音之前一并保留的音频时长，单位为 毫秒，默认为 300 毫秒。

• silence_duration_ms: optional integer

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

• threshold: optional number

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

• type: optional string

话轮检测类型，目前仅支持 server_vad。

示例

## 设置 OPENAI_API_KEY，并按接口替换呼叫 ID、会话参数和请求数据。
curl https://api.openai.com/v1/realtime/transcription_sessions \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{}'

200 响应示例

{
  "client_secret": {
    "expires_at": 0,
    "value": "value"
  },
  "input_audio_format": "input_audio_format",
  "input_audio_transcription": {
    "keywords": [
      "string"
    ],
    "language": "language",
    "languages": [
      "string"
    ],
    "model": "gpt-transcribe",
    "prompt": "prompt"
  },
  "modalities": [
    "text"
  ],
  "turn_detection": {
    "prefix_padding_ms": 0,
    "silence_duration_ms": 0,
    "threshold": 0,
    "type": "type"
  }
}

示例

## 设置 OPENAI_API_KEY，并按接口替换呼叫 ID、会话参数和请求数据。
curl -X POST https://api.openai.com/v1/realtime/transcription_sessions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

响应示例

{
  "id": "sess_BBwZc7cFV3XizEyKGDCGL",
  "object": "realtime.transcription_session",
  "modalities": ["audio", "text"],
  "turn_detection": {
    "type": "server_vad",
    "threshold": 0.5,
    "prefix_padding_ms": 300,
    "silence_duration_ms": 200
  },
  "input_audio_format": "pcm16",
  "input_audio_transcription": {
    "model": "gpt-4o-transcribe",
    "language": null,
    "prompt": ""
  },
  "client_secret": {
    "value": "ek_abc123",
    "expires_at": 1742188264
  }
}

资源类型

转录会话创建响应

• TranscriptionSessionCreateResponse object { client_secret, input_audio_format, input_audio_transcription, 2 more }

新的 Realtime 转录会话配置。

通过 REST API 在服务端创建会话时，会话对象 还包含临时密钥，其默认 TTL 为 10 分钟。通过 WebSocket API 更新会话时，不提供此属性。

• client_secret: object { expires_at, value }

API 返回的临时密钥，仅在通过服务端 REST API 创建会话时提供。

• expires_at: integer

令牌过期的时间戳。目前所有令牌均在 一分钟后过期。

format: unixtime

• value: string

供客户端环境验证连接身份的临时密钥， 用于 Realtime API。客户端应使用该临时密钥。 标准 API 令牌仅供服务端使用。

• input_audio_format: optional string

输入音频格式，可选 pcm16、g711_ulaw 或 g711_alaw。

• input_audio_transcription: optional object { keywords, language, languages, 2 more }

转录模型配置。

• keywords: optional array of string

已配置的、用于引导输入音频转录的词语或短语。

• language: optional string or null

输入音频的语言。

• languages: optional array of string

为转录配置的输入音频可能使用的语言，采用 ISO-639-1 格式。

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。

• 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。

• "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

为输入音频转录配置的提示词（如有）。

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

模型可用于响应的模态集合。如需禁用音频， 设为 ["text"]。

• "text"

• "audio"

• turn_detection: optional object { prefix_padding_ms, silence_duration_ms, threshold, type }

话轮检测配置，可设为 null 关闭。服务端 VAD 表示模型根据 音量检测语音的开始与结束，并在用户说话结束时响应。

• prefix_padding_ms: optional integer

在 VAD 检测到语音之前一并保留的音频时长，单位为 毫秒，默认为 300 毫秒。

• silence_duration_ms: optional integer

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

• threshold: optional number

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

• type: optional string

话轮检测类型，目前仅支持 server_vad。

Translations 翻译资源

连接

打开 Realtime 翻译会话。WebSocket URL 必须包含 model 查询参数。

使用下方 URL 打开 WebSocket 连接，在握手时提供路径参数、查询参数和认证信息。连接后，以 JSON 消息发送客户端事件、接收服务端事件，结束后关闭连接。

WebSocket：wss://api.openai.com/v1/realtime/translations

认证

使用 Bearer 认证，通过 Authorization 请求头提供凭据。

连接参数

• model：查询参数，字符串，必填。

事件

翻译客户端事件

翻译服务端事件

Client Secrets 客户端密钥资源

创建翻译客户端密钥

post /realtime/translations/client_secrets

创建 Realtime 翻译客户端密钥及关联的翻译会话配置。

客户端密钥是短期令牌，可传递给客户端应用， 例如 Web 前端或移动客户端，用于访问 Realtime Translation API，无需暴露主 API 密钥。每个客户端密钥均可自定义 有效期（TTL）。

返回创建的客户端密钥和实际生效的翻译会话对象。 客户端密钥是类似 ek_1234 的字符串。

请求体参数

内容类型：application/json

• session: RealtimeTranslationSessionCreateRequest

Realtime 翻译会话配置。翻译会话持续以流式方式接收源 音频，并输出翻译后的音频和增量文本。

• model: string

此会话使用的 Realtime 翻译模型。

• audio: optional object { input, output }

翻译输入与输出音频的配置。

• input: optional object { noise_reduction, transcription }

• noise_reduction: optional object { type, strength } or null

可选的输入降噪配置，设为 null 可禁用。

• type: NoiseReductionType

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

• "near_field"

• "far_field"

• strength: optional number (default: 1)

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

minimum: 0, maximum: 1

• transcription: optional object { model } or null

可选的源语言转录配置。配置后，服务器输出 session.input_transcript.delta 事件。翻译本身仍然直接基于 输入音频流。

• model: string

用于生成源语言转录文本增量的转录模型。

• output: optional object { language }

• language: optional string

翻译后音频与文本增量的目标语言。

• expires_after: optional object { anchor, seconds }

客户端密钥过期配置。过期时间表示此时间之后 无法再用该密钥创建会话。已经启动的会话本身 可以继续运行。在密钥过期之前，可使用同一个密钥创建多个会话， 直至密钥过期。

• anchor: optional "created_at" (default: "created_at")

客户端密钥过期时间的基准点。将 seconds 加到密钥的 created_at 时间上即可得到过期时间戳。目前仅支持 created_at。

• "created_at"

• seconds: optional integer (default: 600)

从基准点到过期时间的秒数，可选 10–7200 秒（2 小时），省略时默认为 600 秒（10 分钟）。

format: int64, minimum: 10, maximum: 7200

返回值

• RealtimeTranslationClientSecretCreateResponse object { expires_at, session, value }

创建 Realtime 翻译会话及客户端密钥的响应。

• expires_at: integer

客户端密钥过期的 Unix 时间戳，单位为秒。

format: unixtime

• session: RealtimeTranslationSession

Realtime 翻译会话。会话会持续将输入 音频翻译成配置的输出语言。

• id: string

会话唯一标识，类似 sess_1234567890abcdef。

• audio: object { input, output }

翻译输入与输出音频的配置。

• input: optional object { noise_reduction, transcription }

• noise_reduction: optional object { type, strength } or null

可选的输入降噪配置。

• type: NoiseReductionType

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

• "near_field"

• "far_field"

• strength: optional number (default: 1)

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

minimum: 0, maximum: 1

• transcription: optional object { model } or null

可选的源语言转录配置。配置后，服务器输出 session.input_transcript.delta 事件。翻译本身仍然直接基于 输入音频流。

• model: string

用于生成源语言转录文本增量的转录模型。

• output: optional object { language }

• language: optional string

翻译后音频与文本增量的目标语言。

• expires_at: integer

会话过期的 Unix 时间戳，单位为秒。

format: unixtime

• model: string

此会话使用的 Realtime 翻译模型。此字段在 创建会话时设置，无法通过 session.update 修改。

• type: "translation"

会话类型，Realtime 翻译会话固定为 translation。

• "translation"

• value: string

生成的客户端密钥值。

示例

## 设置 OPENAI_API_KEY，并按接口替换呼叫 ID、会话参数和请求数据。
curl https://api.openai.com/v1/realtime/translations/client_secrets \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
          "session": {
            "model": "model"
          }
        }'

200 响应示例

{
  "expires_at": 0,
  "session": {
    "id": "id",
    "audio": {
      "input": {
        "noise_reduction": {
          "type": "near_field",
          "strength": 0
        },
        "transcription": {
          "model": "model"
        }
      },
      "output": {
        "language": "language"
      }
    },
    "expires_at": 0,
    "model": "model",
    "type": "translation"
  },
  "value": "value"
}

示例

## 设置 OPENAI_API_KEY，并按接口替换呼叫 ID、会话参数和请求数据。
curl -X POST https://api.openai.com/v1/realtime/translations/client_secrets \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expires_after": {
      "anchor": "created_at",
      "seconds": 600
    },
    "session": {
      "model": "gpt-realtime-translate",
      "audio": {
        "input": {
          "transcription": {
            "model": "gpt-realtime-whisper"
          },
          "noise_reduction": null
        },
        "output": {
          "language": "es"
        }
      }
    }
  }'

响应示例

{
  "value": "ek_68af296e8e408191a1120ab6383263c2",
  "expires_at": 1756310470,
  "session": {
    "id": "sess_C9CiUVUzUzYIssh3ELY1d",
    "type": "translation",
    "expires_at": 1756310470,
    "model": "gpt-realtime-translate",
    "audio": {
      "input": {
        "transcription": {
          "model": "gpt-realtime-whisper"
        },
        "noise_reduction": null
      },
      "output": {
        "language": "es"
      }
    }
  }
}