OpenAI Live 分叉 WebSocket

分叉 WebSocket

根据已保存的对话状态启动新的 Live 会话，在新的 WebSocket 连接上收发音频和控制事件。

WebSocket：/v1/live/sessions/{session_id}/fork

连接

wss://api.openai.com/v1/live/sessions/{session_id}/fork

在后端使用 OpenAI API 密钥，通过 Authorization: Bearer $OPENAI_API_KEY 请求头认证。密钥须保存在服务器上。

session_id（必填路径参数）：要分叉的已保存源会话的 ID。分叉会话会获得新的会话 ID。

无查询参数。连接后，发送包含会话配置覆盖对象的 session.start；空对象会继承已保存配置。不要提供新模型。等待 session.started 后，再发送音频或其他命令。

输入

连接后须发送一次。省略的设置会继承，包括 store。可以覆盖 Responses 委派配置、存储设置及新 WebSocket 的音频格式。前端客户端权限仅适用于 WebRTC 分叉。

首条消息：session.start

{
  "type": "session.start",
  "session": {}
}

参见下文“客户端事件”。

输出

服务端确认新会话已就绪。后续旁路连接及会话控制须使用新的会话 ID。

分叉就绪：session.started 摘录

{
  "type": "session.started",
  "event_id": "event_started_1",
  "session": {
    "id": "live_fork_123",
    "expires_at": 1788307200,
    "status": "active",
    "model": "gpt-live-1"
  }
}

参见下文“服务端事件”。

了解如何保存会话并分叉其对话。

客户端事件

session.start

连接已保存会话的分叉 WebSocket 后，启动 Live 会话。发送空的 session 对象可使用已保存配置。

模式定义

模式名称：LiveForkSessionStartEvent

• session: ForkSessionConfig

连接分叉 WebSocket 后，对已保存会话设置的覆盖项。空对象继承已保存配置；不要提供新模型。audio.format 仅作用于新的 WebSocket 连接，client 覆盖项仅支持 WebRTC 分叉。

• audio: optional object { format }

WebSocket 分叉的音频格式。WebRTC 分叉通过协商确定音频格式，须省略此字段。

• format: optional AudioFormat

Live WebSocket 连接收发音频的编码与采样率。WebRTC 和 SIP 单独协商媒体格式。

• AudioPCM object { rate, type }

Live WebSocket 连接的原始单声道、16 位小端序 PCM 音频。

• rate: 16000 or 24000

音频采样率，单位为 Hz。Live WebSocket 的 PCM 音频支持 16000 或 24000 Hz。

minimum: 16000, maximum: 24000

• 16000

• 24000

• type: "audio/pcm" (default: "audio/pcm")

音频编码，固定为 audio/pcm。

• "audio/pcm"

• AudioPCMU object { rate, type }

Live WebSocket 连接的原始单声道 G.711 μ-law 音频。

• rate: integer

音频采样率，单位为 Hz。G.711 音频使用 8000 Hz。

minimum: 8000, maximum: 8000

• type: "audio/pcmu" (default: "audio/pcmu")

音频编码，固定为 audio/pcmu。

• "audio/pcmu"

• AudioPCMA object { rate, type }

Live WebSocket 连接的原始单声道 G.711 A-law 音频。

• rate: integer

音频采样率，单位为 Hz。G.711 音频使用 8000 Hz。

minimum: 8000, maximum: 8000

• type: "audio/pcma" (default: "audio/pcma")

音频编码，固定为 audio/pcma。

• "audio/pcma"

• client: optional ClientConfig

WebRTC 分叉的前端数据通道权限。省略的权限继承已保存值；WebSocket 分叉不支持此项。

• data_channel: DataChannelConfig

WebRTC 前端数据通道的客户端与服务端事件权限。

• allowed_client_events: optional "all" or array of string

前端数据通道可发送的客户端事件类型。使用 'all' 允许所有客户端事件，空数组表示全部禁止。省略时保留原有的全部允许行为。

• "all"

• "all"

• array of string

maxItems: 256

• allowed_server_events: optional "all" or array of ServerEventSelector

可发送到前端数据通道的服务端事件。使用 'all' 允许所有服务端事件，空数组表示全部禁止。省略时保留原有的全部允许行为。Responses 事件通过包含 type 'response.event' 和 response_event 选择器的对象指定。

• "all"

• "all"

• array of ServerEventSelector

maxItems: 256

• type: string

外层 Live 服务端事件类型。对于 Responses 事件，使用 'response.event'。

minLength: 1, maxLength: 256

• response_event: optional string

内嵌的 Responses 事件类型。type 为 'response.event' 时必填；其他事件类型禁止使用此字段。

minLength: 1, maxLength: 256

• delegation: optional object { type, acknowledgement_delay_ms, responses }

已保存会话的 Responses 后端覆盖项。仅在已保存会话使用 Responses 委派时支持；不能更改委派类型。

• type: "responses" (default: "responses")

委派任务的处理方。由 Responses API 处理任务时固定为 responses。

• "responses"

• acknowledgement_delay_ms: optional integer

从委派任务发出到请求自动语音确认的等待时长，单位为毫秒。模型仍可能在等待结束前发言。向会话追加任何说明（commentary）或思考（thinking）都会取消所有待处理的确认，包括其他委派任务的确认。Decisions 会话默认为 400，其他会话默认为 0，即立即请求。更新会话时省略此项会保留当前值；更新仅作用于后续委派。

minimum: 0, maximum: 800

• responses: optional ResponsesDelegationUpdateConfig

要更新的 Responses 后端设置。省略的设置保持原值。

• instructions: optional string or null

交给被委派的 Responses 模型的指令，与 Live 指令分开设置。参阅后端提示词。

• max_output_tokens: optional integer or null

每次委派响应的最大输出词元数。

minimum: 16

• model: optional string

后续委派请求使用的 Responses 后端模型。省略时保留当前后端模型。

• parallel_tool_calls: optional boolean or null

被委派的 Responses 模型能否在单次响应中请求多个工具调用。

• reasoning: optional object { effort, summary } or null

传给每次委派 Responses 请求的推理配置。

• effort: optional "none" or "minimal" or "low" or 3 more or null

被委派的 Responses 模型使用的推理强度。支持的值取决于后端模型。

• "none"

• "minimal"

• "low"

• "medium"

• "high"

• "xhigh"

• summary: optional "concise" or "detailed" or "auto" or null

向被委派的 Responses 模型请求的推理摘要类型，须模型支持。

• "concise"

• "detailed"

• "auto"

• service_tier: optional "auto" or "default" or "fast_tier_temp_pilot" or 3 more or null

委派 Responses 请求使用的服务层级。

• "auto"

• "default"

• "fast_tier_temp_pilot"

• "flex"

• "priority"

• "ultrafast"

• text: optional object { verbosity } or null

传给每次委派 Responses 请求的文本生成配置。

• verbosity: optional "low" or "medium" or "high" or null

Responses 后端生成文本的详细程度，此项不配置 Live 模型的口头表达方式。

• "low"

• "medium"

• "high"

• tool_choice: optional "auto" or "none" or "required" or Function { name, type } or Mcp { server_label, type, name } or 11 more

控制 Responses 后端在处理 Live 模型委派的任务时使用哪个工具。

• LiveToolChoiceEnum = "auto" or "none" or "required"

• "auto"

• "none"

• "required"

• Function object { name, type }

• name: string

要调用的函数工具名称。

• type: "function" (default: "function")

要调用的工具，固定为 function。

• "function"

• Mcp object { server_label, type, name }

• server_label: string

要调用的 MCP 服务器标签。

• type: "mcp" (default: "mcp")

要调用的工具，固定为 mcp。

• "mcp"

• name: optional string or null

要调用的 MCP 工具名称。省略时，服务器可选择默认工具。

• FileSearch object { type }

• type: "file_search" (default: "file_search")

要调用的工具，固定为 file_search。

• "file_search"

• WebSearch object { type }

• type: "web_search" (default: "web_search")

要调用的工具，固定为 web_search。

• "web_search"

• WebSearchPreview object { type }

• type: "web_search_preview" (default: "web_search_preview")

要调用的工具，固定为 web_search_preview。

• "web_search_preview"

• ImageGeneration object { type }

• type: "image_generation" (default: "image_generation")

要调用的工具，固定为 image_generation。

• "image_generation"

• Computer object { type }

• type: "computer" (default: "computer")

要调用的工具，固定为 computer。

• "computer"

• CodeInterpreter object { type }

• type: "code_interpreter" (default: "code_interpreter")

要调用的工具，固定为 code_interpreter。

• "code_interpreter"

• ProgrammaticToolCalling object { type }

• type: "programmatic_tool_calling" (default: "programmatic_tool_calling")

要调用的工具，固定为 programmatic_tool_calling。

• "programmatic_tool_calling"

• Shell object { type }

需要调用工具时，强制模型调用 shell 工具。

• type: "shell" (default: "shell")

要调用的工具，固定为 shell。

• "shell"

• Custom object { name, type }

• name: string

要调用的自定义工具名称。

• type: "custom" (default: "custom")

要调用的工具，固定为 custom。

• "custom"

• ApplyPatch object { type }

执行工具调用时，强制模型调用 apply_patch 工具。

• type: "apply_patch" (default: "apply_patch")

要调用的工具，固定为 apply_patch。

• "apply_patch"

• LiveAllowedToolsChoiceParam object { tools, type, mode }

• tools: array of Function { name, type } or Mcp { server_label, type, name } or FileSearch { type } or 9 more

被委派的 Responses 模型可以调用的工具。

minItems: 1, maxItems: 128

• Function object { name, type }

• name: string

要调用的函数工具名称。

• type: "function" (default: "function")

要调用的工具，固定为 function。

• "function"

• Mcp object { server_label, type, name }

• server_label: string

要调用的 MCP 服务器标签。

• type: "mcp" (default: "mcp")

要调用的工具，固定为 mcp。

• "mcp"

• name: optional string or null

要调用的 MCP 工具名称。省略时，服务器可选择默认工具。

• FileSearch object { type }

• type: "file_search" (default: "file_search")

要调用的工具，固定为 file_search。

• "file_search"

• WebSearch object { type }

• type: "web_search" (default: "web_search")

要调用的工具，固定为 web_search。

• "web_search"

• WebSearchPreview object { type }

• type: "web_search_preview" (default: "web_search_preview")

要调用的工具，固定为 web_search_preview。

• "web_search_preview"

• ImageGeneration object { type }

• type: "image_generation" (default: "image_generation")

要调用的工具，固定为 image_generation。

• "image_generation"

• Computer object { type }

• type: "computer" (default: "computer")

要调用的工具，固定为 computer。

• "computer"

• CodeInterpreter object { type }

• type: "code_interpreter" (default: "code_interpreter")

要调用的工具，固定为 code_interpreter。

• "code_interpreter"

• ProgrammaticToolCalling object { type }

• type: "programmatic_tool_calling" (default: "programmatic_tool_calling")

要调用的工具，固定为 programmatic_tool_calling。

• "programmatic_tool_calling"

• Shell object { type }

需要调用工具时，强制模型调用 shell 工具。

• type: "shell" (default: "shell")

要调用的工具，固定为 shell。

• "shell"

• Custom object { name, type }

• name: string

要调用的自定义工具名称。

• type: "custom" (default: "custom")

要调用的工具，固定为 custom。

• "custom"

• ApplyPatch object { type }

执行工具调用时，强制模型调用 apply_patch 工具。

• type: "apply_patch" (default: "apply_patch")

要调用的工具，固定为 apply_patch。

• "apply_patch"

• type: "allowed_tools" (default: "allowed_tools")

工具选择类型，固定为 allowed_tools。

• "allowed_tools"

• mode: optional "none" or "auto" or "required" or null

从允许的工具集合中选择工具的方式。

• "none"

• "auto"

• "required"

• tools: optional array of FunctionTool or WebSearch { type } or FileSearch { type } or 10 more

Responses 后端处理 Live 模型委派的任务时可用的工具。

• FunctionTool object { name, type, description, 2 more }

Live 模型委派任务时，Responses 后端可用的函数工具。

• name: string

被委派的 Responses 模型调用此函数时使用的名称。

• type: "function" (default: "function")

工具类型，固定为 function。

• "function"

• description: optional string or null

函数的用途，以及被委派的 Responses 模型应在何时调用它。

• parameters: optional map[unknown] or null

描述函数可接受参数的 JSON Schema 对象。

• strict: optional boolean or null

被委派的 Responses 模型是否必须严格遵循函数的参数模式。

• WebSearch object { type }

Live 会话的 Responses 后端可用的网页搜索工具。

• type: "web_search" (default: "web_search")

工具类型，固定为 web_search。

• "web_search"

• FileSearch object { type }

• type: "file_search" (default: "file_search")

• "file_search"

• CodeInterpreter object { type }

• type: "code_interpreter" (default: "code_interpreter")

• "code_interpreter"

• Shell object { type, environment }

Responses shell 工具。可使用托管容器，或通过 response.item.create 返回本地 shell 执行结果。不支持域名密钥（domain secrets）。

• type: "shell" (default: "shell")

• "shell"

• environment: optional ContainerAuto { type, file_ids, memory_limit, 2 more } or ContainerReference { container_id, type } or Local { type, skills } or null

• ContainerAuto object { type, file_ids, memory_limit, 2 more }

• type: "container_auto" (default: "container_auto")

为此请求自动创建容器。

• "container_auto"

• file_ids: optional array of string or null

可选的已上传文件列表，这些文件将提供给代码使用。

maxItems: 50

• memory_limit: optional "1g" or "4g" or "16g" or "64g" or null

容器的内存上限。

• "1g"

• "4g"

• "16g"

• "64g"

• network_policy: optional Disabled { type } or Allowlist { allowed_domains, type } or null

容器的网络访问策略。

• Disabled object { type }

• type: "disabled" (default: "disabled")

禁用出站网络访问，固定为 disabled。

• "disabled"

• Allowlist object { allowed_domains, type }

• allowed_domains: array of string

type 为 allowlist 时允许访问的域名列表。

minItems: 1

• type: "allowlist" (default: "allowlist")

仅允许对指定域名发起出站网络访问，固定为 allowlist。

• "allowlist"

• skills: optional array of SkillReference { skill_id, type, version } or Inline { description, name, source, type } or null

可选的技能列表，通过 ID 或内联数据引用技能。

maxItems: 200

• SkillReference object { skill_id, type, version }

• skill_id: string

引用的技能 ID。

minLength: 1, maxLength: 64

• type: "skill_reference" (default: "skill_reference")

引用通过 /v1/skills 接口创建的技能。

• "skill_reference"

• version: optional string or null

可选的技能版本。使用正整数或 'latest'，省略时使用默认版本。

• Inline object { description, name, source, type }

• description: string

技能描述。

• name: string

技能名称。

• source: object { data, media_type, type }

内联技能载荷。

• data: string

采用 Base64 编码的技能 ZIP 包。

minLength: 1, maxLength: 70254592

• media_type: "application/zip" (default: "application/zip")

内联技能载荷的媒体类型，必须为 application/zip。

• "application/zip"

• type: "base64" (default: "base64")

内联技能来源的类型，必须为 base64。

• "base64"

• type: "inline" (default: "inline")

为此请求定义内联技能。

• "inline"

• ContainerReference object { container_id, type }

• container_id: string

引用的容器 ID。

• type: "container_reference" (default: "container_reference")

引用通过 /v1/containers 接口创建的容器。

• "container_reference"

• Local object { type, skills }

• type: "local" (default: "local")

使用本地计算机环境。

• "local"

• skills: optional array of object { description, name, path } or null

可选的技能列表。

maxItems: 200

• description: string

技能描述。

• name: string

技能名称。

• path: string

包含该技能的目录路径。

• ImageGeneration object { type }

• type: "image_generation" (default: "image_generation")

• "image_generation"

• Mcp object { type }

• type: "mcp" (default: "mcp")

• "mcp"

• Custom object { type }

• type: "custom" (default: "custom")

• "custom"

• Namespace object { type }

• type: "namespace" (default: "namespace")

• "namespace"

• ToolSearch object { type }

• type: "tool_search" (default: "tool_search")

• "tool_search"

• ProgrammaticToolCalling object { type }

• type: "programmatic_tool_calling" (default: "programmatic_tool_calling")

• "programmatic_tool_calling"

• Computer object { type }

• type: "computer" (default: "computer")

• "computer"

• ApplyPatch object { type }

• type: "apply_patch" (default: "apply_patch")

• "apply_patch"

• store: optional boolean

是否保存分叉后的会话。省略时继承已保存会话的设置。

• type: "session.start" (default: "session.start")

Live 客户端事件类型，固定为 session.start。

• "session.start"

• event_id: optional string or null

可选的客户端标识，用于将此命令与服务端事件的 client_event_id 或 error.client_event_id 关联。

maxLength: 512

示例

{
  "type": "session.start",
  "session": {}
}

session.update

更新活动 Live 会话的委派配置或转录触发器。服务端通过 session.updated 确认接受的更改。

模式定义

模式名称：LiveSessionUpdateParam

• session: SessionUpdateConfig

对委派和触发器进行局部更新，省略的设置保持原值。不能更改委派类型。模型、前端指令、音频及启动输入不可更改。

• delegation: optional ClientDelegation or Responses { type, acknowledgement_delay_ms, responses } or Decisions { type, acknowledgement_delay_ms, decisions } or null

要更新的委派设置。委派类型须与当前会话一致；省略的设置保持原值。

• ClientDelegation object { type, acknowledgement_delay_ms }

将任务委派给你的应用。Live 会话发出委派事件，由你的后端处理。

• type: "client" (default: "client")

委派任务的处理方。由你的应用处理时固定为 client。

• "client"

• acknowledgement_delay_ms: optional integer

从委派任务发出到请求自动语音确认的等待时长，单位为毫秒。模型仍可能在等待结束前发言。向会话追加任何说明（commentary）或思考（thinking）都会取消所有待处理的确认，包括其他委派任务的确认。Decisions 会话默认为 400，其他会话默认为 0，即立即请求。更新会话时省略此项会保留当前值；更新仅作用于后续委派。

minimum: 0, maximum: 800

• Responses object { type, acknowledgement_delay_ms, responses }

更新现有 Live 会话的 Responses 后端，同时保留任务委派的处理方。

• type: "responses" (default: "responses")

委派任务的处理方。由 Responses API 处理任务时固定为 responses。

• "responses"

• acknowledgement_delay_ms: optional integer

从委派任务发出到请求自动语音确认的等待时长，单位为毫秒。模型仍可能在等待结束前发言。向会话追加任何说明（commentary）或思考（thinking）都会取消所有待处理的确认，包括其他委派任务的确认。Decisions 会话默认为 400，其他会话默认为 0，即立即请求。更新会话时省略此项会保留当前值；更新仅作用于后续委派。

minimum: 0, maximum: 800

• responses: optional ResponsesDelegationUpdateConfig

要更新的 Responses 后端设置。省略的设置保持原值。

• instructions: optional string or null

交给被委派的 Responses 模型的指令，与 Live 指令分开设置。参阅后端提示词。

• max_output_tokens: optional integer or null

每次委派响应的最大输出词元数。

minimum: 16

• model: optional string

后续委派请求使用的 Responses 后端模型。省略时保留当前后端模型。

• parallel_tool_calls: optional boolean or null

被委派的 Responses 模型能否在单次响应中请求多个工具调用。

• reasoning: optional object { effort, summary } or null

传给每次委派 Responses 请求的推理配置。

• effort: optional "none" or "minimal" or "low" or 3 more or null

被委派的 Responses 模型使用的推理强度。支持的值取决于后端模型。

• "none"

• "minimal"

• "low"

• "medium"

• "high"

• "xhigh"

• summary: optional "concise" or "detailed" or "auto" or null

向被委派的 Responses 模型请求的推理摘要类型，须模型支持。

• "concise"

• "detailed"

• "auto"

• service_tier: optional "auto" or "default" or "fast_tier_temp_pilot" or 3 more or null

委派 Responses 请求使用的服务层级。

• "auto"

• "default"

• "fast_tier_temp_pilot"

• "flex"

• "priority"

• "ultrafast"

• text: optional object { verbosity } or null

传给每次委派 Responses 请求的文本生成配置。

• verbosity: optional "low" or "medium" or "high" or null

Responses 后端生成文本的详细程度，此项不配置 Live 模型的口头表达方式。

• "low"

• "medium"

• "high"

• tool_choice: optional "auto" or "none" or "required" or Function { name, type } or Mcp { server_label, type, name } or 11 more

控制 Responses 后端在处理 Live 模型委派的任务时使用哪个工具。

• LiveToolChoiceEnum = "auto" or "none" or "required"

• "auto"

• "none"

• "required"

• Function object { name, type }

• name: string

要调用的函数工具名称。

• type: "function" (default: "function")

要调用的工具，固定为 function。

• "function"

• Mcp object { server_label, type, name }

• server_label: string

要调用的 MCP 服务器标签。

• type: "mcp" (default: "mcp")

要调用的工具，固定为 mcp。

• "mcp"

• name: optional string or null

要调用的 MCP 工具名称。省略时，服务器可选择默认工具。

• FileSearch object { type }

• type: "file_search" (default: "file_search")

要调用的工具，固定为 file_search。

• "file_search"

• WebSearch object { type }

• type: "web_search" (default: "web_search")

要调用的工具，固定为 web_search。

• "web_search"

• WebSearchPreview object { type }

• type: "web_search_preview" (default: "web_search_preview")

要调用的工具，固定为 web_search_preview。

• "web_search_preview"

• ImageGeneration object { type }

• type: "image_generation" (default: "image_generation")

要调用的工具，固定为 image_generation。

• "image_generation"

• Computer object { type }

• type: "computer" (default: "computer")

要调用的工具，固定为 computer。

• "computer"

• CodeInterpreter object { type }

• type: "code_interpreter" (default: "code_interpreter")

要调用的工具，固定为 code_interpreter。

• "code_interpreter"

• ProgrammaticToolCalling object { type }

• type: "programmatic_tool_calling" (default: "programmatic_tool_calling")

要调用的工具，固定为 programmatic_tool_calling。

• "programmatic_tool_calling"

• Shell object { type }

需要调用工具时，强制模型调用 shell 工具。

• type: "shell" (default: "shell")

要调用的工具，固定为 shell。

• "shell"

• Custom object { name, type }

• name: string

要调用的自定义工具名称。

• type: "custom" (default: "custom")

要调用的工具，固定为 custom。

• "custom"

• ApplyPatch object { type }

执行工具调用时，强制模型调用 apply_patch 工具。

• type: "apply_patch" (default: "apply_patch")

要调用的工具，固定为 apply_patch。

• "apply_patch"

• LiveAllowedToolsChoiceParam object { tools, type, mode }

• tools: array of Function { name, type } or Mcp { server_label, type, name } or FileSearch { type } or 9 more

被委派的 Responses 模型可以调用的工具。

minItems: 1, maxItems: 128

• Function object { name, type }

• name: string

要调用的函数工具名称。

• type: "function" (default: "function")

要调用的工具，固定为 function。

• "function"

• Mcp object { server_label, type, name }

• server_label: string

要调用的 MCP 服务器标签。

• type: "mcp" (default: "mcp")

要调用的工具，固定为 mcp。

• "mcp"

• name: optional string or null

要调用的 MCP 工具名称。省略时，服务器可选择默认工具。

• FileSearch object { type }

• type: "file_search" (default: "file_search")

要调用的工具，固定为 file_search。

• "file_search"

• WebSearch object { type }

• type: "web_search" (default: "web_search")

要调用的工具，固定为 web_search。

• "web_search"

• WebSearchPreview object { type }

• type: "web_search_preview" (default: "web_search_preview")

要调用的工具，固定为 web_search_preview。

• "web_search_preview"

• ImageGeneration object { type }

• type: "image_generation" (default: "image_generation")

要调用的工具，固定为 image_generation。

• "image_generation"

• Computer object { type }

• type: "computer" (default: "computer")

要调用的工具，固定为 computer。

• "computer"

• CodeInterpreter object { type }

• type: "code_interpreter" (default: "code_interpreter")

要调用的工具，固定为 code_interpreter。

• "code_interpreter"

• ProgrammaticToolCalling object { type }

• type: "programmatic_tool_calling" (default: "programmatic_tool_calling")

要调用的工具，固定为 programmatic_tool_calling。

• "programmatic_tool_calling"

• Shell object { type }

需要调用工具时，强制模型调用 shell 工具。

• type: "shell" (default: "shell")

要调用的工具，固定为 shell。

• "shell"

• Custom object { name, type }

• name: string

要调用的自定义工具名称。

• type: "custom" (default: "custom")

要调用的工具，固定为 custom。

• "custom"

• ApplyPatch object { type }

执行工具调用时，强制模型调用 apply_patch 工具。

• type: "apply_patch" (default: "apply_patch")

要调用的工具，固定为 apply_patch。

• "apply_patch"

• type: "allowed_tools" (default: "allowed_tools")

工具选择类型，固定为 allowed_tools。

• "allowed_tools"

• mode: optional "none" or "auto" or "required" or null

从允许的工具集合中选择工具的方式。

• "none"

• "auto"

• "required"

• tools: optional array of FunctionTool or WebSearch { type } or FileSearch { type } or 10 more

Responses 后端处理 Live 模型委派的任务时可用的工具。

• FunctionTool object { name, type, description, 2 more }

Live 模型委派任务时，Responses 后端可用的函数工具。

• name: string

被委派的 Responses 模型调用此函数时使用的名称。

• type: "function" (default: "function")

工具类型，固定为 function。

• "function"

• description: optional string or null

函数的用途，以及被委派的 Responses 模型应在何时调用它。

• parameters: optional map[unknown] or null

描述函数可接受参数的 JSON Schema 对象。

• strict: optional boolean or null

被委派的 Responses 模型是否必须严格遵循函数的参数模式。

• WebSearch object { type }

Live 会话的 Responses 后端可用的网页搜索工具。

• type: "web_search" (default: "web_search")

工具类型，固定为 web_search。

• "web_search"

• FileSearch object { type }

• type: "file_search" (default: "file_search")

• "file_search"

• CodeInterpreter object { type }

• type: "code_interpreter" (default: "code_interpreter")

• "code_interpreter"

• Shell object { type, environment }

Responses shell 工具。可使用托管容器，或通过 response.item.create 返回本地 shell 执行结果。不支持域名密钥（domain secrets）。

• type: "shell" (default: "shell")

• "shell"

• environment: optional ContainerAuto { type, file_ids, memory_limit, 2 more } or ContainerReference { container_id, type } or Local { type, skills } or null

• ContainerAuto object { type, file_ids, memory_limit, 2 more }

• type: "container_auto" (default: "container_auto")

为此请求自动创建容器。

• "container_auto"

• file_ids: optional array of string or null

可选的已上传文件列表，这些文件将提供给代码使用。

maxItems: 50

• memory_limit: optional "1g" or "4g" or "16g" or "64g" or null

容器的内存上限。

• "1g"

• "4g"

• "16g"

• "64g"

• network_policy: optional Disabled { type } or Allowlist { allowed_domains, type } or null

容器的网络访问策略。

• Disabled object { type }

• type: "disabled" (default: "disabled")

禁用出站网络访问，固定为 disabled。

• "disabled"

• Allowlist object { allowed_domains, type }

• allowed_domains: array of string

type 为 allowlist 时允许访问的域名列表。

minItems: 1

• type: "allowlist" (default: "allowlist")

仅允许对指定域名发起出站网络访问，固定为 allowlist。

• "allowlist"

• skills: optional array of SkillReference { skill_id, type, version } or Inline { description, name, source, type } or null

可选的技能列表，通过 ID 或内联数据引用技能。

maxItems: 200

• SkillReference object { skill_id, type, version }

• skill_id: string

引用的技能 ID。

minLength: 1, maxLength: 64

• type: "skill_reference" (default: "skill_reference")

引用通过 /v1/skills 接口创建的技能。

• "skill_reference"

• version: optional string or null

可选的技能版本。使用正整数或 'latest'，省略时使用默认版本。

• Inline object { description, name, source, type }

• description: string

技能描述。

• name: string

技能名称。

• source: object { data, media_type, type }

内联技能载荷。

• data: string

采用 Base64 编码的技能 ZIP 包。

minLength: 1, maxLength: 70254592

• media_type: "application/zip" (default: "application/zip")

内联技能载荷的媒体类型，必须为 application/zip。

• "application/zip"

• type: "base64" (default: "base64")

内联技能来源的类型，必须为 base64。

• "base64"

• type: "inline" (default: "inline")

为此请求定义内联技能。

• "inline"

• ContainerReference object { container_id, type }

• container_id: string

引用的容器 ID。

• type: "container_reference" (default: "container_reference")

引用通过 /v1/containers 接口创建的容器。

• "container_reference"

• Local object { type, skills }

• type: "local" (default: "local")

使用本地计算机环境。

• "local"

• skills: optional array of object { description, name, path } or null

可选的技能列表。

maxItems: 200

• description: string

技能描述。

• name: string

技能名称。

• path: string

包含该技能的目录路径。

• ImageGeneration object { type }

• type: "image_generation" (default: "image_generation")

• "image_generation"

• Mcp object { type }

• type: "mcp" (default: "mcp")

• "mcp"

• Custom object { type }

• type: "custom" (default: "custom")

• "custom"

• Namespace object { type }

• type: "namespace" (default: "namespace")

• "namespace"

• ToolSearch object { type }

• type: "tool_search" (default: "tool_search")

• "tool_search"

• ProgrammaticToolCalling object { type }

• type: "programmatic_tool_calling" (default: "programmatic_tool_calling")

• "programmatic_tool_calling"

• Computer object { type }

• type: "computer" (default: "computer")

• "computer"

• ApplyPatch object { type }

• type: "apply_patch" (default: "apply_patch")

• "apply_patch"

• Decisions object { type, acknowledgement_delay_ms, decisions }

• type: "decisions" (default: "decisions")

• "decisions"

• acknowledgement_delay_ms: optional integer

从委派任务发出到请求自动语音确认的等待时长，单位为毫秒。模型仍可能在等待结束前发言。向会话追加任何说明（commentary）或思考（thinking）都会取消所有待处理的确认，包括其他委派任务的确认。Decisions 会话默认为 400，其他会话默认为 0，即立即请求。更新会话时省略此项会保留当前值；更新仅作用于后续委派。

minimum: 0, maximum: 800

• decisions: optional DecisionsDelegationUpdateConfig

• model: optional string

minLength: 1

• questions: optional array of DecisionQuestion

按顺序一起求值的原生 Decision API 问题。

minItems: 1, maxItems: 64

• Choice object { choices, instructions, type, name }

• choices: array of DecisionChoiceOption

minItems: 2, maxItems: 255

• value: string or boolean

• string

• boolean

• description: optional string

• instructions: string or array of DecisionInputText or InputImage { image_url, type, detail } or InputJSON { data, type }

• string

• array of DecisionInputText or InputImage { image_url, type, detail } or InputJSON { data, type }

minItems: 1

• DecisionInputText object { text, type }

• text: string

输入模型的文本。

maxLength: 10485760

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

• "input_text"

• InputImage object { image_url, type, detail }

• image_url: string

采用 Base64 编码的图像 data URL，或可公开访问的 HTTP(S) 图像 URL。

pattern: ^(data:|https?://), maxLength: 20971520

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

• "input_image"

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

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

• "low"

• "high"

• "auto"

• "original"

• InputJSON object { data, type }

• data: map[unknown] or array of map[unknown]

• LiveDecisionJSONObject = map[unknown]

• array of map[unknown]

• type: "input_json" (default: "input_json")

• "input_json"

• type: "choice" (default: "choice")

• "choice"

• name: optional string

• Predicate object { instructions, type, name }

• instructions: string or array of DecisionInputText or InputImage { image_url, type, detail } or InputJSON { data, type }

• string

• array of DecisionInputText or InputImage { image_url, type, detail } or InputJSON { data, type }

minItems: 1

• DecisionInputText object { text, type }

• InputImage object { image_url, type, detail }

• image_url: string

采用 Base64 编码的图像 data URL，或可公开访问的 HTTP(S) 图像 URL。

pattern: ^(data:|https?://), maxLength: 20971520

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

• "input_image"

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

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

• "low"

• "high"

• "auto"

• "original"

• InputJSON object { data, type }

• data: map[unknown] or array of map[unknown]

• LiveDecisionJSONObject = map[unknown]

• array of map[unknown]

• type: "input_json" (default: "input_json")

• "input_json"

• type: "predicate" (default: "predicate")

• "predicate"

• name: optional string

• Score object { instructions, levels, type, name }

• instructions: string or array of DecisionInputText or InputImage { image_url, type, detail } or InputJSON { data, type }

• string

• array of DecisionInputText or InputImage { image_url, type, detail } or InputJSON { data, type }

minItems: 1

• DecisionInputText object { text, type }

• InputImage object { image_url, type, detail }

• image_url: string

采用 Base64 编码的图像 data URL，或可公开访问的 HTTP(S) 图像 URL。

pattern: ^(data:|https?://), maxLength: 20971520

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

• "input_image"

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

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

• "low"

• "high"

• "auto"

• "original"

• InputJSON object { data, type }

• data: map[unknown] or array of map[unknown]

• LiveDecisionJSONObject = map[unknown]

• array of map[unknown]

• type: "input_json" (default: "input_json")

• "input_json"

• levels: array of object { label, description }

minItems: 2, maxItems: 10

• label: string

• description: optional string

• type: "score" (default: "score")

• "score"

• name: optional string

• triggers: optional array of DecisionTrigger

每种转录事件类型最多配置一个 Decisions 触发器。触发器独立于任务委派运行。更新时省略 triggers 会保留当前配置，发送列表会替换配置，发送空列表会禁用触发器。

maxItems: 2

• decisions: object { questions }

使用当前转录文本与会话共享的 Decision 条目进行求值的问题。

• questions: array of DecisionQuestion

按顺序一起求值的原生 Decision API 问题。

minItems: 1, maxItems: 64

• Choice object { choices, instructions, type, name }

• Predicate object { instructions, type, name }

• Score object { instructions, levels, type, name }

• event_type: "session.input_transcript.delta" or "session.output_transcript.delta"

• "session.input_transcript.delta"

• "session.output_transcript.delta"

• type: "decisions" (default: "decisions")

• "decisions"

• type: "session.update" (default: "session.update")

Live 客户端事件类型，固定为 session.update。

• "session.update"

• event_id: optional string or null

可选的客户端标识，用于将此命令与服务端事件的 client_event_id 或 error.client_event_id 关联。

maxLength: 512

示例

{
  "type": "session.update",
  "event_id": "evt_update_001",
  "session": {
    "delegation": {
      "type": "responses",
      "responses": {
        "instructions": "查询餐厅是否有位；确认预订前须先询问。",
        "max_output_tokens": 1024
      }
    }
  }
}

session.input_audio.append

通过主 WebSocket 向 Live 会话发送音频。WebRTC 和 SIP 会话通过各自的媒体传输发送音频。

模式定义

模式名称：LiveInputAudioAppendEvent

• audio: string

采用启动时选定格式的 Base64 编码原始音频，不含 WAV 等容器头。仅用于主 WebSocket，媒体传输通过音轨发送。追加音频不会收到确认。旁路反射的服务端事件复用此事件类型和 audio 键，不含时间戳或 event_id；其音频始终为 24 kHz 单声道 PCM16LE。

minLength: 1

• type: "session.input_audio.append" (default: "session.input_audio.append")

Live 客户端事件类型，固定为 session.input_audio.append。

• "session.input_audio.append"

• event_id: optional string or null

可选的客户端标识，用于将此命令与服务端事件的 client_event_id 或 error.client_event_id 关联。

maxLength: 512

示例

{
  "type": "session.input_audio.append",
  "audio": "AACAAIAAAIAAAP9/AIAAgA=="
}

session.input_audio.mute

静音 Live 模型的音频输入而不关闭会话。服务端通过 session.input_audio.muted 确认。

模式定义

模式名称：LiveInputAudioMuteParam

• type: "session.input_audio.mute" (default: "session.input_audio.mute")

Live 客户端事件类型，固定为 session.input_audio.mute。

• "session.input_audio.mute"

• event_id: optional string or null

可选的客户端标识，用于将此命令与服务端事件的 client_event_id 或 error.client_event_id 关联。

maxLength: 512

示例

{
  "type": "session.input_audio.mute",
  "event_id": "evt_mute_001"
}

session.input_audio.unmute

静音后恢复 Live 模型的音频输入。服务端通过 session.input_audio.unmuted 确认。如果仍有音频片段在播放，推理将暂停直至播放结束。

模式定义

模式名称：LiveInputAudioUnmuteParam

• type: "session.input_audio.unmute" (default: "session.input_audio.unmute")

Live 客户端事件类型，固定为 session.input_audio.unmute。

• "session.input_audio.unmute"

• event_id: optional string or null

可选的客户端标识，用于将此命令与服务端事件的 client_event_id 或 error.client_event_id 关联。

maxLength: 512

示例

{
  "type": "session.input_audio.unmute",
  "event_id": "evt_unmute_001"
}

session.output_audio.fixture.play

通过会话输出播放一段完整的预置音频片段。经主 WebSocket 或服务端旁路发送此事件。无论会话音频格式如何，音频须为原始单声道、24 kHz、16 位小端序 PCM，最长 30 秒。在打断模型语音及静音输入前，会验证整个载荷。同时只能有一个片段处于活动状态。fixture.playing 确认接受，fixture.played 表示服务端混音器已排空。这些通知不代表传输媒体的精确边界。播放期间到达的输入会被丢弃，不会重放。

模式定义

模式名称：LiveOutputAudioFixturePlayParam

• audio: string

Base64 编码的原始单声道 PCM16 音频，小端序，24 kHz；不要包含 WAV 等容器头。

minLength: 1, maxLength: 1920000

• type: "session.output_audio.fixture.play" (default: "session.output_audio.fixture.play")

• "session.output_audio.fixture.play"

• event_id: optional string or null

可选的客户端标识，用于将此命令与服务端事件的 client_event_id 或 error.client_event_id 关联。

maxLength: 512

示例

{
  "type": "session.output_audio.fixture.play",
  "event_id": "evt_play_001",
  "audio": "AAAAAA=="
}

session.instructions.append

在 Live 对话运行期间追加开发者指令，可选择关联已有的客户端委派。播放音频片段期间会拒绝此操作。这些指令在压缩后仍保留于对话历史中，并包含在后续后端委派中。对于外部音频，须描述已经传达的内容，避免助手重复。

模式定义

模式名称：LiveInstructionsAppendParam

• content: string

要追加的指令文本，最多 500 个词元。须为纯字符串，而非内容部分数组。

• delegation_id: string or null

必填，可为 null。设为 null 表示一般会话上下文；也可使用 session.delegation.created 中已有客户端委派的 ID。Responses 委派不接受非 null ID。

minLength: 1

• type: "session.instructions.append" (default: "session.instructions.append")

Live 客户端事件类型，固定为 session.instructions.append。

• "session.instructions.append"

• event_id: optional string or null

可选的客户端标识，用于将此命令与服务端事件的 client_event_id 或 error.client_event_id 关联。

maxLength: 512

示例

{
  "type": "session.instructions.append",
  "event_id": "evt_instructions_001",
  "delegation_id": null,
  "content": "来电者偏好室外座位。"
}

session.thinking.append

向 Live 模型提供不直接发声的推理或进度上下文，可选择关联已有客户端委派。播放音频片段期间会拒绝此操作。

模式定义

模式名称：LiveThinkingAppendParam

• content: string

不直接发声的推理或进度上下文，最多 500 个词元。此项不会直接请求发言，但可影响后续语音，不能作为保密边界。

• delegation_id: string or null

必填，可为 null。设为 null 表示一般会话上下文；也可使用 session.delegation.created 中已有客户端委派的 ID。Responses 委派不接受非 null ID。

minLength: 1

• type: "session.thinking.append" (default: "session.thinking.append")

Live 客户端事件类型，固定为 session.thinking.append。

• "session.thinking.append"

• event_id: optional string or null

可选的客户端标识，用于将此命令与服务端事件的 client_event_id 或 error.client_event_id 关联。

maxLength: 512

示例

{
  "type": "session.thinking.append",
  "event_id": "evt_thinking_001",
  "delegation_id": "del_abc123",
  "content": "正在查询晚上7点的两人座位。"
}

session.commentary.append

提供 Live 模型可向用户传达的上下文，可选择关联已有客户端委派。播放音频片段期间会拒绝此操作。

模式定义

模式名称：LiveCommentaryAppendParam

• content: string

可供 Live 模型口头传达的上下文，最多 500 个词元。需要模型传达结果时使用此项；提供不发声的上下文时使用 session.thinking.append。

• delegation_id: string or null

必填，可为 null。设为 null 表示一般会话上下文；也可使用 session.delegation.created 中已有客户端委派的 ID。Responses 委派不接受非 null ID。

minLength: 1

• type: "session.commentary.append" (default: "session.commentary.append")

Live 客户端事件类型，固定为 session.commentary.append。

• "session.commentary.append"

• event_id: optional string or null

可选的客户端标识，用于将此命令与服务端事件的 client_event_id 或 error.client_event_id 关联。

maxLength: 512

示例

{
  "type": "session.commentary.append",
  "event_id": "evt_commentary_001",
  "delegation_id": "del_abc123",
  "content": "晚上7点有一张室外两人桌，请询问是否预订。"
}

decision.create

使用当前对话和 Decision 输入，对已配置问题进行求值。会话存续期间重复使用 event_id 会被拒绝。

模式定义

模式名称：LiveDecisionCreateParam

• event_id: string

minLength: 1, maxLength: 256

• type: "decision.create" (default: "decision.create")

• "decision.create"

示例

{
  "type": "decision.create",
  "event_id": "decision_1"
}

decision.item.create

追加供后续决策使用的输入条目，不启动求值，也不改变 Live 语音上下文。

模式定义

模式名称：LiveDecisionItemCreateParam

• item: Message { content, role, id, type } or Message { content, role, id, type } or Message { content, role, id, type } or 5 more

• Message object { content, role, id, type }

• content: string or array of InputText { text, type } or InputImage { image_url, type, detail } or InputJSON { data, type }

输入模型的文本。

• string

输入模型的文本。

maxLength: 10485760

• array of InputText { text, type } or InputImage { image_url, type, detail } or InputJSON { data, type }

• InputText object { text, type }

• text: string

输入模型的文本。

maxLength: 10485760

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

• "input_text"

• InputImage object { image_url, type, detail }

• image_url: string

采用 Base64 编码的图像 data URL，或可公开访问的 HTTP(S) 图像 URL。

pattern: ^(data:|https?://), maxLength: 20971520

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

• "input_image"

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

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

• "low"

• "high"

• "auto"

• "original"

• InputJSON object { data, type }

• data: map[unknown] or array of map[unknown]

• LiveDecisionJSONObject = map[unknown]

• array of map[unknown]

• type: "input_json" (default: "input_json")

• "input_json"

• role: "user" (default: "user")

消息角色，固定为 user。

• "user"

• id: optional string or null

此消息条目的唯一 ID。

• type: optional "message" (default: "message")

• "message"

• Message object { content, role, id, type }

• content: string or array of DecisionInputText

输入模型的文本。

• string

输入模型的文本。

maxLength: 10485760

• array of DecisionInputText

• text: string

输入模型的文本。

maxLength: 10485760

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

• "input_text"

• role: "developer" (default: "developer")

• "developer"

• id: optional string or null

此消息条目的唯一 ID。

• type: optional "message" (default: "message")

• "message"

• Message object { content, role, id, type }

• content: string or array of DecisionInputText

输入模型的文本。

• string

输入模型的文本。

maxLength: 10485760

• array of DecisionInputText

• text: string

输入模型的文本。

maxLength: 10485760

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

• role: "system" (default: "system")

• "system"

• id: optional string or null

此消息条目的唯一 ID。

• type: optional "message" (default: "message")

• "message"

• Message object { content, role, id, 2 more }

• content: string or array of OutputText { text, type } or Refusal { refusal, type }

输入模型的文本。

• string

输入模型的文本。

maxLength: 10485760

• array of OutputText { text, type } or Refusal { refusal, type }

• OutputText object { text, type }

• text: string

文本内容。

maxLength: 10485760

• type: "output_text" (default: "output_text")

• "output_text"

• Refusal object { refusal, type }

• refusal: string

拒绝文本。

maxLength: 10485760

• type: "refusal" (default: "refusal")

• "refusal"

• role: "assistant" (default: "assistant")

• "assistant"

• id: optional string or null

此消息条目的唯一 ID。

• phase: optional "commentary" or "final_answer" or null

将 assistant 消息标记为中间说明（commentary）或最终答案（final_answer）。对于 gpt-5.3-codex 及后续此类模型，发送后续请求时须保留并重新发送所有助手消息的 phase，丢弃它可能降低表现。用户消息不使用此字段。

• "commentary"

• "final_answer"

• type: optional "message" (default: "message")

• "message"

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

• arguments: string

以 JSON 字符串表示的函数参数。

• call_id: string

模型生成的函数工具调用的唯一 ID。

minLength: 1, maxLength: 64

• name: string

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

• type: "function_call" (default: "function_call")

条目类型，固定为 function_call。

• "function_call"

• id: optional string or null

本地 Decision 条目 ID。

• namespace: optional string or null

要调用的函数所属的命名空间。

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

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

• "in_progress"

• "completed"

• "incomplete"

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

• call_id: string

模型生成的函数工具调用的唯一 ID。

minLength: 1, maxLength: 64

• output: string or array of DecisionInputText or InputImage { image_url, type, detail }

输入模型的文本。

• string

输入模型的文本。

maxLength: 10485760

• array of DecisionInputText or InputImage { image_url, type, detail }

• DecisionInputText object { text, type }

• text: string

输入模型的文本。

maxLength: 10485760

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

• InputImage object { image_url, type, detail }

• image_url: string

采用 Base64 编码的图像 data URL，或可公开访问的 HTTP(S) 图像 URL。

pattern: ^(data:|https?://), maxLength: 20971520

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

• "input_image"

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

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

• "low"

• "high"

• "auto"

• "original"

• type: "function_call_output" (default: "function_call_output")

类型，固定为 function_call_output。

• "function_call_output"

• id: optional string or null

本地 Decision 条目 ID。

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

• "in_progress"

• "completed"

• "incomplete"

• CustomToolCall object { call_id, input, name, 4 more }

• call_id: string

模型生成的函数工具调用的唯一 ID。

minLength: 1, maxLength: 64

• input: string

自定义工具调用的输入。

• name: string

要调用的自定义工具名称。

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

• type: "custom_tool_call" (default: "custom_tool_call")

条目类型，固定为 custom_tool_call。

• "custom_tool_call"

• id: optional string or null

本地 Decision 条目 ID。

• namespace: optional string or null

要调用的函数所属的命名空间。

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

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

• "in_progress"

• "completed"

• "incomplete"

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

• call_id: string

模型生成的函数工具调用的唯一 ID。

minLength: 1, maxLength: 64

• output: string or array of DecisionInputText or InputImage { image_url, type, detail }

输入模型的文本。

• string

输入模型的文本。

maxLength: 10485760

• array of DecisionInputText or InputImage { image_url, type, detail }

• DecisionInputText object { text, type }

• InputImage object { image_url, type, detail }

• image_url: string

采用 Base64 编码的图像 data URL，或可公开访问的 HTTP(S) 图像 URL。

pattern: ^(data:|https?://), maxLength: 20971520

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

• "input_image"

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

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

• "low"

• "high"

• "auto"

• "original"

• type: "custom_tool_call_output" (default: "custom_tool_call_output")

• "custom_tool_call_output"

• id: optional string or null

本地 Decision 条目 ID。

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

• "in_progress"

• "completed"

• "incomplete"

• type: "decision.item.create" (default: "decision.item.create")

• "decision.item.create"

• event_id: optional string or null

可选的客户端标识，用于将此命令与服务端事件的 client_event_id 或 error.client_event_id 关联。

maxLength: 512

示例

{
  "type": "decision.item.create",
  "event_id": "browser_1",
  "item": {
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "维基百科已打开。"
      }
    ]
  }
}

decision.item.delete

从后续决策中删除输入条目，不启动求值，也不改变 Live 语音上下文。

模式定义

模式名称：LiveDecisionItemDeleteParam

• item_id: string

minLength: 1

• type: "decision.item.delete" (default: "decision.item.delete")

• "decision.item.delete"

• event_id: optional string or null

可选的客户端标识，用于将此命令与服务端事件的 client_event_id 或 error.client_event_id 关联。

maxLength: 512

示例

{
  "type": "decision.item.delete",
  "event_id": "remove_browser_1",
  "item_id": "msg_browser_1"
}

response.item.create

向 Live 会话的 Responses 后端添加输入条目。要求使用 Responses 委派；使用 response.create 请求响应。

模式定义

模式名称：LiveResponseItemCreateParam

• item: EasyInputMessage or Message { content, role, status, type } or ResponseOutputMessage or 30 more

要追加到 Responses 后端对话的输入条目，例如用户消息或函数工具结果。

• EasyInputMessage object { content, role, phase, type }

输入模型的消息，其角色表示指令遵循的 优先级。以 developer 或 system 角色给出的指令 优先于 user 角色给出的指令。 assistant 角色的消息被视为模型在此前 交互中生成的内容。

• content: string or ResponseInputMessageContentList

用于生成响应的文本、图像或音频输入。 也可以包含此前的助手响应。

• TextInput = string

输入模型的文本。

• ResponseInputMessageContentList = array of ResponseInputContent

输入模型的一个或多个条目的列表，可以包含不同 内容类型。

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

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

输入消息的角色，可选 user、assistant、system 或 developer.

• "user"

• "assistant"

• "system"

• "developer"

• phase: optional "commentary" or "final_answer" or null

将 assistant 消息标记为中间说明（commentary）或最终答案（final_answer）。 对于 gpt-5.3-codex 及后续此类模型，发送后续请求时，须保留并重新发送 所有助手消息的 phase；丢弃它可能降低表现。用户消息不使用此字段。

• "commentary"

• "final_answer"

• type: optional "message"

输入消息类型，固定为 message。

• "message"

• Message object { content, role, status, type }

输入模型的消息，其角色表示指令遵循的 优先级。以 developer 或 system 角色给出的指令 优先于 user 角色给出的指令。

• content: ResponseInputMessageContentList

输入模型的一个或多个条目的列表，可以包含不同 内容类型。

• role: "user" or "system" or "developer"

输入消息角色，可选 user、system 或 developer。

• "user"

• "system"

• "developer"

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

条目状态，可选 in_progress、completed 或 incomplete。通过 API 返回条目时填充。

• "in_progress"

• "completed"

• "incomplete"

• type: optional "message"

输入消息类型，固定为 message。

• "message"

• ResponseOutputMessage object { id, content, role, 3 more }

模型输出的消息。

• id: string

输出消息的唯一 ID。

• content: array of ResponseOutputText or ResponseOutputRefusal

输出消息的内容。

• ResponseOutputText object { annotations, logprobs, text, type }

模型输出的文本。

• annotations: array of FileCitation { file_id, filename, index, type } or URLCitation { end_index, start_index, title, 2 more } or ContainerFileCitation { container_id, end_index, file_id, 3 more } or FilePath { file_id, index, type }

文本输出的注解。

• FileCitation object { file_id, filename, index, type }

文件引用。

• file_id: string

文件 ID。

• filename: string

被引用文件的文件名。

• index: integer

在输出文本中插入文件引用的位置索引。

• type: "file_citation" (default: "file_citation")

类型，固定为 file_citation。

• "file_citation"

• URLCitation object { end_index, start_index, title, 2 more }

对生成模型响应所用网页资源的引用。

• end_index: integer

URL 引用在消息中最后一个字符的索引。

• start_index: integer

URL 引用在消息中第一个字符的索引。

• title: string

网络资源标题。

• type: "url_citation" (default: "url_citation")

URL 引用的类型，固定为 url_citation。

• "url_citation"

• url: string

网络资源 URL。

format: uri

• ContainerFileCitation object { container_id, end_index, file_id, 3 more }

对生成模型响应所用容器文件的引用。

• container_id: string

容器文件 ID。

• end_index: integer

消息中容器文件引用最后一个字符的索引。

• file_id: string

文件 ID。

• filename: string

被引用容器文件的文件名。

• start_index: integer

消息中容器文件引用第一个字符的索引。

• type: "container_file_citation" (default: "container_file_citation")

类型，固定为 container_file_citation。

• "container_file_citation"

• FilePath object { file_id, index, type }

文件路径。

• file_id: string

文件 ID。

• index: integer

文件在文件列表中的索引。

• type: "file_path"

类型，固定为 file_path。

• "file_path"

• logprobs: array of object { token, bytes, logprob, top_logprobs }

• token: string

• bytes: array of number

• logprob: number

• top_logprobs: array of object { token, bytes, logprob }

• token: string

• bytes: array of number

• logprob: number

• text: string

模型输出的文本内容。

• type: "output_text" (default: "output_text")

输出文本类型，固定为 output_text。

• "output_text"

• ResponseOutputRefusal object { refusal, type }

模型的拒绝响应。

• refusal: string

模型给出的拒绝原因。

• type: "refusal" (default: "refusal")

类型，固定为 refusal。

• "refusal"

• role: "assistant"

输出消息角色，固定为 assistant。

• "assistant"

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

输入消息状态，可选 in_progress、completed 或 incomplete。通过 API 返回输入条目时填充。

• "in_progress"

• "completed"

• "incomplete"

• type: "message"

类型，固定为 message。

• "message"

• phase: optional "commentary" or "final_answer" or null

将 assistant 消息标记为中间说明（commentary）或最终答案（final_answer）。 对于 gpt-5.3-codex 及后续此类模型，发送后续请求时，须保留并重新发送 所有助手消息的 phase；丢弃它可能降低表现。用户消息不使用此字段。

• "commentary"

• "final_answer"

• FileSearchCall object { id, queries, status, 2 more }

文件搜索工具调用的结果，更多信息参阅 文件搜索指南。

• id: string

文件搜索工具调用的唯一 ID。

• queries: array of string

搜索文件所用的查询。

• status: "in_progress" or "searching" or "completed" or 2 more

文件搜索工具调用状态，可选 in_progress、 searching、incomplete 或 failed，

• "in_progress"

• "searching"

• "completed"

• "incomplete"

• "failed"

• type: "file_search_call"

类型，固定为 file_search_call。

• "file_search_call"

• results: optional array of object { attributes, file_id, filename, 2 more } or null

文件搜索工具调用的结果。

• attributes: optional map[string or number or boolean] or null

可附加到对象的元数据，最多包含 16 组键值对，可 以结构化方式存储对象的额外信息， 格式存储附加信息，并通过 API 或控制台查询对象。键为 最长 64 个字符的字符串；值可以是最长 512 个字符的字符串、布尔值或数字。

• string

maxLength: 512

• number

• boolean

• file_id: optional string

文件的唯一 ID。

• filename: optional string

文件名。

• score: optional number

文件相关性分数，范围为 0–1。

format: float

• text: optional string

从文件中检索出的文本。

• ComputerCall object { id, call_id, pending_safety_checks, 4 more }

计算机使用工具的调用，更多信息参阅 计算机使用指南。

• id: string

计算机工具调用的唯一 ID。

• call_id: string

通过输出回应此工具调用时使用的标识。

• pending_safety_checks: array of object { id, code, message }

此计算机工具调用待处理的安全检查。

• id: string

待处理安全检查的 ID。

• code: optional string or null

待处理安全检查的类型。

• message: optional string or null

待处理安全检查的详情。

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

条目状态，可选 in_progress、completed 或 incomplete。通过 API 返回条目时填充。

• "in_progress"

• "completed"

• "incomplete"

• type: "computer_call" (default: "computer_call")

类型，固定为 computer_call。

• "computer_call"

• action: optional ComputerAction

单击操作。

• Click object { button, type, x, 2 more }

单击操作。

• button: "left" or "right" or "wheel" or 2 more

单击时按下的鼠标按钮，可选 left、right、wheel、back 或 forward。

• "left"

• "right"

• "wheel"

• "back"

• "forward"

• type: "click" (default: "click")

指定事件类型。单击操作固定为 click。

• "click"

• x: integer

单击位置的 x 坐标。

• y: integer

单击位置的 y 坐标。

• keys: optional array of string or null

单击时保持按下的按键。

• DoubleClick object { keys, type, x, y }

双击操作。

• keys: array of string or null

双击时保持按下的按键。

• type: "double_click" (default: "double_click")

指定事件类型。双击操作固定为 double_click。

• "double_click"

• x: integer

双击位置的 x 坐标。

• y: integer

双击位置的 y 坐标。

• Drag object { path, type, keys }

拖动操作。

• path: array of object { x, y }

表示拖动路径的坐标数组。坐标以对象数组形式提供，例如

          // 拖动路径按顺序列出各点的 x、y 坐标。
          [
            { x: 100, y: 200 },
            { x: 200, y: 300 }
          ]

• x: integer

x 坐标。

• y: integer

y 坐标。

• type: "drag" (default: "drag")

指定事件类型。拖动操作固定为 drag。

• "drag"

• keys: optional array of string or null

拖动鼠标时保持按下的按键。

• Keypress object { keys, type }

模型希望执行的一组按键操作。

• keys: array of string

模型请求按下的按键组合，以字符串数组表示，每个字符串代表一个按键。

• type: "keypress" (default: "keypress")

指定事件类型。按键操作固定为 keypress。

• "keypress"

• Move object { type, x, y, keys }

鼠标移动操作。

• type: "move" (default: "move")

指定事件类型。移动操作固定为 move。

• "move"

• x: integer

移动目标的 x 坐标。

• y: integer

移动目标的 y 坐标。

• keys: optional array of string or null

移动鼠标时保持按下的按键。

• Screenshot object { type }

截屏操作。

• type: "screenshot" (default: "screenshot")

指定事件类型。截屏操作固定为 screenshot。

• "screenshot"

• Scroll object { scroll_x, scroll_y, type, 3 more }

滚动操作。

• scroll_x: integer

水平滚动距离。

• scroll_y: integer

垂直滚动距离。

• type: "scroll" (default: "scroll")

指定事件类型。滚动操作固定为 scroll。

• "scroll"

• x: integer

滚动位置的 x 坐标。

• y: integer

滚动位置的 y 坐标。

• keys: optional array of string or null

滚动时保持按下的按键。

• Type object { text, type }

输入文本的操作。

• text: string

要输入的文本。

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

指定事件类型。输入操作固定为 type。

• "type"

• Wait object { type }

等待操作。

• type: "wait" (default: "wait")

指定事件类型。等待操作固定为 wait。

• "wait"

• actions: optional ComputerActionList

computer_use 的扁平化批量操作。每项操作包含 type 判别字段及对应操作专用字段。

• Click object { button, type, x, 2 more }

单击操作。

• DoubleClick object { keys, type, x, y }

双击操作。

• Drag object { path, type, keys }

拖动操作。

• Keypress object { keys, type }

模型希望执行的一组按键操作。

• Move object { type, x, y, keys }

鼠标移动操作。

• Screenshot object { type }

截屏操作。

• Scroll object { scroll_x, scroll_y, type, 3 more }

滚动操作。

• Type object { text, type }

输入文本的操作。

• Wait object { type }

等待操作。

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

计算机工具调用的输出。

• call_id: string

产生此输出的计算机工具调用的 ID。

minLength: 1, maxLength: 64

• output: ResponseComputerToolCallOutputScreenshot

供计算机使用工具使用的屏幕截图图像。

• type: "computer_screenshot" (default: "computer_screenshot")

指定事件类型。计算机屏幕截图的此属性 固定为 computer_screenshot。

• "computer_screenshot"

• file_id: optional string

包含截图的已上传文件的标识。

• image_url: optional string

截图图像的 URL。

format: uri

• type: "computer_call_output" (default: "computer_call_output")

类型，固定为 computer_call_output。

• "computer_call_output"

• id: optional string or null

计算机工具调用输出的 ID。

• acknowledged_safety_checks: optional array of object { id, code, message } or null

API 报告且开发者已确认的安全检查。

• id: string

待处理安全检查的 ID。

• code: optional string or null

待处理安全检查的类型。

• message: optional string or null

待处理安全检查的详情。

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

输入消息状态，可选 in_progress、completed 或 incomplete，通过 API 返回输入条目时填充。

• "in_progress"

• "completed"

• "incomplete"

• WebSearchCall object { id, status, type, action }

网页搜索工具调用的结果，更多信息参阅 网页搜索指南。

• id: string

网页搜索工具调用的唯一 ID。

• status: "in_progress" or "searching" or "completed" or 2 more

网页搜索工具调用的状态。

• "in_progress"

• "searching"

• "completed"

• "failed"

• "incomplete"

• type: "web_search_call"

类型，固定为 web_search_call。

• "web_search_call"

• action: optional Search { type, queries, query, sources } or OpenPage { type, url } or FindInPage { pattern, type, url }

描述此网页搜索调用所执行具体操作的对象。 包含模型如何使用网页的详情：search、open_page、find_in_page。

• Search object { type, queries, query, sources }

操作类型 "search"：执行网页搜索查询。

• type: "search"

操作类型。

• "search"

• queries: optional array of string

搜索查询列表。

• query: optional string

搜索查询。

• sources: optional array of object { type, url }

搜索所用的信息来源。

• type: "url"

来源类型，固定为 url。

• "url"

• url: string

来源 URL。

format: uri

• OpenPage object { type, url }

操作类型 "open_page"：打开搜索结果中的指定 URL。

• type: "open_page"

操作类型。

• "open_page"

• url: optional string or null

模型打开的 URL。

format: uri

• FindInPage object { pattern, type, url }

操作类型 "find_in_page"：在已加载页面中搜索模式。

• pattern: string

要在页面中搜索的模式或文本。

• type: "find_in_page"

操作类型。

• "find_in_page"

• url: optional string or null

用于搜索模式的页面 URL，如可用。

format: uri

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

运行函数的工具调用，更多信息参阅 函数调用指南。

• arguments: string

要传给函数的参数组成的 JSON 字符串。

• call_id: string

模型生成的函数工具调用的唯一 ID。

• name: string

要运行的函数名称。

• type: "function_call"

类型，固定为 function_call。

• "function_call"

• id: optional string

函数工具调用的唯一 ID。

• async: optional boolean

函数工具调用是否异步运行。

• caller: optional Direct { type } or Program { caller_id, type } or null

产生此工具调用的执行上下文。

• Direct object { type }

• type: "direct" (default: "direct")

• "direct"

• Program object { caller_id, type }

• caller_id: string

产生此工具调用的 program 条目的调用 ID。

• type: "program" (default: "program")

• "program"

• namespace: optional string

要运行的函数所属的命名空间。

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

条目状态，可选 in_progress、completed 或 incomplete。通过 API 返回条目时填充。

• "in_progress"

• "completed"

• "incomplete"

• FunctionCallOutput object { output, type, id, 5 more }

函数工具调用的输出。

• output: string or array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent

函数工具调用的文本、图像或文件输出。

• string

函数工具调用输出的 JSON 字符串。

maxLength: 10485760

• array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent

函数工具调用的内容输出数组，包含文本、图像或文件。

• ResponseInputTextContent object { text, type, prompt_cache_breakpoint }

输入模型的文本。

• text: string

输入模型的文本。

maxLength: 10485760

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

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

• "input_text"

• prompt_cache_breakpoint: optional object { mode, ttl } or null

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

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

断点模式，固定为 explicit。

• "explicit"

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

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

• "30m"

• "12h"

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

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

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

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

• "input_image"

• detail: optional ImageDetail or null

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

• file_id: optional string or null

要发送给模型的文件 ID。

• image_url: optional string or null

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

maxLength: 20971520, format: uri

• prompt_cache_breakpoint: optional object { mode, ttl } or null

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

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

断点模式，固定为 explicit。

• "explicit"

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

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

• "30m"

• "12h"

• ResponseInputFileContent 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 or null

要发送给模型的文件的 Base64 编码数据。

maxLength: 73400320

• file_id: optional string or null

要发送给模型的文件 ID。

• file_url: optional string or null

要发送给模型的文件 URL。

format: uri

• filename: optional string or null

要发送给模型的文件名。

• prompt_cache_breakpoint: optional object { mode, ttl } or null

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

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

断点模式，固定为 explicit。

• "explicit"

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

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

• "30m"

• "12h"

• type: "function_call_output" (default: "function_call_output")

类型，固定为 function_call_output。

• "function_call_output"

• id: optional string or null

函数工具调用输出的唯一 ID，通过 API 返回此条目时填充。

• call_id: optional string or null

模型生成的函数工具调用的唯一 ID。

minLength: 1, maxLength: 64

• caller: optional Direct { type } or Program { caller_id, type } or null

产生此工具调用的执行上下文。

• Direct object { type }

• type: "direct" (default: "direct")

调用方类型，固定为 direct。

• "direct"

• Program object { caller_id, type }

• caller_id: string

产生此工具调用的 program 条目的调用 ID。

minLength: 1, maxLength: 64

• type: "program" (default: "program")

调用方类型，固定为 program。

• "program"

• name: optional string or null

产生输出的工具名称。

minLength: 1, maxLength: 128

• namespace: optional string or null

产生输出的工具所属命名空间。

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

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

条目状态，可选 in_progress、completed 或 incomplete，通过 API 返回条目时填充。

• "in_progress"

• "completed"

• "incomplete"

• ToolSearchCall object { arguments, type, id, 3 more }

• arguments: unknown

传给工具搜索调用的参数。

• type: "tool_search_call" (default: "tool_search_call")

条目类型，固定为 tool_search_call。

• "tool_search_call"

• id: optional string or null

此工具搜索调用的唯一 ID。

• call_id: optional string or null

模型生成的工具搜索调用的唯一 ID。

minLength: 1, maxLength: 64

• execution: optional "server" or "client"

工具搜索由服务端还是客户端执行。

• "server"

• "client"

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

工具搜索调用的状态。

• "in_progress"

• "completed"

• "incomplete"

• ToolSearchOutput object { tools, type, id, 3 more }

• tools: array of Function { name, parameters, strict, 6 more } or FileSearch { type, vector_store_ids, filters, 2 more } or Computer { type } or 13 more

工具搜索输出返回的已加载工具定义。

• Function object { name, parameters, strict, 6 more }

定义模型可以选择调用的自有代码函数。参阅函数调用。

• name: string

要调用的函数名称。

• parameters: map[unknown] or null

描述函数参数的 JSON Schema 对象。

• strict: boolean or null

是否对此函数工具强制执行严格参数校验。

• type: "function" (default: "function")

函数工具类型，固定为 function。

• "function"

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

工具调用的上下文。

• "direct"

• "programmatic"

• async: optional boolean

• defer_loading: optional boolean

此函数是否延迟加载并通过工具搜索加载。

• description: optional string or null

函数描述，模型据此判断是否调用该函数。

• output_schema: optional map[unknown] or null

描述此函数字符串输出中编码的 JSON 值的 JSON Schema 对象。

• FileSearch object { type, vector_store_ids, filters, 2 more }

搜索已上传文件中相关内容的工具。参阅文件搜索工具。

• type: "file_search" (default: "file_search")

文件搜索工具类型，固定为 file_search。

• "file_search"

• vector_store_ids: array of string

要搜索的向量存储 ID 列表。

• filters: optional ComparisonFilter or CompoundFilter or null

要应用的筛选条件。

• ComparisonFilter object { key, type, value }

使用指定比较运算，将某个属性键与给定值比较的筛选条件。

• key: string

要与值比较的属性键。

• type: "eq" or "ne" or "gt" or 5 more (default: "eq")

指定比较运算符：eq、ne、gt、gte、lt、lte、in、nin。

• eq：等于
• ne：不等于
• gt：大于
• gte：大于或等于
• lt：小于
• lte：小于或等于
• in：属于
• nin：不属于

• "eq"

• "ne"

• "gt"

• "gte"

• "lt"

• "lte"

• "in"

• "nin"

• value: string or number or boolean or array of string or number

用于与属性键比较的值，支持字符串、数字或布尔类型。

• string

• number

• boolean

• array of string or number

• string

• number

• CompoundFilter object { filters, type }

使用 and 或 or 组合多个筛选条件。

• filters: array of ComparisonFilter or CompoundFilter

要组合的筛选条件数组，条目可以是 ComparisonFilter 或 CompoundFilter。

• ComparisonFilter object { key, type, value }

使用指定比较运算，将某个属性键与给定值比较的筛选条件。

• CompoundFilter object { filters, type }

使用 and 或 or 组合多个筛选条件。

• type: "and" or "or"

运算类型：and 或 or。

• "and"

• "or"

• max_num_results: optional integer

返回结果数量上限，须介于 1–50 之间，含边界。

• ranking_options: optional object { hybrid_search, ranker, score_threshold }

搜索结果的排序选项。

• hybrid_search: optional object { embedding_weight, text_weight }

启用混合搜索时，控制倒数排名融合如何平衡语义嵌入匹配与稀疏关键词匹配的权重。

• embedding_weight: number

嵌入在倒数排名融合中的权重。

• text_weight: number

文本在倒数排名融合中的权重。

• ranker: optional "auto" or "default-2024-11-15"

文件搜索所用的排序器。

• "auto"

• "default-2024-11-15"

• score_threshold: optional number

文件搜索的分数阈值，为 0–1 之间的数字。越接近 1，越倾向于只返回最相关的结果，但返回数量可能减少。

• Computer object { type }

控制虚拟计算机的工具。参阅计算机工具。

• type: "computer" (default: "computer")

计算机工具类型，固定为 computer。

• "computer"

• ComputerUsePreview object { display_height, display_width, environment, type }

控制虚拟计算机的工具。参阅计算机工具。

• display_height: integer

计算机显示区域的高度。

• display_width: integer

计算机显示区域的宽度。

• environment: "windows" or "mac" or "linux" or 2 more

要控制的计算机环境类型。

• "windows"

• "mac"

• "linux"

• "ubuntu"

• "browser"

• type: "computer_use_preview" (default: "computer_use_preview")

计算机使用工具类型，固定为 computer_use_preview。

• "computer_use_preview"

• WebSearch object { type, external_web_access, filters, 2 more }

在互联网上搜索与提示词相关的信息来源。参阅 网络搜索工具时。

• type: "web_search" or "web_search_2025_08_26" (default: "web_search")

网页搜索工具类型，可选 web_search 或 web_search_2025_08_26。

• "web_search"

• "web_search_2025_08_26"

• external_web_access: optional boolean (default: true)

是否允许网页搜索实时访问互联网。省略时默认为 true。设为 false 时，网页搜索工具以离线或仅缓存模式运行，不会抓取新的外部内容。

• filters: optional object { allowed_domains } or null

搜索的筛选条件。

• allowed_domains: optional array of string or null (default: [])

搜索允许的域名。未提供时允许所有域名。 也允许访问所提供域名的子域名。

示例：["pubmed.ncbi.nlm.nih.gov"]

• search_context_size: optional "low" or "medium" or "high" (default: "medium")

对搜索占用上下文窗口空间大小的总体指导，可选 low、medium 或 high，默认为 medium。

• "low"

• "medium"

• "high"

• user_location: optional object { city, country, region, 2 more } or null

用户的大致位置。省略或设为 null 时，默认为 美国。若要避免此默认值，可传入不包含位置字段的 {"type": "approximate"}。 若要本地化结果，须提供相应位置字段。

• city: optional string or null

用户所在城市的自由文本，例如 San Francisco。

• country: optional string or null

用户所在国家/地区的两字母 ISO 代码，例如 US。

• region: optional string or null

用户所在地区的自由文本，例如 California。

• timezone: optional string or null

用户所在的 IANA 时区，例如 America/Los_Angeles。

• type: optional "approximate" (default: "approximate")

位置估算类型，固定为 approximate。

• "approximate"

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

• CodeInterpreter object { container, type, allowed_callers }

运行 Python 代码以帮助生成提示词响应的工具。

• container: string or CodeInterpreterToolAuto { type, file_ids, memory_limit, network_policy }

代码解释器容器，可以是容器 ID，也可以是 指定代码可用的已上传文件 ID 的对象，同时可提供 可选的 memory_limit 设置。

• string

容器 ID。

• CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }

代码解释器容器配置，可以指定运行代码时所处理的文件 ID。

• type: "auto" (default: "auto")

固定为 auto。

• "auto"

• file_ids: optional array of string

可选的已上传文件列表，这些文件将提供给代码使用。

maxItems: 50

• memory_limit: optional "1g" or "4g" or "16g" or "64g" or null

代码解释器容器的内存上限。

• "1g"

• "4g"

• "16g"

• "64g"

• network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist

容器的网络访问策略。

• ContainerNetworkPolicyDisabled object { type }

• type: "disabled" (default: "disabled")

禁用出站网络访问，固定为 disabled。

• "disabled"

• ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }

• allowed_domains: array of string

type 为 allowlist 时允许访问的域名列表。

minItems: 1

• type: "allowlist" (default: "allowlist")

仅允许对指定域名发起出站网络访问，固定为 allowlist。

• "allowlist"

• domain_secrets: optional array of ContainerNetworkPolicyDomainSecret

可选的仅用于允许访问域名的域名级密钥。

minItems: 1

• domain: string

密钥关联的域名。

minLength: 1

• name: string

要为该域名注入的密钥名称。

minLength: 1

• value: string

要为该域名注入的密钥值。

minLength: 1, maxLength: 10485760

• type: "code_interpreter"

代码解释器工具类型，固定为 code_interpreter。

• "code_interpreter"

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

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• ProgrammaticToolCalling object { type }

• type: "programmatic_tool_calling" (default: "programmatic_tool_calling")

工具类型，固定为 programmatic_tool_calling。

• "programmatic_tool_calling"

• ImageGeneration object { type, action, background, 13 more }

使用 GPT 图像模型生成图像的工具。

• type: "image_generation"

图像生成工具类型，固定为 image_generation。

• "image_generation"

• action: optional "generate" or "edit" or "auto"

生成新图像还是编辑已有图像，默认为 auto。

• "generate"

• "edit"

• "auto"

• background: optional "transparent" or "opaque" or "auto" (default: "auto")

生成图像的背景，可选 transparent、opaque， 或 auto。gpt-image-2.5-sunburst 和 gpt-image-2.5-flare，包括 对应的 2026-09-08 快照，支持 opaque 和 transparent 背景。受支持的 GPT Image 模型可以使用透明 背景。对于 gpt-image-2 和 gpt-image-2-2026-04-21，此功能处于 预览阶段。使用 transparent 时，须将输出格式设为 png 或 webp。 默认为 auto。

• "transparent"

• "opaque"

• "auto"

• complexity: optional "low" or "medium" or "high"

用于规划图像的计算投入，与渲染质量分开设置。 覆盖外层响应用于图像生成的 reasoning.effort。 省略时，继承外层受支持的推理强度，或使用 图像模型配置的默认值。 对于 SVG 输出，此项控制参考图像，而不是 SVG 生成模型的 推理。

• "low"

• "medium"

• "high"

• frame_count: optional integer (default: 9)

GIF 帧数，要求 output_format 为 gif，默认为 9。

minimum: 2, maximum: 16

• frame_duration_ms: optional integer (default: 200)

每个 GIF 帧的时长，单位为毫秒，取整到 10 毫秒。 要求 output_format 为 gif，默认为 200。

minimum: 20, maximum: 2000

• input_fidelity: optional "high" or "low" or null

控制模型为匹配输入图像风格和特征（尤其是面部特征）投入的程度。gpt-image-1.5 支持 high 和 low，gpt-image-1-mini 仅支持 low。使用 gpt-image-2 时应省略此参数。支持该参数的模型默认为 low。

• "high"

• "low"

• input_image_mask: optional object { file_id, image_url }

可选的局部重绘蒙版，包含 image_url （可选字符串）和 file_id（可选字符串）。

• file_id: optional string

蒙版图像的文件 ID。

• image_url: optional string

采用 Base64 编码的蒙版图像。

• model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 9 more

用于图像生成的模型，可选 gpt-image-1-mini、 gpt-image-1.5, gpt-image-2, gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、 gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare、 gpt-image-2.5-flare-2026-09-08, gpt-image-2.6-sunburst, gpt-image-2.6-flare 或 chatgpt-image-latest。默认值： gpt-image-2.6-sunburst.

gpt-image-1 已于 2026 年 10 月 23 日停用，请使用 gpt-image-2.5-sunburst 或 gpt-image-2.5-flare。

• string

• "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 9 more

用于图像生成的模型，可选 gpt-image-1-mini、 gpt-image-1.5, gpt-image-2, gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、 gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare、 gpt-image-2.5-flare-2026-09-08, gpt-image-2.6-sunburst, gpt-image-2.6-flare 或 chatgpt-image-latest。默认值： gpt-image-2.6-sunburst.

gpt-image-1 已于 2026 年 10 月 23 日停用，请使用 gpt-image-2.5-sunburst 或 gpt-image-2.5-flare。

• "gpt-image-1"

• "gpt-image-1-mini"

• "gpt-image-2"

• "gpt-image-2-2026-04-21"

• "gpt-image-2.5-sunburst"

• "gpt-image-2.5-sunburst-2026-09-08"

• "gpt-image-2.5-flare"

• "gpt-image-2.5-flare-2026-09-08"

• "gpt-image-2.6-sunburst"

• "gpt-image-2.6-flare"

• "gpt-image-1.5"

• "chatgpt-image-latest"

• moderation: optional "auto" or "low" (default: "auto")

生成图像的审核级别，默认为 auto。

• "auto"

• "low"

• output_compression: optional integer (default: 100)

输出图像的压缩级别，默认为 100。

minimum: 0, maximum: 100

• output_format: optional "png" or "webp" or "jpeg" or 2 more (default: "png")

输出图像格式，可选 png、webp、jpeg、 gif 或 svg，默认为 png。GIF 和 SVG 输出要求模型 支持所选格式。GIF 输出不支持 部分图像流式传输，即 partial_images 大于 0， 也不支持 input_image_mask 或自定义 output_compression。 GIF 输出仍可以流式发送 Responses 生命周期事件。

• "png"

• "webp"

• "jpeg"

• "gif"

• "svg"

• partial_images: optional integer (default: 0)

流式模式中生成的部分图像数量，范围为 0（默认值）到 3。

minimum: 0, maximum: 3

• quality: optional "low" or "medium" or "high" or 3 more (default: "auto")

生成图像的质量。GPT 图像模型支持 low、 medium 和 high。gpt-image-2.5-sunburst 和 gpt-image-2.5-flare， 包括对应的 2026-09-08 快照，还支持 xhigh 和 max。 默认为 auto。

• "low"

• "medium"

• "high"

• "xhigh"

• "max"

• "auto"

• size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto" (default: "auto")

生成图像的尺寸。gpt-image-2、gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare 和 gpt-image-2.5-flare-2026-09-08 支持以 WIDTHxHEIGHT 字符串指定任意分辨率，例如 1536x864。宽和高均须能被 16 整除，宽高比须在 1:3 至 3:1 之间。高于 2560x1440 的分辨率属于实验功能，支持的最高分辨率为 3840x2160。尺寸还须符合模型当前的像素数与边长限制。GPT Image 模型支持标准尺寸 1024x1024、1536x1024 和 1024x1536；允许自动尺寸的模型支持 auto。

• string

• "1024x1024" or "1024x1536" or "1536x1024" or "auto"

生成图像的尺寸。gpt-image-2、gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare 和 gpt-image-2.5-flare-2026-09-08 支持以 WIDTHxHEIGHT 字符串指定任意分辨率，例如 1536x864。宽和高均须能被 16 整除，宽高比须在 1:3 至 3:1 之间。高于 2560x1440 的分辨率属于实验功能，支持的最高分辨率为 3840x2160。尺寸还须符合模型当前的像素数与边长限制。GPT Image 模型支持标准尺寸 1024x1024、1536x1024 和 1024x1536；允许自动尺寸的模型支持 auto。

• "1024x1024"

• "1024x1536"

• "1536x1024"

• "auto"

• svg: optional object { model, reasoning }

SVG 生成模型的设置，要求 output_format 为 svg。 启用 SVG 模型选择时，省略此对象会使用 外层响应模型。否则使用默认 SVG 生成模型，且 不能显式覆盖模型。

• model: optional string

minLength: 1

• reasoning: optional object { effort } or null

SVG 编写的推理强度。省略时，Images 和 Responses 均使用编写模型的默认值。

• effort: optional "none" or "minimal" or "low" or 4 more

控制模型为此次请求投入的推理强度。

• "none"

• "minimal"

• "low"

• "medium"

• "high"

• "xhigh"

• "max"

• LocalShell object { type }

允许模型在本地环境执行 shell 命令的工具。

• type: "local_shell" (default: "local_shell")

本地 shell 工具类型，固定为 local_shell。

• "local_shell"

• Shell object { type, allowed_callers, environment }

允许模型执行 shell 命令的工具。

• type: "shell" (default: "shell")

shell 工具类型，固定为 shell。

• "shell"

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

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• environment: optional ContainerAuto or LocalEnvironment or ContainerReference or null

• ContainerAuto object { type, file_ids, memory_limit, 2 more }

• type: "container_auto" (default: "container_auto")

为此请求自动创建容器。

• "container_auto"

• file_ids: optional array of string

可选的已上传文件列表，这些文件将提供给代码使用。

maxItems: 50

• memory_limit: optional "1g" or "4g" or "16g" or "64g" or null

容器的内存上限。

• "1g"

• "4g"

• "16g"

• "64g"

• network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist

容器的网络访问策略。

• ContainerNetworkPolicyDisabled object { type }

• ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }

• skills: optional array of SkillReference or InlineSkill

可选的技能列表，通过 ID 或内联数据引用技能。

maxItems: 200

• SkillReference object { skill_id, type, version }

• skill_id: string

引用的技能 ID。

minLength: 1, maxLength: 64

• type: "skill_reference" (default: "skill_reference")

引用通过 /v1/skills 接口创建的技能。

• "skill_reference"

• version: optional string

可选的技能版本。使用正整数或 'latest'，省略时使用默认版本。

• InlineSkill object { description, name, source, type }

• description: string

技能描述。

• name: string

技能名称。

• source: InlineSkillSource

内联技能载荷。

• data: string

采用 Base64 编码的技能 ZIP 包。

minLength: 1, maxLength: 70254592

• media_type: "application/zip" (default: "application/zip")

内联技能载荷的媒体类型，必须为 application/zip。

• "application/zip"

• type: "base64" (default: "base64")

内联技能来源的类型，必须为 base64。

• "base64"

• type: "inline" (default: "inline")

为此请求定义内联技能。

• "inline"

• LocalEnvironment object { type, skills }

• type: "local" (default: "local")

使用本地计算机环境。

• "local"

• skills: optional array of LocalSkill

可选的技能列表。

maxItems: 200

• description: string

技能描述。

• name: string

技能名称。

• path: string

包含该技能的目录路径。

• ContainerReference object { container_id, type }

• container_id: string

引用的容器 ID。

• type: "container_reference" (default: "container_reference")

引用通过 /v1/containers 接口创建的容器。

• "container_reference"

• Custom object { name, type, allowed_callers, 4 more }

使用指定格式处理输入的自定义工具。参阅自定义工具。

• name: string

自定义工具的名称，用于在工具调用中标识它。

• type: "custom" (default: "custom")

自定义工具类型，固定为 custom。

• "custom"

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

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• async: optional boolean

工具响应是否可以异步返回，而非在下一次创建响应时立即返回。

• defer_loading: optional boolean

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

• description: optional string

自定义工具的可选描述，用于提供更多上下文。

• format: optional CustomToolInputFormat

自定义工具的输入格式，默认为无约束文本。

• Text object { type }

无约束的自由文本。

• type: "text" (default: "text")

无约束文本格式，固定为 text。

• "text"

• Grammar object { definition, syntax, type }

用户定义的语法。

• definition: string

语法定义。

• syntax: "lark" or "regex"

语法定义的语法类型，可选 lark 或 regex。

• "lark"

• "regex"

• type: "grammar" (default: "grammar")

语法格式，固定为 grammar。

• "grammar"

• ToolSearchOutputNamespaceTool object { description, name, tools, type }

将函数工具或自定义工具归入共享命名空间。

• description: string

展示给模型的命名空间描述。

• name: string

工具调用使用的命名空间名称，例如 crm。

minLength: 1

• tools: array of Function { name, type, allowed_callers, 6 more } or Custom { name, type, allowed_callers, 4 more }

此命名空间内已加载的函数工具或自定义工具。

minItems: 1

• Function object { name, type, allowed_callers, 6 more }

• name: string

已加载的函数工具名称。

pattern: ^(?![\s\S]*[\r\n])[a-zA-Z0-9_.-]+$, minLength: 1, maxLength: 128

• type: "function" (default: "function")

• "function"

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

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• async: optional boolean

工具响应是否可以异步返回，而非在下一次创建响应时立即返回。

• defer_loading: optional boolean

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

• description: optional string or null

• output_schema: optional map[unknown] or null

描述此函数工具字符串输出中编码的 JSON 值的 JSON Schema，不用于描述内容数组输出。

• parameters: optional unknown or null

• strict: optional boolean or null

是否强制执行严格参数校验。省略时，模式兼容的情况下 Responses 会尝试严格校验，否则退回非严格校验。

• Custom object { name, type, allowed_callers, 4 more }

使用指定格式处理输入的自定义工具。参阅自定义工具。

• name: string

自定义工具的名称，用于在工具调用中标识它。

• type: "custom" (default: "custom")

自定义工具类型，固定为 custom。

• "custom"

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

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• async: optional boolean

工具响应是否可以异步返回，而非在下一次创建响应时立即返回。

• defer_loading: optional boolean

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

• description: optional string

自定义工具的可选描述，用于提供更多上下文。

• format: optional CustomToolInputFormat

自定义工具的输入格式，默认为无约束文本。

• type: "namespace" (default: "namespace")

工具类型，固定为 namespace。

• "namespace"

• ToolSearch object { type, description, execution, parameters }

用于延迟加载工具的托管工具搜索或自带工具（BYOT）搜索配置。

• type: "tool_search" (default: "tool_search")

工具类型，固定为 tool_search。

• "tool_search"

• description: optional string or null

客户端执行的工具搜索工具展示给模型的描述。

• execution: optional "server" or "client"

工具搜索由服务端还是客户端执行。

• "server"

• "client"

• parameters: optional unknown or null

客户端执行的工具搜索工具的参数模式。

• WebSearchPreview object { type, search_content_types, search_context_size, user_location }

搜索网页以获取可用于响应的相关结果的工具。参阅网页搜索工具。

• type: "web_search_preview" or "web_search_preview_2025_03_11" (default: "web_search_preview")

网页搜索工具类型，可选 web_search_preview 或 web_search_preview_2025_03_11。

• "web_search_preview"

• "web_search_preview_2025_03_11"

• search_content_types: optional array of "text" or "image"

• "text"

• "image"

• search_context_size: optional "low" or "medium" or "high"

对搜索占用上下文窗口空间大小的总体指导，可选 low、medium 或 high，默认为 medium。

• "low"

• "medium"

• "high"

• user_location: optional object { type, city, country, 2 more } or null

用户的大致位置。省略或设为 null 时默认为美国。若要避免此默认值，可传入不包含位置字段的 {"type": "approximate"}。若要本地化结果，须提供相应位置字段。

• type: "approximate" (default: "approximate")

位置估算类型，固定为 approximate。

• "approximate"

• city: optional string or null

用户所在城市的自由文本，例如 San Francisco。

• country: optional string or null

用户所在国家/地区的两字母 ISO 代码，例如 US。

• region: optional string or null

用户所在地区的自由文本，例如 California。

• timezone: optional string or null

用户所在的 IANA 时区，例如 America/Los_Angeles。

• ApplyPatch object { type, allowed_callers }

允许助手使用统一差异格式创建、删除或更新文件。

• type: "apply_patch" (default: "apply_patch")

工具类型，固定为 apply_patch。

• "apply_patch"

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

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• type: "tool_search_output" (default: "tool_search_output")

条目类型，固定为 tool_search_output。

• "tool_search_output"

• id: optional string or null

此工具搜索输出的唯一 ID。

• call_id: optional string or null

模型生成的工具搜索调用的唯一 ID。

minLength: 1, maxLength: 64

• execution: optional "server" or "client"

工具搜索由服务端还是客户端执行。

• "server"

• "client"

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

工具搜索输出的状态。

• "in_progress"

• "completed"

• "incomplete"

• AdditionalTools object { role, tools, type, id }

• role: "developer" (default: "developer")

提供额外工具的角色，仅支持 developer。

• "developer"

• tools: array of Function { name, parameters, strict, 6 more } or FileSearch { type, vector_store_ids, filters, 2 more } or Computer { type } or 13 more

在此条目中提供的额外工具列表。

• Function object { name, parameters, strict, 6 more }

定义模型可以选择调用的自有代码函数。参阅函数调用。

• name: string

要调用的函数名称。

• parameters: map[unknown] or null

描述函数参数的 JSON Schema 对象。

• strict: boolean or null

是否对此函数工具强制执行严格参数校验。

• type: "function" (default: "function")

函数工具类型，固定为 function。

• "function"

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

工具调用的上下文。

• "direct"

• "programmatic"

• async: optional boolean

• defer_loading: optional boolean

此函数是否延迟加载并通过工具搜索加载。

• description: optional string or null

函数描述，模型据此判断是否调用该函数。

• output_schema: optional map[unknown] or null

描述此函数字符串输出中编码的 JSON 值的 JSON Schema 对象。

• FileSearch object { type, vector_store_ids, filters, 2 more }

搜索已上传文件中相关内容的工具。参阅文件搜索工具。

• type: "file_search" (default: "file_search")

文件搜索工具类型，固定为 file_search。

• "file_search"

• vector_store_ids: array of string

要搜索的向量存储 ID 列表。

• filters: optional ComparisonFilter or CompoundFilter or null

要应用的筛选条件。

• ComparisonFilter object { key, type, value }

使用指定比较运算，将某个属性键与给定值比较的筛选条件。

• CompoundFilter object { filters, type }

使用 and 或 or 组合多个筛选条件。

• max_num_results: optional integer

返回结果数量上限，须介于 1–50 之间，含边界。

• ranking_options: optional object { hybrid_search, ranker, score_threshold }

搜索结果的排序选项。

• hybrid_search: optional object { embedding_weight, text_weight }

启用混合搜索时，控制倒数排名融合如何平衡语义嵌入匹配与稀疏关键词匹配的权重。

• embedding_weight: number

嵌入在倒数排名融合中的权重。

• text_weight: number

文本在倒数排名融合中的权重。

• ranker: optional "auto" or "default-2024-11-15"

文件搜索所用的排序器。

• "auto"

• "default-2024-11-15"

• score_threshold: optional number

文件搜索的分数阈值，为 0–1 之间的数字。越接近 1，越倾向于只返回最相关的结果，但返回数量可能减少。

• Computer object { type }

控制虚拟计算机的工具。参阅计算机工具。

• type: "computer" (default: "computer")

计算机工具类型，固定为 computer。

• "computer"

• ComputerUsePreview object { display_height, display_width, environment, type }

控制虚拟计算机的工具。参阅计算机工具。

• display_height: integer

计算机显示区域的高度。

• display_width: integer

计算机显示区域的宽度。

• environment: "windows" or "mac" or "linux" or 2 more

要控制的计算机环境类型。

• "windows"

• "mac"

• "linux"

• "ubuntu"

• "browser"

• type: "computer_use_preview" (default: "computer_use_preview")

计算机使用工具类型，固定为 computer_use_preview。

• "computer_use_preview"

• WebSearch object { type, external_web_access, filters, 2 more }

在互联网上搜索与提示词相关的信息来源。参阅 网络搜索工具时。

• type: "web_search" or "web_search_2025_08_26" (default: "web_search")

网页搜索工具类型，可选 web_search 或 web_search_2025_08_26。

• "web_search"

• "web_search_2025_08_26"

• external_web_access: optional boolean (default: true)

是否允许网页搜索实时访问互联网。省略时默认为 true。设为 false 时，网页搜索工具以离线或仅缓存模式运行，不会抓取新的外部内容。

• filters: optional object { allowed_domains } or null

搜索的筛选条件。

• allowed_domains: optional array of string or null (default: [])

搜索允许的域名。未提供时允许所有域名。 也允许访问所提供域名的子域名。

示例：["pubmed.ncbi.nlm.nih.gov"]

• search_context_size: optional "low" or "medium" or "high" (default: "medium")

对搜索占用上下文窗口空间大小的总体指导，可选 low、medium 或 high，默认为 medium。

• "low"

• "medium"

• "high"

• user_location: optional object { city, country, region, 2 more } or null

用户的大致位置。省略或设为 null 时，默认为 美国。若要避免此默认值，可传入不包含位置字段的 {"type": "approximate"}。 若要本地化结果，须提供相应位置字段。

• city: optional string or null

用户所在城市的自由文本，例如 San Francisco。

• country: optional string or null

用户所在国家/地区的两字母 ISO 代码，例如 US。

• region: optional string or null

用户所在地区的自由文本，例如 California。

• timezone: optional string or null

用户所在的 IANA 时区，例如 America/Los_Angeles。

• type: optional "approximate" (default: "approximate")

位置估算类型，固定为 approximate。

• "approximate"

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

• CodeInterpreter object { container, type, allowed_callers }

运行 Python 代码以帮助生成提示词响应的工具。

• container: string or CodeInterpreterToolAuto { type, file_ids, memory_limit, network_policy }

代码解释器容器，可以是容器 ID，也可以是 指定代码可用的已上传文件 ID 的对象，同时可提供 可选的 memory_limit 设置。

• string

容器 ID。

• CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }

代码解释器容器配置，可以指定运行代码时所处理的文件 ID。

• type: "auto" (default: "auto")

固定为 auto。

• "auto"

• file_ids: optional array of string

可选的已上传文件列表，这些文件将提供给代码使用。

maxItems: 50

• memory_limit: optional "1g" or "4g" or "16g" or "64g" or null

代码解释器容器的内存上限。

• "1g"

• "4g"

• "16g"

• "64g"

• network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist

容器的网络访问策略。

• ContainerNetworkPolicyDisabled object { type }

• ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }

• type: "code_interpreter"

代码解释器工具类型，固定为 code_interpreter。

• "code_interpreter"

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

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• ProgrammaticToolCalling object { type }

• type: "programmatic_tool_calling" (default: "programmatic_tool_calling")

工具类型，固定为 programmatic_tool_calling。

• "programmatic_tool_calling"

• ImageGeneration object { type, action, background, 13 more }

使用 GPT 图像模型生成图像的工具。

• type: "image_generation"

图像生成工具类型，固定为 image_generation。

• "image_generation"

• action: optional "generate" or "edit" or "auto"

生成新图像还是编辑已有图像，默认为 auto。

• "generate"

• "edit"

• "auto"

• background: optional "transparent" or "opaque" or "auto" (default: "auto")

生成图像的背景，可选 transparent、opaque， 或 auto。gpt-image-2.5-sunburst 和 gpt-image-2.5-flare，包括 对应的 2026-09-08 快照，支持 opaque 和 transparent 背景。受支持的 GPT Image 模型可以使用透明 背景。对于 gpt-image-2 和 gpt-image-2-2026-04-21，此功能处于 预览阶段。使用 transparent 时，须将输出格式设为 png 或 webp。 默认为 auto。

• "transparent"

• "opaque"

• "auto"

• complexity: optional "low" or "medium" or "high"

用于规划图像的计算投入，与渲染质量分开设置。 覆盖外层响应用于图像生成的 reasoning.effort。 省略时，继承外层受支持的推理强度，或使用 图像模型配置的默认值。 对于 SVG 输出，此项控制参考图像，而不是 SVG 生成模型的 推理。

• "low"

• "medium"

• "high"

• frame_count: optional integer (default: 9)

GIF 帧数，要求 output_format 为 gif，默认为 9。

minimum: 2, maximum: 16

• frame_duration_ms: optional integer (default: 200)

每个 GIF 帧的时长，单位为毫秒，取整到 10 毫秒。 要求 output_format 为 gif，默认为 200。

minimum: 20, maximum: 2000

• input_fidelity: optional "high" or "low" or null

控制模型为匹配输入图像风格和特征（尤其是面部特征）投入的程度。gpt-image-1.5 支持 high 和 low，gpt-image-1-mini 仅支持 low。使用 gpt-image-2 时应省略此参数。支持该参数的模型默认为 low。

• "high"

• "low"

• input_image_mask: optional object { file_id, image_url }

可选的局部重绘蒙版，包含 image_url （可选字符串）和 file_id（可选字符串）。

• file_id: optional string

蒙版图像的文件 ID。

• image_url: optional string

采用 Base64 编码的蒙版图像。

• model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 9 more

用于图像生成的模型，可选 gpt-image-1-mini、 gpt-image-1.5, gpt-image-2, gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、 gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare、 gpt-image-2.5-flare-2026-09-08, gpt-image-2.6-sunburst, gpt-image-2.6-flare 或 chatgpt-image-latest。默认值： gpt-image-2.6-sunburst.

gpt-image-1 已于 2026 年 10 月 23 日停用，请使用 gpt-image-2.5-sunburst 或 gpt-image-2.5-flare。

• string

• "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 9 more

用于图像生成的模型，可选 gpt-image-1-mini、 gpt-image-1.5, gpt-image-2, gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、 gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare、 gpt-image-2.5-flare-2026-09-08, gpt-image-2.6-sunburst, gpt-image-2.6-flare 或 chatgpt-image-latest。默认值： gpt-image-2.6-sunburst.

gpt-image-1 已于 2026 年 10 月 23 日停用，请使用 gpt-image-2.5-sunburst 或 gpt-image-2.5-flare。

• "gpt-image-1"

• "gpt-image-1-mini"

• "gpt-image-2"

• "gpt-image-2-2026-04-21"

• "gpt-image-2.5-sunburst"

• "gpt-image-2.5-sunburst-2026-09-08"

• "gpt-image-2.5-flare"

• "gpt-image-2.5-flare-2026-09-08"

• "gpt-image-2.6-sunburst"

• "gpt-image-2.6-flare"

• "gpt-image-1.5"

• "chatgpt-image-latest"

• moderation: optional "auto" or "low" (default: "auto")

生成图像的审核级别，默认为 auto。

• "auto"

• "low"

• output_compression: optional integer (default: 100)

输出图像的压缩级别，默认为 100。

minimum: 0, maximum: 100

• output_format: optional "png" or "webp" or "jpeg" or 2 more (default: "png")

输出图像格式，可选 png、webp、jpeg、 gif 或 svg，默认为 png。GIF 和 SVG 输出要求模型 支持所选格式。GIF 输出不支持 部分图像流式传输，即 partial_images 大于 0， 也不支持 input_image_mask 或自定义 output_compression。 GIF 输出仍可以流式发送 Responses 生命周期事件。

• "png"

• "webp"

• "jpeg"

• "gif"

• "svg"

• partial_images: optional integer (default: 0)

流式模式中生成的部分图像数量，范围为 0（默认值）到 3。

minimum: 0, maximum: 3

• quality: optional "low" or "medium" or "high" or 3 more (default: "auto")

生成图像的质量。GPT 图像模型支持 low、 medium 和 high。gpt-image-2.5-sunburst 和 gpt-image-2.5-flare， 包括对应的 2026-09-08 快照，还支持 xhigh 和 max。 默认为 auto。

• "low"

• "medium"

• "high"

• "xhigh"

• "max"

• "auto"

• size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto" (default: "auto")

生成图像的尺寸。gpt-image-2、gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare 和 gpt-image-2.5-flare-2026-09-08 支持以 WIDTHxHEIGHT 字符串指定任意分辨率，例如 1536x864。宽和高均须能被 16 整除，宽高比须在 1:3 至 3:1 之间。高于 2560x1440 的分辨率属于实验功能，支持的最高分辨率为 3840x2160。尺寸还须符合模型当前的像素数与边长限制。GPT Image 模型支持标准尺寸 1024x1024、1536x1024 和 1024x1536；允许自动尺寸的模型支持 auto。

• string

• "1024x1024" or "1024x1536" or "1536x1024" or "auto"

生成图像的尺寸。gpt-image-2、gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare 和 gpt-image-2.5-flare-2026-09-08 支持以 WIDTHxHEIGHT 字符串指定任意分辨率，例如 1536x864。宽和高均须能被 16 整除，宽高比须在 1:3 至 3:1 之间。高于 2560x1440 的分辨率属于实验功能，支持的最高分辨率为 3840x2160。尺寸还须符合模型当前的像素数与边长限制。GPT Image 模型支持标准尺寸 1024x1024、1536x1024 和 1024x1536；允许自动尺寸的模型支持 auto。

• "1024x1024"

• "1024x1536"

• "1536x1024"

• "auto"

• svg: optional object { model, reasoning }

SVG 生成模型的设置，要求 output_format 为 svg。 启用 SVG 模型选择时，省略此对象会使用 外层响应模型。否则使用默认 SVG 生成模型，且 不能显式覆盖模型。

• model: optional string

minLength: 1

• reasoning: optional object { effort } or null

SVG 编写的推理强度。省略时，Images 和 Responses 均使用编写模型的默认值。

• effort: optional "none" or "minimal" or "low" or 4 more

控制模型为此次请求投入的推理强度。

• "none"

• "minimal"

• "low"

• "medium"

• "high"

• "xhigh"

• "max"

• LocalShell object { type }

允许模型在本地环境执行 shell 命令的工具。

• type: "local_shell" (default: "local_shell")

本地 shell 工具类型，固定为 local_shell。

• "local_shell"

• Shell object { type, allowed_callers, environment }

允许模型执行 shell 命令的工具。

• type: "shell" (default: "shell")

shell 工具类型，固定为 shell。

• "shell"

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

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• environment: optional ContainerAuto or LocalEnvironment or ContainerReference or null

• ContainerAuto object { type, file_ids, memory_limit, 2 more }

• LocalEnvironment object { type, skills }

• ContainerReference object { container_id, type }

• Custom object { name, type, allowed_callers, 4 more }

使用指定格式处理输入的自定义工具。参阅自定义工具。

• name: string

自定义工具的名称，用于在工具调用中标识它。

• type: "custom" (default: "custom")

自定义工具类型，固定为 custom。

• "custom"

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

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• async: optional boolean

工具响应是否可以异步返回，而非在下一次创建响应时立即返回。

• defer_loading: optional boolean

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

• description: optional string

自定义工具的可选描述，用于提供更多上下文。

• format: optional CustomToolInputFormat

自定义工具的输入格式，默认为无约束文本。

• Namespace object { description, name, tools, type }

将函数工具或自定义工具归入共享命名空间。

• description: string

展示给模型的命名空间描述。

• name: string

工具调用使用的命名空间名称，例如 crm。

minLength: 1

• tools: array of Function { name, type, allowed_callers, 6 more } or Custom { name, type, allowed_callers, 4 more }

此命名空间内可用的函数工具或自定义工具。

minItems: 1

• Function object { name, type, allowed_callers, 6 more }

• name: string

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

• type: "function" (default: "function")

• "function"

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

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• async: optional boolean

工具响应是否可以异步返回，而非在下一次创建响应时立即返回。

• defer_loading: optional boolean

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

• description: optional string or null

• output_schema: optional map[unknown] or null

描述此函数工具字符串输出中编码的 JSON 值的 JSON Schema，不用于描述内容数组输出。

• parameters: optional unknown or null

• strict: optional boolean or null

是否强制执行严格参数校验。省略时，模式兼容的情况下 Responses 会尝试严格校验，否则退回非严格校验。

• Custom object { name, type, allowed_callers, 4 more }

使用指定格式处理输入的自定义工具。参阅自定义工具。

• name: string

自定义工具的名称，用于在工具调用中标识它。

• type: "custom" (default: "custom")

自定义工具类型，固定为 custom。

• "custom"

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

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• async: optional boolean

工具响应是否可以异步返回，而非在下一次创建响应时立即返回。

• defer_loading: optional boolean

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

• description: optional string

自定义工具的可选描述，用于提供更多上下文。

• format: optional CustomToolInputFormat

自定义工具的输入格式，默认为无约束文本。

• type: "namespace" (default: "namespace")

工具类型，固定为 namespace。

• "namespace"

• ToolSearch object { type, description, execution, parameters }

用于延迟加载工具的托管工具搜索或自带工具（BYOT）搜索配置。

• type: "tool_search" (default: "tool_search")

工具类型，固定为 tool_search。

• "tool_search"

• description: optional string or null

客户端执行的工具搜索工具展示给模型的描述。

• execution: optional "server" or "client"

工具搜索由服务端还是客户端执行。

• "server"

• "client"

• parameters: optional unknown or null

客户端执行的工具搜索工具的参数模式。

• WebSearchPreview object { type, search_content_types, search_context_size, user_location }

搜索网页以获取可用于响应的相关结果的工具。参阅网页搜索工具。

• type: "web_search_preview" or "web_search_preview_2025_03_11" (default: "web_search_preview")

网页搜索工具类型，可选 web_search_preview 或 web_search_preview_2025_03_11。

• "web_search_preview"

• "web_search_preview_2025_03_11"

• search_content_types: optional array of "text" or "image"

• "text"

• "image"

• search_context_size: optional "low" or "medium" or "high"

对搜索占用上下文窗口空间大小的总体指导，可选 low、medium 或 high，默认为 medium。

• "low"

• "medium"

• "high"

• user_location: optional object { type, city, country, 2 more } or null

用户的大致位置。省略或设为 null 时默认为美国。若要避免此默认值，可传入不包含位置字段的 {"type": "approximate"}。若要本地化结果，须提供相应位置字段。

• type: "approximate" (default: "approximate")

位置估算类型，固定为 approximate。

• "approximate"

• city: optional string or null

用户所在城市的自由文本，例如 San Francisco。

• country: optional string or null

用户所在国家/地区的两字母 ISO 代码，例如 US。

• region: optional string or null

用户所在地区的自由文本，例如 California。

• timezone: optional string or null

用户所在的 IANA 时区，例如 America/Los_Angeles。

• ApplyPatch object { type, allowed_callers }

允许助手使用统一差异格式创建、删除或更新文件。

• type: "apply_patch" (default: "apply_patch")

工具类型，固定为 apply_patch。

• "apply_patch"

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

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• type: "additional_tools" (default: "additional_tools")

条目类型，固定为 additional_tools。

• "additional_tools"

• id: optional string or null

此额外工具条目的唯一 ID。

• ConfigurationUpdate object { type, id, reasoning, text }

对话响应配置的更新。提供 reasoning、 text 或两者。每项设置持续生效，直至后续更新替换它。

• type: "configuration_update" (default: "configuration_update")

条目类型，固定为 configuration_update。

• "configuration_update"

• id: optional string or null

配置更新条目的唯一 ID。

• reasoning: optional object { effort }

推理配置更新，仅支持 effort。

• effort: optional ReasoningEffort or null (default: "medium")

后续响应使用的推理强度，直至另一次 配置更新替换它。

• "none"

• "minimal"

• "low"

• "medium"

• "high"

• "xhigh"

• "max"

• text: optional object { format }

后续响应的文本输出配置。

• format: ResponseFormatText or ResponseFormatTextJSONSchemaConfig

使用 JSON Schema 进行结构化输出，或使用 text 恢复纯文本。

• ResponseFormatText object { type }

默认响应格式，用于生成文本响应。

• type: "text"

定义的响应格式类型，固定为 text。

• "text"

• ResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }

JSON Schema 响应格式，用于生成结构化 JSON 响应。 参阅结构化输出。

• name: string

响应格式的名称，须使用 a-z、A-Z、0-9，或包含 下划线和连字符，最长为 64 个字符。

• schema: map[unknown]

以 JSON Schema 对象描述的响应格式模式。 JSON Schema 的构建方法参阅此处。

• type: "json_schema"

定义的响应格式类型，固定为 json_schema。

• "json_schema"

• description: optional string

响应格式的用途描述，模型据此 判断如何按该格式响应。

• strict: optional boolean or null (default: false)

生成输出时是否启用严格模式遵循。 设为 true 时，模型始终严格遵循 schema 字段中定义的模式。strict 为 true 时仅支持 JSON Schema 的子集。更多信息请参阅结构化输出 指南。

• Reasoning object { id, summary, type, 3 more }

描述推理模型生成响应时所用的 思维链。如果手动管理对话的上下文，后续轮次中须将这些条目 包含在发送给 Responses API 的 input 中， 参阅管理上下文。

• id: string

推理内容的唯一标识。

• summary: array of SummaryTextContent

推理摘要内容。

• text: string

模型到目前为止生成的推理输出摘要。

• type: "summary_text" (default: "summary_text")

类型，固定为 summary_text。

• "summary_text"

• type: "reasoning"

类型，固定为 reasoning。

• "reasoning"

• content: optional array of object { text, type }

推理文本内容。

• text: string

模型生成的推理文本。

• type: "reasoning_text" (default: "reasoning_text")

类型，固定为 reasoning_text。

• "reasoning_text"

• encrypted_content: optional string or null

推理条目的加密内容。通过 POST /v1/responses 和 WebSocket response.create 请求返回的推理条目，默认会填充 此字段。

流式传输时，后续请求须使用 response.output_item.done 事件中完整的推理条目及其 encrypted_content。response.output_item.added 中的 encrypted_content 可能不完整。当 store 为 false 或使用零数据保留时，这一点尤其重要。

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

条目状态，可选 in_progress、completed 或 incomplete。通过 API 返回条目时填充。

• "in_progress"

• "completed"

• "incomplete"

• Compaction object { encrypted_content, type, id }

v1/responses/compact API生成的压缩条目。

• encrypted_content: string

压缩摘要的加密内容。

maxLength: 104857600

• type: "compaction" (default: "compaction")

类型，固定为 compaction。

• "compaction"

• id: optional string or null

压缩条目 ID。

• ImageGenerationCall object { id, result, status, 9 more }

模型发起的图像生成请求。

• id: string

图像生成调用的唯一 ID。

• result: string or null

Base64 编码的生成图像。

• status: "in_progress" or "completed" or "generating" or "failed"

图像生成调用的状态。

• "in_progress"

• "completed"

• "generating"

• "failed"

• type: "image_generation_call"

类型，固定为 image_generation_call。

• "image_generation_call"

• action: optional "generate" or "edit" or "auto" or null

用于图像生成的操作。

• "generate"

• "edit"

• "auto"

• background: optional "transparent" or "opaque" or "auto" or null

生成图像使用的背景设置。

• "transparent"

• "opaque"

• "auto"

• error: optional object { code, message, param, 2 more }

审核失败的详情，如可用。

• code: string or null

错误代码。

• message: string

错误描述。

• param: string or null

关联的请求参数。

• type: string

错误类型。

• moderation_details: optional object { categories, moderation_stage }

moderation_blocked 错误的公开详情，如可用。

• categories: array of string

公开的审核类别，未来可能增加新的类别值。

• moderation_stage: "input" or "output" or "unknown"

审核阻止图像生成调用的阶段。

• "input"

• "output"

• "unknown"

• output_format: optional "png" or "webp" or "jpeg" or 2 more or null

生成图像使用的输出格式。

• "png"

• "webp"

• "jpeg"

• "gif"

• "svg"

• quality: optional "low" or "medium" or "high" or 3 more or null

图像生成工具调用生成的图像质量，可选 low、medium、high、xhigh、max 或 auto。

• "low"

• "medium"

• "high"

• "xhigh"

• "max"

• "auto"

• revised_prompt: optional string or null

模型改写提示词后实际使用的提示词。

• size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or null

图像尺寸，采用 WIDTHxHEIGHT 字符串形式，例如 1536x864。

• string

• "1024x1024" or "1024x1536" or "1536x1024"

图像尺寸，采用 WIDTHxHEIGHT 字符串形式，例如 1536x864。

• "1024x1024"

• "1024x1536"

• "1536x1024"

• svg_usage: optional object { input_tokens, model, output_tokens, 2 more }

• input_tokens: integer

• model: string

• output_tokens: integer

• reasoning_tokens: integer

• total_tokens: integer

• CodeInterpreterCall object { id, code, container_id, 3 more }

运行代码的工具调用。

• id: string

代码解释器工具调用的唯一 ID。

• code: string or null

要运行的代码，不可用时为 null。

• container_id: string

运行代码使用的容器 ID。

• outputs: array of Logs { logs, type } or Image { type, url } or null

代码解释器生成的输出，例如日志或图像。 没有可用输出时，可以为 null。

• Logs object { logs, type }

代码解释器的日志输出。

• logs: string

代码解释器的日志输出。

• type: "logs" (default: "logs")

类型，固定为 logs。

• "logs"

• Image object { type, url }

代码解释器的图像输出。

• type: "image" (default: "image")

类型，固定为 image。

• "image"

• url: string

代码解释器输出图像的 URL。

format: uri

• status: "in_progress" or "completed" or "incomplete" or 2 more

代码解释器工具调用的状态，有效值为 in_progress、completed、incomplete、interpreting 和 failed。

• "in_progress"

• "completed"

• "incomplete"

• "interpreting"

• "failed"

• type: "code_interpreter_call" (default: "code_interpreter_call")

类型，固定为 code_interpreter_call。

• "code_interpreter_call"

• LocalShellCall object { id, action, call_id, 2 more }

在本地 shell 上运行命令的工具调用。

• id: string

本地 shell 调用的唯一 ID。

• action: object { command, env, type, 3 more }

在服务器上执行 shell 命令。

• command: array of string

要运行的命令。

• env: map[string]

要为命令设置的环境变量。

• type: "exec" (default: "exec")

类型，固定为 exec。

• "exec"

• timeout_ms: optional integer or null

可选的命令超时时长，单位为毫秒。

• user: optional string or null

可选的运行命令的用户。

• working_directory: optional string or null

可选的运行命令的工作目录。

• call_id: string

模型生成的本地 shell 工具调用的唯一 ID。

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

本地 shell 调用的状态。

• "in_progress"

• "completed"

• "incomplete"

• type: "local_shell_call"

类型，固定为 local_shell_call。

• "local_shell_call"

• LocalShellCallOutput object { id, output, type, status }

本地 shell 工具调用的输出。

• id: string

模型生成的本地 shell 工具调用的唯一 ID。

• output: string

本地 shell 工具调用输出的 JSON 字符串。

• type: "local_shell_call_output"

类型，固定为 local_shell_call_output。

• "local_shell_call_output"

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

条目状态，可选 in_progress、completed 或 incomplete。

• "in_progress"

• "completed"

• "incomplete"

• ShellCall object { action, call_id, type, 4 more }

表示请求执行一个或多个 shell 命令的工具。

• action: object { commands, max_output_length, timeout_ms }

描述如何运行工具调用的 shell 命令及限制。

• commands: array of string

按顺序交给执行环境运行的 shell 命令。

• max_output_length: optional integer or null

从合并的 stdout 和 stderr 输出中最多捕获的 UTF-8 字符数。

• timeout_ms: optional integer or null

允许 shell 命令运行的最大实际时长，单位为毫秒。

• call_id: string

模型生成的 shell 工具调用的唯一 ID。

minLength: 1, maxLength: 64

• type: "shell_call" (default: "shell_call")

类型，固定为 shell_call。

• "shell_call"

• id: optional string or null

shell 工具调用的唯一 ID，通过 API 返回此条目时填充。

• caller: optional Direct { type } or Program { caller_id, type } or null

产生此工具调用的执行上下文。

• Direct object { type }

• type: "direct" (default: "direct")

调用方类型，固定为 direct。

• "direct"

• Program object { caller_id, type }

• caller_id: string

产生此工具调用的 program 条目的调用 ID。

minLength: 1, maxLength: 64

• type: "program" (default: "program")

调用方类型，固定为 program。

• "program"

• environment: optional LocalEnvironment or ContainerReference or null

执行 shell 命令的环境。

• LocalEnvironment object { type, skills }

• ContainerReference object { container_id, type }

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

shell 调用状态，可选 in_progress、completed 或 incomplete。

• "in_progress"

• "completed"

• "incomplete"

• ShellCallOutput object { call_id, output, type, 4 more }

shell 工具调用发出的流式输出条目。

• call_id: string

模型生成的 shell 工具调用的唯一 ID。

minLength: 1, maxLength: 64

• output: array of ResponseFunctionShellCallOutputContent

捕获的 stdout 和 stderr 输出块，以及关联的执行结果。

• outcome: Timeout { type } or Exit { exit_code, type }

此 shell 调用关联的退出或超时结果。

• Timeout object { type }

表示 shell 调用超过其配置的时间限制。

• type: "timeout" (default: "timeout")

结果类型，固定为 timeout。

• "timeout"

• Exit object { exit_code, type }

表示 shell 命令已结束，并返回退出码。

• exit_code: integer

shell 进程返回的退出码。

• type: "exit" (default: "exit")

结果类型，固定为 exit。

• "exit"

• stderr: string

捕获的 shell 调用的 stderr 输出。

maxLength: 10485760

• stdout: string

捕获的 shell 调用的 stdout 输出。

maxLength: 10485760

• type: "shell_call_output" (default: "shell_call_output")

类型，固定为 shell_call_output。

• "shell_call_output"

• id: optional string or null

shell 工具调用输出的唯一 ID，通过 API 返回此条目时填充。

• caller: optional Direct { type } or Program { caller_id, type } or null

产生此工具调用的执行上下文。

• Direct object { type }

• type: "direct" (default: "direct")

调用方类型，固定为 direct。

• "direct"

• Program object { caller_id, type }

• caller_id: string

产生此工具调用的 program 条目的调用 ID。

minLength: 1, maxLength: 64

• type: "program" (default: "program")

调用方类型，固定为 program。

• "program"

• max_output_length: optional integer or null

此 shell 调用合并输出中捕获的最大 UTF-8 字符数。

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

shell 调用输出的状态。

• "in_progress"

• "completed"

• "incomplete"

• ApplyPatchCall object { call_id, operation, status, 3 more }

表示请求使用差异补丁创建、删除或更新文件的工具调用。

• call_id: string

模型生成的 apply_patch 工具调用的唯一 ID。

minLength: 1, maxLength: 64

• operation: CreateFile { diff, path, type } or DeleteFile { path, type } or UpdateFile { diff, path, type }

apply_patch 工具调用具体的创建、删除或更新指令。

• CreateFile object { diff, path, type }

通过 apply_patch 工具创建新文件的指令。

• diff: string

创建文件时应用的统一差异内容。

maxLength: 10485760

• path: string

相对于工作区根目录的待创建文件路径。

minLength: 1

• type: "create_file" (default: "create_file")

操作类型，固定为 create_file。

• "create_file"

• DeleteFile object { path, type }

通过 apply_patch 工具删除已有文件的指令。

• path: string

相对于工作区根目录的待删除文件路径。

minLength: 1

• type: "delete_file" (default: "delete_file")

操作类型，固定为 delete_file。

• "delete_file"

• UpdateFile object { diff, path, type }

通过 apply_patch 工具更新已有文件的指令。

• diff: string

应用于已有文件的统一差异内容。

maxLength: 10485760

• path: string

相对于工作区根目录的待更新文件路径。

minLength: 1

• type: "update_file" (default: "update_file")

操作类型，固定为 update_file。

• "update_file"

• status: "in_progress" or "completed"

apply_patch 工具调用状态，可选 in_progress 或 completed。

• "in_progress"

• "completed"

• type: "apply_patch_call" (default: "apply_patch_call")

类型，固定为 apply_patch_call。

• "apply_patch_call"

• id: optional string or null

apply_patch 工具调用的唯一 ID，通过 API 返回此条目时填充。

• caller: optional Direct { type } or Program { caller_id, type } or null

产生此工具调用的执行上下文。

• Direct object { type }

• type: "direct" (default: "direct")

调用方类型，固定为 direct。

• "direct"

• Program object { caller_id, type }

• caller_id: string

产生此工具调用的 program 条目的调用 ID。

minLength: 1, maxLength: 64

• type: "program" (default: "program")

调用方类型，固定为 program。

• "program"

• ApplyPatchCallOutput object { call_id, status, type, 3 more }

apply_patch 工具调用发出的流式输出。

• call_id: string

模型生成的 apply_patch 工具调用的唯一 ID。

minLength: 1, maxLength: 64

• status: "completed" or "failed"

apply_patch 工具调用输出的状态，可选 completed 或 failed。

• "completed"

• "failed"

• type: "apply_patch_call_output" (default: "apply_patch_call_output")

类型，固定为 apply_patch_call_output。

• "apply_patch_call_output"

• id: optional string or null

apply_patch 工具调用输出的唯一 ID，通过 API 返回此条目时填充。

• caller: optional Direct { type } or Program { caller_id, type } or null

产生此工具调用的执行上下文。

• Direct object { type }

• type: "direct" (default: "direct")

调用方类型，固定为 direct。

• "direct"

• Program object { caller_id, type }

• caller_id: string

产生此工具调用的 program 条目的调用 ID。

minLength: 1, maxLength: 64

• type: "program" (default: "program")

调用方类型，固定为 program。

• "program"

• output: optional string or null

apply_patch 工具可选的可读日志文本，例如补丁结果或错误。

maxLength: 10485760

• McpListTools object { id, server_label, tools, 2 more }

MCP 服务器可用的工具列表。

• id: string

列表的唯一 ID。

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

• error: optional string or null

服务器无法列出工具时的错误消息。

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

工具调用的人工批准请求。

• id: string

批准请求的唯一 ID。

• arguments: string

工具参数的 JSON 字符串。

• name: string

要运行的工具名称。

• server_label: string

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

• type: "mcp_approval_request"

类型，固定为 mcp_approval_request。

• "mcp_approval_request"

• McpApprovalResponse object { approval_request_id, approve, type, 2 more }

对 MCP 批准请求的响应。

• approval_request_id: string

所回应的批准请求的 ID。

• approve: boolean

请求是否获准。

• type: "mcp_approval_response"

类型，固定为 mcp_approval_response。

• "mcp_approval_response"

• id: optional string or null

批准响应的唯一 ID。

• reason: optional string or null

决定的可选理由。

• McpCall object { id, arguments, name, 6 more }

对 MCP 服务器上工具的调用。

• 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

MCP 工具调用批准请求的唯一标识。 在后续 mcp_approval_response 输入中包含此值，可批准或拒绝对应工具调用。

• error: optional McpToolCallError or null

工具调用的错误，如有。

• McpProtocolError object { code, message, type }

• code: integer

• message: string

• type: "mcp_protocol_error" (default: "mcp_protocol_error")

• "mcp_protocol_error"

• McpToolExecutionError object { content, type }

• content: unknown

• type: "mcp_tool_execution_error" (default: "mcp_tool_execution_error")

• "mcp_tool_execution_error"

• HTTPError object { code, message, type }

• code: integer

• message: string

• type: "http_error" (default: "http_error")

• "http_error"

• output: optional string or null

工具调用的输出。

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

工具调用状态，可选 in_progress、completed、incomplete、calling 或 failed。

• "in_progress"

• "completed"

• "incomplete"

• "calling"

• "failed"

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

自有代码生成、回传给模型的自定义工具调用输出。

• call_id: string

调用 ID，用于将此自定义工具调用输出映射到自定义工具调用。

• output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile

自有代码生成的自定义工具调用输出。 可以是字符串或输出内容列表。

• StringOutput = string

自定义工具调用输出的字符串。

• OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile

自定义工具调用的文本、图像或文件输出。

• ResponseInputText object { text, type, prompt_cache_breakpoint }

输入模型的文本。

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

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

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

输入模型的文件。

• type: "custom_tool_call_output"

类型，固定为 custom_tool_call_output。

• "custom_tool_call_output"

• id: optional string

自定义工具调用输出在 OpenAI 平台中的唯一 ID。

• caller: optional Direct { type } or Program { caller_id, type } or null

产生此工具调用的执行上下文。

• Direct object { type }

• type: "direct" (default: "direct")

调用方类型，固定为 direct。

• "direct"

• Program object { caller_id, type }

• caller_id: string

产生此工具调用的 program 条目的调用 ID。

minLength: 1, maxLength: 64

• type: "program" (default: "program")

调用方类型，固定为 program。

• "program"

• CustomToolCall object { call_id, input, name, 5 more }

模型生成的自定义工具调用。

• call_id: string

用于将此自定义工具调用映射到工具调用输出的标识。

• input: string

模型生成的自定义工具调用输入。

• name: string

被调用的自定义工具的名称。

• type: "custom_tool_call"

类型，固定为 custom_tool_call。

• "custom_tool_call"

• id: optional string

自定义工具调用在 OpenAI 平台中的唯一 ID。

• async: optional boolean

自定义工具调用是否异步运行。

• caller: optional Direct { type } or Program { caller_id, type } or null

产生此工具调用的执行上下文。

• Direct object { type }

• type: "direct" (default: "direct")

• "direct"

• Program object { caller_id, type }

• caller_id: string

产生此工具调用的 program 条目的调用 ID。

• type: "program" (default: "program")

• "program"

• namespace: optional string

被调用的自定义工具所属的命名空间。

• CompactionTrigger object { type, id }

压缩当前上下文，须为最后一个输入条目。

• type: "compaction_trigger" (default: "compaction_trigger")

类型，固定为 compaction_trigger。

• "compaction_trigger"

• id: optional string or null

此压缩触发器的唯一 ID。

• ItemReference object { id, type }

用于引用条目的内部标识。

• id: string

要引用的条目的 ID。

• type: optional "item_reference" or null (default: "item_reference")

引用条目的类型，固定为 item_reference。

• "item_reference"

• Program object { id, call_id, code, 2 more }

• id: string

此 program 条目的唯一 ID。

• call_id: string

program 条目的稳定调用 ID。

minLength: 1, maxLength: 64

• code: string

程序化工具调用所执行的 JavaScript 源代码。

maxLength: 10485760

• fingerprint: string

不透明的程序重放指纹，须在后续请求中原样回传。

maxLength: 10485760

• type: "program" (default: "program")

条目类型，固定为 program。

• "program"

• ProgramOutput object { id, call_id, result, 2 more }

• id: string

此程序输出条目的唯一 ID。

• call_id: string

program 条目的调用 ID。

minLength: 1, maxLength: 64

• result: string

program 条目生成的结果。

maxLength: 10485760

• status: "completed" or "incomplete"

程序输出的终态。

• "completed"

• "incomplete"

• type: "program_output" (default: "program_output")

条目类型，固定为 program_output。

• "program_output"

• type: "response.item.create" (default: "response.item.create")

Live 客户端事件类型，固定为 response.item.create。

• "response.item.create"

• event_id: optional string or null

可选的客户端标识，用于将此命令与服务端事件的 client_event_id 或 error.client_event_id 关联。

maxLength: 512

示例

{
  "type": "response.item.create",
  "event_id": "evt_item_001",
  "item": {
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "请查询晚上7点的两人桌。"
      }
    ]
  }
}

response.create

向 Live 会话的 Responses 后端请求响应，或继续等待工具结果的委派响应。要求使用 Responses 委派。

模式定义

模式名称：LiveResponseCreateParam

• type: "response.create" (default: "response.create")

Live 客户端事件类型，固定为 response.create。

• "response.create"

• event_id: optional string or null

可选的客户端标识，用于将此命令与服务端事件的 client_event_id 或 error.client_event_id 关联。

maxLength: 512

示例

{
  "type": "response.create",
  "event_id": "evt_response_001"
}

session.close

请求关闭 Live 会话。终止事件 session.closed 包含关闭原因和最终用量。

模式定义

模式名称：LiveSessionCloseParam

• type: "session.close" (default: "session.close")

Live 客户端事件类型，固定为 session.close。

• "session.close"

• event_id: optional string or null

可选的客户端标识，用于将此命令与服务端事件的 client_event_id 或 error.client_event_id 关联。

maxLength: 512

示例

{
  "type": "session.close",
  "event_id": "evt_close_001"
}

服务端事件

transport.ringing

SIP 外呼的服务提供商一侧正在振铃或提供早期媒体。仅发送给旁路观察者。

模式定义

模式名称：LiveTransportRinging

• event_id: string

• session_id: string

Live 会话的规范 ID。

• type: "transport.ringing" (default: "transport.ringing")

• "transport.ringing"

示例

{
  "type": "transport.ringing",
  "event_id": "event_call_1",
  "session_id": "live_u0_123"
}

transport.answered

SIP 外呼的服务提供商一侧已接听，媒体连接已建立。仅发送给旁路观察者。

模式定义

模式名称：LiveTransportAnswered

• event_id: string

• session_id: string

Live 会话的规范 ID。

• type: "transport.answered" (default: "transport.answered")

• "transport.answered"

示例

{
  "type": "transport.answered",
  "event_id": "event_call_2",
  "session_id": "live_u0_123"
}

transport.failed

SIP 外呼建立过程的异步失败。仅发送给旁路观察者。

模式定义

模式名称：LiveTransportFailed

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

• code: string

呼叫建立失败的错误码。

• message: string

• type: "call_error" (default: "call_error")

• "call_error"

• param: optional string

与错误关联的参数，如有。没有适用参数时为空。

• event_id: string

• session_id: string

Live 会话的规范 ID。

• type: "transport.failed" (default: "transport.failed")

• "transport.failed"

示例

{
  "type": "transport.failed",
  "event_id": "event_call_4",
  "session_id": "live_u0_123",
  "error": {
    "type": "call_error",
    "code": "provider_invite_failed",
    "message": "服务提供商拒绝了呼叫",
    "param": ""
  }
}

session.started

Live 会话启动后返回，包含解析生效后的会话配置及服务端默认值。

模式定义

模式名称：LiveSessionStarted

• event_id: string

Live 服务端事件的唯一 ID。

• session: SessionResource

解析生效后的 Live 会话配置，以及服务端分配的会话元数据。

• id: string

Live 会话的唯一 ID，用于旁路连接、分叉和下载录音。

• expires_at: integer

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

• model: string or "gpt-live-1"

Live 模型。无论采用哪种传输方式，均须在会话配置中指定；不要通过 URL 查询参数传入。

• string

minLength: 1

• "gpt-live-1"

Live 模型。无论采用哪种传输方式，均须在会话配置中指定；不要通过 URL 查询参数传入。

• "gpt-live-1"

• status: "active" (default: "active")

会话快照的状态，始终为 active，包括 session.closed 中的最终快照；须通过事件类型判断会话已关闭。

• "active"

• audio: optional object { format, output }

启动时的音频配置。只有主 WebSocket 接受 audio.format；WebRTC 和 SIP 协商媒体格式。音色与格式在启动后不可更改。

• format: optional AudioFormat

Live WebSocket 连接收发音频的编码与采样率。WebRTC 和 SIP 单独协商媒体格式。

• AudioPCM object { rate, type }

Live WebSocket 连接的原始单声道、16 位小端序 PCM 音频。

• rate: 16000 or 24000

音频采样率，单位为 Hz。Live WebSocket 的 PCM 音频支持 16000 或 24000 Hz。

minimum: 16000, maximum: 24000

• 16000

• 24000

• type: "audio/pcm" (default: "audio/pcm")

音频编码，固定为 audio/pcm。

• "audio/pcm"

• AudioPCMU object { rate, type }

Live WebSocket 连接的原始单声道 G.711 μ-law 音频。

• rate: integer

音频采样率，单位为 Hz。G.711 音频使用 8000 Hz。

minimum: 8000, maximum: 8000

• type: "audio/pcmu" (default: "audio/pcmu")

音频编码，固定为 audio/pcmu。

• "audio/pcmu"

• AudioPCMA object { rate, type }

Live WebSocket 连接的原始单声道 G.711 A-law 音频。

• rate: integer

音频采样率，单位为 Hz。G.711 音频使用 8000 Hz。

minimum: 8000, maximum: 8000

• type: "audio/pcma" (default: "audio/pcma")

音频编码，固定为 audio/pcma。

• "audio/pcma"

• output: optional object { voice }

Live 模型生成语音使用的音色。

• voice: optional string or "alloy" or "ash" or "ballad" or 35 more or CustomVoice

Live 语音使用的音色，可以是内置音色名称，也可以是包含 ID 的自定义音色对象。默认为 marin，启动后不能更改。

• string

• "alloy" or "ash" or "ballad" or 35 more

Live 语音使用的音色，可以是内置音色名称，也可以是包含 ID 的自定义音色对象。默认为 marin，启动后不能更改。

• "alloy"

• "ash"

• "ballad"

• "beacon"

• "bossa"

• "brise"

• "calandria"

• "cedar"

• "cinder"

• "compas"

• "coral"

• "delta"

• "destello"

• "echo"

• "flitz"

• "gleam"

• "halo"

• "harema"

• "hornero"

• "juni"

• "luciernaga"

• "marin"

• "meridian"

• "nira"

• "noeul"

• "nuri"

• "pearl"

• "quartz"

• "ripple"

• "sage"

• "shida"

• "shimmer"

• "sillage"

• "stone"

• "tempo"

• "verse"

• "vesper"

• "willow"

• CustomVoice object { id }

• id: string

minLength: 1, maxLength: 128

• client: optional ClientConfig

仅在启动时设置的能力权限，适用于连接到统一 WebRTC 会话的不可信前端，不影响可信的旁路连接。

• data_channel: DataChannelConfig

WebRTC 前端数据通道的客户端与服务端事件权限。

• allowed_client_events: optional "all" or array of string

前端数据通道可发送的客户端事件类型。使用 'all' 允许所有客户端事件，空数组表示全部禁止。省略时保留原有的全部允许行为。

• "all"

• "all"

• array of string

maxItems: 256

• allowed_server_events: optional "all" or array of ServerEventSelector

可发送到前端数据通道的服务端事件。使用 'all' 允许所有服务端事件，空数组表示全部禁止。省略时保留原有的全部允许行为。Responses 事件通过包含 type 'response.event' 和 response_event 选择器的对象指定。

• "all"

• "all"

• array of ServerEventSelector

maxItems: 256

• type: string

外层 Live 服务端事件类型。对于 Responses 事件，使用 'response.event'。

minLength: 1, maxLength: 256

• response_event: optional string

内嵌的 Responses 事件类型。type 为 'response.event' 时必填；其他事件类型禁止使用此字段。

minLength: 1, maxLength: 256

• delegation: optional ClientDelegation or Responses { responses, type, acknowledgement_delay_ms } or Decisions { decisions, type, acknowledgement_delay_ms } or null

Live 模型委派任务的处理方。省略或设为 null 时，由你的应用处理；使用 responses 或 decisions，可委派给对应 API。

• ClientDelegation object { type, acknowledgement_delay_ms }

将任务委派给你的应用。Live 会话发出委派事件，由你的后端处理。

• type: "client" (default: "client")

委派任务的处理方。由你的应用处理时固定为 client。

• "client"

• acknowledgement_delay_ms: optional integer

从委派任务发出到请求自动语音确认的等待时长，单位为毫秒。模型仍可能在等待结束前发言。向会话追加任何说明（commentary）或思考（thinking）都会取消所有待处理的确认，包括其他委派任务的确认。Decisions 会话默认为 400，其他会话默认为 0，即立即请求。更新会话时省略此项会保留当前值；更新仅作用于后续委派。

minimum: 0, maximum: 800

• Responses object { responses, type, acknowledgement_delay_ms }

将任务委派给由 Live 会话管理的 Responses 模型。

• responses: ResponsesDelegationConfig

Live 会话将任务委派给 Responses 时所使用的后端模型、提示词和工具。

• model: string

服务端管理的 Responses 委派使用的模型。

• instructions: optional string or null

交给被委派的 Responses 模型的指令，与 Live 指令分开设置。参阅后端提示词。

• max_output_tokens: optional integer or null

每次委派响应的最大输出词元数。

minimum: 16

• parallel_tool_calls: optional boolean or null

被委派的 Responses 模型能否在单次响应中请求多个工具调用。

• reasoning: optional object { effort, summary } or null

传给每次委派 Responses 请求的推理配置。

• effort: optional "none" or "minimal" or "low" or 3 more or null

被委派的 Responses 模型使用的推理强度。支持的值取决于后端模型。

• "none"

• "minimal"

• "low"

• "medium"

• "high"

• "xhigh"

• summary: optional "concise" or "detailed" or "auto" or null

向被委派的 Responses 模型请求的推理摘要类型，须模型支持。

• "concise"

• "detailed"

• "auto"

• service_tier: optional "auto" or "default" or "fast_tier_temp_pilot" or 3 more or null

委派 Responses 请求使用的服务层级。

• "auto"

• "default"

• "fast_tier_temp_pilot"

• "flex"

• "priority"

• "ultrafast"

• text: optional object { verbosity } or null

传给每次委派 Responses 请求的文本生成配置。

• verbosity: optional "low" or "medium" or "high" or null

Responses 后端生成文本的详细程度，此项不配置 Live 模型的口头表达方式。

• "low"

• "medium"

• "high"

• tool_choice: optional "auto" or "none" or "required" or Function { name, type } or Mcp { server_label, type, name } or 11 more

控制 Responses 后端在处理 Live 模型委派的任务时使用哪个工具。

• LiveToolChoiceEnum = "auto" or "none" or "required"

• "auto"

• "none"

• "required"

• Function object { name, type }

• name: string

要调用的函数工具名称。

• type: "function" (default: "function")

要调用的工具，固定为 function。

• "function"

• Mcp object { server_label, type, name }

• server_label: string

要调用的 MCP 服务器标签。

• type: "mcp" (default: "mcp")

要调用的工具，固定为 mcp。

• "mcp"

• name: optional string or null

要调用的 MCP 工具名称。省略时，服务器可选择默认工具。

• FileSearch object { type }

• type: "file_search" (default: "file_search")

要调用的工具，固定为 file_search。

• "file_search"

• WebSearch object { type }

• type: "web_search" (default: "web_search")

要调用的工具，固定为 web_search。

• "web_search"

• WebSearchPreview object { type }

• type: "web_search_preview" (default: "web_search_preview")

要调用的工具，固定为 web_search_preview。

• "web_search_preview"

• ImageGeneration object { type }

• type: "image_generation" (default: "image_generation")

要调用的工具，固定为 image_generation。

• "image_generation"

• Computer object { type }

• type: "computer" (default: "computer")

要调用的工具，固定为 computer。

• "computer"

• CodeInterpreter object { type }

• type: "code_interpreter" (default: "code_interpreter")

要调用的工具，固定为 code_interpreter。

• "code_interpreter"

• ProgrammaticToolCalling object { type }

• type: "programmatic_tool_calling" (default: "programmatic_tool_calling")

要调用的工具，固定为 programmatic_tool_calling。

• "programmatic_tool_calling"

• Shell object { type }

需要调用工具时，强制模型调用 shell 工具。

• type: "shell" (default: "shell")

要调用的工具，固定为 shell。

• "shell"

• Custom object { name, type }

• name: string

要调用的自定义工具名称。

• type: "custom" (default: "custom")

要调用的工具，固定为 custom。

• "custom"

• ApplyPatch object { type }

执行工具调用时，强制模型调用 apply_patch 工具。

• type: "apply_patch" (default: "apply_patch")

要调用的工具，固定为 apply_patch。

• "apply_patch"

• LiveAllowedToolsChoiceParam object { tools, type, mode }

• tools: array of Function { name, type } or Mcp { server_label, type, name } or FileSearch { type } or 9 more

被委派的 Responses 模型可以调用的工具。

minItems: 1, maxItems: 128

• Function object { name, type }

• name: string

要调用的函数工具名称。

• type: "function" (default: "function")

要调用的工具，固定为 function。

• "function"

• Mcp object { server_label, type, name }

• server_label: string

要调用的 MCP 服务器标签。

• type: "mcp" (default: "mcp")

要调用的工具，固定为 mcp。

• "mcp"

• name: optional string or null

要调用的 MCP 工具名称。省略时，服务器可选择默认工具。

• FileSearch object { type }

• type: "file_search" (default: "file_search")

要调用的工具，固定为 file_search。

• "file_search"

• WebSearch object { type }

• type: "web_search" (default: "web_search")

要调用的工具，固定为 web_search。

• "web_search"

• WebSearchPreview object { type }

• type: "web_search_preview" (default: "web_search_preview")

要调用的工具，固定为 web_search_preview。

• "web_search_preview"

• ImageGeneration object { type }

• type: "image_generation" (default: "image_generation")

要调用的工具，固定为 image_generation。

• "image_generation"

• Computer object { type }

• type: "computer" (default: "computer")

要调用的工具，固定为 computer。

• "computer"

• CodeInterpreter object { type }

• type: "code_interpreter" (default: "code_interpreter")

要调用的工具，固定为 code_interpreter。

• "code_interpreter"

• ProgrammaticToolCalling object { type }

• type: "programmatic_tool_calling" (default: "programmatic_tool_calling")

要调用的工具，固定为 programmatic_tool_calling。

• "programmatic_tool_calling"

• Shell object { type }

需要调用工具时，强制模型调用 shell 工具。

• type: "shell" (default: "shell")

要调用的工具，固定为 shell。

• "shell"

• Custom object { name, type }

• name: string

要调用的自定义工具名称。

• type: "custom" (default: "custom")

要调用的工具，固定为 custom。

• "custom"

• ApplyPatch object { type }

执行工具调用时，强制模型调用 apply_patch 工具。

• type: "apply_patch" (default: "apply_patch")

要调用的工具，固定为 apply_patch。

• "apply_patch"

• type: "allowed_tools" (default: "allowed_tools")

工具选择类型，固定为 allowed_tools。

• "allowed_tools"

• mode: optional "none" or "auto" or "required" or null

从允许的工具集合中选择工具的方式。

• "none"

• "auto"

• "required"

• tools: optional array of FunctionTool or WebSearch { type } or FileSearch { type } or 10 more

Responses 后端处理 Live 模型委派的任务时可用的工具。

• FunctionTool object { name, type, description, 2 more }

Live 模型委派任务时，Responses 后端可用的函数工具。

• name: string

被委派的 Responses 模型调用此函数时使用的名称。

• type: "function" (default: "function")

工具类型，固定为 function。

• "function"

• description: optional string or null

函数的用途，以及被委派的 Responses 模型应在何时调用它。

• parameters: optional map[unknown] or null

描述函数可接受参数的 JSON Schema 对象。

• strict: optional boolean or null

被委派的 Responses 模型是否必须严格遵循函数的参数模式。

• WebSearch object { type }

Live 会话的 Responses 后端可用的网页搜索工具。

• type: "web_search" (default: "web_search")

工具类型，固定为 web_search。

• "web_search"

• FileSearch object { type }

• type: "file_search" (default: "file_search")

• "file_search"

• CodeInterpreter object { type }

• type: "code_interpreter" (default: "code_interpreter")

• "code_interpreter"

• Shell object { type, environment }

Responses shell 工具。可使用托管容器，或通过 response.item.create 返回本地 shell 执行结果。不支持域名密钥（domain secrets）。

• type: "shell" (default: "shell")

• "shell"

• environment: optional ContainerAuto { type, file_ids, memory_limit, 2 more } or ContainerReference { container_id, type } or Local { type, skills } or null

• ContainerAuto object { type, file_ids, memory_limit, 2 more }

• type: "container_auto" (default: "container_auto")

为此请求自动创建容器。

• "container_auto"

• file_ids: optional array of string or null

可选的已上传文件列表，这些文件将提供给代码使用。

maxItems: 50

• memory_limit: optional "1g" or "4g" or "16g" or "64g" or null

容器的内存上限。

• "1g"

• "4g"

• "16g"

• "64g"

• network_policy: optional Disabled { type } or Allowlist { allowed_domains, type } or null

容器的网络访问策略。

• Disabled object { type }

• type: "disabled" (default: "disabled")

禁用出站网络访问，固定为 disabled。

• "disabled"

• Allowlist object { allowed_domains, type }

• allowed_domains: array of string

type 为 allowlist 时允许访问的域名列表。

minItems: 1

• type: "allowlist" (default: "allowlist")

仅允许对指定域名发起出站网络访问，固定为 allowlist。

• "allowlist"

• skills: optional array of SkillReference { skill_id, type, version } or Inline { description, name, source, type } or null

可选的技能列表，通过 ID 或内联数据引用技能。

maxItems: 200

• SkillReference object { skill_id, type, version }

• skill_id: string

引用的技能 ID。

minLength: 1, maxLength: 64

• type: "skill_reference" (default: "skill_reference")

引用通过 /v1/skills 接口创建的技能。

• "skill_reference"

• version: optional string or null

可选的技能版本。使用正整数或 'latest'，省略时使用默认版本。

• Inline object { description, name, source, type }

• description: string

技能描述。

• name: string

技能名称。

• source: object { data, media_type, type }

内联技能载荷。

• data: string

采用 Base64 编码的技能 ZIP 包。

minLength: 1, maxLength: 70254592

• media_type: "application/zip" (default: "application/zip")

内联技能载荷的媒体类型，必须为 application/zip。

• "application/zip"

• type: "base64" (default: "base64")

内联技能来源的类型，必须为 base64。

• "base64"

• type: "inline" (default: "inline")

为此请求定义内联技能。

• "inline"

• ContainerReference object { container_id, type }

• container_id: string

引用的容器 ID。

• type: "container_reference" (default: "container_reference")

引用通过 /v1/containers 接口创建的容器。

• "container_reference"

• Local object { type, skills }

• type: "local" (default: "local")

使用本地计算机环境。

• "local"

• skills: optional array of object { description, name, path } or null

可选的技能列表。

maxItems: 200

• description: string

技能描述。

• name: string

技能名称。

• path: string

包含该技能的目录路径。

• ImageGeneration object { type }

• type: "image_generation" (default: "image_generation")

• "image_generation"

• Mcp object { type }

• type: "mcp" (default: "mcp")

• "mcp"

• Custom object { type }

• type: "custom" (default: "custom")

• "custom"

• Namespace object { type }

• type: "namespace" (default: "namespace")

• "namespace"

• ToolSearch object { type }

• type: "tool_search" (default: "tool_search")

• "tool_search"

• ProgrammaticToolCalling object { type }

• type: "programmatic_tool_calling" (default: "programmatic_tool_calling")

• "programmatic_tool_calling"

• Computer object { type }

• type: "computer" (default: "computer")

• "computer"

• ApplyPatch object { type }

• type: "apply_patch" (default: "apply_patch")

• "apply_patch"

• type: "responses" (default: "responses")

委派任务的处理方。由 Responses API 处理任务时固定为 responses。

• "responses"

• acknowledgement_delay_ms: optional integer

从委派任务发出到请求自动语音确认的等待时长，单位为毫秒。模型仍可能在等待结束前发言。向会话追加任何说明（commentary）或思考（thinking）都会取消所有待处理的确认，包括其他委派任务的确认。Decisions 会话默认为 400，其他会话默认为 0，即立即请求。更新会话时省略此项会保留当前值；更新仅作用于后续委派。

minimum: 0, maximum: 800

• Decisions object { decisions, type, acknowledgement_delay_ms }

• decisions: DecisionsDelegationConfig

• model: string

minLength: 1

• questions: array of DecisionQuestion

按顺序一起求值的原生 Decision API 问题。

minItems: 1, maxItems: 64

• Choice object { choices, instructions, type, name }

• choices: array of DecisionChoiceOption

minItems: 2, maxItems: 255

• value: string or boolean

• string

• boolean

• description: optional string

• instructions: string or array of DecisionInputText or InputImage { image_url, type, detail } or InputJSON { data, type }

• string

• array of DecisionInputText or InputImage { image_url, type, detail } or InputJSON { data, type }

minItems: 1

• DecisionInputText object { text, type }

• text: string

输入模型的文本。

maxLength: 10485760

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

• "input_text"

• InputImage object { image_url, type, detail }

• image_url: string

采用 Base64 编码的图像 data URL，或可公开访问的 HTTP(S) 图像 URL。

pattern: ^(data:|https?://), maxLength: 20971520

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

• "input_image"

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

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

• "low"

• "high"

• "auto"

• "original"

• InputJSON object { data, type }

• data: map[unknown] or array of map[unknown]

• LiveDecisionJSONObject = map[unknown]

• array of map[unknown]

• type: "input_json" (default: "input_json")

• "input_json"

• type: "choice" (default: "choice")

• "choice"

• name: optional string

• Predicate object { instructions, type, name }

• instructions: string or array of DecisionInputText or InputImage { image_url, type, detail } or InputJSON { data, type }

• string

• array of DecisionInputText or InputImage { image_url, type, detail } or InputJSON { data, type }

minItems: 1

• DecisionInputText object { text, type }

• InputImage object { image_url, type, detail }

• image_url: string

采用 Base64 编码的图像 data URL，或可公开访问的 HTTP(S) 图像 URL。

pattern: ^(data:|https?://), maxLength: 20971520

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

• "input_image"

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

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

• "low"

• "high"

• "auto"

• "original"

• InputJSON object { data, type }

• data: map[unknown] or array of map[unknown]

• LiveDecisionJSONObject = map[unknown]

• array of map[unknown]

• type: "input_json" (default: "input_json")

• "input_json"

• type: "predicate" (default: "predicate")

• "predicate"

• name: optional string

• Score object { instructions, levels, type, name }

• instructions: string or array of DecisionInputText or InputImage { image_url, type, detail } or InputJSON { data, type }

• string

• array of DecisionInputText or InputImage { image_url, type, detail } or InputJSON { data, type }

minItems: 1

• DecisionInputText object { text, type }

• InputImage object { image_url, type, detail }

• image_url: string

采用 Base64 编码的图像 data URL，或可公开访问的 HTTP(S) 图像 URL。

pattern: ^(data:|https?://), maxLength: 20971520

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

• "input_image"

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

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

• "low"

• "high"

• "auto"

• "original"

• InputJSON object { data, type }

• data: map[unknown] or array of map[unknown]

• LiveDecisionJSONObject = map[unknown]

• array of map[unknown]

• type: "input_json" (default: "input_json")

• "input_json"

• levels: array of object { label, description }

minItems: 2, maxItems: 10

• label: string

• description: optional string

• type: "score" (default: "score")

• "score"

• name: optional string

• type: "decisions" (default: "decisions")

• "decisions"

• acknowledgement_delay_ms: optional integer

从委派任务发出到请求自动语音确认的等待时长，单位为毫秒。模型仍可能在等待结束前发言。向会话追加任何说明（commentary）或思考（thinking）都会取消所有待处理的确认，包括其他委派任务的确认。默认为 400；更新仅作用于后续委派。

minimum: 0, maximum: 800

• input: optional array of InitialItem

启动前提供的有序纯文本历史记录。支持 developer、user 和 assistant 消息，每条消息包含一个文本部分；最多 128 条消息，并受配置的渲染后词元数量上限约束，默认上限为 8,192。

maxItems: 128

• Developer object { content, role, id, 2 more }

包含在 Live 会话初始文本历史记录中的开发者消息。

• content: array of object { text, type }

消息内容。Live 初始对话历史记录中的每条消息须恰好提供一个文本部分。

minItems: 1, maxItems: 1

• text: string

要包含在 Live 会话初始对话历史记录中的消息文本。

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

文本内容类型，固定为 input_text。

• "input_text"

• role: "developer" (default: "developer")

此历史消息的作者，固定为 developer。

• "developer"

• id: optional string or null

所提供历史消息的可选标识。Live 使用消息的角色和文本初始化对话。

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

所提供消息的状态。Live 将其文本作为历史记录，不会恢复未完成的消息。

• "incomplete"

• "completed"

• type: optional "message" (default: "message")

历史记录条目的类型，固定为 message。

• "message"

• User object { content, role, id, 2 more }

包含在 Live 会话初始文本历史记录中的用户消息。

• content: array of object { text, type }

消息内容。Live 初始对话历史记录中的每条消息须恰好提供一个文本部分。

minItems: 1, maxItems: 1

• text: string

要包含在 Live 会话初始对话历史记录中的消息文本。

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

文本内容类型，固定为 input_text。

• "input_text"

• role: "user" (default: "user")

此历史消息的作者，固定为 user。

• "user"

• id: optional string or null

所提供历史消息的可选标识。Live 使用消息的角色和文本初始化对话。

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

所提供消息的状态。Live 将其文本作为历史记录，不会恢复未完成的消息。

• "incomplete"

• "completed"

• type: optional "message" (default: "message")

历史记录条目的类型，固定为 message。

• "message"

• Assistant object { content, role, id, 2 more }

包含在 Live 会话初始文本历史记录中的助手消息。

• content: array of Text { text, type } or OutputText { text, type }

消息内容。Live 初始对话历史记录中的每条消息须恰好提供一个文本部分。

minItems: 1, maxItems: 1

• Text object { text, type }

启动 Live 会话时作为对话历史记录提供的助手文本。

• text: string

要包含在 Live 会话初始对话历史记录中的消息文本。

• type: optional "text" (default: "text")

文本内容类型，固定为 text。

• "text"

• OutputText object { text, type }

启动 Live 会话时作为对话历史记录提供的助手输出文本。

• text: string

要包含在 Live 会话初始对话历史记录中的消息文本。

• type: "output_text" (default: "output_text")

文本内容类型，固定为 output_text。

• "output_text"

• role: "assistant" (default: "assistant")

此历史消息的作者，固定为 assistant。

• "assistant"

• id: optional string or null

所提供历史消息的可选标识。Live 使用消息的角色和文本初始化对话。

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

所提供消息的状态。Live 将其文本作为历史记录，不会恢复未完成的消息。

• "incomplete"

• "completed"

• type: optional "message" (default: "message")

历史记录条目的类型，固定为 message。

• "message"

• instructions: optional string or null

关于音色、对话、打断及何时委派任务的前端指令。先阅读 Live 提示词指南；将业务规则和工具工作流程放在单独的后端提示词中。客户端提供的指令最多 16,384 个词元。省略或提供空白指令时使用服务端默认值。启动后不能更改。

• safety_identifier: optional string or null

最终用户的稳定标识，用于安全监控和滥用检测。

maxLength: 128

• store: optional boolean

是否保存会话，以便之后分叉和下载录音。新会话默认为 false。

• triggers: optional array of DecisionTrigger

每种转录事件类型最多配置一个 Decisions 触发器。触发器独立于任务委派运行。更新时省略 triggers 会保留当前配置，发送列表会替换配置，发送空列表会禁用触发器。

maxItems: 2

• decisions: object { questions }

使用当前转录文本与会话共享的 Decision 条目进行求值的问题。

• questions: array of DecisionQuestion

按顺序一起求值的原生 Decision API 问题。

minItems: 1, maxItems: 64

• Choice object { choices, instructions, type, name }

• Predicate object { instructions, type, name }

• Score object { instructions, levels, type, name }

• event_type: "session.input_transcript.delta" or "session.output_transcript.delta"

• "session.input_transcript.delta"

• "session.output_transcript.delta"

• type: "decisions" (default: "decisions")

• "decisions"

• type: "session.started" (default: "session.started")

事件类型，固定为 session.started。

• "session.started"

• client_event_id: optional string

与此服务端事件关联的客户端命令的 event_id，如已提供。

示例

{
  "type": "session.started",
  "event_id": "evt_started_001",
  "client_event_id": "evt_start_001",
  "session": {
    "id": "live_abc123",
    "model": "gpt-live-1",
    "status": "active",
    "expires_at": 1788555600,
    "instructions": "帮助来电者安排餐厅预订，预订前确认细节。",
    "input": [],
    "audio": {
      "format": {
        "type": "audio/pcm",
        "rate": 24000
      },
      "output": {
        "voice": "marin"
      }
    },
    "delegation": {
      "type": "client"
    }
  }
}

session.updated

Live 会话更新获接受后返回，包含更新后解析生效的会话配置。

模式定义

模式名称：LiveSessionUpdated

• event_id: string

Live 服务端事件的唯一 ID。

• session: SessionResource

解析生效后的 Live 会话配置，以及服务端分配的会话元数据。

• id: string

Live 会话的唯一 ID，用于旁路连接、分叉和下载录音。

• expires_at: integer

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

• model: string or "gpt-live-1"

Live 模型。无论采用哪种传输方式，均须在会话配置中指定；不要通过 URL 查询参数传入。

• string

minLength: 1

• "gpt-live-1"

Live 模型。无论采用哪种传输方式，均须在会话配置中指定；不要通过 URL 查询参数传入。

• "gpt-live-1"

• status: "active" (default: "active")

会话快照的状态，始终为 active，包括 session.closed 中的最终快照；须通过事件类型判断会话已关闭。

• "active"

• audio: optional object { format, output }

启动时的音频配置。只有主 WebSocket 接受 audio.format；WebRTC 和 SIP 协商媒体格式。音色与格式在启动后不可更改。

• format: optional AudioFormat

Live WebSocket 连接收发音频的编码与采样率。WebRTC 和 SIP 单独协商媒体格式。

• AudioPCM object { rate, type }

Live WebSocket 连接的原始单声道、16 位小端序 PCM 音频。

• rate: 16000 or 24000

音频采样率，单位为 Hz。Live WebSocket 的 PCM 音频支持 16000 或 24000 Hz。

minimum: 16000, maximum: 24000

• 16000

• 24000

• type: "audio/pcm" (default: "audio/pcm")

音频编码，固定为 audio/pcm。

• "audio/pcm"

• AudioPCMU object { rate, type }

Live WebSocket 连接的原始单声道 G.711 μ-law 音频。

• rate: integer

音频采样率，单位为 Hz。G.711 音频使用 8000 Hz。

minimum: 8000, maximum: 8000

• type: "audio/pcmu" (default: "audio/pcmu")

音频编码，固定为 audio/pcmu。

• "audio/pcmu"

• AudioPCMA object { rate, type }

Live WebSocket 连接的原始单声道 G.711 A-law 音频。

• rate: integer

音频采样率，单位为 Hz。G.711 音频使用 8000 Hz。

minimum: 8000, maximum: 8000

• type: "audio/pcma" (default: "audio/pcma")

音频编码，固定为 audio/pcma。

• "audio/pcma"

• output: optional object { voice }

Live 模型生成语音使用的音色。

• voice: optional string or "alloy" or "ash" or "ballad" or 35 more or CustomVoice

Live 语音使用的音色，可以是内置音色名称，也可以是包含 ID 的自定义音色对象。默认为 marin，启动后不能更改。

• string

• "alloy" or "ash" or "ballad" or 35 more

Live 语音使用的音色，可以是内置音色名称，也可以是包含 ID 的自定义音色对象。默认为 marin，启动后不能更改。

• "alloy"

• "ash"

• "ballad"

• "beacon"

• "bossa"

• "brise"

• "calandria"

• "cedar"

• "cinder"

• "compas"

• "coral"

• "delta"

• "destello"

• "echo"

• "flitz"

• "gleam"

• "halo"

• "harema"

• "hornero"

• "juni"

• "luciernaga"

• "marin"

• "meridian"

• "nira"

• "noeul"

• "nuri"

• "pearl"

• "quartz"

• "ripple"

• "sage"

• "shida"

• "shimmer"

• "sillage"

• "stone"

• "tempo"

• "verse"

• "vesper"

• "willow"

• CustomVoice object { id }

• id: string

minLength: 1, maxLength: 128

• client: optional ClientConfig

仅在启动时设置的能力权限，适用于连接到统一 WebRTC 会话的不可信前端，不影响可信的旁路连接。

• data_channel: DataChannelConfig

WebRTC 前端数据通道的客户端与服务端事件权限。

• allowed_client_events: optional "all" or array of string

前端数据通道可发送的客户端事件类型。使用 'all' 允许所有客户端事件，空数组表示全部禁止。省略时保留原有的全部允许行为。

• "all"

• "all"

• array of string

maxItems: 256

• allowed_server_events: optional "all" or array of ServerEventSelector

可发送到前端数据通道的服务端事件。使用 'all' 允许所有服务端事件，空数组表示全部禁止。省略时保留原有的全部允许行为。Responses 事件通过包含 type 'response.event' 和 response_event 选择器的对象指定。

• "all"

• "all"

• array of ServerEventSelector

maxItems: 256

• type: string

外层 Live 服务端事件类型。对于 Responses 事件，使用 'response.event'。

minLength: 1, maxLength: 256

• response_event: optional string

内嵌的 Responses 事件类型。type 为 'response.event' 时必填；其他事件类型禁止使用此字段。

minLength: 1, maxLength: 256

• delegation: optional ClientDelegation or Responses { responses, type, acknowledgement_delay_ms } or Decisions { decisions, type, acknowledgement_delay_ms } or null

Live 模型委派任务的处理方。省略或设为 null 时，由你的应用处理；使用 responses 或 decisions，可委派给对应 API。

• ClientDelegation object { type, acknowledgement_delay_ms }

将任务委派给你的应用。Live 会话发出委派事件，由你的后端处理。

• type: "client" (default: "client")

委派任务的处理方。由你的应用处理时固定为 client。

• "client"

• acknowledgement_delay_ms: optional integer

从委派任务发出到请求自动语音确认的等待时长，单位为毫秒。模型仍可能在等待结束前发言。向会话追加任何说明（commentary）或思考（thinking）都会取消所有待处理的确认，包括其他委派任务的确认。Decisions 会话默认为 400，其他会话默认为 0，即立即请求。更新会话时省略此项会保留当前值；更新仅作用于后续委派。

minimum: 0, maximum: 800

• Responses object { responses, type, acknowledgement_delay_ms }

将任务委派给由 Live 会话管理的 Responses 模型。

• responses: ResponsesDelegationConfig

Live 会话将任务委派给 Responses 时所使用的后端模型、提示词和工具。

• model: string

服务端管理的 Responses 委派使用的模型。

• instructions: optional string or null

交给被委派的 Responses 模型的指令，与 Live 指令分开设置。参阅后端提示词。

• max_output_tokens: optional integer or null

每次委派响应的最大输出词元数。

minimum: 16

• parallel_tool_calls: optional boolean or null

被委派的 Responses 模型能否在单次响应中请求多个工具调用。

• reasoning: optional object { effort, summary } or null

传给每次委派 Responses 请求的推理配置。

• effort: optional "none" or "minimal" or "low" or 3 more or null

被委派的 Responses 模型使用的推理强度。支持的值取决于后端模型。

• "none"

• "minimal"

• "low"

• "medium"

• "high"

• "xhigh"

• summary: optional "concise" or "detailed" or "auto" or null

向被委派的 Responses 模型请求的推理摘要类型，须模型支持。

• "concise"

• "detailed"

• "auto"

• service_tier: optional "auto" or "default" or "fast_tier_temp_pilot" or 3 more or null

委派 Responses 请求使用的服务层级。

• "auto"

• "default"

• "fast_tier_temp_pilot"

• "flex"

• "priority"

• "ultrafast"

• text: optional object { verbosity } or null

传给每次委派 Responses 请求的文本生成配置。

• verbosity: optional "low" or "medium" or "high" or null

Responses 后端生成文本的详细程度，此项不配置 Live 模型的口头表达方式。

• "low"

• "medium"

• "high"

• tool_choice: optional "auto" or "none" or "required" or Function { name, type } or Mcp { server_label, type, name } or 11 more

控制 Responses 后端在处理 Live 模型委派的任务时使用哪个工具。

• LiveToolChoiceEnum = "auto" or "none" or "required"

• "auto"

• "none"

• "required"

• Function object { name, type }

• name: string

要调用的函数工具名称。

• type: "function" (default: "function")

要调用的工具，固定为 function。

• "function"

• Mcp object { server_label, type, name }

• server_label: string

要调用的 MCP 服务器标签。

• type: "mcp" (default: "mcp")

要调用的工具，固定为 mcp。

• "mcp"

• name: optional string or null

要调用的 MCP 工具名称。省略时，服务器可选择默认工具。

• FileSearch object { type }

• type: "file_search" (default: "file_search")

要调用的工具，固定为 file_search。

• "file_search"

• WebSearch object { type }

• type: "web_search" (default: "web_search")

要调用的工具，固定为 web_search。

• "web_search"

• WebSearchPreview object { type }

• type: "web_search_preview" (default: "web_search_preview")

要调用的工具，固定为 web_search_preview。

• "web_search_preview"

• ImageGeneration object { type }

• type: "image_generation" (default: "image_generation")

要调用的工具，固定为 image_generation。

• "image_generation"

• Computer object { type }

• type: "computer" (default: "computer")

要调用的工具，固定为 computer。

• "computer"

• CodeInterpreter object { type }

• type: "code_interpreter" (default: "code_interpreter")

要调用的工具，固定为 code_interpreter。

• "code_interpreter"

• ProgrammaticToolCalling object { type }

• type: "programmatic_tool_calling" (default: "programmatic_tool_calling")

要调用的工具，固定为 programmatic_tool_calling。

• "programmatic_tool_calling"

• Shell object { type }

需要调用工具时，强制模型调用 shell 工具。

• type: "shell" (default: "shell")

要调用的工具，固定为 shell。

• "shell"

• Custom object { name, type }

• name: string

要调用的自定义工具名称。

• type: "custom" (default: "custom")

要调用的工具，固定为 custom。

• "custom"

• ApplyPatch object { type }

执行工具调用时，强制模型调用 apply_patch 工具。

• type: "apply_patch" (default: "apply_patch")

要调用的工具，固定为 apply_patch。

• "apply_patch"

• LiveAllowedToolsChoiceParam object { tools, type, mode }

• tools: array of Function { name, type } or Mcp { server_label, type, name } or FileSearch { type } or 9 more

被委派的 Responses 模型可以调用的工具。

minItems: 1, maxItems: 128

• Function object { name, type }

• name: string

要调用的函数工具名称。

• type: "function" (default: "function")

要调用的工具，固定为 function。

• "function"

• Mcp object { server_label, type, name }

• server_label: string

要调用的 MCP 服务器标签。

• type: "mcp" (default: "mcp")

要调用的工具，固定为 mcp。

• "mcp"

• name: optional string or null

要调用的 MCP 工具名称。省略时，服务器可选择默认工具。

• FileSearch object { type }

• type: "file_search" (default: "file_search")

要调用的工具，固定为 file_search。

• "file_search"

• WebSearch object { type }

• type: "web_search" (default: "web_search")

要调用的工具，固定为 web_search。

• "web_search"

• WebSearchPreview object { type }

• type: "web_search_preview" (default: "web_search_preview")

要调用的工具，固定为 web_search_preview。

• "web_search_preview"

• ImageGeneration object { type }

• type: "image_generation" (default: "image_generation")

要调用的工具，固定为 image_generation。

• "image_generation"

• Computer object { type }

• type: "computer" (default: "computer")

要调用的工具，固定为 computer。

• "computer"

• CodeInterpreter object { type }

• type: "code_interpreter" (default: "code_interpreter")

要调用的工具，固定为 code_interpreter。

• "code_interpreter"

• ProgrammaticToolCalling object { type }

• type: "programmatic_tool_calling" (default: "programmatic_tool_calling")

要调用的工具，固定为 programmatic_tool_calling。

• "programmatic_tool_calling"

• Shell object { type }

需要调用工具时，强制模型调用 shell 工具。

• type: "shell" (default: "shell")

要调用的工具，固定为 shell。

• "shell"

• Custom object { name, type }

• name: string

要调用的自定义工具名称。

• type: "custom" (default: "custom")

要调用的工具，固定为 custom。

• "custom"

• ApplyPatch object { type }

执行工具调用时，强制模型调用 apply_patch 工具。

• type: "apply_patch" (default: "apply_patch")

要调用的工具，固定为 apply_patch。

• "apply_patch"

• type: "allowed_tools" (default: "allowed_tools")

工具选择类型，固定为 allowed_tools。

• "allowed_tools"

• mode: optional "none" or "auto" or "required" or null

从允许的工具集合中选择工具的方式。

• "none"

• "auto"

• "required"

• tools: optional array of FunctionTool or WebSearch { type } or FileSearch { type } or 10 more

Responses 后端处理 Live 模型委派的任务时可用的工具。

• FunctionTool object { name, type, description, 2 more }

Live 模型委派任务时，Responses 后端可用的函数工具。

• name: string

被委派的 Responses 模型调用此函数时使用的名称。

• type: "function" (default: "function")

工具类型，固定为 function。

• "function"

• description: optional string or null

函数的用途，以及被委派的 Responses 模型应在何时调用它。

• parameters: optional map[unknown] or null

描述函数可接受参数的 JSON Schema 对象。

• strict: optional boolean or null

被委派的 Responses 模型是否必须严格遵循函数的参数模式。

• WebSearch object { type }

Live 会话的 Responses 后端可用的网页搜索工具。

• type: "web_search" (default: "web_search")

工具类型，固定为 web_search。

• "web_search"

• FileSearch object { type }

• type: "file_search" (default: "file_search")

• "file_search"

• CodeInterpreter object { type }

• type: "code_interpreter" (default: "code_interpreter")

• "code_interpreter"

• Shell object { type, environment }

Responses shell 工具。可使用托管容器，或通过 response.item.create 返回本地 shell 执行结果。不支持域名密钥（domain secrets）。

• type: "shell" (default: "shell")

• "shell"

• environment: optional ContainerAuto { type, file_ids, memory_limit, 2 more } or ContainerReference { container_id, type } or Local { type, skills } or null

• ContainerAuto object { type, file_ids, memory_limit, 2 more }

• type: "container_auto" (default: "container_auto")

为此请求自动创建容器。

• "container_auto"

• file_ids: optional array of string or null

可选的已上传文件列表，这些文件将提供给代码使用。

maxItems: 50

• memory_limit: optional "1g" or "4g" or "16g" or "64g" or null

容器的内存上限。

• "1g"

• "4g"

• "16g"

• "64g"

• network_policy: optional Disabled { type } or Allowlist { allowed_domains, type } or null

容器的网络访问策略。

• Disabled object { type }

• type: "disabled" (default: "disabled")

禁用出站网络访问，固定为 disabled。

• "disabled"

• Allowlist object { allowed_domains, type }

• allowed_domains: array of string

type 为 allowlist 时允许访问的域名列表。

minItems: 1

• type: "allowlist" (default: "allowlist")

仅允许对指定域名发起出站网络访问，固定为 allowlist。

• "allowlist"

• skills: optional array of SkillReference { skill_id, type, version } or Inline { description, name, source, type } or null

可选的技能列表，通过 ID 或内联数据引用技能。

maxItems: 200

• SkillReference object { skill_id, type, version }

• skill_id: string

引用的技能 ID。

minLength: 1, maxLength: 64

• type: "skill_reference" (default: "skill_reference")

引用通过 /v1/skills 接口创建的技能。

• "skill_reference"

• version: optional string or null

可选的技能版本。使用正整数或 'latest'，省略时使用默认版本。

• Inline object { description, name, source, type }

• description: string

技能描述。

• name: string

技能名称。

• source: object { data, media_type, type }

内联技能载荷。

• data: string

采用 Base64 编码的技能 ZIP 包。

minLength: 1, maxLength: 70254592

• media_type: "application/zip" (default: "application/zip")

内联技能载荷的媒体类型，必须为 application/zip。

• "application/zip"

• type: "base64" (default: "base64")

内联技能来源的类型，必须为 base64。

• "base64"

• type: "inline" (default: "inline")

为此请求定义内联技能。

• "inline"

• ContainerReference object { container_id, type }

• container_id: string

引用的容器 ID。

• type: "container_reference" (default: "container_reference")

引用通过 /v1/containers 接口创建的容器。

• "container_reference"

• Local object { type, skills }

• type: "local" (default: "local")

使用本地计算机环境。

• "local"

• skills: optional array of object { description, name, path } or null

可选的技能列表。

maxItems: 200

• description: string

技能描述。

• name: string

技能名称。

• path: string

包含该技能的目录路径。

• ImageGeneration object { type }

• type: "image_generation" (default: "image_generation")

• "image_generation"

• Mcp object { type }

• type: "mcp" (default: "mcp")

• "mcp"

• Custom object { type }

• type: "custom" (default: "custom")

• "custom"

• Namespace object { type }

• type: "namespace" (default: "namespace")

• "namespace"

• ToolSearch object { type }

• type: "tool_search" (default: "tool_search")

• "tool_search"

• ProgrammaticToolCalling object { type }

• type: "programmatic_tool_calling" (default: "programmatic_tool_calling")

• "programmatic_tool_calling"

• Computer object { type }

• type: "computer" (default: "computer")

• "computer"

• ApplyPatch object { type }

• type: "apply_patch" (default: "apply_patch")

• "apply_patch"

• type: "responses" (default: "responses")

委派任务的处理方。由 Responses API 处理任务时固定为 responses。

• "responses"

• acknowledgement_delay_ms: optional integer

从委派任务发出到请求自动语音确认的等待时长，单位为毫秒。模型仍可能在等待结束前发言。向会话追加任何说明（commentary）或思考（thinking）都会取消所有待处理的确认，包括其他委派任务的确认。Decisions 会话默认为 400，其他会话默认为 0，即立即请求。更新会话时省略此项会保留当前值；更新仅作用于后续委派。

minimum: 0, maximum: 800

• Decisions object { decisions, type, acknowledgement_delay_ms }

• decisions: DecisionsDelegationConfig

• model: string

minLength: 1

• questions: array of DecisionQuestion

按顺序一起求值的原生 Decision API 问题。

minItems: 1, maxItems: 64

• Choice object { choices, instructions, type, name }

• choices: array of DecisionChoiceOption

minItems: 2, maxItems: 255

• value: string or boolean

• string

• boolean

• description: optional string

• instructions: string or array of DecisionInputText or InputImage { image_url, type, detail } or InputJSON { data, type }

• string

• array of DecisionInputText or InputImage { image_url, type, detail } or InputJSON { data, type }

minItems: 1

• DecisionInputText object { text, type }

• text: string

输入模型的文本。

maxLength: 10485760

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

• "input_text"

• InputImage object { image_url, type, detail }

• image_url: string

采用 Base64 编码的图像 data URL，或可公开访问的 HTTP(S) 图像 URL。

pattern: ^(data:|https?://), maxLength: 20971520

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

• "input_image"

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

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

• "low"

• "high"

• "auto"

• "original"

• InputJSON object { data, type }

• data: map[unknown] or array of map[unknown]

• LiveDecisionJSONObject = map[unknown]

• array of map[unknown]

• type: "input_json" (default: "input_json")

• "input_json"

• type: "choice" (default: "choice")

• "choice"

• name: optional string

• Predicate object { instructions, type, name }

• instructions: string or array of DecisionInputText or InputImage { image_url, type, detail } or InputJSON { data, type }

• string

• array of DecisionInputText or InputImage { image_url, type, detail } or InputJSON { data, type }

minItems: 1

• DecisionInputText object { text, type }

• InputImage object { image_url, type, detail }

• image_url: string

采用 Base64 编码的图像 data URL，或可公开访问的 HTTP(S) 图像 URL。

pattern: ^(data:|https?://), maxLength: 20971520

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

• "input_image"

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

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

• "low"

• "high"

• "auto"

• "original"

• InputJSON object { data, type }

• data: map[unknown] or array of map[unknown]

• LiveDecisionJSONObject = map[unknown]

• array of map[unknown]

• type: "input_json" (default: "input_json")

• "input_json"

• type: "predicate" (default: "predicate")

• "predicate"

• name: optional string

• Score object { instructions, levels, type, name }

• instructions: string or array of DecisionInputText or InputImage { image_url, type, detail } or InputJSON { data, type }

• string

• array of DecisionInputText or InputImage { image_url, type, detail } or InputJSON { data, type }

minItems: 1

• DecisionInputText object { text, type }

• InputImage object { image_url, type, detail }

• image_url: string

采用 Base64 编码的图像 data URL，或可公开访问的 HTTP(S) 图像 URL。

pattern: ^(data:|https?://), maxLength: 20971520

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

• "input_image"

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

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

• "low"

• "high"

• "auto"

• "original"

• InputJSON object { data, type }

• data: map[unknown] or array of map[unknown]

• LiveDecisionJSONObject = map[unknown]

• array of map[unknown]

• type: "input_json" (default: "input_json")

• "input_json"

• levels: array of object { label, description }

minItems: 2, maxItems: 10

• label: string

• description: optional string

• type: "score" (default: "score")

• "score"

• name: optional string

• type: "decisions" (default: "decisions")

• "decisions"

• acknowledgement_delay_ms: optional integer

从委派任务发出到请求自动语音确认的等待时长，单位为毫秒。模型仍可能在等待结束前发言。向会话追加任何说明（commentary）或思考（thinking）都会取消所有待处理的确认，包括其他委派任务的确认。默认为 400；更新仅作用于后续委派。

minimum: 0, maximum: 800

• input: optional array of InitialItem

启动前提供的有序纯文本历史记录。支持 developer、user 和 assistant 消息，每条消息包含一个文本部分；最多 128 条消息，并受配置的渲染后词元数量上限约束，默认上限为 8,192。

maxItems: 128

• Developer object { content, role, id, 2 more }

包含在 Live 会话初始文本历史记录中的开发者消息。

• content: array of object { text, type }

消息内容。Live 初始对话历史记录中的每条消息须恰好提供一个文本部分。

minItems: 1, maxItems: 1

• text: string

要包含在 Live 会话初始对话历史记录中的消息文本。

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

文本内容类型，固定为 input_text。

• "input_text"

• role: "developer" (default: "developer")

此历史消息的作者，固定为 developer。

• "developer"

• id: optional string or null

所提供历史消息的可选标识。Live 使用消息的角色和文本初始化对话。

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

所提供消息的状态。Live 将其文本作为历史记录，不会恢复未完成的消息。

• "incomplete"

• "completed"

• type: optional "message" (default: "message")

历史记录条目的类型，固定为 message。

• "message"

• User object { content, role, id, 2 more }

包含在 Live 会话初始文本历史记录中的用户消息。

• content: array of object { text, type }

消息内容。Live 初始对话历史记录中的每条消息须恰好提供一个文本部分。

minItems: 1, maxItems: 1

• text: string

要包含在 Live 会话初始对话历史记录中的消息文本。

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

文本内容类型，固定为 input_text。

• "input_text"

• role: "user" (default: "user")

此历史消息的作者，固定为 user。

• "user"

• id: optional string or null

所提供历史消息的可选标识。Live 使用消息的角色和文本初始化对话。

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

所提供消息的状态。Live 将其文本作为历史记录，不会恢复未完成的消息。

• "incomplete"

• "completed"

• type: optional "message" (default: "message")

历史记录条目的类型，固定为 message。

• "message"

• Assistant object { content, role, id, 2 more }

包含在 Live 会话初始文本历史记录中的助手消息。

• content: array of Text { text, type } or OutputText { text, type }

消息内容。Live 初始对话历史记录中的每条消息须恰好提供一个文本部分。

minItems: 1, maxItems: 1

• Text object { text, type }

启动 Live 会话时作为对话历史记录提供的助手文本。

• text: string

要包含在 Live 会话初始对话历史记录中的消息文本。

• type: optional "text" (default: "text")

文本内容类型，固定为 text。

• "text"

• OutputText object { text, type }

启动 Live 会话时作为对话历史记录提供的助手输出文本。

• text: string

要包含在 Live 会话初始对话历史记录中的消息文本。

• type: "output_text" (default: "output_text")

文本内容类型，固定为 output_text。

• "output_text"

• role: "assistant" (default: "assistant")

此历史消息的作者，固定为 assistant。

• "assistant"

• id: optional string or null

所提供历史消息的可选标识。Live 使用消息的角色和文本初始化对话。

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

所提供消息的状态。Live 将其文本作为历史记录，不会恢复未完成的消息。

• "incomplete"

• "completed"

• type: optional "message" (default: "message")

历史记录条目的类型，固定为 message。

• "message"

• instructions: optional string or null

关于音色、对话、打断及何时委派任务的前端指令。先阅读 Live 提示词指南；将业务规则和工具工作流程放在单独的后端提示词中。客户端提供的指令最多 16,384 个词元。省略或提供空白指令时使用服务端默认值。启动后不能更改。

• safety_identifier: optional string or null

最终用户的稳定标识，用于安全监控和滥用检测。

maxLength: 128

• store: optional boolean

是否保存会话，以便之后分叉和下载录音。新会话默认为 false。

• triggers: optional array of DecisionTrigger

每种转录事件类型最多配置一个 Decisions 触发器。触发器独立于任务委派运行。更新时省略 triggers 会保留当前配置，发送列表会替换配置，发送空列表会禁用触发器。

maxItems: 2

• decisions: object { questions }

使用当前转录文本与会话共享的 Decision 条目进行求值的问题。

• questions: array of DecisionQuestion

按顺序一起求值的原生 Decision API 问题。

minItems: 1, maxItems: 64

• Choice object { choices, instructions, type, name }

• Predicate object { instructions, type, name }

• Score object { instructions, levels, type, name }

• event_type: "session.input_transcript.delta" or "session.output_transcript.delta"

• "session.input_transcript.delta"

• "session.output_transcript.delta"

• type: "decisions" (default: "decisions")

• "decisions"

• type: "session.updated" (default: "session.updated")

事件类型，固定为 session.updated。

• "session.updated"

• client_event_id: optional string

与此服务端事件关联的客户端命令的 event_id，如已提供。

示例

{
  "type": "session.updated",
  "event_id": "evt_updated_001",
  "client_event_id": "evt_update_001",
  "session": {
    "id": "live_def456",
    "model": "gpt-live-1",
    "status": "active",
    "expires_at": 1788555600,
    "instructions": "帮助来电者安排餐厅预订，预订前确认细节。",
    "input": [],
    "audio": {
      "format": {
        "type": "audio/pcm",
        "rate": 24000
      },
      "output": {
        "voice": "marin"
      }
    },
    "delegation": {
      "type": "responses",
      "responses": {
        "model": "gpt-6-astra",
        "instructions": "查询餐厅是否有位；确认预订前须先询问。",
        "max_output_tokens": 1024,
        "tools": []
      }
    }
  }
}

session.input_audio.muted

确认 session.input_audio.mute 命令。独立的输入静音会向模型发送静音，但保留旁路音频反射。音频片段播放不会发出此事件。

模式定义

模式名称：LiveInputAudioMuted

• event_id: string

Live 服务端事件的唯一 ID。

• type: "session.input_audio.muted" (default: "session.input_audio.muted")

事件类型，固定为 session.input_audio.muted。

• "session.input_audio.muted"

• client_event_id: optional string

与此服务端事件关联的客户端命令的 event_id，如已提供。

示例

{
  "type": "session.input_audio.muted",
  "event_id": "evt_muted_001",
  "client_event_id": "evt_mute_001"
}

session.input_audio.unmuted

确认 session.input_audio.unmute 命令，解除独立输入静音。若音频片段仍在播放，推理继续暂停直至播放结束。音频片段播放不会发出此事件。

模式定义

模式名称：LiveInputAudioUnmuted

• event_id: string

Live 服务端事件的唯一 ID。

• type: "session.input_audio.unmuted" (default: "session.input_audio.unmuted")

事件类型，固定为 session.input_audio.unmuted。

• "session.input_audio.unmuted"

• client_event_id: optional string

与此服务端事件关联的客户端命令的 event_id，如已提供。

示例

{
  "type": "session.input_audio.unmuted",
  "event_id": "evt_unmuted_001",
  "client_event_id": "evt_unmute_001"
}

session.output_audio.fixture.playing

现有播放路径已接受验证后的音频片段。此确认不表示听众收到第一个采样的时间。可选的 client_event_id 回传播放命令的标识。

模式定义

模式名称：LiveOutputAudioFixturePlaying

• event_id: string

Live 服务端事件的唯一 ID。

• type: "session.output_audio.fixture.playing" (default: "session.output_audio.fixture.playing")

• "session.output_audio.fixture.playing"

• client_event_id: optional string

与此服务端事件关联的客户端命令的 event_id，如已提供。

示例

{
  "type": "session.output_audio.fixture.playing",
  "event_id": "evt_playing_001",
  "client_event_id": "evt_play_001"
}

session.output_audio.fixture.played

完整音频片段已从服务端混音器排空，正常推理已恢复。传输缓冲区仍可能有音频，因此此事件不能证明听众端播放已结束。可选的 client_event_id 回传播放命令的标识。取消或失败的播放不会发出此事件。

模式定义

模式名称：LiveOutputAudioFixturePlayed

• event_id: string

Live 服务端事件的唯一 ID。

• type: "session.output_audio.fixture.played" (default: "session.output_audio.fixture.played")

• "session.output_audio.fixture.played"

• client_event_id: optional string

与此服务端事件关联的客户端命令的 event_id，如已提供。

示例

{
  "type": "session.output_audio.fixture.played",
  "event_id": "evt_played_001",
  "client_event_id": "evt_play_001"
}

session.instructions.appended

session.instructions.append 命令被接纳到 Live 会话时间线后返回。此事件确认指令已追加，不保证模型已据此行动。

模式定义

模式名称：LiveInstructionsAppended

• end_ms: integer

此事件在 Live 会话时间线上的结束位置，单位为自会话开始起的毫秒数。对于追加上下文，可以等于 start_ms。

• event_id: string

Live 服务端事件的唯一 ID。

• start_ms: integer

此事件在 Live 会话时间线上的开始位置，单位为自会话开始起的毫秒数。

• type: "session.instructions.appended" (default: "session.instructions.appended")

事件类型，固定为 session.instructions.appended。

• "session.instructions.appended"

• client_event_id: optional string

与此服务端事件关联的客户端命令的 event_id，如已提供。

示例

{
  "type": "session.instructions.appended",
  "event_id": "evt_instructions_002",
  "client_event_id": "evt_instructions_001",
  "start_ms": 1200,
  "end_ms": 1400
}

session.thinking.appended

session.thinking.append 命令被接纳到 Live 会话时间线后返回。此事件确认推理上下文已添加，不保证产生语音输出。

模式定义

模式名称：LiveThinkingAppended

• end_ms: integer

此事件在 Live 会话时间线上的结束位置，单位为自会话开始起的毫秒数。对于追加上下文，可以等于 start_ms。

• event_id: string

Live 服务端事件的唯一 ID。

• start_ms: integer

此事件在 Live 会话时间线上的开始位置，单位为自会话开始起的毫秒数。

• type: "session.thinking.appended" (default: "session.thinking.appended")

事件类型，固定为 session.thinking.appended。

• "session.thinking.appended"

• client_event_id: optional string

与此服务端事件关联的客户端命令的 event_id，如已提供。

示例

{
  "type": "session.thinking.appended",
  "event_id": "evt_thinking_002",
  "client_event_id": "evt_thinking_001",
  "start_ms": 4600,
  "end_ms": 4800
}

session.commentary.appended

session.commentary.append 命令被接纳到 Live 会话时间线后返回。此事件确认可传达上下文已添加，不保证使用确切措辞或音频播放完成。

模式定义

模式名称：LiveCommentaryAppended

• end_ms: integer

此事件在 Live 会话时间线上的结束位置，单位为自会话开始起的毫秒数。对于追加上下文，可以等于 start_ms。

• event_id: string

Live 服务端事件的唯一 ID。

• start_ms: integer

此事件在 Live 会话时间线上的开始位置，单位为自会话开始起的毫秒数。

• type: "session.commentary.appended" (default: "session.commentary.appended")

事件类型，固定为 session.commentary.appended。

• "session.commentary.appended"

• client_event_id: optional string

与此服务端事件关联的客户端命令的 event_id，如已提供。

示例

{
  "type": "session.commentary.appended",
  "event_id": "evt_commentary_002",
  "client_event_id": "evt_commentary_001",
  "start_ms": 5200,
  "end_ms": 5400
}

session.output_audio.delta

Live 模型生成的音频块。按送达顺序，使用会话配置的音频格式解码并播放主 WebSocket 音频块。旁路连接接收带时间戳的反射输出音频。

模式定义

模式名称：LiveOutputAudioDelta

• delta: string

Base64 编码的原始音频。主 WebSocket 事件使用会话配置的格式；旁路反射事件使用 24 kHz 单声道 PCM16LE。

• type: "session.output_audio.delta" (default: "session.output_audio.delta")

事件类型，固定为 session.output_audio.delta。

• "session.output_audio.delta"

• end_ms: optional integer

相对于会话的结束时间，单位为毫秒，不含边界。旁路反射事件必填，主 WebSocket 省略。被丢弃的输出帧会在反射范围之间留下间隙。

• start_ms: optional integer

相对于会话的开始时间，单位为毫秒，含边界。旁路反射事件必填，主 WebSocket 省略。

示例

{
  "type": "session.output_audio.delta",
  "delta": "AACAAIAAAIAAAP9/AIAAgA==",
  "start_ms": 1000,
  "end_ms": 1200
}

session.input_transcript.delta

Live 会话中用户输入音频的转录片段。按送达顺序累积片段；这些事件不定义完整轮次，也不包含转录完成事件。

模式定义

模式名称：LiveInputTranscriptDelta

• delta: string

此时间范围内音频的转录文本片段。按送达顺序追加片段，构建转录文本。

• end_ms: integer

此事件在 Live 会话时间线上的结束位置，单位为自会话开始起的毫秒数。对于追加上下文，可以等于 start_ms。

• event_id: string

Live 服务端事件的唯一 ID。

• start_ms: integer

此事件在 Live 会话时间线上的开始位置，单位为自会话开始起的毫秒数。

• type: "session.input_transcript.delta" (default: "session.input_transcript.delta")

事件类型，固定为 session.input_transcript.delta。

• "session.input_transcript.delta"

• client_event_id: optional string

与此服务端事件关联的客户端命令的 event_id，如已提供。

示例

{
  "type": "session.input_transcript.delta",
  "event_id": "evt_input_transcript_001",
  "delta": "请订一张7点的两人桌。",
  "start_ms": 1600,
  "end_ms": 3400
}

session.output_transcript.delta

Live 会话中助手输出音频的转录片段。按送达顺序累积片段；这些事件不定义完整轮次，也不包含转录完成事件。

模式定义

模式名称：LiveOutputTranscriptDelta

• delta: string

此时间范围内音频的转录文本片段。按送达顺序追加片段，构建转录文本。

• end_ms: integer

此事件在 Live 会话时间线上的结束位置，单位为自会话开始起的毫秒数。对于追加上下文，可以等于 start_ms。

• event_id: string

Live 服务端事件的唯一 ID。

• start_ms: integer

此事件在 Live 会话时间线上的开始位置，单位为自会话开始起的毫秒数。

• type: "session.output_transcript.delta" (default: "session.output_transcript.delta")

事件类型，固定为 session.output_transcript.delta。

• "session.output_transcript.delta"

• client_event_id: optional string

与此服务端事件关联的客户端命令的 event_id，如已提供。

示例

{
  "type": "session.output_transcript.delta",
  "event_id": "evt_output_transcript_001",
  "delta": "需要我预订那张桌子吗？",
  "start_ms": 5400,
  "end_ms": 7200
}

session.delegation.created

Live 模型将工作委派给你的应用、Responses 或 Decisions 时返回，包含委派元数据及委派发生时在会话时间线上的位置。

模式定义

模式名称：LiveDelegationCreated

• delegation: object { id, target, type, response_id }

委派工作的标识及目的地。此对象包含元数据，不包含任务文本。

• id: string

委派的唯一 ID。回应客户端处理的工作或关联后端事件时，将其用作 delegation_id。

• target: "client" or "responses" or "decisions"

Live 模型委派工作的目标：client、responses 或 decisions。

• "client" or "responses" or "decisions"

Live 模型委派工作的目标：client、responses 或 decisions。

• "client"

• "responses"

• "decisions"

• type: "delegation" (default: "delegation")

对象类型，固定为 delegation。

• "delegation"

• response_id: optional string

与 Responses 委派关联的 Responses API 响应的 ID。客户端委派省略此字段。

• event_id: string

Live 服务端事件的唯一 ID。

• offset_ms: integer

委派创建时在 Live 会话时间线上的位置，单位为自会话开始起的毫秒数。

• type: "session.delegation.created" (default: "session.delegation.created")

事件类型，固定为 session.delegation.created。

• "session.delegation.created"

• client_event_id: optional string

与此服务端事件关联的客户端命令的 event_id，如已提供。

示例

{
  "type": "session.delegation.created",
  "event_id": "evt_delegation_001",
  "offset_ms": 3600,
  "delegation": {
    "id": "del_abc123",
    "type": "delegation",
    "target": "client"
  }
}

decision.event

Live 委派或转录触发器的 Decision API 事件。对于触发器，source_event_id 标识导致此次求值的转录增量事件。

模式定义

模式名称：LiveDecisionEvent

• delegation_id: string or null

Live 委派 ID；对于转录触发器，为 null。

• event: object { decision, type }

• decision: Decision

原生 Decision API 响应，包括模型、有序答案及词元用量。

• answers: array of Predicate { name, probability, type } or Choice { choice, confidence, name, 2 more } or Score { confidence, name, probabilities, 2 more } or Refusal { name, type }

按问题顺序排列的答案。任何问题都可能返回拒绝，其余问题仍可得到答案。拒绝包含 type: "refusal" 和问题的 name，未命名时为 null。

minItems: 0, maxItems: 2000

• Predicate object { name, probability, type }

• name: string or null

minLength: 0

• probability: number

• type: "predicate" (default: "predicate")

类型，固定为 predicate。

• "predicate"

• Choice object { choice, confidence, name, 2 more }

• choice: string or boolean

选项值具有类型；文本相同的字符串与布尔值是不同的值。

• string

minLength: 0

• boolean

• confidence: number

• name: string or null

minLength: 0

• probabilities: array of object { probability, value }

minItems: 0, maxItems: 2000

• probability: number

• value: string or boolean

选项值具有类型；文本相同的字符串与布尔值是不同的值。

• string

minLength: 0

• boolean

• type: "choice" (default: "choice")

类型，固定为 choice。

• "choice"

• Score object { confidence, name, probabilities, 2 more }

• confidence: number

• name: string or null

minLength: 0

• probabilities: array of object { label, probability, value }

minItems: 0, maxItems: 2000

• label: string

minLength: 0

• probability: number

• value: integer

format: int64

• score: number

• type: "score" (default: "score")

类型，固定为 score。

• "score"

• Refusal object { name, type }

模型拒绝回答此问题。同一请求中的其他问题仍可得到答案。

• name: string or null

minLength: 0

• type: "refusal" (default: "refusal")

类型，固定为 refusal。

• "refusal"

• model: string

使用的模型。

minLength: 0

• usage: object { input_tokens, input_tokens_details, output_tokens, 2 more }

请求的词元用量。

• input_tokens: integer

format: int64, minimum: -2147483648, maximum: 2147483647

• input_tokens_details: object { cache_write_tokens, cached_tokens }

• cache_write_tokens: integer

format: int64, minimum: -2147483648, maximum: 2147483647

• cached_tokens: integer

format: int64, minimum: -2147483648, maximum: 2147483647

• output_tokens: integer

format: int64, minimum: -2147483648, maximum: 2147483647

• output_tokens_details: object { reasoning_tokens }

• reasoning_tokens: integer

format: int64, minimum: -2147483648, maximum: 2147483647

• total_tokens: integer

format: int64, minimum: -2147483648, maximum: 2147483647

• type: "decision.completed" (default: "decision.completed")

• "decision.completed"

• event_id: string

此 Live 服务端事件的唯一 ID。

• source_event_id: string or null

导致此触发器运行的转录增量事件的 event_id；对于委派，为 null。

• source_event_type: "session.input_transcript.delta" or "session.output_transcript.delta" or null

• "session.input_transcript.delta" or "session.output_transcript.delta"

• "session.input_transcript.delta"

• "session.output_transcript.delta"

• trigger_id: string or null

Live 分配的此次触发运行的 ID；对于委派，为 null。

• type: "decision.event" (default: "decision.event")

• "decision.event"

示例

{
  "type": "decision.event",
  "event_id": "evt_decision_1",
  "delegation_id": "del_abc123",
  "trigger_id": null,
  "source_event_type": null,
  "source_event_id": null,
  "event": {
    "type": "decision.completed",
    "decision": {
      "model": "gpt-6-luna",
      "answers": [
        {
          "type": "predicate",
          "name": "damaged",
          "probability": 0.95
        }
      ],
      "usage": {
        "input_tokens": 42,
        "input_tokens_details": {
          "cached_tokens": 0,
          "cache_write_tokens": 0
        },
        "output_tokens": 0,
        "output_tokens_details": {
          "reasoning_tokens": 0
        },
        "total_tokens": 42
      }
    }
  }
}

decision.item.created

已追加一个供后续决策使用的输入条目。

模式定义

模式名称：LiveDecisionItemCreated

• event_id: string

Live 服务端事件的唯一 ID。

• item: Message { id, content, role, type } or Message { id, content, role, type } or Message { id, content, role, type } or 5 more

• Message object { id, content, role, type }

• id: string

• content: string or array of InputText { text, type } or InputImage { image_url, type, detail } or InputJSON { data, type }

输入模型的文本。

• string

输入模型的文本。

maxLength: 10485760

• array of InputText { text, type } or InputImage { image_url, type, detail } or InputJSON { data, type }

• InputText object { text, type }

• text: string

输入模型的文本。

maxLength: 10485760

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

• "input_text"

• InputImage object { image_url, type, detail }

• image_url: string

采用 Base64 编码的图像 data URL，或可公开访问的 HTTP(S) 图像 URL。

pattern: ^(data:|https?://), maxLength: 20971520

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

• "input_image"

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

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

• "low"

• "high"

• "auto"

• "original"

• InputJSON object { data, type }

• data: map[unknown] or array of map[unknown]

• LiveDecisionJSONObject = map[unknown]

• array of map[unknown]

• type: "input_json" (default: "input_json")

• "input_json"

• role: "user" (default: "user")

消息角色，固定为 user。

• "user"

• type: optional "message" (default: "message")

• "message"

• Message object { id, content, role, type }

• id: string

• content: string or array of DecisionInputText

输入模型的文本。

• string

输入模型的文本。

maxLength: 10485760

• array of DecisionInputText

• text: string

输入模型的文本。

maxLength: 10485760

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

• "input_text"

• role: "developer" (default: "developer")

• "developer"

• type: optional "message" (default: "message")

• "message"

• Message object { id, content, role, type }

• id: string

• content: string or array of DecisionInputText

输入模型的文本。

• string

输入模型的文本。

maxLength: 10485760

• array of DecisionInputText

• text: string

输入模型的文本。

maxLength: 10485760

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

• role: "system" (default: "system")

• "system"

• type: optional "message" (default: "message")

• "message"

• Message object { id, content, role, 2 more }

• id: string

• content: string or array of OutputText { text, type } or Refusal { refusal, type }

输入模型的文本。

• string

输入模型的文本。

maxLength: 10485760

• array of OutputText { text, type } or Refusal { refusal, type }

• OutputText object { text, type }

• text: string

文本内容。

maxLength: 10485760

• type: "output_text" (default: "output_text")

• "output_text"

• Refusal object { refusal, type }

• refusal: string

拒绝文本。

maxLength: 10485760

• type: "refusal" (default: "refusal")

• "refusal"

• role: "assistant" (default: "assistant")

• "assistant"

• phase: optional "commentary" or "final_answer" or null

将 assistant 消息标记为中间说明（commentary）或最终答案（final_answer）。对于 gpt-5.3-codex 及后续此类模型，发送后续请求时须保留并重新发送所有助手消息的 phase，丢弃它可能降低表现。用户消息不使用此字段。

• "commentary"

• "final_answer"

• type: optional "message" (default: "message")

• "message"

• FunctionCall object { id, arguments, call_id, 4 more }

• id: string

• arguments: string

以 JSON 字符串表示的函数参数。

• call_id: string

模型生成的函数工具调用的唯一 ID。

minLength: 1, maxLength: 64

• name: string

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

• type: "function_call" (default: "function_call")

条目类型，固定为 function_call。

• "function_call"

• namespace: optional string or null

要调用的函数所属的命名空间。

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

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

• "in_progress"

• "completed"

• "incomplete"

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

• id: string

• call_id: string

模型生成的函数工具调用的唯一 ID。

minLength: 1, maxLength: 64

• output: string or array of DecisionInputText or InputImage { image_url, type, detail }

输入模型的文本。

• string

输入模型的文本。

maxLength: 10485760

• array of DecisionInputText or InputImage { image_url, type, detail }

• DecisionInputText object { text, type }

• text: string

输入模型的文本。

maxLength: 10485760

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

• InputImage object { image_url, type, detail }

• image_url: string

采用 Base64 编码的图像 data URL，或可公开访问的 HTTP(S) 图像 URL。

pattern: ^(data:|https?://), maxLength: 20971520

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

• "input_image"

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

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

• "low"

• "high"

• "auto"

• "original"

• type: "function_call_output" (default: "function_call_output")

类型，固定为 function_call_output。

• "function_call_output"

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

• "in_progress"

• "completed"

• "incomplete"

• CustomToolCall object { id, call_id, input, 4 more }

• id: string

• call_id: string

模型生成的函数工具调用的唯一 ID。

minLength: 1, maxLength: 64

• input: string

自定义工具调用的输入。

• name: string

要调用的自定义工具名称。

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

• type: "custom_tool_call" (default: "custom_tool_call")

条目类型，固定为 custom_tool_call。

• "custom_tool_call"

• namespace: optional string or null

要调用的函数所属的命名空间。

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

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

• "in_progress"

• "completed"

• "incomplete"

• CustomToolCallOutput object { id, call_id, output, 2 more }

• id: string

• call_id: string

模型生成的函数工具调用的唯一 ID。

minLength: 1, maxLength: 64

• output: string or array of DecisionInputText or InputImage { image_url, type, detail }

输入模型的文本。

• string

输入模型的文本。

maxLength: 10485760

• array of DecisionInputText or InputImage { image_url, type, detail }

• DecisionInputText object { text, type }

• InputImage object { image_url, type, detail }

• image_url: string

采用 Base64 编码的图像 data URL，或可公开访问的 HTTP(S) 图像 URL。

pattern: ^(data:|https?://), maxLength: 20971520

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

• "input_image"

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

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

• "low"

• "high"

• "auto"

• "original"

• type: "custom_tool_call_output" (default: "custom_tool_call_output")

• "custom_tool_call_output"

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

• "in_progress"

• "completed"

• "incomplete"

• type: "decision.item.created" (default: "decision.item.created")

• "decision.item.created"

• client_event_id: optional string

与此服务端事件关联的客户端命令的 event_id，如已提供。

示例

{
  "type": "decision.item.created",
  "event_id": "evt_item_1",
  "client_event_id": "browser_1",
  "item": {
    "id": "msg_browser_1",
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "维基百科已打开。"
      }
    ]
  }
}

decision.item.deleted

已移除一个供后续决策使用的输入条目。

模式定义

模式名称：LiveDecisionItemDeleted

• event_id: string

Live 服务端事件的唯一 ID。

• item_id: string

• type: "decision.item.deleted" (default: "decision.item.deleted")

• "decision.item.deleted"

• client_event_id: optional string

与此服务端事件关联的客户端命令的 event_id，如已提供。

示例

{
  "type": "decision.item.deleted",
  "event_id": "evt_item_deleted_1",
  "client_event_id": "remove_browser_1",
  "item_id": "msg_browser_1"
}

response.event

Live 会话委派的后端发出的流式 Responses API 事件。使用外层 delegation_id，将内嵌流与相应 Live 委派关联。

模式定义

模式名称：LiveResponseEvent

• event: map[unknown]

内嵌的 Responses 流式事件，按其 type 字段分派处理。响应生命周期快照省略 input，并清空 instructions、tools 和 output 以减小消息；须消费细粒度输出事件获取生成内容。

• event_id: string

Live 服务端事件的唯一 ID。

• type: "response.event" (default: "response.event")

事件类型，固定为 response.event。

• "response.event"

• client_event_id: optional string

与此服务端事件关联的客户端命令的 event_id，如已提供。

• delegation_id: optional string or null

与内嵌 Responses 事件关联的 Live 委派。无法关联委派时，可能为 null 或省略。

示例

{
  "type": "response.event",
  "event_id": "evt_response_002",
  "delegation_id": "del_responses123",
  "event": {
    "type": "response.output_text.delta",
    "item_id": "msg_abc123",
    "output_index": 0,
    "content_index": 0,
    "delta": "晚上7点有室外座位。",
    "sequence_number": 3,
    "logprobs": []
  }
}

session.usage.updated

报告累计 Live 音频用量，以及可用时最近的上下文窗口用量。被委派的 Responses 词元用量在 response.event 事件中单独报告。

模式定义

模式名称：LiveSessionUsageUpdated

• event_id: string

Live 服务端事件的唯一 ID。

• type: "session.usage.updated" (default: "session.usage.updated")

事件类型，固定为 session.usage.updated。

• "session.usage.updated"

• usage: SessionUsage

到目前为止的累计 Live 音频用量。

• seconds: number

累计 Live 音频时长，单位为秒。不要将多个用量事件中的此值相加。

• client_event_id: optional string

与此服务端事件关联的客户端命令的 event_id，如已提供。

• context_window: optional object { usage_ratio }

最近一次测得的 Live 上下文窗口用量。上下文上限未知时省略。

• usage_ratio: number

最近的活动上下文词元数除以 Live 模型的上下文上限。压缩后可能下降，也可能滞后于已测量的音频帧。

示例

{
  "type": "session.usage.updated",
  "event_id": "evt_usage_001",
  "usage": {
    "seconds": 32.5
  },
  "context_window": {
    "usage_ratio": 0.12
  }
}

session.closed

Live 会话完成收尾后返回，包含关闭原因、最终会话快照及累计音频用量。如果连接关闭但未收到此事件，不能确认收尾已成功完成。

模式定义

模式名称：LiveSessionClosed

• event_id: string

Live 服务端事件的唯一 ID。

• reason: "close_requested" or "expired" or "content" or 2 more

Live 会话结束原因：close_requested 表示应用请求关闭或挂断，expired 表示达到会话时长上限，content 表示安全过滤，remote_hangup 表示远端正常断开，connection_lost 表示主连接或上游意外断开。

• "close_requested" or "expired" or "content" or 2 more

Live 会话结束原因：close_requested 表示应用请求关闭或挂断，expired 表示达到会话时长上限，content 表示安全过滤，remote_hangup 表示远端正常断开，connection_lost 表示主连接或上游意外断开。

• "close_requested"

• "expired"

• "content"

• "remote_hangup"

• "connection_lost"

• session: SessionResource

解析生效后的 Live 会话配置，以及服务端分配的会话元数据。

• id: string

Live 会话的唯一 ID，用于旁路连接、分叉和下载录音。

• expires_at: integer

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

• model: string or "gpt-live-1"

Live 模型。无论采用哪种传输方式，均须在会话配置中指定；不要通过 URL 查询参数传入。

• string

minLength: 1

• "gpt-live-1"

Live 模型。无论采用哪种传输方式，均须在会话配置中指定；不要通过 URL 查询参数传入。

• "gpt-live-1"

• status: "active" (default: "active")

会话快照的状态，始终为 active，包括 session.closed 中的最终快照；须通过事件类型判断会话已关闭。

• "active"

• audio: optional object { format, output }

启动时的音频配置。只有主 WebSocket 接受 audio.format；WebRTC 和 SIP 协商媒体格式。音色与格式在启动后不可更改。

• format: optional AudioFormat

Live WebSocket 连接收发音频的编码与采样率。WebRTC 和 SIP 单独协商媒体格式。

• AudioPCM object { rate, type }

Live WebSocket 连接的原始单声道、16 位小端序 PCM 音频。

• rate: 16000 or 24000

音频采样率，单位为 Hz。Live WebSocket 的 PCM 音频支持 16000 或 24000 Hz。

minimum: 16000, maximum: 24000

• 16000

• 24000

• type: "audio/pcm" (default: "audio/pcm")

音频编码，固定为 audio/pcm。

• "audio/pcm"

• AudioPCMU object { rate, type }

Live WebSocket 连接的原始单声道 G.711 μ-law 音频。

• rate: integer

音频采样率，单位为 Hz。G.711 音频使用 8000 Hz。

minimum: 8000, maximum: 8000

• type: "audio/pcmu" (default: "audio/pcmu")

音频编码，固定为 audio/pcmu。

• "audio/pcmu"

• AudioPCMA object { rate, type }

Live WebSocket 连接的原始单声道 G.711 A-law 音频。

• rate: integer

音频采样率，单位为 Hz。G.711 音频使用 8000 Hz。

minimum: 8000, maximum: 8000

• type: "audio/pcma" (default: "audio/pcma")

音频编码，固定为 audio/pcma。

• "audio/pcma"

• output: optional object { voice }

Live 模型生成语音使用的音色。

• voice: optional string or "alloy" or "ash" or "ballad" or 35 more or CustomVoice

Live 语音使用的音色，可以是内置音色名称，也可以是包含 ID 的自定义音色对象。默认为 marin，启动后不能更改。

• string

• "alloy" or "ash" or "ballad" or 35 more

Live 语音使用的音色，可以是内置音色名称，也可以是包含 ID 的自定义音色对象。默认为 marin，启动后不能更改。

• "alloy"

• "ash"

• "ballad"

• "beacon"

• "bossa"

• "brise"

• "calandria"

• "cedar"

• "cinder"

• "compas"

• "coral"

• "delta"

• "destello"

• "echo"

• "flitz"

• "gleam"

• "halo"

• "harema"

• "hornero"

• "juni"

• "luciernaga"

• "marin"

• "meridian"

• "nira"

• "noeul"

• "nuri"

• "pearl"

• "quartz"

• "ripple"

• "sage"

• "shida"

• "shimmer"

• "sillage"

• "stone"

• "tempo"

• "verse"

• "vesper"

• "willow"

• CustomVoice object { id }

• id: string

minLength: 1, maxLength: 128

• client: optional ClientConfig

仅在启动时设置的能力权限，适用于连接到统一 WebRTC 会话的不可信前端，不影响可信的旁路连接。

• data_channel: DataChannelConfig

WebRTC 前端数据通道的客户端与服务端事件权限。

• allowed_client_events: optional "all" or array of string

前端数据通道可发送的客户端事件类型。使用 'all' 允许所有客户端事件，空数组表示全部禁止。省略时保留原有的全部允许行为。

• "all"

• "all"

• array of string

maxItems: 256

• allowed_server_events: optional "all" or array of ServerEventSelector

可发送到前端数据通道的服务端事件。使用 'all' 允许所有服务端事件，空数组表示全部禁止。省略时保留原有的全部允许行为。Responses 事件通过包含 type 'response.event' 和 response_event 选择器的对象指定。

• "all"

• "all"

• array of ServerEventSelector

maxItems: 256

• type: string

外层 Live 服务端事件类型。对于 Responses 事件，使用 'response.event'。

minLength: 1, maxLength: 256

• response_event: optional string

内嵌的 Responses 事件类型。type 为 'response.event' 时必填；其他事件类型禁止使用此字段。

minLength: 1, maxLength: 256

• delegation: optional ClientDelegation or Responses { responses, type, acknowledgement_delay_ms } or Decisions { decisions, type, acknowledgement_delay_ms } or null

Live 模型委派任务的处理方。省略或设为 null 时，由你的应用处理；使用 responses 或 decisions，可委派给对应 API。

• ClientDelegation object { type, acknowledgement_delay_ms }

将任务委派给你的应用。Live 会话发出委派事件，由你的后端处理。

• type: "client" (default: "client")

委派任务的处理方。由你的应用处理时固定为 client。

• "client"

• acknowledgement_delay_ms: optional integer

从委派任务发出到请求自动语音确认的等待时长，单位为毫秒。模型仍可能在等待结束前发言。向会话追加任何说明（commentary）或思考（thinking）都会取消所有待处理的确认，包括其他委派任务的确认。Decisions 会话默认为 400，其他会话默认为 0，即立即请求。更新会话时省略此项会保留当前值；更新仅作用于后续委派。

minimum: 0, maximum: 800

• Responses object { responses, type, acknowledgement_delay_ms }

将任务委派给由 Live 会话管理的 Responses 模型。

• responses: ResponsesDelegationConfig

Live 会话将任务委派给 Responses 时所使用的后端模型、提示词和工具。

• model: string

服务端管理的 Responses 委派使用的模型。

• instructions: optional string or null

交给被委派的 Responses 模型的指令，与 Live 指令分开设置。参阅后端提示词。

• max_output_tokens: optional integer or null

每次委派响应的最大输出词元数。

minimum: 16

• parallel_tool_calls: optional boolean or null

被委派的 Responses 模型能否在单次响应中请求多个工具调用。

• reasoning: optional object { effort, summary } or null

传给每次委派 Responses 请求的推理配置。

• effort: optional "none" or "minimal" or "low" or 3 more or null

被委派的 Responses 模型使用的推理强度。支持的值取决于后端模型。

• "none"

• "minimal"

• "low"

• "medium"

• "high"

• "xhigh"

• summary: optional "concise" or "detailed" or "auto" or null

向被委派的 Responses 模型请求的推理摘要类型，须模型支持。

• "concise"

• "detailed"

• "auto"

• service_tier: optional "auto" or "default" or "fast_tier_temp_pilot" or 3 more or null

委派 Responses 请求使用的服务层级。

• "auto"

• "default"

• "fast_tier_temp_pilot"

• "flex"

• "priority"

• "ultrafast"

• text: optional object { verbosity } or null

传给每次委派 Responses 请求的文本生成配置。

• verbosity: optional "low" or "medium" or "high" or null

Responses 后端生成文本的详细程度，此项不配置 Live 模型的口头表达方式。

• "low"

• "medium"

• "high"

• tool_choice: optional "auto" or "none" or "required" or Function { name, type } or Mcp { server_label, type, name } or 11 more

控制 Responses 后端在处理 Live 模型委派的任务时使用哪个工具。

• LiveToolChoiceEnum = "auto" or "none" or "required"

• "auto"

• "none"

• "required"

• Function object { name, type }

• name: string

要调用的函数工具名称。

• type: "function" (default: "function")

要调用的工具，固定为 function。

• "function"

• Mcp object { server_label, type, name }

• server_label: string

要调用的 MCP 服务器标签。

• type: "mcp" (default: "mcp")

要调用的工具，固定为 mcp。

• "mcp"

• name: optional string or null

要调用的 MCP 工具名称。省略时，服务器可选择默认工具。

• FileSearch object { type }

• type: "file_search" (default: "file_search")

要调用的工具，固定为 file_search。

• "file_search"

• WebSearch object { type }

• type: "web_search" (default: "web_search")

要调用的工具，固定为 web_search。

• "web_search"

• WebSearchPreview object { type }

• type: "web_search_preview" (default: "web_search_preview")

要调用的工具，固定为 web_search_preview。

• "web_search_preview"

• ImageGeneration object { type }

• type: "image_generation" (default: "image_generation")

要调用的工具，固定为 image_generation。

• "image_generation"

• Computer object { type }

• type: "computer" (default: "computer")

要调用的工具，固定为 computer。

• "computer"

• CodeInterpreter object { type }

• type: "code_interpreter" (default: "code_interpreter")

要调用的工具，固定为 code_interpreter。

• "code_interpreter"

• ProgrammaticToolCalling object { type }

• type: "programmatic_tool_calling" (default: "programmatic_tool_calling")

要调用的工具，固定为 programmatic_tool_calling。

• "programmatic_tool_calling"

• Shell object { type }

需要调用工具时，强制模型调用 shell 工具。

• type: "shell" (default: "shell")

要调用的工具，固定为 shell。

• "shell"

• Custom object { name, type }

• name: string

要调用的自定义工具名称。

• type: "custom" (default: "custom")

要调用的工具，固定为 custom。

• "custom"

• ApplyPatch object { type }

执行工具调用时，强制模型调用 apply_patch 工具。

• type: "apply_patch" (default: "apply_patch")

要调用的工具，固定为 apply_patch。

• "apply_patch"

• LiveAllowedToolsChoiceParam object { tools, type, mode }

• tools: array of Function { name, type } or Mcp { server_label, type, name } or FileSearch { type } or 9 more

被委派的 Responses 模型可以调用的工具。

minItems: 1, maxItems: 128

• Function object { name, type }

• name: string

要调用的函数工具名称。

• type: "function" (default: "function")

要调用的工具，固定为 function。

• "function"

• Mcp object { server_label, type, name }

• server_label: string

要调用的 MCP 服务器标签。

• type: "mcp" (default: "mcp")

要调用的工具，固定为 mcp。

• "mcp"

• name: optional string or null

要调用的 MCP 工具名称。省略时，服务器可选择默认工具。

• FileSearch object { type }

• type: "file_search" (default: "file_search")

要调用的工具，固定为 file_search。

• "file_search"

• WebSearch object { type }

• type: "web_search" (default: "web_search")

要调用的工具，固定为 web_search。

• "web_search"

• WebSearchPreview object { type }

• type: "web_search_preview" (default: "web_search_preview")

要调用的工具，固定为 web_search_preview。

• "web_search_preview"

• ImageGeneration object { type }

• type: "image_generation" (default: "image_generation")

要调用的工具，固定为 image_generation。

• "image_generation"

• Computer object { type }

• type: "computer" (default: "computer")

要调用的工具，固定为 computer。

• "computer"

• CodeInterpreter object { type }

• type: "code_interpreter" (default: "code_interpreter")

要调用的工具，固定为 code_interpreter。

• "code_interpreter"

• ProgrammaticToolCalling object { type }

• type: "programmatic_tool_calling" (default: "programmatic_tool_calling")

要调用的工具，固定为 programmatic_tool_calling。

• "programmatic_tool_calling"

• Shell object { type }

需要调用工具时，强制模型调用 shell 工具。

• type: "shell" (default: "shell")

要调用的工具，固定为 shell。

• "shell"

• Custom object { name, type }

• name: string

要调用的自定义工具名称。

• type: "custom" (default: "custom")

要调用的工具，固定为 custom。

• "custom"

• ApplyPatch object { type }

执行工具调用时，强制模型调用 apply_patch 工具。

• type: "apply_patch" (default: "apply_patch")

要调用的工具，固定为 apply_patch。

• "apply_patch"

• type: "allowed_tools" (default: "allowed_tools")

工具选择类型，固定为 allowed_tools。

• "allowed_tools"

• mode: optional "none" or "auto" or "required" or null

从允许的工具集合中选择工具的方式。

• "none"

• "auto"

• "required"

• tools: optional array of FunctionTool or WebSearch { type } or FileSearch { type } or 10 more

Responses 后端处理 Live 模型委派的任务时可用的工具。

• FunctionTool object { name, type, description, 2 more }

Live 模型委派任务时，Responses 后端可用的函数工具。

• name: string

被委派的 Responses 模型调用此函数时使用的名称。

• type: "function" (default: "function")

工具类型，固定为 function。

• "function"

• description: optional string or null

函数的用途，以及被委派的 Responses 模型应在何时调用它。

• parameters: optional map[unknown] or null

描述函数可接受参数的 JSON Schema 对象。

• strict: optional boolean or null

被委派的 Responses 模型是否必须严格遵循函数的参数模式。

• WebSearch object { type }

Live 会话的 Responses 后端可用的网页搜索工具。

• type: "web_search" (default: "web_search")

工具类型，固定为 web_search。

• "web_search"

• FileSearch object { type }

• type: "file_search" (default: "file_search")

• "file_search"

• CodeInterpreter object { type }

• type: "code_interpreter" (default: "code_interpreter")

• "code_interpreter"

• Shell object { type, environment }

Responses shell 工具。可使用托管容器，或通过 response.item.create 返回本地 shell 执行结果。不支持域名密钥（domain secrets）。

• type: "shell" (default: "shell")

• "shell"

• environment: optional ContainerAuto { type, file_ids, memory_limit, 2 more } or ContainerReference { container_id, type } or Local { type, skills } or null

• ContainerAuto object { type, file_ids, memory_limit, 2 more }

• type: "container_auto" (default: "container_auto")

为此请求自动创建容器。

• "container_auto"

• file_ids: optional array of string or null

可选的已上传文件列表，这些文件将提供给代码使用。

maxItems: 50

• memory_limit: optional "1g" or "4g" or "16g" or "64g" or null

容器的内存上限。

• "1g"

• "4g"

• "16g"

• "64g"

• network_policy: optional Disabled { type } or Allowlist { allowed_domains, type } or null

容器的网络访问策略。

• Disabled object { type }

• type: "disabled" (default: "disabled")

禁用出站网络访问，固定为 disabled。

• "disabled"

• Allowlist object { allowed_domains, type }

• allowed_domains: array of string

type 为 allowlist 时允许访问的域名列表。

minItems: 1

• type: "allowlist" (default: "allowlist")

仅允许对指定域名发起出站网络访问，固定为 allowlist。

• "allowlist"

• skills: optional array of SkillReference { skill_id, type, version } or Inline { description, name, source, type } or null

可选的技能列表，通过 ID 或内联数据引用技能。

maxItems: 200

• SkillReference object { skill_id, type, version }

• skill_id: string

引用的技能 ID。

minLength: 1, maxLength: 64

• type: "skill_reference" (default: "skill_reference")

引用通过 /v1/skills 接口创建的技能。

• "skill_reference"

• version: optional string or null

可选的技能版本。使用正整数或 'latest'，省略时使用默认版本。

• Inline object { description, name, source, type }

• description: string

技能描述。

• name: string

技能名称。

• source: object { data, media_type, type }

内联技能载荷。

• data: string

采用 Base64 编码的技能 ZIP 包。

minLength: 1, maxLength: 70254592

• media_type: "application/zip" (default: "application/zip")

内联技能载荷的媒体类型，必须为 application/zip。

• "application/zip"

• type: "base64" (default: "base64")

内联技能来源的类型，必须为 base64。

• "base64"

• type: "inline" (default: "inline")

为此请求定义内联技能。

• "inline"

• ContainerReference object { container_id, type }

• container_id: string

引用的容器 ID。

• type: "container_reference" (default: "container_reference")

引用通过 /v1/containers 接口创建的容器。

• "container_reference"

• Local object { type, skills }

• type: "local" (default: "local")

使用本地计算机环境。

• "local"

• skills: optional array of object { description, name, path } or null

可选的技能列表。

maxItems: 200

• description: string

技能描述。

• name: string

技能名称。

• path: string

包含该技能的目录路径。

• ImageGeneration object { type }

• type: "image_generation" (default: "image_generation")

• "image_generation"

• Mcp object { type }

• type: "mcp" (default: "mcp")

• "mcp"

• Custom object { type }

• type: "custom" (default: "custom")

• "custom"

• Namespace object { type }

• type: "namespace" (default: "namespace")

• "namespace"

• ToolSearch object { type }

• type: "tool_search" (default: "tool_search")

• "tool_search"

• ProgrammaticToolCalling object { type }

• type: "programmatic_tool_calling" (default: "programmatic_tool_calling")

• "programmatic_tool_calling"

• Computer object { type }

• type: "computer" (default: "computer")

• "computer"

• ApplyPatch object { type }

• type: "apply_patch" (default: "apply_patch")

• "apply_patch"

• type: "responses" (default: "responses")

委派任务的处理方。由 Responses API 处理任务时固定为 responses。

• "responses"

• acknowledgement_delay_ms: optional integer

从委派任务发出到请求自动语音确认的等待时长，单位为毫秒。模型仍可能在等待结束前发言。向会话追加任何说明（commentary）或思考（thinking）都会取消所有待处理的确认，包括其他委派任务的确认。Decisions 会话默认为 400，其他会话默认为 0，即立即请求。更新会话时省略此项会保留当前值；更新仅作用于后续委派。

minimum: 0, maximum: 800

• Decisions object { decisions, type, acknowledgement_delay_ms }

• decisions: DecisionsDelegationConfig

• model: string

minLength: 1

• questions: array of DecisionQuestion

按顺序一起求值的原生 Decision API 问题。

minItems: 1, maxItems: 64

• Choice object { choices, instructions, type, name }

• choices: array of DecisionChoiceOption

minItems: 2, maxItems: 255

• value: string or boolean

• string

• boolean

• description: optional string

• instructions: string or array of DecisionInputText or InputImage { image_url, type, detail } or InputJSON { data, type }

• string

• array of DecisionInputText or InputImage { image_url, type, detail } or InputJSON { data, type }

minItems: 1

• DecisionInputText object { text, type }

• text: string

输入模型的文本。

maxLength: 10485760

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

• "input_text"

• InputImage object { image_url, type, detail }

• image_url: string

采用 Base64 编码的图像 data URL，或可公开访问的 HTTP(S) 图像 URL。

pattern: ^(data:|https?://), maxLength: 20971520

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

• "input_image"

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

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

• "low"

• "high"

• "auto"

• "original"

• InputJSON object { data, type }

• data: map[unknown] or array of map[unknown]

• LiveDecisionJSONObject = map[unknown]

• array of map[unknown]

• type: "input_json" (default: "input_json")

• "input_json"

• type: "choice" (default: "choice")

• "choice"

• name: optional string

• Predicate object { instructions, type, name }

• instructions: string or array of DecisionInputText or InputImage { image_url, type, detail } or InputJSON { data, type }

• string

• array of DecisionInputText or InputImage { image_url, type, detail } or InputJSON { data, type }

minItems: 1

• DecisionInputText object { text, type }

• InputImage object { image_url, type, detail }

• image_url: string

采用 Base64 编码的图像 data URL，或可公开访问的 HTTP(S) 图像 URL。

pattern: ^(data:|https?://), maxLength: 20971520

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

• "input_image"

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

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

• "low"

• "high"

• "auto"

• "original"

• InputJSON object { data, type }

• data: map[unknown] or array of map[unknown]

• LiveDecisionJSONObject = map[unknown]

• array of map[unknown]

• type: "input_json" (default: "input_json")

• "input_json"

• type: "predicate" (default: "predicate")

• "predicate"

• name: optional string

• Score object { instructions, levels, type, name }

• instructions: string or array of DecisionInputText or InputImage { image_url, type, detail } or InputJSON { data, type }

• string

• array of DecisionInputText or InputImage { image_url, type, detail } or InputJSON { data, type }

minItems: 1

• DecisionInputText object { text, type }

• InputImage object { image_url, type, detail }

• image_url: string

采用 Base64 编码的图像 data URL，或可公开访问的 HTTP(S) 图像 URL。

pattern: ^(data:|https?://), maxLength: 20971520

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

• "input_image"

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

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

• "low"

• "high"

• "auto"

• "original"

• InputJSON object { data, type }

• data: map[unknown] or array of map[unknown]

• LiveDecisionJSONObject = map[unknown]

• array of map[unknown]

• type: "input_json" (default: "input_json")

• "input_json"

• levels: array of object { label, description }

minItems: 2, maxItems: 10

• label: string

• description: optional string

• type: "score" (default: "score")

• "score"

• name: optional string

• type: "decisions" (default: "decisions")

• "decisions"

• acknowledgement_delay_ms: optional integer

从委派任务发出到请求自动语音确认的等待时长，单位为毫秒。模型仍可能在等待结束前发言。向会话追加任何说明（commentary）或思考（thinking）都会取消所有待处理的确认，包括其他委派任务的确认。默认为 400；更新仅作用于后续委派。

minimum: 0, maximum: 800

• input: optional array of InitialItem

启动前提供的有序纯文本历史记录。支持 developer、user 和 assistant 消息，每条消息包含一个文本部分；最多 128 条消息，并受配置的渲染后词元数量上限约束，默认上限为 8,192。

maxItems: 128

• Developer object { content, role, id, 2 more }

包含在 Live 会话初始文本历史记录中的开发者消息。

• content: array of object { text, type }

消息内容。Live 初始对话历史记录中的每条消息须恰好提供一个文本部分。

minItems: 1, maxItems: 1

• text: string

要包含在 Live 会话初始对话历史记录中的消息文本。

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

文本内容类型，固定为 input_text。

• "input_text"

• role: "developer" (default: "developer")

此历史消息的作者，固定为 developer。

• "developer"

• id: optional string or null

所提供历史消息的可选标识。Live 使用消息的角色和文本初始化对话。

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

所提供消息的状态。Live 将其文本作为历史记录，不会恢复未完成的消息。

• "incomplete"

• "completed"

• type: optional "message" (default: "message")

历史记录条目的类型，固定为 message。

• "message"

• User object { content, role, id, 2 more }

包含在 Live 会话初始文本历史记录中的用户消息。

• content: array of object { text, type }

消息内容。Live 初始对话历史记录中的每条消息须恰好提供一个文本部分。

minItems: 1, maxItems: 1

• text: string

要包含在 Live 会话初始对话历史记录中的消息文本。

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

文本内容类型，固定为 input_text。

• "input_text"

• role: "user" (default: "user")

此历史消息的作者，固定为 user。

• "user"

• id: optional string or null

所提供历史消息的可选标识。Live 使用消息的角色和文本初始化对话。

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

所提供消息的状态。Live 将其文本作为历史记录，不会恢复未完成的消息。

• "incomplete"

• "completed"

• type: optional "message" (default: "message")

历史记录条目的类型，固定为 message。

• "message"

• Assistant object { content, role, id, 2 more }

包含在 Live 会话初始文本历史记录中的助手消息。

• content: array of Text { text, type } or OutputText { text, type }

消息内容。Live 初始对话历史记录中的每条消息须恰好提供一个文本部分。

minItems: 1, maxItems: 1

• Text object { text, type }

启动 Live 会话时作为对话历史记录提供的助手文本。

• text: string

要包含在 Live 会话初始对话历史记录中的消息文本。

• type: optional "text" (default: "text")

文本内容类型，固定为 text。

• "text"

• OutputText object { text, type }

启动 Live 会话时作为对话历史记录提供的助手输出文本。

• text: string

要包含在 Live 会话初始对话历史记录中的消息文本。

• type: "output_text" (default: "output_text")

文本内容类型，固定为 output_text。

• "output_text"

• role: "assistant" (default: "assistant")

此历史消息的作者，固定为 assistant。

• "assistant"

• id: optional string or null

所提供历史消息的可选标识。Live 使用消息的角色和文本初始化对话。

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

所提供消息的状态。Live 将其文本作为历史记录，不会恢复未完成的消息。

• "incomplete"

• "completed"

• type: optional "message" (default: "message")

历史记录条目的类型，固定为 message。

• "message"

• instructions: optional string or null

关于音色、对话、打断及何时委派任务的前端指令。先阅读 Live 提示词指南；将业务规则和工具工作流程放在单独的后端提示词中。客户端提供的指令最多 16,384 个词元。省略或提供空白指令时使用服务端默认值。启动后不能更改。

• safety_identifier: optional string or null

最终用户的稳定标识，用于安全监控和滥用检测。

maxLength: 128

• store: optional boolean

是否保存会话，以便之后分叉和下载录音。新会话默认为 false。

• triggers: optional array of DecisionTrigger

每种转录事件类型最多配置一个 Decisions 触发器。触发器独立于任务委派运行。更新时省略 triggers 会保留当前配置，发送列表会替换配置，发送空列表会禁用触发器。

maxItems: 2

• decisions: object { questions }

使用当前转录文本与会话共享的 Decision 条目进行求值的问题。

• questions: array of DecisionQuestion

按顺序一起求值的原生 Decision API 问题。

minItems: 1, maxItems: 64

• Choice object { choices, instructions, type, name }

• Predicate object { instructions, type, name }

• Score object { instructions, levels, type, name }

• event_type: "session.input_transcript.delta" or "session.output_transcript.delta"

• "session.input_transcript.delta"

• "session.output_transcript.delta"

• type: "decisions" (default: "decisions")

• "decisions"

• type: "session.closed" (default: "session.closed")

事件类型，固定为 session.closed。

• "session.closed"

• usage: SessionUsage

会话收尾后的最终累计 Live 音频用量。

• seconds: number

累计 Live 音频时长，单位为秒。不要将多个用量事件中的此值相加。

• client_event_id: optional string

与此服务端事件关联的客户端命令的 event_id，如已提供。

示例

{
  "type": "session.closed",
  "event_id": "evt_closed_001",
  "client_event_id": "evt_close_001",
  "reason": "close_requested",
  "session": {
    "id": "live_abc123",
    "model": "gpt-live-1",
    "status": "active",
    "expires_at": 1788555600,
    "instructions": "帮助来电者安排餐厅预订，预订前确认细节。",
    "input": [],
    "audio": {
      "format": {
        "type": "audio/pcm",
        "rate": 24000
      },
      "output": {
        "voice": "marin"
      }
    },
    "delegation": {
      "type": "client"
    }
  },
  "usage": {
    "seconds": 45.8
  }
}

error

报告 Live 会话中的错误，例如无效客户端命令。如有 error.client_event_id，可用其识别引发错误的命令。

模式定义

模式名称：LiveErrorEvent

• error: Error

Live 错误及引发错误的客户端命令的详情，如已知。

• code: string

标识 Live 错误的机器可读错误码，例如 unknown_parameter。

• message: string

Live 错误的可读说明。

• type: string

错误类别，例如无效 Live 客户端命令使用 invalid_request_error。

• client_event_id: optional string

引发错误的客户端命令的 event_id，如已提供。

• param: optional string

引发错误的参数，如适用，例如 session.voice。

• event_id: string

Live 服务端事件的唯一 ID。

• type: "error" (default: "error")

事件类型，固定为 error。

• "error"

• client_event_id: optional string

与此服务端事件关联的客户端命令的 event_id，如已提供。

示例

{
  "type": "error",
  "event_id": "evt_error_001",
  "error": {
    "type": "invalid_request_error",
    "code": "unknown_parameter",
    "message": "未知参数：session.voice。",
    "param": "session.voice",
    "client_event_id": "evt_invalid_001"
  }
}

info

关于 Live 会话的信息性通知，例如应用到前端数据通道的事件权限。

模式定义

模式名称：LiveInfoEvent

• code: string

机器可读的通知代码，例如 data_channel_permissions。

• event_id: string

Live 服务端事件的唯一 ID。

• message: string

Live 会话通知的可读说明。

• type: "info" (default: "info")

事件类型，固定为 info。

• "info"

• client_event_id: optional string

与此服务端事件关联的客户端命令的 event_id，如已提供。

示例

{
  "type": "info",
  "event_id": "evt_info_001",
  "code": "data_channel_permissions",
  "message": "前端数据通道已配置受限的事件权限。"
}

session.input_audio.append

从主传输收到的输入音频，在模型输入静音处理前反射到 Live 旁路连接。

模式定义

模式名称：LiveInputAudioAppend

• audio: string

从主传输收到的 Base64 编码原始单声道 PCM16LE 音频，24 kHz，在模型输入静音处理前反射到旁路。此服务端事件使用与客户端命令相同的 audio 键，但不是该命令的确认。

• type: "session.input_audio.append" (default: "session.input_audio.append")

事件类型，固定为 session.input_audio.append。

• "session.input_audio.append"

示例

{
  "type": "session.input_audio.append",
  "audio": "AACAAIAAAIAAAP9/AIAAgA=="
}

transport.dtmf.received

从呼叫方收到的 SIP DTMF 按键。仅发送给旁路观察者。

模式定义

模式名称：LiveTransportDTMFReceived

• event: string

pattern: ^[0-9A-D*#]$, minLength: 1, maxLength: 1

• event_id: string

• type: "transport.dtmf.received" (default: "transport.dtmf.received")

• "transport.dtmf.received"

示例

{
  "type": "transport.dtmf.received",
  "event_id": "event_dtmf_1",
  "event": "5"
}

transport.dtmf.sent

已成功发送到 SIP 中继的 DTMF 按键。仅发送给旁路观察者，这不是客户端命令。

模式定义

模式名称：LiveTransportDTMFSent

• event: string

pattern: ^[0-9A-D*#]$, minLength: 1, maxLength: 1

• event_id: string

• type: "transport.dtmf.sent" (default: "transport.dtmf.sent")

• "transport.dtmf.sent"

• client_event_id: optional string

客户端命令的 event_id，如已提供。

示例

{
  "type": "transport.dtmf.sent",
  "event_id": "event_dtmf_2",
  "event": "#"
}