OpenAI 多智能体流式事件

2026-11-19 17:50 更新

本页覆盖通用多智能体接口。专用网络安全访问配置未纳入此译稿。

创建Response时将stream设为true,服务器会在生成响应的同时向客户端发出SSE事件。本节列出服务端发出的事件。

处理compaction_trigger时,response.compaction.compacting最多每30秒报告一次新采样摘要输出,但不携带摘要内容,也不修改压缩输出条目。已有的response.output_item.added与response.output_item.done标记条目生命周期,后者携带最终加密内容。较短的压缩可能在未发出进度事件前就已完成。

详见流式响应。

response.created

创建响应时发出的事件。

结构定义

结构名称: BetaResponseCreatedEvent

  • response: BetaResponse

已创建的响应。

  • id: string

此响应的唯一标识符。

  • access_programs: object { cyber } or null

  • created_at: number

此响应创建时的 Unix 时间戳,单位为秒。

format: unixtime

  • error: BetaResponseError or null

模型未能生成响应时返回的错误对象。

  • code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 18 more

此响应的错误代码。

  • "server_error"

  • "rate_limit_exceeded"

  • "invalid_prompt"

  • "data_residency_mismatch"

  • "bio_policy"

  • "misalignment_policy_violation"

  • "vector_store_timeout"

  • "invalid_image"

  • "invalid_image_format"

  • "invalid_base64_image"

  • "invalid_image_url"

  • "image_too_large"

  • "image_too_small"

  • "image_parse_error"

  • "image_content_policy_violation"

  • "invalid_image_mode"

  • "image_file_too_large"

  • "unsupported_image_media_type"

  • "empty_image_file"

  • "failed_to_download_image"

  • "image_file_not_found"

  • message: string

便于人阅读的错误说明。

  • misalignment: optional object { detailed_explanation, error_type, review_target, steer }

  • detailed_explanation: optional string

对此次阻止操作的公开说明。

  • error_type: optional string or "potentially_unintended_data_transfer" or "potentially_unintended_data_access" or "potentially_unintended_destructive_activity" or "other"

可选的分类;客户端必须能够接受其他值。

  • string

  • SafetyAlertErrorType = "potentially_unintended_data_transfer" or "potentially_unintended_data_access" or "potentially_unintended_destructive_activity" or "other"

可选的分类;客户端必须能够接受其他值。

  • "potentially_unintended_data_transfer"

  • "potentially_unintended_data_access"

  • "potentially_unintended_destructive_activity"

  • "other"

  • review_target: optional string or null

用于明确继续此次审查的不透明目标;不可用时为 null。

pattern: ^[A-Za-z0-9._~:-]+$, minLength: 1, maxLength: 96

  • steer: optional object { message }

可选的公开继续指令。

  • message: string

公开的继续指令。

  • param: optional string or null

与错误相关的请求参数;未记录时为 null。

  • type: optional string or null

原始错误类型;未记录时为 null。

  • incomplete_details: object { reason } or null

说明响应为何未完成的详细信息。

  • reason: optional "max_output_tokens" or "max_messages" or "content_filter" or "steered"

响应未完成的原因。steered表示响应在收到WebSocket response.steer事件后于安全输出边界停止;服务器随后可自动使用排队输入创建后继响应。

  • "max_output_tokens"

  • "max_messages"

  • "content_filter"

  • "steered"

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

插入模型上下文的系统消息或开发者消息。

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

  • string

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

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

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

  • 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

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

  • metadata: map[string] or null

可附加到对象的一组16个键值对,用于结构化保存附加信息,并通过API或控制台查询对象。

键为最长64个字符的字符串,值为最长512个字符的字符串。

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

生成响应的模型ID,例如gpt-6.2-astra。OpenAI提供能力、性能和价格各异的模型,可在模型指南浏览比较。

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

生成响应的模型ID,例如gpt-6.2-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

  • object: "response"

此资源的对象类型,始终为 response。

  • "response"

  • output: array of BetaResponseOutputItem

模型生成的内容条目数组。

output数组的长度和顺序取决于模型响应。不要假定首个条目一定是包含生成内容的assistant消息;可考虑使用SDK支持的output_text属性。

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

模型输出的消息。

  • 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

从文件中检索出的文本。

  • 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 { id, output, status, 7 more }

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

输入模型的文件。

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

  • type: "function_call_output"

类型,固定为 function_call_output。

  • "function_call_output"

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

  • created_by: optional string

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

  • name: optional string

产生输出的工具名称。

  • namespace: optional 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

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

  • 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

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

  • 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

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

  • 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

单击操作。

  • actions: optional BetaComputerActionList

computer_use的扁平化批量操作。每个操作包含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

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

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

  • 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

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

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

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

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

  • 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

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

  • 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 { 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 工具返回的可选文本输出。

  • 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

工具调用的错误,如有。

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

  • 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

决定的可选理由。

  • 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 { id, call_id, output, 5 more }

  • id: string

自定义工具调用输出条目的唯一 ID。

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

输入模型的文件。

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

  • type: "custom_tool_call_output"

类型,固定为 custom_tool_call_output。

  • "custom_tool_call_output"

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

  • created_by: optional string

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

  • parallel_tool_calls: boolean (default: true)

是否允许模型并行执行工具调用。

  • temperature: number or null (default: 1)

采样温度,范围0到2。0.8等较高值使输出更随机,0.2等较低值使输出更集中、更确定。通常建议只修改此参数或top_p中的一个。

minimum: 0, maximum: 2

  • tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more

模型生成响应时如何选择工具,参见tools参数了解可调用工具的定义方式。

  • BetaToolChoiceOptions = "none" or "auto" or "required"

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

none 表示模型直接生成消息,不调用工具。

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

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

  • "none"

  • "auto"

  • "required"

  • BetaToolChoiceAllowed object { mode, tools, type }

将模型可用的工具限制为预先定义的集合。

  • mode: "auto" or "required"

将模型可用的工具限制为预先定义的集合。

auto 允许模型从可用工具中选择,或生成消息。

required 要求模型至少调用一个可用工具。

  • "auto"

  • "required"

  • tools: array of map[unknown]

应允许模型调用的工具定义列表。

对于 Responses API,工具定义列表可以如下所示:

        [
          { "type": "function", "name": "get_weather" },
          { "type": "mcp", "server_label": "deepwiki" },
          { "type": "image_generation" }
        ]

  • type: "allowed_tools"

允许的工具配置类型,固定为 allowed_tools。

  • "allowed_tools"

  • BetaToolChoiceTypes object { type }

指定模型应使用内置工具生成响应,详见内置工具。

  • type: "file_search" or "web_search_preview" or "computer" or 5 more

模型应使用的托管工具类型,详见内置工具。

允许的值为:

  • file_search
  • web_search_preview
  • computer
  • computer_use_preview
  • computer_use
  • code_interpreter
  • image_generation

  • "file_search"

  • "web_search_preview"

  • "computer"

  • "computer_use_preview"

  • "computer_use"

  • "web_search_preview_2025_03_11"

  • "image_generation"

  • "code_interpreter"

  • BetaToolChoiceFunction object { name, type }

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

  • name: string

要调用的函数名称。

  • type: "function"

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

  • "function"

  • BetaToolChoiceMcp object { server_label, type, name }

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

  • server_label: string

要使用的 MCP 服务器标签。

  • type: "mcp"

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

  • "mcp"

  • name: optional string or null

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

  • BetaToolChoiceCustom object { name, type }

使用此选项强制模型调用特定的自定义工具。

  • name: string

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

  • type: "custom"

对于自定义工具调用,类型固定为 custom。

  • "custom"

  • BetaSpecificProgrammaticToolCallingParam object { type }

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

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

  • "programmatic_tool_calling"

  • BetaToolChoiceApplyPatch object { type }

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

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

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

  • "apply_patch"

  • BetaToolChoiceShell object { type }

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

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

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

  • "shell"

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

模型生成响应时可以调用的工具数组。可以通过设置 tool_choice 参数指定使用哪个工具。

支持以下几类工具:

内置工具:OpenAI提供的扩展能力,如网页搜索和文件搜索,详见内置工具。MCP工具:通过自定义MCP服务器或Google Drive、SharePoint等预定义连接器集成第三方系统,详见MCP工具。函数调用(自定义工具):开发者定义的函数,让模型以强类型参数和输出调用你的代码,详见函数调用;也可使用自定义工具调用自己的代码。

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

  • top_p: number or null (default: 1)

核采样是温度采样的替代方式:模型仅考虑累计概率达到top_p的词元。例如0.1表示只考虑累计概率质量前10%的词元。

通常建议只调整此项或 temperature 中的一项,不同时调整两者。

minimum: 0, maximum: 1

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

是否在后台运行模型响应,详见后台模式。

  • completed_at: optional number or null

Response完成时的Unix时间戳,单位为秒,仅在状态为completed时存在。

format: unixtime

  • conversation: optional object { id } or null

此响应所属的对话。该响应的输入条目和输出条目已自动添加到此对话。

  • id: string

与此响应关联的对话的唯一 ID。

  • image: optional object { context_compression }

  • context_compression: "enabled" or "disabled"

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

  • "enabled"

  • "disabled"

  • input_transformations: optional array of object { id, action, reason, type }

未传给模型的推理输入,按输入顺序排列。

  • id: string

原始推理条目的 ID。

  • action: "removed" (default: "removed")

  • "removed"

  • reason: "organization_mismatch" or "end_user_mismatch" or "model_mismatch" or 2 more

  • "organization_mismatch"

  • "end_user_mismatch"

  • "model_mismatch"

  • "prefix_mismatch"

  • "turn_boundary"

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

  • "reasoning"

  • max_output_tokens: optional integer or null

响应可生成词元数的上限,包括可见输出词元及推理词元。

  • max_tool_calls: optional integer or null

一个响应中可处理的内置工具调用总次数上限。此上限适用于所有内置工具调用的合计次数,而非每个工具分别计算。达到上限后,模型进一步调用工具的尝试会被忽略。

  • moderation: optional object { input, output } or null

如果请求了经审核的补全,则包含响应输入和输出的审核结果。

  • input: ModerationResult { categories, category_applied_input_types, category_scores, 3 more } or Error { code, message, type }

对响应输入的审核。

  • ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }

针对响应输入或输出生成的审核结果。

  • categories: map[boolean]

审核类别到布尔值的映射。输入被某类别标记时,该类别值为 true。

  • category_applied_input_types: map[array of "text" or "image"]

各类别评分所涵盖的输入模态。

  • "text"

  • "image"

  • category_scores: map[number]

审核类别到分数的映射。

  • flagged: boolean

表示内容是否被任一类别标记的布尔值。

  • model: string

生成此结果的审核模型。

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

对象类型,成功审核结果中固定为 moderation_result。

  • "moderation_result"

  • Error object { code, message, type }

尝试审核响应输入或输出时产生的错误。

  • code: string

错误代码。

  • message: string

错误消息。

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

对象类型;审核失败时始终为 error。

  • "error"

  • output: ModerationResult { categories, category_applied_input_types, category_scores, 3 more } or Error { code, message, type }

对响应输出的审核。

  • ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }

针对响应输入或输出生成的审核结果。

  • categories: map[boolean]

审核类别到布尔值的映射。输入被某类别标记时,该类别值为 true。

  • category_applied_input_types: map[array of "text" or "image"]

各类别评分所涵盖的输入模态。

  • "text"

  • "image"

  • category_scores: map[number]

审核类别到分数的映射。

  • flagged: boolean

表示内容是否被任一类别标记的布尔值。

  • model: string

生成此结果的审核模型。

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

对象类型,成功审核结果中固定为 moderation_result。

  • "moderation_result"

  • Error object { code, message, type }

尝试审核响应输入或输出时产生的错误。

  • code: string

错误代码。

  • message: string

错误消息。

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

对象类型;审核失败时始终为 error。

  • "error"

  • output_text: optional string or null

仅SDK提供的便利属性,聚合output数组中所有output_text条目的文本(若存在),Python和JavaScript SDK支持此属性。

  • previous_response_id: optional string or null

前一次模型响应的唯一ID,用于多轮对话,详见对话状态。不能与conversation同时使用。

  • prompt: optional BetaResponsePrompt or null

提示词模板及其变量的引用,详见代码中的提示词版本。

  • id: string

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

  • variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile] or null

可选的变量替换映射,用于替换提示词中的变量。替换值可为字符串,也可为图像或文件等其他Response输入类型。

  • string

  • BetaResponseInputText object { text, type, prompt_cache_breakpoint }

输入模型的文本。

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

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

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

输入模型的文件。

  • version: optional string or null

提示词模板的可选版本。

  • prompt_cache_diagnostics: optional CacheMiss { cache_missed_tokens, reason, type, comparison_reusable_tokens } or CacheHit { type } or ComparisonResponseNotFound { type } or Unavailable { type }

为此响应请求的提示词缓存诊断信息。

  • CacheMiss object { cache_missed_tokens, reason, type, comparison_reusable_tokens }

  • cache_missed_tokens: integer

首次检测到差异之后,受影响的输入词元数量估计值。

  • reason: "model_changed" or "prompt_cache_key_changed" or "tools_changed" or 6 more

未复用提示词缓存的原因。

  • "model_changed"

  • "prompt_cache_key_changed"

  • "tools_changed"

  • "text_format_changed"

  • "reasoning_effort_changed"

  • "verbosity_changed"

  • "context_compacted"

  • "input_changed"

  • "service_tier_changed"

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

  • "cache_miss"

  • comparison_reusable_tokens: optional integer

在所比较的响应中,可复用前缀的原始词元数。

  • CacheHit object { type }

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

  • "cache_hit"

  • ComparisonResponseNotFound object { type }

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

  • "comparison_response_not_found"

  • Unavailable object { type }

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

  • "unavailable"

  • prompt_cache_key: optional string or null

供OpenAI缓存相似请求的响应,以优化缓存命中率,替代user字段,详见提示词缓存。

  • prompt_cache_options: optional object { mode, ttl, comparison_response_id }

应用于该响应的提示词缓存选项。支持 gpt-5.6 及更新模型。

  • mode: "implicit" or "explicit"

是否启用了隐式提示词缓存断点。

  • "implicit"

  • "explicit"

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

应用于每个缓存断点的最短保留时间。

  • "30m"

  • "12h"

  • comparison_response_id: optional string or null

用于提示词缓存诊断比较的响应 ID。

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

已弃用,改用 prompt_cache_options.ttl。

提示词缓存保留策略。设为24h启用扩展缓存,使缓存前缀保持活跃更久,最长24小时,详见缓存保留。此字段表达最长保留策略,prompt_cache_options.ttl表达最短缓存寿命;两者独立、互不影响。gpt-5.5、gpt-5.5-pro及后续模型仅支持24h。

对于同时支持 in_memory 和 24h 的较早模型,默认值取决于组织的数据保留策略:

未启用ZDR的组织默认使用24h;启用ZDR且未指定prompt_cache_retention的组织默认使用in_memory。

  • "in_memory"

  • "24h"

  • reasoning: optional object { context, effort, generate_summary, 2 more } or null

推理模型的配置选项。

  • context: optional "auto" or "current_turn" or "all_turns" or null

控制后续轮次向模型呈现哪些推理条目。省略或设为auto时由模型决定上下文模式。gpt-5.6系列默认all_turns,更早模型默认current_turn。

在响应中返回时,表示本次响应实际使用的推理上下文模式。

  • "auto"

  • "current_turn"

  • "all_turns"

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

限制推理模型的推理努力程度。目前支持none、minimal、low、medium、high、xhigh和max。降低努力程度可能加快响应并减少推理词元。并非所有模型支持每个值,具体见推理指南。

  • "none"

  • "minimal"

  • "low"

  • "medium"

  • "high"

  • "xhigh"

  • "max"

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

已弃用:请改用 summary。

模型推理的摘要,有助于调试和理解推理过程。可选auto、concise或detailed。

  • "auto"

  • "concise"

  • "detailed"

  • mode: optional string or "standard" or "pro"

控制请求的推理执行模式。

当此字段出现在返回的响应中时,表示实际使用的执行模式。

  • string

  • "standard" or "pro"

控制请求的推理执行模式。

当此字段出现在返回的响应中时,表示实际使用的执行模式。

  • "standard"

  • "pro"

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

模型推理的摘要,有助于调试和理解推理过程。可选auto、concise或detailed。

computer-use-preview 模型及 gpt-5 之后的推理模型均支持 concise。

  • "auto"

  • "concise"

  • "detailed"

  • safety_identifier: optional string or null

稳定的用户标识,帮助检测应用中可能违反OpenAI使用政策的用户。应使用唯一标识各用户、最长128字符的字符串。建议对用户名或电子邮箱进行哈希,避免发送个人身份信息,详见安全标识。

maxLength: 128

  • service_tier: optional BetaServiceTier or null (default: "auto")

指定处理请求所采用的服务类型。

auto使用项目设置中的服务层级,未另行配置时为default。default使用所选模型的标准价格及性能;flex使用Flex处理。在Responses或Chat Completions请求中设置service_tier=fast或service_tier=priority可启用快速模式,不论传入哪一个,原文此处写明响应显示priority。ultrafast使用受访问控制的Ultrafast层级,当前此原文列为可供gpt-5.6-sol使用,响应显示ultrafast。未设置时默认auto。

设置 service_tier 后,响应体中的同名字段反映实际采用的处理模式,可能与请求参数的值不同。

  • "auto"

  • "default"

  • "flex"

  • "scale"

  • "priority"

  • "fast"

  • "ultrafast"

  • status: optional BetaResponseStatus

响应生成状态,可选completed、failed、in_progress、cancelled、queued或incomplete。

  • "completed"

  • "failed"

  • "in_progress"

  • "cancelled"

  • "queued"

  • "incomplete"

  • text: optional BetaResponseTextConfig

模型文本响应的配置选项,可为纯文本或结构化JSON数据,详见下列指南。

文本输入与输出;结构化输出。

  • format: optional BetaResponseFormatTextConfig

指定模型必须输出的格式的对象。

配置{ "type": "json_schema" }可启用结构化输出,确保模型匹配提供的JSON Schema,详见结构化输出指南。

默认格式为 { "type": "text" },没有额外选项。

不建议用于 gpt-4o 及后续模型:

设置{ "type": "json_object" }可启用旧版JSON模式,确保模型生成合法JSON。支持json_schema的模型优先使用后者。

  • Text object { type }

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

  • type: "text"

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

  • "text"

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

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

  • JSONObject object { type }

JSON对象响应格式,是生成JSON响应的旧方式。支持json_schema的模型建议使用后者。注意,若system或user消息没有明确要求生成JSON,模型不会自行生成JSON。

  • type: "json_object"

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

  • "json_object"

  • verbosity: optional "low" or "medium" or "high" or null (default: "medium")

约束模型响应的详细程度。较低值生成更简洁的响应,较高值生成更详细的响应。目前支持low、medium和high,默认为medium。

  • "low"

  • "medium"

  • "high"

  • tool_usage: optional object { image_gen, web_search }

托管工具报告的用量,独立于基础模型的 usage。无法取得工具用量时可省略。若返回该字段,没有用量记录的工具类别计数为零。

image_gen 合计所有图像生成调用中可取得的词元计数。可能跳过用量记录不完整的调用。输出词元明细和缓存输入计数可省略,省略缓存计数表示缓存用量未知。

web_search.num_requests 统计可计费的搜索次数。打折搜索与打开网页等操作不计入。最终费用请以账单记录为准。

  • image_gen: object { input_tokens, input_tokens_details, output_tokens, 4 more }

图像生成工具调用的汇总用量统计。

  • input_tokens: integer

输入提示词中的图像与文本词元数量。

  • input_tokens_details: object { image_tokens, text_tokens }

图像生成的输入词元明细。

  • image_tokens: integer

输入提示词中的图像词元数量。

  • text_tokens: integer

输入提示词中的文本词元数量。

  • output_tokens: integer

模型生成的输出词元数量。

  • total_tokens: integer

图像生成使用的图像和文本词元总数。

  • cached_tokens: optional integer

  • cached_tokens_details: optional object { cached_image_tokens, cached_text_tokens }

  • cached_image_tokens: integer

  • cached_text_tokens: integer

  • output_tokens_details: optional object { image_tokens, text_tokens }

图像生成的输出词元明细。

  • image_tokens: integer

模型生成的图像输出词元数量。

  • text_tokens: integer

模型生成的文本输出词元数量。

  • web_search: object { num_requests }

网页搜索工具调用的汇总计费用量统计。

  • num_requests: integer

发起的计费网页搜索请求次数。

  • top_logprobs: optional integer or null

0到20之间的整数,指定每个词元位置返回多少个最可能词元及其对数概率;实际返回数量有时会少于请求值。

minimum: 0, maximum: 20

  • truncation: optional "auto" or "disabled" or null (default: "disabled")

模型响应的截断策略。

  • auto:输入超出模型的上下文窗口时,从对话开头移除条目以适配窗口。对部分模型,API 会先从输入上限扣除模型允许的最大输出量,再统计词元。因此,即使设置较低的 max_output_tokens,也可能更早开始截断。
  • disabled(默认值):输入超出模型上下文窗口时,请求会失败并返回 400 错误。

  • "auto"

  • "disabled"

  • usage: optional BetaResponseUsage or null

词元用量详情,包括输入词元、输出词元、输出词元分类和词元总数。

  • 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

使用的总词元数。

  • user: optional string or null

此字段正被safety_identifier和prompt_cache_key取代,维持缓存优化应改用prompt_cache_key。它是终端用户的稳定标识,通过更好地归类相似请求提高命中率,也帮助OpenAI检测和防止滥用,详见安全标识。

  • sequence_number: integer

此事件的序列号。

  • type: "response.created"

类型,固定为response.created。

  • "response.created"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.created",
  "response": {
    "id": "resp_67ccfcdd16748190a91872c75d38539e09e4d4aac714747c",
    "object": "response",
    "access_programs": null,
    "created_at": 1741487325,
    "status": "in_progress",
    "completed_at": null,
    "error": null,
    "incomplete_details": null,
    "instructions": null,
    "max_output_tokens": null,
    "model": "gpt-6.2-astra",
    "output": [],
    "parallel_tool_calls": true,
    "previous_response_id": null,
    "reasoning": {
      "effort": null,
      "summary": null
    },
    "store": true,
    "temperature": 1,
    "text": {
      "format": {
        "type": "text"
      }
    },
    "tool_choice": "auto",
    "tools": [],
    "top_p": 1,
    "truncation": "disabled",
    "usage": null,
    "user": null,
    "metadata": {}
  },
  "sequence_number": 1
}

response.in_progress

响应进行中时发出。

结构定义

结构名称: BetaResponseInProgressEvent

  • response: BetaResponse

正在进行的响应。

  • id: string

此响应的唯一标识符。

  • access_programs: object { cyber } or null

  • created_at: number

此响应创建时的 Unix 时间戳,单位为秒。

format: unixtime

  • error: BetaResponseError or null

模型未能生成响应时返回的错误对象。

  • code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 18 more

此响应的错误代码。

  • "server_error"

  • "rate_limit_exceeded"

  • "invalid_prompt"

  • "data_residency_mismatch"

  • "bio_policy"

  • "misalignment_policy_violation"

  • "vector_store_timeout"

  • "invalid_image"

  • "invalid_image_format"

  • "invalid_base64_image"

  • "invalid_image_url"

  • "image_too_large"

  • "image_too_small"

  • "image_parse_error"

  • "image_content_policy_violation"

  • "invalid_image_mode"

  • "image_file_too_large"

  • "unsupported_image_media_type"

  • "empty_image_file"

  • "failed_to_download_image"

  • "image_file_not_found"

  • message: string

便于人阅读的错误说明。

  • misalignment: optional object { detailed_explanation, error_type, review_target, steer }

  • detailed_explanation: optional string

对此次阻止操作的公开说明。

  • error_type: optional string or "potentially_unintended_data_transfer" or "potentially_unintended_data_access" or "potentially_unintended_destructive_activity" or "other"

可选的分类;客户端必须能够接受其他值。

  • string

  • SafetyAlertErrorType = "potentially_unintended_data_transfer" or "potentially_unintended_data_access" or "potentially_unintended_destructive_activity" or "other"

可选的分类;客户端必须能够接受其他值。

  • "potentially_unintended_data_transfer"

  • "potentially_unintended_data_access"

  • "potentially_unintended_destructive_activity"

  • "other"

  • review_target: optional string or null

用于明确继续此次审查的不透明目标;不可用时为 null。

pattern: ^[A-Za-z0-9._~:-]+$, minLength: 1, maxLength: 96

  • steer: optional object { message }

可选的公开继续指令。

  • message: string

公开的继续指令。

  • param: optional string or null

与错误相关的请求参数;未记录时为 null。

  • type: optional string or null

原始错误类型;未记录时为 null。

  • incomplete_details: object { reason } or null

说明响应为何未完成的详细信息。

  • reason: optional "max_output_tokens" or "max_messages" or "content_filter" or "steered"

响应未完成的原因。steered表示响应在收到WebSocket response.steer事件后于安全输出边界停止;服务器随后可自动使用排队输入创建后继响应。

  • "max_output_tokens"

  • "max_messages"

  • "content_filter"

  • "steered"

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

插入模型上下文的系统消息或开发者消息。

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

  • string

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

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

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

  • 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

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

  • metadata: map[string] or null

可附加到对象的一组16个键值对,用于结构化保存附加信息,并通过API或控制台查询对象。

键为最长64个字符的字符串,值为最长512个字符的字符串。

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

生成响应的模型ID,例如gpt-6.2-astra。OpenAI提供能力、性能和价格各异的模型,可在模型指南浏览比较。

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

生成响应的模型ID,例如gpt-6.2-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

  • object: "response"

此资源的对象类型,始终为 response。

  • "response"

  • output: array of BetaResponseOutputItem

模型生成的内容条目数组。

output数组的长度和顺序取决于模型响应。不要假定首个条目一定是包含生成内容的assistant消息;可考虑使用SDK支持的output_text属性。

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

模型输出的消息。

  • 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

从文件中检索出的文本。

  • 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 { id, output, status, 7 more }

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

输入模型的文件。

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

  • type: "function_call_output"

类型,固定为 function_call_output。

  • "function_call_output"

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

  • created_by: optional string

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

  • name: optional string

产生输出的工具名称。

  • namespace: optional 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

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

  • 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

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

  • 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

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

  • 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

单击操作。

  • actions: optional BetaComputerActionList

computer_use的扁平化批量操作。每个操作包含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

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

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

  • 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

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

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

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

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

  • 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

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

  • 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 { 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 工具返回的可选文本输出。

  • 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

工具调用的错误,如有。

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

  • 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

决定的可选理由。

  • 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 { id, call_id, output, 5 more }

  • id: string

自定义工具调用输出条目的唯一 ID。

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

输入模型的文件。

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

  • type: "custom_tool_call_output"

类型,固定为 custom_tool_call_output。

  • "custom_tool_call_output"

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

  • created_by: optional string

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

  • parallel_tool_calls: boolean (default: true)

是否允许模型并行执行工具调用。

  • temperature: number or null (default: 1)

采样温度,范围0到2。0.8等较高值使输出更随机,0.2等较低值使输出更集中、更确定。通常建议只修改此参数或top_p中的一个。

minimum: 0, maximum: 2

  • tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more

模型生成响应时如何选择工具,参见tools参数了解可调用工具的定义方式。

  • BetaToolChoiceOptions = "none" or "auto" or "required"

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

none 表示模型直接生成消息,不调用工具。

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

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

  • "none"

  • "auto"

  • "required"

  • BetaToolChoiceAllowed object { mode, tools, type }

将模型可用的工具限制为预先定义的集合。

  • mode: "auto" or "required"

将模型可用的工具限制为预先定义的集合。

auto 允许模型从可用工具中选择,或生成消息。

required 要求模型至少调用一个可用工具。

  • "auto"

  • "required"

  • tools: array of map[unknown]

应允许模型调用的工具定义列表。

对于 Responses API,工具定义列表可以如下所示:

        [
          { "type": "function", "name": "get_weather" },
          { "type": "mcp", "server_label": "deepwiki" },
          { "type": "image_generation" }
        ]

  • type: "allowed_tools"

允许的工具配置类型,固定为 allowed_tools。

  • "allowed_tools"

  • BetaToolChoiceTypes object { type }

指定模型应使用内置工具生成响应,详见内置工具。

  • type: "file_search" or "web_search_preview" or "computer" or 5 more

模型应使用的托管工具类型,详见内置工具。

允许的值为:

  • file_search
  • web_search_preview
  • computer
  • computer_use_preview
  • computer_use
  • code_interpreter
  • image_generation

  • "file_search"

  • "web_search_preview"

  • "computer"

  • "computer_use_preview"

  • "computer_use"

  • "web_search_preview_2025_03_11"

  • "image_generation"

  • "code_interpreter"

  • BetaToolChoiceFunction object { name, type }

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

  • name: string

要调用的函数名称。

  • type: "function"

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

  • "function"

  • BetaToolChoiceMcp object { server_label, type, name }

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

  • server_label: string

要使用的 MCP 服务器标签。

  • type: "mcp"

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

  • "mcp"

  • name: optional string or null

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

  • BetaToolChoiceCustom object { name, type }

使用此选项强制模型调用特定的自定义工具。

  • name: string

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

  • type: "custom"

对于自定义工具调用,类型固定为 custom。

  • "custom"

  • BetaSpecificProgrammaticToolCallingParam object { type }

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

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

  • "programmatic_tool_calling"

  • BetaToolChoiceApplyPatch object { type }

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

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

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

  • "apply_patch"

  • BetaToolChoiceShell object { type }

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

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

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

  • "shell"

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

模型生成响应时可以调用的工具数组。可以通过设置 tool_choice 参数指定使用哪个工具。

支持以下几类工具:

内置工具:OpenAI提供的扩展能力,如网页搜索和文件搜索,详见内置工具。MCP工具:通过自定义MCP服务器或Google Drive、SharePoint等预定义连接器集成第三方系统,详见MCP工具。函数调用(自定义工具):开发者定义的函数,让模型以强类型参数和输出调用你的代码,详见函数调用;也可使用自定义工具调用自己的代码。

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

  • top_p: number or null (default: 1)

核采样是温度采样的替代方式:模型仅考虑累计概率达到top_p的词元。例如0.1表示只考虑累计概率质量前10%的词元。

通常建议只调整此项或 temperature 中的一项,不同时调整两者。

minimum: 0, maximum: 1

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

是否在后台运行模型响应,详见后台模式。

  • completed_at: optional number or null

Response完成时的Unix时间戳,单位为秒,仅在状态为completed时存在。

format: unixtime

  • conversation: optional object { id } or null

此响应所属的对话。该响应的输入条目和输出条目已自动添加到此对话。

  • id: string

与此响应关联的对话的唯一 ID。

  • image: optional object { context_compression }

  • context_compression: "enabled" or "disabled"

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

  • "enabled"

  • "disabled"

  • input_transformations: optional array of object { id, action, reason, type }

未传给模型的推理输入,按输入顺序排列。

  • id: string

原始推理条目的 ID。

  • action: "removed" (default: "removed")

  • "removed"

  • reason: "organization_mismatch" or "end_user_mismatch" or "model_mismatch" or 2 more

  • "organization_mismatch"

  • "end_user_mismatch"

  • "model_mismatch"

  • "prefix_mismatch"

  • "turn_boundary"

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

  • "reasoning"

  • max_output_tokens: optional integer or null

响应可生成词元数的上限,包括可见输出词元及推理词元。

  • max_tool_calls: optional integer or null

一个响应中可处理的内置工具调用总次数上限。此上限适用于所有内置工具调用的合计次数,而非每个工具分别计算。达到上限后,模型进一步调用工具的尝试会被忽略。

  • moderation: optional object { input, output } or null

如果请求了经审核的补全,则包含响应输入和输出的审核结果。

  • input: ModerationResult { categories, category_applied_input_types, category_scores, 3 more } or Error { code, message, type }

对响应输入的审核。

  • ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }

针对响应输入或输出生成的审核结果。

  • categories: map[boolean]

审核类别到布尔值的映射。输入被某类别标记时,该类别值为 true。

  • category_applied_input_types: map[array of "text" or "image"]

各类别评分所涵盖的输入模态。

  • "text"

  • "image"

  • category_scores: map[number]

审核类别到分数的映射。

  • flagged: boolean

表示内容是否被任一类别标记的布尔值。

  • model: string

生成此结果的审核模型。

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

对象类型,成功审核结果中固定为 moderation_result。

  • "moderation_result"

  • Error object { code, message, type }

尝试审核响应输入或输出时产生的错误。

  • code: string

错误代码。

  • message: string

错误消息。

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

对象类型;审核失败时始终为 error。

  • "error"

  • output: ModerationResult { categories, category_applied_input_types, category_scores, 3 more } or Error { code, message, type }

对响应输出的审核。

  • ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }

针对响应输入或输出生成的审核结果。

  • categories: map[boolean]

审核类别到布尔值的映射。输入被某类别标记时,该类别值为 true。

  • category_applied_input_types: map[array of "text" or "image"]

各类别评分所涵盖的输入模态。

  • "text"

  • "image"

  • category_scores: map[number]

审核类别到分数的映射。

  • flagged: boolean

表示内容是否被任一类别标记的布尔值。

  • model: string

生成此结果的审核模型。

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

对象类型,成功审核结果中固定为 moderation_result。

  • "moderation_result"

  • Error object { code, message, type }

尝试审核响应输入或输出时产生的错误。

  • code: string

错误代码。

  • message: string

错误消息。

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

对象类型;审核失败时始终为 error。

  • "error"

  • output_text: optional string or null

仅SDK提供的便利属性,聚合output数组中所有output_text条目的文本(若存在),Python和JavaScript SDK支持此属性。

  • previous_response_id: optional string or null

前一次模型响应的唯一ID,用于多轮对话,详见对话状态。不能与conversation同时使用。

  • prompt: optional BetaResponsePrompt or null

提示词模板及其变量的引用,详见代码中的提示词版本。

  • id: string

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

  • variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile] or null

可选的变量替换映射,用于替换提示词中的变量。替换值可为字符串,也可为图像或文件等其他Response输入类型。

  • string

  • BetaResponseInputText object { text, type, prompt_cache_breakpoint }

输入模型的文本。

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

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

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

输入模型的文件。

  • version: optional string or null

提示词模板的可选版本。

  • prompt_cache_diagnostics: optional CacheMiss { cache_missed_tokens, reason, type, comparison_reusable_tokens } or CacheHit { type } or ComparisonResponseNotFound { type } or Unavailable { type }

为此响应请求的提示词缓存诊断信息。

  • CacheMiss object { cache_missed_tokens, reason, type, comparison_reusable_tokens }

  • cache_missed_tokens: integer

首次检测到差异之后,受影响的输入词元数量估计值。

  • reason: "model_changed" or "prompt_cache_key_changed" or "tools_changed" or 6 more

未复用提示词缓存的原因。

  • "model_changed"

  • "prompt_cache_key_changed"

  • "tools_changed"

  • "text_format_changed"

  • "reasoning_effort_changed"

  • "verbosity_changed"

  • "context_compacted"

  • "input_changed"

  • "service_tier_changed"

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

  • "cache_miss"

  • comparison_reusable_tokens: optional integer

在所比较的响应中,可复用前缀的原始词元数。

  • CacheHit object { type }

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

  • "cache_hit"

  • ComparisonResponseNotFound object { type }

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

  • "comparison_response_not_found"

  • Unavailable object { type }

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

  • "unavailable"

  • prompt_cache_key: optional string or null

供OpenAI缓存相似请求的响应,以优化缓存命中率,替代user字段,详见提示词缓存。

  • prompt_cache_options: optional object { mode, ttl, comparison_response_id }

应用于该响应的提示词缓存选项。支持 gpt-5.6 及更新模型。

  • mode: "implicit" or "explicit"

是否启用了隐式提示词缓存断点。

  • "implicit"

  • "explicit"

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

应用于每个缓存断点的最短保留时间。

  • "30m"

  • "12h"

  • comparison_response_id: optional string or null

用于提示词缓存诊断比较的响应 ID。

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

已弃用,改用 prompt_cache_options.ttl。

提示词缓存保留策略。设为24h启用扩展缓存,使缓存前缀保持活跃更久,最长24小时,详见缓存保留。此字段表达最长保留策略,prompt_cache_options.ttl表达最短缓存寿命;两者独立、互不影响。gpt-5.5、gpt-5.5-pro及后续模型仅支持24h。

对于同时支持 in_memory 和 24h 的较早模型,默认值取决于组织的数据保留策略:

未启用ZDR的组织默认使用24h;启用ZDR且未指定prompt_cache_retention的组织默认使用in_memory。

  • "in_memory"

  • "24h"

  • reasoning: optional object { context, effort, generate_summary, 2 more } or null

推理模型的配置选项。

  • context: optional "auto" or "current_turn" or "all_turns" or null

控制后续轮次向模型呈现哪些推理条目。省略或设为auto时由模型决定上下文模式。gpt-5.6系列默认all_turns,更早模型默认current_turn。

在响应中返回时,表示本次响应实际使用的推理上下文模式。

  • "auto"

  • "current_turn"

  • "all_turns"

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

限制推理模型的推理努力程度。目前支持none、minimal、low、medium、high、xhigh和max。降低努力程度可能加快响应并减少推理词元。并非所有模型支持每个值,具体见推理指南。

  • "none"

  • "minimal"

  • "low"

  • "medium"

  • "high"

  • "xhigh"

  • "max"

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

已弃用:请改用 summary。

模型推理的摘要,有助于调试和理解推理过程。可选auto、concise或detailed。

  • "auto"

  • "concise"

  • "detailed"

  • mode: optional string or "standard" or "pro"

控制请求的推理执行模式。

当此字段出现在返回的响应中时,表示实际使用的执行模式。

  • string

  • "standard" or "pro"

控制请求的推理执行模式。

当此字段出现在返回的响应中时,表示实际使用的执行模式。

  • "standard"

  • "pro"

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

模型推理的摘要,有助于调试和理解推理过程。可选auto、concise或detailed。

computer-use-preview 模型及 gpt-5 之后的推理模型均支持 concise。

  • "auto"

  • "concise"

  • "detailed"

  • safety_identifier: optional string or null

稳定的用户标识,帮助检测应用中可能违反OpenAI使用政策的用户。应使用唯一标识各用户、最长128字符的字符串。建议对用户名或电子邮箱进行哈希,避免发送个人身份信息,详见安全标识。

maxLength: 128

  • service_tier: optional BetaServiceTier or null (default: "auto")

指定处理请求所采用的服务类型。

auto使用项目设置中的服务层级,未另行配置时为default。default使用所选模型的标准价格及性能;flex使用Flex处理。在Responses或Chat Completions请求中设置service_tier=fast或service_tier=priority可启用快速模式,不论传入哪一个,原文此处写明响应显示priority。ultrafast使用受访问控制的Ultrafast层级,当前此原文列为可供gpt-5.6-sol使用,响应显示ultrafast。未设置时默认auto。

设置 service_tier 后,响应体中的同名字段反映实际采用的处理模式,可能与请求参数的值不同。

  • "auto"

  • "default"

  • "flex"

  • "scale"

  • "priority"

  • "fast"

  • "ultrafast"

  • status: optional BetaResponseStatus

响应生成状态,可选completed、failed、in_progress、cancelled、queued或incomplete。

  • "completed"

  • "failed"

  • "in_progress"

  • "cancelled"

  • "queued"

  • "incomplete"

  • text: optional BetaResponseTextConfig

模型文本响应的配置选项,可为纯文本或结构化JSON数据,详见下列指南。

文本输入与输出;结构化输出。

  • format: optional BetaResponseFormatTextConfig

指定模型必须输出的格式的对象。

配置{ "type": "json_schema" }可启用结构化输出,确保模型匹配提供的JSON Schema,详见结构化输出指南。

默认格式为 { "type": "text" },没有额外选项。

不建议用于 gpt-4o 及后续模型:

设置{ "type": "json_object" }可启用旧版JSON模式,确保模型生成合法JSON。支持json_schema的模型优先使用后者。

  • Text object { type }

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

  • type: "text"

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

  • "text"

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

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

  • JSONObject object { type }

JSON对象响应格式,是生成JSON响应的旧方式。支持json_schema的模型建议使用后者。注意,若system或user消息没有明确要求生成JSON,模型不会自行生成JSON。

  • type: "json_object"

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

  • "json_object"

  • verbosity: optional "low" or "medium" or "high" or null (default: "medium")

约束模型响应的详细程度。较低值生成更简洁的响应,较高值生成更详细的响应。目前支持low、medium和high,默认为medium。

  • "low"

  • "medium"

  • "high"

  • tool_usage: optional object { image_gen, web_search }

托管工具报告的用量,独立于基础模型的 usage。无法取得工具用量时可省略。若返回该字段,没有用量记录的工具类别计数为零。

image_gen 合计所有图像生成调用中可取得的词元计数。可能跳过用量记录不完整的调用。输出词元明细和缓存输入计数可省略,省略缓存计数表示缓存用量未知。

web_search.num_requests 统计可计费的搜索次数。打折搜索与打开网页等操作不计入。最终费用请以账单记录为准。

  • image_gen: object { input_tokens, input_tokens_details, output_tokens, 4 more }

图像生成工具调用的汇总用量统计。

  • input_tokens: integer

输入提示词中的图像与文本词元数量。

  • input_tokens_details: object { image_tokens, text_tokens }

图像生成的输入词元明细。

  • image_tokens: integer

输入提示词中的图像词元数量。

  • text_tokens: integer

输入提示词中的文本词元数量。

  • output_tokens: integer

模型生成的输出词元数量。

  • total_tokens: integer

图像生成使用的图像和文本词元总数。

  • cached_tokens: optional integer

  • cached_tokens_details: optional object { cached_image_tokens, cached_text_tokens }

  • cached_image_tokens: integer

  • cached_text_tokens: integer

  • output_tokens_details: optional object { image_tokens, text_tokens }

图像生成的输出词元明细。

  • image_tokens: integer

模型生成的图像输出词元数量。

  • text_tokens: integer

模型生成的文本输出词元数量。

  • web_search: object { num_requests }

网页搜索工具调用的汇总计费用量统计。

  • num_requests: integer

发起的计费网页搜索请求次数。

  • top_logprobs: optional integer or null

0到20之间的整数,指定每个词元位置返回多少个最可能词元及其对数概率;实际返回数量有时会少于请求值。

minimum: 0, maximum: 20

  • truncation: optional "auto" or "disabled" or null (default: "disabled")

模型响应的截断策略。

  • auto:输入超出模型的上下文窗口时,从对话开头移除条目以适配窗口。对部分模型,API 会先从输入上限扣除模型允许的最大输出量,再统计词元。因此,即使设置较低的 max_output_tokens,也可能更早开始截断。
  • disabled(默认值):输入超出模型上下文窗口时,请求会失败并返回 400 错误。

  • "auto"

  • "disabled"

  • usage: optional BetaResponseUsage or null

词元用量详情,包括输入词元、输出词元、输出词元分类和词元总数。

  • 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

使用的总词元数。

  • user: optional string or null

此字段正被safety_identifier和prompt_cache_key取代,维持缓存优化应改用prompt_cache_key。它是终端用户的稳定标识,通过更好地归类相似请求提高命中率,也帮助OpenAI检测和防止滥用,详见安全标识。

  • sequence_number: integer

事件序列号。

  • type: "response.in_progress"

类型,固定为response.in_progress。

  • "response.in_progress"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.in_progress",
  "response": {
    "id": "resp_67ccfcdd16748190a91872c75d38539e09e4d4aac714747c",
    "object": "response",
    "access_programs": null,
    "created_at": 1741487325,
    "status": "in_progress",
    "completed_at": null,
    "error": null,
    "incomplete_details": null,
    "instructions": null,
    "max_output_tokens": null,
    "model": "gpt-6.2-astra",
    "output": [],
    "parallel_tool_calls": true,
    "previous_response_id": null,
    "reasoning": {
      "effort": null,
      "summary": null
    },
    "store": true,
    "temperature": 1,
    "text": {
      "format": {
        "type": "text"
      }
    },
    "tool_choice": "auto",
    "tools": [],
    "top_p": 1,
    "truncation": "disabled",
    "usage": null,
    "user": null,
    "metadata": {}
  },
  "sequence_number": 1
}

response.completed

模型响应完成时发出。

结构定义

结构名称: BetaResponseCompletedEvent

  • response: BetaResponse

已完成响应的属性。

  • id: string

此响应的唯一标识符。

  • access_programs: object { cyber } or null

  • created_at: number

此响应创建时的 Unix 时间戳,单位为秒。

format: unixtime

  • error: BetaResponseError or null

模型未能生成响应时返回的错误对象。

  • code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 18 more

此响应的错误代码。

  • "server_error"

  • "rate_limit_exceeded"

  • "invalid_prompt"

  • "data_residency_mismatch"

  • "bio_policy"

  • "misalignment_policy_violation"

  • "vector_store_timeout"

  • "invalid_image"

  • "invalid_image_format"

  • "invalid_base64_image"

  • "invalid_image_url"

  • "image_too_large"

  • "image_too_small"

  • "image_parse_error"

  • "image_content_policy_violation"

  • "invalid_image_mode"

  • "image_file_too_large"

  • "unsupported_image_media_type"

  • "empty_image_file"

  • "failed_to_download_image"

  • "image_file_not_found"

  • message: string

便于人阅读的错误说明。

  • misalignment: optional object { detailed_explanation, error_type, review_target, steer }

  • detailed_explanation: optional string

对此次阻止操作的公开说明。

  • error_type: optional string or "potentially_unintended_data_transfer" or "potentially_unintended_data_access" or "potentially_unintended_destructive_activity" or "other"

可选的分类;客户端必须能够接受其他值。

  • string

  • SafetyAlertErrorType = "potentially_unintended_data_transfer" or "potentially_unintended_data_access" or "potentially_unintended_destructive_activity" or "other"

可选的分类;客户端必须能够接受其他值。

  • "potentially_unintended_data_transfer"

  • "potentially_unintended_data_access"

  • "potentially_unintended_destructive_activity"

  • "other"

  • review_target: optional string or null

用于明确继续此次审查的不透明目标;不可用时为 null。

pattern: ^[A-Za-z0-9._~:-]+$, minLength: 1, maxLength: 96

  • steer: optional object { message }

可选的公开继续指令。

  • message: string

公开的继续指令。

  • param: optional string or null

与错误相关的请求参数;未记录时为 null。

  • type: optional string or null

原始错误类型;未记录时为 null。

  • incomplete_details: object { reason } or null

说明响应为何未完成的详细信息。

  • reason: optional "max_output_tokens" or "max_messages" or "content_filter" or "steered"

响应未完成的原因。steered表示响应在收到WebSocket response.steer事件后于安全输出边界停止;服务器随后可自动使用排队输入创建后继响应。

  • "max_output_tokens"

  • "max_messages"

  • "content_filter"

  • "steered"

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

插入模型上下文的系统消息或开发者消息。

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

  • string

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

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

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

  • 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

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

  • metadata: map[string] or null

可附加到对象的一组16个键值对,用于结构化保存附加信息,并通过API或控制台查询对象。

键为最长64个字符的字符串,值为最长512个字符的字符串。

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

生成响应的模型ID,例如gpt-6.2-astra。OpenAI提供能力、性能和价格各异的模型,可在模型指南浏览比较。

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

生成响应的模型ID,例如gpt-6.2-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

  • object: "response"

此资源的对象类型,始终为 response。

  • "response"

  • output: array of BetaResponseOutputItem

模型生成的内容条目数组。

output数组的长度和顺序取决于模型响应。不要假定首个条目一定是包含生成内容的assistant消息;可考虑使用SDK支持的output_text属性。

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

模型输出的消息。

  • 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

从文件中检索出的文本。

  • 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 { id, output, status, 7 more }

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

输入模型的文件。

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

  • type: "function_call_output"

类型,固定为 function_call_output。

  • "function_call_output"

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

  • created_by: optional string

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

  • name: optional string

产生输出的工具名称。

  • namespace: optional 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

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

  • 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

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

  • 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

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

  • 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

单击操作。

  • actions: optional BetaComputerActionList

computer_use的扁平化批量操作。每个操作包含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

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

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

  • 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

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

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

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

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

  • 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

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

  • 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 { 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 工具返回的可选文本输出。

  • 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

工具调用的错误,如有。

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

  • 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

决定的可选理由。

  • 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 { id, call_id, output, 5 more }

  • id: string

自定义工具调用输出条目的唯一 ID。

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

输入模型的文件。

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

  • type: "custom_tool_call_output"

类型,固定为 custom_tool_call_output。

  • "custom_tool_call_output"

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

  • created_by: optional string

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

  • parallel_tool_calls: boolean (default: true)

是否允许模型并行执行工具调用。

  • temperature: number or null (default: 1)

采样温度,范围0到2。0.8等较高值使输出更随机,0.2等较低值使输出更集中、更确定。通常建议只修改此参数或top_p中的一个。

minimum: 0, maximum: 2

  • tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more

模型生成响应时如何选择工具,参见tools参数了解可调用工具的定义方式。

  • BetaToolChoiceOptions = "none" or "auto" or "required"

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

none 表示模型直接生成消息,不调用工具。

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

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

  • "none"

  • "auto"

  • "required"

  • BetaToolChoiceAllowed object { mode, tools, type }

将模型可用的工具限制为预先定义的集合。

  • mode: "auto" or "required"

将模型可用的工具限制为预先定义的集合。

auto 允许模型从可用工具中选择,或生成消息。

required 要求模型至少调用一个可用工具。

  • "auto"

  • "required"

  • tools: array of map[unknown]

应允许模型调用的工具定义列表。

对于 Responses API,工具定义列表可以如下所示:

        [
          { "type": "function", "name": "get_weather" },
          { "type": "mcp", "server_label": "deepwiki" },
          { "type": "image_generation" }
        ]

  • type: "allowed_tools"

允许的工具配置类型,固定为 allowed_tools。

  • "allowed_tools"

  • BetaToolChoiceTypes object { type }

指定模型应使用内置工具生成响应,详见内置工具。

  • type: "file_search" or "web_search_preview" or "computer" or 5 more

模型应使用的托管工具类型,详见内置工具。

允许的值为:

  • file_search
  • web_search_preview
  • computer
  • computer_use_preview
  • computer_use
  • code_interpreter
  • image_generation

  • "file_search"

  • "web_search_preview"

  • "computer"

  • "computer_use_preview"

  • "computer_use"

  • "web_search_preview_2025_03_11"

  • "image_generation"

  • "code_interpreter"

  • BetaToolChoiceFunction object { name, type }

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

  • name: string

要调用的函数名称。

  • type: "function"

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

  • "function"

  • BetaToolChoiceMcp object { server_label, type, name }

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

  • server_label: string

要使用的 MCP 服务器标签。

  • type: "mcp"

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

  • "mcp"

  • name: optional string or null

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

  • BetaToolChoiceCustom object { name, type }

使用此选项强制模型调用特定的自定义工具。

  • name: string

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

  • type: "custom"

对于自定义工具调用,类型固定为 custom。

  • "custom"

  • BetaSpecificProgrammaticToolCallingParam object { type }

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

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

  • "programmatic_tool_calling"

  • BetaToolChoiceApplyPatch object { type }

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

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

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

  • "apply_patch"

  • BetaToolChoiceShell object { type }

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

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

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

  • "shell"

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

模型生成响应时可以调用的工具数组。可以通过设置 tool_choice 参数指定使用哪个工具。

支持以下几类工具:

内置工具:OpenAI提供的扩展能力,如网页搜索和文件搜索,详见内置工具。MCP工具:通过自定义MCP服务器或Google Drive、SharePoint等预定义连接器集成第三方系统,详见MCP工具。函数调用(自定义工具):开发者定义的函数,让模型以强类型参数和输出调用你的代码,详见函数调用;也可使用自定义工具调用自己的代码。

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

  • top_p: number or null (default: 1)

核采样是温度采样的替代方式:模型仅考虑累计概率达到top_p的词元。例如0.1表示只考虑累计概率质量前10%的词元。

通常建议只调整此项或 temperature 中的一项,不同时调整两者。

minimum: 0, maximum: 1

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

是否在后台运行模型响应,详见后台模式。

  • completed_at: optional number or null

Response完成时的Unix时间戳,单位为秒,仅在状态为completed时存在。

format: unixtime

  • conversation: optional object { id } or null

此响应所属的对话。该响应的输入条目和输出条目已自动添加到此对话。

  • id: string

与此响应关联的对话的唯一 ID。

  • image: optional object { context_compression }

  • context_compression: "enabled" or "disabled"

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

  • "enabled"

  • "disabled"

  • input_transformations: optional array of object { id, action, reason, type }

未传给模型的推理输入,按输入顺序排列。

  • id: string

原始推理条目的 ID。

  • action: "removed" (default: "removed")

  • "removed"

  • reason: "organization_mismatch" or "end_user_mismatch" or "model_mismatch" or 2 more

  • "organization_mismatch"

  • "end_user_mismatch"

  • "model_mismatch"

  • "prefix_mismatch"

  • "turn_boundary"

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

  • "reasoning"

  • max_output_tokens: optional integer or null

响应可生成词元数的上限,包括可见输出词元及推理词元。

  • max_tool_calls: optional integer or null

一个响应中可处理的内置工具调用总次数上限。此上限适用于所有内置工具调用的合计次数,而非每个工具分别计算。达到上限后,模型进一步调用工具的尝试会被忽略。

  • moderation: optional object { input, output } or null

如果请求了经审核的补全,则包含响应输入和输出的审核结果。

  • input: ModerationResult { categories, category_applied_input_types, category_scores, 3 more } or Error { code, message, type }

对响应输入的审核。

  • ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }

针对响应输入或输出生成的审核结果。

  • categories: map[boolean]

审核类别到布尔值的映射。输入被某类别标记时,该类别值为 true。

  • category_applied_input_types: map[array of "text" or "image"]

各类别评分所涵盖的输入模态。

  • "text"

  • "image"

  • category_scores: map[number]

审核类别到分数的映射。

  • flagged: boolean

表示内容是否被任一类别标记的布尔值。

  • model: string

生成此结果的审核模型。

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

对象类型,成功审核结果中固定为 moderation_result。

  • "moderation_result"

  • Error object { code, message, type }

尝试审核响应输入或输出时产生的错误。

  • code: string

错误代码。

  • message: string

错误消息。

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

对象类型;审核失败时始终为 error。

  • "error"

  • output: ModerationResult { categories, category_applied_input_types, category_scores, 3 more } or Error { code, message, type }

对响应输出的审核。

  • ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }

针对响应输入或输出生成的审核结果。

  • categories: map[boolean]

审核类别到布尔值的映射。输入被某类别标记时,该类别值为 true。

  • category_applied_input_types: map[array of "text" or "image"]

各类别评分所涵盖的输入模态。

  • "text"

  • "image"

  • category_scores: map[number]

审核类别到分数的映射。

  • flagged: boolean

表示内容是否被任一类别标记的布尔值。

  • model: string

生成此结果的审核模型。

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

对象类型,成功审核结果中固定为 moderation_result。

  • "moderation_result"

  • Error object { code, message, type }

尝试审核响应输入或输出时产生的错误。

  • code: string

错误代码。

  • message: string

错误消息。

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

对象类型;审核失败时始终为 error。

  • "error"

  • output_text: optional string or null

仅SDK提供的便利属性,聚合output数组中所有output_text条目的文本(若存在),Python和JavaScript SDK支持此属性。

  • previous_response_id: optional string or null

前一次模型响应的唯一ID,用于多轮对话,详见对话状态。不能与conversation同时使用。

  • prompt: optional BetaResponsePrompt or null

提示词模板及其变量的引用,详见代码中的提示词版本。

  • id: string

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

  • variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile] or null

可选的变量替换映射,用于替换提示词中的变量。替换值可为字符串,也可为图像或文件等其他Response输入类型。

  • string

  • BetaResponseInputText object { text, type, prompt_cache_breakpoint }

输入模型的文本。

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

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

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

输入模型的文件。

  • version: optional string or null

提示词模板的可选版本。

  • prompt_cache_diagnostics: optional CacheMiss { cache_missed_tokens, reason, type, comparison_reusable_tokens } or CacheHit { type } or ComparisonResponseNotFound { type } or Unavailable { type }

为此响应请求的提示词缓存诊断信息。

  • CacheMiss object { cache_missed_tokens, reason, type, comparison_reusable_tokens }

  • cache_missed_tokens: integer

首次检测到差异之后,受影响的输入词元数量估计值。

  • reason: "model_changed" or "prompt_cache_key_changed" or "tools_changed" or 6 more

未复用提示词缓存的原因。

  • "model_changed"

  • "prompt_cache_key_changed"

  • "tools_changed"

  • "text_format_changed"

  • "reasoning_effort_changed"

  • "verbosity_changed"

  • "context_compacted"

  • "input_changed"

  • "service_tier_changed"

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

  • "cache_miss"

  • comparison_reusable_tokens: optional integer

在所比较的响应中,可复用前缀的原始词元数。

  • CacheHit object { type }

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

  • "cache_hit"

  • ComparisonResponseNotFound object { type }

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

  • "comparison_response_not_found"

  • Unavailable object { type }

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

  • "unavailable"

  • prompt_cache_key: optional string or null

供OpenAI缓存相似请求的响应,以优化缓存命中率,替代user字段,详见提示词缓存。

  • prompt_cache_options: optional object { mode, ttl, comparison_response_id }

应用于该响应的提示词缓存选项。支持 gpt-5.6 及更新模型。

  • mode: "implicit" or "explicit"

是否启用了隐式提示词缓存断点。

  • "implicit"

  • "explicit"

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

应用于每个缓存断点的最短保留时间。

  • "30m"

  • "12h"

  • comparison_response_id: optional string or null

用于提示词缓存诊断比较的响应 ID。

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

已弃用,改用 prompt_cache_options.ttl。

提示词缓存保留策略。设为24h启用扩展缓存,使缓存前缀保持活跃更久,最长24小时,详见缓存保留。此字段表达最长保留策略,prompt_cache_options.ttl表达最短缓存寿命;两者独立、互不影响。gpt-5.5、gpt-5.5-pro及后续模型仅支持24h。

对于同时支持 in_memory 和 24h 的较早模型,默认值取决于组织的数据保留策略:

未启用ZDR的组织默认使用24h;启用ZDR且未指定prompt_cache_retention的组织默认使用in_memory。

  • "in_memory"

  • "24h"

  • reasoning: optional object { context, effort, generate_summary, 2 more } or null

推理模型的配置选项。

  • context: optional "auto" or "current_turn" or "all_turns" or null

控制后续轮次向模型呈现哪些推理条目。省略或设为auto时由模型决定上下文模式。gpt-5.6系列默认all_turns,更早模型默认current_turn。

在响应中返回时,表示本次响应实际使用的推理上下文模式。

  • "auto"

  • "current_turn"

  • "all_turns"

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

限制推理模型的推理努力程度。目前支持none、minimal、low、medium、high、xhigh和max。降低努力程度可能加快响应并减少推理词元。并非所有模型支持每个值,具体见推理指南。

  • "none"

  • "minimal"

  • "low"

  • "medium"

  • "high"

  • "xhigh"

  • "max"

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

已弃用:请改用 summary。

模型推理的摘要,有助于调试和理解推理过程。可选auto、concise或detailed。

  • "auto"

  • "concise"

  • "detailed"

  • mode: optional string or "standard" or "pro"

控制请求的推理执行模式。

当此字段出现在返回的响应中时,表示实际使用的执行模式。

  • string

  • "standard" or "pro"

控制请求的推理执行模式。

当此字段出现在返回的响应中时,表示实际使用的执行模式。

  • "standard"

  • "pro"

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

模型推理的摘要,有助于调试和理解推理过程。可选auto、concise或detailed。

computer-use-preview 模型及 gpt-5 之后的推理模型均支持 concise。

  • "auto"

  • "concise"

  • "detailed"

  • safety_identifier: optional string or null

稳定的用户标识,帮助检测应用中可能违反OpenAI使用政策的用户。应使用唯一标识各用户、最长128字符的字符串。建议对用户名或电子邮箱进行哈希,避免发送个人身份信息,详见安全标识。

maxLength: 128

  • service_tier: optional BetaServiceTier or null (default: "auto")

指定处理请求所采用的服务类型。

auto使用项目设置中的服务层级,未另行配置时为default。default使用所选模型的标准价格及性能;flex使用Flex处理。在Responses或Chat Completions请求中设置service_tier=fast或service_tier=priority可启用快速模式,不论传入哪一个,原文此处写明响应显示priority。ultrafast使用受访问控制的Ultrafast层级,当前此原文列为可供gpt-5.6-sol使用,响应显示ultrafast。未设置时默认auto。

设置 service_tier 后,响应体中的同名字段反映实际采用的处理模式,可能与请求参数的值不同。

  • "auto"

  • "default"

  • "flex"

  • "scale"

  • "priority"

  • "fast"

  • "ultrafast"

  • status: optional BetaResponseStatus

响应生成状态,可选completed、failed、in_progress、cancelled、queued或incomplete。

  • "completed"

  • "failed"

  • "in_progress"

  • "cancelled"

  • "queued"

  • "incomplete"

  • text: optional BetaResponseTextConfig

模型文本响应的配置选项,可为纯文本或结构化JSON数据,详见下列指南。

文本输入与输出;结构化输出。

  • format: optional BetaResponseFormatTextConfig

指定模型必须输出的格式的对象。

配置{ "type": "json_schema" }可启用结构化输出,确保模型匹配提供的JSON Schema,详见结构化输出指南。

默认格式为 { "type": "text" },没有额外选项。

不建议用于 gpt-4o 及后续模型:

设置{ "type": "json_object" }可启用旧版JSON模式,确保模型生成合法JSON。支持json_schema的模型优先使用后者。

  • Text object { type }

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

  • type: "text"

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

  • "text"

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

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

  • JSONObject object { type }

JSON对象响应格式,是生成JSON响应的旧方式。支持json_schema的模型建议使用后者。注意,若system或user消息没有明确要求生成JSON,模型不会自行生成JSON。

  • type: "json_object"

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

  • "json_object"

  • verbosity: optional "low" or "medium" or "high" or null (default: "medium")

约束模型响应的详细程度。较低值生成更简洁的响应,较高值生成更详细的响应。目前支持low、medium和high,默认为medium。

  • "low"

  • "medium"

  • "high"

  • tool_usage: optional object { image_gen, web_search }

托管工具报告的用量,独立于基础模型的 usage。无法取得工具用量时可省略。若返回该字段,没有用量记录的工具类别计数为零。

image_gen 合计所有图像生成调用中可取得的词元计数。可能跳过用量记录不完整的调用。输出词元明细和缓存输入计数可省略,省略缓存计数表示缓存用量未知。

web_search.num_requests 统计可计费的搜索次数。打折搜索与打开网页等操作不计入。最终费用请以账单记录为准。

  • image_gen: object { input_tokens, input_tokens_details, output_tokens, 4 more }

图像生成工具调用的汇总用量统计。

  • input_tokens: integer

输入提示词中的图像与文本词元数量。

  • input_tokens_details: object { image_tokens, text_tokens }

图像生成的输入词元明细。

  • image_tokens: integer

输入提示词中的图像词元数量。

  • text_tokens: integer

输入提示词中的文本词元数量。

  • output_tokens: integer

模型生成的输出词元数量。

  • total_tokens: integer

图像生成使用的图像和文本词元总数。

  • cached_tokens: optional integer

  • cached_tokens_details: optional object { cached_image_tokens, cached_text_tokens }

  • cached_image_tokens: integer

  • cached_text_tokens: integer

  • output_tokens_details: optional object { image_tokens, text_tokens }

图像生成的输出词元明细。

  • image_tokens: integer

模型生成的图像输出词元数量。

  • text_tokens: integer

模型生成的文本输出词元数量。

  • web_search: object { num_requests }

网页搜索工具调用的汇总计费用量统计。

  • num_requests: integer

发起的计费网页搜索请求次数。

  • top_logprobs: optional integer or null

0到20之间的整数,指定每个词元位置返回多少个最可能词元及其对数概率;实际返回数量有时会少于请求值。

minimum: 0, maximum: 20

  • truncation: optional "auto" or "disabled" or null (default: "disabled")

模型响应的截断策略。

  • auto:输入超出模型的上下文窗口时,从对话开头移除条目以适配窗口。对部分模型,API 会先从输入上限扣除模型允许的最大输出量,再统计词元。因此,即使设置较低的 max_output_tokens,也可能更早开始截断。
  • disabled(默认值):输入超出模型上下文窗口时,请求会失败并返回 400 错误。

  • "auto"

  • "disabled"

  • usage: optional BetaResponseUsage or null

词元用量详情,包括输入词元、输出词元、输出词元分类和词元总数。

  • 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

使用的总词元数。

  • user: optional string or null

此字段正被safety_identifier和prompt_cache_key取代,维持缓存优化应改用prompt_cache_key。它是终端用户的稳定标识,通过更好地归类相似请求提高命中率,也帮助OpenAI检测和防止滥用,详见安全标识。

  • sequence_number: integer

此事件的序列号。

  • type: "response.completed"

类型,固定为response.completed。

  • "response.completed"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

例中文字:繁星下闪烁的森林里,孤独的独角兽Lila发现了一片泛着月光的小池塘。她每晚在岸边留下闪耀的魔法花朵,希望与他人分享美丽。某个迷人的夜晚,她醒来发现友善的小动物聚在身旁,渴望与她成为朋友、共享魔法。

{
  "type": "response.completed",
  "response": {
    "id": "resp_123",
    "object": "response",
    "access_programs": null,
    "created_at": 1740855869,
    "status": "completed",
    "completed_at": 1740855870,
    "error": null,
    "incomplete_details": null,
    "input": [],
    "instructions": null,
    "max_output_tokens": null,
    "model": "gpt-6.2-astra",
    "output": [
      {
        "id": "msg_123",
        "type": "message",
        "role": "assistant",
        "content": [
          {
            "type": "output_text",
            "text": "In a shimmering forest under a sky full of stars, a lonely unicorn named Lila discovered a hidden pond that glowed with moonlight. Every night, she would leave sparkling, magical flowers by the water's edge, hoping to share her beauty with others. One enchanting evening, she woke to find a group of friendly animals gathered around, eager to be friends and share in her magic.",
            "annotations": [],
            "logprobs": []
          }
        ],
        "status": "completed"
      }
    ],
    "previous_response_id": null,
    "reasoning_effort": null,
    "store": false,
    "temperature": 1,
    "text": {
      "format": {
        "type": "text"
      }
    },
    "tool_choice": "auto",
    "tools": [],
    "top_p": 1,
    "truncation": "disabled",
    "usage": {
      "input_tokens": 0,
      "output_tokens": 0,
      "output_tokens_details": {
        "reasoning_tokens": 0
      },
      "total_tokens": 0,
      "input_tokens_details": {
        "cached_tokens": 0,
        "cache_write_tokens": 0
      }
    },
    "user": null,
    "metadata": {},
    "parallel_tool_calls": true
  },
  "sequence_number": 1
}

response.failed

响应失败时发出的事件。

结构定义

结构名称: BetaResponseFailedEvent

  • response: BetaResponse

失败的响应。

  • id: string

此响应的唯一标识符。

  • access_programs: object { cyber } or null

  • created_at: number

此响应创建时的 Unix 时间戳,单位为秒。

format: unixtime

  • error: BetaResponseError or null

模型未能生成响应时返回的错误对象。

  • code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 18 more

此响应的错误代码。

  • "server_error"

  • "rate_limit_exceeded"

  • "invalid_prompt"

  • "data_residency_mismatch"

  • "bio_policy"

  • "misalignment_policy_violation"

  • "vector_store_timeout"

  • "invalid_image"

  • "invalid_image_format"

  • "invalid_base64_image"

  • "invalid_image_url"

  • "image_too_large"

  • "image_too_small"

  • "image_parse_error"

  • "image_content_policy_violation"

  • "invalid_image_mode"

  • "image_file_too_large"

  • "unsupported_image_media_type"

  • "empty_image_file"

  • "failed_to_download_image"

  • "image_file_not_found"

  • message: string

便于人阅读的错误说明。

  • misalignment: optional object { detailed_explanation, error_type, review_target, steer }

  • detailed_explanation: optional string

对此次阻止操作的公开说明。

  • error_type: optional string or "potentially_unintended_data_transfer" or "potentially_unintended_data_access" or "potentially_unintended_destructive_activity" or "other"

可选的分类;客户端必须能够接受其他值。

  • string

  • SafetyAlertErrorType = "potentially_unintended_data_transfer" or "potentially_unintended_data_access" or "potentially_unintended_destructive_activity" or "other"

可选的分类;客户端必须能够接受其他值。

  • "potentially_unintended_data_transfer"

  • "potentially_unintended_data_access"

  • "potentially_unintended_destructive_activity"

  • "other"

  • review_target: optional string or null

用于明确继续此次审查的不透明目标;不可用时为 null。

pattern: ^[A-Za-z0-9._~:-]+$, minLength: 1, maxLength: 96

  • steer: optional object { message }

可选的公开继续指令。

  • message: string

公开的继续指令。

  • param: optional string or null

与错误相关的请求参数;未记录时为 null。

  • type: optional string or null

原始错误类型;未记录时为 null。

  • incomplete_details: object { reason } or null

说明响应为何未完成的详细信息。

  • reason: optional "max_output_tokens" or "max_messages" or "content_filter" or "steered"

响应未完成的原因。steered表示响应在收到WebSocket response.steer事件后于安全输出边界停止;服务器随后可自动使用排队输入创建后继响应。

  • "max_output_tokens"

  • "max_messages"

  • "content_filter"

  • "steered"

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

插入模型上下文的系统消息或开发者消息。

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

  • string

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

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

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

  • 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

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

  • metadata: map[string] or null

可附加到对象的一组16个键值对,用于结构化保存附加信息,并通过API或控制台查询对象。

键为最长64个字符的字符串,值为最长512个字符的字符串。

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

生成响应的模型ID,例如gpt-6.2-astra。OpenAI提供能力、性能和价格各异的模型,可在模型指南浏览比较。

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

生成响应的模型ID,例如gpt-6.2-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

  • object: "response"

此资源的对象类型,始终为 response。

  • "response"

  • output: array of BetaResponseOutputItem

模型生成的内容条目数组。

output数组的长度和顺序取决于模型响应。不要假定首个条目一定是包含生成内容的assistant消息;可考虑使用SDK支持的output_text属性。

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

模型输出的消息。

  • 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

从文件中检索出的文本。

  • 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 { id, output, status, 7 more }

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

输入模型的文件。

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

  • type: "function_call_output"

类型,固定为 function_call_output。

  • "function_call_output"

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

  • created_by: optional string

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

  • name: optional string

产生输出的工具名称。

  • namespace: optional 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

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

  • 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

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

  • 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

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

  • 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

单击操作。

  • actions: optional BetaComputerActionList

computer_use的扁平化批量操作。每个操作包含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

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

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

  • 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

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

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

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

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

  • 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

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

  • 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 { 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 工具返回的可选文本输出。

  • 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

工具调用的错误,如有。

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

  • 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

决定的可选理由。

  • 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 { id, call_id, output, 5 more }

  • id: string

自定义工具调用输出条目的唯一 ID。

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

输入模型的文件。

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

  • type: "custom_tool_call_output"

类型,固定为 custom_tool_call_output。

  • "custom_tool_call_output"

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

  • created_by: optional string

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

  • parallel_tool_calls: boolean (default: true)

是否允许模型并行执行工具调用。

  • temperature: number or null (default: 1)

采样温度,范围0到2。0.8等较高值使输出更随机,0.2等较低值使输出更集中、更确定。通常建议只修改此参数或top_p中的一个。

minimum: 0, maximum: 2

  • tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more

模型生成响应时如何选择工具,参见tools参数了解可调用工具的定义方式。

  • BetaToolChoiceOptions = "none" or "auto" or "required"

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

none 表示模型直接生成消息,不调用工具。

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

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

  • "none"

  • "auto"

  • "required"

  • BetaToolChoiceAllowed object { mode, tools, type }

将模型可用的工具限制为预先定义的集合。

  • mode: "auto" or "required"

将模型可用的工具限制为预先定义的集合。

auto 允许模型从可用工具中选择,或生成消息。

required 要求模型至少调用一个可用工具。

  • "auto"

  • "required"

  • tools: array of map[unknown]

应允许模型调用的工具定义列表。

对于 Responses API,工具定义列表可以如下所示:

        [
          { "type": "function", "name": "get_weather" },
          { "type": "mcp", "server_label": "deepwiki" },
          { "type": "image_generation" }
        ]

  • type: "allowed_tools"

允许的工具配置类型,固定为 allowed_tools。

  • "allowed_tools"

  • BetaToolChoiceTypes object { type }

指定模型应使用内置工具生成响应,详见内置工具。

  • type: "file_search" or "web_search_preview" or "computer" or 5 more

模型应使用的托管工具类型,详见内置工具。

允许的值为:

  • file_search
  • web_search_preview
  • computer
  • computer_use_preview
  • computer_use
  • code_interpreter
  • image_generation

  • "file_search"

  • "web_search_preview"

  • "computer"

  • "computer_use_preview"

  • "computer_use"

  • "web_search_preview_2025_03_11"

  • "image_generation"

  • "code_interpreter"

  • BetaToolChoiceFunction object { name, type }

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

  • name: string

要调用的函数名称。

  • type: "function"

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

  • "function"

  • BetaToolChoiceMcp object { server_label, type, name }

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

  • server_label: string

要使用的 MCP 服务器标签。

  • type: "mcp"

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

  • "mcp"

  • name: optional string or null

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

  • BetaToolChoiceCustom object { name, type }

使用此选项强制模型调用特定的自定义工具。

  • name: string

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

  • type: "custom"

对于自定义工具调用,类型固定为 custom。

  • "custom"

  • BetaSpecificProgrammaticToolCallingParam object { type }

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

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

  • "programmatic_tool_calling"

  • BetaToolChoiceApplyPatch object { type }

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

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

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

  • "apply_patch"

  • BetaToolChoiceShell object { type }

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

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

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

  • "shell"

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

模型生成响应时可以调用的工具数组。可以通过设置 tool_choice 参数指定使用哪个工具。

支持以下几类工具:

内置工具:OpenAI提供的扩展能力,如网页搜索和文件搜索,详见内置工具。MCP工具:通过自定义MCP服务器或Google Drive、SharePoint等预定义连接器集成第三方系统,详见MCP工具。函数调用(自定义工具):开发者定义的函数,让模型以强类型参数和输出调用你的代码,详见函数调用;也可使用自定义工具调用自己的代码。

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

  • top_p: number or null (default: 1)

核采样是温度采样的替代方式:模型仅考虑累计概率达到top_p的词元。例如0.1表示只考虑累计概率质量前10%的词元。

通常建议只调整此项或 temperature 中的一项,不同时调整两者。

minimum: 0, maximum: 1

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

是否在后台运行模型响应,详见后台模式。

  • completed_at: optional number or null

Response完成时的Unix时间戳,单位为秒,仅在状态为completed时存在。

format: unixtime

  • conversation: optional object { id } or null

此响应所属的对话。该响应的输入条目和输出条目已自动添加到此对话。

  • id: string

与此响应关联的对话的唯一 ID。

  • image: optional object { context_compression }

  • context_compression: "enabled" or "disabled"

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

  • "enabled"

  • "disabled"

  • input_transformations: optional array of object { id, action, reason, type }

未传给模型的推理输入,按输入顺序排列。

  • id: string

原始推理条目的 ID。

  • action: "removed" (default: "removed")

  • "removed"

  • reason: "organization_mismatch" or "end_user_mismatch" or "model_mismatch" or 2 more

  • "organization_mismatch"

  • "end_user_mismatch"

  • "model_mismatch"

  • "prefix_mismatch"

  • "turn_boundary"

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

  • "reasoning"

  • max_output_tokens: optional integer or null

响应可生成词元数的上限,包括可见输出词元及推理词元。

  • max_tool_calls: optional integer or null

一个响应中可处理的内置工具调用总次数上限。此上限适用于所有内置工具调用的合计次数,而非每个工具分别计算。达到上限后,模型进一步调用工具的尝试会被忽略。

  • moderation: optional object { input, output } or null

如果请求了经审核的补全,则包含响应输入和输出的审核结果。

  • input: ModerationResult { categories, category_applied_input_types, category_scores, 3 more } or Error { code, message, type }

对响应输入的审核。

  • ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }

针对响应输入或输出生成的审核结果。

  • categories: map[boolean]

审核类别到布尔值的映射。输入被某类别标记时,该类别值为 true。

  • category_applied_input_types: map[array of "text" or "image"]

各类别评分所涵盖的输入模态。

  • "text"

  • "image"

  • category_scores: map[number]

审核类别到分数的映射。

  • flagged: boolean

表示内容是否被任一类别标记的布尔值。

  • model: string

生成此结果的审核模型。

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

对象类型,成功审核结果中固定为 moderation_result。

  • "moderation_result"

  • Error object { code, message, type }

尝试审核响应输入或输出时产生的错误。

  • code: string

错误代码。

  • message: string

错误消息。

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

对象类型;审核失败时始终为 error。

  • "error"

  • output: ModerationResult { categories, category_applied_input_types, category_scores, 3 more } or Error { code, message, type }

对响应输出的审核。

  • ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }

针对响应输入或输出生成的审核结果。

  • categories: map[boolean]

审核类别到布尔值的映射。输入被某类别标记时,该类别值为 true。

  • category_applied_input_types: map[array of "text" or "image"]

各类别评分所涵盖的输入模态。

  • "text"

  • "image"

  • category_scores: map[number]

审核类别到分数的映射。

  • flagged: boolean

表示内容是否被任一类别标记的布尔值。

  • model: string

生成此结果的审核模型。

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

对象类型,成功审核结果中固定为 moderation_result。

  • "moderation_result"

  • Error object { code, message, type }

尝试审核响应输入或输出时产生的错误。

  • code: string

错误代码。

  • message: string

错误消息。

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

对象类型;审核失败时始终为 error。

  • "error"

  • output_text: optional string or null

仅SDK提供的便利属性,聚合output数组中所有output_text条目的文本(若存在),Python和JavaScript SDK支持此属性。

  • previous_response_id: optional string or null

前一次模型响应的唯一ID,用于多轮对话,详见对话状态。不能与conversation同时使用。

  • prompt: optional BetaResponsePrompt or null

提示词模板及其变量的引用,详见代码中的提示词版本。

  • id: string

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

  • variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile] or null

可选的变量替换映射,用于替换提示词中的变量。替换值可为字符串,也可为图像或文件等其他Response输入类型。

  • string

  • BetaResponseInputText object { text, type, prompt_cache_breakpoint }

输入模型的文本。

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

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

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

输入模型的文件。

  • version: optional string or null

提示词模板的可选版本。

  • prompt_cache_diagnostics: optional CacheMiss { cache_missed_tokens, reason, type, comparison_reusable_tokens } or CacheHit { type } or ComparisonResponseNotFound { type } or Unavailable { type }

为此响应请求的提示词缓存诊断信息。

  • CacheMiss object { cache_missed_tokens, reason, type, comparison_reusable_tokens }

  • cache_missed_tokens: integer

首次检测到差异之后,受影响的输入词元数量估计值。

  • reason: "model_changed" or "prompt_cache_key_changed" or "tools_changed" or 6 more

未复用提示词缓存的原因。

  • "model_changed"

  • "prompt_cache_key_changed"

  • "tools_changed"

  • "text_format_changed"

  • "reasoning_effort_changed"

  • "verbosity_changed"

  • "context_compacted"

  • "input_changed"

  • "service_tier_changed"

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

  • "cache_miss"

  • comparison_reusable_tokens: optional integer

在所比较的响应中,可复用前缀的原始词元数。

  • CacheHit object { type }

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

  • "cache_hit"

  • ComparisonResponseNotFound object { type }

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

  • "comparison_response_not_found"

  • Unavailable object { type }

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

  • "unavailable"

  • prompt_cache_key: optional string or null

供OpenAI缓存相似请求的响应,以优化缓存命中率,替代user字段,详见提示词缓存。

  • prompt_cache_options: optional object { mode, ttl, comparison_response_id }

应用于该响应的提示词缓存选项。支持 gpt-5.6 及更新模型。

  • mode: "implicit" or "explicit"

是否启用了隐式提示词缓存断点。

  • "implicit"

  • "explicit"

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

应用于每个缓存断点的最短保留时间。

  • "30m"

  • "12h"

  • comparison_response_id: optional string or null

用于提示词缓存诊断比较的响应 ID。

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

已弃用,改用 prompt_cache_options.ttl。

提示词缓存保留策略。设为24h启用扩展缓存,使缓存前缀保持活跃更久,最长24小时,详见缓存保留。此字段表达最长保留策略,prompt_cache_options.ttl表达最短缓存寿命;两者独立、互不影响。gpt-5.5、gpt-5.5-pro及后续模型仅支持24h。

对于同时支持 in_memory 和 24h 的较早模型,默认值取决于组织的数据保留策略:

未启用ZDR的组织默认使用24h;启用ZDR且未指定prompt_cache_retention的组织默认使用in_memory。

  • "in_memory"

  • "24h"

  • reasoning: optional object { context, effort, generate_summary, 2 more } or null

推理模型的配置选项。

  • context: optional "auto" or "current_turn" or "all_turns" or null

控制后续轮次向模型呈现哪些推理条目。省略或设为auto时由模型决定上下文模式。gpt-5.6系列默认all_turns,更早模型默认current_turn。

在响应中返回时,表示本次响应实际使用的推理上下文模式。

  • "auto"

  • "current_turn"

  • "all_turns"

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

限制推理模型的推理努力程度。目前支持none、minimal、low、medium、high、xhigh和max。降低努力程度可能加快响应并减少推理词元。并非所有模型支持每个值,具体见推理指南。

  • "none"

  • "minimal"

  • "low"

  • "medium"

  • "high"

  • "xhigh"

  • "max"

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

已弃用:请改用 summary。

模型推理的摘要,有助于调试和理解推理过程。可选auto、concise或detailed。

  • "auto"

  • "concise"

  • "detailed"

  • mode: optional string or "standard" or "pro"

控制请求的推理执行模式。

当此字段出现在返回的响应中时,表示实际使用的执行模式。

  • string

  • "standard" or "pro"

控制请求的推理执行模式。

当此字段出现在返回的响应中时,表示实际使用的执行模式。

  • "standard"

  • "pro"

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

模型推理的摘要,有助于调试和理解推理过程。可选auto、concise或detailed。

computer-use-preview 模型及 gpt-5 之后的推理模型均支持 concise。

  • "auto"

  • "concise"

  • "detailed"

  • safety_identifier: optional string or null

稳定的用户标识,帮助检测应用中可能违反OpenAI使用政策的用户。应使用唯一标识各用户、最长128字符的字符串。建议对用户名或电子邮箱进行哈希,避免发送个人身份信息,详见安全标识。

maxLength: 128

  • service_tier: optional BetaServiceTier or null (default: "auto")

指定处理请求所采用的服务类型。

auto使用项目设置中的服务层级,未另行配置时为default。default使用所选模型的标准价格及性能;flex使用Flex处理。在Responses或Chat Completions请求中设置service_tier=fast或service_tier=priority可启用快速模式,不论传入哪一个,原文此处写明响应显示priority。ultrafast使用受访问控制的Ultrafast层级,当前此原文列为可供gpt-5.6-sol使用,响应显示ultrafast。未设置时默认auto。

设置 service_tier 后,响应体中的同名字段反映实际采用的处理模式,可能与请求参数的值不同。

  • "auto"

  • "default"

  • "flex"

  • "scale"

  • "priority"

  • "fast"

  • "ultrafast"

  • status: optional BetaResponseStatus

响应生成状态,可选completed、failed、in_progress、cancelled、queued或incomplete。

  • "completed"

  • "failed"

  • "in_progress"

  • "cancelled"

  • "queued"

  • "incomplete"

  • text: optional BetaResponseTextConfig

模型文本响应的配置选项,可为纯文本或结构化JSON数据,详见下列指南。

文本输入与输出;结构化输出。

  • format: optional BetaResponseFormatTextConfig

指定模型必须输出的格式的对象。

配置{ "type": "json_schema" }可启用结构化输出,确保模型匹配提供的JSON Schema,详见结构化输出指南。

默认格式为 { "type": "text" },没有额外选项。

不建议用于 gpt-4o 及后续模型:

设置{ "type": "json_object" }可启用旧版JSON模式,确保模型生成合法JSON。支持json_schema的模型优先使用后者。

  • Text object { type }

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

  • type: "text"

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

  • "text"

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

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

  • JSONObject object { type }

JSON对象响应格式,是生成JSON响应的旧方式。支持json_schema的模型建议使用后者。注意,若system或user消息没有明确要求生成JSON,模型不会自行生成JSON。

  • type: "json_object"

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

  • "json_object"

  • verbosity: optional "low" or "medium" or "high" or null (default: "medium")

约束模型响应的详细程度。较低值生成更简洁的响应,较高值生成更详细的响应。目前支持low、medium和high,默认为medium。

  • "low"

  • "medium"

  • "high"

  • tool_usage: optional object { image_gen, web_search }

托管工具报告的用量,独立于基础模型的 usage。无法取得工具用量时可省略。若返回该字段,没有用量记录的工具类别计数为零。

image_gen 合计所有图像生成调用中可取得的词元计数。可能跳过用量记录不完整的调用。输出词元明细和缓存输入计数可省略,省略缓存计数表示缓存用量未知。

web_search.num_requests 统计可计费的搜索次数。打折搜索与打开网页等操作不计入。最终费用请以账单记录为准。

  • image_gen: object { input_tokens, input_tokens_details, output_tokens, 4 more }

图像生成工具调用的汇总用量统计。

  • input_tokens: integer

输入提示词中的图像与文本词元数量。

  • input_tokens_details: object { image_tokens, text_tokens }

图像生成的输入词元明细。

  • image_tokens: integer

输入提示词中的图像词元数量。

  • text_tokens: integer

输入提示词中的文本词元数量。

  • output_tokens: integer

模型生成的输出词元数量。

  • total_tokens: integer

图像生成使用的图像和文本词元总数。

  • cached_tokens: optional integer

  • cached_tokens_details: optional object { cached_image_tokens, cached_text_tokens }

  • cached_image_tokens: integer

  • cached_text_tokens: integer

  • output_tokens_details: optional object { image_tokens, text_tokens }

图像生成的输出词元明细。

  • image_tokens: integer

模型生成的图像输出词元数量。

  • text_tokens: integer

模型生成的文本输出词元数量。

  • web_search: object { num_requests }

网页搜索工具调用的汇总计费用量统计。

  • num_requests: integer

发起的计费网页搜索请求次数。

  • top_logprobs: optional integer or null

0到20之间的整数,指定每个词元位置返回多少个最可能词元及其对数概率;实际返回数量有时会少于请求值。

minimum: 0, maximum: 20

  • truncation: optional "auto" or "disabled" or null (default: "disabled")

模型响应的截断策略。

  • auto:输入超出模型的上下文窗口时,从对话开头移除条目以适配窗口。对部分模型,API 会先从输入上限扣除模型允许的最大输出量,再统计词元。因此,即使设置较低的 max_output_tokens,也可能更早开始截断。
  • disabled(默认值):输入超出模型上下文窗口时,请求会失败并返回 400 错误。

  • "auto"

  • "disabled"

  • usage: optional BetaResponseUsage or null

词元用量详情,包括输入词元、输出词元、输出词元分类和词元总数。

  • 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

使用的总词元数。

  • user: optional string or null

此字段正被safety_identifier和prompt_cache_key取代,维持缓存优化应改用prompt_cache_key。它是终端用户的稳定标识,通过更好地归类相似请求提高命中率,也帮助OpenAI检测和防止滥用,详见安全标识。

  • sequence_number: integer

事件序列号。

  • type: "response.failed"

类型,固定为response.failed。

  • "response.failed"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

例中文字:模型未能生成响应。

{
  "type": "response.failed",
  "response": {
    "id": "resp_123",
    "object": "response",
    "access_programs": null,
    "created_at": 1740855869,
    "status": "failed",
    "completed_at": null,
    "error": {
      "code": "server_error",
      "message": "The model failed to generate a response."
    },
    "incomplete_details": null,
    "instructions": null,
    "max_output_tokens": null,
    "model": "gpt-6.2-astra",
    "output": [],
    "previous_response_id": null,
    "reasoning_effort": null,
    "store": false,
    "temperature": 1,
    "text": {
      "format": {
        "type": "text"
      }
    },
    "tool_choice": "auto",
    "tools": [],
    "top_p": 1,
    "truncation": "disabled",
    "usage": null,
    "user": null,
    "metadata": {},
    "parallel_tool_calls": true
  },
  "sequence_number": 1
}

response.incomplete

响应以未完成状态结束时发出。

WebSocket中的转向输入可使响应以response.incomplete_details.reason: steered结束;随后服务器自动发出后继response.created,提交排队的转向输入。

结构定义

结构名称: BetaResponseIncompleteEvent

  • response: BetaResponse

未完成的响应。

  • id: string

此响应的唯一标识符。

  • access_programs: object { cyber } or null

  • created_at: number

此响应创建时的 Unix 时间戳,单位为秒。

format: unixtime

  • error: BetaResponseError or null

模型未能生成响应时返回的错误对象。

  • code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 18 more

此响应的错误代码。

  • "server_error"

  • "rate_limit_exceeded"

  • "invalid_prompt"

  • "data_residency_mismatch"

  • "bio_policy"

  • "misalignment_policy_violation"

  • "vector_store_timeout"

  • "invalid_image"

  • "invalid_image_format"

  • "invalid_base64_image"

  • "invalid_image_url"

  • "image_too_large"

  • "image_too_small"

  • "image_parse_error"

  • "image_content_policy_violation"

  • "invalid_image_mode"

  • "image_file_too_large"

  • "unsupported_image_media_type"

  • "empty_image_file"

  • "failed_to_download_image"

  • "image_file_not_found"

  • message: string

便于人阅读的错误说明。

  • misalignment: optional object { detailed_explanation, error_type, review_target, steer }

  • detailed_explanation: optional string

对此次阻止操作的公开说明。

  • error_type: optional string or "potentially_unintended_data_transfer" or "potentially_unintended_data_access" or "potentially_unintended_destructive_activity" or "other"

可选的分类;客户端必须能够接受其他值。

  • string

  • SafetyAlertErrorType = "potentially_unintended_data_transfer" or "potentially_unintended_data_access" or "potentially_unintended_destructive_activity" or "other"

可选的分类;客户端必须能够接受其他值。

  • "potentially_unintended_data_transfer"

  • "potentially_unintended_data_access"

  • "potentially_unintended_destructive_activity"

  • "other"

  • review_target: optional string or null

用于明确继续此次审查的不透明目标;不可用时为 null。

pattern: ^[A-Za-z0-9._~:-]+$, minLength: 1, maxLength: 96

  • steer: optional object { message }

可选的公开继续指令。

  • message: string

公开的继续指令。

  • param: optional string or null

与错误相关的请求参数;未记录时为 null。

  • type: optional string or null

原始错误类型;未记录时为 null。

  • incomplete_details: object { reason } or null

说明响应为何未完成的详细信息。

  • reason: optional "max_output_tokens" or "max_messages" or "content_filter" or "steered"

响应未完成的原因。steered表示响应在收到WebSocket response.steer事件后于安全输出边界停止;服务器随后可自动使用排队输入创建后继响应。

  • "max_output_tokens"

  • "max_messages"

  • "content_filter"

  • "steered"

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

插入模型上下文的系统消息或开发者消息。

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

  • string

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

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

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

  • 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

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

  • metadata: map[string] or null

可附加到对象的一组16个键值对,用于结构化保存附加信息,并通过API或控制台查询对象。

键为最长64个字符的字符串,值为最长512个字符的字符串。

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

生成响应的模型ID,例如gpt-6.2-astra。OpenAI提供能力、性能和价格各异的模型,可在模型指南浏览比较。

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

生成响应的模型ID,例如gpt-6.2-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

  • object: "response"

此资源的对象类型,始终为 response。

  • "response"

  • output: array of BetaResponseOutputItem

模型生成的内容条目数组。

output数组的长度和顺序取决于模型响应。不要假定首个条目一定是包含生成内容的assistant消息;可考虑使用SDK支持的output_text属性。

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

模型输出的消息。

  • 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

从文件中检索出的文本。

  • 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 { id, output, status, 7 more }

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

输入模型的文件。

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

  • type: "function_call_output"

类型,固定为 function_call_output。

  • "function_call_output"

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

  • created_by: optional string

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

  • name: optional string

产生输出的工具名称。

  • namespace: optional 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

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

  • 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

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

  • 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

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

  • 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

单击操作。

  • actions: optional BetaComputerActionList

computer_use的扁平化批量操作。每个操作包含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

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

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

  • 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

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

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

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

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

  • 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

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

  • 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 { 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 工具返回的可选文本输出。

  • 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

工具调用的错误,如有。

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

  • 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

决定的可选理由。

  • 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 { id, call_id, output, 5 more }

  • id: string

自定义工具调用输出条目的唯一 ID。

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

输入模型的文件。

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

  • type: "custom_tool_call_output"

类型,固定为 custom_tool_call_output。

  • "custom_tool_call_output"

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

  • created_by: optional string

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

  • parallel_tool_calls: boolean (default: true)

是否允许模型并行执行工具调用。

  • temperature: number or null (default: 1)

采样温度,范围0到2。0.8等较高值使输出更随机,0.2等较低值使输出更集中、更确定。通常建议只修改此参数或top_p中的一个。

minimum: 0, maximum: 2

  • tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more

模型生成响应时如何选择工具,参见tools参数了解可调用工具的定义方式。

  • BetaToolChoiceOptions = "none" or "auto" or "required"

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

none 表示模型直接生成消息,不调用工具。

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

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

  • "none"

  • "auto"

  • "required"

  • BetaToolChoiceAllowed object { mode, tools, type }

将模型可用的工具限制为预先定义的集合。

  • mode: "auto" or "required"

将模型可用的工具限制为预先定义的集合。

auto 允许模型从可用工具中选择,或生成消息。

required 要求模型至少调用一个可用工具。

  • "auto"

  • "required"

  • tools: array of map[unknown]

应允许模型调用的工具定义列表。

对于 Responses API,工具定义列表可以如下所示:

        [
          { "type": "function", "name": "get_weather" },
          { "type": "mcp", "server_label": "deepwiki" },
          { "type": "image_generation" }
        ]

  • type: "allowed_tools"

允许的工具配置类型,固定为 allowed_tools。

  • "allowed_tools"

  • BetaToolChoiceTypes object { type }

指定模型应使用内置工具生成响应,详见内置工具。

  • type: "file_search" or "web_search_preview" or "computer" or 5 more

模型应使用的托管工具类型,详见内置工具。

允许的值为:

  • file_search
  • web_search_preview
  • computer
  • computer_use_preview
  • computer_use
  • code_interpreter
  • image_generation

  • "file_search"

  • "web_search_preview"

  • "computer"

  • "computer_use_preview"

  • "computer_use"

  • "web_search_preview_2025_03_11"

  • "image_generation"

  • "code_interpreter"

  • BetaToolChoiceFunction object { name, type }

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

  • name: string

要调用的函数名称。

  • type: "function"

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

  • "function"

  • BetaToolChoiceMcp object { server_label, type, name }

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

  • server_label: string

要使用的 MCP 服务器标签。

  • type: "mcp"

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

  • "mcp"

  • name: optional string or null

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

  • BetaToolChoiceCustom object { name, type }

使用此选项强制模型调用特定的自定义工具。

  • name: string

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

  • type: "custom"

对于自定义工具调用,类型固定为 custom。

  • "custom"

  • BetaSpecificProgrammaticToolCallingParam object { type }

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

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

  • "programmatic_tool_calling"

  • BetaToolChoiceApplyPatch object { type }

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

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

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

  • "apply_patch"

  • BetaToolChoiceShell object { type }

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

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

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

  • "shell"

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

模型生成响应时可以调用的工具数组。可以通过设置 tool_choice 参数指定使用哪个工具。

支持以下几类工具:

内置工具:OpenAI提供的扩展能力,如网页搜索和文件搜索,详见内置工具。MCP工具:通过自定义MCP服务器或Google Drive、SharePoint等预定义连接器集成第三方系统,详见MCP工具。函数调用(自定义工具):开发者定义的函数,让模型以强类型参数和输出调用你的代码,详见函数调用;也可使用自定义工具调用自己的代码。

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

  • top_p: number or null (default: 1)

核采样是温度采样的替代方式:模型仅考虑累计概率达到top_p的词元。例如0.1表示只考虑累计概率质量前10%的词元。

通常建议只调整此项或 temperature 中的一项,不同时调整两者。

minimum: 0, maximum: 1

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

是否在后台运行模型响应,详见后台模式。

  • completed_at: optional number or null

Response完成时的Unix时间戳,单位为秒,仅在状态为completed时存在。

format: unixtime

  • conversation: optional object { id } or null

此响应所属的对话。该响应的输入条目和输出条目已自动添加到此对话。

  • id: string

与此响应关联的对话的唯一 ID。

  • image: optional object { context_compression }

  • context_compression: "enabled" or "disabled"

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

  • "enabled"

  • "disabled"

  • input_transformations: optional array of object { id, action, reason, type }

未传给模型的推理输入,按输入顺序排列。

  • id: string

原始推理条目的 ID。

  • action: "removed" (default: "removed")

  • "removed"

  • reason: "organization_mismatch" or "end_user_mismatch" or "model_mismatch" or 2 more

  • "organization_mismatch"

  • "end_user_mismatch"

  • "model_mismatch"

  • "prefix_mismatch"

  • "turn_boundary"

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

  • "reasoning"

  • max_output_tokens: optional integer or null

响应可生成词元数的上限,包括可见输出词元及推理词元。

  • max_tool_calls: optional integer or null

一个响应中可处理的内置工具调用总次数上限。此上限适用于所有内置工具调用的合计次数,而非每个工具分别计算。达到上限后,模型进一步调用工具的尝试会被忽略。

  • moderation: optional object { input, output } or null

如果请求了经审核的补全,则包含响应输入和输出的审核结果。

  • input: ModerationResult { categories, category_applied_input_types, category_scores, 3 more } or Error { code, message, type }

对响应输入的审核。

  • ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }

针对响应输入或输出生成的审核结果。

  • categories: map[boolean]

审核类别到布尔值的映射。输入被某类别标记时,该类别值为 true。

  • category_applied_input_types: map[array of "text" or "image"]

各类别评分所涵盖的输入模态。

  • "text"

  • "image"

  • category_scores: map[number]

审核类别到分数的映射。

  • flagged: boolean

表示内容是否被任一类别标记的布尔值。

  • model: string

生成此结果的审核模型。

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

对象类型,成功审核结果中固定为 moderation_result。

  • "moderation_result"

  • Error object { code, message, type }

尝试审核响应输入或输出时产生的错误。

  • code: string

错误代码。

  • message: string

错误消息。

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

对象类型;审核失败时始终为 error。

  • "error"

  • output: ModerationResult { categories, category_applied_input_types, category_scores, 3 more } or Error { code, message, type }

对响应输出的审核。

  • ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }

针对响应输入或输出生成的审核结果。

  • categories: map[boolean]

审核类别到布尔值的映射。输入被某类别标记时,该类别值为 true。

  • category_applied_input_types: map[array of "text" or "image"]

各类别评分所涵盖的输入模态。

  • "text"

  • "image"

  • category_scores: map[number]

审核类别到分数的映射。

  • flagged: boolean

表示内容是否被任一类别标记的布尔值。

  • model: string

生成此结果的审核模型。

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

对象类型,成功审核结果中固定为 moderation_result。

  • "moderation_result"

  • Error object { code, message, type }

尝试审核响应输入或输出时产生的错误。

  • code: string

错误代码。

  • message: string

错误消息。

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

对象类型;审核失败时始终为 error。

  • "error"

  • output_text: optional string or null

仅SDK提供的便利属性,聚合output数组中所有output_text条目的文本(若存在),Python和JavaScript SDK支持此属性。

  • previous_response_id: optional string or null

前一次模型响应的唯一ID,用于多轮对话,详见对话状态。不能与conversation同时使用。

  • prompt: optional BetaResponsePrompt or null

提示词模板及其变量的引用,详见代码中的提示词版本。

  • id: string

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

  • variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile] or null

可选的变量替换映射,用于替换提示词中的变量。替换值可为字符串,也可为图像或文件等其他Response输入类型。

  • string

  • BetaResponseInputText object { text, type, prompt_cache_breakpoint }

输入模型的文本。

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

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

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

输入模型的文件。

  • version: optional string or null

提示词模板的可选版本。

  • prompt_cache_diagnostics: optional CacheMiss { cache_missed_tokens, reason, type, comparison_reusable_tokens } or CacheHit { type } or ComparisonResponseNotFound { type } or Unavailable { type }

为此响应请求的提示词缓存诊断信息。

  • CacheMiss object { cache_missed_tokens, reason, type, comparison_reusable_tokens }

  • cache_missed_tokens: integer

首次检测到差异之后,受影响的输入词元数量估计值。

  • reason: "model_changed" or "prompt_cache_key_changed" or "tools_changed" or 6 more

未复用提示词缓存的原因。

  • "model_changed"

  • "prompt_cache_key_changed"

  • "tools_changed"

  • "text_format_changed"

  • "reasoning_effort_changed"

  • "verbosity_changed"

  • "context_compacted"

  • "input_changed"

  • "service_tier_changed"

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

  • "cache_miss"

  • comparison_reusable_tokens: optional integer

在所比较的响应中,可复用前缀的原始词元数。

  • CacheHit object { type }

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

  • "cache_hit"

  • ComparisonResponseNotFound object { type }

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

  • "comparison_response_not_found"

  • Unavailable object { type }

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

  • "unavailable"

  • prompt_cache_key: optional string or null

供OpenAI缓存相似请求的响应,以优化缓存命中率,替代user字段,详见提示词缓存。

  • prompt_cache_options: optional object { mode, ttl, comparison_response_id }

应用于该响应的提示词缓存选项。支持 gpt-5.6 及更新模型。

  • mode: "implicit" or "explicit"

是否启用了隐式提示词缓存断点。

  • "implicit"

  • "explicit"

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

应用于每个缓存断点的最短保留时间。

  • "30m"

  • "12h"

  • comparison_response_id: optional string or null

用于提示词缓存诊断比较的响应 ID。

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

已弃用,改用 prompt_cache_options.ttl。

提示词缓存保留策略。设为24h启用扩展缓存,使缓存前缀保持活跃更久,最长24小时,详见缓存保留。此字段表达最长保留策略,prompt_cache_options.ttl表达最短缓存寿命;两者独立、互不影响。gpt-5.5、gpt-5.5-pro及后续模型仅支持24h。

对于同时支持 in_memory 和 24h 的较早模型,默认值取决于组织的数据保留策略:

未启用ZDR的组织默认使用24h;启用ZDR且未指定prompt_cache_retention的组织默认使用in_memory。

  • "in_memory"

  • "24h"

  • reasoning: optional object { context, effort, generate_summary, 2 more } or null

推理模型的配置选项。

  • context: optional "auto" or "current_turn" or "all_turns" or null

控制后续轮次向模型呈现哪些推理条目。省略或设为auto时由模型决定上下文模式。gpt-5.6系列默认all_turns,更早模型默认current_turn。

在响应中返回时,表示本次响应实际使用的推理上下文模式。

  • "auto"

  • "current_turn"

  • "all_turns"

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

限制推理模型的推理努力程度。目前支持none、minimal、low、medium、high、xhigh和max。降低努力程度可能加快响应并减少推理词元。并非所有模型支持每个值,具体见推理指南。

  • "none"

  • "minimal"

  • "low"

  • "medium"

  • "high"

  • "xhigh"

  • "max"

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

已弃用:请改用 summary。

模型推理的摘要,有助于调试和理解推理过程。可选auto、concise或detailed。

  • "auto"

  • "concise"

  • "detailed"

  • mode: optional string or "standard" or "pro"

控制请求的推理执行模式。

当此字段出现在返回的响应中时,表示实际使用的执行模式。

  • string

  • "standard" or "pro"

控制请求的推理执行模式。

当此字段出现在返回的响应中时,表示实际使用的执行模式。

  • "standard"

  • "pro"

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

模型推理的摘要,有助于调试和理解推理过程。可选auto、concise或detailed。

computer-use-preview 模型及 gpt-5 之后的推理模型均支持 concise。

  • "auto"

  • "concise"

  • "detailed"

  • safety_identifier: optional string or null

稳定的用户标识,帮助检测应用中可能违反OpenAI使用政策的用户。应使用唯一标识各用户、最长128字符的字符串。建议对用户名或电子邮箱进行哈希,避免发送个人身份信息,详见安全标识。

maxLength: 128

  • service_tier: optional BetaServiceTier or null (default: "auto")

指定处理请求所采用的服务类型。

auto使用项目设置中的服务层级,未另行配置时为default。default使用所选模型的标准价格及性能;flex使用Flex处理。在Responses或Chat Completions请求中设置service_tier=fast或service_tier=priority可启用快速模式,不论传入哪一个,原文此处写明响应显示priority。ultrafast使用受访问控制的Ultrafast层级,当前此原文列为可供gpt-5.6-sol使用,响应显示ultrafast。未设置时默认auto。

设置 service_tier 后,响应体中的同名字段反映实际采用的处理模式,可能与请求参数的值不同。

  • "auto"

  • "default"

  • "flex"

  • "scale"

  • "priority"

  • "fast"

  • "ultrafast"

  • status: optional BetaResponseStatus

响应生成状态,可选completed、failed、in_progress、cancelled、queued或incomplete。

  • "completed"

  • "failed"

  • "in_progress"

  • "cancelled"

  • "queued"

  • "incomplete"

  • text: optional BetaResponseTextConfig

模型文本响应的配置选项,可为纯文本或结构化JSON数据,详见下列指南。

文本输入与输出;结构化输出。

  • format: optional BetaResponseFormatTextConfig

指定模型必须输出的格式的对象。

配置{ "type": "json_schema" }可启用结构化输出,确保模型匹配提供的JSON Schema,详见结构化输出指南。

默认格式为 { "type": "text" },没有额外选项。

不建议用于 gpt-4o 及后续模型:

设置{ "type": "json_object" }可启用旧版JSON模式,确保模型生成合法JSON。支持json_schema的模型优先使用后者。

  • Text object { type }

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

  • type: "text"

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

  • "text"

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

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

  • JSONObject object { type }

JSON对象响应格式,是生成JSON响应的旧方式。支持json_schema的模型建议使用后者。注意,若system或user消息没有明确要求生成JSON,模型不会自行生成JSON。

  • type: "json_object"

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

  • "json_object"

  • verbosity: optional "low" or "medium" or "high" or null (default: "medium")

约束模型响应的详细程度。较低值生成更简洁的响应,较高值生成更详细的响应。目前支持low、medium和high,默认为medium。

  • "low"

  • "medium"

  • "high"

  • tool_usage: optional object { image_gen, web_search }

托管工具报告的用量,独立于基础模型的 usage。无法取得工具用量时可省略。若返回该字段,没有用量记录的工具类别计数为零。

image_gen 合计所有图像生成调用中可取得的词元计数。可能跳过用量记录不完整的调用。输出词元明细和缓存输入计数可省略,省略缓存计数表示缓存用量未知。

web_search.num_requests 统计可计费的搜索次数。打折搜索与打开网页等操作不计入。最终费用请以账单记录为准。

  • image_gen: object { input_tokens, input_tokens_details, output_tokens, 4 more }

图像生成工具调用的汇总用量统计。

  • input_tokens: integer

输入提示词中的图像与文本词元数量。

  • input_tokens_details: object { image_tokens, text_tokens }

图像生成的输入词元明细。

  • image_tokens: integer

输入提示词中的图像词元数量。

  • text_tokens: integer

输入提示词中的文本词元数量。

  • output_tokens: integer

模型生成的输出词元数量。

  • total_tokens: integer

图像生成使用的图像和文本词元总数。

  • cached_tokens: optional integer

  • cached_tokens_details: optional object { cached_image_tokens, cached_text_tokens }

  • cached_image_tokens: integer

  • cached_text_tokens: integer

  • output_tokens_details: optional object { image_tokens, text_tokens }

图像生成的输出词元明细。

  • image_tokens: integer

模型生成的图像输出词元数量。

  • text_tokens: integer

模型生成的文本输出词元数量。

  • web_search: object { num_requests }

网页搜索工具调用的汇总计费用量统计。

  • num_requests: integer

发起的计费网页搜索请求次数。

  • top_logprobs: optional integer or null

0到20之间的整数,指定每个词元位置返回多少个最可能词元及其对数概率;实际返回数量有时会少于请求值。

minimum: 0, maximum: 20

  • truncation: optional "auto" or "disabled" or null (default: "disabled")

模型响应的截断策略。

  • auto:输入超出模型的上下文窗口时,从对话开头移除条目以适配窗口。对部分模型,API 会先从输入上限扣除模型允许的最大输出量,再统计词元。因此,即使设置较低的 max_output_tokens,也可能更早开始截断。
  • disabled(默认值):输入超出模型上下文窗口时,请求会失败并返回 400 错误。

  • "auto"

  • "disabled"

  • usage: optional BetaResponseUsage or null

词元用量详情,包括输入词元、输出词元、输出词元分类和词元总数。

  • 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

使用的总词元数。

  • user: optional string or null

此字段正被safety_identifier和prompt_cache_key取代,维持缓存优化应改用prompt_cache_key。它是终端用户的稳定标识,通过更好地归类相似请求提高命中率,也帮助OpenAI检测和防止滥用,详见安全标识。

  • sequence_number: integer

事件序列号。

  • type: "response.incomplete"

类型,固定为response.incomplete。

  • "response.incomplete"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.incomplete",
  "response": {
    "id": "resp_123",
    "object": "response",
    "access_programs": null,
    "created_at": 1740855869,
    "status": "incomplete",
    "completed_at": null,
    "error": null,
    "incomplete_details": {
      "reason": "max_output_tokens"
    },
    "instructions": null,
    "max_output_tokens": null,
    "model": "gpt-6.2-astra",
    "output": [],
    "previous_response_id": null,
    "reasoning_effort": null,
    "store": false,
    "temperature": 1,
    "text": {
      "format": {
        "type": "text"
      }
    },
    "tool_choice": "auto",
    "tools": [],
    "top_p": 1,
    "truncation": "disabled",
    "usage": null,
    "user": null,
    "metadata": {},
    "parallel_tool_calls": true
  },
  "sequence_number": 1
}

response.output_item.added

添加新输出条目时发出。

结构定义

结构名称: BetaResponseOutputItemAddedEvent

  • item: BetaResponseOutputItem

新增输出条目。推理条目仍在进行中时,encrypted_content可能不完整;后续请求应使用对应response.output_item.done事件中的推理条目作为输入。

  • 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

从文件中检索出的文本。

  • 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 { id, output, status, 7 more }

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

输入模型的文本。

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

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

  • type: "function_call_output"

类型,固定为 function_call_output。

  • "function_call_output"

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

  • created_by: optional string

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

  • name: optional string

产生输出的工具名称。

  • namespace: optional 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

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

  • 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

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

  • 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

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

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

  • 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

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

  • 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

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

  • 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

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

  • 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 { 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 工具返回的可选文本输出。

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

  • 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

决定的可选理由。

  • 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 { id, call_id, output, 5 more }

  • id: string

自定义工具调用输出条目的唯一 ID。

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

输入模型的文件。

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

  • type: "custom_tool_call_output"

类型,固定为 custom_tool_call_output。

  • "custom_tool_call_output"

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

  • created_by: optional string

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

  • output_index: integer

新增输出条目的索引。

  • sequence_number: integer

事件序列号。

  • type: "response.output_item.added"

类型,固定为response.output_item.added。

  • "response.output_item.added"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.output_item.added",
  "output_index": 0,
  "item": {
    "id": "msg_123",
    "status": "in_progress",
    "type": "message",
    "role": "assistant",
    "content": []
  },
  "sequence_number": 1
}

response.output_item.done

输出条目标记为完成时发出。

结构定义

结构名称: BetaResponseOutputItemDoneEvent

  • item: BetaResponseOutputItem

标记为完成的输出条目。

  • 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

从文件中检索出的文本。

  • 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 { id, output, status, 7 more }

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

输入模型的文本。

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

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

  • type: "function_call_output"

类型,固定为 function_call_output。

  • "function_call_output"

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

  • created_by: optional string

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

  • name: optional string

产生输出的工具名称。

  • namespace: optional 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

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

  • 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

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

  • 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

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

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

  • 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

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

  • 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

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

  • 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

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

  • 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 { 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 工具返回的可选文本输出。

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

  • 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

决定的可选理由。

  • 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 { id, call_id, output, 5 more }

  • id: string

自定义工具调用输出条目的唯一 ID。

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

输入模型的文件。

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

  • type: "custom_tool_call_output"

类型,固定为 custom_tool_call_output。

  • "custom_tool_call_output"

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

  • created_by: optional string

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

  • output_index: integer

标记为完成的输出条目索引。

  • sequence_number: integer

事件序列号。

  • type: "response.output_item.done"

类型,固定为response.output_item.done。

  • "response.output_item.done"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

例中文字:繁星下闪烁的森林里,孤独的独角兽Lila发现了一片泛着月光的小池塘。她每晚在岸边留下闪耀的魔法花朵,希望与他人分享美丽。某个迷人的夜晚,她醒来发现友善的小动物聚在身旁,渴望与她成为朋友、共享魔法。

{
  "type": "response.output_item.done",
  "output_index": 0,
  "item": {
    "id": "msg_123",
    "status": "completed",
    "type": "message",
    "role": "assistant",
    "content": [
      {
        "type": "output_text",
        "text": "In a shimmering forest under a sky full of stars, a lonely unicorn named Lila discovered a hidden pond that glowed with moonlight. Every night, she would leave sparkling, magical flowers by the water's edge, hoping to share her beauty with others. One enchanting evening, she woke to find a group of friendly animals gathered around, eager to be friends and share in her magic.",
        "annotations": [],
        "logprobs": []
      }
    ]
  },
  "sequence_number": 1
}

response.content_part.added

添加新内容部分时发出。

结构定义

结构名称: BetaResponseContentPartAddedEvent

  • content_index: integer

新增内容部分的索引。

  • item_id: string

新增内容部分所属的输出条目ID。

  • output_index: integer

新增内容部分所属的输出条目索引。

  • part: BetaResponseOutputText or BetaResponseOutputRefusal or ReasoningText { text, type }

添加的内容部分。

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

  • ReasoningText object { text, type }

模型生成的推理文本。

  • text: string

模型生成的推理文本。

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

类型,固定为 reasoning_text。

  • "reasoning_text"

  • sequence_number: integer

事件序列号。

  • type: "response.content_part.added"

类型,固定为response.content_part.added。

  • "response.content_part.added"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.content_part.added",
  "item_id": "msg_123",
  "output_index": 0,
  "content_index": 0,
  "part": {
    "type": "output_text",
    "text": "",
    "annotations": [],
    "logprobs": []
  },
  "sequence_number": 1
}

response.content_part.done

内容部分完成时发出。

结构定义

结构名称: BetaResponseContentPartDoneEvent

  • content_index: integer

已完成内容部分的索引。

  • item_id: string

新增内容部分所属的输出条目ID。

  • output_index: integer

新增内容部分所属的输出条目索引。

  • part: BetaResponseOutputText or BetaResponseOutputRefusal or ReasoningText { text, type }

已完成的内容部分。

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

  • ReasoningText object { text, type }

模型生成的推理文本。

  • text: string

模型生成的推理文本。

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

类型,固定为 reasoning_text。

  • "reasoning_text"

  • sequence_number: integer

事件序列号。

  • type: "response.content_part.done"

类型,固定为response.content_part.done。

  • "response.content_part.done"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

例中文字:繁星下闪烁的森林里,孤独的独角兽Lila发现了一片泛着月光的小池塘。她每晚在岸边留下闪耀的魔法花朵,希望与他人分享美丽。某个迷人的夜晚,她醒来发现友善的小动物聚在身旁,渴望与她成为朋友、共享魔法。

{
  "type": "response.content_part.done",
  "item_id": "msg_123",
  "output_index": 0,
  "content_index": 0,
  "sequence_number": 1,
  "part": {
    "type": "output_text",
    "text": "In a shimmering forest under a sky full of stars, a lonely unicorn named Lila discovered a hidden pond that glowed with moonlight. Every night, she would leave sparkling, magical flowers by the water's edge, hoping to share her beauty with others. One enchanting evening, she woke to find a group of friendly animals gathered around, eager to be friends and share in her magic.",
    "annotations": [],
    "logprobs": []
  }
}

response.output_text.delta

产生额外文本增量时发出。

结构定义

结构名称: BetaResponseTextDeltaEvent

  • content_index: integer

接收文本增量的内容部分索引。

  • delta: string

新增文本增量。

  • item_id: string

接收文本增量的输出条目ID。

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

增量中各词元的对数概率。

  • token: string

可能出现的文本词元。

  • logprob: number

此词元的对数概率。

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

最多20个最可能词元的对数概率。

  • token: optional string

可能出现的文本词元。

  • logprob: optional number

此词元的对数概率。

  • output_index: integer

接收文本增量的输出条目索引。

  • sequence_number: integer

此事件的序列号。

  • type: "response.output_text.delta"

类型,固定为response.output_text.delta。

  • "response.output_text.delta"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.output_text.delta",
  "item_id": "msg_123",
  "output_index": 0,
  "content_index": 0,
  "delta": "In",
  "sequence_number": 1,
  "logprobs": []
}

response.output_text.done

文本内容确定后发出。

结构定义

结构名称: BetaResponseTextDoneEvent

  • content_index: integer

文本内容确定时对应的内容部分索引。

  • item_id: string

文本内容确定时对应的输出条目ID。

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

增量中各词元的对数概率。

  • token: string

可能出现的文本词元。

  • logprob: number

此词元的对数概率。

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

最多20个最可能词元的对数概率。

  • token: optional string

可能出现的文本词元。

  • logprob: optional number

此词元的对数概率。

  • output_index: integer

文本内容确定时对应的输出条目索引。

  • sequence_number: integer

此事件的序列号。

  • text: string

已确定的文本内容。

  • type: "response.output_text.done"

类型,固定为response.output_text.done。

  • "response.output_text.done"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

例中文字:繁星下闪烁的森林里,孤独的独角兽Lila发现了一片泛着月光的小池塘。她每晚在岸边留下闪耀的魔法花朵,希望与他人分享美丽。某个迷人的夜晚,她醒来发现友善的小动物聚在身旁,渴望与她成为朋友、共享魔法。

{
  "type": "response.output_text.done",
  "item_id": "msg_123",
  "output_index": 0,
  "content_index": 0,
  "text": "In a shimmering forest under a sky full of stars, a lonely unicorn named Lila discovered a hidden pond that glowed with moonlight. Every night, she would leave sparkling, magical flowers by the water's edge, hoping to share her beauty with others. One enchanting evening, she woke to find a group of friendly animals gathered around, eager to be friends and share in her magic.",
  "sequence_number": 1,
  "logprobs": []
}

response.refusal.delta

产生部分拒绝文本时发出。

结构定义

结构名称: BetaResponseRefusalDeltaEvent

  • content_index: integer

接收新增拒绝文本的内容部分索引。

  • delta: string

新增的拒绝文本。

  • item_id: string

接收新增拒绝文本的输出条目ID。

  • output_index: integer

接收新增拒绝文本的输出条目索引。

  • sequence_number: integer

事件序列号。

  • type: "response.refusal.delta"

类型,固定为response.refusal.delta。

  • "response.refusal.delta"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

例中文字:截至当前的拒绝文本

{
  "type": "response.refusal.delta",
  "item_id": "msg_123",
  "output_index": 0,
  "content_index": 0,
  "delta": "refusal text so far",
  "sequence_number": 1
}

response.refusal.done

拒绝文本确定后发出。

结构定义

结构名称: BetaResponseRefusalDoneEvent

  • content_index: integer

拒绝文本确定时对应的内容部分索引。

  • item_id: string

拒绝文本确定时对应的输出条目ID。

  • output_index: integer

拒绝文本确定时对应的输出条目索引。

  • refusal: string

已确定的拒绝文本。

  • sequence_number: integer

事件序列号。

  • type: "response.refusal.done"

类型,固定为response.refusal.done。

  • "response.refusal.done"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

例中文字:最终拒绝文本

{
  "type": "response.refusal.done",
  "item_id": "item-abc",
  "output_index": 1,
  "content_index": 2,
  "refusal": "final refusal text",
  "sequence_number": 1
}

response.function_call_arguments.delta

函数调用参数产生部分增量时发出。

结构定义

结构名称: BetaResponseFunctionCallArgumentsDeltaEvent

  • delta: string

新增的函数调用参数增量。

  • item_id: string

接收函数调用参数增量的输出条目ID。

  • output_index: integer

接收函数调用参数增量的输出条目索引。

  • sequence_number: integer

事件序列号。

  • type: "response.function_call_arguments.delta"

类型,固定为response.function_call_arguments.delta。

  • "response.function_call_arguments.delta"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.function_call_arguments.delta",
  "item_id": "item-abc",
  "output_index": 0,
  "delta": "{ \"arg\":",
  "sequence_number": 1
}

response.function_call_arguments.done

函数调用参数确定后发出。

结构定义

结构名称: BetaResponseFunctionCallArgumentsDoneEvent

  • arguments: string

函数调用参数。

  • item_id: string

条目 ID。

  • output_index: integer

输出条目索引。

  • sequence_number: integer

事件序列号。

  • type: "response.function_call_arguments.done"

  • "response.function_call_arguments.done"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.function_call_arguments.done",
  "item_id": "item-abc",
  "output_index": 1,
  "arguments": "{ \"arg\": 123 }",
  "sequence_number": 1
}

response.file_search_call.in_progress

发起文件搜索调用时发出。

结构定义

结构名称: BetaResponseFileSearchCallInProgressEvent

  • item_id: string

发起文件搜索调用的输出条目ID。

  • output_index: integer

发起文件搜索调用的输出条目索引。

  • sequence_number: integer

事件序列号。

  • type: "response.file_search_call.in_progress"

类型,固定为response.file_search_call.in_progress。

  • "response.file_search_call.in_progress"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.file_search_call.in_progress",
  "output_index": 0,
  "item_id": "fs_123",
  "sequence_number": 1
}

response.file_search_call.searching

文件搜索正在搜索时发出。

结构定义

结构名称: BetaResponseFileSearchCallSearchingEvent

  • item_id: string

发起文件搜索调用的输出条目ID。

  • output_index: integer

正在执行文件搜索的输出条目索引。

  • sequence_number: integer

事件序列号。

  • type: "response.file_search_call.searching"

类型,固定为response.file_search_call.searching。

  • "response.file_search_call.searching"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.file_search_call.searching",
  "output_index": 0,
  "item_id": "fs_123",
  "sequence_number": 1
}

response.file_search_call.completed

文件搜索调用完成、已找到结果时发出。

结构定义

结构名称: BetaResponseFileSearchCallCompletedEvent

  • item_id: string

发起文件搜索调用的输出条目ID。

  • output_index: integer

发起文件搜索调用的输出条目索引。

  • sequence_number: integer

事件序列号。

  • type: "response.file_search_call.completed"

类型,固定为response.file_search_call.completed。

  • "response.file_search_call.completed"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.file_search_call.completed",
  "output_index": 0,
  "item_id": "fs_123",
  "sequence_number": 1
}

response.web_search_call.in_progress

发起网页搜索调用时发出。

结构定义

结构名称: BetaResponseWebSearchCallInProgressEvent

  • item_id: string

与网页搜索调用关联的输出条目唯一ID。

  • output_index: integer

与网页搜索调用关联的输出条目索引。

  • sequence_number: integer

正在处理的网页搜索调用序列号。

  • type: "response.web_search_call.in_progress"

类型,固定为response.web_search_call.in_progress。

  • "response.web_search_call.in_progress"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.web_search_call.in_progress",
  "output_index": 0,
  "item_id": "ws_123",
  "sequence_number": 0
}

response.web_search_call.searching

网页搜索调用正在执行时发出。

结构定义

结构名称: BetaResponseWebSearchCallSearchingEvent

  • item_id: string

与网页搜索调用关联的输出条目唯一ID。

  • output_index: integer

与网页搜索调用关联的输出条目索引。

  • sequence_number: integer

正在处理的网页搜索调用序列号。

  • type: "response.web_search_call.searching"

类型,固定为response.web_search_call.searching。

  • "response.web_search_call.searching"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.web_search_call.searching",
  "output_index": 0,
  "item_id": "ws_123",
  "sequence_number": 0
}

response.web_search_call.completed

网页搜索调用完成时发出。

结构定义

结构名称: BetaResponseWebSearchCallCompletedEvent

  • item_id: string

与网页搜索调用关联的输出条目唯一ID。

  • output_index: integer

与网页搜索调用关联的输出条目索引。

  • sequence_number: integer

正在处理的网页搜索调用序列号。

  • type: "response.web_search_call.completed"

类型,固定为response.web_search_call.completed。

  • "response.web_search_call.completed"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.web_search_call.completed",
  "output_index": 0,
  "item_id": "ws_123",
  "sequence_number": 0
}

response.reasoning_summary_part.added

添加新的推理摘要部分时发出。

结构定义

结构名称: BetaResponseReasoningSummaryPartAddedEvent

  • item_id: string

此摘要部分关联的条目ID。

  • output_index: integer

此摘要部分关联的输出条目索引。

  • part: object { text, type }

新增摘要部分。

  • text: string

摘要部分的文本。

  • type: "summary_text"

类型,固定为summary_text。

  • "summary_text"

  • sequence_number: integer

事件序列号。

  • summary_index: integer

摘要部分在推理摘要中的索引。

  • type: "response.reasoning_summary_part.added"

类型,固定为response.reasoning_summary_part.added。

  • "response.reasoning_summary_part.added"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.reasoning_summary_part.added",
  "item_id": "rs_6806bfca0b2481918a5748308061a2600d3ce51bdffd5476",
  "output_index": 0,
  "summary_index": 0,
  "part": {
    "type": "summary_text",
    "text": ""
  },
  "sequence_number": 1
}

response.reasoning_summary_part.done

推理摘要部分完成时发出。

结构定义

结构名称: BetaResponseReasoningSummaryPartDoneEvent

  • item_id: string

此摘要部分关联的条目ID。

  • output_index: integer

此摘要部分关联的输出条目索引。

  • part: object { text, type }

已完成的摘要部分。

  • text: string

摘要部分的文本。

  • type: "summary_text"

类型,固定为summary_text。

  • "summary_text"

  • sequence_number: integer

事件序列号。

  • summary_index: integer

摘要部分在推理摘要中的索引。

  • type: "response.reasoning_summary_part.done"

类型,固定为response.reasoning_summary_part.done。

  • "response.reasoning_summary_part.done"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

  • status: optional "incomplete"

摘要部分的完成状态。正常完成时省略;生成被中断时为incomplete。

  • "incomplete"

示例

例中文字:回应问候:用户刚刚说了“你好!”,看来我需要接话。既然用户想聊天,我会回以问候,并表示愿意提供帮助。我可以这样说:“你好!今天有什么可以帮你?”这样的回应显得友好而开放。用户没有提出具体问题,因此这种方式很适合开启对话。接下来看看对话会如何发展!

{
  "type": "response.reasoning_summary_part.done",
  "item_id": "rs_6806bfca0b2481918a5748308061a2600d3ce51bdffd5476",
  "output_index": 0,
  "summary_index": 0,
  "part": {
    "type": "summary_text",
    "text": "**Responding to a greeting**\n\nThe user just said, \"Hello!\" So, it seems I need to engage. I'll greet them back and offer help since they're looking to chat. I could say something like, \"Hello! How can I assist you today?\" That feels friendly and open. They didn't ask a specific question, so this approach will work well for starting a conversation. Let's see where it goes from there!"
  },
  "sequence_number": 1
}

response.reasoning_summary_text.delta

向推理摘要文本添加增量时发出。

结构定义

结构名称: BetaResponseReasoningSummaryTextDeltaEvent

  • delta: string

新增到摘要的文本增量。

  • item_id: string

此摘要文本增量关联的条目ID。

  • output_index: integer

此摘要文本增量关联的输出条目索引。

  • sequence_number: integer

事件序列号。

  • summary_index: integer

摘要部分在推理摘要中的索引。

  • type: "response.reasoning_summary_text.delta"

类型,固定为response.reasoning_summary_text.delta。

  • "response.reasoning_summary_text.delta"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

例中文字:回应问候:用户刚刚说了“你好!”,看来我需要接话。既然用户想聊天,我会回以问候,并表示愿意提供帮助。我可以这样说:“你好!今天有什么可以帮你?”这样的回应显得友好而开放。用户没有提出具体问题,因此这种方式很适合开启对话。接下来看看对话会如何发展!

{
  "type": "response.reasoning_summary_text.delta",
  "item_id": "rs_6806bfca0b2481918a5748308061a2600d3ce51bdffd5476",
  "output_index": 0,
  "summary_index": 0,
  "delta": "**Responding to a greeting**\n\nThe user just said, \"Hello!\" So, it seems I need to engage. I'll greet them back and offer help since they're looking to chat. I could say something like, \"Hello! How can I assist you today?\" That feels friendly and open. They didn't ask a specific question, so this approach will work well for starting a conversation. Let's see where it goes from there!",
  "sequence_number": 1
}

response.reasoning_summary_text.done

推理摘要文本完成时发出。

结构定义

结构名称: BetaResponseReasoningSummaryTextDoneEvent

  • item_id: string

此摘要文本关联的条目ID。

  • output_index: integer

此摘要文本关联的输出条目索引。

  • sequence_number: integer

事件序列号。

  • summary_index: integer

摘要部分在推理摘要中的索引。

  • text: string

已完成推理摘要的完整文本。

  • type: "response.reasoning_summary_text.done"

类型,固定为response.reasoning_summary_text.done。

  • "response.reasoning_summary_text.done"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

例中文字:回应问候:用户刚刚说了“你好!”,看来我需要接话。既然用户想聊天,我会回以问候,并表示愿意提供帮助。我可以这样说:“你好!今天有什么可以帮你?”这样的回应显得友好而开放。用户没有提出具体问题,因此这种方式很适合开启对话。接下来看看对话会如何发展!

{
  "type": "response.reasoning_summary_text.done",
  "item_id": "rs_6806bfca0b2481918a5748308061a2600d3ce51bdffd5476",
  "output_index": 0,
  "summary_index": 0,
  "text": "**Responding to a greeting**\n\nThe user just said, \"Hello!\" So, it seems I need to engage. I'll greet them back and offer help since they're looking to chat. I could say something like, \"Hello! How can I assist you today?\" That feels friendly and open. They didn't ask a specific question, so this approach will work well for starting a conversation. Let's see where it goes from there!",
  "sequence_number": 1
}

response.reasoning_text.delta

向推理文本添加增量时发出。

结构定义

结构名称: BetaResponseReasoningTextDeltaEvent

  • content_index: integer

此增量关联的推理内容部分索引。

  • delta: string

新增到推理内容的文本增量。

  • item_id: string

此推理文本增量关联的条目ID。

  • output_index: integer

此推理文本增量关联的输出条目索引。

  • sequence_number: integer

事件序列号。

  • type: "response.reasoning_text.delta"

类型,固定为response.reasoning_text.delta。

  • "response.reasoning_text.delta"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.reasoning_text.delta",
  "item_id": "rs_123",
  "output_index": 0,
  "content_index": 0,
  "delta": "The",
  "sequence_number": 1
}

response.reasoning_text.done

推理文本完成时发出。

结构定义

结构名称: BetaResponseReasoningTextDoneEvent

  • content_index: integer

推理内容部分的索引。

  • item_id: string

此推理文本关联的条目ID。

  • output_index: integer

此推理文本关联的输出条目索引。

  • sequence_number: integer

事件序列号。

  • text: string

已完成推理内容的完整文本。

  • type: "response.reasoning_text.done"

类型,固定为response.reasoning_text.done。

  • "response.reasoning_text.done"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

例中文字:用户正在询问……

{
  "type": "response.reasoning_text.done",
  "item_id": "rs_123",
  "output_index": 0,
  "content_index": 0,
  "text": "The user is asking...",
  "sequence_number": 4
}

response.image_generation_call.completed

图像生成工具调用完成、最终图像可用时发出。

结构定义

结构名称: BetaResponseImageGenCallCompletedEvent

  • item_id: string

正在处理的图像生成条目的唯一标识。

  • output_index: integer

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

  • sequence_number: integer

事件序列号。

  • type: "response.image_generation_call.completed"

类型,固定为response.image_generation_call.completed。

  • "response.image_generation_call.completed"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.image_generation_call.completed",
  "output_index": 0,
  "item_id": "item-123",
  "sequence_number": 1
}

response.image_generation_call.generating

图像生成工具正在生成图像的中间阶段发出。

结构定义

结构名称: BetaResponseImageGenCallGeneratingEvent

  • item_id: string

正在处理的图像生成条目的唯一标识。

  • output_index: integer

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

  • sequence_number: integer

正在处理的图像生成条目的序列号。

  • type: "response.image_generation_call.generating"

类型,固定为response.image_generation_call.generating。

  • "response.image_generation_call.generating"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.image_generation_call.generating",
  "output_index": 0,
  "item_id": "item-123",
  "sequence_number": 0
}

response.image_generation_call.in_progress

图像生成工具调用进行中时发出。

结构定义

结构名称: BetaResponseImageGenCallInProgressEvent

  • item_id: string

正在处理的图像生成条目的唯一标识。

  • output_index: integer

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

  • sequence_number: integer

正在处理的图像生成条目的序列号。

  • type: "response.image_generation_call.in_progress"

类型,固定为response.image_generation_call.in_progress。

  • "response.image_generation_call.in_progress"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.image_generation_call.in_progress",
  "output_index": 0,
  "item_id": "item-123",
  "sequence_number": 0
}

response.image_generation_call.partial_image

图像生成流式传输期间,部分图像可用时发出。

结构定义

结构名称: BetaResponseImageGenCallPartialImageEvent

  • item_id: string

正在处理的图像生成条目的唯一标识。

  • output_index: integer

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

  • partial_image_b64: string

Base64 编码的部分图像数据,可用于渲染图像。

  • partial_image_index: integer

部分图像从0开始的索引;后端从1开始,但面向用户时从0开始。

  • sequence_number: integer

正在处理的图像生成条目的序列号。

  • type: "response.image_generation_call.partial_image"

类型,固定为response.image_generation_call.partial_image。

  • "response.image_generation_call.partial_image"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

  • background: optional string

实际使用的背景设置。

  • output_format: optional string

实际使用的输出格式。

  • quality: optional string

实际使用的图像质量。

  • size: optional string

实际使用的图像尺寸。

示例

{
  "type": "response.image_generation_call.partial_image",
  "output_index": 0,
  "item_id": "item-123",
  "sequence_number": 0,
  "partial_image_index": 0,
  "partial_image_b64": "..."
}

response.mcp_call_arguments.delta

MCP工具调用参数产生部分增量时发出。

结构定义

结构名称: BetaResponseMCPCallArgumentsDeltaEvent

  • delta: string

包含MCP工具调用参数部分更新的JSON字符串。

  • item_id: string

正在处理的MCP工具调用条目的唯一标识。

  • output_index: integer

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

  • sequence_number: integer

事件序列号。

  • type: "response.mcp_call_arguments.delta"

类型,固定为response.mcp_call_arguments.delta。

  • "response.mcp_call_arguments.delta"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.mcp_call_arguments.delta",
  "output_index": 0,
  "item_id": "item-abc",
  "delta": "{",
  "sequence_number": 1
}

response.mcp_call_arguments.done

MCP工具调用参数确定后发出。

结构定义

结构名称: BetaResponseMCPCallArgumentsDoneEvent

  • arguments: string

包含已确定MCP工具调用参数的JSON字符串。

  • item_id: string

正在处理的MCP工具调用条目的唯一标识。

  • output_index: integer

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

  • sequence_number: integer

事件序列号。

  • type: "response.mcp_call_arguments.done"

类型,固定为response.mcp_call_arguments.done。

  • "response.mcp_call_arguments.done"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.mcp_call_arguments.done",
  "output_index": 0,
  "item_id": "item-abc",
  "arguments": "{\"arg1\": \"value1\", \"arg2\": \"value2\"}",
  "sequence_number": 1
}

response.mcp_call.completed

MCP工具调用成功完成时发出。

结构定义

结构名称: BetaResponseMCPCallCompletedEvent

  • item_id: string

已完成MCP工具调用条目的ID。

  • output_index: integer

已完成输出条目的索引。

  • sequence_number: integer

事件序列号。

  • type: "response.mcp_call.completed"

类型,固定为response.mcp_call.completed。

  • "response.mcp_call.completed"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.mcp_call.completed",
  "sequence_number": 1,
  "item_id": "mcp_682d437d90a88191bf88cd03aae0c3e503937d5f622d7a90",
  "output_index": 0
}

response.mcp_call.failed

MCP工具调用失败时发出。

结构定义

结构名称: BetaResponseMCPCallFailedEvent

  • item_id: string

失败的MCP工具调用条目ID。

  • output_index: integer

失败的输出条目索引。

  • sequence_number: integer

事件序列号。

  • type: "response.mcp_call.failed"

类型,固定为response.mcp_call.failed。

  • "response.mcp_call.failed"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.mcp_call.failed",
  "sequence_number": 1,
  "item_id": "mcp_682d437d90a88191bf88cd03aae0c3e503937d5f622d7a90",
  "output_index": 0
}

response.mcp_call.in_progress

MCP工具调用进行中时发出。

结构定义

结构名称: BetaResponseMCPCallInProgressEvent

  • item_id: string

正在处理的MCP工具调用条目的唯一标识。

  • output_index: integer

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

  • sequence_number: integer

事件序列号。

  • type: "response.mcp_call.in_progress"

类型,固定为response.mcp_call.in_progress。

  • "response.mcp_call.in_progress"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.mcp_call.in_progress",
  "sequence_number": 1,
  "output_index": 0,
  "item_id": "mcp_682d437d90a88191bf88cd03aae0c3e503937d5f622d7a90"
}

response.mcp_list_tools.completed

成功取得可用MCP工具列表时发出。

结构定义

结构名称: BetaResponseMCPListToolsCompletedEvent

  • item_id: string

产生此输出的MCP工具调用条目ID。

  • output_index: integer

已处理输出条目的索引。

  • sequence_number: integer

事件序列号。

  • type: "response.mcp_list_tools.completed"

类型,固定为response.mcp_list_tools.completed。

  • "response.mcp_list_tools.completed"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.mcp_list_tools.completed",
  "sequence_number": 1,
  "output_index": 0,
  "item_id": "mcpl_682d4379df088191886b70f4ec39f90403937d5f622d7a90"
}

response.mcp_list_tools.failed

尝试列出可用MCP工具失败时发出。

结构定义

结构名称: BetaResponseMCPListToolsFailedEvent

  • item_id: string

失败的MCP工具调用条目ID。

  • output_index: integer

失败的输出条目索引。

  • sequence_number: integer

事件序列号。

  • type: "response.mcp_list_tools.failed"

类型,固定为response.mcp_list_tools.failed。

  • "response.mcp_list_tools.failed"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.mcp_list_tools.failed",
  "sequence_number": 1,
  "output_index": 0,
  "item_id": "mcpl_682d4379df088191886b70f4ec39f90403937d5f622d7a90"
}

response.mcp_list_tools.in_progress

系统正在取得可用MCP工具列表时发出。

结构定义

结构名称: BetaResponseMCPListToolsInProgressEvent

  • item_id: string

正在处理的MCP工具调用条目ID。

  • output_index: integer

正在处理的输出条目索引。

  • sequence_number: integer

事件序列号。

  • type: "response.mcp_list_tools.in_progress"

类型,固定为response.mcp_list_tools.in_progress。

  • "response.mcp_list_tools.in_progress"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.mcp_list_tools.in_progress",
  "sequence_number": 1,
  "output_index": 0,
  "item_id": "mcpl_682d4379df088191886b70f4ec39f90403937d5f622d7a90"
}

response.code_interpreter_call.in_progress

代码解释器调用进行中时发出。

结构定义

结构名称: BetaResponseCodeInterpreterCallInProgressEvent

  • item_id: string

代码解释器工具调用条目的唯一标识。

  • output_index: integer

响应中代码解释器调用正在进行的输出条目索引。

  • sequence_number: integer

此事件序列号,用于对流式事件排序。

  • type: "response.code_interpreter_call.in_progress"

类型,固定为response.code_interpreter_call.in_progress。

  • "response.code_interpreter_call.in_progress"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.code_interpreter_call.in_progress",
  "output_index": 0,
  "item_id": "ci_12345",
  "sequence_number": 1
}

response.code_interpreter_call.interpreting

代码解释器正在解释代码片段时发出。

结构定义

结构名称: BetaResponseCodeInterpreterCallInterpretingEvent

  • item_id: string

代码解释器工具调用条目的唯一标识。

  • output_index: integer

响应中代码解释器正在解释代码的输出条目索引。

  • sequence_number: integer

此事件序列号,用于对流式事件排序。

  • type: "response.code_interpreter_call.interpreting"

类型,固定为response.code_interpreter_call.interpreting。

  • "response.code_interpreter_call.interpreting"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.code_interpreter_call.interpreting",
  "output_index": 4,
  "item_id": "ci_12345",
  "sequence_number": 1
}

response.code_interpreter_call.completed

代码解释器调用完成时发出。

结构定义

结构名称: BetaResponseCodeInterpreterCallCompletedEvent

  • item_id: string

代码解释器工具调用条目的唯一标识。

  • output_index: integer

响应中代码解释器调用已完成的输出条目索引。

  • sequence_number: integer

此事件序列号,用于对流式事件排序。

  • type: "response.code_interpreter_call.completed"

类型,固定为response.code_interpreter_call.completed。

  • "response.code_interpreter_call.completed"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.code_interpreter_call.completed",
  "output_index": 5,
  "item_id": "ci_12345",
  "sequence_number": 1
}

response.code_interpreter_call_code.delta

代码解释器流式输出部分代码时发出。

结构定义

结构名称: BetaResponseCodeInterpreterCallCodeDeltaEvent

  • delta: string

代码解释器正在流式输出的部分代码片段。

  • item_id: string

代码解释器工具调用条目的唯一标识。

  • output_index: integer

响应中正在流式输出代码的输出条目索引。

  • sequence_number: integer

此事件序列号,用于对流式事件排序。

  • type: "response.code_interpreter_call_code.delta"

类型,固定为response.code_interpreter_call_code.delta。

  • "response.code_interpreter_call_code.delta"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.code_interpreter_call_code.delta",
  "output_index": 0,
  "item_id": "ci_12345",
  "delta": "print('Hello, world')",
  "sequence_number": 1
}

response.code_interpreter_call_code.done

代码解释器确定最终代码片段时发出。

结构定义

结构名称: BetaResponseCodeInterpreterCallCodeDoneEvent

  • code: string

代码解释器输出的最终代码片段。

  • item_id: string

代码解释器工具调用条目的唯一标识。

  • output_index: integer

响应中代码已确定的输出条目索引。

  • sequence_number: integer

此事件序列号,用于对流式事件排序。

  • type: "response.code_interpreter_call_code.done"

类型,固定为response.code_interpreter_call_code.done。

  • "response.code_interpreter_call_code.done"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.code_interpreter_call_code.done",
  "output_index": 3,
  "item_id": "ci_12345",
  "code": "print('done')",
  "sequence_number": 1
}

response.output_text.annotation.added

向输出文本内容添加注解时发出。

结构定义

结构名称: BetaResponseOutputTextAnnotationAddedEvent

  • annotation: 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 } or null

新增的注解对象,详见注解schema。

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

  • annotation_index: integer

注解在内容部分中的索引。

  • content_index: integer

内容部分在输出条目中的索引。

  • item_id: string

接收新增注解的条目唯一标识。

  • output_index: integer

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

  • sequence_number: integer

事件序列号。

  • type: "response.output_text.annotation.added"

类型,固定为response.output_text.annotation.added。

  • "response.output_text.annotation.added"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.output_text.annotation.added",
  "item_id": "item-abc",
  "output_index": 0,
  "content_index": 0,
  "annotation_index": 0,
  "annotation": {
    "type": "file_citation",
    "file_id": "file-abc",
    "index": 0,
    "filename": "example.txt"
  },
  "sequence_number": 1
}

response.queued

响应进入队列、等待处理时发出。

结构定义

结构名称: BetaResponseQueuedEvent

  • response: BetaResponse

正在排队的完整响应对象。

  • id: string

此响应的唯一标识符。

  • access_programs: object { cyber } or null

  • created_at: number

此响应创建时的 Unix 时间戳,单位为秒。

format: unixtime

  • error: BetaResponseError or null

模型未能生成响应时返回的错误对象。

  • code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 18 more

此响应的错误代码。

  • "server_error"

  • "rate_limit_exceeded"

  • "invalid_prompt"

  • "data_residency_mismatch"

  • "bio_policy"

  • "misalignment_policy_violation"

  • "vector_store_timeout"

  • "invalid_image"

  • "invalid_image_format"

  • "invalid_base64_image"

  • "invalid_image_url"

  • "image_too_large"

  • "image_too_small"

  • "image_parse_error"

  • "image_content_policy_violation"

  • "invalid_image_mode"

  • "image_file_too_large"

  • "unsupported_image_media_type"

  • "empty_image_file"

  • "failed_to_download_image"

  • "image_file_not_found"

  • message: string

便于人阅读的错误说明。

  • misalignment: optional object { detailed_explanation, error_type, review_target, steer }

  • detailed_explanation: optional string

对此次阻止操作的公开说明。

  • error_type: optional string or "potentially_unintended_data_transfer" or "potentially_unintended_data_access" or "potentially_unintended_destructive_activity" or "other"

可选的分类;客户端必须能够接受其他值。

  • string

  • SafetyAlertErrorType = "potentially_unintended_data_transfer" or "potentially_unintended_data_access" or "potentially_unintended_destructive_activity" or "other"

可选的分类;客户端必须能够接受其他值。

  • "potentially_unintended_data_transfer"

  • "potentially_unintended_data_access"

  • "potentially_unintended_destructive_activity"

  • "other"

  • review_target: optional string or null

用于明确继续此次审查的不透明目标;不可用时为 null。

pattern: ^[A-Za-z0-9._~:-]+$, minLength: 1, maxLength: 96

  • steer: optional object { message }

可选的公开继续指令。

  • message: string

公开的继续指令。

  • param: optional string or null

与错误相关的请求参数;未记录时为 null。

  • type: optional string or null

原始错误类型;未记录时为 null。

  • incomplete_details: object { reason } or null

说明响应为何未完成的详细信息。

  • reason: optional "max_output_tokens" or "max_messages" or "content_filter" or "steered"

响应未完成的原因。steered表示响应在收到WebSocket response.steer事件后于安全输出边界停止;服务器随后可自动使用排队输入创建后继响应。

  • "max_output_tokens"

  • "max_messages"

  • "content_filter"

  • "steered"

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

插入模型上下文的系统消息或开发者消息。

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

  • string

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

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

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

  • 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

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

  • metadata: map[string] or null

可附加到对象的一组16个键值对,用于结构化保存附加信息,并通过API或控制台查询对象。

键为最长64个字符的字符串,值为最长512个字符的字符串。

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

生成响应的模型ID,例如gpt-6.2-astra。OpenAI提供能力、性能和价格各异的模型,可在模型指南浏览比较。

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

生成响应的模型ID,例如gpt-6.2-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

  • object: "response"

此资源的对象类型,始终为 response。

  • "response"

  • output: array of BetaResponseOutputItem

模型生成的内容条目数组。

output数组的长度和顺序取决于模型响应。不要假定首个条目一定是包含生成内容的assistant消息;可考虑使用SDK支持的output_text属性。

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

模型输出的消息。

  • 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

从文件中检索出的文本。

  • 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 { id, output, status, 7 more }

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

输入模型的文件。

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

  • type: "function_call_output"

类型,固定为 function_call_output。

  • "function_call_output"

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

  • created_by: optional string

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

  • name: optional string

产生输出的工具名称。

  • namespace: optional 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

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

  • 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

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

  • 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

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

  • 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

单击操作。

  • actions: optional BetaComputerActionList

computer_use的扁平化批量操作。每个操作包含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

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

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

  • 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

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

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

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

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

  • 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

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

  • 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 { 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 工具返回的可选文本输出。

  • 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

工具调用的错误,如有。

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

  • 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

决定的可选理由。

  • 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 { id, call_id, output, 5 more }

  • id: string

自定义工具调用输出条目的唯一 ID。

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

输入模型的文件。

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

  • type: "custom_tool_call_output"

类型,固定为 custom_tool_call_output。

  • "custom_tool_call_output"

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

  • created_by: optional string

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

  • parallel_tool_calls: boolean (default: true)

是否允许模型并行执行工具调用。

  • temperature: number or null (default: 1)

采样温度,范围0到2。0.8等较高值使输出更随机,0.2等较低值使输出更集中、更确定。通常建议只修改此参数或top_p中的一个。

minimum: 0, maximum: 2

  • tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more

模型生成响应时如何选择工具,参见tools参数了解可调用工具的定义方式。

  • BetaToolChoiceOptions = "none" or "auto" or "required"

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

none 表示模型直接生成消息,不调用工具。

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

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

  • "none"

  • "auto"

  • "required"

  • BetaToolChoiceAllowed object { mode, tools, type }

将模型可用的工具限制为预先定义的集合。

  • mode: "auto" or "required"

将模型可用的工具限制为预先定义的集合。

auto 允许模型从可用工具中选择,或生成消息。

required 要求模型至少调用一个可用工具。

  • "auto"

  • "required"

  • tools: array of map[unknown]

应允许模型调用的工具定义列表。

对于 Responses API,工具定义列表可以如下所示:

        [
          { "type": "function", "name": "get_weather" },
          { "type": "mcp", "server_label": "deepwiki" },
          { "type": "image_generation" }
        ]

  • type: "allowed_tools"

允许的工具配置类型,固定为 allowed_tools。

  • "allowed_tools"

  • BetaToolChoiceTypes object { type }

指定模型应使用内置工具生成响应,详见内置工具。

  • type: "file_search" or "web_search_preview" or "computer" or 5 more

模型应使用的托管工具类型,详见内置工具。

允许的值为:

  • file_search
  • web_search_preview
  • computer
  • computer_use_preview
  • computer_use
  • code_interpreter
  • image_generation

  • "file_search"

  • "web_search_preview"

  • "computer"

  • "computer_use_preview"

  • "computer_use"

  • "web_search_preview_2025_03_11"

  • "image_generation"

  • "code_interpreter"

  • BetaToolChoiceFunction object { name, type }

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

  • name: string

要调用的函数名称。

  • type: "function"

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

  • "function"

  • BetaToolChoiceMcp object { server_label, type, name }

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

  • server_label: string

要使用的 MCP 服务器标签。

  • type: "mcp"

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

  • "mcp"

  • name: optional string or null

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

  • BetaToolChoiceCustom object { name, type }

使用此选项强制模型调用特定的自定义工具。

  • name: string

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

  • type: "custom"

对于自定义工具调用,类型固定为 custom。

  • "custom"

  • BetaSpecificProgrammaticToolCallingParam object { type }

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

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

  • "programmatic_tool_calling"

  • BetaToolChoiceApplyPatch object { type }

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

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

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

  • "apply_patch"

  • BetaToolChoiceShell object { type }

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

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

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

  • "shell"

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

模型生成响应时可以调用的工具数组。可以通过设置 tool_choice 参数指定使用哪个工具。

支持以下几类工具:

内置工具:OpenAI提供的扩展能力,如网页搜索和文件搜索,详见内置工具。MCP工具:通过自定义MCP服务器或Google Drive、SharePoint等预定义连接器集成第三方系统,详见MCP工具。函数调用(自定义工具):开发者定义的函数,让模型以强类型参数和输出调用你的代码,详见函数调用;也可使用自定义工具调用自己的代码。

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

  • top_p: number or null (default: 1)

核采样是温度采样的替代方式:模型仅考虑累计概率达到top_p的词元。例如0.1表示只考虑累计概率质量前10%的词元。

通常建议只调整此项或 temperature 中的一项,不同时调整两者。

minimum: 0, maximum: 1

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

是否在后台运行模型响应,详见后台模式。

  • completed_at: optional number or null

Response完成时的Unix时间戳,单位为秒,仅在状态为completed时存在。

format: unixtime

  • conversation: optional object { id } or null

此响应所属的对话。该响应的输入条目和输出条目已自动添加到此对话。

  • id: string

与此响应关联的对话的唯一 ID。

  • image: optional object { context_compression }

  • context_compression: "enabled" or "disabled"

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

  • "enabled"

  • "disabled"

  • input_transformations: optional array of object { id, action, reason, type }

未传给模型的推理输入,按输入顺序排列。

  • id: string

原始推理条目的 ID。

  • action: "removed" (default: "removed")

  • "removed"

  • reason: "organization_mismatch" or "end_user_mismatch" or "model_mismatch" or 2 more

  • "organization_mismatch"

  • "end_user_mismatch"

  • "model_mismatch"

  • "prefix_mismatch"

  • "turn_boundary"

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

  • "reasoning"

  • max_output_tokens: optional integer or null

响应可生成词元数的上限,包括可见输出词元及推理词元。

  • max_tool_calls: optional integer or null

一个响应中可处理的内置工具调用总次数上限。此上限适用于所有内置工具调用的合计次数,而非每个工具分别计算。达到上限后,模型进一步调用工具的尝试会被忽略。

  • moderation: optional object { input, output } or null

如果请求了经审核的补全,则包含响应输入和输出的审核结果。

  • input: ModerationResult { categories, category_applied_input_types, category_scores, 3 more } or Error { code, message, type }

对响应输入的审核。

  • ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }

针对响应输入或输出生成的审核结果。

  • categories: map[boolean]

审核类别到布尔值的映射。输入被某类别标记时,该类别值为 true。

  • category_applied_input_types: map[array of "text" or "image"]

各类别评分所涵盖的输入模态。

  • "text"

  • "image"

  • category_scores: map[number]

审核类别到分数的映射。

  • flagged: boolean

表示内容是否被任一类别标记的布尔值。

  • model: string

生成此结果的审核模型。

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

对象类型,成功审核结果中固定为 moderation_result。

  • "moderation_result"

  • Error object { code, message, type }

尝试审核响应输入或输出时产生的错误。

  • code: string

错误代码。

  • message: string

错误消息。

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

对象类型;审核失败时始终为 error。

  • "error"

  • output: ModerationResult { categories, category_applied_input_types, category_scores, 3 more } or Error { code, message, type }

对响应输出的审核。

  • ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }

针对响应输入或输出生成的审核结果。

  • categories: map[boolean]

审核类别到布尔值的映射。输入被某类别标记时,该类别值为 true。

  • category_applied_input_types: map[array of "text" or "image"]

各类别评分所涵盖的输入模态。

  • "text"

  • "image"

  • category_scores: map[number]

审核类别到分数的映射。

  • flagged: boolean

表示内容是否被任一类别标记的布尔值。

  • model: string

生成此结果的审核模型。

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

对象类型,成功审核结果中固定为 moderation_result。

  • "moderation_result"

  • Error object { code, message, type }

尝试审核响应输入或输出时产生的错误。

  • code: string

错误代码。

  • message: string

错误消息。

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

对象类型;审核失败时始终为 error。

  • "error"

  • output_text: optional string or null

仅SDK提供的便利属性,聚合output数组中所有output_text条目的文本(若存在),Python和JavaScript SDK支持此属性。

  • previous_response_id: optional string or null

前一次模型响应的唯一ID,用于多轮对话,详见对话状态。不能与conversation同时使用。

  • prompt: optional BetaResponsePrompt or null

提示词模板及其变量的引用,详见代码中的提示词版本。

  • id: string

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

  • variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile] or null

可选的变量替换映射,用于替换提示词中的变量。替换值可为字符串,也可为图像或文件等其他Response输入类型。

  • string

  • BetaResponseInputText object { text, type, prompt_cache_breakpoint }

输入模型的文本。

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

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

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

输入模型的文件。

  • version: optional string or null

提示词模板的可选版本。

  • prompt_cache_diagnostics: optional CacheMiss { cache_missed_tokens, reason, type, comparison_reusable_tokens } or CacheHit { type } or ComparisonResponseNotFound { type } or Unavailable { type }

为此响应请求的提示词缓存诊断信息。

  • CacheMiss object { cache_missed_tokens, reason, type, comparison_reusable_tokens }

  • cache_missed_tokens: integer

首次检测到差异之后,受影响的输入词元数量估计值。

  • reason: "model_changed" or "prompt_cache_key_changed" or "tools_changed" or 6 more

未复用提示词缓存的原因。

  • "model_changed"

  • "prompt_cache_key_changed"

  • "tools_changed"

  • "text_format_changed"

  • "reasoning_effort_changed"

  • "verbosity_changed"

  • "context_compacted"

  • "input_changed"

  • "service_tier_changed"

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

  • "cache_miss"

  • comparison_reusable_tokens: optional integer

在所比较的响应中,可复用前缀的原始词元数。

  • CacheHit object { type }

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

  • "cache_hit"

  • ComparisonResponseNotFound object { type }

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

  • "comparison_response_not_found"

  • Unavailable object { type }

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

  • "unavailable"

  • prompt_cache_key: optional string or null

供OpenAI缓存相似请求的响应,以优化缓存命中率,替代user字段,详见提示词缓存。

  • prompt_cache_options: optional object { mode, ttl, comparison_response_id }

应用于该响应的提示词缓存选项。支持 gpt-5.6 及更新模型。

  • mode: "implicit" or "explicit"

是否启用了隐式提示词缓存断点。

  • "implicit"

  • "explicit"

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

应用于每个缓存断点的最短保留时间。

  • "30m"

  • "12h"

  • comparison_response_id: optional string or null

用于提示词缓存诊断比较的响应 ID。

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

已弃用,改用 prompt_cache_options.ttl。

提示词缓存保留策略。设为24h启用扩展缓存,使缓存前缀保持活跃更久,最长24小时,详见缓存保留。此字段表达最长保留策略,prompt_cache_options.ttl表达最短缓存寿命;两者独立、互不影响。gpt-5.5、gpt-5.5-pro及后续模型仅支持24h。

对于同时支持 in_memory 和 24h 的较早模型,默认值取决于组织的数据保留策略:

未启用ZDR的组织默认使用24h;启用ZDR且未指定prompt_cache_retention的组织默认使用in_memory。

  • "in_memory"

  • "24h"

  • reasoning: optional object { context, effort, generate_summary, 2 more } or null

推理模型的配置选项。

  • context: optional "auto" or "current_turn" or "all_turns" or null

控制后续轮次向模型呈现哪些推理条目。省略或设为auto时由模型决定上下文模式。gpt-5.6系列默认all_turns,更早模型默认current_turn。

在响应中返回时,表示本次响应实际使用的推理上下文模式。

  • "auto"

  • "current_turn"

  • "all_turns"

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

限制推理模型的推理努力程度。目前支持none、minimal、low、medium、high、xhigh和max。降低努力程度可能加快响应并减少推理词元。并非所有模型支持每个值,具体见推理指南。

  • "none"

  • "minimal"

  • "low"

  • "medium"

  • "high"

  • "xhigh"

  • "max"

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

已弃用:请改用 summary。

模型推理的摘要,有助于调试和理解推理过程。可选auto、concise或detailed。

  • "auto"

  • "concise"

  • "detailed"

  • mode: optional string or "standard" or "pro"

控制请求的推理执行模式。

当此字段出现在返回的响应中时,表示实际使用的执行模式。

  • string

  • "standard" or "pro"

控制请求的推理执行模式。

当此字段出现在返回的响应中时,表示实际使用的执行模式。

  • "standard"

  • "pro"

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

模型推理的摘要,有助于调试和理解推理过程。可选auto、concise或detailed。

computer-use-preview 模型及 gpt-5 之后的推理模型均支持 concise。

  • "auto"

  • "concise"

  • "detailed"

  • safety_identifier: optional string or null

稳定的用户标识,帮助检测应用中可能违反OpenAI使用政策的用户。应使用唯一标识各用户、最长128字符的字符串。建议对用户名或电子邮箱进行哈希,避免发送个人身份信息,详见安全标识。

maxLength: 128

  • service_tier: optional BetaServiceTier or null (default: "auto")

指定处理请求所采用的服务类型。

auto使用项目设置中的服务层级,未另行配置时为default。default使用所选模型的标准价格及性能;flex使用Flex处理。在Responses或Chat Completions请求中设置service_tier=fast或service_tier=priority可启用快速模式,不论传入哪一个,原文此处写明响应显示priority。ultrafast使用受访问控制的Ultrafast层级,当前此原文列为可供gpt-5.6-sol使用,响应显示ultrafast。未设置时默认auto。

设置 service_tier 后,响应体中的同名字段反映实际采用的处理模式,可能与请求参数的值不同。

  • "auto"

  • "default"

  • "flex"

  • "scale"

  • "priority"

  • "fast"

  • "ultrafast"

  • status: optional BetaResponseStatus

响应生成状态,可选completed、failed、in_progress、cancelled、queued或incomplete。

  • "completed"

  • "failed"

  • "in_progress"

  • "cancelled"

  • "queued"

  • "incomplete"

  • text: optional BetaResponseTextConfig

模型文本响应的配置选项,可为纯文本或结构化JSON数据,详见下列指南。

文本输入与输出;结构化输出。

  • format: optional BetaResponseFormatTextConfig

指定模型必须输出的格式的对象。

配置{ "type": "json_schema" }可启用结构化输出,确保模型匹配提供的JSON Schema,详见结构化输出指南。

默认格式为 { "type": "text" },没有额外选项。

不建议用于 gpt-4o 及后续模型:

设置{ "type": "json_object" }可启用旧版JSON模式,确保模型生成合法JSON。支持json_schema的模型优先使用后者。

  • Text object { type }

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

  • type: "text"

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

  • "text"

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

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

  • JSONObject object { type }

JSON对象响应格式,是生成JSON响应的旧方式。支持json_schema的模型建议使用后者。注意,若system或user消息没有明确要求生成JSON,模型不会自行生成JSON。

  • type: "json_object"

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

  • "json_object"

  • verbosity: optional "low" or "medium" or "high" or null (default: "medium")

约束模型响应的详细程度。较低值生成更简洁的响应,较高值生成更详细的响应。目前支持low、medium和high,默认为medium。

  • "low"

  • "medium"

  • "high"

  • tool_usage: optional object { image_gen, web_search }

托管工具报告的用量,独立于基础模型的 usage。无法取得工具用量时可省略。若返回该字段,没有用量记录的工具类别计数为零。

image_gen 合计所有图像生成调用中可取得的词元计数。可能跳过用量记录不完整的调用。输出词元明细和缓存输入计数可省略,省略缓存计数表示缓存用量未知。

web_search.num_requests 统计可计费的搜索次数。打折搜索与打开网页等操作不计入。最终费用请以账单记录为准。

  • image_gen: object { input_tokens, input_tokens_details, output_tokens, 4 more }

图像生成工具调用的汇总用量统计。

  • input_tokens: integer

输入提示词中的图像与文本词元数量。

  • input_tokens_details: object { image_tokens, text_tokens }

图像生成的输入词元明细。

  • image_tokens: integer

输入提示词中的图像词元数量。

  • text_tokens: integer

输入提示词中的文本词元数量。

  • output_tokens: integer

模型生成的输出词元数量。

  • total_tokens: integer

图像生成使用的图像和文本词元总数。

  • cached_tokens: optional integer

  • cached_tokens_details: optional object { cached_image_tokens, cached_text_tokens }

  • cached_image_tokens: integer

  • cached_text_tokens: integer

  • output_tokens_details: optional object { image_tokens, text_tokens }

图像生成的输出词元明细。

  • image_tokens: integer

模型生成的图像输出词元数量。

  • text_tokens: integer

模型生成的文本输出词元数量。

  • web_search: object { num_requests }

网页搜索工具调用的汇总计费用量统计。

  • num_requests: integer

发起的计费网页搜索请求次数。

  • top_logprobs: optional integer or null

0到20之间的整数,指定每个词元位置返回多少个最可能词元及其对数概率;实际返回数量有时会少于请求值。

minimum: 0, maximum: 20

  • truncation: optional "auto" or "disabled" or null (default: "disabled")

模型响应的截断策略。

  • auto:输入超出模型的上下文窗口时,从对话开头移除条目以适配窗口。对部分模型,API 会先从输入上限扣除模型允许的最大输出量,再统计词元。因此,即使设置较低的 max_output_tokens,也可能更早开始截断。
  • disabled(默认值):输入超出模型上下文窗口时,请求会失败并返回 400 错误。

  • "auto"

  • "disabled"

  • usage: optional BetaResponseUsage or null

词元用量详情,包括输入词元、输出词元、输出词元分类和词元总数。

  • 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

使用的总词元数。

  • user: optional string or null

此字段正被safety_identifier和prompt_cache_key取代,维持缓存优化应改用prompt_cache_key。它是终端用户的稳定标识,通过更好地归类相似请求提高命中率,也帮助OpenAI检测和防止滥用,详见安全标识。

  • sequence_number: integer

此事件的序列号。

  • type: "response.queued"

类型,固定为response.queued。

  • "response.queued"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.queued",
  "response": {
    "id": "resp_123",
    "object": "response",
    "access_programs": null,
    "created_at": 1609459200,
    "status": "queued",
    "error": null,
    "incomplete_details": null,
    "instructions": null,
    "model": "gpt-6.2-astra",
    "output": [],
    "parallel_tool_calls": true,
    "temperature": 1,
    "tool_choice": "auto",
    "tools": [],
    "top_p": 1,
    "metadata": {}
  },
  "sequence_number": 1
}

response.custom_tool_call_input.delta

表示自定义工具调用输入增量更新的事件。

结构定义

结构名称: BetaResponseCustomToolCallInputDeltaEvent

  • delta: string

自定义工具调用的增量输入数据。

  • item_id: string

与此事件关联的API条目唯一标识。

  • output_index: integer

此增量适用的输出索引。

  • sequence_number: integer

事件序列号。

  • type: "response.custom_tool_call_input.delta"

事件类型标识。

  • "response.custom_tool_call_input.delta"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

例中文字:部分输入文本

{
  "type": "response.custom_tool_call_input.delta",
  "sequence_number": 1,
  "output_index": 0,
  "item_id": "ctc_1234567890abcdef",
  "delta": "partial input text"
}

response.custom_tool_call_input.done

表示自定义工具调用输入已经完整的事件。

结构定义

结构名称: BetaResponseCustomToolCallInputDoneEvent

  • input: string

自定义工具调用的完整输入数据。

  • item_id: string

与此事件关联的API条目唯一标识。

  • output_index: integer

此事件适用的输出索引。

  • sequence_number: integer

事件序列号。

  • type: "response.custom_tool_call_input.done"

事件类型标识。

  • "response.custom_tool_call_input.done"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

例中文字:最终完整输入文本

{
  "type": "response.custom_tool_call_input.done",
  "sequence_number": 1,
  "output_index": 0,
  "item_id": "ctc_1234567890abcdef",
  "input": "final complete input text"
}

error

发生错误时发出。

结构定义

结构名称: BetaResponseErrorEvent

  • code: string or null

错误代码。

  • message: string

错误消息。

  • param: string or null

错误参数。

  • sequence_number: integer

事件序列号。

  • type: "error"

类型,固定为error。

  • "error"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

例中文字:发生了错误。

{
  "type": "error",
  "code": "ERR_SOMETHING",
  "message": "Something went wrong",
  "param": null,
  "sequence_number": 1
}

response.audio.delta

产生部分音频响应时发出。

结构定义

结构名称: BetaResponseAudioDeltaEvent

  • delta: string

一块Base64编码的响应音频字节。

  • sequence_number: integer

流式响应中此分块的序列号。

  • type: "response.audio.delta"

类型,固定为response.audio.delta。

  • "response.audio.delta"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.audio.delta",
  "response_id": "resp_123",
  "delta": "base64encoded...",
  "sequence_number": 1
}

response.audio.done

音频响应完成时发出。

结构定义

结构名称: BetaResponseAudioDoneEvent

  • sequence_number: integer

增量的序列号。

  • type: "response.audio.done"

类型,固定为response.audio.done。

  • "response.audio.done"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.audio.done",
  "response_id": "resp-123",
  "sequence_number": 1
}

response.audio.transcript.delta

产生部分音频转录文本时发出。

结构定义

结构名称: BetaResponseAudioTranscriptDeltaEvent

  • delta: string

音频响应的部分转录文本。

  • sequence_number: integer

事件序列号。

  • type: "response.audio.transcript.delta"

类型,固定为response.audio.transcript.delta。

  • "response.audio.transcript.delta"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

例中文字:……部分转录文本……

{
  "type": "response.audio.transcript.delta",
  "response_id": "resp_123",
  "delta": " ... partial transcript ... ",
  "sequence_number": 1
}

response.audio.transcript.done

完整音频转录完成时发出。

结构定义

结构名称: BetaResponseAudioTranscriptDoneEvent

  • sequence_number: integer

事件序列号。

  • type: "response.audio.transcript.done"

类型,固定为response.audio.transcript.done。

  • "response.audio.transcript.done"

  • agent: optional object { agent_name } or null

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.audio.transcript.done",
  "response_id": "resp_123",
  "sequence_number": 1
}

response.compaction.compacting

为压缩触发器采样新的摘要内容时发出,事件本身不包含摘要内容。

结构定义

结构名称: BetaResponseCompactionCompactingStreamingEvent

  • item_id: string

压缩输出条目的ID。

  • output_index: integer

压缩输出条目的索引。

  • sequence_number: integer

已发出事件的序列号。

  • type: "response.compaction.compacting" (default: "response.compaction.compacting")

事件类型,固定为response.compaction.compacting。

  • "response.compaction.compacting"

  • agent: optional object { agent_name }

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.compaction.compacting",
  "sequence_number": 0,
  "agent": {
    "agent_name": "agent_name"
  },
  "output_index": 0,
  "item_id": "item_id"
}

response.shell_call_command.added

向工具调用添加shell命令的流式事件。

结构定义

结构名称: BetaResponseShellCallCommandAddedStreamingEvent

  • command: string

新增的shell命令。

  • command_index: integer

新增shell命令的索引。

  • output_index: integer

被更新输出条目的索引。

  • sequence_number: integer

已发出事件的序列号。

  • type: "response.shell_call_command.added" (default: "response.shell_call_command.added")

类型,固定为response.shell_call_command.added。

  • "response.shell_call_command.added"

  • agent: optional object { agent_name }

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.shell_call_command.added",
  "sequence_number": 0,
  "agent": {
    "agent_name": "agent_name"
  },
  "output_index": 0,
  "command_index": 0,
  "command": "command"
}

response.shell_call_command.delta

增量更新shell命令的流式事件。

结构定义

结构名称: BetaResponseShellCallCommandDeltaStreamingEvent

  • command_index: integer

已更新shell命令的索引。

  • delta: string

追加的shell命令增量。

  • output_index: integer

被更新输出条目的索引。

  • sequence_number: integer

已发出事件的序列号。

  • type: "response.shell_call_command.delta" (default: "response.shell_call_command.delta")

类型,固定为response.shell_call_command.delta。

  • "response.shell_call_command.delta"

  • agent: optional object { agent_name }

此多智能体流式事件所属的智能体。

  • agent_name: string

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

  • obfuscation: optional string

用于填充事件载荷的混淆字符串。

示例

{
  "type": "response.shell_call_command.delta",
  "sequence_number": 0,
  "agent": {
    "agent_name": "agent_name"
  },
  "output_index": 0,
  "command_index": 0,
  "delta": "delta",
  "obfuscation": "obfuscation"
}

response.shell_call_command.done

shell命令完成的流式事件。

结构定义

结构名称: BetaResponseShellCallCommandDoneStreamingEvent

  • command: string

发出的最终shell命令。

  • command_index: integer

已完成shell命令的索引。

  • output_index: integer

被更新输出条目的索引。

  • sequence_number: integer

已发出事件的序列号。

  • type: "response.shell_call_command.done" (default: "response.shell_call_command.done")

类型,固定为response.shell_call_command.done。

  • "response.shell_call_command.done"

  • agent: optional object { agent_name }

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.shell_call_command.done",
  "sequence_number": 0,
  "agent": {
    "agent_name": "agent_name"
  },
  "output_index": 0,
  "command_index": 0,
  "command": "command"
}

response.shell_call_output_content.delta

增量添加shell调用输出的流式事件。

结构定义

结构名称: BetaResponseShellCallOutputContentDeltaStreamingEvent

  • command_index: integer

产生输出的shell命令索引。

  • delta: object { stderr, stdout }

发出的标准输出或标准错误增量。

  • stderr: optional string

发出的标准错误增量。

  • stdout: optional string

发出的标准输出增量。

  • item_id: string

已更新输出条目的ID。

  • output_index: integer

被更新输出条目的索引。

  • sequence_number: integer

已发出事件的序列号。

  • type: "response.shell_call_output_content.delta" (default: "response.shell_call_output_content.delta")

类型,固定为response.shell_call_output_content.delta。

  • "response.shell_call_output_content.delta"

  • agent: optional object { agent_name }

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.shell_call_output_content.delta",
  "sequence_number": 0,
  "agent": {
    "agent_name": "agent_name"
  },
  "item_id": "item_id",
  "output_index": 0,
  "command_index": 0,
  "delta": {
    "stdout": "stdout",
    "stderr": "stderr"
  }
}

response.shell_call_output_content.done

shell调用输出完成的流式事件。

结构定义

结构名称: BetaResponseShellCallOutputContentDoneStreamingEvent

  • command_index: integer

产生输出的shell命令索引。

  • item_id: string

已更新输出条目的ID。

  • 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

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

  • output_index: integer

被更新输出条目的索引。

  • sequence_number: integer

已发出事件的序列号。

  • type: "response.shell_call_output_content.done" (default: "response.shell_call_output_content.done")

类型,固定为response.shell_call_output_content.done。

  • "response.shell_call_output_content.done"

  • agent: optional object { agent_name }

此多智能体流式事件所属的智能体。

  • agent_name: string

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

示例

{
  "type": "response.shell_call_output_content.done",
  "sequence_number": 0,
  "agent": {
    "agent_name": "agent_name"
  },
  "item_id": "item_id",
  "output_index": 0,
  "command_index": 0,
  "output": [
    {
      "stdout": "stdout",
      "stderr": "stderr",
      "outcome": {
        "type": "timeout"
      },
      "created_by": "created_by"
    }
  ]
}
以上内容是否对您有帮助:
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号