OpenAI 列出多智能体响应输入条目

2026-11-19 17:50 更新

列出输入条目

get /responses/{response_id}/input_items?beta=true

返回指定响应的输入条目列表。

请求头参数

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

  • "responses_multi_agent=v1"

路径参数

  • response_id: string

要列出输入条目的响应 ID。

查询参数

  • after: optional string

分页时从此条目 ID 之后开始列出。

  • include: optional array of BetaResponseIncludable

响应额外包含的字段,详见上方创建Response的include参数。

  • "file_search_call.results"

  • "web_search_call.results"

  • "web_search_call.action.sources"

  • "message.input_image.image_url"

  • "computer_call_output.output.image_url"

  • "code_interpreter_call.outputs"

  • "reasoning.encrypted_content"

  • "message.output_text.logprobs"

  • limit: optional integer (default: 20)

返回对象数量上限,范围为 1–100,默认为 20。

  • order: optional "asc" or "desc"

输入条目的返回顺序,默认为 desc。

  • asc:按升序返回输入条目。
  • desc:按降序返回输入条目。

  • "asc"

  • "desc"

返回值

  • BetaResponseItemList object { data, first_id, has_more, 2 more }

Response条目列表。

  • data: array of BetaResponseInputMessageItem or BetaResponseOutputMessage or FileSearchCall { id, queries, status, 3 more } or 30 more

用于生成此响应的条目列表。

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

  • id: string

消息输入的唯一ID。

  • content: BetaResponseInputMessageContentList

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

  • 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 "system" or "developer"

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

  • "user"

  • "system"

  • "developer"

  • type: "message"

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

  • "message"

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

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

  • id: string

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

  • call_id: string

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

  • output: BetaResponseComputerToolCallOutputScreenshot

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

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

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

  • "computer_screenshot"

  • file_id: optional string

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

  • image_url: optional string

截图图像的 URL。

format: uri

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

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

  • "completed"

  • "incomplete"

  • "failed"

  • "in_progress"

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

类型,固定为 computer_call_output。

  • "computer_call_output"

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

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

  • id: string

待处理安全检查的 ID。

  • code: optional string or null

待处理安全检查的类型。

  • message: optional string or null

待处理安全检查的详情。

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

  • created_by: optional string

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

  • 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 { id, arguments, call_id, 8 more }

  • id: string

函数工具调用的唯一 ID。

  • arguments: string

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

  • call_id: string

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

  • name: string

要运行的函数名称。

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

  • type: "function_call"

类型,固定为 function_call。

  • "function_call"

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

  • created_by: optional string

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

  • namespace: optional string

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

  • FunctionCallOutput object { id, output, status, 7 more }

  • id: string

函数调用工具输出的唯一 ID。

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

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

  • StringOutput = string

函数调用输出的字符串。

  • OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile

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

  • BetaResponseInputText object { text, type, prompt_cache_breakpoint }

输入模型的文本。

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

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

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

输入模型的文件。

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

  • type: "function_call_output"

类型,固定为 function_call_output。

  • "function_call_output"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

  • call_id: optional string

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

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

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

  • Direct object { type }

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

调用方类型,固定为 direct。

  • "direct"

  • Program object { caller_id, type }

  • caller_id: string

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

minLength: 1, maxLength: 64

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

调用方类型,固定为 program。

  • "program"

  • created_by: optional string

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

  • name: optional string

产生输出的工具名称。

  • namespace: optional string

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

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

  • id: string

此智能体消息的唯一 ID。

  • author: string

发送方智能体的标识。

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

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

  • BetaResponseInputText object { text, type, prompt_cache_breakpoint }

输入模型的文本。

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

模型输出的文本。

  • Text object { text, type }

文本内容。

  • text: string

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

  • "text"

  • SummaryText object { text, type }

模型生成的摘要文本。

  • text: string

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

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

类型,固定为 summary_text。

  • "summary_text"

  • ReasoningText object { text, type }

模型生成的推理文本。

  • text: string

模型生成的推理文本。

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

类型,固定为 reasoning_text。

  • "reasoning_text"

  • BetaResponseOutputRefusal object { refusal, type }

模型的拒绝响应。

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

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

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

计算机屏幕截图。

  • detail: BetaImageDetail

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

  • file_id: string or null

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

  • image_url: string or null

截图图像的 URL。

format: uri

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

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

  • "computer_screenshot"

  • prompt_cache_breakpoint: optional object { mode, ttl }

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

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

断点模式,固定为 explicit。

  • "explicit"

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

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

  • "30m"

  • "12h"

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

输入模型的文件。

  • EncryptedContent object { encrypted_content, type }

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

  • encrypted_content: string

不透明的加密内容。

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

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

  • "encrypted_content"

  • recipient: string

接收方智能体的标识。

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

条目类型,固定为 agent_message。

  • "agent_message"

  • agent: optional object { agent_name }

生成该条目的智能体。

  • agent_name: string

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

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

  • id: string

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

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

要执行的多智能体操作。

  • "spawn_agent"

  • "interrupt_agent"

  • "list_agents"

  • "send_message"

  • "followup_task"

  • "wait_agent"

  • arguments: string

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

  • call_id: string

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

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

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

  • "multi_agent_call"

  • agent: optional object { agent_name }

生成该条目的智能体。

  • agent_name: string

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

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

  • id: string

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

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

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

  • "spawn_agent"

  • "interrupt_agent"

  • "list_agents"

  • "send_message"

  • "followup_task"

  • "wait_agent"

  • call_id: string

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

  • output: array of BetaResponseOutputText

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

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

文本输出的注解。

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

  • text: string

模型输出的文本内容。

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

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

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

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

  • "multi_agent_call_output"

  • agent: optional object { agent_name }

生成该条目的智能体。

  • agent_name: string

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

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

  • id: string

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

  • arguments: unknown

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

  • call_id: string or null

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

  • execution: "server" or "client"

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

  • "server"

  • "client"

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

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

条目类型,固定为 tool_search_call。

  • "tool_search_call"

  • agent: optional object { agent_name }

生成该条目的智能体。

  • agent_name: string

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

  • created_by: optional string

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

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

  • id: string

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

  • call_id: string or null

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

  • execution: "server" or "client"

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

  • "server"

  • "client"

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

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

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

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

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

  • name: string

要调用的函数名称。

  • parameters: map[unknown] or null

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

  • strict: boolean or null

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

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

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

  • "function"

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

工具调用的上下文。

  • "direct"

  • "programmatic"

  • async: optional boolean

  • defer_loading: optional boolean

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

  • description: optional string or null

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

  • output_schema: optional map[unknown] or null

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

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

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

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

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

  • "file_search"

  • vector_store_ids: array of string

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

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

要应用的筛选条件。

  • ComparisonFilter object { key, type, value }

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

  • key: string

要与值比较的属性键。

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

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

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

  • "eq"

  • "ne"

  • "gt"

  • "gte"

  • "lt"

  • "lte"

  • "in"

  • "nin"

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

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

  • string

  • number

  • boolean

  • array of string or number

  • string

  • number

  • BetaCompoundFilter = unknown

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

  • max_num_results: optional integer

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

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

搜索结果的排序选项。

  • hybrid_search: optional object { embedding_weight, text_weight }

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

  • embedding_weight: number

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

  • text_weight: number

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

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

文件搜索所用的排序器。

  • "auto"

  • "default-2024-11-15"

  • score_threshold: optional number

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

  • Computer object { type }

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

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

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

  • "computer"

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

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

  • display_height: integer

计算机显示区域的高度。

  • display_width: integer

计算机显示区域的宽度。

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

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

  • "windows"

  • "mac"

  • "linux"

  • "ubuntu"

  • "browser"

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

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

  • "computer_use_preview"

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

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

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

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

  • "web_search"

  • "web_search_2025_08_26"

  • external_web_access: optional boolean (default: true)

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

  • filters: optional object { allowed_domains } or null

搜索的筛选条件。

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

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

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

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

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

  • "low"

  • "medium"

  • "high"

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

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

  • city: optional string or null

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

  • country: optional string or null

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

  • region: optional string or null

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

  • timezone: optional string or null

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

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

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

  • "approximate"

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

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

  • server_label: string

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

  • type: "mcp"

MCP 工具类型,固定为 mcp。

  • "mcp"

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

工具调用的上下文。

minItems: 1

  • "direct"

  • "programmatic"

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

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

  • McpAllowedTools = array of string

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

  • McpToolFilter object { read_only, tool_names }

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

  • read_only: optional boolean

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

  • tool_names: optional array of string

允许的工具名称列表。

  • authorization: optional string

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

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

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

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

当前支持的 connector_id 值如下:

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

  • "connector_dropbox"

  • "connector_gmail"

  • "connector_googlecalendar"

  • "connector_googledrive"

  • "connector_microsoftteams"

  • "connector_outlookcalendar"

  • "connector_outlookemail"

  • "connector_sharepoint"

  • defer_loading: optional boolean

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

  • headers: optional map[string] or null

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

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

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

  • McpToolApprovalFilter object { always, never }

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

  • always: optional object { read_only, tool_names }

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

  • read_only: optional boolean

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

  • tool_names: optional array of string

允许的工具名称列表。

  • never: optional object { read_only, tool_names }

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

  • read_only: optional boolean

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

  • tool_names: optional array of string

允许的工具名称列表。

  • McpToolApprovalSetting = "always" or "never"

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

  • "always"

  • "never"

  • server_description: optional string

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

  • server_url: optional string

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

format: uri

  • tunnel_id: optional string

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

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

  • CodeInterpreter object { container, type, allowed_callers }

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

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

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

  • string

容器 ID。

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

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

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

固定为 auto。

  • "auto"

  • file_ids: optional array of string

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

maxItems: 50

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

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

  • "1g"

  • "4g"

  • "16g"

  • "64g"

  • network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist

容器的网络访问策略。

  • BetaContainerNetworkPolicyDisabled object { type }

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

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

  • "disabled"

  • BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }

  • allowed_domains: array of string

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

minItems: 1

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

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

  • "allowlist"

  • domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret

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

minItems: 1

  • domain: string

密钥关联的域名。

minLength: 1

  • name: string

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

minLength: 1

  • value: string

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

minLength: 1, maxLength: 10485760

  • type: "code_interpreter"

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

  • "code_interpreter"

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

工具调用的上下文。

minItems: 1

  • "direct"

  • "programmatic"

  • ProgrammaticToolCalling object { type }

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

工具类型,固定为 programmatic_tool_calling。

  • "programmatic_tool_calling"

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

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

  • type: "image_generation"

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

  • "image_generation"

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

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

  • "generate"

  • "edit"

  • "auto"

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

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

  • "transparent"

  • "opaque"

  • "auto"

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

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

  • "low"

  • "medium"

  • "high"

  • frame_count: optional integer (default: 9)

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

minimum: 2, maximum: 16

  • frame_duration_ms: optional integer (default: 200)

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

minimum: 20, maximum: 2000

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

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

  • "high"

  • "low"

  • input_image_mask: optional object { file_id, image_url }

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

  • file_id: optional string

蒙版图像的文件 ID。

  • image_url: optional string

采用 Base64 编码的蒙版图像。

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

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

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

  • string

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

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

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

  • "gpt-image-1"

  • "gpt-image-1-mini"

  • "gpt-image-2"

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

  • "gpt-image-2.5-sunburst"

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

  • "gpt-image-2.5-flare"

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

  • "gpt-image-2.6-sunburst"

  • "gpt-image-2.6-flare"

  • "gpt-image-1.5"

  • "chatgpt-image-latest"

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

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

  • "auto"

  • "low"

  • output_compression: optional integer (default: 100)

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

minimum: 0, maximum: 100

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

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

  • "png"

  • "webp"

  • "jpeg"

  • "gif"

  • "svg"

  • partial_images: optional integer (default: 0)

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

minimum: 0, maximum: 3

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

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

  • "low"

  • "medium"

  • "high"

  • "xhigh"

  • "max"

  • "auto"

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

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

  • string

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

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

  • "1024x1024"

  • "1024x1536"

  • "1536x1024"

  • "auto"

  • svg: optional object { model, reasoning }

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

  • model: optional string

minLength: 1

  • reasoning: optional object { effort } or null

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

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

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

  • "none"

  • "minimal"

  • "low"

  • "medium"

  • "high"

  • "xhigh"

  • "max"

  • LocalShell object { type }

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

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

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

  • "local_shell"

  • Shell object { type, allowed_callers, environment }

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

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

shell 工具类型,固定为 shell。

  • "shell"

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

工具调用的上下文。

minItems: 1

  • "direct"

  • "programmatic"

  • environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference or null

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

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

为此请求自动创建容器。

  • "container_auto"

  • file_ids: optional array of string

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

maxItems: 50

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

容器的内存上限。

  • "1g"

  • "4g"

  • "16g"

  • "64g"

  • network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist

容器的网络访问策略。

  • BetaContainerNetworkPolicyDisabled object { type }

  • BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }

  • skills: optional array of BetaSkillReference or BetaInlineSkill

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

maxItems: 200

  • BetaSkillReference object { skill_id, type, version }

  • skill_id: string

引用的技能 ID。

minLength: 1, maxLength: 64

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

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

  • "skill_reference"

  • version: optional string

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

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

  • description: string

技能描述。

  • name: string

技能名称。

  • source: BetaInlineSkillSource

内联技能载荷。

  • data: string

采用 Base64 编码的技能 ZIP 包。

minLength: 1, maxLength: 70254592

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

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

  • "application/zip"

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

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

  • "base64"

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

为此请求定义内联技能。

  • "inline"

  • BetaLocalEnvironment object { type, skills }

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

使用本地计算机环境。

  • "local"

  • skills: optional array of BetaLocalSkill

可选的技能列表。

maxItems: 200

  • description: string

技能描述。

  • name: string

技能名称。

  • path: string

包含该技能的目录路径。

  • BetaContainerReference object { container_id, type }

  • container_id: string

引用的容器 ID。

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

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

  • "container_reference"

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

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

  • name: string

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

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

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

  • "custom"

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

工具调用的上下文。

minItems: 1

  • "direct"

  • "programmatic"

  • async: optional boolean

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

  • defer_loading: optional boolean

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

  • description: optional string

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

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

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

  • Text object { type }

无约束的自由文本。

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

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

  • "text"

  • Grammar object { definition, syntax, type }

用户定义的语法。

  • definition: string

语法定义。

  • syntax: "lark" or "regex"

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

  • "lark"

  • "regex"

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

语法格式,固定为 grammar。

  • "grammar"

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

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

  • description: string

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

  • name: string

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

minLength: 1

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

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

minItems: 1

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

  • name: string

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

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

  • "function"

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

工具调用的上下文。

minItems: 1

  • "direct"

  • "programmatic"

  • async: optional boolean

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

  • defer_loading: optional boolean

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

  • description: optional string or null

  • output_schema: optional map[unknown] or null

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

  • parameters: optional unknown or null

  • strict: optional boolean or null

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

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

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

  • name: string

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

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

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

  • "custom"

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

工具调用的上下文。

minItems: 1

  • "direct"

  • "programmatic"

  • async: optional boolean

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

  • defer_loading: optional boolean

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

  • description: optional string

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

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

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

  • Text object { type }

无约束的自由文本。

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

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

  • "text"

  • Grammar object { definition, syntax, type }

用户定义的语法。

  • definition: string

语法定义。

  • syntax: "lark" or "regex"

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

  • "lark"

  • "regex"

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

语法格式,固定为 grammar。

  • "grammar"

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

工具类型,固定为 namespace。

  • "namespace"

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

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

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

工具类型,固定为 tool_search。

  • "tool_search"

  • description: optional string or null

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

  • execution: optional "server" or "client"

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

  • "server"

  • "client"

  • parameters: optional unknown or null

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

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

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

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

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

  • "web_search_preview"

  • "web_search_preview_2025_03_11"

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

  • "text"

  • "image"

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

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

  • "low"

  • "medium"

  • "high"

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

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

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

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

  • "approximate"

  • city: optional string or null

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

  • country: optional string or null

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

  • region: optional string or null

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

  • timezone: optional string or null

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

  • ApplyPatch object { type, allowed_callers }

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

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

工具类型,固定为 apply_patch。

  • "apply_patch"

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

工具调用的上下文。

minItems: 1

  • "direct"

  • "programmatic"

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

条目类型,固定为 tool_search_output。

  • "tool_search_output"

  • agent: optional object { agent_name }

生成该条目的智能体。

  • agent_name: string

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

  • created_by: optional string

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

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

  • id: string

额外工具条目的唯一 ID。

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

提供额外工具的角色。

  • "unknown"

  • "user"

  • "assistant"

  • "system"

  • "critic"

  • "discriminator"

  • "developer"

  • "tool"

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

此条目中提供的额外工具定义。

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

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

  • name: string

要调用的函数名称。

  • parameters: map[unknown] or null

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

  • strict: boolean or null

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

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

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

  • "function"

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

工具调用的上下文。

  • "direct"

  • "programmatic"

  • async: optional boolean

  • defer_loading: optional boolean

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

  • description: optional string or null

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

  • output_schema: optional map[unknown] or null

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

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

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

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

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

  • "file_search"

  • vector_store_ids: array of string

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

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

要应用的筛选条件。

  • ComparisonFilter object { key, type, value }

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

  • key: string

要与值比较的属性键。

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

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

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

  • "eq"

  • "ne"

  • "gt"

  • "gte"

  • "lt"

  • "lte"

  • "in"

  • "nin"

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

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

  • string

  • number

  • boolean

  • array of string or number

  • string

  • number

  • BetaCompoundFilter = unknown

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

  • max_num_results: optional integer

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

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

搜索结果的排序选项。

  • hybrid_search: optional object { embedding_weight, text_weight }

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

  • embedding_weight: number

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

  • text_weight: number

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

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

文件搜索所用的排序器。

  • "auto"

  • "default-2024-11-15"

  • score_threshold: optional number

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

  • Computer object { type }

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

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

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

  • "computer"

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

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

  • display_height: integer

计算机显示区域的高度。

  • display_width: integer

计算机显示区域的宽度。

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

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

  • "windows"

  • "mac"

  • "linux"

  • "ubuntu"

  • "browser"

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

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

  • "computer_use_preview"

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

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

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

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

  • "web_search"

  • "web_search_2025_08_26"

  • external_web_access: optional boolean (default: true)

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

  • filters: optional object { allowed_domains } or null

搜索的筛选条件。

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

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

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

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

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

  • "low"

  • "medium"

  • "high"

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

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

  • city: optional string or null

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

  • country: optional string or null

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

  • region: optional string or null

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

  • timezone: optional string or null

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

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

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

  • "approximate"

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

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

  • server_label: string

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

  • type: "mcp"

MCP 工具类型,固定为 mcp。

  • "mcp"

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

工具调用的上下文。

minItems: 1

  • "direct"

  • "programmatic"

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

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

  • McpAllowedTools = array of string

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

  • McpToolFilter object { read_only, tool_names }

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

  • read_only: optional boolean

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

  • tool_names: optional array of string

允许的工具名称列表。

  • authorization: optional string

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

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

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

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

当前支持的 connector_id 值如下:

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

  • "connector_dropbox"

  • "connector_gmail"

  • "connector_googlecalendar"

  • "connector_googledrive"

  • "connector_microsoftteams"

  • "connector_outlookcalendar"

  • "connector_outlookemail"

  • "connector_sharepoint"

  • defer_loading: optional boolean

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

  • headers: optional map[string] or null

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

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

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

  • McpToolApprovalFilter object { always, never }

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

  • always: optional object { read_only, tool_names }

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

  • read_only: optional boolean

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

  • tool_names: optional array of string

允许的工具名称列表。

  • never: optional object { read_only, tool_names }

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

  • read_only: optional boolean

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

  • tool_names: optional array of string

允许的工具名称列表。

  • McpToolApprovalSetting = "always" or "never"

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

  • "always"

  • "never"

  • server_description: optional string

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

  • server_url: optional string

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

format: uri

  • tunnel_id: optional string

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

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

  • CodeInterpreter object { container, type, allowed_callers }

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

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

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

  • string

容器 ID。

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

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

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

固定为 auto。

  • "auto"

  • file_ids: optional array of string

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

maxItems: 50

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

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

  • "1g"

  • "4g"

  • "16g"

  • "64g"

  • network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist

容器的网络访问策略。

  • BetaContainerNetworkPolicyDisabled object { type }

  • BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }

  • type: "code_interpreter"

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

  • "code_interpreter"

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

工具调用的上下文。

minItems: 1

  • "direct"

  • "programmatic"

  • ProgrammaticToolCalling object { type }

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

工具类型,固定为 programmatic_tool_calling。

  • "programmatic_tool_calling"

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

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

  • type: "image_generation"

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

  • "image_generation"

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

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

  • "generate"

  • "edit"

  • "auto"

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

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

  • "transparent"

  • "opaque"

  • "auto"

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

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

  • "low"

  • "medium"

  • "high"

  • frame_count: optional integer (default: 9)

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

minimum: 2, maximum: 16

  • frame_duration_ms: optional integer (default: 200)

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

minimum: 20, maximum: 2000

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

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

  • "high"

  • "low"

  • input_image_mask: optional object { file_id, image_url }

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

  • file_id: optional string

蒙版图像的文件 ID。

  • image_url: optional string

采用 Base64 编码的蒙版图像。

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

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

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

  • string

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

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

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

  • "gpt-image-1"

  • "gpt-image-1-mini"

  • "gpt-image-2"

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

  • "gpt-image-2.5-sunburst"

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

  • "gpt-image-2.5-flare"

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

  • "gpt-image-2.6-sunburst"

  • "gpt-image-2.6-flare"

  • "gpt-image-1.5"

  • "chatgpt-image-latest"

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

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

  • "auto"

  • "low"

  • output_compression: optional integer (default: 100)

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

minimum: 0, maximum: 100

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

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

  • "png"

  • "webp"

  • "jpeg"

  • "gif"

  • "svg"

  • partial_images: optional integer (default: 0)

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

minimum: 0, maximum: 3

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

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

  • "low"

  • "medium"

  • "high"

  • "xhigh"

  • "max"

  • "auto"

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

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

  • string

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

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

  • "1024x1024"

  • "1024x1536"

  • "1536x1024"

  • "auto"

  • svg: optional object { model, reasoning }

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

  • model: optional string

minLength: 1

  • reasoning: optional object { effort } or null

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

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

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

  • "none"

  • "minimal"

  • "low"

  • "medium"

  • "high"

  • "xhigh"

  • "max"

  • LocalShell object { type }

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

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

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

  • "local_shell"

  • Shell object { type, allowed_callers, environment }

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

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

shell 工具类型,固定为 shell。

  • "shell"

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

工具调用的上下文。

minItems: 1

  • "direct"

  • "programmatic"

  • environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference or null

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

  • BetaLocalEnvironment object { type, skills }

  • BetaContainerReference object { container_id, type }

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

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

  • name: string

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

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

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

  • "custom"

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

工具调用的上下文。

minItems: 1

  • "direct"

  • "programmatic"

  • async: optional boolean

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

  • defer_loading: optional boolean

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

  • description: optional string

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

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

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

  • Text object { type }

无约束的自由文本。

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

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

  • "text"

  • Grammar object { definition, syntax, type }

用户定义的语法。

  • definition: string

语法定义。

  • syntax: "lark" or "regex"

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

  • "lark"

  • "regex"

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

语法格式,固定为 grammar。

  • "grammar"

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

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

  • description: string

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

  • name: string

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

minLength: 1

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

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

minItems: 1

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

  • name: string

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

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

  • "function"

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

工具调用的上下文。

minItems: 1

  • "direct"

  • "programmatic"

  • async: optional boolean

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

  • defer_loading: optional boolean

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

  • description: optional string or null

  • output_schema: optional map[unknown] or null

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

  • parameters: optional unknown or null

  • strict: optional boolean or null

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

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

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

  • name: string

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

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

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

  • "custom"

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

工具调用的上下文。

minItems: 1

  • "direct"

  • "programmatic"

  • async: optional boolean

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

  • defer_loading: optional boolean

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

  • description: optional string

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

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

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

  • Text object { type }

无约束的自由文本。

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

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

  • "text"

  • Grammar object { definition, syntax, type }

用户定义的语法。

  • definition: string

语法定义。

  • syntax: "lark" or "regex"

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

  • "lark"

  • "regex"

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

语法格式,固定为 grammar。

  • "grammar"

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

工具类型,固定为 namespace。

  • "namespace"

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

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

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

工具类型,固定为 tool_search。

  • "tool_search"

  • description: optional string or null

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

  • execution: optional "server" or "client"

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

  • "server"

  • "client"

  • parameters: optional unknown or null

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

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

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

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

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

  • "web_search_preview"

  • "web_search_preview_2025_03_11"

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

  • "text"

  • "image"

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

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

  • "low"

  • "medium"

  • "high"

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

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

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

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

  • "approximate"

  • city: optional string or null

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

  • country: optional string or null

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

  • region: optional string or null

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

  • timezone: optional string or null

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

  • ApplyPatch object { type, allowed_callers }

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

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

工具类型,固定为 apply_patch。

  • "apply_patch"

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

工具调用的上下文。

minItems: 1

  • "direct"

  • "programmatic"

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

条目类型,固定为 additional_tools。

  • "additional_tools"

  • agent: optional object { agent_name }

生成该条目的智能体。

  • agent_name: string

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

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

更新后续响应使用的配置。每项设置持续有效,直到之后另行更新。

  • id: string

配置更新条目的唯一 ID。

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

条目类型,固定为 configuration_update。

  • "configuration_update"

  • agent: optional object { agent_name }

生成该条目的智能体。

  • agent_name: string

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

  • reasoning: optional object { 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"

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

  • id: string

program 条目的唯一 ID。

  • call_id: string

program 条目的稳定调用 ID。

  • code: string

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

  • fingerprint: string

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

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

条目类型,固定为 program。

  • "program"

  • agent: optional object { agent_name }

生成该条目的智能体。

  • agent_name: string

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

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

  • id: string

程序输出条目的唯一 ID。

  • call_id: string

program 条目的调用 ID。

  • result: string

program 条目生成的结果。

  • status: "completed" or "incomplete"

程序输出条目的终态。

  • "completed"

  • "incomplete"

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

条目类型,固定为 program_output。

  • "program_output"

  • agent: optional object { agent_name }

生成该条目的智能体。

  • agent_name: string

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

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

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

  • id: string

压缩条目的唯一 ID。

  • encrypted_content: string

压缩生成的加密内容。

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

类型,固定为 compaction。

  • "compaction"

  • agent: optional object { agent_name }

生成该条目的智能体。

  • agent_name: string

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

  • created_by: optional string

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

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

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

  • id: string

图像生成调用的唯一 ID。

  • result: string or null

Base64 编码的生成图像。

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

图像生成调用的状态。

  • "in_progress"

  • "completed"

  • "generating"

  • "failed"

  • type: "image_generation_call"

类型,固定为 image_generation_call。

  • "image_generation_call"

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

用于图像生成的操作。

  • "generate"

  • "edit"

  • "auto"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

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

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

  • "transparent"

  • "opaque"

  • "auto"

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

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

  • code: string or null

错误代码。

  • message: string

错误描述。

  • param: string or null

关联的请求参数。

  • type: string

错误类型。

  • moderation_details: optional object { categories, moderation_stage }

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

  • categories: array of string

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

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

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

  • "input"

  • "output"

  • "unknown"

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

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

  • "png"

  • "webp"

  • "jpeg"

  • "gif"

  • "svg"

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

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

  • "low"

  • "medium"

  • "high"

  • "xhigh"

  • "max"

  • "auto"

  • revised_prompt: optional string or null

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

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

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

  • string

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

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

  • "1024x1024"

  • "1024x1536"

  • "1536x1024"

  • svg_usage: optional object { input_tokens, model, output_tokens, 2 more }

  • input_tokens: integer

  • model: string

  • output_tokens: integer

  • reasoning_tokens: integer

  • total_tokens: integer

  • CodeInterpreterCall object { id, code, container_id, 4 more }

运行代码的工具调用。

  • id: string

代码解释器工具调用的唯一 ID。

  • code: string or null

要运行的代码,不可用时为 null。

  • container_id: string

运行代码使用的容器 ID。

  • outputs: array of Logs { logs, type } or Image { type, url } or null

代码解释器产生的日志、图像等输出;没有可用输出时可为null。

  • Logs object { logs, type }

代码解释器的日志输出。

  • logs: string

代码解释器的日志输出。

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

类型,固定为 logs。

  • "logs"

  • Image object { type, url }

代码解释器的图像输出。

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

类型,固定为 image。

  • "image"

  • url: string

代码解释器输出图像的 URL。

format: uri

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

代码解释器工具调用的状态,有效值为 in_progress、completed、incomplete、interpreting 和 failed。

  • "in_progress"

  • "completed"

  • "incomplete"

  • "interpreting"

  • "failed"

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

类型,固定为 code_interpreter_call。

  • "code_interpreter_call"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

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

在本地 shell 上运行命令的工具调用。

  • id: string

本地 shell 调用的唯一 ID。

  • action: object { command, env, type, 3 more }

在服务器上执行 shell 命令。

  • command: array of string

要运行的命令。

  • env: map[string]

要为命令设置的环境变量。

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

类型,固定为 exec。

  • "exec"

  • timeout_ms: optional integer or null

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

  • user: optional string or null

可选的运行命令的用户。

  • working_directory: optional string or null

可选的运行命令的工作目录。

  • call_id: string

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

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

本地 shell 调用的状态。

  • "in_progress"

  • "completed"

  • "incomplete"

  • type: "local_shell_call"

类型,固定为 local_shell_call。

  • "local_shell_call"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

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

本地 shell 工具调用的输出。

  • id: string

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

  • output: string

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

  • type: "local_shell_call_output"

类型,固定为 local_shell_call_output。

  • "local_shell_call_output"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

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

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

  • id: string

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

  • action: object { commands, max_output_length, timeout_ms }

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

  • commands: array of string

  • max_output_length: integer or null

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

  • timeout_ms: integer or null

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

  • call_id: string

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

  • environment: BetaResponseLocalEnvironment or BetaResponseContainerReference or null

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

  • BetaResponseLocalEnvironment object { type }

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

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

环境类型,固定为 local。

  • "local"

  • BetaResponseContainerReference object { container_id, type }

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

  • container_id: string

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

环境类型,固定为 container_reference。

  • "container_reference"

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

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

类型,固定为 shell_call。

  • "shell_call"

  • agent: optional object { agent_name }

生成该条目的智能体。

  • agent_name: string

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

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

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

  • Direct object { type }

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

  • "direct"

  • Program object { caller_id, type }

  • caller_id: string

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

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

  • "program"

  • created_by: optional string

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

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

shell 工具调用发出的输出。

  • id: string

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

  • call_id: string

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

  • max_output_length: integer or null

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

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

shell 调用输出内容的数组。

  • outcome: Timeout { type } or Exit { exit_code, type }

表示 shell 调用输出块的退出结果(包含退出码)或超时结果。

  • Timeout object { type }

表示 shell 调用超过其配置的时间限制。

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

结果类型,固定为 timeout。

  • "timeout"

  • Exit object { exit_code, type }

表示 shell 命令已结束,并返回退出码。

  • exit_code: integer

shell 进程的退出码。

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

结果类型,固定为 exit。

  • "exit"

  • stderr: string

捕获的标准错误输出。

  • stdout: string

捕获的标准输出。

  • created_by: optional string

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

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

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

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

  • "shell_call_output"

  • agent: optional object { agent_name }

生成该条目的智能体。

  • agent_name: string

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

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

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

  • Direct object { type }

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

  • "direct"

  • Program object { caller_id, type }

  • caller_id: string

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

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

  • "program"

  • created_by: optional string

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

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

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

  • id: string

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

  • call_id: string

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

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

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

  • CreateFile object { diff, path, type }

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

  • diff: string

要应用的差异。

  • path: string

要创建的文件路径。

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

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

  • "create_file"

  • DeleteFile object { path, type }

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

  • path: string

要删除的文件路径。

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

删除指定文件。

  • "delete_file"

  • UpdateFile object { diff, path, type }

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

  • diff: string

要应用的差异。

  • path: string

要更新的文件路径。

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

使用提供的差异更新已有文件。

  • "update_file"

  • status: "in_progress" or "completed"

apply_patch 工具调用状态,可选 in_progress 或 completed。

  • "in_progress"

  • "completed"

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

类型,固定为 apply_patch_call。

  • "apply_patch_call"

  • agent: optional object { agent_name }

生成该条目的智能体。

  • agent_name: string

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

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

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

  • Direct object { type }

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

  • "direct"

  • Program object { caller_id, type }

  • caller_id: string

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

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

  • "program"

  • created_by: optional string

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

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

apply_patch 工具调用发出的输出。

  • id: string

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

  • call_id: string

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

  • status: "completed" or "failed"

apply_patch 工具调用输出的状态,可选 completed 或 failed。

  • "completed"

  • "failed"

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

类型,固定为 apply_patch_call_output。

  • "apply_patch_call_output"

  • agent: optional object { agent_name }

生成该条目的智能体。

  • agent_name: string

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

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

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

  • Direct object { type }

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

  • "direct"

  • Program object { caller_id, type }

  • caller_id: string

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

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

  • "program"

  • created_by: optional string

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

  • output: optional string or null

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

  • McpListTools object { id, server_label, tools, 3 more }

MCP 服务器可用的工具列表。

  • id: string

列表的唯一 ID。

  • server_label: string

MCP 服务器标签。

  • tools: array of object { input_schema, name, annotations, description }

服务器可用的工具。

  • input_schema: unknown

描述工具输入的 JSON Schema。

  • name: string

工具名称。

  • annotations: optional unknown or null

工具的额外注解。

  • description: optional string or null

工具描述。

  • type: "mcp_list_tools"

类型,固定为 mcp_list_tools。

  • "mcp_list_tools"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

  • error: optional string or null

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

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

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

  • id: string

批准请求的唯一 ID。

  • arguments: string

工具参数的 JSON 字符串。

  • name: string

要运行的工具名称。

  • server_label: string

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

  • type: "mcp_approval_request"

类型,固定为 mcp_approval_request。

  • "mcp_approval_request"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

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

对 MCP 批准请求的响应。

  • id: string

批准响应的唯一 ID。

  • approval_request_id: string

所回应的批准请求的 ID。

  • approve: boolean

请求是否获准。

  • type: "mcp_approval_response"

类型,固定为 mcp_approval_response。

  • "mcp_approval_response"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

  • reason: optional string or null

决定的可选理由。

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

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

  • id: string

工具调用的唯一 ID。

  • arguments: string

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

  • name: string

已运行的工具名称。

  • server_label: string

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

  • type: "mcp_call"

类型,固定为 mcp_call。

  • "mcp_call"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

  • approval_request_id: optional string or null

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

  • error: optional BetaMcpToolCallError or null

工具调用的错误,如有。

  • McpProtocolError object { code, message, type }

  • code: integer

  • message: string

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

  • "mcp_protocol_error"

  • McpToolExecutionError object { content, type }

  • content: unknown

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

  • "mcp_tool_execution_error"

  • HTTPError object { code, message, type }

  • code: integer

  • message: string

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

  • "http_error"

  • output: optional string or null

工具调用的输出。

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

工具调用状态,可选 in_progress、completed、incomplete、calling 或 failed。

  • "in_progress"

  • "completed"

  • "incomplete"

  • "calling"

  • "failed"

  • CustomToolCall object { id, call_id, input, 8 more }

  • id: string

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

  • call_id: string

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

  • input: string

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

  • name: string

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

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

  • type: "custom_tool_call"

类型,固定为 custom_tool_call。

  • "custom_tool_call"

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

  • created_by: optional string

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

  • namespace: optional string

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

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

  • id: string

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

  • call_id: string

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

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

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

  • StringOutput = string

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

  • OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile

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

  • BetaResponseInputText object { text, type, prompt_cache_breakpoint }

输入模型的文本。

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

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

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

输入模型的文件。

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

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

  • "in_progress"

  • "completed"

  • "incomplete"

  • type: "custom_tool_call_output"

类型,固定为 custom_tool_call_output。

  • "custom_tool_call_output"

  • agent: optional object { agent_name } or null

生成该条目的智能体。

  • agent_name: string

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

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

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

  • Direct object { type }

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

调用方类型,固定为 direct。

  • "direct"

  • Program object { caller_id, type }

  • caller_id: string

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

minLength: 1, maxLength: 64

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

调用方类型,固定为 program。

  • "program"

  • created_by: optional string

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

  • first_id: string

列表中第一个条目的 ID。

  • has_more: boolean

是否还有更多可用条目。

  • last_id: string

列表中最后一个条目的 ID。

  • object: "list"

返回对象的类型,须为 list。

  • "list"

示例

## 从环境变量读取 API 密钥,按需替换示例资源标识。
curl https://api.openai.com/v1/responses/resp_abc123/input_items \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

响应示例

例中文字:讲一个关于独角兽的三句话睡前故事。

{
  "object": "list",
  "data": [
    {
      "id": "msg_abc123",
      "type": "message",
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Tell me a three sentence bedtime story about a unicorn."
        }
      ]
    }
  ],
  "first_id": "msg_abc123",
  "last_id": "msg_abc123",
  "has_more": false
}
以上内容是否对您有帮助:
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号