OpenAI 计算多智能体输入词元数

2026-11-19 17:50 更新

获取输入词元数量

post /responses/input_tokens?beta=true

返回请求的输入词元数量。

返回一个对象,其中 object 为 response.input_tokens,并包含 input_tokens 计数。

请求头参数

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

  • "responses_multi_agent=v1"

请求体参数

内容类型为 application/json。

  • conversation: optional string or BetaResponseConversationParam or null

此响应所属的对话。对话条目会放在本次请求的input_items前面;响应完成后,其输入和输出条目会自动添加到此对话。

  • ConversationID = string

对话的唯一 ID。

  • BetaResponseConversationParam object { id }

此响应所属的对话。

  • id: string

对话的唯一 ID。

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

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

  • string

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

maxLength: 10485760

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

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

maxItems: 131072

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

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

  • content: string or BetaResponseInputMessageContentList

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

  • TextInput = string

输入模型的文本。

  • BetaResponseInputMessageContentList = array of BetaResponseInputContent

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

  • BetaResponseInputText object { text, type, prompt_cache_breakpoint }

输入模型的文本。

  • text: string

输入模型的文本。

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

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

  • "input_text"

  • prompt_cache_breakpoint: optional object { mode, ttl }

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

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

断点模式,固定为 explicit。

  • "explicit"

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

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

  • "30m"

  • "12h"

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

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

  • detail: BetaImageDetail

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

  • "low"

  • "high"

  • "auto"

  • "original"

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

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

  • "input_image"

  • file_id: optional string or null

要发送给模型的文件 ID。

  • image_url: optional string or null

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

format: uri

  • prompt_cache_breakpoint: optional object { mode, ttl }

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

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

断点模式,固定为 explicit。

  • "explicit"

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

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

  • "30m"

  • "12h"

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

输入模型的文件。

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

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

  • "input_file"

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

发送给模型的文件细节级别。使用 auto 由系统选择;对于 GPT-5.6 及后续模型,auto 使用高质量渲染,可能增加输入词元用量。使用 low 进行成本较低的渲染,或使用 high 以更高质量渲染文件。默认为 auto。

  • "auto"

  • "low"

  • "high"

  • file_data: optional string

要发送给模型的文件内容。

  • file_id: optional string or null

要发送给模型的文件 ID。

  • file_url: optional string

要发送给模型的文件 URL。

format: uri

  • filename: optional string

要发送给模型的文件名。

  • prompt_cache_breakpoint: optional object { mode, ttl }

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

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

断点模式,固定为 explicit。

  • "explicit"

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

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

  • "30m"

  • "12h"

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

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

  • "user"

  • "assistant"

  • "system"

  • "developer"

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

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

  • "commentary"

  • "final_answer"

  • type: optional "message"

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

  • "message"

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

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

  • content: BetaResponseInputMessageContentList

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

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

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

  • "user"

  • "system"

  • "developer"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

  • type: optional "message"

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

  • "message"

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

模型输出的消息。

  • id: string

输出消息的唯一 ID。

  • content: array of BetaResponseOutputText or BetaResponseOutputRefusal

输出消息的内容。

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

模型输出的文本。

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

文本输出的注解。

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

文件引用。

  • file_id: string

文件 ID。

  • filename: string

被引用文件的文件名。

  • index: integer

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

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

类型,固定为 file_citation。

  • "file_citation"

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

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

  • end_index: integer

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

  • start_index: integer

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

  • title: string

网络资源标题。

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

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

  • "url_citation"

  • url: string

网络资源 URL。

format: uri

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

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

  • container_id: string

容器文件 ID。

  • end_index: integer

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

  • file_id: string

文件 ID。

  • filename: string

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

  • start_index: integer

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

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

类型,固定为 container_file_citation。

  • "container_file_citation"

  • FilePath object { file_id, index, type }

文件路径。

  • file_id: string

文件 ID。

  • index: integer

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

  • type: "file_path"

类型,固定为 file_path。

  • "file_path"

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

  • token: string

  • bytes: array of number

  • logprob: number

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

  • token: string

  • bytes: array of number

  • logprob: number

  • text: string

模型输出的文本内容。

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

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

  • "output_text"

  • BetaResponseOutputRefusal object { refusal, type }

模型的拒绝响应。

  • refusal: string

模型给出的拒绝原因。

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

类型,固定为 refusal。

  • "refusal"

  • role: "assistant"

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

  • "assistant"

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

  • type: "message"

类型,固定为 message。

  • "message"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

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

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

  • "commentary"

  • "final_answer"

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

文件搜索工具调用的结果,详见文件搜索指南。

  • id: string

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

  • queries: array of string

搜索文件所用的查询。

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

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

  • "in_progress"

  • "searching"

  • "completed"

  • "incomplete"

  • "failed"

  • type: "file_search_call"

类型,固定为 file_search_call。

  • "file_search_call"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

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

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

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

可附加到对象的一组16个键值对,可用于以结构化格式保存额外信息,并通过API或控制台查询对象。键为最长64个字符的字符串;值可以是最长512个字符的字符串、布尔值或数字。

  • string

maxLength: 512

  • number

  • boolean

  • file_id: optional string

文件的唯一 ID。

  • filename: optional string

文件名。

  • score: optional number

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

format: float

  • text: optional string

从文件中检索出的文本。

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

对计算机使用工具的调用,详见计算机使用指南。

  • id: string

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

  • call_id: string

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

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

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

  • id: string

待处理安全检查的 ID。

  • code: optional string or null

待处理安全检查的类型。

  • message: optional string or null

待处理安全检查的详情。

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

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

类型,固定为 computer_call。

  • "computer_call"

  • action: optional BetaComputerAction

单击操作。

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

单击操作。

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

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

  • "left"

  • "right"

  • "wheel"

  • "back"

  • "forward"

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

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

  • "click"

  • x: integer

单击位置的 x 坐标。

  • y: integer

单击位置的 y 坐标。

  • keys: optional array of string or null

单击时保持按下的按键。

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

双击操作。

  • keys: array of string or null

双击时保持按下的按键。

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

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

  • "double_click"

  • x: integer

双击位置的 x 坐标。

  • y: integer

双击位置的 y 坐标。

  • Drag object { path, type, keys }

拖动操作。

  • path: array of object { x, y }

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

            [
              { x: 100, y: 200 },
              { x: 200, y: 300 }
            ]

  • x: integer

x 坐标。

  • y: integer

y 坐标。

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

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

  • "drag"

  • keys: optional array of string or null

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

  • Keypress object { keys, type }

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

  • keys: array of string

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

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

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

  • "keypress"

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

鼠标移动操作。

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

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

  • "move"

  • x: integer

移动目标的 x 坐标。

  • y: integer

移动目标的 y 坐标。

  • keys: optional array of string or null

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

  • Screenshot object { type }

截屏操作。

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

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

  • "screenshot"

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

滚动操作。

  • scroll_x: integer

水平滚动距离。

  • scroll_y: integer

垂直滚动距离。

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

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

  • "scroll"

  • x: integer

滚动位置的 x 坐标。

  • y: integer

滚动位置的 y 坐标。

  • keys: optional array of string or null

滚动时保持按下的按键。

  • Type object { text, type }

输入文本的操作。

  • text: string

要输入的文本。

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

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

  • "type"

  • Wait object { type }

等待操作。

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

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

  • "wait"

  • actions: optional BetaComputerActionList

computer_use的扁平化批量操作。每个操作包含type判别字段及该操作专属字段。

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

单击操作。

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

双击操作。

  • Drag object { path, type, keys }

拖动操作。

  • Keypress object { keys, type }

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

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

鼠标移动操作。

  • Screenshot object { type }

截屏操作。

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

滚动操作。

  • Type object { text, type }

输入文本的操作。

  • Wait object { type }

等待操作。

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

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

计算机工具调用的输出。

  • call_id: string

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

minLength: 1, maxLength: 64

  • output: BetaResponseComputerToolCallOutputScreenshot

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

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

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

  • "computer_screenshot"

  • file_id: optional string

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

  • image_url: optional string

截图图像的 URL。

format: uri

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

类型,固定为 computer_call_output。

  • "computer_call_output"

  • id: optional string or null

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

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

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

  • id: string

待处理安全检查的 ID。

  • code: optional string or null

待处理安全检查的类型。

  • message: optional string or null

待处理安全检查的详情。

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

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

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

  • id: string

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

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

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

  • "in_progress"

  • "searching"

  • "completed"

  • "failed"

  • "incomplete"

  • type: "web_search_call"

类型,固定为 web_search_call。

  • "web_search_call"

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

描述此次网页搜索具体操作的对象,包括模型如何使用网页:search、open_page、find_in_page。

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

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

  • type: "search"

操作类型。

  • "search"

  • queries: optional array of string

搜索查询列表。

  • query: optional string

搜索查询。

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

搜索所用的信息来源。

  • type: "url"

来源类型,固定为 url。

  • "url"

  • url: string

来源 URL。

format: uri

  • OpenPage object { type, url }

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

  • type: "open_page"

操作类型。

  • "open_page"

  • url: optional string or null

模型打开的 URL。

format: uri

  • FindInPage object { pattern, type, url }

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

  • pattern: string

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

  • type: "find_in_page"

操作类型。

  • "find_in_page"

  • url: optional string or null

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

format: uri

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

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

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

  • arguments: string

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

  • call_id: string

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

  • name: string

要运行的函数名称。

  • type: "function_call"

类型,固定为 function_call。

  • "function_call"

  • id: optional string

函数工具调用的唯一 ID。

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

  • async: optional boolean

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

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

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

  • Direct object { type }

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

  • "direct"

  • Program object { caller_id, type }

  • caller_id: string

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

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

  • "program"

  • namespace: optional string

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

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

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

函数工具调用的输出。

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

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

  • string

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

maxLength: 10485760

  • array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent

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

  • BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }

输入模型的文本。

  • text: string

输入模型的文本。

maxLength: 10485760

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

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

  • "input_text"

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

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

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

断点模式,固定为 explicit。

  • "explicit"

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

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

  • "30m"

  • "12h"

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

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

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

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

  • "input_image"

  • detail: optional BetaImageDetail or null

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

  • file_id: optional string or null

要发送给模型的文件 ID。

  • image_url: optional string or null

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

maxLength: 20971520, format: uri

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

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

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

断点模式,固定为 explicit。

  • "explicit"

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

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

  • "30m"

  • "12h"

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

输入模型的文件。

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

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

  • "input_file"

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

发送给模型的文件细节级别。使用 auto 由系统选择;对于 GPT-5.6 及后续模型,auto 使用高质量渲染,可能增加输入词元用量。使用 low 进行成本较低的渲染,或使用 high 以更高质量渲染文件。默认为 auto。

  • "auto"

  • "low"

  • "high"

  • file_data: optional string or null

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

maxLength: 73400320

  • file_id: optional string or null

要发送给模型的文件 ID。

  • file_url: optional string or null

要发送给模型的文件 URL。

format: uri

  • filename: optional string or null

要发送给模型的文件名。

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

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

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

断点模式,固定为 explicit。

  • "explicit"

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

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

  • "30m"

  • "12h"

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

类型,固定为 function_call_output。

  • "function_call_output"

  • id: optional string or null

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

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

  • call_id: optional string or null

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

minLength: 1, maxLength: 64

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

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

  • Direct object { type }

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

调用方类型,固定为 direct。

  • "direct"

  • Program object { caller_id, type }

  • caller_id: string

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

minLength: 1, maxLength: 64

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

调用方类型,固定为 program。

  • "program"

  • name: optional string or null

产生输出的工具名称。

minLength: 1, maxLength: 128

  • namespace: optional string or null

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

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

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

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

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

  • author: string

发送方智能体的标识。

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

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

  • BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }

输入模型的文本。

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

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

  • EncryptedContent object { encrypted_content, type }

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

  • encrypted_content: string

不透明的加密内容。

maxLength: 10485760

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

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

  • "encrypted_content"

  • recipient: string

接收方智能体的标识。

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

条目类型,固定为 agent_message。

  • "agent_message"

  • id: optional string or null

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

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

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

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

已执行的多智能体操作。

  • "spawn_agent"

  • "interrupt_agent"

  • "list_agents"

  • "send_message"

  • "followup_task"

  • "wait_agent"

  • arguments: string

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

  • call_id: string

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

minLength: 1, maxLength: 64

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

条目类型,固定为 multi_agent_call。

  • "multi_agent_call"

  • id: optional string or null

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

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

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

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

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

  • "spawn_agent"

  • "interrupt_agent"

  • "list_agents"

  • "send_message"

  • "followup_task"

  • "wait_agent"

  • call_id: string

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

minLength: 1, maxLength: 64

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

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

  • text: string

文本内容。

maxLength: 10485760

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

内容类型,固定为 output_text。

  • "output_text"

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

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

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

  • file_id: string

文件 ID。

  • filename: string

被引用文件的文件名。

  • index: integer

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

minimum: 0

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

引用类型,固定为 file_citation。

  • "file_citation"

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

  • end_index: integer

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

minimum: 0

  • start_index: integer

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

minimum: 0

  • title: string

被引用资源的标题。

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

引用类型,固定为 url_citation。

  • "url_citation"

  • url: string

被引用资源的 URL。

format: uri

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

  • container_id: string

容器 ID。

  • end_index: integer

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

minimum: 0

  • file_id: string

容器文件 ID。

  • filename: string

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

  • start_index: integer

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

minimum: 0

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

引用类型,固定为 container_file_citation。

  • "container_file_citation"

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

条目类型,固定为 multi_agent_call_output。

  • "multi_agent_call_output"

  • id: optional string or null

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

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

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

  • arguments: unknown

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

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

条目类型,固定为 tool_search_call。

  • "tool_search_call"

  • id: optional string or null

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

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

  • call_id: optional string or null

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

minLength: 1, maxLength: 64

  • execution: optional "server" or "client"

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

  • "server"

  • "client"

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

工具搜索调用的状态。

  • "in_progress"

  • "completed"

  • "incomplete"

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

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

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

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

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

  • name: string

要调用的函数名称。

  • parameters: map[unknown] or null

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

  • strict: boolean or null

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

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

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

  • "function"

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

工具调用的上下文。

  • "direct"

  • "programmatic"

  • async: optional boolean

  • defer_loading: optional boolean

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

  • description: optional string or null

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

  • output_schema: optional map[unknown] or null

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

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

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

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

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

  • "file_search"

  • vector_store_ids: array of string

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

  • filters: optional ComparisonFilter { key, type, value } or unknown or null

要应用的筛选条件。

  • ComparisonFilter object { key, type, value }

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

  • key: string

要与值比较的属性键。

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

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

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

  • "eq"

  • "ne"

  • "gt"

  • "gte"

  • "lt"

  • "lte"

  • "in"

  • "nin"

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

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

  • string

  • number

  • boolean

  • array of string or number

  • string

  • number

  • BetaCompoundFilter = unknown

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

  • max_num_results: optional integer

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

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

搜索结果的排序选项。

  • hybrid_search: optional object { embedding_weight, text_weight }

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

  • embedding_weight: number

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

  • text_weight: number

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

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

文件搜索所用的排序器。

  • "auto"

  • "default-2024-11-15"

  • score_threshold: optional number

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

  • Computer object { type }

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

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

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

  • "computer"

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

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

  • display_height: integer

计算机显示区域的高度。

  • display_width: integer

计算机显示区域的宽度。

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

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

  • "windows"

  • "mac"

  • "linux"

  • "ubuntu"

  • "browser"

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

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

  • "computer_use_preview"

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

在互联网搜索与提示词相关的来源,详见网页搜索工具。

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

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

  • "web_search"

  • "web_search_2025_08_26"

  • external_web_access: optional boolean (default: true)

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

  • filters: optional object { allowed_domains } or null

搜索的筛选条件。

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

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

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

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

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

  • "low"

  • "medium"

  • "high"

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

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

  • city: optional string or null

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

  • country: optional string or null

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

  • region: optional string or null

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

  • timezone: optional string or null

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

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

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

  • "approximate"

  • Mcp object { server_label, type, allowed_callers, 9 more }

通过远程模型上下文协议(MCP)服务器向模型提供更多工具,详见MCP说明。

  • server_label: string

此 MCP 服务器的标签,用于在工具调用中标识服务器。

  • type: "mcp"

MCP 工具类型,固定为 mcp。

  • "mcp"

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

工具调用的上下文。

minItems: 1

  • "direct"

  • "programmatic"

  • allowed_tools: optional array of string or McpToolFilter { read_only, tool_names } or null

允许的工具名称列表或筛选对象。

  • McpAllowedTools = array of string

允许的工具名称组成的字符串数组。

  • McpToolFilter object { read_only, tool_names }

用于指定允许哪些工具的筛选对象。

  • read_only: optional boolean

说明工具会修改数据还是仅执行只读操作。如果MCP服务器标注了readOnlyHint,就会匹配这个筛选条件。

  • tool_names: optional array of string

允许的工具名称列表。

  • authorization: optional string

用于远程MCP服务器的OAuth访问令牌,既可用于自定义MCP服务器URL,也可用于服务连接器。应用须处理OAuth授权流程,并在此提供令牌。

  • connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more

服务连接器的标识,例如ChatGPT中的连接器。server_url、connector_id、tunnel_id须提供其一,详见服务连接器。

此字段在2026年9月1日之后发布的模型中已弃用。远程MCP服务器改用server_url,安全MCP隧道连接改用tunnel_id。

当前支持的 connector_id 值如下:

Dropbox:connector_dropbox;Gmail:connector_gmail;Google Calendar:connector_googlecalendar;Google Drive:connector_googledrive;Microsoft Teams:connector_microsoftteams;Outlook Calendar:connector_outlookcalendar;Outlook Email:connector_outlookemail;SharePoint:connector_sharepoint。

  • "connector_dropbox"

  • "connector_gmail"

  • "connector_googlecalendar"

  • "connector_googledrive"

  • "connector_microsoftteams"

  • "connector_outlookcalendar"

  • "connector_outlookemail"

  • "connector_sharepoint"

  • defer_loading: optional boolean

此 MCP 工具是否延迟加载并通过工具搜索发现。

  • headers: optional map[string] or null

发送给MCP服务器的可选HTTP请求头,用于身份验证或其他目的。

  • require_approval: optional McpToolApprovalFilter { always, never } or "always" or "never" or null (default: "always")

指定 MCP 服务器的哪些工具需要批准。

  • McpToolApprovalFilter object { always, never }

指定哪些工具需要批准,可选always、never或筛选对象。

  • always: optional object { read_only, tool_names }

用于指定允许哪些工具的筛选对象。

  • read_only: optional boolean

说明工具会修改数据还是仅执行只读操作。如果MCP服务器标注了readOnlyHint,就会匹配这个筛选条件。

  • tool_names: optional array of string

允许的工具名称列表。

  • never: optional object { read_only, tool_names }

用于指定允许哪些工具的筛选对象。

  • read_only: optional boolean

说明工具会修改数据还是仅执行只读操作。如果MCP服务器标注了readOnlyHint,就会匹配这个筛选条件。

  • tool_names: optional array of string

允许的工具名称列表。

  • McpToolApprovalSetting = "always" or "never"

为所有工具统一指定批准策略,可选always或never。always要求所有工具获得批准,never表示工具无需批准。

  • "always"

  • "never"

  • server_description: optional string

MCP 服务器的可选描述,用于提供更多上下文。

  • server_url: optional string

MCP服务器URL。server_url、connector_id、tunnel_id三者必须提供其一。

format: uri

  • tunnel_id: optional string

替代直接服务器URL的安全MCP隧道ID。server_url、connector_id、tunnel_id三者必须提供其一。

pattern: ^tunnel_[a-z0-9]{32}$

  • CodeInterpreter object { container, type, allowed_callers }

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

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

代码解释器容器,可指定容器ID,或指定包含已上传文件ID的对象,以及可选的memory_limit设置。

  • string

容器 ID。

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

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

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

固定为 auto。

  • "auto"

  • file_ids: optional array of string

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

maxItems: 50

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

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

  • "1g"

  • "4g"

  • "16g"

  • "64g"

  • network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist

容器的网络访问策略。

  • BetaContainerNetworkPolicyDisabled object { type }

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

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

  • "disabled"

  • BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }

  • allowed_domains: array of string

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

minItems: 1

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

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

  • "allowlist"

  • domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret

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

minItems: 1

  • domain: string

密钥关联的域名。

minLength: 1

  • name: string

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

minLength: 1

  • value: string

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

minLength: 1, maxLength: 10485760

  • type: "code_interpreter"

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

  • "code_interpreter"

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

工具调用的上下文。

minItems: 1

  • "direct"

  • "programmatic"

  • ProgrammaticToolCalling object { type }

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

工具类型,固定为 programmatic_tool_calling。

  • "programmatic_tool_calling"

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

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

  • type: "image_generation"

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

  • "image_generation"

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

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

  • "generate"

  • "edit"

  • "auto"

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

生成图像的背景,可选transparent、opaque或auto。gpt-image-2.5-sunburst、gpt-image-2.5-flare及其2026-09-08快照支持不透明和透明背景;gpt-image-2的透明背景为预览能力。使用transparent时,输出格式须设为png或webp。默认为auto。

  • "transparent"

  • "opaque"

  • "auto"

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

图像规划使用的计算量,独立于渲染质量。生成图像时,此设置覆盖外层响应的 reasoning.effort。省略时会继承外层支持的推理强度,或使用图像模型配置的默认值。生成 SVG 时,此设置控制参考图像的规划计算量,SVG 作者模型使用自己的推理设置。

  • "low"

  • "medium"

  • "high"

  • frame_count: optional integer (default: 9)

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

minimum: 2, maximum: 16

  • frame_duration_ms: optional integer (default: 200)

GIF 每帧的时长,以毫秒计,四舍五入到 10 毫秒。要求 output_format 为 gif。默认值为 200。

minimum: 20, maximum: 2000

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

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

  • "high"

  • "low"

  • input_image_mask: optional object { file_id, image_url }

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

  • file_id: optional string

蒙版图像的文件 ID。

  • image_url: optional string

采用 Base64 编码的蒙版图像。

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

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

gpt-image-1 已于 2026 年 10 月 23 日停用,可改用 gpt-image-2.5-sunburst 或 gpt-image-2.5-flare。

  • string

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

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

gpt-image-1 已于 2026 年 10 月 23 日停用,可改用 gpt-image-2.5-sunburst 或 gpt-image-2.5-flare。

  • "gpt-image-1"

  • "gpt-image-1-mini"

  • "gpt-image-2"

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

  • "gpt-image-2.5-sunburst"

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

  • "gpt-image-2.5-flare"

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

  • "gpt-image-2.6-sunburst"

  • "gpt-image-2.6-flare"

  • "gpt-image-1.5"

  • "chatgpt-image-latest"

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

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

  • "auto"

  • "low"

  • output_compression: optional integer (default: 100)

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

minimum: 0, maximum: 100

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

生成图像的格式。可选 png、webp、jpeg、gif 或 svg,默认值为 png。GIF 和 SVG 要求模型支持对应格式。GIF 不支持部分图像流式输出(partial_images 大于 0)、input_image_mask 或自定义 output_compression。Responses 生命周期事件仍可流式返回。

  • "png"

  • "webp"

  • "jpeg"

  • "gif"

  • "svg"

  • partial_images: optional integer (default: 0)

流式模式中生成的部分图像数量,范围为 0(默认值)到 3。

minimum: 0, maximum: 3

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

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

  • "low"

  • "medium"

  • "high"

  • "xhigh"

  • "max"

  • "auto"

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

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

  • string

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

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

  • "1024x1024"

  • "1024x1536"

  • "1536x1024"

  • "auto"

  • svg: optional object { model, reasoning }

SVG 作者模型设置。要求 output_format 为 svg。启用 SVG 模型选择时,省略此对象将使用外层响应模型。其他情况下会使用默认 SVG 作者模型,且无法显式覆盖。

  • model: optional string

minLength: 1

  • reasoning: optional object { effort } or null

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

  • effort: optional "none" or "minimal" or "low" or 4 more

控制模型为此次请求投入的推理强度。

  • "none"

  • "minimal"

  • "low"

  • "medium"

  • "high"

  • "xhigh"

  • "max"

  • LocalShell object { type }

允许模型在本地环境执行 shell 命令的工具。

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

本地 shell 工具类型,固定为 local_shell。

  • "local_shell"

  • Shell object { type, allowed_callers, environment }

允许模型执行 shell 命令的工具。

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

shell 工具类型,固定为 shell。

  • "shell"

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

工具调用的上下文。

minItems: 1

  • "direct"

  • "programmatic"

  • environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference or null

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

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

为此请求自动创建容器。

  • "container_auto"

  • file_ids: optional array of string

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

maxItems: 50

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

容器的内存上限。

  • "1g"

  • "4g"

  • "16g"

  • "64g"

  • network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist

容器的网络访问策略。

  • BetaContainerNetworkPolicyDisabled object { type }

  • BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }

  • skills: optional array of BetaSkillReference or BetaInlineSkill

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

maxItems: 200

  • BetaSkillReference object { skill_id, type, version }

  • skill_id: string

引用的技能 ID。

minLength: 1, maxLength: 64

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

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

  • "skill_reference"

  • version: optional string

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

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

  • description: string

技能描述。

  • name: string

技能名称。

  • source: BetaInlineSkillSource

内联技能载荷。

  • data: string

采用 Base64 编码的技能 ZIP 包。

minLength: 1, maxLength: 70254592

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

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

  • "application/zip"

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

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

  • "base64"

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

为此请求定义内联技能。

  • "inline"

  • BetaLocalEnvironment object { type, skills }

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

使用本地计算机环境。

  • "local"

  • skills: optional array of BetaLocalSkill

可选的技能列表。

maxItems: 200

  • description: string

技能描述。

  • name: string

技能名称。

  • path: string

包含该技能的目录路径。

  • BetaContainerReference object { container_id, type }

  • container_id: string

引用的容器 ID。

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

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

  • "container_reference"

  • Custom object { name, type, allowed_callers, 4 more }

使用指定格式处理输入的自定义工具。参阅自定义工具。

  • name: string

自定义工具的名称,用于在工具调用中标识它。

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

自定义工具类型,固定为 custom。

  • "custom"

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

工具调用的上下文。

minItems: 1

  • "direct"

  • "programmatic"

  • async: optional boolean

工具响应是否可以异步返回,而非在下一次创建响应时立即返回。

  • defer_loading: optional boolean

此工具是否应延迟加载并通过工具搜索发现。

  • description: optional string

自定义工具的可选描述,用于提供更多上下文。

  • format: optional Text { type } or Grammar { definition, syntax, type }

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

  • Text object { type }

无约束的自由文本。

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

无约束文本格式,固定为 text。

  • "text"

  • Grammar object { definition, syntax, type }

用户定义的语法。

  • definition: string

语法定义。

  • syntax: "lark" or "regex"

语法定义的语法类型,可选 lark 或 regex。

  • "lark"

  • "regex"

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

语法格式,固定为 grammar。

  • "grammar"

  • BetaToolSearchOutputNamespaceTool object { description, name, tools, type }

将函数工具或自定义工具归入共享命名空间。

  • description: string

展示给模型的命名空间描述。

  • name: string

工具调用使用的命名空间名称,例如 crm。

minLength: 1

  • tools: array of Function { name, type, allowed_callers, 6 more } or Custom { name, type, allowed_callers, 4 more }

此命名空间内已加载的函数工具或自定义工具。

minItems: 1

  • Function object { name, type, allowed_callers, 6 more }

  • name: string

已加载的函数工具名称。

pattern: ^(?![\s\S]*[\r\n])[a-zA-Z0-9_.-]+$, minLength: 1, maxLength: 128

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

  • "function"

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

工具调用的上下文。

minItems: 1

  • "direct"

  • "programmatic"

  • async: optional boolean

工具响应是否可以异步返回,而非在下一次创建响应时立即返回。

  • defer_loading: optional boolean

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

  • description: optional string or null

  • output_schema: optional map[unknown] or null

描述此函数工具字符串输出中编码的 JSON 值的 JSON Schema,不用于描述内容数组输出。

  • parameters: optional unknown or null

  • strict: optional boolean or null

是否强制执行严格参数校验。省略时,模式兼容的情况下 Responses 会尝试严格校验,否则退回非严格校验。

  • Custom object { name, type, allowed_callers, 4 more }

使用指定格式处理输入的自定义工具。参阅自定义工具。

  • name: string

自定义工具的名称,用于在工具调用中标识它。

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

自定义工具类型,固定为 custom。

  • "custom"

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

工具调用的上下文。

minItems: 1

  • "direct"

  • "programmatic"

  • async: optional boolean

工具响应是否可以异步返回,而非在下一次创建响应时立即返回。

  • defer_loading: optional boolean

此工具是否应延迟加载并通过工具搜索发现。

  • description: optional string

自定义工具的可选描述,用于提供更多上下文。

  • format: optional Text { type } or Grammar { definition, syntax, type }

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

  • Text object { type }

无约束的自由文本。

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

无约束文本格式,固定为 text。

  • "text"

  • Grammar object { definition, syntax, type }

用户定义的语法。

  • definition: string

语法定义。

  • syntax: "lark" or "regex"

语法定义的语法类型,可选 lark 或 regex。

  • "lark"

  • "regex"

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

语法格式,固定为 grammar。

  • "grammar"

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

工具类型,固定为 namespace。

  • "namespace"

  • ToolSearch object { type, description, execution, parameters }

用于延迟加载工具的托管工具搜索或自带工具(BYOT)搜索配置。

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

工具类型,固定为 tool_search。

  • "tool_search"

  • description: optional string or null

客户端执行的工具搜索工具展示给模型的描述。

  • execution: optional "server" or "client"

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

  • "server"

  • "client"

  • parameters: optional unknown or null

客户端执行的工具搜索工具的参数模式。

  • WebSearchPreview object { type, search_content_types, search_context_size, user_location }

搜索网页以获取可用于响应的相关结果的工具。参阅网页搜索工具。

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

网页搜索工具类型,可选 web_search_preview 或 web_search_preview_2025_03_11。

  • "web_search_preview"

  • "web_search_preview_2025_03_11"

  • search_content_types: optional array of "text" or "image"

  • "text"

  • "image"

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

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

  • "low"

  • "medium"

  • "high"

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

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

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

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

  • "approximate"

  • city: optional string or null

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

  • country: optional string or null

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

  • region: optional string or null

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

  • timezone: optional string or null

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

  • ApplyPatch object { type, allowed_callers }

允许助手使用统一差异格式创建、删除或更新文件。

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

工具类型,固定为 apply_patch。

  • "apply_patch"

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

工具调用的上下文。

minItems: 1

  • "direct"

  • "programmatic"

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

条目类型,固定为 tool_search_output。

  • "tool_search_output"

  • id: optional string or null

此工具搜索输出的唯一 ID。

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

  • call_id: optional string or null

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

minLength: 1, maxLength: 64

  • execution: optional "server" or "client"

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

  • "server"

  • "client"

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

工具搜索输出的状态。

  • "in_progress"

  • "completed"

  • "incomplete"

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

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

提供额外工具的角色,仅支持 developer。

  • "developer"

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

在此条目中提供的额外工具列表。

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

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

  • name: string

要调用的函数名称。

  • parameters: map[unknown] or null

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

  • strict: boolean or null

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

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

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

  • "function"

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

工具调用的上下文。

  • "direct"

  • "programmatic"

  • async: optional boolean

  • defer_loading: optional boolean

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

  • description: optional string or null

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

  • output_schema: optional map[unknown] or null

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

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

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

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

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

  • "file_search"

  • vector_store_ids: array of string

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

  • filters: optional ComparisonFilter { key, type, value } or unknown or null

要应用的筛选条件。

  • ComparisonFilter object { key, type, value }

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

  • key: string

要与值比较的属性键。

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

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

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

  • "eq"

  • "ne"

  • "gt"

  • "gte"

  • "lt"

  • "lte"

  • "in"

  • "nin"

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

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

  • string

  • number

  • boolean

  • array of string or number

  • string

  • number

  • BetaCompoundFilter = unknown

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

  • max_num_results: optional integer

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

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

搜索结果的排序选项。

  • hybrid_search: optional object { embedding_weight, text_weight }

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

  • embedding_weight: number

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

  • text_weight: number

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

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

文件搜索所用的排序器。

  • "auto"

  • "default-2024-11-15"

  • score_threshold: optional number

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

  • Computer object { type }

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

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

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

  • "computer"

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

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

  • display_height: integer

计算机显示区域的高度。

  • display_width: integer

计算机显示区域的宽度。

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

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

  • "windows"

  • "mac"

  • "linux"

  • "ubuntu"

  • "browser"

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

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

  • "computer_use_preview"

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

在互联网搜索与提示词相关的来源,详见网页搜索工具。

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

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

  • "web_search"

  • "web_search_2025_08_26"

  • external_web_access: optional boolean (default: true)

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

  • filters: optional object { allowed_domains } or null

搜索的筛选条件。

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

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

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

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

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

  • "low"

  • "medium"

  • "high"

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

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

  • city: optional string or null

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

  • country: optional string or null

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

  • region: optional string or null

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

  • timezone: optional string or null

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

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

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

  • "approximate"

  • Mcp object { server_label, type, allowed_callers, 9 more }

通过远程模型上下文协议(MCP)服务器向模型提供更多工具,详见MCP说明。

  • server_label: string

此 MCP 服务器的标签,用于在工具调用中标识服务器。

  • type: "mcp"

MCP 工具类型,固定为 mcp。

  • "mcp"

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

工具调用的上下文。

minItems: 1

  • "direct"

  • "programmatic"

  • allowed_tools: optional array of string or McpToolFilter { read_only, tool_names } or null

允许的工具名称列表或筛选对象。

  • McpAllowedTools = array of string

允许的工具名称组成的字符串数组。

  • McpToolFilter object { read_only, tool_names }

用于指定允许哪些工具的筛选对象。

  • read_only: optional boolean

说明工具会修改数据还是仅执行只读操作。如果MCP服务器标注了readOnlyHint,就会匹配这个筛选条件。

  • tool_names: optional array of string

允许的工具名称列表。

  • authorization: optional string

用于远程MCP服务器的OAuth访问令牌,既可用于自定义MCP服务器URL,也可用于服务连接器。应用须处理OAuth授权流程,并在此提供令牌。

  • connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more

服务连接器的标识,例如ChatGPT中的连接器。server_url、connector_id、tunnel_id须提供其一,详见服务连接器。

此字段在2026年9月1日之后发布的模型中已弃用。远程MCP服务器改用server_url,安全MCP隧道连接改用tunnel_id。

当前支持的 connector_id 值如下:

Dropbox:connector_dropbox;Gmail:connector_gmail;Google Calendar:connector_googlecalendar;Google Drive:connector_googledrive;Microsoft Teams:connector_microsoftteams;Outlook Calendar:connector_outlookcalendar;Outlook Email:connector_outlookemail;SharePoint:connector_sharepoint。

  • "connector_dropbox"

  • "connector_gmail"

  • "connector_googlecalendar"

  • "connector_googledrive"

  • "connector_microsoftteams"

  • "connector_outlookcalendar"

  • "connector_outlookemail"

  • "connector_sharepoint"

  • defer_loading: optional boolean

此 MCP 工具是否延迟加载并通过工具搜索发现。

  • headers: optional map[string] or null

发送给MCP服务器的可选HTTP请求头,用于身份验证或其他目的。

  • require_approval: optional McpToolApprovalFilter { always, never } or "always" or "never" or null (default: "always")

指定 MCP 服务器的哪些工具需要批准。

  • McpToolApprovalFilter object { always, never }

指定哪些工具需要批准,可选always、never或筛选对象。

  • always: optional object { read_only, tool_names }

用于指定允许哪些工具的筛选对象。

  • read_only: optional boolean

说明工具会修改数据还是仅执行只读操作。如果MCP服务器标注了readOnlyHint,就会匹配这个筛选条件。

  • tool_names: optional array of string

允许的工具名称列表。

  • never: optional object { read_only, tool_names }

用于指定允许哪些工具的筛选对象。

  • read_only: optional boolean

说明工具会修改数据还是仅执行只读操作。如果MCP服务器标注了readOnlyHint,就会匹配这个筛选条件。

  • tool_names: optional array of string

允许的工具名称列表。

  • McpToolApprovalSetting = "always" or "never"

为所有工具统一指定批准策略,可选always或never。always要求所有工具获得批准,never表示工具无需批准。

  • "always"

  • "never"

  • server_description: optional string

MCP 服务器的可选描述,用于提供更多上下文。

  • server_url: optional string

MCP服务器URL。server_url、connector_id、tunnel_id三者必须提供其一。

format: uri

  • tunnel_id: optional string

替代直接服务器URL的安全MCP隧道ID。server_url、connector_id、tunnel_id三者必须提供其一。

pattern: ^tunnel_[a-z0-9]{32}$

  • CodeInterpreter object { container, type, allowed_callers }

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

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

代码解释器容器,可指定容器ID,或指定包含已上传文件ID的对象,以及可选的memory_limit设置。

  • string

容器 ID。

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

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

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

固定为 auto。

  • "auto"

  • file_ids: optional array of string

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

maxItems: 50

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

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

  • "1g"

  • "4g"

  • "16g"

  • "64g"

  • network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist

容器的网络访问策略。

  • BetaContainerNetworkPolicyDisabled object { type }

  • BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }

  • type: "code_interpreter"

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

  • "code_interpreter"

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

工具调用的上下文。

minItems: 1

  • "direct"

  • "programmatic"

  • ProgrammaticToolCalling object { type }

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

工具类型,固定为 programmatic_tool_calling。

  • "programmatic_tool_calling"

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

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

  • type: "image_generation"

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

  • "image_generation"

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

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

  • "generate"

  • "edit"

  • "auto"

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

生成图像的背景,可选transparent、opaque或auto。gpt-image-2.5-sunburst、gpt-image-2.5-flare及其2026-09-08快照支持不透明和透明背景;gpt-image-2的透明背景为预览能力。使用transparent时,输出格式须设为png或webp。默认为auto。

  • "transparent"

  • "opaque"

  • "auto"

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

图像规划使用的计算量,独立于渲染质量。生成图像时,此设置覆盖外层响应的 reasoning.effort。省略时会继承外层支持的推理强度,或使用图像模型配置的默认值。生成 SVG 时,此设置控制参考图像的规划计算量,SVG 作者模型使用自己的推理设置。

  • "low"

  • "medium"

  • "high"

  • frame_count: optional integer (default: 9)

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

minimum: 2, maximum: 16

  • frame_duration_ms: optional integer (default: 200)

GIF 每帧的时长,以毫秒计,四舍五入到 10 毫秒。要求 output_format 为 gif。默认值为 200。

minimum: 20, maximum: 2000

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

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

  • "high"

  • "low"

  • input_image_mask: optional object { file_id, image_url }

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

  • file_id: optional string

蒙版图像的文件 ID。

  • image_url: optional string

采用 Base64 编码的蒙版图像。

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

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

gpt-image-1 已于 2026 年 10 月 23 日停用,可改用 gpt-image-2.5-sunburst 或 gpt-image-2.5-flare。

  • string

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

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

gpt-image-1 已于 2026 年 10 月 23 日停用,可改用 gpt-image-2.5-sunburst 或 gpt-image-2.5-flare。

  • "gpt-image-1"

  • "gpt-image-1-mini"

  • "gpt-image-2"

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

  • "gpt-image-2.5-sunburst"

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

  • "gpt-image-2.5-flare"

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

  • "gpt-image-2.6-sunburst"

  • "gpt-image-2.6-flare"

  • "gpt-image-1.5"

  • "chatgpt-image-latest"

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

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

  • "auto"

  • "low"

  • output_compression: optional integer (default: 100)

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

minimum: 0, maximum: 100

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

生成图像的格式。可选 png、webp、jpeg、gif 或 svg,默认值为 png。GIF 和 SVG 要求模型支持对应格式。GIF 不支持部分图像流式输出(partial_images 大于 0)、input_image_mask 或自定义 output_compression。Responses 生命周期事件仍可流式返回。

  • "png"

  • "webp"

  • "jpeg"

  • "gif"

  • "svg"

  • partial_images: optional integer (default: 0)

流式模式中生成的部分图像数量,范围为 0(默认值)到 3。

minimum: 0, maximum: 3

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

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

  • "low"

  • "medium"

  • "high"

  • "xhigh"

  • "max"

  • "auto"

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

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

  • string

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

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

  • "1024x1024"

  • "1024x1536"

  • "1536x1024"

  • "auto"

  • svg: optional object { model, reasoning }

SVG 作者模型设置。要求 output_format 为 svg。启用 SVG 模型选择时,省略此对象将使用外层响应模型。其他情况下会使用默认 SVG 作者模型,且无法显式覆盖。

  • model: optional string

minLength: 1

  • reasoning: optional object { effort } or null

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

  • effort: optional "none" or "minimal" or "low" or 4 more

控制模型为此次请求投入的推理强度。

  • "none"

  • "minimal"

  • "low"

  • "medium"

  • "high"

  • "xhigh"

  • "max"

  • LocalShell object { type }

允许模型在本地环境执行 shell 命令的工具。

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

本地 shell 工具类型,固定为 local_shell。

  • "local_shell"

  • Shell object { type, allowed_callers, environment }

允许模型执行 shell 命令的工具。

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

shell 工具类型,固定为 shell。

  • "shell"

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

工具调用的上下文。

minItems: 1

  • "direct"

  • "programmatic"

  • environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference or null

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

  • BetaLocalEnvironment object { type, skills }

  • BetaContainerReference object { container_id, type }

  • Custom object { name, type, allowed_callers, 4 more }

使用指定格式处理输入的自定义工具。参阅自定义工具。

  • name: string

自定义工具的名称,用于在工具调用中标识它。

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

自定义工具类型,固定为 custom。

  • "custom"

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

工具调用的上下文。

minItems: 1

  • "direct"

  • "programmatic"

  • async: optional boolean

工具响应是否可以异步返回,而非在下一次创建响应时立即返回。

  • defer_loading: optional boolean

此工具是否应延迟加载并通过工具搜索发现。

  • description: optional string

自定义工具的可选描述,用于提供更多上下文。

  • format: optional Text { type } or Grammar { definition, syntax, type }

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

  • Text object { type }

无约束的自由文本。

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

无约束文本格式,固定为 text。

  • "text"

  • Grammar object { definition, syntax, type }

用户定义的语法。

  • definition: string

语法定义。

  • syntax: "lark" or "regex"

语法定义的语法类型,可选 lark 或 regex。

  • "lark"

  • "regex"

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

语法格式,固定为 grammar。

  • "grammar"

  • Namespace object { description, name, tools, type }

将函数工具或自定义工具归入共享命名空间。

  • description: string

展示给模型的命名空间描述。

  • name: string

工具调用使用的命名空间名称,例如 crm。

minLength: 1

  • tools: array of Function { name, type, allowed_callers, 6 more } or Custom { name, type, allowed_callers, 4 more }

此命名空间内可用的函数工具或自定义工具。

minItems: 1

  • Function object { name, type, allowed_callers, 6 more }

  • name: string

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

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

  • "function"

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

工具调用的上下文。

minItems: 1

  • "direct"

  • "programmatic"

  • async: optional boolean

工具响应是否可以异步返回,而非在下一次创建响应时立即返回。

  • defer_loading: optional boolean

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

  • description: optional string or null

  • output_schema: optional map[unknown] or null

描述此函数工具字符串输出中编码的 JSON 值的 JSON Schema,不用于描述内容数组输出。

  • parameters: optional unknown or null

  • strict: optional boolean or null

是否强制执行严格参数校验。省略时,模式兼容的情况下 Responses 会尝试严格校验,否则退回非严格校验。

  • Custom object { name, type, allowed_callers, 4 more }

使用指定格式处理输入的自定义工具。参阅自定义工具。

  • name: string

自定义工具的名称,用于在工具调用中标识它。

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

自定义工具类型,固定为 custom。

  • "custom"

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

工具调用的上下文。

minItems: 1

  • "direct"

  • "programmatic"

  • async: optional boolean

工具响应是否可以异步返回,而非在下一次创建响应时立即返回。

  • defer_loading: optional boolean

此工具是否应延迟加载并通过工具搜索发现。

  • description: optional string

自定义工具的可选描述,用于提供更多上下文。

  • format: optional Text { type } or Grammar { definition, syntax, type }

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

  • Text object { type }

无约束的自由文本。

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

无约束文本格式,固定为 text。

  • "text"

  • Grammar object { definition, syntax, type }

用户定义的语法。

  • definition: string

语法定义。

  • syntax: "lark" or "regex"

语法定义的语法类型,可选 lark 或 regex。

  • "lark"

  • "regex"

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

语法格式,固定为 grammar。

  • "grammar"

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

工具类型,固定为 namespace。

  • "namespace"

  • ToolSearch object { type, description, execution, parameters }

用于延迟加载工具的托管工具搜索或自带工具(BYOT)搜索配置。

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

工具类型,固定为 tool_search。

  • "tool_search"

  • description: optional string or null

客户端执行的工具搜索工具展示给模型的描述。

  • execution: optional "server" or "client"

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

  • "server"

  • "client"

  • parameters: optional unknown or null

客户端执行的工具搜索工具的参数模式。

  • WebSearchPreview object { type, search_content_types, search_context_size, user_location }

搜索网页以获取可用于响应的相关结果的工具。参阅网页搜索工具。

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

网页搜索工具类型,可选 web_search_preview 或 web_search_preview_2025_03_11。

  • "web_search_preview"

  • "web_search_preview_2025_03_11"

  • search_content_types: optional array of "text" or "image"

  • "text"

  • "image"

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

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

  • "low"

  • "medium"

  • "high"

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

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

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

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

  • "approximate"

  • city: optional string or null

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

  • country: optional string or null

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

  • region: optional string or null

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

  • timezone: optional string or null

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

  • ApplyPatch object { type, allowed_callers }

允许助手使用统一差异格式创建、删除或更新文件。

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

工具类型,固定为 apply_patch。

  • "apply_patch"

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

工具调用的上下文。

minItems: 1

  • "direct"

  • "programmatic"

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

条目类型,固定为 additional_tools。

  • "additional_tools"

  • id: optional string or null

此额外工具条目的唯一 ID。

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

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

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

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

条目类型,固定为 configuration_update。

  • "configuration_update"

  • id: optional string or null

配置更新条目的唯一 ID。

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

  • reasoning: optional object { effort }

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

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

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

  • "none"

  • "minimal"

  • "low"

  • "medium"

  • "high"

  • "xhigh"

  • "max"

  • text: optional object { format }

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

  • format: Text { type } or BetaResponseFormatTextJSONSchemaConfig

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

  • Text object { type }

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

  • type: "text"

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

  • "text"

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

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

  • name: string

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

  • schema: map[unknown]

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

  • type: "json_schema"

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

  • "json_schema"

  • description: optional string

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

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

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

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

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

  • id: string

推理内容的唯一标识。

  • summary: array of object { text, type }

推理摘要内容。

  • text: string

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

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

类型,固定为 summary_text。

  • "summary_text"

  • type: "reasoning"

类型,固定为 reasoning。

  • "reasoning"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

  • content: optional array of object { text, type }

推理文本内容。

  • text: string

模型生成的推理文本。

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

类型,固定为 reasoning_text。

  • "reasoning_text"

  • encrypted_content: optional string or null

推理条目的加密内容。POST /v1/responses及WebSocket response.create请求返回的推理条目默认填充此字段。

流式处理中,后续请求应使用response.output_item.done事件中的已完成推理条目及其encrypted_content。response.output_item.added中的加密内容可能不完整。在store为false或使用零数据保留时尤其重要。

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

  • Compaction object { encrypted_content, type, id, agent }

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

  • encrypted_content: string

压缩摘要的加密内容。

maxLength: 104857600

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

类型,固定为 compaction。

  • "compaction"

  • id: optional string or null

压缩条目 ID。

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

  • ImageGenerationCall object { id, result, status, 10 more }

模型发起的图像生成请求。

  • id: string

图像生成调用的唯一 ID。

  • result: string or null

Base64 编码的生成图像。

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

图像生成调用的状态。

  • "in_progress"

  • "completed"

  • "generating"

  • "failed"

  • type: "image_generation_call"

类型,固定为 image_generation_call。

  • "image_generation_call"

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

用于图像生成的操作。

  • "generate"

  • "edit"

  • "auto"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

  • background: optional "transparent" or "opaque" or "auto" or null

生成图像使用的背景设置。

  • "transparent"

  • "opaque"

  • "auto"

  • error: optional object { code, message, param, 2 more }

审核失败的详情,如可用。

  • code: string or null

错误代码。

  • message: string

错误描述。

  • param: string or null

关联的请求参数。

  • type: string

错误类型。

  • moderation_details: optional object { categories, moderation_stage }

moderation_blocked 错误的公开详情,如可用。

  • categories: array of string

公开的审核类别,未来可能增加新的类别值。

  • moderation_stage: "input" or "output" or "unknown"

审核阻止图像生成调用的阶段。

  • "input"

  • "output"

  • "unknown"

  • output_format: optional "png" or "webp" or "jpeg" or 2 more or null

生成图像使用的输出格式。

  • "png"

  • "webp"

  • "jpeg"

  • "gif"

  • "svg"

  • quality: optional "low" or "medium" or "high" or 3 more or null

图像生成工具调用生成的图像质量,可选 low、medium、high、xhigh、max 或 auto。

  • "low"

  • "medium"

  • "high"

  • "xhigh"

  • "max"

  • "auto"

  • revised_prompt: optional string or null

模型改写提示词后实际使用的提示词。

  • size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or null

图像尺寸,采用 WIDTHxHEIGHT 字符串形式,例如 1536x864。

  • string

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

图像尺寸,采用 WIDTHxHEIGHT 字符串形式,例如 1536x864。

  • "1024x1024"

  • "1024x1536"

  • "1536x1024"

  • svg_usage: optional object { input_tokens, model, output_tokens, 2 more }

  • input_tokens: integer

  • model: string

  • output_tokens: integer

  • reasoning_tokens: integer

  • total_tokens: integer

  • CodeInterpreterCall object { id, code, container_id, 4 more }

运行代码的工具调用。

  • id: string

代码解释器工具调用的唯一 ID。

  • code: string or null

要运行的代码,不可用时为 null。

  • container_id: string

运行代码使用的容器 ID。

  • outputs: array of Logs { logs, type } or Image { type, url } or null

代码解释器产生的日志、图像等输出;没有可用输出时可为null。

  • Logs object { logs, type }

代码解释器的日志输出。

  • logs: string

代码解释器的日志输出。

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

类型,固定为 logs。

  • "logs"

  • Image object { type, url }

代码解释器的图像输出。

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

类型,固定为 image。

  • "image"

  • url: string

代码解释器输出图像的 URL。

format: uri

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

代码解释器工具调用的状态,有效值为 in_progress、completed、incomplete、interpreting 和 failed。

  • "in_progress"

  • "completed"

  • "incomplete"

  • "interpreting"

  • "failed"

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

类型,固定为 code_interpreter_call。

  • "code_interpreter_call"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

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

在本地 shell 上运行命令的工具调用。

  • id: string

本地 shell 调用的唯一 ID。

  • action: object { command, env, type, 3 more }

在服务器上执行 shell 命令。

  • command: array of string

要运行的命令。

  • env: map[string]

要为命令设置的环境变量。

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

类型,固定为 exec。

  • "exec"

  • timeout_ms: optional integer or null

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

  • user: optional string or null

可选的运行命令的用户。

  • working_directory: optional string or null

可选的运行命令的工作目录。

  • call_id: string

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

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

本地 shell 调用的状态。

  • "in_progress"

  • "completed"

  • "incomplete"

  • type: "local_shell_call"

类型,固定为 local_shell_call。

  • "local_shell_call"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

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

本地 shell 工具调用的输出。

  • id: string

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

  • output: string

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

  • type: "local_shell_call_output"

类型,固定为 local_shell_call_output。

  • "local_shell_call_output"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

  • ShellCall object { action, call_id, type, 5 more }

表示请求执行一个或多个 shell 命令的工具。

  • action: object { commands, max_output_length, timeout_ms }

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

  • commands: array of string

按顺序交给执行环境运行的 shell 命令。

  • max_output_length: optional integer or null

从合并的 stdout 和 stderr 输出中最多捕获的 UTF-8 字符数。

  • timeout_ms: optional integer or null

允许 shell 命令运行的最大实际时长,单位为毫秒。

  • call_id: string

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

minLength: 1, maxLength: 64

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

类型,固定为 shell_call。

  • "shell_call"

  • id: optional string or null

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

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

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

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

  • Direct object { type }

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

调用方类型,固定为 direct。

  • "direct"

  • Program object { caller_id, type }

  • caller_id: string

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

minLength: 1, maxLength: 64

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

调用方类型,固定为 program。

  • "program"

  • environment: optional BetaLocalEnvironment or BetaContainerReference or null

执行 shell 命令的环境。

  • BetaLocalEnvironment object { type, skills }

  • BetaContainerReference object { container_id, type }

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

  • ShellCallOutput object { call_id, output, type, 5 more }

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

  • call_id: string

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

minLength: 1, maxLength: 64

  • output: array of BetaResponseFunctionShellCallOutputContent

捕获的 stdout 和 stderr 输出块,以及关联的执行结果。

  • outcome: Timeout { type } or Exit { exit_code, type }

此 shell 调用关联的退出或超时结果。

  • Timeout object { type }

表示 shell 调用超过其配置的时间限制。

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

结果类型,固定为 timeout。

  • "timeout"

  • Exit object { exit_code, type }

表示 shell 命令已结束,并返回退出码。

  • exit_code: integer

shell 进程返回的退出码。

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

结果类型,固定为 exit。

  • "exit"

  • stderr: string

捕获的 shell 调用的 stderr 输出。

maxLength: 10485760

  • stdout: string

捕获的 shell 调用的 stdout 输出。

maxLength: 10485760

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

类型,固定为 shell_call_output。

  • "shell_call_output"

  • id: optional string or null

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

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

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

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

  • Direct object { type }

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

调用方类型,固定为 direct。

  • "direct"

  • Program object { caller_id, type }

  • caller_id: string

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

minLength: 1, maxLength: 64

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

调用方类型,固定为 program。

  • "program"

  • max_output_length: optional integer or null

此 shell 调用合并输出中捕获的最大 UTF-8 字符数。

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

shell 调用输出的状态。

  • "in_progress"

  • "completed"

  • "incomplete"

  • ApplyPatchCall object { call_id, operation, status, 4 more }

表示请求使用差异补丁创建、删除或更新文件的工具调用。

  • call_id: string

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

minLength: 1, maxLength: 64

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

apply_patch 工具调用具体的创建、删除或更新指令。

  • CreateFile object { diff, path, type }

通过 apply_patch 工具创建新文件的指令。

  • diff: string

创建文件时应用的统一差异内容。

maxLength: 10485760

  • path: string

相对于工作区根目录的待创建文件路径。

minLength: 1

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

操作类型,固定为 create_file。

  • "create_file"

  • DeleteFile object { path, type }

通过 apply_patch 工具删除已有文件的指令。

  • path: string

相对于工作区根目录的待删除文件路径。

minLength: 1

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

操作类型,固定为 delete_file。

  • "delete_file"

  • UpdateFile object { diff, path, type }

通过 apply_patch 工具更新已有文件的指令。

  • diff: string

应用于已有文件的统一差异内容。

maxLength: 10485760

  • path: string

相对于工作区根目录的待更新文件路径。

minLength: 1

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

操作类型,固定为 update_file。

  • "update_file"

  • status: "in_progress" or "completed"

apply_patch 工具调用状态,可选 in_progress 或 completed。

  • "in_progress"

  • "completed"

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

类型,固定为 apply_patch_call。

  • "apply_patch_call"

  • id: optional string or null

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

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

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

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

  • Direct object { type }

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

调用方类型,固定为 direct。

  • "direct"

  • Program object { caller_id, type }

  • caller_id: string

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

minLength: 1, maxLength: 64

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

调用方类型,固定为 program。

  • "program"

  • ApplyPatchCallOutput object { call_id, status, type, 4 more }

apply_patch 工具调用发出的流式输出。

  • call_id: string

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

minLength: 1, maxLength: 64

  • status: "completed" or "failed"

apply_patch 工具调用输出的状态,可选 completed 或 failed。

  • "completed"

  • "failed"

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

类型,固定为 apply_patch_call_output。

  • "apply_patch_call_output"

  • id: optional string or null

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

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

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

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

  • Direct object { type }

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

调用方类型,固定为 direct。

  • "direct"

  • Program object { caller_id, type }

  • caller_id: string

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

minLength: 1, maxLength: 64

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

调用方类型,固定为 program。

  • "program"

  • output: optional string or null

apply_patch 工具可选的可读日志文本,例如补丁结果或错误。

maxLength: 10485760

  • McpListTools object { id, server_label, tools, 3 more }

MCP 服务器可用的工具列表。

  • id: string

列表的唯一 ID。

  • server_label: string

MCP 服务器标签。

  • tools: array of object { input_schema, name, annotations, description }

服务器可用的工具。

  • input_schema: unknown

描述工具输入的 JSON Schema。

  • name: string

工具名称。

  • annotations: optional unknown or null

工具的额外注解。

  • description: optional string or null

工具描述。

  • type: "mcp_list_tools"

类型,固定为 mcp_list_tools。

  • "mcp_list_tools"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

  • error: optional string or null

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

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

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

  • id: string

批准请求的唯一 ID。

  • arguments: string

工具参数的 JSON 字符串。

  • name: string

要运行的工具名称。

  • server_label: string

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

  • type: "mcp_approval_request"

类型,固定为 mcp_approval_request。

  • "mcp_approval_request"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

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

对 MCP 批准请求的响应。

  • approval_request_id: string

所回应的批准请求的 ID。

  • approve: boolean

请求是否获准。

  • type: "mcp_approval_response"

类型,固定为 mcp_approval_response。

  • "mcp_approval_response"

  • id: optional string or null

批准响应的唯一 ID。

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

  • reason: optional string or null

决定的可选理由。

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

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

  • id: string

工具调用的唯一 ID。

  • arguments: string

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

  • name: string

已运行的工具名称。

  • server_label: string

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

  • type: "mcp_call"

类型,固定为 mcp_call。

  • "mcp_call"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

  • approval_request_id: optional string or null

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

  • error: optional BetaMcpToolCallError or null

工具调用的错误,如有。

  • McpProtocolError object { code, message, type }

  • code: integer

  • message: string

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

  • "mcp_protocol_error"

  • McpToolExecutionError object { content, type }

  • content: unknown

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

  • "mcp_tool_execution_error"

  • HTTPError object { code, message, type }

  • code: integer

  • message: string

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

  • "http_error"

  • output: optional string or null

工具调用的输出。

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

工具调用状态,可选 in_progress、completed、incomplete、calling 或 failed。

  • "in_progress"

  • "completed"

  • "incomplete"

  • "calling"

  • "failed"

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

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

  • call_id: string

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

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

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

  • StringOutput = string

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

  • OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile

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

  • BetaResponseInputText object { text, type, prompt_cache_breakpoint }

输入模型的文本。

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

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

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

输入模型的文件。

  • type: "custom_tool_call_output"

类型,固定为 custom_tool_call_output。

  • "custom_tool_call_output"

  • id: optional string

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

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

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

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

  • Direct object { type }

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

调用方类型,固定为 direct。

  • "direct"

  • Program object { caller_id, type }

  • caller_id: string

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

minLength: 1, maxLength: 64

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

调用方类型,固定为 program。

  • "program"

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

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

  • call_id: string

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

  • input: string

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

  • name: string

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

  • type: "custom_tool_call"

类型,固定为 custom_tool_call。

  • "custom_tool_call"

  • id: optional string

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

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

  • async: optional boolean

自定义工具调用是否异步运行。

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

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

  • Direct object { type }

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

  • "direct"

  • Program object { caller_id, type }

  • caller_id: string

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

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

  • "program"

  • namespace: optional string

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

  • CompactionTrigger object { type, id, agent }

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

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

类型,固定为 compaction_trigger。

  • "compaction_trigger"

  • id: optional string or null

此压缩触发器的唯一 ID。

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

  • ItemReference object { id, agent, type }

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

  • id: string

要引用的条目的 ID。

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

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

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

  • "item_reference"

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

  • id: string

此 program 条目的唯一 ID。

  • call_id: string

program 条目的稳定调用 ID。

minLength: 1, maxLength: 64

  • code: string

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

maxLength: 10485760

  • fingerprint: string

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

maxLength: 10485760

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

条目类型,固定为 program。

  • "program"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

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

  • id: string

此程序输出条目的唯一 ID。

  • call_id: string

program 条目的调用 ID。

minLength: 1, maxLength: 64

  • result: string

program 条目生成的结果。

maxLength: 10485760

  • status: "completed" or "incomplete"

程序输出的终态。

  • "completed"

  • "incomplete"

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

条目类型,固定为 program_output。

  • "program_output"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

  • instructions: optional string or null

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

  • model: optional string or null

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

  • parallel_tool_calls: optional boolean or null

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

  • personality: optional string or "friendly" or "pragmatic"

应用于此请求的模型专属风格预设。省略时使用模型的默认风格。支持的值可能随时间增加。值最多为 64 个字符。

  • string

  • "friendly" or "pragmatic"

应用于此请求的模型专属风格预设。省略时使用模型的默认风格。支持的值可能随时间增加。值最多为 64 个字符。

  • "friendly"

  • "pragmatic"

  • previous_response_id: optional string or null

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

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

仅限 gpt-5 和 o 系列模型:推理模型的配置选项。

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

  • text: optional object { format, verbosity } or null

模型文本响应的配置选项,可为纯文本或结构化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_choice: optional BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more or null

控制模型应使用哪个工具(如果使用工具)。

  • 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: optional array of Function { name, parameters, strict, 6 more } or FileSearch { type, vector_store_ids, filters, 2 more } or Computer { type } or 13 more or null

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

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

  • truncation: optional "auto" or "disabled"

模型响应的截断策略。

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

  • "auto"

  • "disabled"

返回值

  • input_tokens: integer

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

  • "response.input_tokens"

示例

例中文字:给我讲个笑话。

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

响应示例

{
  "object": "response.input_tokens",
  "input_tokens": 11
}
以上内容是否对您有帮助:
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号