OpenAI 压缩多智能体对话

2026-11-18 15:19 更新

压缩对话

post /responses/compact?beta=true

压缩对话,返回压缩后的响应对象。

关于何时及如何压缩持续运行的长对话,请参阅对话状态指南。关于与 ZDR 兼容的压缩,请参阅高级压缩。

请求头参数

  • "openai-beta": optional array of "responses_multi_agent=v1"

  • "responses_multi_agent=v1"

请求体参数

内容类型为 application/json。

  • model: "gpt-6-astra" or "gpt-6.2-astra" or "gpt-6.1-sol" or 112 more or string or null

用于生成响应的模型 ID,例如 gpt-6-astra。OpenAI 提供能力、性能特点和价格各异的多种模型。请参阅模型指南,浏览和比较可用模型。

  • "gpt-6-astra" or "gpt-6.2-astra" or "gpt-6.1-sol" or 112 more

用于生成响应的模型 ID,例如 gpt-6-astra。OpenAI 提供能力、性能特点和价格各异的多种模型。请参阅模型指南,浏览和比较可用模型。

  • "gpt-6-astra"

  • "gpt-6.2-astra"

  • "gpt-6.1-sol"

  • "gpt-6.2-sol"

  • "gpt-6.1-terra"

  • "gpt-6-sol"

  • "gpt-6-luna"

  • "gpt-5.6-sol"

  • "gpt-5.6-terra"

  • "gpt-5.6-luna"

  • "gpt-5.5"

  • "gpt-5.5-2026-04-23"

  • "gpt-5.4"

  • "gpt-5.4-mini"

  • "gpt-5.4-nano"

  • "gpt-5.4-mini-2026-03-17"

  • "gpt-5.4-nano-2026-03-17"

  • "gpt-5.3-chat-latest"

  • "gpt-5.2"

  • "gpt-5.2-2025-12-11"

  • "gpt-5.2-chat-latest"

  • "gpt-5.2-pro"

  • "gpt-5.2-pro-2025-12-11"

  • "gpt-5.1"

  • "gpt-5.1-2025-11-13"

  • "gpt-5.1-codex"

  • "gpt-5.1-mini"

  • "gpt-5.1-chat-latest"

  • "gpt-5"

  • "gpt-5-mini"

  • "gpt-5-nano"

  • "gpt-5-2025-08-07"

  • "gpt-5-mini-2025-08-07"

  • "gpt-5-nano-2025-08-07"

  • "gpt-5-chat-latest"

  • "gpt-4.1"

  • "gpt-4.1-mini"

  • "gpt-4.1-nano"

  • "gpt-4.1-2025-04-14"

  • "gpt-4.1-mini-2025-04-14"

  • "gpt-4.1-nano-2025-04-14"

  • "o4-mini"

  • "o4-mini-2025-04-16"

  • "o3"

  • "o3-2025-04-16"

  • "o3-mini"

  • "o3-mini-2025-01-31"

  • "o1"

  • "o1-2024-12-17"

  • "o1-preview"

  • "o1-preview-2024-09-12"

  • "o1-mini"

  • "o1-mini-2024-09-12"

  • "gpt-4o"

  • "gpt-4o-2024-11-20"

  • "gpt-4o-2024-08-06"

  • "gpt-4o-2024-05-13"

  • "gpt-audio-mini"

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

  • "gpt-4o-audio-preview"

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

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

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

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

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

  • "gpt-4o-search-preview"

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

  • "gpt-4o-search-preview-2025-03-11"

  • "gpt-4o-mini-search-preview-2025-03-11"

  • "chatgpt-4o-latest"

  • "codex-mini-latest"

  • "gpt-4o-mini"

  • "gpt-4o-mini-2024-07-18"

  • "gpt-4-turbo"

  • "gpt-4-turbo-2024-04-09"

  • "gpt-4-0125-preview"

  • "gpt-4-turbo-preview"

  • "gpt-4-1106-preview"

  • "gpt-4-vision-preview"

  • "gpt-4"

  • "gpt-4-0314"

  • "gpt-4-0613"

  • "gpt-4-32k"

  • "gpt-4-32k-0314"

  • "gpt-4-32k-0613"

  • "gpt-3.5-turbo"

  • "gpt-3.5-turbo-16k"

  • "gpt-3.5-turbo-0301"

  • "gpt-3.5-turbo-0613"

  • "gpt-3.5-turbo-1106"

  • "gpt-3.5-turbo-0125"

  • "gpt-3.5-turbo-16k-0613"

  • "o1-pro"

  • "o1-pro-2025-03-19"

  • "o3-pro"

  • "o3-pro-2025-06-10"

  • "o3-deep-research"

  • "o3-deep-research-2025-06-26"

  • "o4-mini-deep-research"

  • "o4-mini-deep-research-2025-06-26"

  • "computer-use-preview"

  • "computer-use-preview-2025-03-11"

  • "gpt-5.5-pro"

  • "gpt-5.5-pro-2026-04-23"

  • "gpt-5-codex"

  • "gpt-5-pro"

  • "gpt-5-pro-2025-10-06"

  • "gpt-5.1-codex-max"

  • "gpt-daybreak-blue-latest"

  • "gpt-daybreak-red-latest"

  • "gpt-5.6-cyber"

  • "gpt-6-cyber"

  • "gpt-rosalind-research"

  • "gpt-6-rosalind"

  • "gpt-6.2-astra-law"

  • string

  • image: optional object { context_compression }

请求级别的图像选项。

  • context_compression: optional "auto" or "enabled" or "disabled"

控制图像上下文优化。默认为 auto,根据模型、传输方式和输入选择策略。设为 enabled 可要求支持压缩,设为 disabled 可关闭此功能。

  • "auto"

  • "enabled"

  • "disabled"

  • input: optional string or array of BetaEasyInputMessage or Message { content, role, agent, 2 more } or BetaResponseOutputMessage or 33 more or null

提供给模型的文本、图像或文件输入,用于生成响应。

  • string

提供给模型的文本输入,等同于角色为 user 的文本输入。

maxLength: 10485760

  • array of BetaEasyInputMessage or Message { content, role, agent, 2 more } or BetaResponseOutputMessage or 33 more

提供给模型的一个或多个输入条目组成的列表,其中可以包含不同类型的内容。

maxItems: 131072

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

提供给模型的消息输入,角色表示指令遵循层级。developer或system指令优先于user指令;assistant消息被视为模型在先前交互中生成的消息。

  • content: string or BetaResponseInputMessageContentList

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

  • TextInput = string

输入模型的文本。

  • BetaResponseInputMessageContentList = array of BetaResponseInputContent

提供给模型的一个或多个输入条目组成的列表,其中可以包含不同类型的内容。

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

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

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

  • detail: BetaImageDetail

发送给模型的图像细节级别,可选 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"

  • BetaResponseInputFile 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, agent, 2 more }

提供给模型的消息输入,角色表示指令遵循层级;developer或system指令优先于user指令。

  • content: BetaResponseInputMessageContentList

提供给模型的一个或多个输入条目组成的列表,其中可以包含不同类型的内容。

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

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

  • "user"

  • "system"

  • "developer"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

  • type: optional "message"

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

  • "message"

  • BetaResponseOutputMessage object { id, content, role, 4 more }

模型输出的消息。

  • id: string

输出消息的唯一 ID。

  • content: array of BetaResponseOutputText or BetaResponseOutputRefusal

输出消息的内容。

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

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

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

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

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • 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, 5 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 BetaComputerAction

单击操作。

  • 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: 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 BetaComputerActionList

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 }

等待操作。

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

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

计算机工具调用的输出。

  • call_id: string

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

minLength: 1, maxLength: 64

  • output: BetaResponseComputerToolCallOutputScreenshot

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

  • 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

待处理安全检查的详情。

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

  • WebSearchCall object { id, status, type, 2 more }

网页搜索工具调用的结果,详见网页搜索指南。

  • 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

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

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

执行函数的工具调用,详见函数调用指南。

  • arguments: string

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

  • call_id: string

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

  • name: string

要运行的函数名称。

  • type: "function_call"

类型,固定为 function_call。

  • "function_call"

  • id: optional string

函数工具调用的唯一 ID。

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • 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, 6 more }

函数工具调用的输出。

  • output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent

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

  • string

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

maxLength: 10485760

  • array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent

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

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

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

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

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

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

  • "input_image"

  • detail: optional BetaImageDetail 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"

  • BetaResponseInputFileContent 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 返回此条目时填充。

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

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

  • AgentMessage object { author, content, recipient, 3 more }

在智能体之间路由的消息。

  • author: string

发送方智能体的标识。

  • content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or EncryptedContent { encrypted_content, type }

智能体之间传递的纯文本、图像或加密内容。

  • BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }

输入模型的文本。

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

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

  • EncryptedContent object { encrypted_content, type }

不透明的加密内容,由 Responses API 在受信任的模型执行环境中解密。

  • encrypted_content: string

不透明的加密内容。

maxLength: 10485760

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

输入条目的类型,固定为 encrypted_content。

  • "encrypted_content"

  • recipient: string

接收方智能体的标识。

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

条目类型,固定为 agent_message。

  • "agent_message"

  • id: optional string or null

此智能体消息条目的唯一 ID。

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • MultiAgentCall object { action, arguments, call_id, 3 more }

  • action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more

已执行的多智能体操作。

  • "spawn_agent"

  • "interrupt_agent"

  • "list_agents"

  • "send_message"

  • "followup_task"

  • "wait_agent"

  • arguments: string

以 JSON 字符串表示的操作参数。

  • call_id: string

关联调用与其输出的唯一 ID。

minLength: 1, maxLength: 64

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

条目类型,固定为 multi_agent_call。

  • "multi_agent_call"

  • id: optional string or null

此多智能体调用的唯一 ID。

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • MultiAgentCallOutput object { action, call_id, output, 3 more }

  • action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more

生成此结果的多智能体操作。

  • "spawn_agent"

  • "interrupt_agent"

  • "list_agents"

  • "send_message"

  • "followup_task"

  • "wait_agent"

  • call_id: string

此多智能体调用的唯一 ID。

minLength: 1, maxLength: 64

  • output: array of object { text, type, annotations }

多智能体操作返回的文本。

  • text: string

文本内容。

maxLength: 10485760

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

内容类型,固定为 output_text。

  • "output_text"

  • annotations: optional 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 }

与该文本内容关联的引用。

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

  • file_id: string

文件 ID。

  • filename: string

被引用文件的文件名。

  • index: integer

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

minimum: 0

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

引用类型,固定为 file_citation。

  • "file_citation"

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

  • end_index: integer

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

minimum: 0

  • start_index: integer

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

minimum: 0

  • title: string

被引用资源的标题。

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

引用类型,固定为 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

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

minimum: 0

  • file_id: string

容器文件 ID。

  • filename: string

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

  • start_index: integer

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

minimum: 0

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

引用类型,固定为 container_file_citation。

  • "container_file_citation"

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

条目类型,固定为 multi_agent_call_output。

  • "multi_agent_call_output"

  • id: optional string or null

此多智能体调用输出的唯一 ID。

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

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

  • arguments: unknown

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

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

条目类型,固定为 tool_search_call。

  • "tool_search_call"

  • id: optional string or null

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

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • 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, 4 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 { key, type, value } or unknown 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

  • BetaCompoundFilter = unknown

使用 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日之后发布的模型中已弃用。远程MCP服务器改用server_url,安全MCP隧道连接改用tunnel_id。

当前支持的 connector_id 值如下:

Dropbox:connector_dropbox;Gmail:connector_gmail;Google Calendar:connector_googlecalendar;Google Drive:connector_googledrive;Microsoft Teams:connector_microsoftteams;Outlook Calendar:connector_outlookcalendar;Outlook Email: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 }

指定哪些工具需要批准,可选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 BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist

容器的网络访问策略。

  • BetaContainerNetworkPolicyDisabled object { type }

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

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

  • "disabled"

  • BetaContainerNetworkPolicyAllowlist 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 BetaContainerNetworkPolicyDomainSecret

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

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快照支持不透明和透明背景;gpt-image-2的透明背景为预览能力。使用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。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 BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference or null

  • BetaContainerAuto 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 BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist

容器的网络访问策略。

  • BetaContainerNetworkPolicyDisabled object { type }

  • BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }

  • skills: optional array of BetaSkillReference or BetaInlineSkill

可选技能列表,支持按 ID 引用或传入内联数据。列表中所有内联技能解码后的 ZIP 数据合计最多 50 MiB,Base64 文本含换行在内合计最多 70,254,592 个字符。技能引用不计入限制。

maxItems: 200

  • BetaSkillReference 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',省略时使用默认版本。

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

  • description: string

技能描述。

  • name: string

技能名称。

  • source: BetaInlineSkillSource

内联技能载荷。

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

  • BetaLocalEnvironment object { type, skills }

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

使用本地计算机环境。

  • "local"

  • skills: optional array of BetaLocalSkill

可选的技能列表。

maxItems: 200

  • description: string

技能描述。

  • name: string

技能名称。

  • path: string

包含该技能的目录路径。

  • BetaContainerReference 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 Text { type } or Grammar { definition, syntax, type }

自定义工具的输入格式,默认为无约束文本。

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

  • BetaToolSearchOutputNamespaceTool 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 Text { type } or Grammar { definition, syntax, type }

自定义工具的输入格式,默认为无约束文本。

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

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

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • 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, 2 more }

  • 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 { key, type, value } or unknown 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

  • BetaCompoundFilter = unknown

使用 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日之后发布的模型中已弃用。远程MCP服务器改用server_url,安全MCP隧道连接改用tunnel_id。

当前支持的 connector_id 值如下:

Dropbox:connector_dropbox;Gmail:connector_gmail;Google Calendar:connector_googlecalendar;Google Drive:connector_googledrive;Microsoft Teams:connector_microsoftteams;Outlook Calendar:connector_outlookcalendar;Outlook Email: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 }

指定哪些工具需要批准,可选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 BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist

容器的网络访问策略。

  • BetaContainerNetworkPolicyDisabled object { type }

  • BetaContainerNetworkPolicyAllowlist 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快照支持不透明和透明背景;gpt-image-2的透明背景为预览能力。使用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。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 BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference or null

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

  • BetaLocalEnvironment object { type, skills }

  • BetaContainerReference 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 Text { type } or Grammar { definition, syntax, type }

自定义工具的输入格式,默认为无约束文本。

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

  • 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 Text { type } or Grammar { definition, syntax, type }

自定义工具的输入格式,默认为无约束文本。

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

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

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • ConfigurationUpdate object { type, id, agent, 2 more }

更新对话的响应配置。可提供推理设置、文本设置或两者。各项设置持续有效,直至后续更新替换。

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

条目类型,固定为 configuration_update。

  • "configuration_update"

  • id: optional string or null

配置更新条目的唯一 ID。

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • reasoning: optional object { effort }

推理配置更新,仅支持 effort。

  • effort: optional "none" or "minimal" or "low" or 4 more or null (default: "medium")

后续响应使用的推理努力程度,直到被下一条配置更新替代。

  • "none"

  • "minimal"

  • "low"

  • "medium"

  • "high"

  • "xhigh"

  • "max"

  • text: optional object { format }

后续响应的文本输出配置。

  • format: Text { type } or BetaResponseFormatTextJSONSchemaConfig

使用 JSON Schema 进行结构化输出,或使用 text 恢复纯文本。

  • Text object { type }

默认响应格式,用于生成文本响应。

  • type: "text"

定义的响应格式类型,固定为 text。

  • "text"

  • BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }

JSON Schema响应格式,用于生成结构化JSON,详见结构化输出。

  • name: string

响应格式名称,只能使用a-z、A-Z、0-9、下划线和连字符,最长64个字符。

  • schema: map[unknown]

以JSON Schema对象描述的响应格式schema,构建方法见JSON Schema。

  • type: "json_schema"

定义的响应格式类型,固定为 json_schema。

  • "json_schema"

  • description: optional string

响应格式用途的描述,供模型判断如何按此格式回答。

  • strict: optional boolean or null (default: false)

是否严格遵循输出schema。设为true时,模型会严格遵循schema定义;strict为true时仅支持JSON Schema子集,详见结构化输出指南。

  • Reasoning object { id, summary, type, 4 more }

推理模型生成响应时所用思维链的描述。如果手动管理上下文,请在后续对话轮次发送给Responses API的input中包含这些条目。

  • id: string

推理内容的唯一标识。

  • summary: array of object { text, type }

推理摘要内容。

  • text: string

模型到目前为止生成的推理输出摘要。

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

类型,固定为 summary_text。

  • "summary_text"

  • type: "reasoning"

类型,固定为 reasoning。

  • "reasoning"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • 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中的加密内容可能不完整。在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, agent }

v1/responses/compact API生成的压缩条目。

  • encrypted_content: string

压缩摘要的加密内容。

maxLength: 104857600

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

类型,固定为 compaction。

  • "compaction"

  • id: optional string or null

压缩条目 ID。

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • ImageGenerationCall object { id, result, status, 10 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"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

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

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • LocalShellCall object { id, action, call_id, 3 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"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • LocalShellCallOutput object { id, output, type, 2 more }

本地 shell 工具调用的输出。

  • id: string

模型生成的本地 shell 工具调用的唯一 ID。

  • output: string

本地 shell 工具调用输出的 JSON 字符串。

  • type: "local_shell_call_output"

类型,固定为 local_shell_call_output。

  • "local_shell_call_output"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

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

条目状态,可选 in_progress、completed 或 incomplete。

  • "in_progress"

  • "completed"

  • "incomplete"

  • ShellCall object { action, call_id, type, 5 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 返回此条目时填充。

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • 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 BetaLocalEnvironment or BetaContainerReference or null

执行 shell 命令的环境。

  • BetaLocalEnvironment object { type, skills }

  • BetaContainerReference 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, 5 more }

shell 工具调用发出的流式输出条目。

  • call_id: string

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

minLength: 1, maxLength: 64

  • output: array of BetaResponseFunctionShellCallOutputContent

捕获的 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 返回此条目时填充。

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • 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, 4 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 返回此条目时填充。

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • 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, 4 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 返回此条目时填充。

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

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

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • error: optional string or null

服务器无法列出工具时的错误消息。

  • McpApprovalRequest object { id, arguments, name, 3 more }

工具调用的人工批准请求。

  • id: string

批准请求的唯一 ID。

  • arguments: string

工具参数的 JSON 字符串。

  • name: string

要运行的工具名称。

  • server_label: string

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

  • type: "mcp_approval_request"

类型,固定为 mcp_approval_request。

  • "mcp_approval_request"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • McpApprovalResponse object { approval_request_id, approve, type, 3 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。

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • reason: optional string or null

决定的可选理由。

  • McpCall object { id, arguments, name, 7 more }

对 MCP 服务器上工具的调用。

  • id: string

工具调用的唯一 ID。

  • arguments: string

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

  • name: string

已运行的工具名称。

  • server_label: string

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

  • type: "mcp_call"

类型,固定为 mcp_call。

  • "mcp_call"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • approval_request_id: optional string or null

MCP工具调用批准请求的唯一标识。要批准或拒绝相应调用,应在后续mcp_approval_response输入中包含此值。

  • error: optional BetaMcpToolCallError 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, 3 more }

自有代码生成、回传给模型的自定义工具调用输出。

  • call_id: string

调用 ID,用于将此自定义工具调用输出映射到自定义工具调用。

  • output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile

你的代码生成的自定义工具输出,可为字符串或输出内容列表。

  • StringOutput = string

自定义工具调用输出的字符串。

  • OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile

自定义工具调用的文本、图像或文件输出。

  • BetaResponseInputText object { text, type, prompt_cache_breakpoint }

输入模型的文本。

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

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

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

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • 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, 6 more }

模型生成的自定义工具调用。

  • call_id: string

用于将此自定义工具调用映射到工具调用输出的标识。

  • input: string

模型生成的自定义工具调用输入。

  • name: string

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

  • type: "custom_tool_call"

类型,固定为 custom_tool_call。

  • "custom_tool_call"

  • id: optional string

自定义工具调用在 OpenAI 平台中的唯一 ID。

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • 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, agent }

压缩当前上下文,须为最后一个输入条目。

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

类型,固定为 compaction_trigger。

  • "compaction_trigger"

  • id: optional string or null

此压缩触发器的唯一 ID。

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • ItemReference object { id, agent, type }

用于引用条目的内部标识。

  • id: string

要引用的条目的 ID。

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • type: optional "item_reference" or null (default: "item_reference")

引用条目的类型,固定为 item_reference。

  • "item_reference"

  • Program object { id, call_id, code, 3 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"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • ProgramOutput object { id, call_id, result, 3 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"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • instructions: optional string or null

插入模型上下文的system或developer消息。与previous_response_id一起使用时,上一响应的instructions不会传入下一响应,便于在新响应中替换system或developer消息。

  • previous_response_id: optional string or null

模型上一个响应的唯一 ID。使用此字段创建多轮对话。有关详情,请参阅对话状态。不能与 conversation 同时使用。

  • prompt_cache_key: optional string or null

读取或写入提示词缓存时使用的键。

maxLength: 64

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

提示词缓存选项,支持 gpt-5.6 及后续模型。默认由 OpenAI 自动选择一个隐式缓存断点。可通过 prompt_cache_breakpoint 为内容块添加显式断点。每个请求最多写入四个断点。缓存匹配会考虑对话中最近最多 80 个断点,不受内容块回看数量限制。将 mode 设为 explicit 可禁用隐式断点。ttl 默认为 30m。支持的存续时间取决于 API,当前详情参阅提示词缓存指南。

  • mode: optional "implicit" or "explicit"

控制 OpenAI 是否自动创建隐式缓存断点,默认为 implicit。使用 implicit 时,创建一个隐式断点,并写入请求中最近最多三个显式断点。使用 explicit 时,不创建隐式断点,写入最近最多四个显式断点。如果没有显式断点,请求不使用提示词缓存。

  • "implicit"

  • "explicit"

  • ttl: optional "30m"

请求写入的每个隐式和显式缓存断点的最短存续时间,默认为 30m,目前仅支持此值。后端可能保留缓存条目更长时间。

  • "30m"

  • prompt_cache_retention: optional "in_memory" or "24h" or null

此请求创建的提示词缓存条目的保留时间。

  • "in_memory"

  • "24h"

  • service_tier: optional "auto" or "default" or "fast" or 2 more or null

指定处理请求的类型。auto使用项目配置的服务层级,未另配置时为default;default使用所选模型标准价格和性能;flex使用Flex处理。Responses或Chat Completions请求以service_tier=fast或service_tier=priority启用快速模式:有专用Fast层级的模型两者均解析为fast,其他模型均解析为priority。未设置时默认auto。响应的service_tier反映实际处理模式,可能不同于请求参数。

  • "auto"

  • "default"

  • "fast"

  • "flex"

  • "priority"

返回值

  • BetaCompactedResponse object { id, created_at, object, 3 more }

  • id: string

压缩后的响应的唯一标识符。

  • created_at: integer

压缩后对话创建时的 Unix 时间戳,单位为秒。

format: unixtime

  • object: "response.compaction" (default: "response.compaction")

对象类型,始终为 response.compaction。

  • "response.compaction"

  • output: array of Message { id, content, role, 4 more } or Program { id, call_id, code, 3 more } or ProgramOutput { id, call_id, result, 3 more } or 28 more

压缩后的输出条目列表。

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

发往模型或由模型发出的消息。

  • id: string

消息的唯一 ID。

  • content: array of BetaResponseInputText or BetaResponseOutputText or Text { text, type } or 7 more

消息内容。

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

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

  • Text object { text, type }

文本内容。

  • text: string

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

  • "text"

  • SummaryText object { text, type }

模型生成的摘要文本。

  • text: string

模型到目前为止生成的推理输出摘要。

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

类型,固定为 summary_text。

  • "summary_text"

  • ReasoningText object { text, type }

模型生成的推理文本。

  • text: string

模型生成的推理文本。

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

类型,固定为 reasoning_text。

  • "reasoning_text"

  • BetaResponseOutputRefusal object { refusal, type }

模型的拒绝响应。

  • refusal: string

模型给出的拒绝原因。

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

类型,固定为 refusal。

  • "refusal"

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

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

  • detail: BetaImageDetail

发送给模型的图像细节级别,可选 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"

  • ComputerScreenshot object { detail, file_id, image_url, 2 more }

计算机屏幕截图。

  • detail: BetaImageDetail

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

  • file_id: string or null

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

  • image_url: string or null

截图图像的 URL。

format: uri

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

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

  • "computer_screenshot"

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

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

  • EncryptedContent object { encrypted_content, type }

不透明的加密内容,由 Responses API 在受信任的模型执行环境中解密。

  • encrypted_content: string

不透明的加密内容。

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

输入条目的类型,固定为 encrypted_content。

  • "encrypted_content"

  • role: "unknown" or "user" or "assistant" or 5 more

消息角色,可选 unknown、user、assistant、system、critic、discriminator、developer 或 tool。

  • "unknown"

  • "user"

  • "assistant"

  • "system"

  • "critic"

  • "discriminator"

  • "developer"

  • "tool"

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

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

消息类型,固定为 message。

  • "message"

  • agent: optional object { agent_name }

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

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

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

  • "commentary"

  • "final_answer"

  • Program object { id, call_id, code, 3 more }

  • id: string

program 条目的唯一 ID。

  • call_id: string

program 条目的稳定调用 ID。

  • code: string

程序化工具调用所执行的 JavaScript 源代码。

  • fingerprint: string

不透明的程序重放指纹,须在后续请求中原样回传。

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

条目类型,固定为 program。

  • "program"

  • agent: optional object { agent_name }

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • ProgramOutput object { id, call_id, result, 3 more }

  • id: string

程序输出条目的唯一 ID。

  • call_id: string

program 条目的调用 ID。

  • result: string

program 条目生成的结果。

  • status: "completed" or "incomplete"

程序输出条目的终态。

  • "completed"

  • "incomplete"

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

条目类型,固定为 program_output。

  • "program_output"

  • agent: optional object { agent_name }

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

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

执行函数的工具调用,详见函数调用指南。

  • arguments: string

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

  • call_id: string

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

  • name: string

要运行的函数名称。

  • type: "function_call"

类型,固定为 function_call。

  • "function_call"

  • id: optional string

函数工具调用的唯一 ID。

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

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

  • MultiAgentCall object { id, action, arguments, 3 more }

  • id: string

该多智能体调用条目的唯一 ID。

  • action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more

要执行的多智能体操作。

  • "spawn_agent"

  • "interrupt_agent"

  • "list_agents"

  • "send_message"

  • "followup_task"

  • "wait_agent"

  • arguments: string

为该操作生成的参数,格式为 JSON 字符串。

  • call_id: string

关联调用与其输出的唯一 ID。

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

多智能体调用的类型,固定为 multi_agent_call。

  • "multi_agent_call"

  • agent: optional object { agent_name }

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • MultiAgentCallOutput object { id, action, call_id, 3 more }

  • id: string

此多智能体调用输出条目的唯一 ID。

  • action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more

生成此结果的多智能体操作。

  • "spawn_agent"

  • "interrupt_agent"

  • "list_agents"

  • "send_message"

  • "followup_task"

  • "wait_agent"

  • call_id: string

此多智能体调用的唯一 ID。

  • output: array of BetaResponseOutputText

多智能体操作返回的文本。

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

文本输出的注解。

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

  • text: string

模型输出的文本内容。

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

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

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

多智能体结果的类型,固定为 multi_agent_call_output。

  • "multi_agent_call_output"

  • agent: optional object { agent_name }

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • ToolSearchCall object { id, arguments, call_id, 5 more }

  • id: string

工具搜索调用条目的唯一 ID。

  • arguments: unknown

工具搜索调用所用的参数。

  • call_id: string or null

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

  • execution: "server" or "client"

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

  • "server"

  • "client"

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

已记录的工具搜索调用条目的状态。

  • "in_progress"

  • "completed"

  • "incomplete"

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

条目类型,固定为 tool_search_call。

  • "tool_search_call"

  • agent: optional object { agent_name }

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • created_by: optional string

创建该条目的执行主体的标识。

  • ToolSearchOutput object { id, call_id, execution, 5 more }

  • id: string

工具搜索输出条目的唯一 ID。

  • call_id: string or null

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

  • execution: "server" or "client"

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

  • "server"

  • "client"

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

已记录的工具搜索输出条目的状态。

  • "in_progress"

  • "completed"

  • "incomplete"

  • 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 { key, type, value } or unknown 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

  • BetaCompoundFilter = unknown

使用 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日之后发布的模型中已弃用。远程MCP服务器改用server_url,安全MCP隧道连接改用tunnel_id。

当前支持的 connector_id 值如下:

Dropbox:connector_dropbox;Gmail:connector_gmail;Google Calendar:connector_googlecalendar;Google Drive:connector_googledrive;Microsoft Teams:connector_microsoftteams;Outlook Calendar:connector_outlookcalendar;Outlook Email: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 }

指定哪些工具需要批准,可选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 BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist

容器的网络访问策略。

  • BetaContainerNetworkPolicyDisabled object { type }

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

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

  • "disabled"

  • BetaContainerNetworkPolicyAllowlist 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 BetaContainerNetworkPolicyDomainSecret

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

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快照支持不透明和透明背景;gpt-image-2的透明背景为预览能力。使用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。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 BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference or null

  • BetaContainerAuto 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 BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist

容器的网络访问策略。

  • BetaContainerNetworkPolicyDisabled object { type }

  • BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }

  • skills: optional array of BetaSkillReference or BetaInlineSkill

可选技能列表,支持按 ID 引用或传入内联数据。列表中所有内联技能解码后的 ZIP 数据合计最多 50 MiB,Base64 文本含换行在内合计最多 70,254,592 个字符。技能引用不计入限制。

maxItems: 200

  • BetaSkillReference 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',省略时使用默认版本。

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

  • description: string

技能描述。

  • name: string

技能名称。

  • source: BetaInlineSkillSource

内联技能载荷。

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

  • BetaLocalEnvironment object { type, skills }

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

使用本地计算机环境。

  • "local"

  • skills: optional array of BetaLocalSkill

可选的技能列表。

maxItems: 200

  • description: string

技能描述。

  • name: string

技能名称。

  • path: string

包含该技能的目录路径。

  • BetaContainerReference 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 Text { type } or Grammar { definition, syntax, type }

自定义工具的输入格式,默认为无约束文本。

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

  • 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 Text { type } or Grammar { definition, syntax, type }

自定义工具的输入格式,默认为无约束文本。

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

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

  • agent: optional object { agent_name }

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • created_by: optional string

创建该条目的执行主体的标识。

  • AdditionalTools object { id, role, tools, 2 more }

  • id: string

额外工具条目的唯一 ID。

  • role: "unknown" or "user" or "assistant" or 5 more

提供额外工具的角色。

  • "unknown"

  • "user"

  • "assistant"

  • "system"

  • "critic"

  • "discriminator"

  • "developer"

  • "tool"

  • 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 { key, type, value } or unknown 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

  • BetaCompoundFilter = unknown

使用 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日之后发布的模型中已弃用。远程MCP服务器改用server_url,安全MCP隧道连接改用tunnel_id。

当前支持的 connector_id 值如下:

Dropbox:connector_dropbox;Gmail:connector_gmail;Google Calendar:connector_googlecalendar;Google Drive:connector_googledrive;Microsoft Teams:connector_microsoftteams;Outlook Calendar:connector_outlookcalendar;Outlook Email: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 }

指定哪些工具需要批准,可选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 BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist

容器的网络访问策略。

  • BetaContainerNetworkPolicyDisabled object { type }

  • BetaContainerNetworkPolicyAllowlist 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快照支持不透明和透明背景;gpt-image-2的透明背景为预览能力。使用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。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 BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference or null

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

  • BetaLocalEnvironment object { type, skills }

  • BetaContainerReference 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 Text { type } or Grammar { definition, syntax, type }

自定义工具的输入格式,默认为无约束文本。

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

  • 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 Text { type } or Grammar { definition, syntax, type }

自定义工具的输入格式,默认为无约束文本。

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

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

  • agent: optional object { agent_name }

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • AgentMessage object { id, author, content, 3 more }

  • id: string

此智能体消息的唯一 ID。

  • author: string

发送方智能体的标识。

  • content: array of BetaResponseInputText or BetaResponseOutputText or Text { text, type } or 7 more

智能体之间发送的加密内容。

  • BetaResponseInputText object { text, type, prompt_cache_breakpoint }

输入模型的文本。

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

模型输出的文本。

  • Text object { text, type }

文本内容。

  • text: string

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

  • "text"

  • SummaryText object { text, type }

模型生成的摘要文本。

  • text: string

模型到目前为止生成的推理输出摘要。

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

类型,固定为 summary_text。

  • "summary_text"

  • ReasoningText object { text, type }

模型生成的推理文本。

  • text: string

模型生成的推理文本。

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

类型,固定为 reasoning_text。

  • "reasoning_text"

  • BetaResponseOutputRefusal object { refusal, type }

模型的拒绝响应。

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

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

  • ComputerScreenshot object { detail, file_id, image_url, 2 more }

计算机屏幕截图。

  • detail: BetaImageDetail

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

  • file_id: string or null

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

  • image_url: string or null

截图图像的 URL。

format: uri

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

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

  • "computer_screenshot"

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

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

输入模型的文件。

  • EncryptedContent object { encrypted_content, type }

不透明的加密内容,由 Responses API 在受信任的模型执行环境中解密。

  • encrypted_content: string

不透明的加密内容。

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

输入条目的类型,固定为 encrypted_content。

  • "encrypted_content"

  • recipient: string

接收方智能体的标识。

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

条目类型,固定为 agent_message。

  • "agent_message"

  • agent: optional object { agent_name }

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

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

函数工具调用的输出。

  • output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile

你的代码产生的函数调用输出,可为字符串或输出内容列表。

  • StringOutput = string

函数调用输出的字符串。

  • OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile

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

  • BetaResponseInputText object { text, type, prompt_cache_breakpoint }

输入模型的文本。

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

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

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

输入模型的文件。

  • type: "function_call_output"

类型,固定为 function_call_output。

  • "function_call_output"

  • id: optional string

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

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • call_id: optional string

模型生成的函数工具调用的唯一 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"

  • name: optional string

产生输出的工具名称。

  • namespace: optional string

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

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

  • FileSearchCall object { id, queries, status, 3 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"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • 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

从文件中检索出的文本。

  • WebSearchCall object { id, status, type, 2 more }

网页搜索工具调用的结果,详见网页搜索指南。

  • 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

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • ImageGenerationCall object { id, result, status, 10 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"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • 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

  • ComputerCall object { id, call_id, pending_safety_checks, 5 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 BetaComputerAction

单击操作。

  • 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: 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 BetaComputerActionList

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 }

等待操作。

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • ComputerCallOutput object { id, call_id, output, 5 more }

  • id: string

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

  • call_id: string

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

  • output: BetaResponseComputerToolCallOutputScreenshot

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

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

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

  • "computer_screenshot"

  • file_id: optional string

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

  • image_url: optional string

截图图像的 URL。

format: uri

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

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

  • "completed"

  • "incomplete"

  • "failed"

  • "in_progress"

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

类型,固定为 computer_call_output。

  • "computer_call_output"

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

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

  • id: string

待处理安全检查的 ID。

  • code: optional string or null

待处理安全检查的类型。

  • message: optional string or null

待处理安全检查的详情。

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • created_by: optional string

创建该条目的执行主体的标识。

  • Reasoning object { id, summary, type, 4 more }

推理模型生成响应时所用思维链的描述。如果手动管理上下文,请在后续对话轮次发送给Responses API的input中包含这些条目。

  • id: string

推理内容的唯一标识。

  • summary: array of object { text, type }

推理摘要内容。

  • text: string

模型到目前为止生成的推理输出摘要。

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

类型,固定为 summary_text。

  • "summary_text"

  • type: "reasoning"

类型,固定为 reasoning。

  • "reasoning"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • 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中的加密内容可能不完整。在store为false或使用零数据保留时尤其重要。

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

  • Compaction object { id, encrypted_content, type, 2 more }

v1/responses/compact API生成的压缩条目。

  • id: string

压缩条目的唯一 ID。

  • encrypted_content: string

压缩生成的加密内容。

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

类型,固定为 compaction。

  • "compaction"

  • agent: optional object { agent_name }

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • created_by: optional string

创建该条目的执行主体的标识。

  • CodeInterpreterCall object { id, code, container_id, 4 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"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • LocalShellCall object { id, action, call_id, 3 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"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • LocalShellCallOutput object { id, output, type, 2 more }

本地 shell 工具调用的输出。

  • id: string

模型生成的本地 shell 工具调用的唯一 ID。

  • output: string

本地 shell 工具调用输出的 JSON 字符串。

  • type: "local_shell_call_output"

类型,固定为 local_shell_call_output。

  • "local_shell_call_output"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

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

条目状态,可选 in_progress、completed 或 incomplete。

  • "in_progress"

  • "completed"

  • "incomplete"

  • ShellCall object { id, action, call_id, 6 more }

在托管环境中执行一个或多个 shell 命令的工具调用。

  • id: string

shell 工具调用的唯一 ID,通过 API 返回此条目时填充。

  • action: object { commands, max_output_length, timeout_ms }

描述如何运行工具调用的 shell 命令及限制。

  • commands: array of string

  • max_output_length: integer or null

可选的每个命令返回的最大字符数。

  • timeout_ms: integer or null

可选的命令超时时长,单位为毫秒。

  • call_id: string

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

  • environment: BetaResponseLocalEnvironment or BetaResponseContainerReference or null

表示使用本地环境执行 shell 操作。

  • BetaResponseLocalEnvironment object { type }

表示使用本地环境执行 shell 操作。

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

环境类型,固定为 local。

  • "local"

  • BetaResponseContainerReference object { container_id, type }

表示通过 /v1/containers 创建的容器。

  • container_id: string

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

环境类型,固定为 container_reference。

  • "container_reference"

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

shell 调用状态,可选 in_progress、completed 或 incomplete。

  • "in_progress"

  • "completed"

  • "incomplete"

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

类型,固定为 shell_call。

  • "shell_call"

  • agent: optional object { agent_name }

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

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

  • created_by: optional string

创建此工具调用的实体的 ID。

  • ShellCallOutput object { id, call_id, max_output_length, 6 more }

shell 工具调用发出的输出。

  • id: string

shell 调用输出的唯一 ID,通过 API 返回此条目时填充。

  • call_id: string

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

  • max_output_length: integer or null

shell 命令输出的最大长度,由模型生成,应与原始输出一并回传。

  • output: array of object { outcome, stderr, stdout, created_by }

shell 调用输出内容的数组。

  • 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

捕获的标准错误输出。

  • stdout: string

捕获的标准输出。

  • created_by: optional string

创建该条目的执行主体的标识。

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

shell 调用输出的状态,可选 in_progress、completed 或 incomplete。

  • "in_progress"

  • "completed"

  • "incomplete"

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

shell 调用输出的类型,固定为 shell_call_output。

  • "shell_call_output"

  • agent: optional object { agent_name }

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

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

  • created_by: optional string

创建该条目的执行主体的标识。

  • ApplyPatchCall object { id, call_id, operation, 5 more }

通过创建、删除或更新文件来应用文件差异的工具调用。

  • id: string

apply_patch 工具调用的唯一 ID,通过 API 返回此条目时填充。

  • call_id: string

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

  • operation: CreateFile { diff, path, type } or DeleteFile { path, type } or UpdateFile { diff, path, type }

通过 apply_patch 应用的 create_file、delete_file 或 update_file 操作之一。

  • CreateFile object { diff, path, type }

描述如何通过 apply_patch 工具创建文件的指令。

  • diff: string

要应用的差异。

  • path: string

要创建的文件路径。

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

使用提供的差异创建新文件。

  • "create_file"

  • DeleteFile object { path, type }

描述如何通过 apply_patch 工具删除文件的指令。

  • path: string

要删除的文件路径。

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

删除指定文件。

  • "delete_file"

  • UpdateFile object { diff, path, type }

描述如何通过 apply_patch 工具更新文件的指令。

  • diff: string

要应用的差异。

  • path: string

要更新的文件路径。

  • type: "update_file" (default: "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"

  • agent: optional object { agent_name }

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

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

  • created_by: optional string

创建此工具调用的实体的 ID。

  • ApplyPatchCallOutput object { id, call_id, status, 5 more }

apply_patch 工具调用发出的输出。

  • id: string

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

  • call_id: string

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

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

  • agent: optional object { agent_name }

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

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

  • created_by: optional string

创建此工具调用输出的实体的 ID。

  • output: optional string or null

apply_patch 工具返回的可选文本输出。

  • McpListTools object { id, server_label, tools, 3 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"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • error: optional string or null

服务器无法列出工具时的错误消息。

  • McpApprovalRequest object { id, arguments, name, 3 more }

工具调用的人工批准请求。

  • id: string

批准请求的唯一 ID。

  • arguments: string

工具参数的 JSON 字符串。

  • name: string

要运行的工具名称。

  • server_label: string

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

  • type: "mcp_approval_request"

类型,固定为 mcp_approval_request。

  • "mcp_approval_request"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • McpApprovalResponse object { id, approval_request_id, approve, 3 more }

对 MCP 批准请求的响应。

  • id: string

批准响应的唯一 ID。

  • approval_request_id: string

所回应的批准请求的 ID。

  • approve: boolean

请求是否获准。

  • type: "mcp_approval_response"

类型,固定为 mcp_approval_response。

  • "mcp_approval_response"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • reason: optional string or null

决定的可选理由。

  • McpCall object { id, arguments, name, 7 more }

对 MCP 服务器上工具的调用。

  • id: string

工具调用的唯一 ID。

  • arguments: string

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

  • name: string

已运行的工具名称。

  • server_label: string

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

  • type: "mcp_call"

类型,固定为 mcp_call。

  • "mcp_call"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • approval_request_id: optional string or null

MCP工具调用批准请求的唯一标识。要批准或拒绝相应调用,应在后续mcp_approval_response输入中包含此值。

  • error: optional BetaMcpToolCallError 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"

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

模型生成的自定义工具调用。

  • call_id: string

用于将此自定义工具调用映射到工具调用输出的标识。

  • input: string

模型生成的自定义工具调用输入。

  • name: string

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

  • type: "custom_tool_call"

类型,固定为 custom_tool_call。

  • "custom_tool_call"

  • id: optional string

自定义工具调用在 OpenAI 平台中的唯一 ID。

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

  • 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

被调用的自定义工具所属的命名空间。

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

自有代码生成、回传给模型的自定义工具调用输出。

  • call_id: string

调用 ID,用于将此自定义工具调用输出映射到自定义工具调用。

  • output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile

你的代码生成的自定义工具输出,可为字符串或输出内容列表。

  • StringOutput = string

自定义工具调用输出的字符串。

  • OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile

自定义工具调用的文本、图像或文件输出。

  • BetaResponseInputText object { text, type, prompt_cache_breakpoint }

输入模型的文本。

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

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

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

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

生成该条目的智能体的规范名称。

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

  • usage: BetaResponseUsage

压缩过程的词元统计,包括缓存、推理和总词元数。

  • input_tokens: integer

输入词元数量。

  • input_tokens_details: object { cache_write_tokens, cached_tokens, cache_write_tokens_details }

输入词元的详细分类统计。

  • cache_write_tokens: integer

已写入缓存的输入词元数量。

  • cached_tokens: integer

从缓存读取的词元数量,详见提示词缓存。

  • cache_write_tokens_details: optional object { ttl_12h_tokens, ttl_30m_tokens }

  • ttl_12h_tokens: integer

以保留 12 小时的方式写入的输入词元数量。

  • ttl_30m_tokens: integer

以保留 30 分钟的方式写入的输入词元数量。

  • output_tokens: integer

输出词元数量。

  • output_tokens_details: object { reasoning_tokens }

输出词元的详细分类统计。

  • reasoning_tokens: integer

推理词元数量。

  • total_tokens: integer

使用的总词元数。

  • image: optional object { context_compression }

  • context_compression: "enabled" or "disabled"

实际采用的图像上下文优化策略。

  • "enabled"

  • "disabled"

示例

## 从环境变量读取 API 密钥,按需替换示例资源标识。
curl https://api.openai.com/v1/responses/compact \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
          "model": "gpt-6-astra",
          "previous_response_id": "resp_123"
        }'

200 响应示例

例中文字:总结我们上周的发布检查清单。 / 你正在执行上下文检查点压缩……

{
  "id": "resp_001",
  "created_at": 1731459200,
  "object": "response.compaction",
  "output": [
    {
      "id": "msg_001",
      "status": "completed",
      "type": "message",
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Summarize our launch checklist from last week."
        }
      ]
    },
    {
      "id": "msg_002",
      "status": "completed",
      "type": "message",
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "You are performing a CONTEXT CHECKPOINT COMPACTION..."
        }
      ]
    },
    {
      "type": "compaction",
      "id": "cmp_001",
      "encrypted_content": "encrypted-summary"
    }
  ],
  "usage": {
    "input_tokens": 42897,
    "input_tokens_details": {
      "cache_write_tokens": 0,
      "cached_tokens": 0,
      "cache_write_tokens_details": {
        "ttl_12h_tokens": 0,
        "ttl_30m_tokens": 0
      }
    },
    "output_tokens": 12000,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 54897
  },
  "image": {
    "context_compression": "disabled"
  }
}

示例

例中文字:为一家可以抚摸狗狗的咖啡馆创建简单落地页。 / 以下是可直接使用、单文件的抚狗咖啡馆落地页:……

## 从环境变量读取 API 密钥,按需替换示例资源标识。
curl -X POST https://api.openai.com/v1/responses/compact \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
      "model": "gpt-6-astra",
      "input": [
        {
          "role": "user",
          "content": "Create a simple landing page for a dog petting café."
        },
        {
          "id": "msg_001",
          "type": "message",
          "status": "completed",
          "content": [
            {
              "type": "output_text",
              "annotations": [],
              "logprobs": [],
              "text": "Below is a single file, ready-to-use landing page for a dog petting café:..."
            }
          ],
          "role": "assistant"
        }
      ]
    }'

响应示例

例中文字:为一家可以抚摸狗狗的咖啡馆创建简单落地页。

{
  "id": "resp_001",
  "object": "response.compaction",
  "created_at": 1764967971,
  "output": [
    {
      "id": "msg_000",
      "type": "message",
      "status": "completed",
      "content": [
        {
          "type": "input_text",
          "text": "Create a simple landing page for a dog petting cafe."
        }
      ],
      "role": "user"
    },
    {
      "id": "cmp_001",
      "type": "compaction",
      "encrypted_content": "gAAAAABpM0Yj-...="
    }
  ],
  "usage": {
    "input_tokens": 139,
    "input_tokens_details": {
      "cached_tokens": 0,
      "cache_write_tokens": 0
    },
    "output_tokens": 438,
    "output_tokens_details": {
      "reasoning_tokens": 64
    },
    "total_tokens": 577
  }
}
以上内容是否对您有帮助:
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号