OpenAI 创建对话条目

创建条目

post /conversations/{conversation_id}/items

在指定 ID 的对话中创建条目。

路径参数

• conversation_id: string

要添加条目的对话的 ID。

查询参数

• include: optional array of ResponseIncludable

响应中需要包含的额外字段。更多信息请参阅 列出对话条目中的 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"

请求体参数

内容类型：application/json

• items: array of EasyInputMessage or Message { content, role, status, type } or ResponseOutputMessage or 30 more

要添加到对话中的条目，每次最多添加 20 个。

maxItems: 20

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

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

• content: string or ResponseInputMessageContentList

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

• TextInput = string

输入模型的文本。

• ResponseInputMessageContentList = array of ResponseInputContent

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

• ResponseInputText object { text, type, prompt_cache_breakpoint }

输入模型的文本。

• text: string

输入模型的文本。

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

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

• "input_text"

• prompt_cache_breakpoint: optional object { mode, ttl }

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

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

断点模式，固定为 explicit。

• "explicit"

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

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

• "30m"

• "12h"

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

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

• detail: ImageDetail

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

• "low"

• "high"

• "auto"

• "original"

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

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

• "input_image"

• file_id: optional string or null

要发送给模型的文件 ID。

• image_url: optional string or null

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

format: uri

• prompt_cache_breakpoint: optional object { mode, ttl }

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

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

断点模式，固定为 explicit。

• "explicit"

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

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

• "30m"

• "12h"

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

输入模型的文件。

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

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

• "input_file"

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

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

• "auto"

• "low"

• "high"

• file_data: optional string

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

• file_id: optional string or null

要发送给模型的文件 ID。

• file_url: optional string

要发送给模型的文件 URL。

format: uri

• filename: optional string

要发送给模型的文件名。

• prompt_cache_breakpoint: optional object { mode, ttl }

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

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

断点模式，固定为 explicit。

• "explicit"

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

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

• "30m"

• "12h"

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

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

• "user"

• "assistant"

• "system"

• "developer"

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

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

• "commentary"

• "final_answer"

• type: optional "message"

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

• "message"

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

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

• content: ResponseInputMessageContentList

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

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

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

• "user"

• "system"

• "developer"

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

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

• "in_progress"

• "completed"

• "incomplete"

• type: optional "message"

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

• "message"

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

模型输出的消息。

• id: string

输出消息的唯一 ID。

• content: array of ResponseOutputText or ResponseOutputRefusal

输出消息的内容。

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

模型输出的文本。

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

文本输出的注解。

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

文件引用。

• file_id: string

文件 ID。

• filename: string

被引用文件的文件名。

• index: integer

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

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

类型，固定为 file_citation。

• "file_citation"

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

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

• end_index: integer

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

• start_index: integer

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

• title: string

网络资源标题。

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

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

• "url_citation"

• url: string

网络资源 URL。

format: uri

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

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

• container_id: string

容器文件 ID。

• end_index: integer

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

• file_id: string

文件 ID。

• filename: string

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

• start_index: integer

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

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

类型，固定为 container_file_citation。

• "container_file_citation"

• FilePath object { file_id, index, type }

文件路径。

• file_id: string

文件 ID。

• index: integer

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

• type: "file_path"

类型，固定为 file_path。

• "file_path"

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

• token: string

• bytes: array of number

• logprob: number

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

• token: string

• bytes: array of number

• logprob: number

• text: string

模型输出的文本内容。

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

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

• "output_text"

• ResponseOutputRefusal object { refusal, type }

模型的拒绝响应。

• refusal: string

模型给出的拒绝原因。

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

类型，固定为 refusal。

• "refusal"

• role: "assistant"

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

• "assistant"

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

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

• "in_progress"

• "completed"

• "incomplete"

• type: "message"

类型，固定为 message。

• "message"

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

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

• "commentary"

• "final_answer"

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

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

• id: string

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

• queries: array of string

搜索文件所用的查询。

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

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

• "in_progress"

• "searching"

• "completed"

• "incomplete"

• "failed"

• type: "file_search_call"

类型，固定为 file_search_call。

• "file_search_call"

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

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

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

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

• string

maxLength: 512

• number

• boolean

• file_id: optional string

文件的唯一 ID。

• filename: optional string

文件名。

• score: optional number

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

format: float

• text: optional string

从文件中检索出的文本。

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

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

• id: string

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

• call_id: string

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

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

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

• id: string

待处理安全检查的 ID。

• code: optional string or null

待处理安全检查的类型。

• message: optional string or null

待处理安全检查的详情。

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

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

• "in_progress"

• "completed"

• "incomplete"

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

类型，固定为 computer_call。

• "computer_call"

• action: optional ComputerAction

单击操作。

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

单击操作。

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

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

• "left"

• "right"

• "wheel"

• "back"

• "forward"

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

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

• "click"

• x: integer

单击位置的 x 坐标。

• y: integer

单击位置的 y 坐标。

• keys: optional array of string or null

单击时保持按下的按键。

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

双击操作。

• keys: array of string or null

双击时保持按下的按键。

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

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

• "double_click"

• x: integer

双击位置的 x 坐标。

• y: integer

双击位置的 y 坐标。

• Drag object { path, type, keys }

拖动操作。

• path: array of object { x, y }

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

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

• x: integer

x 坐标。

• y: integer

y 坐标。

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

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

• "drag"

• keys: optional array of string or null

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

• Keypress object { keys, type }

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

• keys: array of string

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

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

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

• "keypress"

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

鼠标移动操作。

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

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

• "move"

• x: integer

移动目标的 x 坐标。

• y: integer

移动目标的 y 坐标。

• keys: optional array of string or null

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

• Screenshot object { type }

截屏操作。

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

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

• "screenshot"

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

滚动操作。

• scroll_x: integer

水平滚动距离。

• scroll_y: integer

垂直滚动距离。

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

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

• "scroll"

• x: integer

滚动位置的 x 坐标。

• y: integer

滚动位置的 y 坐标。

• keys: optional array of string or null

滚动时保持按下的按键。

• Type object { text, type }

输入文本的操作。

• text: string

要输入的文本。

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

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

• "type"

• Wait object { type }

等待操作。

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

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

• "wait"

• actions: optional ComputerActionList

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

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

单击操作。

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

双击操作。

• Drag object { path, type, keys }

拖动操作。

• Keypress object { keys, type }

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

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

鼠标移动操作。

• Screenshot object { type }

截屏操作。

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

滚动操作。

• Type object { text, type }

输入文本的操作。

• Wait object { type }

等待操作。

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

计算机工具调用的输出。

• call_id: string

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

minLength: 1, maxLength: 64

• output: ResponseComputerToolCallOutputScreenshot

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

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

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

• "computer_screenshot"

• file_id: optional string

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

• image_url: optional string

截图图像的 URL。

format: uri

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

类型，固定为 computer_call_output。

• "computer_call_output"

• id: optional string or null

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

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

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

• id: string

待处理安全检查的 ID。

• code: optional string or null

待处理安全检查的类型。

• message: optional string or null

待处理安全检查的详情。

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

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

• "in_progress"

• "completed"

• "incomplete"

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

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

• id: string

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

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

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

• "in_progress"

• "searching"

• "completed"

• "failed"

• "incomplete"

• type: "web_search_call"

类型，固定为 web_search_call。

• "web_search_call"

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

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

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

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

• type: "search"

操作类型。

• "search"

• queries: optional array of string

搜索查询列表。

• query: optional string

搜索查询。

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

搜索所用的信息来源。

• type: "url"

来源类型，固定为 url。

• "url"

• url: string

来源 URL。

format: uri

• OpenPage object { type, url }

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

• type: "open_page"

操作类型。

• "open_page"

• url: optional string or null

模型打开的 URL。

format: uri

• FindInPage object { pattern, type, url }

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

• pattern: string

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

• type: "find_in_page"

操作类型。

• "find_in_page"

• url: optional string or null

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

format: uri

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

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

• arguments: string

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

• call_id: string

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

• name: string

要运行的函数名称。

• type: "function_call"

类型，固定为 function_call。

• "function_call"

• id: optional string

函数工具调用的唯一 ID。

• async: optional boolean

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

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

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

• Direct object { type }

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

• "direct"

• Program object { caller_id, type }

• caller_id: string

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

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

• "program"

• namespace: optional string

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

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

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

• "in_progress"

• "completed"

• "incomplete"

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

函数工具调用的输出。

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

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

• string

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

maxLength: 10485760

• array of ResponseInputTextContent or ResponseInputImageContent or ResponseInputFileContent

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

• ResponseInputTextContent object { text, type, prompt_cache_breakpoint }

输入模型的文本。

• text: string

输入模型的文本。

maxLength: 10485760

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

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

• "input_text"

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

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

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

断点模式，固定为 explicit。

• "explicit"

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

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

• "30m"

• "12h"

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

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

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

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

• "input_image"

• detail: optional ImageDetail or null

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

• file_id: optional string or null

要发送给模型的文件 ID。

• image_url: optional string or null

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

maxLength: 20971520, format: uri

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

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

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

断点模式，固定为 explicit。

• "explicit"

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

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

• "30m"

• "12h"

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

输入模型的文件。

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

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

• "input_file"

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

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

• "auto"

• "low"

• "high"

• file_data: optional string or null

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

maxLength: 73400320

• file_id: optional string or null

要发送给模型的文件 ID。

• file_url: optional string or null

要发送给模型的文件 URL。

format: uri

• filename: optional string or null

要发送给模型的文件名。

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

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

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

断点模式，固定为 explicit。

• "explicit"

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

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

• "30m"

• "12h"

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

类型，固定为 function_call_output。

• "function_call_output"

• id: optional string or null

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

• call_id: optional string or null

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

minLength: 1, maxLength: 64

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

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

• Direct object { type }

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

调用方类型，固定为 direct。

• "direct"

• Program object { caller_id, type }

• caller_id: string

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

minLength: 1, maxLength: 64

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

调用方类型，固定为 program。

• "program"

• name: optional string or null

产生输出的工具名称。

minLength: 1, maxLength: 128

• namespace: optional string or null

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

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

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

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

• "in_progress"

• "completed"

• "incomplete"

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

• arguments: unknown

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

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

条目类型，固定为 tool_search_call。

• "tool_search_call"

• id: optional string or null

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

• call_id: optional string or null

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

minLength: 1, maxLength: 64

• execution: optional "server" or "client"

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

• "server"

• "client"

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

工具搜索调用的状态。

• "in_progress"

• "completed"

• "incomplete"

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

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

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

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

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

• name: string

要调用的函数名称。

• parameters: map[unknown] or null

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

• strict: boolean or null

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

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

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

• "function"

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

工具调用的上下文。

• "direct"

• "programmatic"

• async: optional boolean

• defer_loading: optional boolean

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

• description: optional string or null

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

• output_schema: optional map[unknown] or null

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

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

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

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

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

• "file_search"

• vector_store_ids: array of string

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

• filters: optional ComparisonFilter or CompoundFilter or null

要应用的筛选条件。

• ComparisonFilter object { key, type, value }

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

• key: string

要与值比较的属性键。

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

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

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

• "eq"

• "ne"

• "gt"

• "gte"

• "lt"

• "lte"

• "in"

• "nin"

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

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

• string

• number

• boolean

• array of string or number

• string

• number

• CompoundFilter object { filters, type }

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

• filters: array of ComparisonFilter or CompoundFilter

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

• ComparisonFilter object { key, type, value }

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

• CompoundFilter object { filters, type }

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

• type: "and" or "or"

运算类型：and 或 or。

• "and"

• "or"

• max_num_results: optional integer

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

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

搜索结果的排序选项。

• hybrid_search: optional object { embedding_weight, text_weight }

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

• embedding_weight: number

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

• text_weight: number

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

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

文件搜索所用的排序器。

• "auto"

• "default-2024-11-15"

• score_threshold: optional number

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

• Computer object { type }

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

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

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

• "computer"

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

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

• display_height: integer

计算机显示区域的高度。

• display_width: integer

计算机显示区域的宽度。

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

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

• "windows"

• "mac"

• "linux"

• "ubuntu"

• "browser"

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

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

• "computer_use_preview"

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

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

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

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

• "web_search"

• "web_search_2025_08_26"

• external_web_access: optional boolean (default: true)

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

• filters: optional object { allowed_domains } or null

搜索的筛选条件。

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

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

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

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

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

• "low"

• "medium"

• "high"

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

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

• city: optional string or null

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

• country: optional string or null

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

• region: optional string or null

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

• timezone: optional string or null

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

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

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

• "approximate"

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

通过远程模型上下文协议（MCP）服务器， 向模型提供额外工具。了解 MCP。

• server_label: string

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

• type: "mcp"

MCP 工具类型，固定为 mcp。

• "mcp"

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

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

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

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

• McpAllowedTools = array of string

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

• McpToolFilter object { read_only, tool_names }

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

• read_only: optional boolean

表示工具会修改数据还是只读。如果 MCP 服务器标注了 readOnlyHint， 就会与此筛选条件匹配。

• tool_names: optional array of string

允许的工具名称列表。

• authorization: optional string

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

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

服务连接器的标识，例如 ChatGPT 中提供的连接器。须提供 server_url、connector_id 或 tunnel_id 中的一项。更多 服务连接器信息参阅此处。

对于 2026 年 9 月 1 日之后发布的模型，此字段已弃用。 使用 server_url 连接远程 MCP 服务器，或使用 tunnel_id 通过安全 MCP 隧道连接。

当前支持的 connector_id 值如下：

• Dropbox：connector_dropbox
• Gmail：connector_gmail
• Google 日历：connector_googlecalendar
• Google 云端硬盘：connector_googledrive
• Microsoft Teams：connector_microsoftteams
• Outlook 日历：connector_outlookcalendar
• Outlook 邮箱：connector_outlookemail
• SharePoint：connector_sharepoint

• "connector_dropbox"

• "connector_gmail"

• "connector_googlecalendar"

• "connector_googledrive"

• "connector_microsoftteams"

• "connector_outlookcalendar"

• "connector_outlookemail"

• "connector_sharepoint"

• defer_loading: optional boolean

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

• headers: optional map[string] or null

可选的发送给 MCP 服务器的 HTTP 请求头，用于认证 或其他用途。

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

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

• McpToolApprovalFilter object { always, never }

指定 MCP 服务器的哪些工具需要批准。可以是 always、never，或与需要批准的工具关联的 筛选对象。

• always: optional object { read_only, tool_names }

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

• read_only: optional boolean

表示工具会修改数据还是只读。如果 MCP 服务器标注了 readOnlyHint， 就会与此筛选条件匹配。

• tool_names: optional array of string

允许的工具名称列表。

• never: optional object { read_only, tool_names }

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

• read_only: optional boolean

表示工具会修改数据还是只读。如果 MCP 服务器标注了 readOnlyHint， 就会与此筛选条件匹配。

• tool_names: optional array of string

允许的工具名称列表。

• McpToolApprovalSetting = "always" or "never"

为所有工具指定统一的批准策略，可选 always 或 never。设为 always 时，所有工具均需要批准； 设为 never 时，所有工具均不需要批准。

• "always"

• "never"

• server_description: optional string

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

• server_url: optional string

MCP 服务器的 URL。须提供 server_url、connector_id 或 tunnel_id 中的一项。

format: uri

• tunnel_id: optional string

用来替代直接服务器 URL 的安全 MCP 隧道 ID。须提供 server_url、connector_id 或 tunnel_id 中的一项。

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

• CodeInterpreter object { container, type, allowed_callers }

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

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

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

• string

容器 ID。

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

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

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

固定为 auto。

• "auto"

• file_ids: optional array of string

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

maxItems: 50

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

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

• "1g"

• "4g"

• "16g"

• "64g"

• network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist

容器的网络访问策略。

• ContainerNetworkPolicyDisabled object { type }

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

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

• "disabled"

• ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }

• allowed_domains: array of string

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

minItems: 1

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

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

• "allowlist"

• domain_secrets: optional array of ContainerNetworkPolicyDomainSecret

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

minItems: 1

• domain: string

密钥关联的域名。

minLength: 1

• name: string

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

minLength: 1

• value: string

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

minLength: 1, maxLength: 10485760

• type: "code_interpreter"

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

• "code_interpreter"

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

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• ProgrammaticToolCalling object { type }

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

工具类型，固定为 programmatic_tool_calling。

• "programmatic_tool_calling"

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

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

• type: "image_generation"

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

• "image_generation"

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

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

• "generate"

• "edit"

• "auto"

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

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

• "transparent"

• "opaque"

• "auto"

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

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

• "low"

• "medium"

• "high"

• frame_count: optional integer (default: 9)

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

minimum: 2, maximum: 16

• frame_duration_ms: optional integer (default: 200)

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

minimum: 20, maximum: 2000

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

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

• "high"

• "low"

• input_image_mask: optional object { file_id, image_url }

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

• file_id: optional string

蒙版图像的文件 ID。

• image_url: optional string

采用 Base64 编码的蒙版图像。

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

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

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

• string

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

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

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

• "gpt-image-1"

• "gpt-image-1-mini"

• "gpt-image-2"

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

• "gpt-image-2.5-sunburst"

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

• "gpt-image-2.5-flare"

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

• "gpt-image-2.6-sunburst"

• "gpt-image-2.6-flare"

• "gpt-image-1.5"

• "chatgpt-image-latest"

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

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

• "auto"

• "low"

• output_compression: optional integer (default: 100)

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

minimum: 0, maximum: 100

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

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

• "png"

• "webp"

• "jpeg"

• "gif"

• "svg"

• partial_images: optional integer (default: 0)

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

minimum: 0, maximum: 3

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

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

• "low"

• "medium"

• "high"

• "xhigh"

• "max"

• "auto"

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

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

• string

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

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

• "1024x1024"

• "1024x1536"

• "1536x1024"

• "auto"

• svg: optional object { model, reasoning }

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

• model: optional string

minLength: 1

• reasoning: optional object { effort } or null

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

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

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

• "none"

• "minimal"

• "low"

• "medium"

• "high"

• "xhigh"

• "max"

• LocalShell object { type }

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

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

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

• "local_shell"

• Shell object { type, allowed_callers, environment }

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

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

shell 工具类型，固定为 shell。

• "shell"

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

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• environment: optional ContainerAuto or LocalEnvironment or ContainerReference or null

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

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

为此请求自动创建容器。

• "container_auto"

• file_ids: optional array of string

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

maxItems: 50

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

容器的内存上限。

• "1g"

• "4g"

• "16g"

• "64g"

• network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist

容器的网络访问策略。

• ContainerNetworkPolicyDisabled object { type }

• ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }

• skills: optional array of SkillReference or InlineSkill

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

maxItems: 200

• SkillReference object { skill_id, type, version }

• skill_id: string

引用的技能 ID。

minLength: 1, maxLength: 64

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

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

• "skill_reference"

• version: optional string

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

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

• description: string

技能描述。

• name: string

技能名称。

• source: InlineSkillSource

内联技能载荷。

• data: string

采用 Base64 编码的技能 ZIP 包。

minLength: 1, maxLength: 70254592

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

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

• "application/zip"

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

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

• "base64"

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

为此请求定义内联技能。

• "inline"

• LocalEnvironment object { type, skills }

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

使用本地计算机环境。

• "local"

• skills: optional array of LocalSkill

可选的技能列表。

maxItems: 200

• description: string

技能描述。

• name: string

技能名称。

• path: string

包含该技能的目录路径。

• ContainerReference object { container_id, type }

• container_id: string

引用的容器 ID。

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

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

• "container_reference"

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

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

• name: string

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

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

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

• "custom"

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

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• async: optional boolean

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

• defer_loading: optional boolean

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

• description: optional string

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

• format: optional CustomToolInputFormat

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

• Text object { type }

无约束的自由文本。

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

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

• "text"

• Grammar object { definition, syntax, type }

用户定义的语法。

• definition: string

语法定义。

• syntax: "lark" or "regex"

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

• "lark"

• "regex"

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

语法格式，固定为 grammar。

• "grammar"

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

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

• description: string

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

• name: string

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

minLength: 1

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

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

minItems: 1

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

• name: string

已加载的函数工具名称。

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

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

• "function"

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

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• async: optional boolean

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

• defer_loading: optional boolean

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

• description: optional string or null

• output_schema: optional map[unknown] or null

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

• parameters: optional unknown or null

• strict: optional boolean or null

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

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

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

• name: string

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

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

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

• "custom"

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

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• async: optional boolean

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

• defer_loading: optional boolean

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

• description: optional string

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

• format: optional CustomToolInputFormat

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

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

工具类型，固定为 namespace。

• "namespace"

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

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

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

工具类型，固定为 tool_search。

• "tool_search"

• description: optional string or null

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

• execution: optional "server" or "client"

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

• "server"

• "client"

• parameters: optional unknown or null

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

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

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

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

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

• "web_search_preview"

• "web_search_preview_2025_03_11"

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

• "text"

• "image"

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

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

• "low"

• "medium"

• "high"

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

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

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

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

• "approximate"

• city: optional string or null

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

• country: optional string or null

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

• region: optional string or null

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

• timezone: optional string or null

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

• ApplyPatch object { type, allowed_callers }

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

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

工具类型，固定为 apply_patch。

• "apply_patch"

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

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

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

条目类型，固定为 tool_search_output。

• "tool_search_output"

• id: optional string or null

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

• call_id: optional string or null

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

minLength: 1, maxLength: 64

• execution: optional "server" or "client"

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

• "server"

• "client"

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

工具搜索输出的状态。

• "in_progress"

• "completed"

• "incomplete"

• AdditionalTools object { role, tools, type, id }

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

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

• "developer"

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

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

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

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

• name: string

要调用的函数名称。

• parameters: map[unknown] or null

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

• strict: boolean or null

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

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

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

• "function"

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

工具调用的上下文。

• "direct"

• "programmatic"

• async: optional boolean

• defer_loading: optional boolean

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

• description: optional string or null

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

• output_schema: optional map[unknown] or null

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

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

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

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

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

• "file_search"

• vector_store_ids: array of string

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

• filters: optional ComparisonFilter or CompoundFilter or null

要应用的筛选条件。

• ComparisonFilter object { key, type, value }

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

• CompoundFilter object { filters, type }

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

• max_num_results: optional integer

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

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

搜索结果的排序选项。

• hybrid_search: optional object { embedding_weight, text_weight }

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

• embedding_weight: number

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

• text_weight: number

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

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

文件搜索所用的排序器。

• "auto"

• "default-2024-11-15"

• score_threshold: optional number

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

• Computer object { type }

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

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

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

• "computer"

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

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

• display_height: integer

计算机显示区域的高度。

• display_width: integer

计算机显示区域的宽度。

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

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

• "windows"

• "mac"

• "linux"

• "ubuntu"

• "browser"

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

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

• "computer_use_preview"

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

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

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

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

• "web_search"

• "web_search_2025_08_26"

• external_web_access: optional boolean (default: true)

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

• filters: optional object { allowed_domains } or null

搜索的筛选条件。

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

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

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

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

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

• "low"

• "medium"

• "high"

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

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

• city: optional string or null

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

• country: optional string or null

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

• region: optional string or null

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

• timezone: optional string or null

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

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

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

• "approximate"

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

通过远程模型上下文协议（MCP）服务器， 向模型提供额外工具。了解 MCP。

• server_label: string

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

• type: "mcp"

MCP 工具类型，固定为 mcp。

• "mcp"

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

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

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

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

• McpAllowedTools = array of string

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

• McpToolFilter object { read_only, tool_names }

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

• read_only: optional boolean

表示工具会修改数据还是只读。如果 MCP 服务器标注了 readOnlyHint， 就会与此筛选条件匹配。

• tool_names: optional array of string

允许的工具名称列表。

• authorization: optional string

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

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

服务连接器的标识，例如 ChatGPT 中提供的连接器。须提供 server_url、connector_id 或 tunnel_id 中的一项。更多 服务连接器信息参阅此处。

对于 2026 年 9 月 1 日之后发布的模型，此字段已弃用。 使用 server_url 连接远程 MCP 服务器，或使用 tunnel_id 通过安全 MCP 隧道连接。

当前支持的 connector_id 值如下：

• Dropbox：connector_dropbox
• Gmail：connector_gmail
• Google 日历：connector_googlecalendar
• Google 云端硬盘：connector_googledrive
• Microsoft Teams：connector_microsoftteams
• Outlook 日历：connector_outlookcalendar
• Outlook 邮箱：connector_outlookemail
• SharePoint：connector_sharepoint

• "connector_dropbox"

• "connector_gmail"

• "connector_googlecalendar"

• "connector_googledrive"

• "connector_microsoftteams"

• "connector_outlookcalendar"

• "connector_outlookemail"

• "connector_sharepoint"

• defer_loading: optional boolean

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

• headers: optional map[string] or null

可选的发送给 MCP 服务器的 HTTP 请求头，用于认证 或其他用途。

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

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

• McpToolApprovalFilter object { always, never }

指定 MCP 服务器的哪些工具需要批准。可以是 always、never，或与需要批准的工具关联的 筛选对象。

• always: optional object { read_only, tool_names }

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

• read_only: optional boolean

表示工具会修改数据还是只读。如果 MCP 服务器标注了 readOnlyHint， 就会与此筛选条件匹配。

• tool_names: optional array of string

允许的工具名称列表。

• never: optional object { read_only, tool_names }

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

• read_only: optional boolean

表示工具会修改数据还是只读。如果 MCP 服务器标注了 readOnlyHint， 就会与此筛选条件匹配。

• tool_names: optional array of string

允许的工具名称列表。

• McpToolApprovalSetting = "always" or "never"

为所有工具指定统一的批准策略，可选 always 或 never。设为 always 时，所有工具均需要批准； 设为 never 时，所有工具均不需要批准。

• "always"

• "never"

• server_description: optional string

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

• server_url: optional string

MCP 服务器的 URL。须提供 server_url、connector_id 或 tunnel_id 中的一项。

format: uri

• tunnel_id: optional string

用来替代直接服务器 URL 的安全 MCP 隧道 ID。须提供 server_url、connector_id 或 tunnel_id 中的一项。

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

• CodeInterpreter object { container, type, allowed_callers }

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

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

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

• string

容器 ID。

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

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

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

固定为 auto。

• "auto"

• file_ids: optional array of string

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

maxItems: 50

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

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

• "1g"

• "4g"

• "16g"

• "64g"

• network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist

容器的网络访问策略。

• ContainerNetworkPolicyDisabled object { type }

• ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }

• type: "code_interpreter"

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

• "code_interpreter"

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

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• ProgrammaticToolCalling object { type }

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

工具类型，固定为 programmatic_tool_calling。

• "programmatic_tool_calling"

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

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

• type: "image_generation"

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

• "image_generation"

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

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

• "generate"

• "edit"

• "auto"

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

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

• "transparent"

• "opaque"

• "auto"

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

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

• "low"

• "medium"

• "high"

• frame_count: optional integer (default: 9)

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

minimum: 2, maximum: 16

• frame_duration_ms: optional integer (default: 200)

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

minimum: 20, maximum: 2000

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

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

• "high"

• "low"

• input_image_mask: optional object { file_id, image_url }

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

• file_id: optional string

蒙版图像的文件 ID。

• image_url: optional string

采用 Base64 编码的蒙版图像。

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

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

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

• string

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

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

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

• "gpt-image-1"

• "gpt-image-1-mini"

• "gpt-image-2"

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

• "gpt-image-2.5-sunburst"

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

• "gpt-image-2.5-flare"

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

• "gpt-image-2.6-sunburst"

• "gpt-image-2.6-flare"

• "gpt-image-1.5"

• "chatgpt-image-latest"

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

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

• "auto"

• "low"

• output_compression: optional integer (default: 100)

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

minimum: 0, maximum: 100

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

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

• "png"

• "webp"

• "jpeg"

• "gif"

• "svg"

• partial_images: optional integer (default: 0)

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

minimum: 0, maximum: 3

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

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

• "low"

• "medium"

• "high"

• "xhigh"

• "max"

• "auto"

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

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

• string

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

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

• "1024x1024"

• "1024x1536"

• "1536x1024"

• "auto"

• svg: optional object { model, reasoning }

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

• model: optional string

minLength: 1

• reasoning: optional object { effort } or null

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

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

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

• "none"

• "minimal"

• "low"

• "medium"

• "high"

• "xhigh"

• "max"

• LocalShell object { type }

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

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

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

• "local_shell"

• Shell object { type, allowed_callers, environment }

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

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

shell 工具类型，固定为 shell。

• "shell"

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

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• environment: optional ContainerAuto or LocalEnvironment or ContainerReference or null

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

• LocalEnvironment object { type, skills }

• ContainerReference object { container_id, type }

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

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

• name: string

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

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

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

• "custom"

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

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• async: optional boolean

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

• defer_loading: optional boolean

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

• description: optional string

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

• format: optional CustomToolInputFormat

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

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

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

• description: string

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

• name: string

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

minLength: 1

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

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

minItems: 1

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

• name: string

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

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

• "function"

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

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• async: optional boolean

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

• defer_loading: optional boolean

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

• description: optional string or null

• output_schema: optional map[unknown] or null

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

• parameters: optional unknown or null

• strict: optional boolean or null

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

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

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

• name: string

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

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

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

• "custom"

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

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• async: optional boolean

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

• defer_loading: optional boolean

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

• description: optional string

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

• format: optional CustomToolInputFormat

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

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

工具类型，固定为 namespace。

• "namespace"

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

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

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

工具类型，固定为 tool_search。

• "tool_search"

• description: optional string or null

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

• execution: optional "server" or "client"

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

• "server"

• "client"

• parameters: optional unknown or null

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

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

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

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

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

• "web_search_preview"

• "web_search_preview_2025_03_11"

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

• "text"

• "image"

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

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

• "low"

• "medium"

• "high"

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

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

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

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

• "approximate"

• city: optional string or null

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

• country: optional string or null

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

• region: optional string or null

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

• timezone: optional string or null

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

• ApplyPatch object { type, allowed_callers }

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

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

工具类型，固定为 apply_patch。

• "apply_patch"

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

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

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

条目类型，固定为 additional_tools。

• "additional_tools"

• id: optional string or null

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

• ConfigurationUpdate object { type, id, reasoning, text }

对话响应配置的更新。提供 reasoning、 text 或两者。每项设置持续生效，直至后续更新替换它。

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

条目类型，固定为 configuration_update。

• "configuration_update"

• id: optional string or null

配置更新条目的唯一 ID。

• reasoning: optional object { effort }

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

• effort: optional ReasoningEffort or null (default: "medium")

后续响应使用的推理强度，直至另一次 配置更新替换它。

• "none"

• "minimal"

• "low"

• "medium"

• "high"

• "xhigh"

• "max"

• text: optional object { format }

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

• format: ResponseFormatText or ResponseFormatTextJSONSchemaConfig

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

• ResponseFormatText object { type }

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

• type: "text"

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

• "text"

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

JSON Schema 响应格式，用于生成结构化 JSON 响应。 参阅结构化输出。

• name: string

响应格式的名称，须使用 a-z、A-Z、0-9，或包含 下划线和连字符，最长为 64 个字符。

• schema: map[unknown]

以 JSON Schema 对象描述的响应格式模式。 JSON Schema 的构建方法参阅此处。

• type: "json_schema"

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

• "json_schema"

• description: optional string

响应格式的用途描述，模型据此 判断如何按该格式响应。

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

生成输出时是否启用严格模式遵循。 设为 true 时，模型始终严格遵循 schema 字段中定义的模式。strict 为 true 时仅支持 JSON Schema 的子集。更多信息请参阅结构化输出 指南。

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

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

• id: string

推理内容的唯一标识。

• summary: array of SummaryTextContent

推理摘要内容。

• text: string

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

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

类型，固定为 summary_text。

• "summary_text"

• type: "reasoning"

类型，固定为 reasoning。

• "reasoning"

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

推理文本内容。

• text: string

模型生成的推理文本。

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

类型，固定为 reasoning_text。

• "reasoning_text"

• encrypted_content: optional string or null

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

流式传输时，后续请求须使用 response.output_item.done 事件中完整的推理条目及其 encrypted_content。response.output_item.added 中的 encrypted_content 可能不完整。当 store 为 false 或使用零数据保留时，这一点尤其重要。

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

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

• "in_progress"

• "completed"

• "incomplete"

• Compaction object { encrypted_content, type, id }

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

• encrypted_content: string

压缩摘要的加密内容。

maxLength: 104857600

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

类型，固定为 compaction。

• "compaction"

• id: optional string or null

压缩条目 ID。

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

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

• id: string

图像生成调用的唯一 ID。

• result: string or null

Base64 编码的生成图像。

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

图像生成调用的状态。

• "in_progress"

• "completed"

• "generating"

• "failed"

• type: "image_generation_call"

类型，固定为 image_generation_call。

• "image_generation_call"

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

用于图像生成的操作。

• "generate"

• "edit"

• "auto"

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

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

• "transparent"

• "opaque"

• "auto"

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

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

• code: string or null

错误代码。

• message: string

错误描述。

• param: string or null

关联的请求参数。

• type: string

错误类型。

• moderation_details: optional object { categories, moderation_stage }

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

• categories: array of string

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

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

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

• "input"

• "output"

• "unknown"

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

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

• "png"

• "webp"

• "jpeg"

• "gif"

• "svg"

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

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

• "low"

• "medium"

• "high"

• "xhigh"

• "max"

• "auto"

• revised_prompt: optional string or null

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

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

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

• string

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

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

• "1024x1024"

• "1024x1536"

• "1536x1024"

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

• input_tokens: integer

• model: string

• output_tokens: integer

• reasoning_tokens: integer

• total_tokens: integer

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

运行代码的工具调用。

• id: string

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

• code: string or null

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

• container_id: string

运行代码使用的容器 ID。

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

代码解释器生成的输出，例如日志或图像。 没有可用输出时，可以为 null。

• Logs object { logs, type }

代码解释器的日志输出。

• logs: string

代码解释器的日志输出。

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

类型，固定为 logs。

• "logs"

• Image object { type, url }

代码解释器的图像输出。

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

类型，固定为 image。

• "image"

• url: string

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

format: uri

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

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

• "in_progress"

• "completed"

• "incomplete"

• "interpreting"

• "failed"

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

类型，固定为 code_interpreter_call。

• "code_interpreter_call"

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

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

• id: string

本地 shell 调用的唯一 ID。

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

在服务器上执行 shell 命令。

• command: array of string

要运行的命令。

• env: map[string]

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

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

类型，固定为 exec。

• "exec"

• timeout_ms: optional integer or null

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

• user: optional string or null

可选的运行命令的用户。

• working_directory: optional string or null

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

• call_id: string

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

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

本地 shell 调用的状态。

• "in_progress"

• "completed"

• "incomplete"

• type: "local_shell_call"

类型，固定为 local_shell_call。

• "local_shell_call"

• LocalShellCallOutput object { id, output, type, status }

本地 shell 工具调用的输出。

• id: string

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

• output: string

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

• type: "local_shell_call_output"

类型，固定为 local_shell_call_output。

• "local_shell_call_output"

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

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

• "in_progress"

• "completed"

• "incomplete"

• ShellCall object { action, call_id, type, 4 more }

表示请求执行一个或多个 shell 命令的工具。

• action: object { commands, max_output_length, timeout_ms }

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

• commands: array of string

按顺序交给执行环境运行的 shell 命令。

• max_output_length: optional integer or null

从合并的 stdout 和 stderr 输出中最多捕获的 UTF-8 字符数。

• timeout_ms: optional integer or null

允许 shell 命令运行的最大实际时长，单位为毫秒。

• call_id: string

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

minLength: 1, maxLength: 64

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

类型，固定为 shell_call。

• "shell_call"

• id: optional string or null

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

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

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

• Direct object { type }

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

调用方类型，固定为 direct。

• "direct"

• Program object { caller_id, type }

• caller_id: string

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

minLength: 1, maxLength: 64

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

调用方类型，固定为 program。

• "program"

• environment: optional LocalEnvironment or ContainerReference or null

执行 shell 命令的环境。

• LocalEnvironment object { type, skills }

• ContainerReference object { container_id, type }

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

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

• "in_progress"

• "completed"

• "incomplete"

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

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

• call_id: string

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

minLength: 1, maxLength: 64

• output: array of ResponseFunctionShellCallOutputContent

捕获的 stdout 和 stderr 输出块，以及关联的执行结果。

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

此 shell 调用关联的退出或超时结果。

• Timeout object { type }

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

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

结果类型，固定为 timeout。

• "timeout"

• Exit object { exit_code, type }

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

• exit_code: integer

shell 进程返回的退出码。

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

结果类型，固定为 exit。

• "exit"

• stderr: string

捕获的 shell 调用的 stderr 输出。

maxLength: 10485760

• stdout: string

捕获的 shell 调用的 stdout 输出。

maxLength: 10485760

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

类型，固定为 shell_call_output。

• "shell_call_output"

• id: optional string or null

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

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

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

• Direct object { type }

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

调用方类型，固定为 direct。

• "direct"

• Program object { caller_id, type }

• caller_id: string

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

minLength: 1, maxLength: 64

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

调用方类型，固定为 program。

• "program"

• max_output_length: optional integer or null

此 shell 调用合并输出中捕获的最大 UTF-8 字符数。

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

shell 调用输出的状态。

• "in_progress"

• "completed"

• "incomplete"

• ApplyPatchCall object { call_id, operation, status, 3 more }

表示请求使用差异补丁创建、删除或更新文件的工具调用。

• call_id: string

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

minLength: 1, maxLength: 64

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

apply_patch 工具调用具体的创建、删除或更新指令。

• CreateFile object { diff, path, type }

通过 apply_patch 工具创建新文件的指令。

• diff: string

创建文件时应用的统一差异内容。

maxLength: 10485760

• path: string

相对于工作区根目录的待创建文件路径。

minLength: 1

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

操作类型，固定为 create_file。

• "create_file"

• DeleteFile object { path, type }

通过 apply_patch 工具删除已有文件的指令。

• path: string

相对于工作区根目录的待删除文件路径。

minLength: 1

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

操作类型，固定为 delete_file。

• "delete_file"

• UpdateFile object { diff, path, type }

通过 apply_patch 工具更新已有文件的指令。

• diff: string

应用于已有文件的统一差异内容。

maxLength: 10485760

• path: string

相对于工作区根目录的待更新文件路径。

minLength: 1

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

操作类型，固定为 update_file。

• "update_file"

• status: "in_progress" or "completed"

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

• "in_progress"

• "completed"

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

类型，固定为 apply_patch_call。

• "apply_patch_call"

• id: optional string or null

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

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

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

• Direct object { type }

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

调用方类型，固定为 direct。

• "direct"

• Program object { caller_id, type }

• caller_id: string

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

minLength: 1, maxLength: 64

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

调用方类型，固定为 program。

• "program"

• ApplyPatchCallOutput object { call_id, status, type, 3 more }

apply_patch 工具调用发出的流式输出。

• call_id: string

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

minLength: 1, maxLength: 64

• status: "completed" or "failed"

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

• "completed"

• "failed"

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

类型，固定为 apply_patch_call_output。

• "apply_patch_call_output"

• id: optional string or null

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

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

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

• Direct object { type }

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

调用方类型，固定为 direct。

• "direct"

• Program object { caller_id, type }

• caller_id: string

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

minLength: 1, maxLength: 64

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

调用方类型，固定为 program。

• "program"

• output: optional string or null

apply_patch 工具可选的可读日志文本，例如补丁结果或错误。

maxLength: 10485760

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

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

• id: string

列表的唯一 ID。

• server_label: string

MCP 服务器标签。

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

服务器可用的工具。

• input_schema: unknown

描述工具输入的 JSON Schema。

• name: string

工具名称。

• annotations: optional unknown or null

工具的额外注解。

• description: optional string or null

工具描述。

• type: "mcp_list_tools"

类型，固定为 mcp_list_tools。

• "mcp_list_tools"

• error: optional string or null

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

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

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

• id: string

批准请求的唯一 ID。

• arguments: string

工具参数的 JSON 字符串。

• name: string

要运行的工具名称。

• server_label: string

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

• type: "mcp_approval_request"

类型，固定为 mcp_approval_request。

• "mcp_approval_request"

• McpApprovalResponse object { approval_request_id, approve, type, 2 more }

对 MCP 批准请求的响应。

• approval_request_id: string

所回应的批准请求的 ID。

• approve: boolean

请求是否获准。

• type: "mcp_approval_response"

类型，固定为 mcp_approval_response。

• "mcp_approval_response"

• id: optional string or null

批准响应的唯一 ID。

• reason: optional string or null

决定的可选理由。

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

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

• id: string

工具调用的唯一 ID。

• arguments: string

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

• name: string

已运行的工具名称。

• server_label: string

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

• type: "mcp_call"

类型，固定为 mcp_call。

• "mcp_call"

• approval_request_id: optional string or null

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

• error: optional McpToolCallError or null

工具调用的错误，如有。

• McpProtocolError object { code, message, type }

• code: integer

• message: string

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

• "mcp_protocol_error"

• McpToolExecutionError object { content, type }

• content: unknown

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

• "mcp_tool_execution_error"

• HTTPError object { code, message, type }

• code: integer

• message: string

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

• "http_error"

• output: optional string or null

工具调用的输出。

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

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

• "in_progress"

• "completed"

• "incomplete"

• "calling"

• "failed"

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

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

• call_id: string

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

• output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile

自有代码生成的自定义工具调用输出。 可以是字符串或输出内容列表。

• StringOutput = string

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

• OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile

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

• ResponseInputText object { text, type, prompt_cache_breakpoint }

输入模型的文本。

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

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

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

输入模型的文件。

• type: "custom_tool_call_output"

类型，固定为 custom_tool_call_output。

• "custom_tool_call_output"

• id: optional string

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

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

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

• Direct object { type }

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

调用方类型，固定为 direct。

• "direct"

• Program object { caller_id, type }

• caller_id: string

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

minLength: 1, maxLength: 64

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

调用方类型，固定为 program。

• "program"

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

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

• call_id: string

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

• input: string

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

• name: string

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

• type: "custom_tool_call"

类型，固定为 custom_tool_call。

• "custom_tool_call"

• id: optional string

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

• async: optional boolean

自定义工具调用是否异步运行。

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

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

• Direct object { type }

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

• "direct"

• Program object { caller_id, type }

• caller_id: string

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

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

• "program"

• namespace: optional string

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

• CompactionTrigger object { type, id }

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

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

类型，固定为 compaction_trigger。

• "compaction_trigger"

• id: optional string or null

此压缩触发器的唯一 ID。

• ItemReference object { id, type }

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

• id: string

要引用的条目的 ID。

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

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

• "item_reference"

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

• id: string

此 program 条目的唯一 ID。

• call_id: string

program 条目的稳定调用 ID。

minLength: 1, maxLength: 64

• code: string

程序化工具调用所执行的 JavaScript 源代码。

maxLength: 10485760

• fingerprint: string

不透明的程序重放指纹，须在后续请求中原样回传。

maxLength: 10485760

• type: "program" (default: "program")

条目类型，固定为 program。

• "program"

• ProgramOutput object { id, call_id, result, 2 more }

• id: string

此程序输出条目的唯一 ID。

• call_id: string

program 条目的调用 ID。

minLength: 1, maxLength: 64

• result: string

program 条目生成的结果。

maxLength: 10485760

• status: "completed" or "incomplete"

程序输出的终态。

• "completed"

• "incomplete"

• type: "program_output" (default: "program_output")

条目类型，固定为 program_output。

• "program_output"

返回值

• ConversationItemList object { data, first_id, has_more, 2 more }

对话条目列表。

• data: array of ConversationItem

对话条目列表。

• Message object { id, content, role, 3 more }

发往模型或由模型发出的消息。

• id: string

消息的唯一 ID。

• content: array of ResponseInputText or ResponseOutputText or TextContent or 6 more

消息内容。

• ResponseInputText object { text, type, prompt_cache_breakpoint }

输入模型的文本。

• text: string

输入模型的文本。

• type: "input_text" (default: "input_text")

输入条目类型，固定为 input_text。

• "input_text"

• prompt_cache_breakpoint: optional object { mode, ttl }

标记可复用提示词前缀的精确结束位置。省略 ttl 时，断点继承请求中的 prompt_cache_options.ttl；该边界不会按词元块取整。

• mode: "explicit" (default: "explicit")

断点模式，固定为 explicit。

• "explicit"

• ttl: optional "30m" or "12h"

此缓存断点的最短存续时间，默认为请求的 TTL。

• "30m"

• "12h"

• ResponseOutputText object { annotations, logprobs, text, type }

模型输出的文本。

• annotations: array of FileCitation { file_id, filename, index, type } or URLCitation { end_index, start_index, title, 2 more } or ContainerFileCitation { container_id, end_index, file_id, 3 more } or FilePath { file_id, index, type }

文本输出的注解。

• FileCitation object { file_id, filename, index, type }

文件引用。

• file_id: string

文件 ID。

• filename: string

被引用文件的文件名。

• index: integer

在输出文本中插入文件引用的位置索引。

• type: "file_citation" (default: "file_citation")

类型，固定为 file_citation。

• "file_citation"

• URLCitation object { end_index, start_index, title, 2 more }

对生成模型响应所用网页资源的引用。

• end_index: integer

URL 引用在消息中最后一个字符的索引。

• start_index: integer

URL 引用在消息中第一个字符的索引。

• title: string

网络资源标题。

• type: "url_citation" (default: "url_citation")

URL 引用的类型，固定为 url_citation。

• "url_citation"

• url: string

网络资源 URL。

format: uri

• ContainerFileCitation object { container_id, end_index, file_id, 3 more }

对生成模型响应所用容器文件的引用。

• container_id: string

容器文件 ID。

• end_index: integer

消息中容器文件引用最后一个字符的索引。

• file_id: string

文件 ID。

• filename: string

被引用容器文件的文件名。

• start_index: integer

消息中容器文件引用第一个字符的索引。

• type: "container_file_citation" (default: "container_file_citation")

类型，固定为 container_file_citation。

• "container_file_citation"

• FilePath object { file_id, index, type }

文件路径。

• file_id: string

文件 ID。

• index: integer

文件在文件列表中的索引。

• type: "file_path"

类型，固定为 file_path。

• "file_path"

• logprobs: array of object { token, bytes, logprob, top_logprobs }

• token: string

• bytes: array of number

• logprob: number

• top_logprobs: array of object { token, bytes, logprob }

• token: string

• bytes: array of number

• logprob: number

• text: string

模型输出的文本内容。

• type: "output_text" (default: "output_text")

输出文本类型，固定为 output_text。

• "output_text"

• TextContent object { text, type }

文本内容。

• text: string

• type: "text" (default: "text")

• "text"

• SummaryTextContent 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"

• ResponseOutputRefusal object { refusal, type }

模型的拒绝响应。

• refusal: string

模型给出的拒绝原因。

• type: "refusal" (default: "refusal")

类型，固定为 refusal。

• "refusal"

• ResponseInputImage object { detail, type, file_id, 2 more }

输入模型的图像。参阅图像输入。

• detail: ImageDetail

发送给模型的图像细节级别，可选 high、low、auto 或 original，默认为 auto。

• "low"

• "high"

• "auto"

• "original"

• type: "input_image" (default: "input_image")

输入条目类型，固定为 input_image。

• "input_image"

• file_id: optional string or null

要发送给模型的文件 ID。

• image_url: optional string or null

要发送给模型的图像 URL，可以是完整 URL，或包含 Base64 编码图像的 data URL。

format: uri

• prompt_cache_breakpoint: optional object { mode, ttl }

标记可复用提示词前缀的精确结束位置。省略 ttl 时，断点继承请求中的 prompt_cache_options.ttl；该边界不会按词元块取整。

• mode: "explicit" (default: "explicit")

断点模式，固定为 explicit。

• "explicit"

• ttl: optional "30m" or "12h"

此缓存断点的最短存续时间，默认为请求的 TTL。

• "30m"

• "12h"

• ComputerScreenshotContent object { detail, file_id, image_url, 2 more }

计算机屏幕截图。

• detail: ImageDetail

发送给模型的截图图像的细节级别，可选 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"

• ResponseInputFile object { type, detail, file_data, 4 more }

输入模型的文件。

• type: "input_file" (default: "input_file")

输入条目类型，固定为 input_file。

• "input_file"

• detail: optional "auto" or "low" or "high"

发送给模型的文件细节级别。使用 auto 由系统选择；对于 GPT-5.6 及后续模型，auto 使用高质量渲染，可能增加输入词元用量。使用 low 进行成本较低的渲染，或使用 high 以更高质量渲染文件。默认为 auto。

• "auto"

• "low"

• "high"

• file_data: optional string

要发送给模型的文件内容。

• file_id: optional string or null

要发送给模型的文件 ID。

• file_url: optional string

要发送给模型的文件 URL。

format: uri

• filename: optional string

要发送给模型的文件名。

• prompt_cache_breakpoint: optional object { mode, ttl }

标记可复用提示词前缀的精确结束位置。省略 ttl 时，断点继承请求中的 prompt_cache_options.ttl；该边界不会按词元块取整。

• mode: "explicit" (default: "explicit")

断点模式，固定为 explicit。

• "explicit"

• ttl: optional "30m" or "12h"

此缓存断点的最短存续时间，默认为请求的 TTL。

• "30m"

• "12h"

• role: "unknown" or "user" or "assistant" or 5 more

消息角色，可选 unknown、user、assistant、system、critic、discriminator、developer 或 tool。

• "unknown"

• "user"

• "assistant"

• "system"

• "critic"

• "discriminator"

• "developer"

• "tool"

• status: "in_progress" or "completed" or "incomplete"

条目状态，可选 in_progress、completed 或 incomplete，通过 API 返回条目时填充。

• "in_progress"

• "completed"

• "incomplete"

• type: "message" (default: "message")

消息类型，固定为 message。

• "message"

• phase: optional "commentary" or "final_answer" or null

将 assistant 消息标记为中间说明（commentary）或最终答案（final_answer）。对于 gpt-5.3-codex 及后续此类模型，发送后续请求时须保留并重新发送所有助手消息的 phase，丢弃它可能降低表现。用户消息不使用此字段。

• "commentary"

• "final_answer"

• FunctionCall object { id, arguments, call_id, 7 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"

• 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, 6 more }

• id: string

函数调用工具输出的唯一 ID。

• output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile

自有代码生成的函数调用输出。 可以是字符串或输出内容列表。

• StringOutput = string

函数调用输出的字符串。

• OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile

函数调用的文本、图像或文件输出。

• ResponseInputText object { text, type, prompt_cache_breakpoint }

输入模型的文本。

• ResponseInputImage object { detail, type, file_id, 2 more }

输入模型的图像。参阅图像输入。

• ResponseInputFile object { type, detail, file_data, 4 more }

输入模型的文件。

• 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"

• 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

产生输出的工具所属命名空间。

• FileSearchCall object { id, queries, status, 2 more }

文件搜索工具调用的结果，更多信息参阅 文件搜索指南。

• id: string

文件搜索工具调用的唯一 ID。

• queries: array of string

搜索文件所用的查询。

• status: "in_progress" or "searching" or "completed" or 2 more

文件搜索工具调用状态，可选 in_progress、 searching、incomplete 或 failed，

• "in_progress"

• "searching"

• "completed"

• "incomplete"

• "failed"

• type: "file_search_call"

类型，固定为 file_search_call。

• "file_search_call"

• results: optional array of object { attributes, file_id, filename, 2 more } or null

文件搜索工具调用的结果。

• attributes: optional map[string or number or boolean] or null

可附加到对象的元数据，最多包含 16 组键值对，可 以结构化方式存储对象的额外信息， 格式存储附加信息，并通过 API 或控制台查询对象。键为 最长 64 个字符的字符串；值可以是最长 512 个字符的字符串、布尔值或数字。

• string

maxLength: 512

• number

• boolean

• file_id: optional string

文件的唯一 ID。

• filename: optional string

文件名。

• score: optional number

文件相关性分数，范围为 0–1。

format: float

• text: optional string

从文件中检索出的文本。

• WebSearchCall object { id, status, type, action }

网页搜索工具调用的结果，更多信息参阅 网页搜索指南。

• id: string

网页搜索工具调用的唯一 ID。

• status: "in_progress" or "searching" or "completed" or 2 more

网页搜索工具调用的状态。

• "in_progress"

• "searching"

• "completed"

• "failed"

• "incomplete"

• type: "web_search_call"

类型，固定为 web_search_call。

• "web_search_call"

• action: optional Search { type, queries, query, sources } or OpenPage { type, url } or FindInPage { pattern, type, url }

描述此网页搜索调用所执行具体操作的对象。 包含模型如何使用网页的详情：search、open_page、find_in_page。

• Search object { type, queries, query, sources }

操作类型 "search"：执行网页搜索查询。

• type: "search"

操作类型。

• "search"

• queries: optional array of string

搜索查询列表。

• query: optional string

搜索查询。

• sources: optional array of object { type, url }

搜索所用的信息来源。

• type: "url"

来源类型，固定为 url。

• "url"

• url: string

来源 URL。

format: uri

• OpenPage object { type, url }

操作类型 "open_page"：打开搜索结果中的指定 URL。

• type: "open_page"

操作类型。

• "open_page"

• url: optional string or null

模型打开的 URL。

format: uri

• FindInPage object { pattern, type, url }

操作类型 "find_in_page"：在已加载页面中搜索模式。

• pattern: string

要在页面中搜索的模式或文本。

• type: "find_in_page"

操作类型。

• "find_in_page"

• url: optional string or null

用于搜索模式的页面 URL，如可用。

format: uri

• ImageGenerationCall object { id, result, status, 9 more }

模型发起的图像生成请求。

• id: string

图像生成调用的唯一 ID。

• result: string or null

Base64 编码的生成图像。

• status: "in_progress" or "completed" or "generating" or "failed"

图像生成调用的状态。

• "in_progress"

• "completed"

• "generating"

• "failed"

• type: "image_generation_call"

类型，固定为 image_generation_call。

• "image_generation_call"

• action: optional "generate" or "edit" or "auto" or null

用于图像生成的操作。

• "generate"

• "edit"

• "auto"

• background: optional "transparent" or "opaque" or "auto" or null

生成图像使用的背景设置。

• "transparent"

• "opaque"

• "auto"

• error: optional object { code, message, param, 2 more }

审核失败的详情，如可用。

• code: string or null

错误代码。

• message: string

错误描述。

• param: string or null

关联的请求参数。

• type: string

错误类型。

• moderation_details: optional object { categories, moderation_stage }

moderation_blocked 错误的公开详情，如可用。

• categories: array of string

公开的审核类别，未来可能增加新的类别值。

• moderation_stage: "input" or "output" or "unknown"

审核阻止图像生成调用的阶段。

• "input"

• "output"

• "unknown"

• output_format: optional "png" or "webp" or "jpeg" or 2 more or null

生成图像使用的输出格式。

• "png"

• "webp"

• "jpeg"

• "gif"

• "svg"

• quality: optional "low" or "medium" or "high" or 3 more or null

图像生成工具调用生成的图像质量，可选 low、medium、high、xhigh、max 或 auto。

• "low"

• "medium"

• "high"

• "xhigh"

• "max"

• "auto"

• revised_prompt: optional string or null

模型改写提示词后实际使用的提示词。

• size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or null

图像尺寸，采用 WIDTHxHEIGHT 字符串形式，例如 1536x864。

• string

• "1024x1024" or "1024x1536" or "1536x1024"

图像尺寸，采用 WIDTHxHEIGHT 字符串形式，例如 1536x864。

• "1024x1024"

• "1024x1536"

• "1536x1024"

• svg_usage: optional object { input_tokens, model, output_tokens, 2 more }

• input_tokens: integer

• model: string

• output_tokens: integer

• reasoning_tokens: integer

• total_tokens: integer

• ComputerCall object { id, call_id, pending_safety_checks, 4 more }

计算机使用工具的调用，更多信息参阅 计算机使用指南。

• id: string

计算机工具调用的唯一 ID。

• call_id: string

通过输出回应此工具调用时使用的标识。

• pending_safety_checks: array of object { id, code, message }

此计算机工具调用待处理的安全检查。

• id: string

待处理安全检查的 ID。

• code: optional string or null

待处理安全检查的类型。

• message: optional string or null

待处理安全检查的详情。

• status: "in_progress" or "completed" or "incomplete"

条目状态，可选 in_progress、completed 或 incomplete。通过 API 返回条目时填充。

• "in_progress"

• "completed"

• "incomplete"

• type: "computer_call" (default: "computer_call")

类型，固定为 computer_call。

• "computer_call"

• action: optional ComputerAction

单击操作。

• Click object { button, type, x, 2 more }

单击操作。

• button: "left" or "right" or "wheel" or 2 more

单击时按下的鼠标按钮，可选 left、right、wheel、back 或 forward。

• "left"

• "right"

• "wheel"

• "back"

• "forward"

• type: "click" (default: "click")

指定事件类型。单击操作固定为 click。

• "click"

• x: integer

单击位置的 x 坐标。

• y: integer

单击位置的 y 坐标。

• keys: optional array of string or null

单击时保持按下的按键。

• DoubleClick object { keys, type, x, y }

双击操作。

• keys: array of string or null

双击时保持按下的按键。

• type: "double_click" (default: "double_click")

指定事件类型。双击操作固定为 double_click。

• "double_click"

• x: integer

双击位置的 x 坐标。

• y: integer

双击位置的 y 坐标。

• Drag object { path, type, keys }

拖动操作。

• path: array of object { x, y }

表示拖动路径的坐标数组。坐标以对象数组形式提供，例如

            // 拖动路径按顺序列出各点的 x、y 坐标。
            [
              { x: 100, y: 200 },
              { x: 200, y: 300 }
            ]

• x: integer

x 坐标。

• y: integer

y 坐标。

• type: "drag" (default: "drag")

指定事件类型。拖动操作固定为 drag。

• "drag"

• keys: optional array of string or null

拖动鼠标时保持按下的按键。

• Keypress object { keys, type }

模型希望执行的一组按键操作。

• keys: array of string

模型请求按下的按键组合，以字符串数组表示，每个字符串代表一个按键。

• type: "keypress" (default: "keypress")

指定事件类型。按键操作固定为 keypress。

• "keypress"

• Move object { type, x, y, keys }

鼠标移动操作。

• type: "move" (default: "move")

指定事件类型。移动操作固定为 move。

• "move"

• x: integer

移动目标的 x 坐标。

• y: integer

移动目标的 y 坐标。

• keys: optional array of string or null

移动鼠标时保持按下的按键。

• Screenshot object { type }

截屏操作。

• type: "screenshot" (default: "screenshot")

指定事件类型。截屏操作固定为 screenshot。

• "screenshot"

• Scroll object { scroll_x, scroll_y, type, 3 more }

滚动操作。

• scroll_x: integer

水平滚动距离。

• scroll_y: integer

垂直滚动距离。

• type: "scroll" (default: "scroll")

指定事件类型。滚动操作固定为 scroll。

• "scroll"

• x: integer

滚动位置的 x 坐标。

• y: integer

滚动位置的 y 坐标。

• keys: optional array of string or null

滚动时保持按下的按键。

• Type object { text, type }

输入文本的操作。

• text: string

要输入的文本。

• type: "type" (default: "type")

指定事件类型。输入操作固定为 type。

• "type"

• Wait object { type }

等待操作。

• type: "wait" (default: "wait")

指定事件类型。等待操作固定为 wait。

• "wait"

• actions: optional ComputerActionList

computer_use 的扁平化批量操作。每项操作包含 type 判别字段及对应操作专用字段。

• Click object { button, type, x, 2 more }

单击操作。

• DoubleClick object { keys, type, x, y }

双击操作。

• Drag object { path, type, keys }

拖动操作。

• Keypress object { keys, type }

模型希望执行的一组按键操作。

• Move object { type, x, y, keys }

鼠标移动操作。

• Screenshot object { type }

截屏操作。

• Scroll object { scroll_x, scroll_y, type, 3 more }

滚动操作。

• Type object { text, type }

输入文本的操作。

• Wait object { type }

等待操作。

• ComputerCallOutput object { id, call_id, output, 4 more }

• id: string

计算机工具调用输出的 ID。

• call_id: string

产生此输出的计算机工具调用的 ID。

• output: ResponseComputerToolCallOutputScreenshot

供计算机使用工具使用的屏幕截图图像。

• 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

待处理安全检查的详情。

• created_by: optional string

创建该条目的执行主体的标识。

• ToolSearchCall object { id, arguments, call_id, 4 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"

• created_by: optional string

创建该条目的执行主体的标识。

• ToolSearchOutput object { id, call_id, execution, 4 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 or CompoundFilter or null

要应用的筛选条件。

• ComparisonFilter object { key, type, value }

使用指定比较运算，将某个属性键与给定值比较的筛选条件。

• key: string

要与值比较的属性键。

• type: "eq" or "ne" or "gt" or 5 more (default: "eq")

指定比较运算符：eq、ne、gt、gte、lt、lte、in、nin。

• eq：等于
• ne：不等于
• gt：大于
• gte：大于或等于
• lt：小于
• lte：小于或等于
• in：属于
• nin：不属于

• "eq"

• "ne"

• "gt"

• "gte"

• "lt"

• "lte"

• "in"

• "nin"

• value: string or number or boolean or array of string or number

用于与属性键比较的值，支持字符串、数字或布尔类型。

• string

• number

• boolean

• array of string or number

• string

• number

• CompoundFilter object { filters, type }

使用 and 或 or 组合多个筛选条件。

• filters: array of ComparisonFilter or CompoundFilter

要组合的筛选条件数组，条目可以是 ComparisonFilter 或 CompoundFilter。

• ComparisonFilter object { key, type, value }

使用指定比较运算，将某个属性键与给定值比较的筛选条件。

• CompoundFilter object { filters, type }

使用 and 或 or 组合多个筛选条件。

• type: "and" or "or"

运算类型：and 或 or。

• "and"

• "or"

• max_num_results: optional integer

返回结果数量上限，须介于 1–50 之间，含边界。

• ranking_options: optional object { hybrid_search, ranker, score_threshold }

搜索结果的排序选项。

• hybrid_search: optional object { embedding_weight, text_weight }

启用混合搜索时，控制倒数排名融合如何平衡语义嵌入匹配与稀疏关键词匹配的权重。

• embedding_weight: number

嵌入在倒数排名融合中的权重。

• text_weight: number

文本在倒数排名融合中的权重。

• ranker: optional "auto" or "default-2024-11-15"

文件搜索所用的排序器。

• "auto"

• "default-2024-11-15"

• score_threshold: optional number

文件搜索的分数阈值，为 0–1 之间的数字。越接近 1，越倾向于只返回最相关的结果，但返回数量可能减少。

• Computer object { type }

控制虚拟计算机的工具。参阅计算机工具。

• type: "computer" (default: "computer")

计算机工具类型，固定为 computer。

• "computer"

• ComputerUsePreview object { display_height, display_width, environment, type }

控制虚拟计算机的工具。参阅计算机工具。

• display_height: integer

计算机显示区域的高度。

• display_width: integer

计算机显示区域的宽度。

• environment: "windows" or "mac" or "linux" or 2 more

要控制的计算机环境类型。

• "windows"

• "mac"

• "linux"

• "ubuntu"

• "browser"

• type: "computer_use_preview" (default: "computer_use_preview")

计算机使用工具类型，固定为 computer_use_preview。

• "computer_use_preview"

• WebSearch object { type, external_web_access, filters, 2 more }

在互联网上搜索与提示词相关的信息来源。参阅 网络搜索工具时。

• type: "web_search" or "web_search_2025_08_26" (default: "web_search")

网页搜索工具类型，可选 web_search 或 web_search_2025_08_26。

• "web_search"

• "web_search_2025_08_26"

• external_web_access: optional boolean (default: true)

是否允许网页搜索实时访问互联网。省略时默认为 true。设为 false 时，网页搜索工具以离线或仅缓存模式运行，不会抓取新的外部内容。

• filters: optional object { allowed_domains } or null

搜索的筛选条件。

• allowed_domains: optional array of string or null (default: [])

搜索允许的域名。未提供时允许所有域名。 也允许访问所提供域名的子域名。

示例：["pubmed.ncbi.nlm.nih.gov"]

• search_context_size: optional "low" or "medium" or "high" (default: "medium")

对搜索占用上下文窗口空间大小的总体指导，可选 low、medium 或 high，默认为 medium。

• "low"

• "medium"

• "high"

• user_location: optional object { city, country, region, 2 more } or null

用户的大致位置。省略或设为 null 时，默认为 美国。若要避免此默认值，可传入不包含位置字段的 {"type": "approximate"}。 若要本地化结果，须提供相应位置字段。

• city: optional string or null

用户所在城市的自由文本，例如 San Francisco。

• country: optional string or null

用户所在国家/地区的两字母 ISO 代码，例如 US。

• region: optional string or null

用户所在地区的自由文本，例如 California。

• timezone: optional string or null

用户所在的 IANA 时区，例如 America/Los_Angeles。

• type: optional "approximate" (default: "approximate")

位置估算类型，固定为 approximate。

• "approximate"

• Mcp object { server_label, type, allowed_callers, 9 more }

通过远程模型上下文协议（MCP）服务器， 向模型提供额外工具。了解 MCP。

• server_label: string

此 MCP 服务器的标签，用于在工具调用中标识服务器。

• type: "mcp"

MCP 工具类型，固定为 mcp。

• "mcp"

• allowed_callers: optional array of "direct" or "programmatic" or null

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• allowed_tools: optional array of string or McpToolFilter { read_only, tool_names } or null

允许的工具名称列表或筛选对象。

• McpAllowedTools = array of string

允许的工具名称组成的字符串数组。

• McpToolFilter object { read_only, tool_names }

用于指定允许哪些工具的筛选对象。

• read_only: optional boolean

表示工具会修改数据还是只读。如果 MCP 服务器标注了 readOnlyHint， 就会与此筛选条件匹配。

• tool_names: optional array of string

允许的工具名称列表。

• authorization: optional string

可用于远程 MCP 服务器的 OAuth 访问令牌，既可 配合自定义 MCP 服务器 URL，也可配合服务连接器。你的应用 须处理 OAuth 授权流程，并在此提供令牌。

• connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more

服务连接器的标识，例如 ChatGPT 中提供的连接器。须提供 server_url、connector_id 或 tunnel_id 中的一项。更多 服务连接器信息参阅此处。

对于 2026 年 9 月 1 日之后发布的模型，此字段已弃用。 使用 server_url 连接远程 MCP 服务器，或使用 tunnel_id 通过安全 MCP 隧道连接。

当前支持的 connector_id 值如下：

• Dropbox：connector_dropbox
• Gmail：connector_gmail
• Google 日历：connector_googlecalendar
• Google 云端硬盘：connector_googledrive
• Microsoft Teams：connector_microsoftteams
• Outlook 日历：connector_outlookcalendar
• Outlook 邮箱：connector_outlookemail
• SharePoint：connector_sharepoint

• "connector_dropbox"

• "connector_gmail"

• "connector_googlecalendar"

• "connector_googledrive"

• "connector_microsoftteams"

• "connector_outlookcalendar"

• "connector_outlookemail"

• "connector_sharepoint"

• defer_loading: optional boolean

此 MCP 工具是否延迟加载并通过工具搜索发现。

• headers: optional map[string] or null

可选的发送给 MCP 服务器的 HTTP 请求头，用于认证 或其他用途。

• require_approval: optional McpToolApprovalFilter { always, never } or "always" or "never" or null (default: "always")

指定 MCP 服务器的哪些工具需要批准。

• McpToolApprovalFilter object { always, never }

指定 MCP 服务器的哪些工具需要批准。可以是 always、never，或与需要批准的工具关联的 筛选对象。

• always: optional object { read_only, tool_names }

用于指定允许哪些工具的筛选对象。

• read_only: optional boolean

表示工具会修改数据还是只读。如果 MCP 服务器标注了 readOnlyHint， 就会与此筛选条件匹配。

• tool_names: optional array of string

允许的工具名称列表。

• never: optional object { read_only, tool_names }

用于指定允许哪些工具的筛选对象。

• read_only: optional boolean

表示工具会修改数据还是只读。如果 MCP 服务器标注了 readOnlyHint， 就会与此筛选条件匹配。

• tool_names: optional array of string

允许的工具名称列表。

• McpToolApprovalSetting = "always" or "never"

为所有工具指定统一的批准策略，可选 always 或 never。设为 always 时，所有工具均需要批准； 设为 never 时，所有工具均不需要批准。

• "always"

• "never"

• server_description: optional string

MCP 服务器的可选描述，用于提供更多上下文。

• server_url: optional string

MCP 服务器的 URL。须提供 server_url、connector_id 或 tunnel_id 中的一项。

format: uri

• tunnel_id: optional string

用来替代直接服务器 URL 的安全 MCP 隧道 ID。须提供 server_url、connector_id 或 tunnel_id 中的一项。

pattern: ^tunnel_[a-z0-9]{32}$

• CodeInterpreter object { container, type, allowed_callers }

运行 Python 代码以帮助生成提示词响应的工具。

• container: string or CodeInterpreterToolAuto { type, file_ids, memory_limit, network_policy }

代码解释器容器，可以是容器 ID，也可以是 指定代码可用的已上传文件 ID 的对象，同时可提供 可选的 memory_limit 设置。

• string

容器 ID。

• CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }

代码解释器容器配置，可以指定运行代码时所处理的文件 ID。

• type: "auto" (default: "auto")

固定为 auto。

• "auto"

• file_ids: optional array of string

可选的已上传文件列表，这些文件将提供给代码使用。

maxItems: 50

• memory_limit: optional "1g" or "4g" or "16g" or "64g" or null

代码解释器容器的内存上限。

• "1g"

• "4g"

• "16g"

• "64g"

• network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist

容器的网络访问策略。

• ContainerNetworkPolicyDisabled object { type }

• type: "disabled" (default: "disabled")

禁用出站网络访问，固定为 disabled。

• "disabled"

• ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }

• allowed_domains: array of string

type 为 allowlist 时允许访问的域名列表。

minItems: 1

• type: "allowlist" (default: "allowlist")

仅允许对指定域名发起出站网络访问，固定为 allowlist。

• "allowlist"

• domain_secrets: optional array of ContainerNetworkPolicyDomainSecret

可选的仅用于允许访问域名的域名级密钥。

minItems: 1

• domain: string

密钥关联的域名。

minLength: 1

• name: string

要为该域名注入的密钥名称。

minLength: 1

• value: string

要为该域名注入的密钥值。

minLength: 1, maxLength: 10485760

• type: "code_interpreter"

代码解释器工具类型，固定为 code_interpreter。

• "code_interpreter"

• allowed_callers: optional array of "direct" or "programmatic" or null

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• ProgrammaticToolCalling object { type }

• type: "programmatic_tool_calling" (default: "programmatic_tool_calling")

工具类型，固定为 programmatic_tool_calling。

• "programmatic_tool_calling"

• ImageGeneration object { type, action, background, 13 more }

使用 GPT 图像模型生成图像的工具。

• type: "image_generation"

图像生成工具类型，固定为 image_generation。

• "image_generation"

• action: optional "generate" or "edit" or "auto"

生成新图像还是编辑已有图像，默认为 auto。

• "generate"

• "edit"

• "auto"

• background: optional "transparent" or "opaque" or "auto" (default: "auto")

生成图像的背景，可选 transparent、opaque， 或 auto。gpt-image-2.5-sunburst 和 gpt-image-2.5-flare，包括 对应的 2026-09-08 快照，支持 opaque 和 transparent 背景。受支持的 GPT Image 模型可以使用透明 背景。对于 gpt-image-2 和 gpt-image-2-2026-04-21，此功能处于 预览阶段。使用 transparent 时，须将输出格式设为 png 或 webp。 默认为 auto。

• "transparent"

• "opaque"

• "auto"

• complexity: optional "low" or "medium" or "high"

用于规划图像的计算投入，与渲染质量分开设置。 覆盖外层响应用于图像生成的 reasoning.effort。 省略时，继承外层受支持的推理强度，或使用 图像模型配置的默认值。 对于 SVG 输出，此项控制参考图像，而不是 SVG 生成模型的 推理。

• "low"

• "medium"

• "high"

• frame_count: optional integer (default: 9)

GIF 帧数，要求 output_format 为 gif，默认为 9。

minimum: 2, maximum: 16

• frame_duration_ms: optional integer (default: 200)

每个 GIF 帧的时长，单位为毫秒，取整到 10 毫秒。 要求 output_format 为 gif，默认为 200。

minimum: 20, maximum: 2000

• input_fidelity: optional "high" or "low" or null

控制模型为匹配输入图像风格和特征（尤其是面部特征）投入的程度。gpt-image-1.5 支持 high 和 low，gpt-image-1-mini 仅支持 low。使用 gpt-image-2 时应省略此参数。支持该参数的模型默认为 low。

• "high"

• "low"

• input_image_mask: optional object { file_id, image_url }

可选的局部重绘蒙版，包含 image_url （可选字符串）和 file_id（可选字符串）。

• file_id: optional string

蒙版图像的文件 ID。

• image_url: optional string

采用 Base64 编码的蒙版图像。

• model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 9 more

用于图像生成的模型，可选 gpt-image-1-mini、 gpt-image-1.5, gpt-image-2, gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、 gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare、 gpt-image-2.5-flare-2026-09-08, gpt-image-2.6-sunburst, gpt-image-2.6-flare 或 chatgpt-image-latest。默认值： gpt-image-2.6-sunburst.

gpt-image-1 已于 2026 年 10 月 23 日停用，请使用 gpt-image-2.5-sunburst 或 gpt-image-2.5-flare。

• string

• "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 9 more

用于图像生成的模型，可选 gpt-image-1-mini、 gpt-image-1.5, gpt-image-2, gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、 gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare、 gpt-image-2.5-flare-2026-09-08, gpt-image-2.6-sunburst, gpt-image-2.6-flare 或 chatgpt-image-latest。默认值： gpt-image-2.6-sunburst.

gpt-image-1 已于 2026 年 10 月 23 日停用，请使用 gpt-image-2.5-sunburst 或 gpt-image-2.5-flare。

• "gpt-image-1"

• "gpt-image-1-mini"

• "gpt-image-2"

• "gpt-image-2-2026-04-21"

• "gpt-image-2.5-sunburst"

• "gpt-image-2.5-sunburst-2026-09-08"

• "gpt-image-2.5-flare"

• "gpt-image-2.5-flare-2026-09-08"

• "gpt-image-2.6-sunburst"

• "gpt-image-2.6-flare"

• "gpt-image-1.5"

• "chatgpt-image-latest"

• moderation: optional "auto" or "low" (default: "auto")

生成图像的审核级别，默认为 auto。

• "auto"

• "low"

• output_compression: optional integer (default: 100)

输出图像的压缩级别，默认为 100。

minimum: 0, maximum: 100

• output_format: optional "png" or "webp" or "jpeg" or 2 more (default: "png")

输出图像格式，可选 png、webp、jpeg、 gif 或 svg，默认为 png。GIF 和 SVG 输出要求模型 支持所选格式。GIF 输出不支持 部分图像流式传输，即 partial_images 大于 0， 也不支持 input_image_mask 或自定义 output_compression。 GIF 输出仍可以流式发送 Responses 生命周期事件。

• "png"

• "webp"

• "jpeg"

• "gif"

• "svg"

• partial_images: optional integer (default: 0)

流式模式中生成的部分图像数量，范围为 0（默认值）到 3。

minimum: 0, maximum: 3

• quality: optional "low" or "medium" or "high" or 3 more (default: "auto")

生成图像的质量。GPT 图像模型支持 low、 medium 和 high。gpt-image-2.5-sunburst 和 gpt-image-2.5-flare， 包括对应的 2026-09-08 快照，还支持 xhigh 和 max。 默认为 auto。

• "low"

• "medium"

• "high"

• "xhigh"

• "max"

• "auto"

• size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto" (default: "auto")

生成图像的尺寸。gpt-image-2、gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare 和 gpt-image-2.5-flare-2026-09-08 支持以 WIDTHxHEIGHT 字符串指定任意分辨率，例如 1536x864。宽和高均须能被 16 整除，宽高比须在 1:3 至 3:1 之间。高于 2560x1440 的分辨率属于实验功能，支持的最高分辨率为 3840x2160。尺寸还须符合模型当前的像素数与边长限制。GPT Image 模型支持标准尺寸 1024x1024、1536x1024 和 1024x1536；允许自动尺寸的模型支持 auto。

• string

• "1024x1024" or "1024x1536" or "1536x1024" or "auto"

生成图像的尺寸。gpt-image-2、gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare 和 gpt-image-2.5-flare-2026-09-08 支持以 WIDTHxHEIGHT 字符串指定任意分辨率，例如 1536x864。宽和高均须能被 16 整除，宽高比须在 1:3 至 3:1 之间。高于 2560x1440 的分辨率属于实验功能，支持的最高分辨率为 3840x2160。尺寸还须符合模型当前的像素数与边长限制。GPT Image 模型支持标准尺寸 1024x1024、1536x1024 和 1024x1536；允许自动尺寸的模型支持 auto。

• "1024x1024"

• "1024x1536"

• "1536x1024"

• "auto"

• svg: optional object { model, reasoning }

SVG 生成模型的设置，要求 output_format 为 svg。 启用 SVG 模型选择时，省略此对象会使用 外层响应模型。否则使用默认 SVG 生成模型，且 不能显式覆盖模型。

• model: optional string

minLength: 1

• reasoning: optional object { effort } or null

SVG 编写的推理强度。省略时，Images 和 Responses 均使用编写模型的默认值。

• effort: optional "none" or "minimal" or "low" or 4 more

控制模型为此次请求投入的推理强度。

• "none"

• "minimal"

• "low"

• "medium"

• "high"

• "xhigh"

• "max"

• LocalShell object { type }

允许模型在本地环境执行 shell 命令的工具。

• type: "local_shell" (default: "local_shell")

本地 shell 工具类型，固定为 local_shell。

• "local_shell"

• Shell object { type, allowed_callers, environment }

允许模型执行 shell 命令的工具。

• type: "shell" (default: "shell")

shell 工具类型，固定为 shell。

• "shell"

• allowed_callers: optional array of "direct" or "programmatic" or null

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• environment: optional ContainerAuto or LocalEnvironment or ContainerReference or null

• ContainerAuto object { type, file_ids, memory_limit, 2 more }

• type: "container_auto" (default: "container_auto")

为此请求自动创建容器。

• "container_auto"

• file_ids: optional array of string

可选的已上传文件列表，这些文件将提供给代码使用。

maxItems: 50

• memory_limit: optional "1g" or "4g" or "16g" or "64g" or null

容器的内存上限。

• "1g"

• "4g"

• "16g"

• "64g"

• network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist

容器的网络访问策略。

• ContainerNetworkPolicyDisabled object { type }

• ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }

• skills: optional array of SkillReference or InlineSkill

可选的技能列表，通过 ID 或内联数据引用技能。

maxItems: 200

• SkillReference object { skill_id, type, version }

• skill_id: string

引用的技能 ID。

minLength: 1, maxLength: 64

• type: "skill_reference" (default: "skill_reference")

引用通过 /v1/skills 接口创建的技能。

• "skill_reference"

• version: optional string

可选的技能版本。使用正整数或 'latest'，省略时使用默认版本。

• InlineSkill object { description, name, source, type }

• description: string

技能描述。

• name: string

技能名称。

• source: InlineSkillSource

内联技能载荷。

• data: string

采用 Base64 编码的技能 ZIP 包。

minLength: 1, maxLength: 70254592

• media_type: "application/zip" (default: "application/zip")

内联技能载荷的媒体类型，必须为 application/zip。

• "application/zip"

• type: "base64" (default: "base64")

内联技能来源的类型，必须为 base64。

• "base64"

• type: "inline" (default: "inline")

为此请求定义内联技能。

• "inline"

• LocalEnvironment object { type, skills }

• type: "local" (default: "local")

使用本地计算机环境。

• "local"

• skills: optional array of LocalSkill

可选的技能列表。

maxItems: 200

• description: string

技能描述。

• name: string

技能名称。

• path: string

包含该技能的目录路径。

• ContainerReference object { container_id, type }

• container_id: string

引用的容器 ID。

• type: "container_reference" (default: "container_reference")

引用通过 /v1/containers 接口创建的容器。

• "container_reference"

• Custom object { name, type, allowed_callers, 4 more }

使用指定格式处理输入的自定义工具。参阅自定义工具。

• name: string

自定义工具的名称，用于在工具调用中标识它。

• type: "custom" (default: "custom")

自定义工具类型，固定为 custom。

• "custom"

• allowed_callers: optional array of "direct" or "programmatic" or null

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• async: optional boolean

工具响应是否可以异步返回，而非在下一次创建响应时立即返回。

• defer_loading: optional boolean

此工具是否应延迟加载并通过工具搜索发现。

• description: optional string

自定义工具的可选描述，用于提供更多上下文。

• format: optional CustomToolInputFormat

自定义工具的输入格式，默认为无约束文本。

• Text object { type }

无约束的自由文本。

• type: "text" (default: "text")

无约束文本格式，固定为 text。

• "text"

• Grammar object { definition, syntax, type }

用户定义的语法。

• definition: string

语法定义。

• syntax: "lark" or "regex"

语法定义的语法类型，可选 lark 或 regex。

• "lark"

• "regex"

• type: "grammar" (default: "grammar")

语法格式，固定为 grammar。

• "grammar"

• Namespace object { description, name, tools, type }

将函数工具或自定义工具归入共享命名空间。

• description: string

展示给模型的命名空间描述。

• name: string

工具调用使用的命名空间名称，例如 crm。

minLength: 1

• tools: array of Function { name, type, allowed_callers, 6 more } or Custom { name, type, allowed_callers, 4 more }

此命名空间内可用的函数工具或自定义工具。

minItems: 1

• Function object { name, type, allowed_callers, 6 more }

• name: string

pattern: ^[a-zA-Z0-9_-]+$, minLength: 1, maxLength: 128

• type: "function" (default: "function")

• "function"

• allowed_callers: optional array of "direct" or "programmatic" or null

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• async: optional boolean

工具响应是否可以异步返回，而非在下一次创建响应时立即返回。

• defer_loading: optional boolean

此函数是否应延迟加载并通过工具搜索发现。

• description: optional string or null

• output_schema: optional map[unknown] or null

描述此函数工具字符串输出中编码的 JSON 值的 JSON Schema，不用于描述内容数组输出。

• parameters: optional unknown or null

• strict: optional boolean or null

是否强制执行严格参数校验。省略时，模式兼容的情况下 Responses 会尝试严格校验，否则退回非严格校验。

• Custom object { name, type, allowed_callers, 4 more }

使用指定格式处理输入的自定义工具。参阅自定义工具。

• name: string

自定义工具的名称，用于在工具调用中标识它。

• type: "custom" (default: "custom")

自定义工具类型，固定为 custom。

• "custom"

• allowed_callers: optional array of "direct" or "programmatic" or null

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• async: optional boolean

工具响应是否可以异步返回，而非在下一次创建响应时立即返回。

• defer_loading: optional boolean

此工具是否应延迟加载并通过工具搜索发现。

• description: optional string

自定义工具的可选描述，用于提供更多上下文。

• format: optional CustomToolInputFormat

自定义工具的输入格式，默认为无约束文本。

• type: "namespace" (default: "namespace")

工具类型，固定为 namespace。

• "namespace"

• ToolSearch object { type, description, execution, parameters }

用于延迟加载工具的托管工具搜索或自带工具（BYOT）搜索配置。

• type: "tool_search" (default: "tool_search")

工具类型，固定为 tool_search。

• "tool_search"

• description: optional string or null

客户端执行的工具搜索工具展示给模型的描述。

• execution: optional "server" or "client"

工具搜索由服务端还是客户端执行。

• "server"

• "client"

• parameters: optional unknown or null

客户端执行的工具搜索工具的参数模式。

• WebSearchPreview object { type, search_content_types, search_context_size, user_location }

搜索网页以获取可用于响应的相关结果的工具。参阅网页搜索工具。

• type: "web_search_preview" or "web_search_preview_2025_03_11" (default: "web_search_preview")

网页搜索工具类型，可选 web_search_preview 或 web_search_preview_2025_03_11。

• "web_search_preview"

• "web_search_preview_2025_03_11"

• search_content_types: optional array of "text" or "image"

• "text"

• "image"

• search_context_size: optional "low" or "medium" or "high"

对搜索占用上下文窗口空间大小的总体指导，可选 low、medium 或 high，默认为 medium。

• "low"

• "medium"

• "high"

• user_location: optional object { type, city, country, 2 more } or null

用户的大致位置。省略或设为 null 时默认为美国。若要避免此默认值，可传入不包含位置字段的 {"type": "approximate"}。若要本地化结果，须提供相应位置字段。

• type: "approximate" (default: "approximate")

位置估算类型，固定为 approximate。

• "approximate"

• city: optional string or null

用户所在城市的自由文本，例如 San Francisco。

• country: optional string or null

用户所在国家/地区的两字母 ISO 代码，例如 US。

• region: optional string or null

用户所在地区的自由文本，例如 California。

• timezone: optional string or null

用户所在的 IANA 时区，例如 America/Los_Angeles。

• ApplyPatch object { type, allowed_callers }

允许助手使用统一差异格式创建、删除或更新文件。

• type: "apply_patch" (default: "apply_patch")

工具类型，固定为 apply_patch。

• "apply_patch"

• allowed_callers: optional array of "direct" or "programmatic" or null

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• type: "tool_search_output" (default: "tool_search_output")

条目类型，固定为 tool_search_output。

• "tool_search_output"

• created_by: optional string

创建该条目的执行主体的标识。

• AdditionalTools object { id, role, tools, type }

• 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 or CompoundFilter or null

要应用的筛选条件。

• ComparisonFilter object { key, type, value }

使用指定比较运算，将某个属性键与给定值比较的筛选条件。

• CompoundFilter object { filters, type }

使用 and 或 or 组合多个筛选条件。

• max_num_results: optional integer

返回结果数量上限，须介于 1–50 之间，含边界。

• ranking_options: optional object { hybrid_search, ranker, score_threshold }

搜索结果的排序选项。

• hybrid_search: optional object { embedding_weight, text_weight }

启用混合搜索时，控制倒数排名融合如何平衡语义嵌入匹配与稀疏关键词匹配的权重。

• embedding_weight: number

嵌入在倒数排名融合中的权重。

• text_weight: number

文本在倒数排名融合中的权重。

• ranker: optional "auto" or "default-2024-11-15"

文件搜索所用的排序器。

• "auto"

• "default-2024-11-15"

• score_threshold: optional number

文件搜索的分数阈值，为 0–1 之间的数字。越接近 1，越倾向于只返回最相关的结果，但返回数量可能减少。

• Computer object { type }

控制虚拟计算机的工具。参阅计算机工具。

• type: "computer" (default: "computer")

计算机工具类型，固定为 computer。

• "computer"

• ComputerUsePreview object { display_height, display_width, environment, type }

控制虚拟计算机的工具。参阅计算机工具。

• display_height: integer

计算机显示区域的高度。

• display_width: integer

计算机显示区域的宽度。

• environment: "windows" or "mac" or "linux" or 2 more

要控制的计算机环境类型。

• "windows"

• "mac"

• "linux"

• "ubuntu"

• "browser"

• type: "computer_use_preview" (default: "computer_use_preview")

计算机使用工具类型，固定为 computer_use_preview。

• "computer_use_preview"

• WebSearch object { type, external_web_access, filters, 2 more }

在互联网上搜索与提示词相关的信息来源。参阅 网络搜索工具时。

• type: "web_search" or "web_search_2025_08_26" (default: "web_search")

网页搜索工具类型，可选 web_search 或 web_search_2025_08_26。

• "web_search"

• "web_search_2025_08_26"

• external_web_access: optional boolean (default: true)

是否允许网页搜索实时访问互联网。省略时默认为 true。设为 false 时，网页搜索工具以离线或仅缓存模式运行，不会抓取新的外部内容。

• filters: optional object { allowed_domains } or null

搜索的筛选条件。

• allowed_domains: optional array of string or null (default: [])

搜索允许的域名。未提供时允许所有域名。 也允许访问所提供域名的子域名。

示例：["pubmed.ncbi.nlm.nih.gov"]

• search_context_size: optional "low" or "medium" or "high" (default: "medium")

对搜索占用上下文窗口空间大小的总体指导，可选 low、medium 或 high，默认为 medium。

• "low"

• "medium"

• "high"

• user_location: optional object { city, country, region, 2 more } or null

用户的大致位置。省略或设为 null 时，默认为 美国。若要避免此默认值，可传入不包含位置字段的 {"type": "approximate"}。 若要本地化结果，须提供相应位置字段。

• city: optional string or null

用户所在城市的自由文本，例如 San Francisco。

• country: optional string or null

用户所在国家/地区的两字母 ISO 代码，例如 US。

• region: optional string or null

用户所在地区的自由文本，例如 California。

• timezone: optional string or null

用户所在的 IANA 时区，例如 America/Los_Angeles。

• type: optional "approximate" (default: "approximate")

位置估算类型，固定为 approximate。

• "approximate"

• Mcp object { server_label, type, allowed_callers, 9 more }

通过远程模型上下文协议（MCP）服务器， 向模型提供额外工具。了解 MCP。

• server_label: string

此 MCP 服务器的标签，用于在工具调用中标识服务器。

• type: "mcp"

MCP 工具类型，固定为 mcp。

• "mcp"

• allowed_callers: optional array of "direct" or "programmatic" or null

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• allowed_tools: optional array of string or McpToolFilter { read_only, tool_names } or null

允许的工具名称列表或筛选对象。

• McpAllowedTools = array of string

允许的工具名称组成的字符串数组。

• McpToolFilter object { read_only, tool_names }

用于指定允许哪些工具的筛选对象。

• read_only: optional boolean

表示工具会修改数据还是只读。如果 MCP 服务器标注了 readOnlyHint， 就会与此筛选条件匹配。

• tool_names: optional array of string

允许的工具名称列表。

• authorization: optional string

可用于远程 MCP 服务器的 OAuth 访问令牌，既可 配合自定义 MCP 服务器 URL，也可配合服务连接器。你的应用 须处理 OAuth 授权流程，并在此提供令牌。

• connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more

服务连接器的标识，例如 ChatGPT 中提供的连接器。须提供 server_url、connector_id 或 tunnel_id 中的一项。更多 服务连接器信息参阅此处。

对于 2026 年 9 月 1 日之后发布的模型，此字段已弃用。 使用 server_url 连接远程 MCP 服务器，或使用 tunnel_id 通过安全 MCP 隧道连接。

当前支持的 connector_id 值如下：

• Dropbox：connector_dropbox
• Gmail：connector_gmail
• Google 日历：connector_googlecalendar
• Google 云端硬盘：connector_googledrive
• Microsoft Teams：connector_microsoftteams
• Outlook 日历：connector_outlookcalendar
• Outlook 邮箱：connector_outlookemail
• SharePoint：connector_sharepoint

• "connector_dropbox"

• "connector_gmail"

• "connector_googlecalendar"

• "connector_googledrive"

• "connector_microsoftteams"

• "connector_outlookcalendar"

• "connector_outlookemail"

• "connector_sharepoint"

• defer_loading: optional boolean

此 MCP 工具是否延迟加载并通过工具搜索发现。

• headers: optional map[string] or null

可选的发送给 MCP 服务器的 HTTP 请求头，用于认证 或其他用途。

• require_approval: optional McpToolApprovalFilter { always, never } or "always" or "never" or null (default: "always")

指定 MCP 服务器的哪些工具需要批准。

• McpToolApprovalFilter object { always, never }

指定 MCP 服务器的哪些工具需要批准。可以是 always、never，或与需要批准的工具关联的 筛选对象。

• always: optional object { read_only, tool_names }

用于指定允许哪些工具的筛选对象。

• read_only: optional boolean

表示工具会修改数据还是只读。如果 MCP 服务器标注了 readOnlyHint， 就会与此筛选条件匹配。

• tool_names: optional array of string

允许的工具名称列表。

• never: optional object { read_only, tool_names }

用于指定允许哪些工具的筛选对象。

• read_only: optional boolean

表示工具会修改数据还是只读。如果 MCP 服务器标注了 readOnlyHint， 就会与此筛选条件匹配。

• tool_names: optional array of string

允许的工具名称列表。

• McpToolApprovalSetting = "always" or "never"

为所有工具指定统一的批准策略，可选 always 或 never。设为 always 时，所有工具均需要批准； 设为 never 时，所有工具均不需要批准。

• "always"

• "never"

• server_description: optional string

MCP 服务器的可选描述，用于提供更多上下文。

• server_url: optional string

MCP 服务器的 URL。须提供 server_url、connector_id 或 tunnel_id 中的一项。

format: uri

• tunnel_id: optional string

用来替代直接服务器 URL 的安全 MCP 隧道 ID。须提供 server_url、connector_id 或 tunnel_id 中的一项。

pattern: ^tunnel_[a-z0-9]{32}$

• CodeInterpreter object { container, type, allowed_callers }

运行 Python 代码以帮助生成提示词响应的工具。

• container: string or CodeInterpreterToolAuto { type, file_ids, memory_limit, network_policy }

代码解释器容器，可以是容器 ID，也可以是 指定代码可用的已上传文件 ID 的对象，同时可提供 可选的 memory_limit 设置。

• string

容器 ID。

• CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }

代码解释器容器配置，可以指定运行代码时所处理的文件 ID。

• type: "auto" (default: "auto")

固定为 auto。

• "auto"

• file_ids: optional array of string

可选的已上传文件列表，这些文件将提供给代码使用。

maxItems: 50

• memory_limit: optional "1g" or "4g" or "16g" or "64g" or null

代码解释器容器的内存上限。

• "1g"

• "4g"

• "16g"

• "64g"

• network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist

容器的网络访问策略。

• ContainerNetworkPolicyDisabled object { type }

• ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }

• type: "code_interpreter"

代码解释器工具类型，固定为 code_interpreter。

• "code_interpreter"

• allowed_callers: optional array of "direct" or "programmatic" or null

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• ProgrammaticToolCalling object { type }

• type: "programmatic_tool_calling" (default: "programmatic_tool_calling")

工具类型，固定为 programmatic_tool_calling。

• "programmatic_tool_calling"

• ImageGeneration object { type, action, background, 13 more }

使用 GPT 图像模型生成图像的工具。

• type: "image_generation"

图像生成工具类型，固定为 image_generation。

• "image_generation"

• action: optional "generate" or "edit" or "auto"

生成新图像还是编辑已有图像，默认为 auto。

• "generate"

• "edit"

• "auto"

• background: optional "transparent" or "opaque" or "auto" (default: "auto")

生成图像的背景，可选 transparent、opaque， 或 auto。gpt-image-2.5-sunburst 和 gpt-image-2.5-flare，包括 对应的 2026-09-08 快照，支持 opaque 和 transparent 背景。受支持的 GPT Image 模型可以使用透明 背景。对于 gpt-image-2 和 gpt-image-2-2026-04-21，此功能处于 预览阶段。使用 transparent 时，须将输出格式设为 png 或 webp。 默认为 auto。

• "transparent"

• "opaque"

• "auto"

• complexity: optional "low" or "medium" or "high"

用于规划图像的计算投入，与渲染质量分开设置。 覆盖外层响应用于图像生成的 reasoning.effort。 省略时，继承外层受支持的推理强度，或使用 图像模型配置的默认值。 对于 SVG 输出，此项控制参考图像，而不是 SVG 生成模型的 推理。

• "low"

• "medium"

• "high"

• frame_count: optional integer (default: 9)

GIF 帧数，要求 output_format 为 gif，默认为 9。

minimum: 2, maximum: 16

• frame_duration_ms: optional integer (default: 200)

每个 GIF 帧的时长，单位为毫秒，取整到 10 毫秒。 要求 output_format 为 gif，默认为 200。

minimum: 20, maximum: 2000

• input_fidelity: optional "high" or "low" or null

控制模型为匹配输入图像风格和特征（尤其是面部特征）投入的程度。gpt-image-1.5 支持 high 和 low，gpt-image-1-mini 仅支持 low。使用 gpt-image-2 时应省略此参数。支持该参数的模型默认为 low。

• "high"

• "low"

• input_image_mask: optional object { file_id, image_url }

可选的局部重绘蒙版，包含 image_url （可选字符串）和 file_id（可选字符串）。

• file_id: optional string

蒙版图像的文件 ID。

• image_url: optional string

采用 Base64 编码的蒙版图像。

• model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 9 more

用于图像生成的模型，可选 gpt-image-1-mini、 gpt-image-1.5, gpt-image-2, gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、 gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare、 gpt-image-2.5-flare-2026-09-08, gpt-image-2.6-sunburst, gpt-image-2.6-flare 或 chatgpt-image-latest。默认值： gpt-image-2.6-sunburst.

gpt-image-1 已于 2026 年 10 月 23 日停用，请使用 gpt-image-2.5-sunburst 或 gpt-image-2.5-flare。

• string

• "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 9 more

用于图像生成的模型，可选 gpt-image-1-mini、 gpt-image-1.5, gpt-image-2, gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、 gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare、 gpt-image-2.5-flare-2026-09-08, gpt-image-2.6-sunburst, gpt-image-2.6-flare 或 chatgpt-image-latest。默认值： gpt-image-2.6-sunburst.

gpt-image-1 已于 2026 年 10 月 23 日停用，请使用 gpt-image-2.5-sunburst 或 gpt-image-2.5-flare。

• "gpt-image-1"

• "gpt-image-1-mini"

• "gpt-image-2"

• "gpt-image-2-2026-04-21"

• "gpt-image-2.5-sunburst"

• "gpt-image-2.5-sunburst-2026-09-08"

• "gpt-image-2.5-flare"

• "gpt-image-2.5-flare-2026-09-08"

• "gpt-image-2.6-sunburst"

• "gpt-image-2.6-flare"

• "gpt-image-1.5"

• "chatgpt-image-latest"

• moderation: optional "auto" or "low" (default: "auto")

生成图像的审核级别，默认为 auto。

• "auto"

• "low"

• output_compression: optional integer (default: 100)

输出图像的压缩级别，默认为 100。

minimum: 0, maximum: 100

• output_format: optional "png" or "webp" or "jpeg" or 2 more (default: "png")

输出图像格式，可选 png、webp、jpeg、 gif 或 svg，默认为 png。GIF 和 SVG 输出要求模型 支持所选格式。GIF 输出不支持 部分图像流式传输，即 partial_images 大于 0， 也不支持 input_image_mask 或自定义 output_compression。 GIF 输出仍可以流式发送 Responses 生命周期事件。

• "png"

• "webp"

• "jpeg"

• "gif"

• "svg"

• partial_images: optional integer (default: 0)

流式模式中生成的部分图像数量，范围为 0（默认值）到 3。

minimum: 0, maximum: 3

• quality: optional "low" or "medium" or "high" or 3 more (default: "auto")

生成图像的质量。GPT 图像模型支持 low、 medium 和 high。gpt-image-2.5-sunburst 和 gpt-image-2.5-flare， 包括对应的 2026-09-08 快照，还支持 xhigh 和 max。 默认为 auto。

• "low"

• "medium"

• "high"

• "xhigh"

• "max"

• "auto"

• size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto" (default: "auto")

生成图像的尺寸。gpt-image-2、gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare 和 gpt-image-2.5-flare-2026-09-08 支持以 WIDTHxHEIGHT 字符串指定任意分辨率，例如 1536x864。宽和高均须能被 16 整除，宽高比须在 1:3 至 3:1 之间。高于 2560x1440 的分辨率属于实验功能，支持的最高分辨率为 3840x2160。尺寸还须符合模型当前的像素数与边长限制。GPT Image 模型支持标准尺寸 1024x1024、1536x1024 和 1024x1536；允许自动尺寸的模型支持 auto。

• string

• "1024x1024" or "1024x1536" or "1536x1024" or "auto"

生成图像的尺寸。gpt-image-2、gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare 和 gpt-image-2.5-flare-2026-09-08 支持以 WIDTHxHEIGHT 字符串指定任意分辨率，例如 1536x864。宽和高均须能被 16 整除，宽高比须在 1:3 至 3:1 之间。高于 2560x1440 的分辨率属于实验功能，支持的最高分辨率为 3840x2160。尺寸还须符合模型当前的像素数与边长限制。GPT Image 模型支持标准尺寸 1024x1024、1536x1024 和 1024x1536；允许自动尺寸的模型支持 auto。

• "1024x1024"

• "1024x1536"

• "1536x1024"

• "auto"

• svg: optional object { model, reasoning }

SVG 生成模型的设置，要求 output_format 为 svg。 启用 SVG 模型选择时，省略此对象会使用 外层响应模型。否则使用默认 SVG 生成模型，且 不能显式覆盖模型。

• model: optional string

minLength: 1

• reasoning: optional object { effort } or null

SVG 编写的推理强度。省略时，Images 和 Responses 均使用编写模型的默认值。

• effort: optional "none" or "minimal" or "low" or 4 more

控制模型为此次请求投入的推理强度。

• "none"

• "minimal"

• "low"

• "medium"

• "high"

• "xhigh"

• "max"

• LocalShell object { type }

允许模型在本地环境执行 shell 命令的工具。

• type: "local_shell" (default: "local_shell")

本地 shell 工具类型，固定为 local_shell。

• "local_shell"

• Shell object { type, allowed_callers, environment }

允许模型执行 shell 命令的工具。

• type: "shell" (default: "shell")

shell 工具类型，固定为 shell。

• "shell"

• allowed_callers: optional array of "direct" or "programmatic" or null

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• environment: optional ContainerAuto or LocalEnvironment or ContainerReference or null

• ContainerAuto object { type, file_ids, memory_limit, 2 more }

• LocalEnvironment object { type, skills }

• ContainerReference object { container_id, type }

• Custom object { name, type, allowed_callers, 4 more }

使用指定格式处理输入的自定义工具。参阅自定义工具。

• name: string

自定义工具的名称，用于在工具调用中标识它。

• type: "custom" (default: "custom")

自定义工具类型，固定为 custom。

• "custom"

• allowed_callers: optional array of "direct" or "programmatic" or null

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• async: optional boolean

工具响应是否可以异步返回，而非在下一次创建响应时立即返回。

• defer_loading: optional boolean

此工具是否应延迟加载并通过工具搜索发现。

• description: optional string

自定义工具的可选描述，用于提供更多上下文。

• format: optional CustomToolInputFormat

自定义工具的输入格式，默认为无约束文本。

• Namespace object { description, name, tools, type }

将函数工具或自定义工具归入共享命名空间。

• description: string

展示给模型的命名空间描述。

• name: string

工具调用使用的命名空间名称，例如 crm。

minLength: 1

• tools: array of Function { name, type, allowed_callers, 6 more } or Custom { name, type, allowed_callers, 4 more }

此命名空间内可用的函数工具或自定义工具。

minItems: 1

• Function object { name, type, allowed_callers, 6 more }

• name: string

pattern: ^[a-zA-Z0-9_-]+$, minLength: 1, maxLength: 128

• type: "function" (default: "function")

• "function"

• allowed_callers: optional array of "direct" or "programmatic" or null

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• async: optional boolean

工具响应是否可以异步返回，而非在下一次创建响应时立即返回。

• defer_loading: optional boolean

此函数是否应延迟加载并通过工具搜索发现。

• description: optional string or null

• output_schema: optional map[unknown] or null

描述此函数工具字符串输出中编码的 JSON 值的 JSON Schema，不用于描述内容数组输出。

• parameters: optional unknown or null

• strict: optional boolean or null

是否强制执行严格参数校验。省略时，模式兼容的情况下 Responses 会尝试严格校验，否则退回非严格校验。

• Custom object { name, type, allowed_callers, 4 more }

使用指定格式处理输入的自定义工具。参阅自定义工具。

• name: string

自定义工具的名称，用于在工具调用中标识它。

• type: "custom" (default: "custom")

自定义工具类型，固定为 custom。

• "custom"

• allowed_callers: optional array of "direct" or "programmatic" or null

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• async: optional boolean

工具响应是否可以异步返回，而非在下一次创建响应时立即返回。

• defer_loading: optional boolean

此工具是否应延迟加载并通过工具搜索发现。

• description: optional string

自定义工具的可选描述，用于提供更多上下文。

• format: optional CustomToolInputFormat

自定义工具的输入格式，默认为无约束文本。

• type: "namespace" (default: "namespace")

工具类型，固定为 namespace。

• "namespace"

• ToolSearch object { type, description, execution, parameters }

用于延迟加载工具的托管工具搜索或自带工具（BYOT）搜索配置。

• type: "tool_search" (default: "tool_search")

工具类型，固定为 tool_search。

• "tool_search"

• description: optional string or null

客户端执行的工具搜索工具展示给模型的描述。

• execution: optional "server" or "client"

工具搜索由服务端还是客户端执行。

• "server"

• "client"

• parameters: optional unknown or null

客户端执行的工具搜索工具的参数模式。

• WebSearchPreview object { type, search_content_types, search_context_size, user_location }

搜索网页以获取可用于响应的相关结果的工具。参阅网页搜索工具。

• type: "web_search_preview" or "web_search_preview_2025_03_11" (default: "web_search_preview")

网页搜索工具类型，可选 web_search_preview 或 web_search_preview_2025_03_11。

• "web_search_preview"

• "web_search_preview_2025_03_11"

• search_content_types: optional array of "text" or "image"

• "text"

• "image"

• search_context_size: optional "low" or "medium" or "high"

对搜索占用上下文窗口空间大小的总体指导，可选 low、medium 或 high，默认为 medium。

• "low"

• "medium"

• "high"

• user_location: optional object { type, city, country, 2 more } or null

用户的大致位置。省略或设为 null 时默认为美国。若要避免此默认值，可传入不包含位置字段的 {"type": "approximate"}。若要本地化结果，须提供相应位置字段。

• type: "approximate" (default: "approximate")

位置估算类型，固定为 approximate。

• "approximate"

• city: optional string or null

用户所在城市的自由文本，例如 San Francisco。

• country: optional string or null

用户所在国家/地区的两字母 ISO 代码，例如 US。

• region: optional string or null

用户所在地区的自由文本，例如 California。

• timezone: optional string or null

用户所在的 IANA 时区，例如 America/Los_Angeles。

• ApplyPatch object { type, allowed_callers }

允许助手使用统一差异格式创建、删除或更新文件。

• type: "apply_patch" (default: "apply_patch")

工具类型，固定为 apply_patch。

• "apply_patch"

• allowed_callers: optional array of "direct" or "programmatic" or null

工具调用的上下文。

minItems: 1

• "direct"

• "programmatic"

• type: "additional_tools" (default: "additional_tools")

条目类型，固定为 additional_tools。

• "additional_tools"

• ConfigurationUpdate object { id, type, reasoning, text }

后续响应的配置更新。每项设置保持生效， 直至后续更新替换该设置。

• id: string

配置更新条目的唯一 ID。

• type: "configuration_update" (default: "configuration_update")

条目类型，固定为 configuration_update。

• "configuration_update"

• reasoning: optional object { effort }

本次更新应用的推理配置。

• effort: optional ReasoningEffort or null (default: "medium")

后续响应使用的推理强度，直至另一次 配置更新替换它。

• "none"

• "minimal"

• "low"

• "medium"

• "high"

• "xhigh"

• "max"

• text: optional object { format }

后续响应的文本输出配置。

• format: ResponseFormatText or ResponseFormatTextJSONSchemaConfig

使用 JSON Schema 进行结构化输出，或使用 text 恢复纯文本。

• ResponseFormatText object { type }

默认响应格式，用于生成文本响应。

• type: "text"

定义的响应格式类型，固定为 text。

• "text"

• ResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }

JSON Schema 响应格式，用于生成结构化 JSON 响应。 参阅结构化输出。

• name: string

响应格式的名称，须使用 a-z、A-Z、0-9，或包含 下划线和连字符，最长为 64 个字符。

• schema: map[unknown]

以 JSON Schema 对象描述的响应格式模式。 JSON Schema 的构建方法参阅此处。

• type: "json_schema"

定义的响应格式类型，固定为 json_schema。

• "json_schema"

• description: optional string

响应格式的用途描述，模型据此 判断如何按该格式响应。

• strict: optional boolean or null (default: false)

生成输出时是否启用严格模式遵循。 设为 true 时，模型始终严格遵循 schema 字段中定义的模式。strict 为 true 时仅支持 JSON Schema 的子集。更多信息请参阅结构化输出 指南。

• Reasoning object { id, summary, type, 3 more }

描述推理模型生成响应时所用的 思维链。如果手动管理对话的上下文，后续轮次中须将这些条目 包含在发送给 Responses API 的 input 中， 管理上下文。

• id: string

推理内容的唯一标识。

• summary: array of SummaryTextContent

推理摘要内容。

• text: string

模型到目前为止生成的推理输出摘要。

• type: "summary_text" (default: "summary_text")

类型，固定为 summary_text。

• type: "reasoning"

类型，固定为 reasoning。

• "reasoning"

• content: optional array of object { text, type }

推理文本内容。

• text: string

模型生成的推理文本。

• type: "reasoning_text" (default: "reasoning_text")

类型，固定为 reasoning_text。

• "reasoning_text"

• encrypted_content: optional string or null

推理条目的加密内容。通过 POST /v1/responses 和 WebSocket response.create 请求返回的推理条目，默认会填充 此字段。

流式传输时，后续请求须使用 response.output_item.done 事件中完整的推理条目及其 encrypted_content。response.output_item.added 中的 encrypted_content 可能不完整。当 store 为 false 或使用零数据保留时，这一点尤其重要。

• status: optional "in_progress" or "completed" or "incomplete"

条目状态，可选 in_progress、completed 或 incomplete。通过 API 返回条目时填充。

• "in_progress"

• "completed"

• "incomplete"

• Program object { id, call_id, code, 2 more }

• id: string

program 条目的唯一 ID。

• call_id: string

program 条目的稳定调用 ID。

• code: string

程序化工具调用所执行的 JavaScript 源代码。

• fingerprint: string

不透明的程序重放指纹，须在后续请求中原样回传。

• type: "program" (default: "program")

条目类型，固定为 program。

• "program"

• ProgramOutput object { id, call_id, result, 2 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"

• Compaction object { id, encrypted_content, type, created_by }

v1/responses/compact API生成的压缩条目。

• id: string

压缩条目的唯一 ID。

• encrypted_content: string

压缩生成的加密内容。

• type: "compaction" (default: "compaction")

类型，固定为 compaction。

• "compaction"

• created_by: optional string

创建该条目的执行主体的标识。

• CodeInterpreterCall object { id, code, container_id, 3 more }

运行代码的工具调用。

• id: string

代码解释器工具调用的唯一 ID。

• code: string or null

要运行的代码，不可用时为 null。

• container_id: string

运行代码使用的容器 ID。

• outputs: array of Logs { logs, type } or Image { type, url } or null

代码解释器生成的输出，例如日志或图像。 没有可用输出时，可以为 null。

• Logs object { logs, type }

代码解释器的日志输出。

• logs: string

代码解释器的日志输出。

• type: "logs" (default: "logs")

类型，固定为 logs。

• "logs"

• Image object { type, url }

代码解释器的图像输出。

• type: "image" (default: "image")

类型，固定为 image。

• "image"

• url: string

代码解释器输出图像的 URL。

format: uri

• status: "in_progress" or "completed" or "incomplete" or 2 more

代码解释器工具调用的状态，有效值为 in_progress、completed、incomplete、interpreting 和 failed。

• "in_progress"

• "completed"

• "incomplete"

• "interpreting"

• "failed"

• type: "code_interpreter_call" (default: "code_interpreter_call")

类型，固定为 code_interpreter_call。

• "code_interpreter_call"

• LocalShellCall object { id, action, call_id, 2 more }

在本地 shell 上运行命令的工具调用。

• id: string

本地 shell 调用的唯一 ID。

• action: object { command, env, type, 3 more }

在服务器上执行 shell 命令。

• command: array of string

要运行的命令。

• env: map[string]

要为命令设置的环境变量。

• type: "exec" (default: "exec")

类型，固定为 exec。

• "exec"

• timeout_ms: optional integer or null

可选的命令超时时长，单位为毫秒。

• user: optional string or null

可选的运行命令的用户。

• working_directory: optional string or null

可选的运行命令的工作目录。

• call_id: string

模型生成的本地 shell 工具调用的唯一 ID。

• status: "in_progress" or "completed" or "incomplete"

本地 shell 调用的状态。

• "in_progress"

• "completed"

• "incomplete"

• type: "local_shell_call"

类型，固定为 local_shell_call。

• "local_shell_call"

• LocalShellCallOutput object { id, output, type, status }

本地 shell 工具调用的输出。

• id: string

模型生成的本地 shell 工具调用的唯一 ID。

• output: string

本地 shell 工具调用输出的 JSON 字符串。

• type: "local_shell_call_output"

类型，固定为 local_shell_call_output。

• "local_shell_call_output"

• status: optional "in_progress" or "completed" or "incomplete" or null

条目状态，可选 in_progress、completed 或 incomplete。

• "in_progress"

• "completed"

• "incomplete"

• ShellCall object { id, action, call_id, 5 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: ResponseLocalEnvironment or ResponseContainerReference or null

表示使用本地环境执行 shell 操作。

• ResponseLocalEnvironment object { type }

表示使用本地环境执行 shell 操作。

• type: "local" (default: "local")

环境类型，固定为 local。

• "local"

• ResponseContainerReference 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"

• 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, 5 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"

• 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, 4 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"

• 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, 4 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"

• 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, 2 more }

MCP 服务器可用的工具列表。

• id: string

列表的唯一 ID。

• server_label: string

MCP 服务器标签。

• tools: array of object { input_schema, name, annotations, description }

服务器可用的工具。

• input_schema: unknown

描述工具输入的 JSON Schema。

• name: string

工具名称。

• annotations: optional unknown or null

工具的额外注解。

• description: optional string or null

工具描述。

• type: "mcp_list_tools"

类型，固定为 mcp_list_tools。

• "mcp_list_tools"

• error: optional string or null

服务器无法列出工具时的错误消息。

• McpApprovalRequest object { id, arguments, name, 2 more }

工具调用的人工批准请求。

• id: string

批准请求的唯一 ID。

• arguments: string

工具参数的 JSON 字符串。

• name: string

要运行的工具名称。

• server_label: string

发出请求的 MCP 服务器标签。

• type: "mcp_approval_request"

类型，固定为 mcp_approval_request。

• "mcp_approval_request"

• McpApprovalResponse object { id, approval_request_id, approve, 2 more }

对 MCP 批准请求的响应。

• id: string

批准响应的唯一 ID。

• approval_request_id: string

所回应的批准请求的 ID。

• approve: boolean

请求是否获准。

• type: "mcp_approval_response"

类型，固定为 mcp_approval_response。

• "mcp_approval_response"

• reason: optional string or null

决定的可选理由。

• McpCall object { id, arguments, name, 6 more }

对 MCP 服务器上工具的调用。

• id: string

工具调用的唯一 ID。

• arguments: string

传给工具的参数组成的 JSON 字符串。

• name: string

已运行的工具名称。

• server_label: string

运行工具的 MCP 服务器标签。

• type: "mcp_call"

类型，固定为 mcp_call。

• "mcp_call"

• approval_request_id: optional string or null

MCP 工具调用批准请求的唯一标识。 在后续 mcp_approval_response 输入中包含此值，可批准或拒绝对应工具调用。

• error: optional McpToolCallError or null

工具调用的错误，如有。

• McpProtocolError object { code, message, type }

• code: integer

• message: string

• type: "mcp_protocol_error" (default: "mcp_protocol_error")

• "mcp_protocol_error"

• McpToolExecutionError object { content, type }

• content: unknown

• type: "mcp_tool_execution_error" (default: "mcp_tool_execution_error")

• "mcp_tool_execution_error"

• HTTPError object { code, message, type }

• code: integer

• message: string

• type: "http_error" (default: "http_error")

• "http_error"

• output: optional string or null

工具调用的输出。

• status: optional "in_progress" or "completed" or "incomplete" or 2 more

工具调用状态，可选 in_progress、completed、incomplete、calling 或 failed。

• "in_progress"

• "completed"

• "incomplete"

• "calling"

• "failed"

• CustomToolCall object { call_id, input, name, 5 more }

模型生成的自定义工具调用。

• call_id: string

用于将此自定义工具调用映射到工具调用输出的标识。

• input: string

模型生成的自定义工具调用输入。

• name: string

被调用的自定义工具的名称。

• type: "custom_tool_call"

类型，固定为 custom_tool_call。

• "custom_tool_call"

• id: optional string

自定义工具调用在 OpenAI 平台中的唯一 ID。

• async: optional boolean

自定义工具调用是否异步运行。

• caller: optional Direct { type } or Program { caller_id, type } or null

产生此工具调用的执行上下文。

• Direct object { type }

• type: "direct" (default: "direct")

• "direct"

• Program object { caller_id, type }

• caller_id: string

产生此工具调用的 program 条目的调用 ID。

• type: "program" (default: "program")

• "program"

• namespace: optional string

被调用的自定义工具所属的命名空间。

• CustomToolCallOutput object { call_id, output, type, 2 more }

自有代码生成、回传给模型的自定义工具调用输出。

• call_id: string

调用 ID，用于将此自定义工具调用输出映射到自定义工具调用。

• output: string or array of ResponseInputText or ResponseInputImage or ResponseInputFile

自有代码生成的自定义工具调用输出。 可以是字符串或输出内容列表。

• StringOutput = string

自定义工具调用输出的字符串。

• OutputContentList = array of ResponseInputText or ResponseInputImage or ResponseInputFile

自定义工具调用的文本、图像或文件输出。

• ResponseInputText object { text, type, prompt_cache_breakpoint }

输入模型的文本。

• ResponseInputImage object { detail, type, file_id, 2 more }

输入模型的图像。参阅图像输入。

• ResponseInputFile object { type, detail, file_data, 4 more }

输入模型的文件。

• type: "custom_tool_call_output"

类型，固定为 custom_tool_call_output。

• "custom_tool_call_output"

• id: optional string

自定义工具调用输出在 OpenAI 平台中的唯一 ID。

• caller: optional Direct { type } or Program { caller_id, type } or null

产生此工具调用的执行上下文。

• Direct object { type }

• type: "direct" (default: "direct")

调用方类型，固定为 direct。

• "direct"

• Program object { caller_id, type }

• caller_id: string

产生此工具调用的 program 条目的调用 ID。

minLength: 1, maxLength: 64

• type: "program" (default: "program")

调用方类型，固定为 program。

• "program"

• first_id: string

列表中第一个条目的 ID。

• has_more: boolean

是否还有更多可用条目。

• last_id: string

列表中最后一个条目的 ID。

• object: "list"

返回对象的类型，须为 list。

• "list"

示例

## 设置 OPENAI_API_KEY，并按接口替换对话 ID、条目 ID 和请求数据。
curl https://api.openai.com/v1/conversations/$CONVERSATION_ID/items \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{}'

200 响应示例

{
  "data": [
    {
      "id": "id",
      "content": [
        {
          "text": "text",
          "type": "input_text",
          "prompt_cache_breakpoint": {
            "mode": "explicit",
            "ttl": "30m"
          }
        }
      ],
      "role": "unknown",
      "status": "in_progress",
      "type": "message",
      "phase": "commentary"
    }
  ],
  "first_id": "first_id",
  "has_more": true,
  "last_id": "last_id",
  "object": "list"
}

示例

## 设置 OPENAI_API_KEY，并按接口替换对话 ID、条目 ID 和请求数据。
curl https://api.openai.com/v1/conversations/conv_123/items \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "items": [
      {
        "type": "message",
        "role": "user",
        "content": [
          {"type": "input_text", "text": "你好！"}
        ]
      },
      {
        "type": "message",
        "role": "user",
        "content": [
          {"type": "input_text", "text": "你好吗？"}
        ]
      }
    ]
  }'

响应示例

{
  "object": "list",
  "data": [
    {
      "type": "message",
      "id": "msg_abc",
      "status": "completed",
      "role": "user",
      "content": [
        {"type": "input_text", "text": "你好！"}
      ]
    },
    {
      "type": "message",
      "id": "msg_def",
      "status": "completed",
      "role": "user",
      "content": [
        {"type": "input_text", "text": "你好吗？"}
      ]
    }
  ],
  "first_id": "msg_abc",
  "last_id": "msg_def",
  "has_more": false
}