OpenAI 检索响应

示例说明：自然语言已作中文本地化；日期、故事内容和词元统计沿用官方演示背景，不代表当前新闻事实或中文输入的实测计数。协议标识、加密数据及词元概率演示所需的数据保持原样。

获取模型响应

get /responses/{response_id}

检索指定 ID 的模型响应。

路径参数

• response_id: string

要检索的响应 ID。

查询参数

• include: optional array of ResponseIncludable

响应中需要包含的额外字段。更多信息请参阅 参数，了解详情。

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

• include_obfuscation: optional boolean

为 true 时启用流混淆。流混淆会在流式增量事件的 obfuscation 在流式增量事件的 obfuscation 字段中添加随机字符， 使载荷大小趋于一致，从而缓解某些侧信道 攻击。这些混淆字段默认包含在事件中，但会给 数据流带来少量开销。如果信任应用与 OpenAI API 之间的网络连接，可以将 include_obfuscation 设为 false， 以优化带宽使用。

• starting_after: optional integer

从哪个事件之后开始流式传输，该事件的序列号。

• stream: optional false

设为 true 时，模型响应数据会在生成过程中通过 服务器发送事件（SSE）流式发送给客户端。 请参阅下方的流式输出部分。 中的说明。

• false

返回值

• Response object { id, access_programs, created_at, 36 more }

• id: string

此响应的唯一标识符。

• access_programs: object { cyber } or null

• cyber: "standard" or "daybreak_blue" or "daybreak_red"

此响应实际使用的 Cyber 访问计划。

• "standard"

• "daybreak_blue"

• "daybreak_red"

• created_at: number

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

format: unixtime

• error: ResponseError or null

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

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

此响应的错误代码。

• "server_error"

• "rate_limit_exceeded"

• "invalid_prompt"

• "data_residency_mismatch"

• "bio_policy"

• "misalignment_policy_violation"

• "vector_store_timeout"

• "invalid_image"

• "invalid_image_format"

• "invalid_base64_image"

• "invalid_image_url"

• "image_too_large"

• "image_too_small"

• "image_parse_error"

• "image_content_policy_violation"

• "invalid_image_mode"

• "image_file_too_large"

• "unsupported_image_media_type"

• "empty_image_file"

• "failed_to_download_image"

• "image_file_not_found"

• message: string

便于人阅读的错误说明。

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

• detailed_explanation: optional string

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

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

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

• string

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

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

• "potentially_unintended_data_transfer"

• "potentially_unintended_data_access"

• "potentially_unintended_destructive_activity"

• "other"

• review_target: optional string or null

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

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

• steer: optional object { message }

可选的公开继续指令。

• message: string

公开的继续指令。

• param: optional string or null

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

• type: optional string or null

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

• incomplete_details: object { reason } or null

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

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

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

• "max_output_tokens"

• "max_messages"

• "content_filter"

• "steered"

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

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

与 previous_response_id 一起使用时，上一个响应中的指令 不会沿用到下一个响应。这使得在新响应中 更换系统消息或开发者消息更为方便。

• string

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

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

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

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

• metadata: Metadata or null

可附加到对象的元数据，最多包含 16 组键值对，可 以结构化方式存储对象的额外信息， 并通过 API 或控制台查询对象。

键为最多 64 个字符的字符串，值为 最多 512 个字符的字符串。

• model: ResponsesModel

用于生成响应的模型 ID，例如 gpt-6-astra。OpenAI 提供多种模型，其能力、性能 特点及价格各不相同。可通过模型指南 浏览并比较可用模型。

• string

• "gpt-6-astra" or "gpt-6.1-sol" or "gpt-6.1-terra" or 87 more

• "gpt-6-astra"

• "gpt-6.1-sol"

• "gpt-6.1-terra"

• "gpt-6-sol"

• "gpt-6-luna"

• "gpt-5.6-sol"

• "gpt-5.6-terra"

• "gpt-5.6-luna"

• "gpt-5.5"

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

• "gpt-5.4"

• "gpt-5.4-mini"

• "gpt-5.4-nano"

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

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

• "gpt-5.3-chat-latest"

• "gpt-5.2"

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

• "gpt-5.2-chat-latest"

• "gpt-5.2-pro"

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

• "gpt-5.1"

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

• "gpt-5.1-codex"

• "gpt-5.1-mini"

• "gpt-5.1-chat-latest"

• "gpt-5"

• "gpt-5-mini"

• "gpt-5-nano"

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

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

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

• "gpt-5-chat-latest"

• "gpt-4.1"

• "gpt-4.1-mini"

• "gpt-4.1-nano"

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

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

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

• "o4-mini"

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

• "o3"

• "o3-2025-04-16"

• "o3-mini"

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

• "o1"

• "o1-2024-12-17"

• "o1-preview"

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

• "o1-mini"

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

• "gpt-4o"

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

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

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

• "gpt-audio-mini"

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

• "gpt-4o-audio-preview"

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

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

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

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

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

• "gpt-4o-search-preview"

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

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

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

• "chatgpt-4o-latest"

• "codex-mini-latest"

• "gpt-4o-mini"

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

• "gpt-4-turbo"

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

• "gpt-4-0125-preview"

• "gpt-4-turbo-preview"

• "gpt-4-1106-preview"

• "gpt-4-vision-preview"

• "gpt-4"

• "gpt-4-0314"

• "gpt-4-0613"

• "gpt-4-32k"

• "gpt-4-32k-0314"

• "gpt-4-32k-0613"

• "gpt-3.5-turbo"

• "gpt-3.5-turbo-16k"

• "gpt-3.5-turbo-0301"

• "gpt-3.5-turbo-0613"

• "gpt-3.5-turbo-1106"

• "gpt-3.5-turbo-0125"

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

• ResponsesOnlyModel = "o1-pro" or "o1-pro-2025-03-19" or "o3-pro" or 19 more

• "o1-pro"

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

• "o3-pro"

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

• "o3-deep-research"

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

• "o4-mini-deep-research"

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

• "computer-use-preview"

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

• "gpt-5.5-pro"

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

• "gpt-5-codex"

• "gpt-5-pro"

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

• "gpt-5.1-codex-max"

• "gpt-daybreak-blue-latest"

• "gpt-daybreak-red-latest"

• "gpt-5.6-cyber"

• "gpt-6-cyber"

• "gpt-rosalind-research"

• "gpt-6-rosalind"

• object: "response"

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

• "response"

• output: array of ResponseOutputItem

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

• output 数组中条目的数量和顺序取决于 模型的响应。
• 与其访问 output 数组中的第一个条目， 并假定它是包含模型生成内容的 assistant 消息， 不如考虑使用 SDK 中受支持的 output_text 属性。

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

模型输出的消息。

• 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

从文件中检索出的文本。

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

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

• 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

• 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

单击操作。

• actions: optional ComputerActionList

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

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

• id: string

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

• call_id: string

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

• output: ResponseComputerToolCallOutputScreenshot

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

• 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

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

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

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

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

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

• 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

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

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

• 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

工具调用的错误，如有。

• output: optional string or null

工具调用的输出。

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

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

• "in_progress"

• "completed"

• "incomplete"

• "calling"

• "failed"

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

决定的可选理由。

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

• id: string

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

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

输入模型的文件。

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

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

• "in_progress"

• "completed"

• "incomplete"

• type: "custom_tool_call_output"

类型，固定为 custom_tool_call_output。

• "custom_tool_call_output"

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

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

• Direct object { type }

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

调用方类型，固定为 direct。

• "direct"

• Program object { caller_id, type }

• caller_id: string

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

minLength: 1, maxLength: 64

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

调用方类型，固定为 program。

• "program"

• created_by: optional string

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

• parallel_tool_calls: boolean (default: true)

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

• temperature: number or null (default: 1)

模型采样温度，范围为 0–2。0.8 等较高值使输出更随机，0.2 等较低值使输出更集中、更具确定性。 通常建议只调整此项或 top_p 中的一项，不同时调整两者。

minimum: 0, maximum: 2

• tool_choice: ToolChoiceOptions or ToolChoiceAllowed or ToolChoiceTypes or 6 more

模型在生成响应时应如何选择要使用的工具。 如需指定模型可以调用哪些工具， 请参阅 tools 参数。

• ToolChoiceOptions = "none" or "auto" or "required"

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

none 表示模型不调用工具，而是生成消息。

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

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

• "none"

• "auto"

• "required"

• ToolChoiceAllowed object { mode, tools, type }

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

• mode: "auto" or "required"

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

auto 允许模型从允许的工具中选择，并生成 消息。

required 要求模型调用一个或多个允许的工具。

• "auto"

• "required"

• tools: array of map[unknown]

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

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

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

• type: "allowed_tools"

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

• "allowed_tools"

• ToolChoiceTypes object { type }

表示模型应使用内置工具生成响应。 了解内置工具。

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

模型应使用的托管工具类型。有关以下内容的详情， 内置工具。

允许的值为：

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

• "file_search"

• "web_search_preview"

• "computer"

• "computer_use_preview"

• "computer_use"

• "web_search_preview_2025_03_11"

• "image_generation"

• "code_interpreter"

• ToolChoiceFunction object { name, type }

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

• name: string

要调用的函数名称。

• type: "function"

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

• "function"

• ToolChoiceMcp object { server_label, type, name }

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

• server_label: string

要使用的 MCP 服务器标签。

• type: "mcp"

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

• "mcp"

• name: optional string or null

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

• ToolChoiceCustom object { name, type }

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

• name: string

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

• type: "custom"

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

• "custom"

• SpecificProgrammaticToolCallingParam object { type }

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

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

• "programmatic_tool_calling"

• ToolChoiceApplyPatch object { type }

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

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

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

• "apply_patch"

• ToolChoiceShell object { type }

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

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

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

• "shell"

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

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

支持以下几类工具：

• 内置工具：由 OpenAI 提供，用于扩展 模型能力，例如网页搜索 或文件搜索。更多信息参阅 内置工具。
• MCP 工具：通过自定义 MCP 服务器，或 Google Drive、SharePoint 等预定义连接器，与第三方系统集成。有关详情， 可参阅 MCP 工具。
• 函数调用（自定义工具）：由你定义的函数， 让模型使用具有明确类型的参数和输出调用你自己的代码。 有关详情， 请参阅函数调用。也可以使用 自定义工具调用你自己的代码。

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

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

• name: string

要调用的函数名称。

• parameters: map[unknown] or null

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

• strict: boolean or null

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

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

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

• "function"

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

工具调用的上下文。

• "direct"

• "programmatic"

• async: optional boolean

• defer_loading: optional boolean

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

• description: optional string or null

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

• output_schema: optional map[unknown] or null

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

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

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

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

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

• "file_search"

• vector_store_ids: array of string

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

• filters: optional ComparisonFilter 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"

• top_p: number or null (default: 1)

除 temperature 采样之外的另一种方式，称为核采样。 模型考虑累计概率质量达到 top_p 的词元。 例如 0.1 表示仅考虑累计占最高 10% 概率质量 的词元。

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

minimum: 0, maximum: 1

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

是否在后台生成模型响应。 了解详情。

• completed_at: optional number or null

此响应完成时的 Unix 时间戳，单位为秒。 仅在状态为 completed 时存在。

format: unixtime

• conversation: optional object { id } or null

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

• id: string

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

• image: optional object { context_compression }

• context_compression: "enabled" or "disabled"

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

• "enabled"

• "disabled"

• max_output_tokens: optional integer or null

为响应生成的词元数上限，包括可见输出词元和推理词元。

• max_tool_calls: optional integer or null

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

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

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

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

对响应输入的审核。

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

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

• categories: map[boolean]

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

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

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

• "text"

• "image"

• category_scores: map[number]

审核类别到分数的映射。

• flagged: boolean

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

• model: string

生成此结果的审核模型。

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

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

• "moderation_result"

• Error object { code, message, type }

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

• code: string

错误代码。

• message: string

错误消息。

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

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

• "error"

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

对响应输出的审核。

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

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

• categories: map[boolean]

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

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

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

• "text"

• "image"

• category_scores: map[number]

审核类别到分数的映射。

• flagged: boolean

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

• model: string

生成此结果的审核模型。

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

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

• "moderation_result"

• Error object { code, message, type }

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

• code: string

错误代码。

• message: string

错误消息。

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

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

• "error"

• output_text: optional string or null

仅在 SDK 中提供的便捷属性，汇总 output 数组中 所有 output_text 条目的文本输出（如有）。 Python 和 JavaScript SDK 支持此属性。

• previous_response_id: optional string or null

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

• prompt: optional ResponsePrompt or null

对提示词模板及其变量的引用。 了解更多。

• id: string

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

• variables: optional map[string or ResponseInputText or ResponseInputImage or ResponseInputFile] or null

可选的值映射，用于替换提示词中的 变量。替换值可以是字符串，也可以是其他 Responses 输入类型，例如图像或文件。

• string

• ResponseInputText object { text, type, prompt_cache_breakpoint }

输入模型的文本。

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

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

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

输入模型的文件。

• version: optional string or null

提示词模板的可选版本。

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

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

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

• cache_missed_tokens: integer

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

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

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

• "model_changed"

• "prompt_cache_key_changed"

• "tools_changed"

• "text_format_changed"

• "reasoning_effort_changed"

• "verbosity_changed"

• "context_compacted"

• "input_changed"

• "service_tier_changed"

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

• "cache_miss"

• comparison_reusable_tokens: optional integer

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

• CacheHit object { type }

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

• "cache_hit"

• ComparisonResponseNotFound object { type }

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

• "comparison_response_not_found"

• Unavailable object { type }

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

• "unavailable"

• prompt_cache_key: optional string or null

OpenAI 用于缓存类似请求的响应，以优化缓存命中率。替代 user 字段。了解更多。

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

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

• mode: "implicit" or "explicit"

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

• "implicit"

• "explicit"

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

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

• "30m"

• "12h"

• comparison_response_id: optional string or null

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

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

已弃用，改用 prompt_cache_options.ttl。

提示词缓存的保留策略。设为 24h 可启用扩展提示词缓存，使缓存前缀保持活动更久，最长 24 小时。了解更多。 此字段表示最大保留策略，而 prompt_cache_options.ttl 表示最短缓存存续时间。两者 相互独立，不发生交互。 对于 gpt-5.5、gpt-5.5-pro 及未来模型，仅支持 24h。

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

• 未启用 ZDR 的组织默认为 24h。
• 启用 ZDR 的组织在未指定 prompt_cache_retention 时默认为 in_memory。

• "in_memory"

• "24h"

• reasoning: optional Reasoning or null

以下对象的配置选项： 推理模型。

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

控制在后续轮次中将哪些推理条目重新提供给模型。 省略此字段或设为 auto 时，由模型确定上下文模式。 gpt-5.6 模型家族默认为 all_turns；更早的模型默认为 current_turn.

当此字段出现在返回的响应中时，表示该响应 实际使用的推理上下文模式。

• "auto"

• "current_turn"

• "all_turns"

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

限制推理模型的推理强度。当前支持 none、minimal、low、medium、high、xhigh 和 max。 降低推理强度可能加快响应，并减少响应中用于 推理的词元数。并非所有推理模型都支持每个 取值。各模型的支持情况请参阅 推理指南 中的说明。

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

已弃用：请改用 summary。

模型推理过程的摘要，可用于 调试和理解模型的推理过程。 可选值为 auto、concise 或 detailed。

• "auto"

• "concise"

• "detailed"

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

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

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

• string

• "standard" or "pro"

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

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

• "standard"

• "pro"

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

模型推理过程的摘要，可用于 调试和理解模型的推理过程。 可选值为 auto、concise 或 detailed。

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

• "auto"

• "concise"

• "detailed"

• safety_identifier: optional string or null

稳定的标识，用于检测可能违反 OpenAI 使用政策的应用用户。 ID 应为唯一标识每位用户的字符串，最长 128 个字符。建议对用户名或邮箱地址进行哈希处理，避免发送可识别身份的信息。了解更多。

maxLength: 128

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

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

• 设为 'auto' 时，按项目设置的服务层级处理请求。未另行配置时，项目使用 'default'。
• 设为 'default' 时，使用所选模型的标准价格和性能处理请求。
• 设为 'flex' 时，使用 Flex Processing 服务层级处理请求。
• 在请求级别启用快速模式，可在 Responses 或 Chat Completions 请求中传入 service_tier=fast 或 service_tier=priority。无论请求中使用哪一种值，响应均显示 service_tier=priority。
• 设为 'ultrafast' 时，通过受访问控制的 Ultrafast Processing 服务层级处理请求。此层级目前适用于 gpt-5.6-sol；通过该层级提供服务的响应会显示 service_tier=ultrafast。
• 未设置时，默认按 'auto' 处理。

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

• "auto"

• "default"

• "flex"

• "scale"

• "priority"

• "fast"

• "ultrafast"

• status: optional ResponseStatus

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

• "completed"

• "failed"

• "in_progress"

• "cancelled"

• "queued"

• "incomplete"

• text: optional ResponseTextConfig

模型文本响应的配置选项，可以是纯 文本或结构化 JSON 数据。更多信息：

• 文本输入与输出
• 结构化输出

• format: optional ResponseFormatTextConfig

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

配置 { "type": "json_schema" } 会启用结构化输出， 确保模型遵循你提供的 JSON Schema。更多信息参阅 结构化输出指南。

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

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

设为 { "type": "json_object" } 会启用旧版 JSON 模式， 确保模型生成有效的 JSON。对于支持的模型，优先使用 json_schema 格式。

• ResponseFormatText object { type }

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

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

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

• ResponseFormatJSONObject object { type }

JSON 对象响应格式，是生成 JSON 响应的较早方式。 对于支持的模型，建议使用 json_schema。注意： 须在系统消息或用户消息中指示模型生成 JSON， 模型才会生成 JSON。

• type: "json_object"

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

• "json_object"

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

限制模型响应的详细程度。较低值会生成 更简洁的响应，较高值会生成更详细的响应。 当前支持 low、medium 和 high，默认值为 medium.

• "low"

• "medium"

• "high"

• tool_usage: optional object { image_gen, web_search }

托管工具报告的用量，与基础模型的 usage 分开统计。 工具用量不可用时可省略此字段。存在此字段时， 没有记录到用量的工具类别计数为零。

image_gen 汇总图像生成调用中可获得的词元计数。 用量记录缺失或不完整的调用可能被跳过。输出词元明细 和缓存输入计数可以省略。缓存计数缺失 表示缓存用量未知。

web_search.num_requests 统计需要计费的搜索。不包括享受折扣的搜索 和打开页面等操作。最终费用应以 账单记录核对为准。

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

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

• input_tokens: integer

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

• input_tokens_details: object { image_tokens, text_tokens }

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

• image_tokens: integer

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

• text_tokens: integer

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

• output_tokens: integer

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

• total_tokens: integer

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

• cached_tokens: optional integer

• cached_tokens_details: optional object { cached_image_tokens, cached_text_tokens }

• cached_image_tokens: integer

• cached_text_tokens: integer

• output_tokens_details: optional object { image_tokens, text_tokens }

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

• image_tokens: integer

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

• text_tokens: integer

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

• web_search: object { num_requests }

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

• num_requests: integer

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

• top_logprobs: optional integer or null

数值为 0–20 的整数，指定每个词元位置最多返回 多少个最可能的词元，每个词元附带其对数 概率。某些情况下，返回数量可能少于 请求数量。

minimum: 0, maximum: 20

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

模型响应的截断策略。

• auto：如果此响应的输入超出 模型的上下文窗口，模型会从对话开头丢弃条目， 将响应截断到上下文窗口容许的范围内。 对于某些模型，截断可能更早开始，因为即使设置了较小的 max_output_tokens， API 仍会从输入上限中减去模型允许的最大输出量。
• disabled（默认值）：如果输入超出模型的上下文窗口， 请求会失败并返回 400 错误。

• "auto"

• "disabled"

• usage: optional ResponseUsage or null

词元用量明细，包括输入词元、输出词元、 输出词元明细和词元总数。

• input_tokens: integer

输入词元数量。

• input_tokens_details: object { cache_write_tokens, cached_tokens, cache_write_tokens_details }

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

• cache_write_tokens: integer

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

• cached_tokens: integer

从缓存中读取的词元数量。 了解提示词缓存。

• cache_write_tokens_details: optional object { ttl_12h_tokens, ttl_30m_tokens }

• ttl_12h_tokens: integer

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

• ttl_30m_tokens: integer

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

• output_tokens: integer

输出词元数量。

• output_tokens_details: object { reasoning_tokens }

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

• reasoning_tokens: integer

推理词元数量。

• total_tokens: integer

使用的总词元数。

• user: optional string or null

此字段正被 safety_identifier 和 prompt_cache_key 替代。使用 prompt_cache_key 保持缓存优化。 最终用户的稳定标识。 通过更好地对类似请求分组，提高缓存命中率，并帮助 OpenAI 检测与防止滥用。了解更多。

示例

## 从环境变量读取 API 密钥；按实际请求替换模型、输入或响应 ID。
curl https://api.openai.com/v1/responses/$RESPONSE_ID \
    -H "Authorization: Bearer $OPENAI_API_KEY"

200 响应示例

{
  "id": "resp_67ccd3a9da748190baa7f1570fe91ac604becb25c45c1d41",
  "object": "response",
  "access_programs": null,
  "created_at": 1741476777,
  "status": "completed",
  "completed_at": 1741476778,
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "model": "gpt-6-astra",
  "output": [
    {
      "type": "message",
      "id": "msg_67ccd3acc8d48190a77525dc6de64b4104becb25c45c1d41",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "图中是一处风景：木制栈道或小径穿过茂密的绿草，天空湛蓝，飘着几朵云。这里看起来是一片宁静的自然区域，可能是公园或自然保护区，背景中有树木和灌木。",
          "annotations": [],
          "logprobs": []
        }
      ]
    }
  ],
  "parallel_tool_calls": true,
  "previous_response_id": null,
  "reasoning": {
    "effort": null,
    "summary": null,
    "context": null
  },
  "store": true,
  "temperature": 1,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [],
  "top_p": 1,
  "truncation": "disabled",
  "usage": {
    "input_tokens": 328,
    "input_tokens_details": {
      "cached_tokens": 0,
      "cache_write_tokens": 0
    },
    "output_tokens": 52,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 380
  },
  "tool_usage": {
    "image_gen": {
      "input_tokens": 0,
      "input_tokens_details": {
        "text_tokens": 0,
        "image_tokens": 0
      },
      "output_tokens": 0,
      "output_tokens_details": {
        "text_tokens": 0,
        "image_tokens": 0
      },
      "total_tokens": 0
    },
    "web_search": {
      "num_requests": 0
    }
  },
  "user": null,
  "metadata": {},
  "conversation": {
    "id": "id"
  },
  "image": {
    "context_compression": "enabled"
  },
  "moderation": {
    "input": {
      "categories": {
        "foo": true
      },
      "category_applied_input_types": {
        "foo": [
          "text"
        ]
      },
      "category_scores": {
        "foo": 0
      },
      "flagged": true,
      "model": "model",
      "type": "moderation_result"
    },
    "output": {
      "categories": {
        "foo": true
      },
      "category_applied_input_types": {
        "foo": [
          "text"
        ]
      },
      "category_scores": {
        "foo": 0
      },
      "flagged": true,
      "model": "model",
      "type": "moderation_result"
    }
  },
  "output_text": "output_text",
  "prompt_cache_diagnostics": {
    "cache_missed_tokens": 0,
    "reason": "model_changed",
    "type": "cache_miss",
    "comparison_reusable_tokens": 0
  },
  "prompt_cache_options": {
    "mode": "implicit",
    "ttl": "30m",
    "comparison_response_id": "comparison_response_id"
  },
  "service_tier": "auto"
}

示例

## 从环境变量读取 API 密钥；按实际请求替换模型、输入或响应 ID。
curl https://api.openai.com/v1/responses/resp_123 \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY"

响应示例

{
  "id": "resp_67cb71b351908190a308f3859487620d06981a8637e6bc44",
  "object": "response",
  "access_programs": null,
  "created_at": 1741386163,
  "status": "completed",
  "completed_at": 1741386164,
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "model": "gpt-6-astra",
  "output": [
    {
      "type": "message",
      "id": "msg_67cb71b3c2b0819084d481baaaf148f206981a8637e6bc44",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "寂静的电路低吟，\n思绪从数据流中涌现——\n数字世界迎来黎明。",
          "annotations": [],
          "logprobs": []
        }
      ]
    }
  ],
  "parallel_tool_calls": true,
  "previous_response_id": null,
  "reasoning": {
    "effort": null,
    "summary": null
  },
  "store": true,
  "temperature": 1.0,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [],
  "top_p": 1.0,
  "truncation": "disabled",
  "usage": {
    "input_tokens": 32,
    "input_tokens_details": {
      "cached_tokens": 0,
      "cache_write_tokens": 0
    },
    "output_tokens": 18,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 50
  },
  "user": null,
  "metadata": {}
}