TRAE-AI编程
OpenAI Realtime 客户端密钥接口参考
译注：原文请求说明、字段枚举与响应示例列出的音色范围不完全一致，此项保留待核。客户端密钥过期限制的是创建会话的时间，已启动会话不因此立即结束。
Client Secrets 客户端密钥资源
创建客户端密钥
post /realtime/client_secrets
创建 Realtime 客户端密钥，并关联会话配置。
客户端密钥是短期令牌，可传递给客户端应用， 例如网页前端或移动客户端；它允许访问 Realtime API， 同时不泄露主 API 密钥。可以为每个客户端密钥配置自定义 TTL。
也可以将会话配置选项附加到客户端密钥上， 使用该密钥创建的会话会应用这些选项，但客户端连接也可以 覆盖它们。
返回创建的客户端密钥与实际生效的会话对象。客户端密钥是类似 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、会话配置或 SDP；临时密钥仅供客户端使用。
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、会话配置或 SDP；临时密钥仅供客户端使用。
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。
更多建议：