OpenAI 压缩多智能体对话
压缩对话
post /responses/compact?beta=true
压缩对话,返回压缩后的响应对象。
关于何时及如何压缩持续运行的长对话,请参阅对话状态指南。关于与 ZDR 兼容的压缩,请参阅高级压缩。
请求头参数
"openai-beta": optional array of "responses_multi_agent=v1"
"responses_multi_agent=v1"
请求体参数
内容类型为 application/json。
model: "gpt-6-astra" or "gpt-6.2-astra" or "gpt-6.1-sol" or 112 more or string or null
用于生成响应的模型 ID,例如 gpt-6-astra。OpenAI 提供能力、性能特点和价格各异的多种模型。请参阅模型指南,浏览和比较可用模型。
"gpt-6-astra" or "gpt-6.2-astra" or "gpt-6.1-sol" or 112 more
用于生成响应的模型 ID,例如 gpt-6-astra。OpenAI 提供能力、性能特点和价格各异的多种模型。请参阅模型指南,浏览和比较可用模型。
"gpt-6-astra"
"gpt-6.2-astra"
"gpt-6.1-sol"
"gpt-6.2-sol"
"gpt-6.1-terra"
"gpt-6-sol"
"gpt-6-luna"
"gpt-5.6-sol"
"gpt-5.6-terra"
"gpt-5.6-luna"
"gpt-5.5"
"gpt-5.5-2026-04-23"
"gpt-5.4"
"gpt-5.4-mini"
"gpt-5.4-nano"
"gpt-5.4-mini-2026-03-17"
"gpt-5.4-nano-2026-03-17"
"gpt-5.3-chat-latest"
"gpt-5.2"
"gpt-5.2-2025-12-11"
"gpt-5.2-chat-latest"
"gpt-5.2-pro"
"gpt-5.2-pro-2025-12-11"
"gpt-5.1"
"gpt-5.1-2025-11-13"
"gpt-5.1-codex"
"gpt-5.1-mini"
"gpt-5.1-chat-latest"
"gpt-5"
"gpt-5-mini"
"gpt-5-nano"
"gpt-5-2025-08-07"
"gpt-5-mini-2025-08-07"
"gpt-5-nano-2025-08-07"
"gpt-5-chat-latest"
"gpt-4.1"
"gpt-4.1-mini"
"gpt-4.1-nano"
"gpt-4.1-2025-04-14"
"gpt-4.1-mini-2025-04-14"
"gpt-4.1-nano-2025-04-14"
"o4-mini"
"o4-mini-2025-04-16"
"o3"
"o3-2025-04-16"
"o3-mini"
"o3-mini-2025-01-31"
"o1"
"o1-2024-12-17"
"o1-preview"
"o1-preview-2024-09-12"
"o1-mini"
"o1-mini-2024-09-12"
"gpt-4o"
"gpt-4o-2024-11-20"
"gpt-4o-2024-08-06"
"gpt-4o-2024-05-13"
"gpt-audio-mini"
"gpt-audio-mini-2025-12-15"
"gpt-4o-audio-preview"
"gpt-4o-audio-preview-2024-10-01"
"gpt-4o-audio-preview-2024-12-17"
"gpt-4o-audio-preview-2025-06-03"
"gpt-4o-mini-audio-preview"
"gpt-4o-mini-audio-preview-2024-12-17"
"gpt-4o-search-preview"
"gpt-4o-mini-search-preview"
"gpt-4o-search-preview-2025-03-11"
"gpt-4o-mini-search-preview-2025-03-11"
"chatgpt-4o-latest"
"codex-mini-latest"
"gpt-4o-mini"
"gpt-4o-mini-2024-07-18"
"gpt-4-turbo"
"gpt-4-turbo-2024-04-09"
"gpt-4-0125-preview"
"gpt-4-turbo-preview"
"gpt-4-1106-preview"
"gpt-4-vision-preview"
"gpt-4"
"gpt-4-0314"
"gpt-4-0613"
"gpt-4-32k"
"gpt-4-32k-0314"
"gpt-4-32k-0613"
"gpt-3.5-turbo"
"gpt-3.5-turbo-16k"
"gpt-3.5-turbo-0301"
"gpt-3.5-turbo-0613"
"gpt-3.5-turbo-1106"
"gpt-3.5-turbo-0125"
"gpt-3.5-turbo-16k-0613"
"o1-pro"
"o1-pro-2025-03-19"
"o3-pro"
"o3-pro-2025-06-10"
"o3-deep-research"
"o3-deep-research-2025-06-26"
"o4-mini-deep-research"
"o4-mini-deep-research-2025-06-26"
"computer-use-preview"
"computer-use-preview-2025-03-11"
"gpt-5.5-pro"
"gpt-5.5-pro-2026-04-23"
"gpt-5-codex"
"gpt-5-pro"
"gpt-5-pro-2025-10-06"
"gpt-5.1-codex-max"
"gpt-daybreak-blue-latest"
"gpt-daybreak-red-latest"
"gpt-5.6-cyber"
"gpt-6-cyber"
"gpt-rosalind-research"
"gpt-6-rosalind"
"gpt-6.2-astra-law"
string
image: optional object { context_compression }
请求级别的图像选项。
context_compression: optional "auto" or "enabled" or "disabled"
控制图像上下文优化。默认为 auto,根据模型、传输方式和输入选择策略。设为 enabled 可要求支持压缩,设为 disabled 可关闭此功能。
"auto"
"enabled"
"disabled"
input: optional string or array of BetaEasyInputMessage or Message { content, role, agent, 2 more } or BetaResponseOutputMessage or 33 more or null
提供给模型的文本、图像或文件输入,用于生成响应。
string
提供给模型的文本输入,等同于角色为 user 的文本输入。
maxLength: 10485760
array of BetaEasyInputMessage or Message { content, role, agent, 2 more } or BetaResponseOutputMessage or 33 more
提供给模型的一个或多个输入条目组成的列表,其中可以包含不同类型的内容。
maxItems: 131072
BetaEasyInputMessage object { content, role, phase, type }
提供给模型的消息输入,角色表示指令遵循层级。developer或system指令优先于user指令;assistant消息被视为模型在先前交互中生成的消息。
content: string or BetaResponseInputMessageContentList
用于生成响应的文本、图像或音频输入,也可包含先前助手的响应。
TextInput = string
输入模型的文本。
BetaResponseInputMessageContentList = array of BetaResponseInputContent
提供给模型的一个或多个输入条目组成的列表,其中可以包含不同类型的内容。
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
text: string
输入模型的文本。
type: "input_text" (default: "input_text")
输入条目类型,固定为 input_text。
"input_text"
prompt_cache_breakpoint: optional object { mode, ttl }
标记可复用提示词前缀的精确结束位置。省略 ttl 时,断点继承请求中的 prompt_cache_options.ttl;该边界不会按词元块取整。
mode: "explicit" (default: "explicit")
断点模式,固定为 explicit。
"explicit"
ttl: optional "30m" or "12h"
此缓存断点的最短存续时间,默认为请求的 TTL。
"30m"
"12h"
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
detail: BetaImageDetail
发送给模型的图像细节级别,可选 high、low、auto 或 original,默认为 auto。
"low"
"high"
"auto"
"original"
type: "input_image" (default: "input_image")
输入条目类型,固定为 input_image。
"input_image"
file_id: optional string or null
要发送给模型的文件 ID。
image_url: optional string or null
要发送给模型的图像 URL,可以是完整 URL,或包含 Base64 编码图像的 data URL。
format: uri
prompt_cache_breakpoint: optional object { mode, ttl }
标记可复用提示词前缀的精确结束位置。省略 ttl 时,断点继承请求中的 prompt_cache_options.ttl;该边界不会按词元块取整。
mode: "explicit" (default: "explicit")
断点模式,固定为 explicit。
"explicit"
ttl: optional "30m" or "12h"
此缓存断点的最短存续时间,默认为请求的 TTL。
"30m"
"12h"
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
type: "input_file" (default: "input_file")
输入条目类型,固定为 input_file。
"input_file"
detail: optional "auto" or "low" or "high"
发送给模型的文件细节级别。使用 auto 由系统选择;对于 GPT-5.6 及后续模型,auto 使用高质量渲染,可能增加输入词元用量。使用 low 进行成本较低的渲染,或使用 high 以更高质量渲染文件。默认为 auto。
"auto"
"low"
"high"
file_data: optional string
要发送给模型的文件内容。
file_id: optional string or null
要发送给模型的文件 ID。
file_url: optional string
要发送给模型的文件 URL。
format: uri
filename: optional string
要发送给模型的文件名。
prompt_cache_breakpoint: optional object { mode, ttl }
标记可复用提示词前缀的精确结束位置。省略 ttl 时,断点继承请求中的 prompt_cache_options.ttl;该边界不会按词元块取整。
mode: "explicit" (default: "explicit")
断点模式,固定为 explicit。
"explicit"
ttl: optional "30m" or "12h"
此缓存断点的最短存续时间,默认为请求的 TTL。
"30m"
"12h"
role: "user" or "assistant" or "system" or "developer"
消息输入角色,可选user、assistant、system或developer。
"user"
"assistant"
"system"
"developer"
phase: optional "commentary" or "final_answer" or null
将 assistant 消息标记为中间说明(commentary)或最终答案(final_answer)。对于 gpt-5.3-codex 及后续此类模型,发送后续请求时须保留并重新发送所有助手消息的 phase,丢弃它可能降低表现。用户消息不使用此字段。
"commentary"
"final_answer"
type: optional "message"
输入消息类型,固定为 message。
"message"
Message object { content, role, agent, 2 more }
提供给模型的消息输入,角色表示指令遵循层级;developer或system指令优先于user指令。
content: BetaResponseInputMessageContentList
提供给模型的一个或多个输入条目组成的列表,其中可以包含不同类型的内容。
role: "user" or "system" or "developer"
输入消息角色,可选 user、system 或 developer。
"user"
"system"
"developer"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
status: optional "in_progress" or "completed" or "incomplete"
条目状态,可选 in_progress、completed 或 incomplete,通过 API 返回条目时填充。
"in_progress"
"completed"
"incomplete"
type: optional "message"
输入消息类型,固定为 message。
"message"
BetaResponseOutputMessage object { id, content, role, 4 more }
模型输出的消息。
id: string
输出消息的唯一 ID。
content: array of BetaResponseOutputText or BetaResponseOutputRefusal
输出消息的内容。
BetaResponseOutputText object { annotations, logprobs, text, type }
模型输出的文本。
annotations: array of FileCitation { file_id, filename, index, type } or URLCitation { end_index, start_index, title, 2 more } or ContainerFileCitation { container_id, end_index, file_id, 3 more } or FilePath { file_id, index, type }
文本输出的注解。
FileCitation object { file_id, filename, index, type }
文件引用。
file_id: string
文件 ID。
filename: string
被引用文件的文件名。
index: integer
在输出文本中插入文件引用的位置索引。
type: "file_citation" (default: "file_citation")
类型,固定为 file_citation。
"file_citation"
URLCitation object { end_index, start_index, title, 2 more }
对生成模型响应所用网页资源的引用。
end_index: integer
URL 引用在消息中最后一个字符的索引。
start_index: integer
URL 引用在消息中第一个字符的索引。
title: string
网络资源标题。
type: "url_citation" (default: "url_citation")
URL 引用的类型,固定为 url_citation。
"url_citation"
url: string
网络资源 URL。
format: uri
ContainerFileCitation object { container_id, end_index, file_id, 3 more }
对生成模型响应所用容器文件的引用。
container_id: string
容器文件 ID。
end_index: integer
消息中容器文件引用最后一个字符的索引。
file_id: string
文件 ID。
filename: string
被引用容器文件的文件名。
start_index: integer
消息中容器文件引用第一个字符的索引。
type: "container_file_citation" (default: "container_file_citation")
类型,固定为 container_file_citation。
"container_file_citation"
FilePath object { file_id, index, type }
文件路径。
file_id: string
文件 ID。
index: integer
文件在文件列表中的索引。
type: "file_path"
类型,固定为 file_path。
"file_path"
logprobs: array of object { token, bytes, logprob, top_logprobs }
token: string
bytes: array of number
logprob: number
top_logprobs: array of object { token, bytes, logprob }
token: string
bytes: array of number
logprob: number
text: string
模型输出的文本内容。
type: "output_text" (default: "output_text")
输出文本类型,固定为 output_text。
"output_text"
BetaResponseOutputRefusal object { refusal, type }
模型的拒绝响应。
refusal: string
模型给出的拒绝原因。
type: "refusal" (default: "refusal")
类型,固定为 refusal。
"refusal"
role: "assistant"
输出消息角色,固定为 assistant。
"assistant"
status: "in_progress" or "completed" or "incomplete"
输入消息状态,可选 in_progress、completed 或 incomplete,通过 API 返回输入条目时填充。
"in_progress"
"completed"
"incomplete"
type: "message"
类型,固定为 message。
"message"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
phase: optional "commentary" or "final_answer" or null
将 assistant 消息标记为中间说明(commentary)或最终答案(final_answer)。对于 gpt-5.3-codex 及后续此类模型,发送后续请求时须保留并重新发送所有助手消息的 phase,丢弃它可能降低表现。用户消息不使用此字段。
"commentary"
"final_answer"
FileSearchCall object { id, queries, status, 3 more }
文件搜索工具调用的结果,详见文件搜索指南。
id: string
文件搜索工具调用的唯一 ID。
queries: array of string
搜索文件所用的查询。
status: "in_progress" or "searching" or "completed" or 2 more
文件搜索工具调用状态,可选in_progress、searching、incomplete或failed。
"in_progress"
"searching"
"completed"
"incomplete"
"failed"
type: "file_search_call"
类型,固定为 file_search_call。
"file_search_call"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
results: optional array of object { attributes, file_id, filename, 2 more } or null
文件搜索工具调用的结果。
attributes: optional map[string or number or boolean] or null
可附加到对象的一组16个键值对,可用于以结构化格式保存额外信息,并通过API或控制台查询对象。键为最长64个字符的字符串;值可以是最长512个字符的字符串、布尔值或数字。
string
maxLength: 512
number
boolean
file_id: optional string
文件的唯一 ID。
filename: optional string
文件名。
score: optional number
文件相关性分数,范围为 0–1。
format: float
text: optional string
从文件中检索出的文本。
ComputerCall object { id, call_id, pending_safety_checks, 5 more }
对计算机使用工具的调用,详见计算机使用指南。
id: string
计算机工具调用的唯一 ID。
call_id: string
通过输出回应此工具调用时使用的标识。
pending_safety_checks: array of object { id, code, message }
此计算机工具调用待处理的安全检查。
id: string
待处理安全检查的 ID。
code: optional string or null
待处理安全检查的类型。
message: optional string or null
待处理安全检查的详情。
status: "in_progress" or "completed" or "incomplete"
条目状态,可选 in_progress、completed 或 incomplete,通过 API 返回条目时填充。
"in_progress"
"completed"
"incomplete"
type: "computer_call" (default: "computer_call")
类型,固定为 computer_call。
"computer_call"
action: optional BetaComputerAction
单击操作。
Click object { button, type, x, 2 more }
单击操作。
button: "left" or "right" or "wheel" or 2 more
单击时按下的鼠标按钮,可选 left、right、wheel、back 或 forward。
"left"
"right"
"wheel"
"back"
"forward"
type: "click" (default: "click")
指定事件类型。单击操作固定为 click。
"click"
x: integer
单击位置的 x 坐标。
y: integer
单击位置的 y 坐标。
keys: optional array of string or null
单击时保持按下的按键。
DoubleClick object { keys, type, x, y }
双击操作。
keys: array of string or null
双击时保持按下的按键。
type: "double_click" (default: "double_click")
指定事件类型。双击操作固定为 double_click。
"double_click"
x: integer
双击位置的 x 坐标。
y: integer
双击位置的 y 坐标。
Drag object { path, type, keys }
拖动操作。
path: array of object { x, y }
表示拖动路径的坐标数组。坐标以对象数组形式提供,例如
[
{ x: 100, y: 200 },
{ x: 200, y: 300 }
]
x: integer
x 坐标。
y: integer
y 坐标。
type: "drag" (default: "drag")
指定事件类型。拖动操作固定为 drag。
"drag"
keys: optional array of string or null
拖动鼠标时保持按下的按键。
Keypress object { keys, type }
模型希望执行的一组按键操作。
keys: array of string
模型请求按下的按键组合,以字符串数组表示,每个字符串代表一个按键。
type: "keypress" (default: "keypress")
指定事件类型。按键操作固定为 keypress。
"keypress"
Move object { type, x, y, keys }
鼠标移动操作。
type: "move" (default: "move")
指定事件类型。移动操作固定为 move。
"move"
x: integer
移动目标的 x 坐标。
y: integer
移动目标的 y 坐标。
keys: optional array of string or null
移动鼠标时保持按下的按键。
Screenshot object { type }
截屏操作。
type: "screenshot" (default: "screenshot")
指定事件类型。截屏操作固定为 screenshot。
"screenshot"
Scroll object { scroll_x, scroll_y, type, 3 more }
滚动操作。
scroll_x: integer
水平滚动距离。
scroll_y: integer
垂直滚动距离。
type: "scroll" (default: "scroll")
指定事件类型。滚动操作固定为 scroll。
"scroll"
x: integer
滚动位置的 x 坐标。
y: integer
滚动位置的 y 坐标。
keys: optional array of string or null
滚动时保持按下的按键。
Type object { text, type }
输入文本的操作。
text: string
要输入的文本。
type: "type" (default: "type")
指定事件类型。输入操作固定为 type。
"type"
Wait object { type }
等待操作。
type: "wait" (default: "wait")
指定事件类型。等待操作固定为 wait。
"wait"
actions: optional BetaComputerActionList
computer_use的扁平化批量操作。每个操作包含type判别字段及该操作专属字段。
Click object { button, type, x, 2 more }
单击操作。
DoubleClick object { keys, type, x, y }
双击操作。
Drag object { path, type, keys }
拖动操作。
Keypress object { keys, type }
模型希望执行的一组按键操作。
Move object { type, x, y, keys }
鼠标移动操作。
Screenshot object { type }
截屏操作。
Scroll object { scroll_x, scroll_y, type, 3 more }
滚动操作。
Type object { text, type }
输入文本的操作。
Wait object { type }
等待操作。
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
ComputerCallOutput object { call_id, output, type, 4 more }
计算机工具调用的输出。
call_id: string
产生此输出的计算机工具调用的 ID。
minLength: 1, maxLength: 64
output: BetaResponseComputerToolCallOutputScreenshot
供计算机使用工具使用的屏幕截图图像。
type: "computer_screenshot" (default: "computer_screenshot")
指定事件类型。对于计算机屏幕截图,此属性固定为 computer_screenshot。
"computer_screenshot"
file_id: optional string
包含截图的已上传文件的标识。
image_url: optional string
截图图像的 URL。
format: uri
type: "computer_call_output" (default: "computer_call_output")
类型,固定为 computer_call_output。
"computer_call_output"
id: optional string or null
计算机工具调用输出的 ID。
acknowledged_safety_checks: optional array of object { id, code, message } or null
API 报告且开发者已确认的安全检查。
id: string
待处理安全检查的 ID。
code: optional string or null
待处理安全检查的类型。
message: optional string or null
待处理安全检查的详情。
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
status: optional "in_progress" or "completed" or "incomplete" or null
输入消息状态,可选 in_progress、completed 或 incomplete,通过 API 返回输入条目时填充。
"in_progress"
"completed"
"incomplete"
WebSearchCall object { id, status, type, 2 more }
网页搜索工具调用的结果,详见网页搜索指南。
id: string
网页搜索工具调用的唯一 ID。
status: "in_progress" or "searching" or "completed" or 2 more
网页搜索工具调用的状态。
"in_progress"
"searching"
"completed"
"failed"
"incomplete"
type: "web_search_call"
类型,固定为 web_search_call。
"web_search_call"
action: optional Search { type, queries, query, sources } or OpenPage { type, url } or FindInPage { pattern, type, url }
描述此次网页搜索具体操作的对象,包括模型如何使用网页:search、open_page、find_in_page。
Search object { type, queries, query, sources }
操作类型 "search":执行网页搜索查询。
type: "search"
操作类型。
"search"
queries: optional array of string
搜索查询列表。
query: optional string
搜索查询。
sources: optional array of object { type, url }
搜索所用的信息来源。
type: "url"
来源类型,固定为 url。
"url"
url: string
来源 URL。
format: uri
OpenPage object { type, url }
操作类型 "open_page":打开搜索结果中的指定 URL。
type: "open_page"
操作类型。
"open_page"
url: optional string or null
模型打开的 URL。
format: uri
FindInPage object { pattern, type, url }
操作类型 "find_in_page":在已加载页面中搜索模式。
pattern: string
要在页面中搜索的模式或文本。
type: "find_in_page"
操作类型。
"find_in_page"
url: optional string or null
用于搜索模式的页面 URL,如可用。
format: uri
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
FunctionCall object { arguments, call_id, name, 7 more }
执行函数的工具调用,详见函数调用指南。
arguments: string
要传给函数的参数组成的 JSON 字符串。
call_id: string
模型生成的函数工具调用的唯一 ID。
name: string
要运行的函数名称。
type: "function_call"
类型,固定为 function_call。
"function_call"
id: optional string
函数工具调用的唯一 ID。
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
async: optional boolean
函数工具调用是否异步运行。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
namespace: optional string
要运行的函数所属的命名空间。
status: optional "in_progress" or "completed" or "incomplete"
条目状态,可选 in_progress、completed 或 incomplete,通过 API 返回条目时填充。
"in_progress"
"completed"
"incomplete"
FunctionCallOutput object { output, type, id, 6 more }
函数工具调用的输出。
output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent
函数工具调用的文本、图像或文件输出。
string
函数工具调用输出的 JSON 字符串。
maxLength: 10485760
array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent
函数工具调用的内容输出数组,包含文本、图像或文件。
BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }
输入模型的文本。
text: string
输入模型的文本。
maxLength: 10485760
type: "input_text" (default: "input_text")
输入条目类型,固定为 input_text。
"input_text"
prompt_cache_breakpoint: optional object { mode, ttl } or null
标记可复用提示词前缀的精确结束位置。省略 ttl 时,断点继承请求中的 prompt_cache_options.ttl;该边界不会按词元块取整。
mode: "explicit" (default: "explicit")
断点模式,固定为 explicit。
"explicit"
ttl: optional "30m" or "12h"
此缓存断点的最短存续时间,默认为请求的 TTL。
"30m"
"12h"
BetaResponseInputImageContent object { type, detail, file_id, 2 more }
输入模型的图像。参阅图像输入。
type: "input_image" (default: "input_image")
输入条目类型,固定为 input_image。
"input_image"
detail: optional BetaImageDetail or null
发送给模型的图像细节级别,可选 high、low、auto 或 original,默认为 auto。
file_id: optional string or null
要发送给模型的文件 ID。
image_url: optional string or null
要发送给模型的图像 URL,可以是完整 URL,或包含 Base64 编码图像的 data URL。
maxLength: 20971520, format: uri
prompt_cache_breakpoint: optional object { mode, ttl } or null
标记可复用提示词前缀的精确结束位置。省略 ttl 时,断点继承请求中的 prompt_cache_options.ttl;该边界不会按词元块取整。
mode: "explicit" (default: "explicit")
断点模式,固定为 explicit。
"explicit"
ttl: optional "30m" or "12h"
此缓存断点的最短存续时间,默认为请求的 TTL。
"30m"
"12h"
BetaResponseInputFileContent object { type, detail, file_data, 4 more }
输入模型的文件。
type: "input_file" (default: "input_file")
输入条目类型,固定为 input_file。
"input_file"
detail: optional "auto" or "low" or "high"
发送给模型的文件细节级别。使用 auto 由系统选择;对于 GPT-5.6 及后续模型,auto 使用高质量渲染,可能增加输入词元用量。使用 low 进行成本较低的渲染,或使用 high 以更高质量渲染文件。默认为 auto。
"auto"
"low"
"high"
file_data: optional string or null
要发送给模型的文件的 Base64 编码数据。
maxLength: 73400320
file_id: optional string or null
要发送给模型的文件 ID。
file_url: optional string or null
要发送给模型的文件 URL。
format: uri
filename: optional string or null
要发送给模型的文件名。
prompt_cache_breakpoint: optional object { mode, ttl } or null
标记可复用提示词前缀的精确结束位置。省略 ttl 时,断点继承请求中的 prompt_cache_options.ttl;该边界不会按词元块取整。
mode: "explicit" (default: "explicit")
断点模式,固定为 explicit。
"explicit"
ttl: optional "30m" or "12h"
此缓存断点的最短存续时间,默认为请求的 TTL。
"30m"
"12h"
type: "function_call_output" (default: "function_call_output")
类型,固定为 function_call_output。
"function_call_output"
id: optional string or null
函数工具调用输出的唯一 ID,通过 API 返回此条目时填充。
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
call_id: optional string or null
模型生成的函数工具调用的唯一 ID。
minLength: 1, maxLength: 64
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
调用方类型,固定为 direct。
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
minLength: 1, maxLength: 64
type: "program" (default: "program")
调用方类型,固定为 program。
"program"
name: optional string or null
产生输出的工具名称。
minLength: 1, maxLength: 128
namespace: optional string or null
产生输出的工具所属命名空间。
pattern: ^[a-zA-Z0-9_-]+$, minLength: 1, maxLength: 128
status: optional "in_progress" or "completed" or "incomplete" or null
条目状态,可选 in_progress、completed 或 incomplete,通过 API 返回条目时填充。
"in_progress"
"completed"
"incomplete"
AgentMessage object { author, content, recipient, 3 more }
在智能体之间路由的消息。
author: string
发送方智能体的标识。
content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or EncryptedContent { encrypted_content, type }
智能体之间传递的纯文本、图像或加密内容。
BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }
输入模型的文本。
BetaResponseInputImageContent object { type, detail, file_id, 2 more }
输入模型的图像。参阅图像输入。
EncryptedContent object { encrypted_content, type }
不透明的加密内容,由 Responses API 在受信任的模型执行环境中解密。
encrypted_content: string
不透明的加密内容。
maxLength: 10485760
type: "encrypted_content" (default: "encrypted_content")
输入条目的类型,固定为 encrypted_content。
"encrypted_content"
recipient: string
接收方智能体的标识。
type: "agent_message" (default: "agent_message")
条目类型,固定为 agent_message。
"agent_message"
id: optional string or null
此智能体消息条目的唯一 ID。
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
MultiAgentCall object { action, arguments, call_id, 3 more }
action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more
已执行的多智能体操作。
"spawn_agent"
"interrupt_agent"
"list_agents"
"send_message"
"followup_task"
"wait_agent"
arguments: string
以 JSON 字符串表示的操作参数。
call_id: string
关联调用与其输出的唯一 ID。
minLength: 1, maxLength: 64
type: "multi_agent_call" (default: "multi_agent_call")
条目类型,固定为 multi_agent_call。
"multi_agent_call"
id: optional string or null
此多智能体调用的唯一 ID。
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
MultiAgentCallOutput object { action, call_id, output, 3 more }
action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more
生成此结果的多智能体操作。
"spawn_agent"
"interrupt_agent"
"list_agents"
"send_message"
"followup_task"
"wait_agent"
call_id: string
此多智能体调用的唯一 ID。
minLength: 1, maxLength: 64
output: array of object { text, type, annotations }
多智能体操作返回的文本。
text: string
文本内容。
maxLength: 10485760
type: "output_text" (default: "output_text")
内容类型,固定为 output_text。
"output_text"
annotations: optional array of FileCitation { file_id, filename, index, type } or URLCitation { end_index, start_index, title, 2 more } or ContainerFileCitation { container_id, end_index, file_id, 3 more }
与该文本内容关联的引用。
FileCitation object { file_id, filename, index, type }
file_id: string
文件 ID。
filename: string
被引用文件的文件名。
index: integer
文件在文件列表中的索引。
minimum: 0
type: "file_citation" (default: "file_citation")
引用类型,固定为 file_citation。
"file_citation"
URLCitation object { end_index, start_index, title, 2 more }
end_index: integer
引用在消息中最后一个字符的索引。
minimum: 0
start_index: integer
引用在消息中第一个字符的索引。
minimum: 0
title: string
被引用资源的标题。
type: "url_citation" (default: "url_citation")
引用类型,固定为 url_citation。
"url_citation"
url: string
被引用资源的 URL。
format: uri
ContainerFileCitation object { container_id, end_index, file_id, 3 more }
container_id: string
容器 ID。
end_index: integer
引用在消息中最后一个字符的索引。
minimum: 0
file_id: string
容器文件 ID。
filename: string
被引用容器文件的文件名。
start_index: integer
引用在消息中第一个字符的索引。
minimum: 0
type: "container_file_citation" (default: "container_file_citation")
引用类型,固定为 container_file_citation。
"container_file_citation"
type: "multi_agent_call_output" (default: "multi_agent_call_output")
条目类型,固定为 multi_agent_call_output。
"multi_agent_call_output"
id: optional string or null
此多智能体调用输出的唯一 ID。
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
ToolSearchCall object { arguments, type, id, 4 more }
arguments: unknown
传给工具搜索调用的参数。
type: "tool_search_call" (default: "tool_search_call")
条目类型,固定为 tool_search_call。
"tool_search_call"
id: optional string or null
此工具搜索调用的唯一 ID。
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
call_id: optional string or null
模型生成的工具搜索调用的唯一 ID。
minLength: 1, maxLength: 64
execution: optional "server" or "client"
工具搜索由服务端还是客户端执行。
"server"
"client"
status: optional "in_progress" or "completed" or "incomplete" or null
工具搜索调用的状态。
"in_progress"
"completed"
"incomplete"
ToolSearchOutput object { tools, type, id, 4 more }
tools: array of Function { name, parameters, strict, 6 more } or FileSearch { type, vector_store_ids, filters, 2 more } or Computer { type } or 13 more
工具搜索输出返回的已加载工具定义。
Function object { name, parameters, strict, 6 more }
定义模型可以选择调用的自有代码函数。参阅函数调用。
name: string
要调用的函数名称。
parameters: map[unknown] or null
描述函数参数的 JSON Schema 对象。
strict: boolean or null
是否对此函数工具强制执行严格参数校验。
type: "function" (default: "function")
函数工具类型,固定为 function。
"function"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
"direct"
"programmatic"
async: optional boolean
defer_loading: optional boolean
此函数是否延迟加载并通过工具搜索加载。
description: optional string or null
函数描述,模型据此判断是否调用该函数。
output_schema: optional map[unknown] or null
描述此函数字符串输出中编码的 JSON 值的 JSON Schema 对象。
FileSearch object { type, vector_store_ids, filters, 2 more }
搜索已上传文件中相关内容的工具。参阅文件搜索工具。
type: "file_search" (default: "file_search")
文件搜索工具类型,固定为 file_search。
"file_search"
vector_store_ids: array of string
要搜索的向量存储 ID 列表。
filters: optional ComparisonFilter { key, type, value } or unknown or null
要应用的筛选条件。
ComparisonFilter object { key, type, value }
使用指定比较运算,将某个属性键与给定值比较的筛选条件。
key: string
要与值比较的属性键。
type: "eq" or "ne" or "gt" or 5 more (default: "eq")
指定比较运算符:eq、ne、gt、gte、lt、lte、in、nin。
eq:等于。ne:不等于。gt:大于。gte:大于或等于。lt:小于。lte:小于或等于。in:属于。nin:不属于。
"eq"
"ne"
"gt"
"gte"
"lt"
"lte"
"in"
"nin"
value: string or number or boolean or array of string or number
用于与属性键比较的值,支持字符串、数字或布尔类型。
string
number
boolean
array of string or number
string
number
BetaCompoundFilter = unknown
使用 and 或 or 组合多个筛选条件。
max_num_results: optional integer
返回结果数量上限,须介于 1–50 之间,含边界。
ranking_options: optional object { hybrid_search, ranker, score_threshold }
搜索结果的排序选项。
hybrid_search: optional object { embedding_weight, text_weight }
启用混合搜索时,控制倒数排名融合如何平衡语义嵌入匹配与稀疏关键词匹配的权重。
embedding_weight: number
嵌入在倒数排名融合中的权重。
text_weight: number
文本在倒数排名融合中的权重。
ranker: optional "auto" or "default-2024-11-15"
文件搜索所用的排序器。
"auto"
"default-2024-11-15"
score_threshold: optional number
文件搜索的分数阈值,为 0–1 之间的数字。越接近 1,越倾向于只返回最相关的结果,但返回数量可能减少。
Computer object { type }
控制虚拟计算机的工具。参阅计算机工具。
type: "computer" (default: "computer")
计算机工具类型,固定为 computer。
"computer"
ComputerUsePreview object { display_height, display_width, environment, type }
控制虚拟计算机的工具。参阅计算机工具。
display_height: integer
计算机显示区域的高度。
display_width: integer
计算机显示区域的宽度。
environment: "windows" or "mac" or "linux" or 2 more
要控制的计算机环境类型。
"windows"
"mac"
"linux"
"ubuntu"
"browser"
type: "computer_use_preview" (default: "computer_use_preview")
计算机使用工具类型,固定为 computer_use_preview。
"computer_use_preview"
WebSearch object { type, external_web_access, filters, 2 more }
在互联网搜索与提示词相关的来源,详见网页搜索工具。
type: "web_search" or "web_search_2025_08_26" (default: "web_search")
网页搜索工具类型,可选 web_search 或 web_search_2025_08_26。
"web_search"
"web_search_2025_08_26"
external_web_access: optional boolean (default: true)
是否允许网页搜索实时访问互联网。省略时默认为 true。设为 false 时,网页搜索工具以离线或仅缓存模式运行,不会抓取新的外部内容。
filters: optional object { allowed_domains } or null
搜索的筛选条件。
allowed_domains: optional array of string or null (default: [])
搜索允许访问的域名。不提供时允许所有域名,所列域名的子域名也允许访问。
示例:["pubmed.ncbi.nlm.nih.gov"]
search_context_size: optional "low" or "medium" or "high" (default: "medium")
对搜索占用上下文窗口空间大小的总体指导,可选 low、medium 或 high,默认为 medium。
"low"
"medium"
"high"
user_location: optional object { city, country, region, 2 more } or null
用户的大致位置。省略或设为 null 时默认为美国。若要避免此默认值,可传入不包含位置字段的 {"type": "approximate"}。若要本地化结果,须提供相应位置字段。
city: optional string or null
用户所在城市的自由文本,例如 San Francisco。
country: optional string or null
用户所在国家/地区的两字母 ISO 代码,例如 US。
region: optional string or null
用户所在地区的自由文本,例如 California。
timezone: optional string or null
用户所在的 IANA 时区,例如 America/Los_Angeles。
type: optional "approximate" (default: "approximate")
位置估算类型,固定为 approximate。
"approximate"
Mcp object { server_label, type, allowed_callers, 9 more }
通过远程模型上下文协议(MCP)服务器向模型提供更多工具,详见MCP说明。
server_label: string
此 MCP 服务器的标签,用于在工具调用中标识服务器。
type: "mcp"
MCP 工具类型,固定为 mcp。
"mcp"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
minItems: 1
"direct"
"programmatic"
allowed_tools: optional array of string or McpToolFilter { read_only, tool_names } or null
允许的工具名称列表或筛选对象。
McpAllowedTools = array of string
允许的工具名称组成的字符串数组。
McpToolFilter object { read_only, tool_names }
用于指定允许哪些工具的筛选对象。
read_only: optional boolean
说明工具会修改数据还是仅执行只读操作。如果MCP服务器标注了readOnlyHint,就会匹配这个筛选条件。
tool_names: optional array of string
允许的工具名称列表。
authorization: optional string
用于远程MCP服务器的OAuth访问令牌,既可用于自定义MCP服务器URL,也可用于服务连接器。应用须处理OAuth授权流程,并在此提供令牌。
connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more
服务连接器的标识,例如ChatGPT中的连接器。server_url、connector_id、tunnel_id须提供其一,详见服务连接器。
此字段在2026年9月1日之后发布的模型中已弃用。远程MCP服务器改用server_url,安全MCP隧道连接改用tunnel_id。
当前支持的 connector_id 值如下:
Dropbox:connector_dropbox;Gmail:connector_gmail;Google Calendar:connector_googlecalendar;Google Drive:connector_googledrive;Microsoft Teams:connector_microsoftteams;Outlook Calendar:connector_outlookcalendar;Outlook Email:connector_outlookemail;SharePoint:connector_sharepoint。
"connector_dropbox"
"connector_gmail"
"connector_googlecalendar"
"connector_googledrive"
"connector_microsoftteams"
"connector_outlookcalendar"
"connector_outlookemail"
"connector_sharepoint"
defer_loading: optional boolean
此 MCP 工具是否延迟加载并通过工具搜索发现。
headers: optional map[string] or null
发送给MCP服务器的可选HTTP请求头,用于身份验证或其他目的。
require_approval: optional McpToolApprovalFilter { always, never } or "always" or "never" or null (default: "always")
指定 MCP 服务器的哪些工具需要批准。
McpToolApprovalFilter object { always, never }
指定哪些工具需要批准,可选always、never或筛选对象。
always: optional object { read_only, tool_names }
用于指定允许哪些工具的筛选对象。
read_only: optional boolean
说明工具会修改数据还是仅执行只读操作。如果MCP服务器标注了readOnlyHint,就会匹配这个筛选条件。
tool_names: optional array of string
允许的工具名称列表。
never: optional object { read_only, tool_names }
用于指定允许哪些工具的筛选对象。
read_only: optional boolean
说明工具会修改数据还是仅执行只读操作。如果MCP服务器标注了readOnlyHint,就会匹配这个筛选条件。
tool_names: optional array of string
允许的工具名称列表。
McpToolApprovalSetting = "always" or "never"
为所有工具统一指定批准策略,可选always或never。always要求所有工具获得批准,never表示工具无需批准。
"always"
"never"
server_description: optional string
MCP 服务器的可选描述,用于提供更多上下文。
server_url: optional string
MCP服务器URL。server_url、connector_id、tunnel_id三者必须提供其一。
format: uri
tunnel_id: optional string
替代直接服务器URL的安全MCP隧道ID。server_url、connector_id、tunnel_id三者必须提供其一。
pattern: ^tunnel_[a-z0-9]{32}$
CodeInterpreter object { container, type, allowed_callers }
运行 Python 代码以帮助生成提示词响应的工具。
container: string or CodeInterpreterToolAuto { type, file_ids, memory_limit, network_policy }
代码解释器容器,可指定容器ID,或指定包含已上传文件ID的对象,以及可选的memory_limit设置。
string
容器 ID。
CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }
代码解释器容器配置,可以指定运行代码时所处理的文件 ID。
type: "auto" (default: "auto")
固定为 auto。
"auto"
file_ids: optional array of string
可选的已上传文件列表,这些文件将提供给代码使用。
maxItems: 50
memory_limit: optional "1g" or "4g" or "16g" or "64g" or null
代码解释器容器的内存上限。
"1g"
"4g"
"16g"
"64g"
network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist
容器的网络访问策略。
BetaContainerNetworkPolicyDisabled object { type }
type: "disabled" (default: "disabled")
禁用出站网络访问,固定为 disabled。
"disabled"
BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }
allowed_domains: array of string
type 为 allowlist 时允许访问的域名列表。
minItems: 1
type: "allowlist" (default: "allowlist")
仅允许对指定域名发起出站网络访问,固定为 allowlist。
"allowlist"
domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret
可选的仅用于允许访问域名的域名级密钥。
minItems: 1
domain: string
密钥关联的域名。
minLength: 1
name: string
要为该域名注入的密钥名称。
minLength: 1
value: string
要为该域名注入的密钥值。
minLength: 1, maxLength: 10485760
type: "code_interpreter"
代码解释器工具类型,固定为 code_interpreter。
"code_interpreter"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
minItems: 1
"direct"
"programmatic"
ProgrammaticToolCalling object { type }
type: "programmatic_tool_calling" (default: "programmatic_tool_calling")
工具类型,固定为 programmatic_tool_calling。
"programmatic_tool_calling"
ImageGeneration object { type, action, background, 13 more }
使用 GPT 图像模型生成图像的工具。
type: "image_generation"
图像生成工具类型,固定为 image_generation。
"image_generation"
action: optional "generate" or "edit" or "auto"
生成新图像还是编辑已有图像,默认为 auto。
"generate"
"edit"
"auto"
background: optional "transparent" or "opaque" or "auto" (default: "auto")
生成图像的背景,可选transparent、opaque或auto。gpt-image-2.5-sunburst、gpt-image-2.5-flare及其2026-09-08快照支持不透明和透明背景;gpt-image-2的透明背景为预览能力。使用transparent时,输出格式须设为png或webp。默认为auto。
"transparent"
"opaque"
"auto"
complexity: optional "low" or "medium" or "high"
图像规划使用的计算量,独立于渲染质量。生成图像时,此设置覆盖外层响应的 reasoning.effort。省略时会继承外层支持的推理强度,或使用图像模型配置的默认值。生成 SVG 时,此设置控制参考图像的规划计算量,SVG 作者模型使用自己的推理设置。
"low"
"medium"
"high"
frame_count: optional integer (default: 9)
GIF 帧数,要求 output_format 为 gif,默认为 9。
minimum: 2, maximum: 16
frame_duration_ms: optional integer (default: 200)
GIF 每帧的时长,以毫秒计,四舍五入到 10 毫秒。要求 output_format 为 gif。默认值为 200。
minimum: 20, maximum: 2000
input_fidelity: optional "high" or "low" or null
控制模型为匹配输入图像风格和特征(尤其是面部特征)投入的程度。gpt-image-1.5 支持 high 和 low,gpt-image-1-mini 仅支持 low。使用 gpt-image-2 时应省略此参数。支持该参数的模型默认为 low。
"high"
"low"
input_image_mask: optional object { file_id, image_url }
可选的局部重绘蒙版,包含可选image_url字符串和可选file_id字符串。
file_id: optional string
蒙版图像的文件 ID。
image_url: optional string
采用 Base64 编码的蒙版图像。
model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 9 more
生成图像的模型。可用值为 gpt-image-1-mini、gpt-image-1.5、gpt-image-2、gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare、gpt-image-2.5-flare-2026-09-08、gpt-image-2.6-sunburst、gpt-image-2.6-flare 或 chatgpt-image-latest。默认值为 gpt-image-2.6-sunburst。
gpt-image-1 已于 2026 年 10 月 23 日停用,可改用 gpt-image-2.5-sunburst 或 gpt-image-2.5-flare。
string
"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 9 more
生成图像的模型。可用值为 gpt-image-1-mini、gpt-image-1.5、gpt-image-2、gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare、gpt-image-2.5-flare-2026-09-08、gpt-image-2.6-sunburst、gpt-image-2.6-flare 或 chatgpt-image-latest。默认值为 gpt-image-2.6-sunburst。
gpt-image-1 已于 2026 年 10 月 23 日停用,可改用 gpt-image-2.5-sunburst 或 gpt-image-2.5-flare。
"gpt-image-1"
"gpt-image-1-mini"
"gpt-image-2"
"gpt-image-2-2026-04-21"
"gpt-image-2.5-sunburst"
"gpt-image-2.5-sunburst-2026-09-08"
"gpt-image-2.5-flare"
"gpt-image-2.5-flare-2026-09-08"
"gpt-image-2.6-sunburst"
"gpt-image-2.6-flare"
"gpt-image-1.5"
"chatgpt-image-latest"
moderation: optional "auto" or "low" (default: "auto")
生成图像的审核级别,默认为 auto。
"auto"
"low"
output_compression: optional integer (default: 100)
输出图像的压缩级别,默认为 100。
minimum: 0, maximum: 100
output_format: optional "png" or "webp" or "jpeg" or 2 more (default: "png")
生成图像的格式。可选 png、webp、jpeg、gif 或 svg,默认值为 png。GIF 和 SVG 要求模型支持对应格式。GIF 不支持部分图像流式输出(partial_images 大于 0)、input_image_mask 或自定义 output_compression。Responses 生命周期事件仍可流式返回。
"png"
"webp"
"jpeg"
"gif"
"svg"
partial_images: optional integer (default: 0)
流式模式中生成的部分图像数量,范围为 0(默认值)到 3。
minimum: 0, maximum: 3
quality: optional "low" or "medium" or "high" or 3 more (default: "auto")
生成图像的质量。GPT图像模型支持low、medium、high;gpt-image-2.5-sunburst、gpt-image-2.5-flare及其2026-09-08快照还支持xhigh和max。默认为auto。
"low"
"medium"
"high"
"xhigh"
"max"
"auto"
size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto" (default: "auto")
生成图像的尺寸。gpt-image-2、gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare 和 gpt-image-2.5-flare-2026-09-08 支持以 WIDTHxHEIGHT 字符串指定任意分辨率,例如 1536x864。宽和高均须能被 16 整除,宽高比须在 1:3 至 3:1 之间。高于 2560x1440 的分辨率属于实验功能,支持的最高分辨率为 3840x2160。尺寸还须符合模型当前的像素数与边长限制。GPT Image 模型支持标准尺寸 1024x1024、1536x1024 和 1024x1536;允许自动尺寸的模型支持 auto。
string
"1024x1024" or "1024x1536" or "1536x1024" or "auto"
生成图像的尺寸。gpt-image-2、gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare 和 gpt-image-2.5-flare-2026-09-08 支持以 WIDTHxHEIGHT 字符串指定任意分辨率,例如 1536x864。宽和高均须能被 16 整除,宽高比须在 1:3 至 3:1 之间。高于 2560x1440 的分辨率属于实验功能,支持的最高分辨率为 3840x2160。尺寸还须符合模型当前的像素数与边长限制。GPT Image 模型支持标准尺寸 1024x1024、1536x1024 和 1024x1536;允许自动尺寸的模型支持 auto。
"1024x1024"
"1024x1536"
"1536x1024"
"auto"
svg: optional object { model, reasoning }
SVG 作者模型设置。要求 output_format 为 svg。启用 SVG 模型选择时,省略此对象将使用外层响应模型。其他情况下会使用默认 SVG 作者模型,且无法显式覆盖。
model: optional string
minLength: 1
reasoning: optional object { effort } or null
SVG 编写的推理强度。省略时,Images 和 Responses 均使用编写模型的默认值。
effort: optional "none" or "minimal" or "low" or 4 more
控制模型为此次请求投入的推理强度。
"none"
"minimal"
"low"
"medium"
"high"
"xhigh"
"max"
LocalShell object { type }
允许模型在本地环境执行 shell 命令的工具。
type: "local_shell" (default: "local_shell")
本地 shell 工具类型,固定为 local_shell。
"local_shell"
Shell object { type, allowed_callers, environment }
允许模型执行 shell 命令的工具。
type: "shell" (default: "shell")
shell 工具类型,固定为 shell。
"shell"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
minItems: 1
"direct"
"programmatic"
environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference or null
BetaContainerAuto object { type, file_ids, memory_limit, 2 more }
type: "container_auto" (default: "container_auto")
为此请求自动创建容器。
"container_auto"
file_ids: optional array of string
可选的已上传文件列表,这些文件将提供给代码使用。
maxItems: 50
memory_limit: optional "1g" or "4g" or "16g" or "64g" or null
容器的内存上限。
"1g"
"4g"
"16g"
"64g"
network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist
容器的网络访问策略。
BetaContainerNetworkPolicyDisabled object { type }
BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }
skills: optional array of BetaSkillReference or BetaInlineSkill
可选技能列表,支持按 ID 引用或传入内联数据。列表中所有内联技能解码后的 ZIP 数据合计最多 50 MiB,Base64 文本含换行在内合计最多 70,254,592 个字符。技能引用不计入限制。
maxItems: 200
BetaSkillReference object { skill_id, type, version }
skill_id: string
引用的技能 ID。
minLength: 1, maxLength: 64
type: "skill_reference" (default: "skill_reference")
引用通过 /v1/skills 接口创建的技能。
"skill_reference"
version: optional string
可选的技能版本。使用正整数或 'latest',省略时使用默认版本。
BetaInlineSkill object { description, name, source, type }
description: string
技能描述。
name: string
技能名称。
source: BetaInlineSkillSource
内联技能载荷。
data: string
采用 Base64 编码的技能 ZIP 包。
minLength: 1, maxLength: 70254592
media_type: "application/zip" (default: "application/zip")
内联技能载荷的媒体类型,必须为 application/zip。
"application/zip"
type: "base64" (default: "base64")
内联技能来源的类型,必须为 base64。
"base64"
type: "inline" (default: "inline")
为此请求定义内联技能。
"inline"
BetaLocalEnvironment object { type, skills }
type: "local" (default: "local")
使用本地计算机环境。
"local"
skills: optional array of BetaLocalSkill
可选的技能列表。
maxItems: 200
description: string
技能描述。
name: string
技能名称。
path: string
包含该技能的目录路径。
BetaContainerReference object { container_id, type }
container_id: string
引用的容器 ID。
type: "container_reference" (default: "container_reference")
引用通过 /v1/containers 接口创建的容器。
"container_reference"
Custom object { name, type, allowed_callers, 4 more }
使用指定格式处理输入的自定义工具。参阅自定义工具。
name: string
自定义工具的名称,用于在工具调用中标识它。
type: "custom" (default: "custom")
自定义工具类型,固定为 custom。
"custom"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
minItems: 1
"direct"
"programmatic"
async: optional boolean
工具响应是否可以异步返回,而非在下一次创建响应时立即返回。
defer_loading: optional boolean
此工具是否应延迟加载并通过工具搜索发现。
description: optional string
自定义工具的可选描述,用于提供更多上下文。
format: optional Text { type } or Grammar { definition, syntax, type }
自定义工具的输入格式,默认为无约束文本。
Text object { type }
无约束的自由文本。
type: "text" (default: "text")
无约束文本格式,固定为 text。
"text"
Grammar object { definition, syntax, type }
用户定义的语法。
definition: string
语法定义。
syntax: "lark" or "regex"
语法定义的语法类型,可选 lark 或 regex。
"lark"
"regex"
type: "grammar" (default: "grammar")
语法格式,固定为 grammar。
"grammar"
BetaToolSearchOutputNamespaceTool object { description, name, tools, type }
将函数工具或自定义工具归入共享命名空间。
description: string
展示给模型的命名空间描述。
name: string
工具调用使用的命名空间名称,例如 crm。
minLength: 1
tools: array of Function { name, type, allowed_callers, 6 more } or Custom { name, type, allowed_callers, 4 more }
此命名空间内已加载的函数工具或自定义工具。
minItems: 1
Function object { name, type, allowed_callers, 6 more }
name: string
已加载的函数工具名称。
pattern: ^(?![\s\S]*[\r\n])[a-zA-Z0-9_.-]+$, minLength: 1, maxLength: 128
type: "function" (default: "function")
"function"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
minItems: 1
"direct"
"programmatic"
async: optional boolean
工具响应是否可以异步返回,而非在下一次创建响应时立即返回。
defer_loading: optional boolean
此函数是否应延迟加载并通过工具搜索发现。
description: optional string or null
output_schema: optional map[unknown] or null
描述此函数工具字符串输出中编码的 JSON 值的 JSON Schema,不用于描述内容数组输出。
parameters: optional unknown or null
strict: optional boolean or null
是否强制执行严格参数校验。省略时,模式兼容的情况下 Responses 会尝试严格校验,否则退回非严格校验。
Custom object { name, type, allowed_callers, 4 more }
使用指定格式处理输入的自定义工具。参阅自定义工具。
name: string
自定义工具的名称,用于在工具调用中标识它。
type: "custom" (default: "custom")
自定义工具类型,固定为 custom。
"custom"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
minItems: 1
"direct"
"programmatic"
async: optional boolean
工具响应是否可以异步返回,而非在下一次创建响应时立即返回。
defer_loading: optional boolean
此工具是否应延迟加载并通过工具搜索发现。
description: optional string
自定义工具的可选描述,用于提供更多上下文。
format: optional Text { type } or Grammar { definition, syntax, type }
自定义工具的输入格式,默认为无约束文本。
Text object { type }
无约束的自由文本。
type: "text" (default: "text")
无约束文本格式,固定为 text。
"text"
Grammar object { definition, syntax, type }
用户定义的语法。
definition: string
语法定义。
syntax: "lark" or "regex"
语法定义的语法类型,可选 lark 或 regex。
"lark"
"regex"
type: "grammar" (default: "grammar")
语法格式,固定为 grammar。
"grammar"
type: "namespace" (default: "namespace")
工具类型,固定为 namespace。
"namespace"
ToolSearch object { type, description, execution, parameters }
用于延迟加载工具的托管工具搜索或自带工具(BYOT)搜索配置。
type: "tool_search" (default: "tool_search")
工具类型,固定为 tool_search。
"tool_search"
description: optional string or null
客户端执行的工具搜索工具展示给模型的描述。
execution: optional "server" or "client"
工具搜索由服务端还是客户端执行。
"server"
"client"
parameters: optional unknown or null
客户端执行的工具搜索工具的参数模式。
WebSearchPreview object { type, search_content_types, search_context_size, user_location }
搜索网页以获取可用于响应的相关结果的工具。参阅网页搜索工具。
type: "web_search_preview" or "web_search_preview_2025_03_11" (default: "web_search_preview")
网页搜索工具类型,可选 web_search_preview 或 web_search_preview_2025_03_11。
"web_search_preview"
"web_search_preview_2025_03_11"
search_content_types: optional array of "text" or "image"
"text"
"image"
search_context_size: optional "low" or "medium" or "high"
对搜索占用上下文窗口空间大小的总体指导,可选 low、medium 或 high,默认为 medium。
"low"
"medium"
"high"
user_location: optional object { type, city, country, 2 more } or null
用户的大致位置。省略或设为 null 时默认为美国。若要避免此默认值,可传入不包含位置字段的 {"type": "approximate"}。若要本地化结果,须提供相应位置字段。
type: "approximate" (default: "approximate")
位置估算类型,固定为 approximate。
"approximate"
city: optional string or null
用户所在城市的自由文本,例如 San Francisco。
country: optional string or null
用户所在国家/地区的两字母 ISO 代码,例如 US。
region: optional string or null
用户所在地区的自由文本,例如 California。
timezone: optional string or null
用户所在的 IANA 时区,例如 America/Los_Angeles。
ApplyPatch object { type, allowed_callers }
允许助手使用统一差异格式创建、删除或更新文件。
type: "apply_patch" (default: "apply_patch")
工具类型,固定为 apply_patch。
"apply_patch"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
minItems: 1
"direct"
"programmatic"
type: "tool_search_output" (default: "tool_search_output")
条目类型,固定为 tool_search_output。
"tool_search_output"
id: optional string or null
此工具搜索输出的唯一 ID。
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
call_id: optional string or null
模型生成的工具搜索调用的唯一 ID。
minLength: 1, maxLength: 64
execution: optional "server" or "client"
工具搜索由服务端还是客户端执行。
"server"
"client"
status: optional "in_progress" or "completed" or "incomplete" or null
工具搜索输出的状态。
"in_progress"
"completed"
"incomplete"
AdditionalTools object { role, tools, type, 2 more }
role: "developer" (default: "developer")
提供额外工具的角色,仅支持 developer。
"developer"
tools: array of Function { name, parameters, strict, 6 more } or FileSearch { type, vector_store_ids, filters, 2 more } or Computer { type } or 13 more
在此条目中提供的额外工具列表。
Function object { name, parameters, strict, 6 more }
定义模型可以选择调用的自有代码函数。参阅函数调用。
name: string
要调用的函数名称。
parameters: map[unknown] or null
描述函数参数的 JSON Schema 对象。
strict: boolean or null
是否对此函数工具强制执行严格参数校验。
type: "function" (default: "function")
函数工具类型,固定为 function。
"function"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
"direct"
"programmatic"
async: optional boolean
defer_loading: optional boolean
此函数是否延迟加载并通过工具搜索加载。
description: optional string or null
函数描述,模型据此判断是否调用该函数。
output_schema: optional map[unknown] or null
描述此函数字符串输出中编码的 JSON 值的 JSON Schema 对象。
FileSearch object { type, vector_store_ids, filters, 2 more }
搜索已上传文件中相关内容的工具。参阅文件搜索工具。
type: "file_search" (default: "file_search")
文件搜索工具类型,固定为 file_search。
"file_search"
vector_store_ids: array of string
要搜索的向量存储 ID 列表。
filters: optional ComparisonFilter { key, type, value } or unknown or null
要应用的筛选条件。
ComparisonFilter object { key, type, value }
使用指定比较运算,将某个属性键与给定值比较的筛选条件。
key: string
要与值比较的属性键。
type: "eq" or "ne" or "gt" or 5 more (default: "eq")
指定比较运算符:eq、ne、gt、gte、lt、lte、in、nin。
eq:等于。ne:不等于。gt:大于。gte:大于或等于。lt:小于。lte:小于或等于。in:属于。nin:不属于。
"eq"
"ne"
"gt"
"gte"
"lt"
"lte"
"in"
"nin"
value: string or number or boolean or array of string or number
用于与属性键比较的值,支持字符串、数字或布尔类型。
string
number
boolean
array of string or number
string
number
BetaCompoundFilter = unknown
使用 and 或 or 组合多个筛选条件。
max_num_results: optional integer
返回结果数量上限,须介于 1–50 之间,含边界。
ranking_options: optional object { hybrid_search, ranker, score_threshold }
搜索结果的排序选项。
hybrid_search: optional object { embedding_weight, text_weight }
启用混合搜索时,控制倒数排名融合如何平衡语义嵌入匹配与稀疏关键词匹配的权重。
embedding_weight: number
嵌入在倒数排名融合中的权重。
text_weight: number
文本在倒数排名融合中的权重。
ranker: optional "auto" or "default-2024-11-15"
文件搜索所用的排序器。
"auto"
"default-2024-11-15"
score_threshold: optional number
文件搜索的分数阈值,为 0–1 之间的数字。越接近 1,越倾向于只返回最相关的结果,但返回数量可能减少。
Computer object { type }
控制虚拟计算机的工具。参阅计算机工具。
type: "computer" (default: "computer")
计算机工具类型,固定为 computer。
"computer"
ComputerUsePreview object { display_height, display_width, environment, type }
控制虚拟计算机的工具。参阅计算机工具。
display_height: integer
计算机显示区域的高度。
display_width: integer
计算机显示区域的宽度。
environment: "windows" or "mac" or "linux" or 2 more
要控制的计算机环境类型。
"windows"
"mac"
"linux"
"ubuntu"
"browser"
type: "computer_use_preview" (default: "computer_use_preview")
计算机使用工具类型,固定为 computer_use_preview。
"computer_use_preview"
WebSearch object { type, external_web_access, filters, 2 more }
在互联网搜索与提示词相关的来源,详见网页搜索工具。
type: "web_search" or "web_search_2025_08_26" (default: "web_search")
网页搜索工具类型,可选 web_search 或 web_search_2025_08_26。
"web_search"
"web_search_2025_08_26"
external_web_access: optional boolean (default: true)
是否允许网页搜索实时访问互联网。省略时默认为 true。设为 false 时,网页搜索工具以离线或仅缓存模式运行,不会抓取新的外部内容。
filters: optional object { allowed_domains } or null
搜索的筛选条件。
allowed_domains: optional array of string or null (default: [])
搜索允许访问的域名。不提供时允许所有域名,所列域名的子域名也允许访问。
示例:["pubmed.ncbi.nlm.nih.gov"]
search_context_size: optional "low" or "medium" or "high" (default: "medium")
对搜索占用上下文窗口空间大小的总体指导,可选 low、medium 或 high,默认为 medium。
"low"
"medium"
"high"
user_location: optional object { city, country, region, 2 more } or null
用户的大致位置。省略或设为 null 时默认为美国。若要避免此默认值,可传入不包含位置字段的 {"type": "approximate"}。若要本地化结果,须提供相应位置字段。
city: optional string or null
用户所在城市的自由文本,例如 San Francisco。
country: optional string or null
用户所在国家/地区的两字母 ISO 代码,例如 US。
region: optional string or null
用户所在地区的自由文本,例如 California。
timezone: optional string or null
用户所在的 IANA 时区,例如 America/Los_Angeles。
type: optional "approximate" (default: "approximate")
位置估算类型,固定为 approximate。
"approximate"
Mcp object { server_label, type, allowed_callers, 9 more }
通过远程模型上下文协议(MCP)服务器向模型提供更多工具,详见MCP说明。
server_label: string
此 MCP 服务器的标签,用于在工具调用中标识服务器。
type: "mcp"
MCP 工具类型,固定为 mcp。
"mcp"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
minItems: 1
"direct"
"programmatic"
allowed_tools: optional array of string or McpToolFilter { read_only, tool_names } or null
允许的工具名称列表或筛选对象。
McpAllowedTools = array of string
允许的工具名称组成的字符串数组。
McpToolFilter object { read_only, tool_names }
用于指定允许哪些工具的筛选对象。
read_only: optional boolean
说明工具会修改数据还是仅执行只读操作。如果MCP服务器标注了readOnlyHint,就会匹配这个筛选条件。
tool_names: optional array of string
允许的工具名称列表。
authorization: optional string
用于远程MCP服务器的OAuth访问令牌,既可用于自定义MCP服务器URL,也可用于服务连接器。应用须处理OAuth授权流程,并在此提供令牌。
connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more
服务连接器的标识,例如ChatGPT中的连接器。server_url、connector_id、tunnel_id须提供其一,详见服务连接器。
此字段在2026年9月1日之后发布的模型中已弃用。远程MCP服务器改用server_url,安全MCP隧道连接改用tunnel_id。
当前支持的 connector_id 值如下:
Dropbox:connector_dropbox;Gmail:connector_gmail;Google Calendar:connector_googlecalendar;Google Drive:connector_googledrive;Microsoft Teams:connector_microsoftteams;Outlook Calendar:connector_outlookcalendar;Outlook Email:connector_outlookemail;SharePoint:connector_sharepoint。
"connector_dropbox"
"connector_gmail"
"connector_googlecalendar"
"connector_googledrive"
"connector_microsoftteams"
"connector_outlookcalendar"
"connector_outlookemail"
"connector_sharepoint"
defer_loading: optional boolean
此 MCP 工具是否延迟加载并通过工具搜索发现。
headers: optional map[string] or null
发送给MCP服务器的可选HTTP请求头,用于身份验证或其他目的。
require_approval: optional McpToolApprovalFilter { always, never } or "always" or "never" or null (default: "always")
指定 MCP 服务器的哪些工具需要批准。
McpToolApprovalFilter object { always, never }
指定哪些工具需要批准,可选always、never或筛选对象。
always: optional object { read_only, tool_names }
用于指定允许哪些工具的筛选对象。
read_only: optional boolean
说明工具会修改数据还是仅执行只读操作。如果MCP服务器标注了readOnlyHint,就会匹配这个筛选条件。
tool_names: optional array of string
允许的工具名称列表。
never: optional object { read_only, tool_names }
用于指定允许哪些工具的筛选对象。
read_only: optional boolean
说明工具会修改数据还是仅执行只读操作。如果MCP服务器标注了readOnlyHint,就会匹配这个筛选条件。
tool_names: optional array of string
允许的工具名称列表。
McpToolApprovalSetting = "always" or "never"
为所有工具统一指定批准策略,可选always或never。always要求所有工具获得批准,never表示工具无需批准。
"always"
"never"
server_description: optional string
MCP 服务器的可选描述,用于提供更多上下文。
server_url: optional string
MCP服务器URL。server_url、connector_id、tunnel_id三者必须提供其一。
format: uri
tunnel_id: optional string
替代直接服务器URL的安全MCP隧道ID。server_url、connector_id、tunnel_id三者必须提供其一。
pattern: ^tunnel_[a-z0-9]{32}$
CodeInterpreter object { container, type, allowed_callers }
运行 Python 代码以帮助生成提示词响应的工具。
container: string or CodeInterpreterToolAuto { type, file_ids, memory_limit, network_policy }
代码解释器容器,可指定容器ID,或指定包含已上传文件ID的对象,以及可选的memory_limit设置。
string
容器 ID。
CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }
代码解释器容器配置,可以指定运行代码时所处理的文件 ID。
type: "auto" (default: "auto")
固定为 auto。
"auto"
file_ids: optional array of string
可选的已上传文件列表,这些文件将提供给代码使用。
maxItems: 50
memory_limit: optional "1g" or "4g" or "16g" or "64g" or null
代码解释器容器的内存上限。
"1g"
"4g"
"16g"
"64g"
network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist
容器的网络访问策略。
BetaContainerNetworkPolicyDisabled object { type }
BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }
type: "code_interpreter"
代码解释器工具类型,固定为 code_interpreter。
"code_interpreter"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
minItems: 1
"direct"
"programmatic"
ProgrammaticToolCalling object { type }
type: "programmatic_tool_calling" (default: "programmatic_tool_calling")
工具类型,固定为 programmatic_tool_calling。
"programmatic_tool_calling"
ImageGeneration object { type, action, background, 13 more }
使用 GPT 图像模型生成图像的工具。
type: "image_generation"
图像生成工具类型,固定为 image_generation。
"image_generation"
action: optional "generate" or "edit" or "auto"
生成新图像还是编辑已有图像,默认为 auto。
"generate"
"edit"
"auto"
background: optional "transparent" or "opaque" or "auto" (default: "auto")
生成图像的背景,可选transparent、opaque或auto。gpt-image-2.5-sunburst、gpt-image-2.5-flare及其2026-09-08快照支持不透明和透明背景;gpt-image-2的透明背景为预览能力。使用transparent时,输出格式须设为png或webp。默认为auto。
"transparent"
"opaque"
"auto"
complexity: optional "low" or "medium" or "high"
图像规划使用的计算量,独立于渲染质量。生成图像时,此设置覆盖外层响应的 reasoning.effort。省略时会继承外层支持的推理强度,或使用图像模型配置的默认值。生成 SVG 时,此设置控制参考图像的规划计算量,SVG 作者模型使用自己的推理设置。
"low"
"medium"
"high"
frame_count: optional integer (default: 9)
GIF 帧数,要求 output_format 为 gif,默认为 9。
minimum: 2, maximum: 16
frame_duration_ms: optional integer (default: 200)
GIF 每帧的时长,以毫秒计,四舍五入到 10 毫秒。要求 output_format 为 gif。默认值为 200。
minimum: 20, maximum: 2000
input_fidelity: optional "high" or "low" or null
控制模型为匹配输入图像风格和特征(尤其是面部特征)投入的程度。gpt-image-1.5 支持 high 和 low,gpt-image-1-mini 仅支持 low。使用 gpt-image-2 时应省略此参数。支持该参数的模型默认为 low。
"high"
"low"
input_image_mask: optional object { file_id, image_url }
可选的局部重绘蒙版,包含可选image_url字符串和可选file_id字符串。
file_id: optional string
蒙版图像的文件 ID。
image_url: optional string
采用 Base64 编码的蒙版图像。
model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 9 more
生成图像的模型。可用值为 gpt-image-1-mini、gpt-image-1.5、gpt-image-2、gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare、gpt-image-2.5-flare-2026-09-08、gpt-image-2.6-sunburst、gpt-image-2.6-flare 或 chatgpt-image-latest。默认值为 gpt-image-2.6-sunburst。
gpt-image-1 已于 2026 年 10 月 23 日停用,可改用 gpt-image-2.5-sunburst 或 gpt-image-2.5-flare。
string
"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 9 more
生成图像的模型。可用值为 gpt-image-1-mini、gpt-image-1.5、gpt-image-2、gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare、gpt-image-2.5-flare-2026-09-08、gpt-image-2.6-sunburst、gpt-image-2.6-flare 或 chatgpt-image-latest。默认值为 gpt-image-2.6-sunburst。
gpt-image-1 已于 2026 年 10 月 23 日停用,可改用 gpt-image-2.5-sunburst 或 gpt-image-2.5-flare。
"gpt-image-1"
"gpt-image-1-mini"
"gpt-image-2"
"gpt-image-2-2026-04-21"
"gpt-image-2.5-sunburst"
"gpt-image-2.5-sunburst-2026-09-08"
"gpt-image-2.5-flare"
"gpt-image-2.5-flare-2026-09-08"
"gpt-image-2.6-sunburst"
"gpt-image-2.6-flare"
"gpt-image-1.5"
"chatgpt-image-latest"
moderation: optional "auto" or "low" (default: "auto")
生成图像的审核级别,默认为 auto。
"auto"
"low"
output_compression: optional integer (default: 100)
输出图像的压缩级别,默认为 100。
minimum: 0, maximum: 100
output_format: optional "png" or "webp" or "jpeg" or 2 more (default: "png")
生成图像的格式。可选 png、webp、jpeg、gif 或 svg,默认值为 png。GIF 和 SVG 要求模型支持对应格式。GIF 不支持部分图像流式输出(partial_images 大于 0)、input_image_mask 或自定义 output_compression。Responses 生命周期事件仍可流式返回。
"png"
"webp"
"jpeg"
"gif"
"svg"
partial_images: optional integer (default: 0)
流式模式中生成的部分图像数量,范围为 0(默认值)到 3。
minimum: 0, maximum: 3
quality: optional "low" or "medium" or "high" or 3 more (default: "auto")
生成图像的质量。GPT图像模型支持low、medium、high;gpt-image-2.5-sunburst、gpt-image-2.5-flare及其2026-09-08快照还支持xhigh和max。默认为auto。
"low"
"medium"
"high"
"xhigh"
"max"
"auto"
size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto" (default: "auto")
生成图像的尺寸。gpt-image-2、gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare 和 gpt-image-2.5-flare-2026-09-08 支持以 WIDTHxHEIGHT 字符串指定任意分辨率,例如 1536x864。宽和高均须能被 16 整除,宽高比须在 1:3 至 3:1 之间。高于 2560x1440 的分辨率属于实验功能,支持的最高分辨率为 3840x2160。尺寸还须符合模型当前的像素数与边长限制。GPT Image 模型支持标准尺寸 1024x1024、1536x1024 和 1024x1536;允许自动尺寸的模型支持 auto。
string
"1024x1024" or "1024x1536" or "1536x1024" or "auto"
生成图像的尺寸。gpt-image-2、gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare 和 gpt-image-2.5-flare-2026-09-08 支持以 WIDTHxHEIGHT 字符串指定任意分辨率,例如 1536x864。宽和高均须能被 16 整除,宽高比须在 1:3 至 3:1 之间。高于 2560x1440 的分辨率属于实验功能,支持的最高分辨率为 3840x2160。尺寸还须符合模型当前的像素数与边长限制。GPT Image 模型支持标准尺寸 1024x1024、1536x1024 和 1024x1536;允许自动尺寸的模型支持 auto。
"1024x1024"
"1024x1536"
"1536x1024"
"auto"
svg: optional object { model, reasoning }
SVG 作者模型设置。要求 output_format 为 svg。启用 SVG 模型选择时,省略此对象将使用外层响应模型。其他情况下会使用默认 SVG 作者模型,且无法显式覆盖。
model: optional string
minLength: 1
reasoning: optional object { effort } or null
SVG 编写的推理强度。省略时,Images 和 Responses 均使用编写模型的默认值。
effort: optional "none" or "minimal" or "low" or 4 more
控制模型为此次请求投入的推理强度。
"none"
"minimal"
"low"
"medium"
"high"
"xhigh"
"max"
LocalShell object { type }
允许模型在本地环境执行 shell 命令的工具。
type: "local_shell" (default: "local_shell")
本地 shell 工具类型,固定为 local_shell。
"local_shell"
Shell object { type, allowed_callers, environment }
允许模型执行 shell 命令的工具。
type: "shell" (default: "shell")
shell 工具类型,固定为 shell。
"shell"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
minItems: 1
"direct"
"programmatic"
environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference or null
BetaContainerAuto object { type, file_ids, memory_limit, 2 more }
BetaLocalEnvironment object { type, skills }
BetaContainerReference object { container_id, type }
Custom object { name, type, allowed_callers, 4 more }
使用指定格式处理输入的自定义工具。参阅自定义工具。
name: string
自定义工具的名称,用于在工具调用中标识它。
type: "custom" (default: "custom")
自定义工具类型,固定为 custom。
"custom"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
minItems: 1
"direct"
"programmatic"
async: optional boolean
工具响应是否可以异步返回,而非在下一次创建响应时立即返回。
defer_loading: optional boolean
此工具是否应延迟加载并通过工具搜索发现。
description: optional string
自定义工具的可选描述,用于提供更多上下文。
format: optional Text { type } or Grammar { definition, syntax, type }
自定义工具的输入格式,默认为无约束文本。
Text object { type }
无约束的自由文本。
type: "text" (default: "text")
无约束文本格式,固定为 text。
"text"
Grammar object { definition, syntax, type }
用户定义的语法。
definition: string
语法定义。
syntax: "lark" or "regex"
语法定义的语法类型,可选 lark 或 regex。
"lark"
"regex"
type: "grammar" (default: "grammar")
语法格式,固定为 grammar。
"grammar"
Namespace object { description, name, tools, type }
将函数工具或自定义工具归入共享命名空间。
description: string
展示给模型的命名空间描述。
name: string
工具调用使用的命名空间名称,例如 crm。
minLength: 1
tools: array of Function { name, type, allowed_callers, 6 more } or Custom { name, type, allowed_callers, 4 more }
此命名空间内可用的函数工具或自定义工具。
minItems: 1
Function object { name, type, allowed_callers, 6 more }
name: string
pattern: ^[a-zA-Z0-9_-]+$, minLength: 1, maxLength: 128
type: "function" (default: "function")
"function"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
minItems: 1
"direct"
"programmatic"
async: optional boolean
工具响应是否可以异步返回,而非在下一次创建响应时立即返回。
defer_loading: optional boolean
此函数是否应延迟加载并通过工具搜索发现。
description: optional string or null
output_schema: optional map[unknown] or null
描述此函数工具字符串输出中编码的 JSON 值的 JSON Schema,不用于描述内容数组输出。
parameters: optional unknown or null
strict: optional boolean or null
是否强制执行严格参数校验。省略时,模式兼容的情况下 Responses 会尝试严格校验,否则退回非严格校验。
Custom object { name, type, allowed_callers, 4 more }
使用指定格式处理输入的自定义工具。参阅自定义工具。
name: string
自定义工具的名称,用于在工具调用中标识它。
type: "custom" (default: "custom")
自定义工具类型,固定为 custom。
"custom"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
minItems: 1
"direct"
"programmatic"
async: optional boolean
工具响应是否可以异步返回,而非在下一次创建响应时立即返回。
defer_loading: optional boolean
此工具是否应延迟加载并通过工具搜索发现。
description: optional string
自定义工具的可选描述,用于提供更多上下文。
format: optional Text { type } or Grammar { definition, syntax, type }
自定义工具的输入格式,默认为无约束文本。
Text object { type }
无约束的自由文本。
type: "text" (default: "text")
无约束文本格式,固定为 text。
"text"
Grammar object { definition, syntax, type }
用户定义的语法。
definition: string
语法定义。
syntax: "lark" or "regex"
语法定义的语法类型,可选 lark 或 regex。
"lark"
"regex"
type: "grammar" (default: "grammar")
语法格式,固定为 grammar。
"grammar"
type: "namespace" (default: "namespace")
工具类型,固定为 namespace。
"namespace"
ToolSearch object { type, description, execution, parameters }
用于延迟加载工具的托管工具搜索或自带工具(BYOT)搜索配置。
type: "tool_search" (default: "tool_search")
工具类型,固定为 tool_search。
"tool_search"
description: optional string or null
客户端执行的工具搜索工具展示给模型的描述。
execution: optional "server" or "client"
工具搜索由服务端还是客户端执行。
"server"
"client"
parameters: optional unknown or null
客户端执行的工具搜索工具的参数模式。
WebSearchPreview object { type, search_content_types, search_context_size, user_location }
搜索网页以获取可用于响应的相关结果的工具。参阅网页搜索工具。
type: "web_search_preview" or "web_search_preview_2025_03_11" (default: "web_search_preview")
网页搜索工具类型,可选 web_search_preview 或 web_search_preview_2025_03_11。
"web_search_preview"
"web_search_preview_2025_03_11"
search_content_types: optional array of "text" or "image"
"text"
"image"
search_context_size: optional "low" or "medium" or "high"
对搜索占用上下文窗口空间大小的总体指导,可选 low、medium 或 high,默认为 medium。
"low"
"medium"
"high"
user_location: optional object { type, city, country, 2 more } or null
用户的大致位置。省略或设为 null 时默认为美国。若要避免此默认值,可传入不包含位置字段的 {"type": "approximate"}。若要本地化结果,须提供相应位置字段。
type: "approximate" (default: "approximate")
位置估算类型,固定为 approximate。
"approximate"
city: optional string or null
用户所在城市的自由文本,例如 San Francisco。
country: optional string or null
用户所在国家/地区的两字母 ISO 代码,例如 US。
region: optional string or null
用户所在地区的自由文本,例如 California。
timezone: optional string or null
用户所在的 IANA 时区,例如 America/Los_Angeles。
ApplyPatch object { type, allowed_callers }
允许助手使用统一差异格式创建、删除或更新文件。
type: "apply_patch" (default: "apply_patch")
工具类型,固定为 apply_patch。
"apply_patch"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
minItems: 1
"direct"
"programmatic"
type: "additional_tools" (default: "additional_tools")
条目类型,固定为 additional_tools。
"additional_tools"
id: optional string or null
此额外工具条目的唯一 ID。
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
ConfigurationUpdate object { type, id, agent, 2 more }
更新对话的响应配置。可提供推理设置、文本设置或两者。各项设置持续有效,直至后续更新替换。
type: "configuration_update" (default: "configuration_update")
条目类型,固定为 configuration_update。
"configuration_update"
id: optional string or null
配置更新条目的唯一 ID。
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
reasoning: optional object { effort }
推理配置更新,仅支持 effort。
effort: optional "none" or "minimal" or "low" or 4 more or null (default: "medium")
后续响应使用的推理努力程度,直到被下一条配置更新替代。
"none"
"minimal"
"low"
"medium"
"high"
"xhigh"
"max"
text: optional object { format }
后续响应的文本输出配置。
format: Text { type } or BetaResponseFormatTextJSONSchemaConfig
使用 JSON Schema 进行结构化输出,或使用 text 恢复纯文本。
Text object { type }
默认响应格式,用于生成文本响应。
type: "text"
定义的响应格式类型,固定为 text。
"text"
BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }
JSON Schema响应格式,用于生成结构化JSON,详见结构化输出。
name: string
响应格式名称,只能使用a-z、A-Z、0-9、下划线和连字符,最长64个字符。
schema: map[unknown]
以JSON Schema对象描述的响应格式schema,构建方法见JSON Schema。
type: "json_schema"
定义的响应格式类型,固定为 json_schema。
"json_schema"
description: optional string
响应格式用途的描述,供模型判断如何按此格式回答。
strict: optional boolean or null (default: false)
是否严格遵循输出schema。设为true时,模型会严格遵循schema定义;strict为true时仅支持JSON Schema子集,详见结构化输出指南。
Reasoning object { id, summary, type, 4 more }
推理模型生成响应时所用思维链的描述。如果手动管理上下文,请在后续对话轮次发送给Responses API的input中包含这些条目。
id: string
推理内容的唯一标识。
summary: array of object { text, type }
推理摘要内容。
text: string
模型到目前为止生成的推理输出摘要。
type: "summary_text" (default: "summary_text")
类型,固定为 summary_text。
"summary_text"
type: "reasoning"
类型,固定为 reasoning。
"reasoning"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
content: optional array of object { text, type }
推理文本内容。
text: string
模型生成的推理文本。
type: "reasoning_text" (default: "reasoning_text")
类型,固定为 reasoning_text。
"reasoning_text"
encrypted_content: optional string or null
推理条目的加密内容。POST /v1/responses及WebSocket response.create请求返回的推理条目默认填充此字段。
流式处理中,后续请求应使用response.output_item.done事件中的已完成推理条目及其encrypted_content。response.output_item.added中的加密内容可能不完整。在store为false或使用零数据保留时尤其重要。
status: optional "in_progress" or "completed" or "incomplete"
条目状态,可选 in_progress、completed 或 incomplete,通过 API 返回条目时填充。
"in_progress"
"completed"
"incomplete"
Compaction object { encrypted_content, type, id, agent }
v1/responses/compact API生成的压缩条目。
encrypted_content: string
压缩摘要的加密内容。
maxLength: 104857600
type: "compaction" (default: "compaction")
类型,固定为 compaction。
"compaction"
id: optional string or null
压缩条目 ID。
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
ImageGenerationCall object { id, result, status, 10 more }
模型发起的图像生成请求。
id: string
图像生成调用的唯一 ID。
result: string or null
Base64 编码的生成图像。
status: "in_progress" or "completed" or "generating" or "failed"
图像生成调用的状态。
"in_progress"
"completed"
"generating"
"failed"
type: "image_generation_call"
类型,固定为 image_generation_call。
"image_generation_call"
action: optional "generate" or "edit" or "auto" or null
用于图像生成的操作。
"generate"
"edit"
"auto"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
background: optional "transparent" or "opaque" or "auto" or null
生成图像使用的背景设置。
"transparent"
"opaque"
"auto"
error: optional object { code, message, param, 2 more }
审核失败的详情,如可用。
code: string or null
错误代码。
message: string
错误描述。
param: string or null
关联的请求参数。
type: string
错误类型。
moderation_details: optional object { categories, moderation_stage }
moderation_blocked 错误的公开详情,如可用。
categories: array of string
公开的审核类别,未来可能增加新的类别值。
moderation_stage: "input" or "output" or "unknown"
审核阻止图像生成调用的阶段。
"input"
"output"
"unknown"
output_format: optional "png" or "webp" or "jpeg" or 2 more or null
生成图像使用的输出格式。
"png"
"webp"
"jpeg"
"gif"
"svg"
quality: optional "low" or "medium" or "high" or 3 more or null
图像生成工具调用生成的图像质量,可选 low、medium、high、xhigh、max 或 auto。
"low"
"medium"
"high"
"xhigh"
"max"
"auto"
revised_prompt: optional string or null
模型改写提示词后实际使用的提示词。
size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or null
图像尺寸,采用 WIDTHxHEIGHT 字符串形式,例如 1536x864。
string
"1024x1024" or "1024x1536" or "1536x1024"
图像尺寸,采用 WIDTHxHEIGHT 字符串形式,例如 1536x864。
"1024x1024"
"1024x1536"
"1536x1024"
svg_usage: optional object { input_tokens, model, output_tokens, 2 more }
input_tokens: integer
model: string
output_tokens: integer
reasoning_tokens: integer
total_tokens: integer
CodeInterpreterCall object { id, code, container_id, 4 more }
运行代码的工具调用。
id: string
代码解释器工具调用的唯一 ID。
code: string or null
要运行的代码,不可用时为 null。
container_id: string
运行代码使用的容器 ID。
outputs: array of Logs { logs, type } or Image { type, url } or null
代码解释器产生的日志、图像等输出;没有可用输出时可为null。
Logs object { logs, type }
代码解释器的日志输出。
logs: string
代码解释器的日志输出。
type: "logs" (default: "logs")
类型,固定为 logs。
"logs"
Image object { type, url }
代码解释器的图像输出。
type: "image" (default: "image")
类型,固定为 image。
"image"
url: string
代码解释器输出图像的 URL。
format: uri
status: "in_progress" or "completed" or "incomplete" or 2 more
代码解释器工具调用的状态,有效值为 in_progress、completed、incomplete、interpreting 和 failed。
"in_progress"
"completed"
"incomplete"
"interpreting"
"failed"
type: "code_interpreter_call" (default: "code_interpreter_call")
类型,固定为 code_interpreter_call。
"code_interpreter_call"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
LocalShellCall object { id, action, call_id, 3 more }
在本地 shell 上运行命令的工具调用。
id: string
本地 shell 调用的唯一 ID。
action: object { command, env, type, 3 more }
在服务器上执行 shell 命令。
command: array of string
要运行的命令。
env: map[string]
要为命令设置的环境变量。
type: "exec" (default: "exec")
类型,固定为 exec。
"exec"
timeout_ms: optional integer or null
可选的命令超时时长,单位为毫秒。
user: optional string or null
可选的运行命令的用户。
working_directory: optional string or null
可选的运行命令的工作目录。
call_id: string
模型生成的本地 shell 工具调用的唯一 ID。
status: "in_progress" or "completed" or "incomplete"
本地 shell 调用的状态。
"in_progress"
"completed"
"incomplete"
type: "local_shell_call"
类型,固定为 local_shell_call。
"local_shell_call"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
LocalShellCallOutput object { id, output, type, 2 more }
本地 shell 工具调用的输出。
id: string
模型生成的本地 shell 工具调用的唯一 ID。
output: string
本地 shell 工具调用输出的 JSON 字符串。
type: "local_shell_call_output"
类型,固定为 local_shell_call_output。
"local_shell_call_output"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
status: optional "in_progress" or "completed" or "incomplete" or null
条目状态,可选 in_progress、completed 或 incomplete。
"in_progress"
"completed"
"incomplete"
ShellCall object { action, call_id, type, 5 more }
表示请求执行一个或多个 shell 命令的工具。
action: object { commands, max_output_length, timeout_ms }
描述如何运行工具调用的 shell 命令及限制。
commands: array of string
按顺序交给执行环境运行的 shell 命令。
max_output_length: optional integer or null
从合并的 stdout 和 stderr 输出中最多捕获的 UTF-8 字符数。
timeout_ms: optional integer or null
允许 shell 命令运行的最大实际时长,单位为毫秒。
call_id: string
模型生成的 shell 工具调用的唯一 ID。
minLength: 1, maxLength: 64
type: "shell_call" (default: "shell_call")
类型,固定为 shell_call。
"shell_call"
id: optional string or null
shell 工具调用的唯一 ID,通过 API 返回此条目时填充。
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
调用方类型,固定为 direct。
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
minLength: 1, maxLength: 64
type: "program" (default: "program")
调用方类型,固定为 program。
"program"
environment: optional BetaLocalEnvironment or BetaContainerReference or null
执行 shell 命令的环境。
BetaLocalEnvironment object { type, skills }
BetaContainerReference object { container_id, type }
status: optional "in_progress" or "completed" or "incomplete" or null
shell 调用状态,可选 in_progress、completed 或 incomplete。
"in_progress"
"completed"
"incomplete"
ShellCallOutput object { call_id, output, type, 5 more }
shell 工具调用发出的流式输出条目。
call_id: string
模型生成的 shell 工具调用的唯一 ID。
minLength: 1, maxLength: 64
output: array of BetaResponseFunctionShellCallOutputContent
捕获的 stdout 和 stderr 输出块,以及关联的执行结果。
outcome: Timeout { type } or Exit { exit_code, type }
此 shell 调用关联的退出或超时结果。
Timeout object { type }
表示 shell 调用超过其配置的时间限制。
type: "timeout" (default: "timeout")
结果类型,固定为 timeout。
"timeout"
Exit object { exit_code, type }
表示 shell 命令已结束,并返回退出码。
exit_code: integer
shell 进程返回的退出码。
type: "exit" (default: "exit")
结果类型,固定为 exit。
"exit"
stderr: string
捕获的 shell 调用的 stderr 输出。
maxLength: 10485760
stdout: string
捕获的 shell 调用的 stdout 输出。
maxLength: 10485760
type: "shell_call_output" (default: "shell_call_output")
类型,固定为 shell_call_output。
"shell_call_output"
id: optional string or null
shell 工具调用输出的唯一 ID,通过 API 返回此条目时填充。
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
调用方类型,固定为 direct。
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
minLength: 1, maxLength: 64
type: "program" (default: "program")
调用方类型,固定为 program。
"program"
max_output_length: optional integer or null
此 shell 调用合并输出中捕获的最大 UTF-8 字符数。
status: optional "in_progress" or "completed" or "incomplete" or null
shell 调用输出的状态。
"in_progress"
"completed"
"incomplete"
ApplyPatchCall object { call_id, operation, status, 4 more }
表示请求使用差异补丁创建、删除或更新文件的工具调用。
call_id: string
模型生成的 apply_patch 工具调用的唯一 ID。
minLength: 1, maxLength: 64
operation: CreateFile { diff, path, type } or DeleteFile { path, type } or UpdateFile { diff, path, type }
apply_patch 工具调用具体的创建、删除或更新指令。
CreateFile object { diff, path, type }
通过 apply_patch 工具创建新文件的指令。
diff: string
创建文件时应用的统一差异内容。
maxLength: 10485760
path: string
相对于工作区根目录的待创建文件路径。
minLength: 1
type: "create_file" (default: "create_file")
操作类型,固定为 create_file。
"create_file"
DeleteFile object { path, type }
通过 apply_patch 工具删除已有文件的指令。
path: string
相对于工作区根目录的待删除文件路径。
minLength: 1
type: "delete_file" (default: "delete_file")
操作类型,固定为 delete_file。
"delete_file"
UpdateFile object { diff, path, type }
通过 apply_patch 工具更新已有文件的指令。
diff: string
应用于已有文件的统一差异内容。
maxLength: 10485760
path: string
相对于工作区根目录的待更新文件路径。
minLength: 1
type: "update_file" (default: "update_file")
操作类型,固定为 update_file。
"update_file"
status: "in_progress" or "completed"
apply_patch 工具调用状态,可选 in_progress 或 completed。
"in_progress"
"completed"
type: "apply_patch_call" (default: "apply_patch_call")
类型,固定为 apply_patch_call。
"apply_patch_call"
id: optional string or null
apply_patch 工具调用的唯一 ID,通过 API 返回此条目时填充。
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
调用方类型,固定为 direct。
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
minLength: 1, maxLength: 64
type: "program" (default: "program")
调用方类型,固定为 program。
"program"
ApplyPatchCallOutput object { call_id, status, type, 4 more }
apply_patch 工具调用发出的流式输出。
call_id: string
模型生成的 apply_patch 工具调用的唯一 ID。
minLength: 1, maxLength: 64
status: "completed" or "failed"
apply_patch 工具调用输出的状态,可选 completed 或 failed。
"completed"
"failed"
type: "apply_patch_call_output" (default: "apply_patch_call_output")
类型,固定为 apply_patch_call_output。
"apply_patch_call_output"
id: optional string or null
apply_patch 工具调用输出的唯一 ID,通过 API 返回此条目时填充。
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
调用方类型,固定为 direct。
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
minLength: 1, maxLength: 64
type: "program" (default: "program")
调用方类型,固定为 program。
"program"
output: optional string or null
apply_patch 工具可选的可读日志文本,例如补丁结果或错误。
maxLength: 10485760
McpListTools object { id, server_label, tools, 3 more }
MCP 服务器可用的工具列表。
id: string
列表的唯一 ID。
server_label: string
MCP 服务器标签。
tools: array of object { input_schema, name, annotations, description }
服务器可用的工具。
input_schema: unknown
描述工具输入的 JSON Schema。
name: string
工具名称。
annotations: optional unknown or null
工具的额外注解。
description: optional string or null
工具描述。
type: "mcp_list_tools"
类型,固定为 mcp_list_tools。
"mcp_list_tools"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
error: optional string or null
服务器无法列出工具时的错误消息。
McpApprovalRequest object { id, arguments, name, 3 more }
工具调用的人工批准请求。
id: string
批准请求的唯一 ID。
arguments: string
工具参数的 JSON 字符串。
name: string
要运行的工具名称。
server_label: string
发出请求的 MCP 服务器标签。
type: "mcp_approval_request"
类型,固定为 mcp_approval_request。
"mcp_approval_request"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
McpApprovalResponse object { approval_request_id, approve, type, 3 more }
对 MCP 批准请求的响应。
approval_request_id: string
所回应的批准请求的 ID。
approve: boolean
请求是否获准。
type: "mcp_approval_response"
类型,固定为 mcp_approval_response。
"mcp_approval_response"
id: optional string or null
批准响应的唯一 ID。
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
reason: optional string or null
决定的可选理由。
McpCall object { id, arguments, name, 7 more }
对 MCP 服务器上工具的调用。
id: string
工具调用的唯一 ID。
arguments: string
传给工具的参数组成的 JSON 字符串。
name: string
已运行的工具名称。
server_label: string
运行工具的 MCP 服务器标签。
type: "mcp_call"
类型,固定为 mcp_call。
"mcp_call"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
approval_request_id: optional string or null
MCP工具调用批准请求的唯一标识。要批准或拒绝相应调用,应在后续mcp_approval_response输入中包含此值。
error: optional BetaMcpToolCallError or null
工具调用的错误,如有。
McpProtocolError object { code, message, type }
code: integer
message: string
type: "mcp_protocol_error" (default: "mcp_protocol_error")
"mcp_protocol_error"
McpToolExecutionError object { content, type }
content: unknown
type: "mcp_tool_execution_error" (default: "mcp_tool_execution_error")
"mcp_tool_execution_error"
HTTPError object { code, message, type }
code: integer
message: string
type: "http_error" (default: "http_error")
"http_error"
output: optional string or null
工具调用的输出。
status: optional "in_progress" or "completed" or "incomplete" or 2 more
工具调用状态,可选 in_progress、completed、incomplete、calling 或 failed。
"in_progress"
"completed"
"incomplete"
"calling"
"failed"
CustomToolCallOutput object { call_id, output, type, 3 more }
自有代码生成、回传给模型的自定义工具调用输出。
call_id: string
调用 ID,用于将此自定义工具调用输出映射到自定义工具调用。
output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
你的代码生成的自定义工具输出,可为字符串或输出内容列表。
StringOutput = string
自定义工具调用输出的字符串。
OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
自定义工具调用的文本、图像或文件输出。
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
type: "custom_tool_call_output"
类型,固定为 custom_tool_call_output。
"custom_tool_call_output"
id: optional string
自定义工具调用输出在 OpenAI 平台中的唯一 ID。
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
调用方类型,固定为 direct。
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
minLength: 1, maxLength: 64
type: "program" (default: "program")
调用方类型,固定为 program。
"program"
CustomToolCall object { call_id, input, name, 6 more }
模型生成的自定义工具调用。
call_id: string
用于将此自定义工具调用映射到工具调用输出的标识。
input: string
模型生成的自定义工具调用输入。
name: string
被调用的自定义工具的名称。
type: "custom_tool_call"
类型,固定为 custom_tool_call。
"custom_tool_call"
id: optional string
自定义工具调用在 OpenAI 平台中的唯一 ID。
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
async: optional boolean
自定义工具调用是否异步运行。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
namespace: optional string
被调用的自定义工具所属的命名空间。
CompactionTrigger object { type, id, agent }
压缩当前上下文,须为最后一个输入条目。
type: "compaction_trigger" (default: "compaction_trigger")
类型,固定为 compaction_trigger。
"compaction_trigger"
id: optional string or null
此压缩触发器的唯一 ID。
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
ItemReference object { id, agent, type }
用于引用条目的内部标识。
id: string
要引用的条目的 ID。
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
type: optional "item_reference" or null (default: "item_reference")
引用条目的类型,固定为 item_reference。
"item_reference"
Program object { id, call_id, code, 3 more }
id: string
此 program 条目的唯一 ID。
call_id: string
program 条目的稳定调用 ID。
minLength: 1, maxLength: 64
code: string
程序化工具调用所执行的 JavaScript 源代码。
maxLength: 10485760
fingerprint: string
不透明的程序重放指纹,须在后续请求中原样回传。
maxLength: 10485760
type: "program" (default: "program")
条目类型,固定为 program。
"program"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
ProgramOutput object { id, call_id, result, 3 more }
id: string
此程序输出条目的唯一 ID。
call_id: string
program 条目的调用 ID。
minLength: 1, maxLength: 64
result: string
program 条目生成的结果。
maxLength: 10485760
status: "completed" or "incomplete"
程序输出的终态。
"completed"
"incomplete"
type: "program_output" (default: "program_output")
条目类型,固定为 program_output。
"program_output"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
instructions: optional string or null
插入模型上下文的system或developer消息。与previous_response_id一起使用时,上一响应的instructions不会传入下一响应,便于在新响应中替换system或developer消息。
previous_response_id: optional string or null
模型上一个响应的唯一 ID。使用此字段创建多轮对话。有关详情,请参阅对话状态。不能与 conversation 同时使用。
prompt_cache_key: optional string or null
读取或写入提示词缓存时使用的键。
maxLength: 64
prompt_cache_options: optional object { mode, ttl } or null
提示词缓存选项,支持 gpt-5.6 及后续模型。默认由 OpenAI 自动选择一个隐式缓存断点。可通过 prompt_cache_breakpoint 为内容块添加显式断点。每个请求最多写入四个断点。缓存匹配会考虑对话中最近最多 80 个断点,不受内容块回看数量限制。将 mode 设为 explicit 可禁用隐式断点。ttl 默认为 30m。支持的存续时间取决于 API,当前详情参阅提示词缓存指南。
mode: optional "implicit" or "explicit"
控制 OpenAI 是否自动创建隐式缓存断点,默认为 implicit。使用 implicit 时,创建一个隐式断点,并写入请求中最近最多三个显式断点。使用 explicit 时,不创建隐式断点,写入最近最多四个显式断点。如果没有显式断点,请求不使用提示词缓存。
"implicit"
"explicit"
ttl: optional "30m"
请求写入的每个隐式和显式缓存断点的最短存续时间,默认为 30m,目前仅支持此值。后端可能保留缓存条目更长时间。
"30m"
prompt_cache_retention: optional "in_memory" or "24h" or null
此请求创建的提示词缓存条目的保留时间。
"in_memory"
"24h"
service_tier: optional "auto" or "default" or "fast" or 2 more or null
指定处理请求的类型。auto使用项目配置的服务层级,未另配置时为default;default使用所选模型标准价格和性能;flex使用Flex处理。Responses或Chat Completions请求以service_tier=fast或service_tier=priority启用快速模式:有专用Fast层级的模型两者均解析为fast,其他模型均解析为priority。未设置时默认auto。响应的service_tier反映实际处理模式,可能不同于请求参数。
"auto"
"default"
"fast"
"flex"
"priority"
返回值
BetaCompactedResponse object { id, created_at, object, 3 more }
id: string
压缩后的响应的唯一标识符。
created_at: integer
压缩后对话创建时的 Unix 时间戳,单位为秒。
format: unixtime
object: "response.compaction" (default: "response.compaction")
对象类型,始终为 response.compaction。
"response.compaction"
output: array of Message { id, content, role, 4 more } or Program { id, call_id, code, 3 more } or ProgramOutput { id, call_id, result, 3 more } or 28 more
压缩后的输出条目列表。
Message object { id, content, role, 4 more }
发往模型或由模型发出的消息。
id: string
消息的唯一 ID。
content: array of BetaResponseInputText or BetaResponseOutputText or Text { text, type } or 7 more
消息内容。
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
text: string
输入模型的文本。
type: "input_text" (default: "input_text")
输入条目类型,固定为 input_text。
"input_text"
prompt_cache_breakpoint: optional object { mode, ttl }
标记可复用提示词前缀的精确结束位置。省略 ttl 时,断点继承请求中的 prompt_cache_options.ttl;该边界不会按词元块取整。
mode: "explicit" (default: "explicit")
断点模式,固定为 explicit。
"explicit"
ttl: optional "30m" or "12h"
此缓存断点的最短存续时间,默认为请求的 TTL。
"30m"
"12h"
BetaResponseOutputText object { annotations, logprobs, text, type }
模型输出的文本。
annotations: array of FileCitation { file_id, filename, index, type } or URLCitation { end_index, start_index, title, 2 more } or ContainerFileCitation { container_id, end_index, file_id, 3 more } or FilePath { file_id, index, type }
文本输出的注解。
FileCitation object { file_id, filename, index, type }
文件引用。
file_id: string
文件 ID。
filename: string
被引用文件的文件名。
index: integer
在输出文本中插入文件引用的位置索引。
type: "file_citation" (default: "file_citation")
类型,固定为 file_citation。
"file_citation"
URLCitation object { end_index, start_index, title, 2 more }
对生成模型响应所用网页资源的引用。
end_index: integer
URL 引用在消息中最后一个字符的索引。
start_index: integer
URL 引用在消息中第一个字符的索引。
title: string
网络资源标题。
type: "url_citation" (default: "url_citation")
URL 引用的类型,固定为 url_citation。
"url_citation"
url: string
网络资源 URL。
format: uri
ContainerFileCitation object { container_id, end_index, file_id, 3 more }
对生成模型响应所用容器文件的引用。
container_id: string
容器文件 ID。
end_index: integer
消息中容器文件引用最后一个字符的索引。
file_id: string
文件 ID。
filename: string
被引用容器文件的文件名。
start_index: integer
消息中容器文件引用第一个字符的索引。
type: "container_file_citation" (default: "container_file_citation")
类型,固定为 container_file_citation。
"container_file_citation"
FilePath object { file_id, index, type }
文件路径。
file_id: string
文件 ID。
index: integer
文件在文件列表中的索引。
type: "file_path"
类型,固定为 file_path。
"file_path"
logprobs: array of object { token, bytes, logprob, top_logprobs }
token: string
bytes: array of number
logprob: number
top_logprobs: array of object { token, bytes, logprob }
token: string
bytes: array of number
logprob: number
text: string
模型输出的文本内容。
type: "output_text" (default: "output_text")
输出文本类型,固定为 output_text。
"output_text"
Text object { text, type }
文本内容。
text: string
type: "text" (default: "text")
"text"
SummaryText object { text, type }
模型生成的摘要文本。
text: string
模型到目前为止生成的推理输出摘要。
type: "summary_text" (default: "summary_text")
类型,固定为 summary_text。
"summary_text"
ReasoningText object { text, type }
模型生成的推理文本。
text: string
模型生成的推理文本。
type: "reasoning_text" (default: "reasoning_text")
类型,固定为 reasoning_text。
"reasoning_text"
BetaResponseOutputRefusal object { refusal, type }
模型的拒绝响应。
refusal: string
模型给出的拒绝原因。
type: "refusal" (default: "refusal")
类型,固定为 refusal。
"refusal"
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
detail: BetaImageDetail
发送给模型的图像细节级别,可选 high、low、auto 或 original,默认为 auto。
"low"
"high"
"auto"
"original"
type: "input_image" (default: "input_image")
输入条目类型,固定为 input_image。
"input_image"
file_id: optional string or null
要发送给模型的文件 ID。
image_url: optional string or null
要发送给模型的图像 URL,可以是完整 URL,或包含 Base64 编码图像的 data URL。
format: uri
prompt_cache_breakpoint: optional object { mode, ttl }
标记可复用提示词前缀的精确结束位置。省略 ttl 时,断点继承请求中的 prompt_cache_options.ttl;该边界不会按词元块取整。
mode: "explicit" (default: "explicit")
断点模式,固定为 explicit。
"explicit"
ttl: optional "30m" or "12h"
此缓存断点的最短存续时间,默认为请求的 TTL。
"30m"
"12h"
ComputerScreenshot object { detail, file_id, image_url, 2 more }
计算机屏幕截图。
detail: BetaImageDetail
发送给模型的截图图像的细节级别,可选 high、low、auto 或 original,默认为 auto。
file_id: string or null
包含截图的已上传文件的标识。
image_url: string or null
截图图像的 URL。
format: uri
type: "computer_screenshot" (default: "computer_screenshot")
指定事件类型。对于计算机屏幕截图,此属性固定为 computer_screenshot。
"computer_screenshot"
prompt_cache_breakpoint: optional object { mode, ttl }
标记可复用提示词前缀的精确结束位置。省略 ttl 时,断点继承请求中的 prompt_cache_options.ttl;该边界不会按词元块取整。
mode: "explicit" (default: "explicit")
断点模式,固定为 explicit。
"explicit"
ttl: optional "30m" or "12h"
此缓存断点的最短存续时间,默认为请求的 TTL。
"30m"
"12h"
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
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"
EncryptedContent object { encrypted_content, type }
不透明的加密内容,由 Responses API 在受信任的模型执行环境中解密。
encrypted_content: string
不透明的加密内容。
type: "encrypted_content" (default: "encrypted_content")
输入条目的类型,固定为 encrypted_content。
"encrypted_content"
role: "unknown" or "user" or "assistant" or 5 more
消息角色,可选 unknown、user、assistant、system、critic、discriminator、developer 或 tool。
"unknown"
"user"
"assistant"
"system"
"critic"
"discriminator"
"developer"
"tool"
status: "in_progress" or "completed" or "incomplete"
条目状态,可选 in_progress、completed 或 incomplete,通过 API 返回条目时填充。
"in_progress"
"completed"
"incomplete"
type: "message" (default: "message")
消息类型,固定为 message。
"message"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
phase: optional "commentary" or "final_answer" or null
将 assistant 消息标记为中间说明(commentary)或最终答案(final_answer)。对于 gpt-5.3-codex 及后续此类模型,发送后续请求时须保留并重新发送所有助手消息的 phase,丢弃它可能降低表现。用户消息不使用此字段。
"commentary"
"final_answer"
Program object { id, call_id, code, 3 more }
id: string
program 条目的唯一 ID。
call_id: string
program 条目的稳定调用 ID。
code: string
程序化工具调用所执行的 JavaScript 源代码。
fingerprint: string
不透明的程序重放指纹,须在后续请求中原样回传。
type: "program" (default: "program")
条目类型,固定为 program。
"program"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
ProgramOutput object { id, call_id, result, 3 more }
id: string
程序输出条目的唯一 ID。
call_id: string
program 条目的调用 ID。
result: string
program 条目生成的结果。
status: "completed" or "incomplete"
程序输出条目的终态。
"completed"
"incomplete"
type: "program_output" (default: "program_output")
条目类型,固定为 program_output。
"program_output"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
FunctionCall object { arguments, call_id, name, 7 more }
执行函数的工具调用,详见函数调用指南。
arguments: string
要传给函数的参数组成的 JSON 字符串。
call_id: string
模型生成的函数工具调用的唯一 ID。
name: string
要运行的函数名称。
type: "function_call"
类型,固定为 function_call。
"function_call"
id: optional string
函数工具调用的唯一 ID。
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
async: optional boolean
函数工具调用是否异步运行。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
namespace: optional string
要运行的函数所属的命名空间。
status: optional "in_progress" or "completed" or "incomplete"
条目状态,可选 in_progress、completed 或 incomplete,通过 API 返回条目时填充。
"in_progress"
"completed"
"incomplete"
MultiAgentCall object { id, action, arguments, 3 more }
id: string
该多智能体调用条目的唯一 ID。
action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more
要执行的多智能体操作。
"spawn_agent"
"interrupt_agent"
"list_agents"
"send_message"
"followup_task"
"wait_agent"
arguments: string
为该操作生成的参数,格式为 JSON 字符串。
call_id: string
关联调用与其输出的唯一 ID。
type: "multi_agent_call" (default: "multi_agent_call")
多智能体调用的类型,固定为 multi_agent_call。
"multi_agent_call"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
MultiAgentCallOutput object { id, action, call_id, 3 more }
id: string
此多智能体调用输出条目的唯一 ID。
action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more
生成此结果的多智能体操作。
"spawn_agent"
"interrupt_agent"
"list_agents"
"send_message"
"followup_task"
"wait_agent"
call_id: string
此多智能体调用的唯一 ID。
output: array of BetaResponseOutputText
多智能体操作返回的文本。
annotations: array of FileCitation { file_id, filename, index, type } or URLCitation { end_index, start_index, title, 2 more } or ContainerFileCitation { container_id, end_index, file_id, 3 more } or FilePath { file_id, index, type }
文本输出的注解。
logprobs: array of object { token, bytes, logprob, top_logprobs }
text: string
模型输出的文本内容。
type: "output_text" (default: "output_text")
输出文本类型,固定为 output_text。
type: "multi_agent_call_output" (default: "multi_agent_call_output")
多智能体结果的类型,固定为 multi_agent_call_output。
"multi_agent_call_output"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
ToolSearchCall object { id, arguments, call_id, 5 more }
id: string
工具搜索调用条目的唯一 ID。
arguments: unknown
工具搜索调用所用的参数。
call_id: string or null
模型生成的工具搜索调用的唯一 ID。
execution: "server" or "client"
工具搜索由服务端还是客户端执行。
"server"
"client"
status: "in_progress" or "completed" or "incomplete"
已记录的工具搜索调用条目的状态。
"in_progress"
"completed"
"incomplete"
type: "tool_search_call" (default: "tool_search_call")
条目类型,固定为 tool_search_call。
"tool_search_call"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
created_by: optional string
创建该条目的执行主体的标识。
ToolSearchOutput object { id, call_id, execution, 5 more }
id: string
工具搜索输出条目的唯一 ID。
call_id: string or null
模型生成的工具搜索调用的唯一 ID。
execution: "server" or "client"
工具搜索由服务端还是客户端执行。
"server"
"client"
status: "in_progress" or "completed" or "incomplete"
已记录的工具搜索输出条目的状态。
"in_progress"
"completed"
"incomplete"
tools: array of Function { name, parameters, strict, 6 more } or FileSearch { type, vector_store_ids, filters, 2 more } or Computer { type } or 13 more
工具搜索返回的已加载工具定义。
Function object { name, parameters, strict, 6 more }
定义模型可以选择调用的自有代码函数。参阅函数调用。
name: string
要调用的函数名称。
parameters: map[unknown] or null
描述函数参数的 JSON Schema 对象。
strict: boolean or null
是否对此函数工具强制执行严格参数校验。
type: "function" (default: "function")
函数工具类型,固定为 function。
"function"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
"direct"
"programmatic"
async: optional boolean
defer_loading: optional boolean
此函数是否延迟加载并通过工具搜索加载。
description: optional string or null
函数描述,模型据此判断是否调用该函数。
output_schema: optional map[unknown] or null
描述此函数字符串输出中编码的 JSON 值的 JSON Schema 对象。
FileSearch object { type, vector_store_ids, filters, 2 more }
搜索已上传文件中相关内容的工具。参阅文件搜索工具。
type: "file_search" (default: "file_search")
文件搜索工具类型,固定为 file_search。
"file_search"
vector_store_ids: array of string
要搜索的向量存储 ID 列表。
filters: optional ComparisonFilter { key, type, value } or unknown or null
要应用的筛选条件。
ComparisonFilter object { key, type, value }
使用指定比较运算,将某个属性键与给定值比较的筛选条件。
key: string
要与值比较的属性键。
type: "eq" or "ne" or "gt" or 5 more (default: "eq")
指定比较运算符:eq、ne、gt、gte、lt、lte、in、nin。
eq:等于。ne:不等于。gt:大于。gte:大于或等于。lt:小于。lte:小于或等于。in:属于。nin:不属于。
"eq"
"ne"
"gt"
"gte"
"lt"
"lte"
"in"
"nin"
value: string or number or boolean or array of string or number
用于与属性键比较的值,支持字符串、数字或布尔类型。
string
number
boolean
array of string or number
string
number
BetaCompoundFilter = unknown
使用 and 或 or 组合多个筛选条件。
max_num_results: optional integer
返回结果数量上限,须介于 1–50 之间,含边界。
ranking_options: optional object { hybrid_search, ranker, score_threshold }
搜索结果的排序选项。
hybrid_search: optional object { embedding_weight, text_weight }
启用混合搜索时,控制倒数排名融合如何平衡语义嵌入匹配与稀疏关键词匹配的权重。
embedding_weight: number
嵌入在倒数排名融合中的权重。
text_weight: number
文本在倒数排名融合中的权重。
ranker: optional "auto" or "default-2024-11-15"
文件搜索所用的排序器。
"auto"
"default-2024-11-15"
score_threshold: optional number
文件搜索的分数阈值,为 0–1 之间的数字。越接近 1,越倾向于只返回最相关的结果,但返回数量可能减少。
Computer object { type }
控制虚拟计算机的工具。参阅计算机工具。
type: "computer" (default: "computer")
计算机工具类型,固定为 computer。
"computer"
ComputerUsePreview object { display_height, display_width, environment, type }
控制虚拟计算机的工具。参阅计算机工具。
display_height: integer
计算机显示区域的高度。
display_width: integer
计算机显示区域的宽度。
environment: "windows" or "mac" or "linux" or 2 more
要控制的计算机环境类型。
"windows"
"mac"
"linux"
"ubuntu"
"browser"
type: "computer_use_preview" (default: "computer_use_preview")
计算机使用工具类型,固定为 computer_use_preview。
"computer_use_preview"
WebSearch object { type, external_web_access, filters, 2 more }
在互联网搜索与提示词相关的来源,详见网页搜索工具。
type: "web_search" or "web_search_2025_08_26" (default: "web_search")
网页搜索工具类型,可选 web_search 或 web_search_2025_08_26。
"web_search"
"web_search_2025_08_26"
external_web_access: optional boolean (default: true)
是否允许网页搜索实时访问互联网。省略时默认为 true。设为 false 时,网页搜索工具以离线或仅缓存模式运行,不会抓取新的外部内容。
filters: optional object { allowed_domains } or null
搜索的筛选条件。
allowed_domains: optional array of string or null (default: [])
搜索允许访问的域名。不提供时允许所有域名,所列域名的子域名也允许访问。
示例:["pubmed.ncbi.nlm.nih.gov"]
search_context_size: optional "low" or "medium" or "high" (default: "medium")
对搜索占用上下文窗口空间大小的总体指导,可选 low、medium 或 high,默认为 medium。
"low"
"medium"
"high"
user_location: optional object { city, country, region, 2 more } or null
用户的大致位置。省略或设为 null 时默认为美国。若要避免此默认值,可传入不包含位置字段的 {"type": "approximate"}。若要本地化结果,须提供相应位置字段。
city: optional string or null
用户所在城市的自由文本,例如 San Francisco。
country: optional string or null
用户所在国家/地区的两字母 ISO 代码,例如 US。
region: optional string or null
用户所在地区的自由文本,例如 California。
timezone: optional string or null
用户所在的 IANA 时区,例如 America/Los_Angeles。
type: optional "approximate" (default: "approximate")
位置估算类型,固定为 approximate。
"approximate"
Mcp object { server_label, type, allowed_callers, 9 more }
通过远程模型上下文协议(MCP)服务器向模型提供更多工具,详见MCP说明。
server_label: string
此 MCP 服务器的标签,用于在工具调用中标识服务器。
type: "mcp"
MCP 工具类型,固定为 mcp。
"mcp"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
minItems: 1
"direct"
"programmatic"
allowed_tools: optional array of string or McpToolFilter { read_only, tool_names } or null
允许的工具名称列表或筛选对象。
McpAllowedTools = array of string
允许的工具名称组成的字符串数组。
McpToolFilter object { read_only, tool_names }
用于指定允许哪些工具的筛选对象。
read_only: optional boolean
说明工具会修改数据还是仅执行只读操作。如果MCP服务器标注了readOnlyHint,就会匹配这个筛选条件。
tool_names: optional array of string
允许的工具名称列表。
authorization: optional string
用于远程MCP服务器的OAuth访问令牌,既可用于自定义MCP服务器URL,也可用于服务连接器。应用须处理OAuth授权流程,并在此提供令牌。
connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more
服务连接器的标识,例如ChatGPT中的连接器。server_url、connector_id、tunnel_id须提供其一,详见服务连接器。
此字段在2026年9月1日之后发布的模型中已弃用。远程MCP服务器改用server_url,安全MCP隧道连接改用tunnel_id。
当前支持的 connector_id 值如下:
Dropbox:connector_dropbox;Gmail:connector_gmail;Google Calendar:connector_googlecalendar;Google Drive:connector_googledrive;Microsoft Teams:connector_microsoftteams;Outlook Calendar:connector_outlookcalendar;Outlook Email:connector_outlookemail;SharePoint:connector_sharepoint。
"connector_dropbox"
"connector_gmail"
"connector_googlecalendar"
"connector_googledrive"
"connector_microsoftteams"
"connector_outlookcalendar"
"connector_outlookemail"
"connector_sharepoint"
defer_loading: optional boolean
此 MCP 工具是否延迟加载并通过工具搜索发现。
headers: optional map[string] or null
发送给MCP服务器的可选HTTP请求头,用于身份验证或其他目的。
require_approval: optional McpToolApprovalFilter { always, never } or "always" or "never" or null (default: "always")
指定 MCP 服务器的哪些工具需要批准。
McpToolApprovalFilter object { always, never }
指定哪些工具需要批准,可选always、never或筛选对象。
always: optional object { read_only, tool_names }
用于指定允许哪些工具的筛选对象。
read_only: optional boolean
说明工具会修改数据还是仅执行只读操作。如果MCP服务器标注了readOnlyHint,就会匹配这个筛选条件。
tool_names: optional array of string
允许的工具名称列表。
never: optional object { read_only, tool_names }
用于指定允许哪些工具的筛选对象。
read_only: optional boolean
说明工具会修改数据还是仅执行只读操作。如果MCP服务器标注了readOnlyHint,就会匹配这个筛选条件。
tool_names: optional array of string
允许的工具名称列表。
McpToolApprovalSetting = "always" or "never"
为所有工具统一指定批准策略,可选always或never。always要求所有工具获得批准,never表示工具无需批准。
"always"
"never"
server_description: optional string
MCP 服务器的可选描述,用于提供更多上下文。
server_url: optional string
MCP服务器URL。server_url、connector_id、tunnel_id三者必须提供其一。
format: uri
tunnel_id: optional string
替代直接服务器URL的安全MCP隧道ID。server_url、connector_id、tunnel_id三者必须提供其一。
pattern: ^tunnel_[a-z0-9]{32}$
CodeInterpreter object { container, type, allowed_callers }
运行 Python 代码以帮助生成提示词响应的工具。
container: string or CodeInterpreterToolAuto { type, file_ids, memory_limit, network_policy }
代码解释器容器,可指定容器ID,或指定包含已上传文件ID的对象,以及可选的memory_limit设置。
string
容器 ID。
CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }
代码解释器容器配置,可以指定运行代码时所处理的文件 ID。
type: "auto" (default: "auto")
固定为 auto。
"auto"
file_ids: optional array of string
可选的已上传文件列表,这些文件将提供给代码使用。
maxItems: 50
memory_limit: optional "1g" or "4g" or "16g" or "64g" or null
代码解释器容器的内存上限。
"1g"
"4g"
"16g"
"64g"
network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist
容器的网络访问策略。
BetaContainerNetworkPolicyDisabled object { type }
type: "disabled" (default: "disabled")
禁用出站网络访问,固定为 disabled。
"disabled"
BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }
allowed_domains: array of string
type 为 allowlist 时允许访问的域名列表。
minItems: 1
type: "allowlist" (default: "allowlist")
仅允许对指定域名发起出站网络访问,固定为 allowlist。
"allowlist"
domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret
可选的仅用于允许访问域名的域名级密钥。
minItems: 1
domain: string
密钥关联的域名。
minLength: 1
name: string
要为该域名注入的密钥名称。
minLength: 1
value: string
要为该域名注入的密钥值。
minLength: 1, maxLength: 10485760
type: "code_interpreter"
代码解释器工具类型,固定为 code_interpreter。
"code_interpreter"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
minItems: 1
"direct"
"programmatic"
ProgrammaticToolCalling object { type }
type: "programmatic_tool_calling" (default: "programmatic_tool_calling")
工具类型,固定为 programmatic_tool_calling。
"programmatic_tool_calling"
ImageGeneration object { type, action, background, 13 more }
使用 GPT 图像模型生成图像的工具。
type: "image_generation"
图像生成工具类型,固定为 image_generation。
"image_generation"
action: optional "generate" or "edit" or "auto"
生成新图像还是编辑已有图像,默认为 auto。
"generate"
"edit"
"auto"
background: optional "transparent" or "opaque" or "auto" (default: "auto")
生成图像的背景,可选transparent、opaque或auto。gpt-image-2.5-sunburst、gpt-image-2.5-flare及其2026-09-08快照支持不透明和透明背景;gpt-image-2的透明背景为预览能力。使用transparent时,输出格式须设为png或webp。默认为auto。
"transparent"
"opaque"
"auto"
complexity: optional "low" or "medium" or "high"
图像规划使用的计算量,独立于渲染质量。生成图像时,此设置覆盖外层响应的 reasoning.effort。省略时会继承外层支持的推理强度,或使用图像模型配置的默认值。生成 SVG 时,此设置控制参考图像的规划计算量,SVG 作者模型使用自己的推理设置。
"low"
"medium"
"high"
frame_count: optional integer (default: 9)
GIF 帧数,要求 output_format 为 gif,默认为 9。
minimum: 2, maximum: 16
frame_duration_ms: optional integer (default: 200)
GIF 每帧的时长,以毫秒计,四舍五入到 10 毫秒。要求 output_format 为 gif。默认值为 200。
minimum: 20, maximum: 2000
input_fidelity: optional "high" or "low" or null
控制模型为匹配输入图像风格和特征(尤其是面部特征)投入的程度。gpt-image-1.5 支持 high 和 low,gpt-image-1-mini 仅支持 low。使用 gpt-image-2 时应省略此参数。支持该参数的模型默认为 low。
"high"
"low"
input_image_mask: optional object { file_id, image_url }
可选的局部重绘蒙版,包含可选image_url字符串和可选file_id字符串。
file_id: optional string
蒙版图像的文件 ID。
image_url: optional string
采用 Base64 编码的蒙版图像。
model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 9 more
生成图像的模型。可用值为 gpt-image-1-mini、gpt-image-1.5、gpt-image-2、gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare、gpt-image-2.5-flare-2026-09-08、gpt-image-2.6-sunburst、gpt-image-2.6-flare 或 chatgpt-image-latest。默认值为 gpt-image-2.6-sunburst。
gpt-image-1 已于 2026 年 10 月 23 日停用,可改用 gpt-image-2.5-sunburst 或 gpt-image-2.5-flare。
string
"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 9 more
生成图像的模型。可用值为 gpt-image-1-mini、gpt-image-1.5、gpt-image-2、gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare、gpt-image-2.5-flare-2026-09-08、gpt-image-2.6-sunburst、gpt-image-2.6-flare 或 chatgpt-image-latest。默认值为 gpt-image-2.6-sunburst。
gpt-image-1 已于 2026 年 10 月 23 日停用,可改用 gpt-image-2.5-sunburst 或 gpt-image-2.5-flare。
"gpt-image-1"
"gpt-image-1-mini"
"gpt-image-2"
"gpt-image-2-2026-04-21"
"gpt-image-2.5-sunburst"
"gpt-image-2.5-sunburst-2026-09-08"
"gpt-image-2.5-flare"
"gpt-image-2.5-flare-2026-09-08"
"gpt-image-2.6-sunburst"
"gpt-image-2.6-flare"
"gpt-image-1.5"
"chatgpt-image-latest"
moderation: optional "auto" or "low" (default: "auto")
生成图像的审核级别,默认为 auto。
"auto"
"low"
output_compression: optional integer (default: 100)
输出图像的压缩级别,默认为 100。
minimum: 0, maximum: 100
output_format: optional "png" or "webp" or "jpeg" or 2 more (default: "png")
生成图像的格式。可选 png、webp、jpeg、gif 或 svg,默认值为 png。GIF 和 SVG 要求模型支持对应格式。GIF 不支持部分图像流式输出(partial_images 大于 0)、input_image_mask 或自定义 output_compression。Responses 生命周期事件仍可流式返回。
"png"
"webp"
"jpeg"
"gif"
"svg"
partial_images: optional integer (default: 0)
流式模式中生成的部分图像数量,范围为 0(默认值)到 3。
minimum: 0, maximum: 3
quality: optional "low" or "medium" or "high" or 3 more (default: "auto")
生成图像的质量。GPT图像模型支持low、medium、high;gpt-image-2.5-sunburst、gpt-image-2.5-flare及其2026-09-08快照还支持xhigh和max。默认为auto。
"low"
"medium"
"high"
"xhigh"
"max"
"auto"
size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto" (default: "auto")
生成图像的尺寸。gpt-image-2、gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare 和 gpt-image-2.5-flare-2026-09-08 支持以 WIDTHxHEIGHT 字符串指定任意分辨率,例如 1536x864。宽和高均须能被 16 整除,宽高比须在 1:3 至 3:1 之间。高于 2560x1440 的分辨率属于实验功能,支持的最高分辨率为 3840x2160。尺寸还须符合模型当前的像素数与边长限制。GPT Image 模型支持标准尺寸 1024x1024、1536x1024 和 1024x1536;允许自动尺寸的模型支持 auto。
string
"1024x1024" or "1024x1536" or "1536x1024" or "auto"
生成图像的尺寸。gpt-image-2、gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare 和 gpt-image-2.5-flare-2026-09-08 支持以 WIDTHxHEIGHT 字符串指定任意分辨率,例如 1536x864。宽和高均须能被 16 整除,宽高比须在 1:3 至 3:1 之间。高于 2560x1440 的分辨率属于实验功能,支持的最高分辨率为 3840x2160。尺寸还须符合模型当前的像素数与边长限制。GPT Image 模型支持标准尺寸 1024x1024、1536x1024 和 1024x1536;允许自动尺寸的模型支持 auto。
"1024x1024"
"1024x1536"
"1536x1024"
"auto"
svg: optional object { model, reasoning }
SVG 作者模型设置。要求 output_format 为 svg。启用 SVG 模型选择时,省略此对象将使用外层响应模型。其他情况下会使用默认 SVG 作者模型,且无法显式覆盖。
model: optional string
minLength: 1
reasoning: optional object { effort } or null
SVG 编写的推理强度。省略时,Images 和 Responses 均使用编写模型的默认值。
effort: optional "none" or "minimal" or "low" or 4 more
控制模型为此次请求投入的推理强度。
"none"
"minimal"
"low"
"medium"
"high"
"xhigh"
"max"
LocalShell object { type }
允许模型在本地环境执行 shell 命令的工具。
type: "local_shell" (default: "local_shell")
本地 shell 工具类型,固定为 local_shell。
"local_shell"
Shell object { type, allowed_callers, environment }
允许模型执行 shell 命令的工具。
type: "shell" (default: "shell")
shell 工具类型,固定为 shell。
"shell"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
minItems: 1
"direct"
"programmatic"
environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference or null
BetaContainerAuto object { type, file_ids, memory_limit, 2 more }
type: "container_auto" (default: "container_auto")
为此请求自动创建容器。
"container_auto"
file_ids: optional array of string
可选的已上传文件列表,这些文件将提供给代码使用。
maxItems: 50
memory_limit: optional "1g" or "4g" or "16g" or "64g" or null
容器的内存上限。
"1g"
"4g"
"16g"
"64g"
network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist
容器的网络访问策略。
BetaContainerNetworkPolicyDisabled object { type }
BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }
skills: optional array of BetaSkillReference or BetaInlineSkill
可选技能列表,支持按 ID 引用或传入内联数据。列表中所有内联技能解码后的 ZIP 数据合计最多 50 MiB,Base64 文本含换行在内合计最多 70,254,592 个字符。技能引用不计入限制。
maxItems: 200
BetaSkillReference object { skill_id, type, version }
skill_id: string
引用的技能 ID。
minLength: 1, maxLength: 64
type: "skill_reference" (default: "skill_reference")
引用通过 /v1/skills 接口创建的技能。
"skill_reference"
version: optional string
可选的技能版本。使用正整数或 'latest',省略时使用默认版本。
BetaInlineSkill object { description, name, source, type }
description: string
技能描述。
name: string
技能名称。
source: BetaInlineSkillSource
内联技能载荷。
data: string
采用 Base64 编码的技能 ZIP 包。
minLength: 1, maxLength: 70254592
media_type: "application/zip" (default: "application/zip")
内联技能载荷的媒体类型,必须为 application/zip。
"application/zip"
type: "base64" (default: "base64")
内联技能来源的类型,必须为 base64。
"base64"
type: "inline" (default: "inline")
为此请求定义内联技能。
"inline"
BetaLocalEnvironment object { type, skills }
type: "local" (default: "local")
使用本地计算机环境。
"local"
skills: optional array of BetaLocalSkill
可选的技能列表。
maxItems: 200
description: string
技能描述。
name: string
技能名称。
path: string
包含该技能的目录路径。
BetaContainerReference object { container_id, type }
container_id: string
引用的容器 ID。
type: "container_reference" (default: "container_reference")
引用通过 /v1/containers 接口创建的容器。
"container_reference"
Custom object { name, type, allowed_callers, 4 more }
使用指定格式处理输入的自定义工具。参阅自定义工具。
name: string
自定义工具的名称,用于在工具调用中标识它。
type: "custom" (default: "custom")
自定义工具类型,固定为 custom。
"custom"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
minItems: 1
"direct"
"programmatic"
async: optional boolean
工具响应是否可以异步返回,而非在下一次创建响应时立即返回。
defer_loading: optional boolean
此工具是否应延迟加载并通过工具搜索发现。
description: optional string
自定义工具的可选描述,用于提供更多上下文。
format: optional Text { type } or Grammar { definition, syntax, type }
自定义工具的输入格式,默认为无约束文本。
Text object { type }
无约束的自由文本。
type: "text" (default: "text")
无约束文本格式,固定为 text。
"text"
Grammar object { definition, syntax, type }
用户定义的语法。
definition: string
语法定义。
syntax: "lark" or "regex"
语法定义的语法类型,可选 lark 或 regex。
"lark"
"regex"
type: "grammar" (default: "grammar")
语法格式,固定为 grammar。
"grammar"
Namespace object { description, name, tools, type }
将函数工具或自定义工具归入共享命名空间。
description: string
展示给模型的命名空间描述。
name: string
工具调用使用的命名空间名称,例如 crm。
minLength: 1
tools: array of Function { name, type, allowed_callers, 6 more } or Custom { name, type, allowed_callers, 4 more }
此命名空间内可用的函数工具或自定义工具。
minItems: 1
Function object { name, type, allowed_callers, 6 more }
name: string
pattern: ^[a-zA-Z0-9_-]+$, minLength: 1, maxLength: 128
type: "function" (default: "function")
"function"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
minItems: 1
"direct"
"programmatic"
async: optional boolean
工具响应是否可以异步返回,而非在下一次创建响应时立即返回。
defer_loading: optional boolean
此函数是否应延迟加载并通过工具搜索发现。
description: optional string or null
output_schema: optional map[unknown] or null
描述此函数工具字符串输出中编码的 JSON 值的 JSON Schema,不用于描述内容数组输出。
parameters: optional unknown or null
strict: optional boolean or null
是否强制执行严格参数校验。省略时,模式兼容的情况下 Responses 会尝试严格校验,否则退回非严格校验。
Custom object { name, type, allowed_callers, 4 more }
使用指定格式处理输入的自定义工具。参阅自定义工具。
name: string
自定义工具的名称,用于在工具调用中标识它。
type: "custom" (default: "custom")
自定义工具类型,固定为 custom。
"custom"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
minItems: 1
"direct"
"programmatic"
async: optional boolean
工具响应是否可以异步返回,而非在下一次创建响应时立即返回。
defer_loading: optional boolean
此工具是否应延迟加载并通过工具搜索发现。
description: optional string
自定义工具的可选描述,用于提供更多上下文。
format: optional Text { type } or Grammar { definition, syntax, type }
自定义工具的输入格式,默认为无约束文本。
Text object { type }
无约束的自由文本。
type: "text" (default: "text")
无约束文本格式,固定为 text。
"text"
Grammar object { definition, syntax, type }
用户定义的语法。
definition: string
语法定义。
syntax: "lark" or "regex"
语法定义的语法类型,可选 lark 或 regex。
"lark"
"regex"
type: "grammar" (default: "grammar")
语法格式,固定为 grammar。
"grammar"
type: "namespace" (default: "namespace")
工具类型,固定为 namespace。
"namespace"
ToolSearch object { type, description, execution, parameters }
用于延迟加载工具的托管工具搜索或自带工具(BYOT)搜索配置。
type: "tool_search" (default: "tool_search")
工具类型,固定为 tool_search。
"tool_search"
description: optional string or null
客户端执行的工具搜索工具展示给模型的描述。
execution: optional "server" or "client"
工具搜索由服务端还是客户端执行。
"server"
"client"
parameters: optional unknown or null
客户端执行的工具搜索工具的参数模式。
WebSearchPreview object { type, search_content_types, search_context_size, user_location }
搜索网页以获取可用于响应的相关结果的工具。参阅网页搜索工具。
type: "web_search_preview" or "web_search_preview_2025_03_11" (default: "web_search_preview")
网页搜索工具类型,可选 web_search_preview 或 web_search_preview_2025_03_11。
"web_search_preview"
"web_search_preview_2025_03_11"
search_content_types: optional array of "text" or "image"
"text"
"image"
search_context_size: optional "low" or "medium" or "high"
对搜索占用上下文窗口空间大小的总体指导,可选 low、medium 或 high,默认为 medium。
"low"
"medium"
"high"
user_location: optional object { type, city, country, 2 more } or null
用户的大致位置。省略或设为 null 时默认为美国。若要避免此默认值,可传入不包含位置字段的 {"type": "approximate"}。若要本地化结果,须提供相应位置字段。
type: "approximate" (default: "approximate")
位置估算类型,固定为 approximate。
"approximate"
city: optional string or null
用户所在城市的自由文本,例如 San Francisco。
country: optional string or null
用户所在国家/地区的两字母 ISO 代码,例如 US。
region: optional string or null
用户所在地区的自由文本,例如 California。
timezone: optional string or null
用户所在的 IANA 时区,例如 America/Los_Angeles。
ApplyPatch object { type, allowed_callers }
允许助手使用统一差异格式创建、删除或更新文件。
type: "apply_patch" (default: "apply_patch")
工具类型,固定为 apply_patch。
"apply_patch"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
minItems: 1
"direct"
"programmatic"
type: "tool_search_output" (default: "tool_search_output")
条目类型,固定为 tool_search_output。
"tool_search_output"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
created_by: optional string
创建该条目的执行主体的标识。
AdditionalTools object { id, role, tools, 2 more }
id: string
额外工具条目的唯一 ID。
role: "unknown" or "user" or "assistant" or 5 more
提供额外工具的角色。
"unknown"
"user"
"assistant"
"system"
"critic"
"discriminator"
"developer"
"tool"
tools: array of Function { name, parameters, strict, 6 more } or FileSearch { type, vector_store_ids, filters, 2 more } or Computer { type } or 13 more
此条目中提供的额外工具定义。
Function object { name, parameters, strict, 6 more }
定义模型可以选择调用的自有代码函数。参阅函数调用。
name: string
要调用的函数名称。
parameters: map[unknown] or null
描述函数参数的 JSON Schema 对象。
strict: boolean or null
是否对此函数工具强制执行严格参数校验。
type: "function" (default: "function")
函数工具类型,固定为 function。
"function"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
"direct"
"programmatic"
async: optional boolean
defer_loading: optional boolean
此函数是否延迟加载并通过工具搜索加载。
description: optional string or null
函数描述,模型据此判断是否调用该函数。
output_schema: optional map[unknown] or null
描述此函数字符串输出中编码的 JSON 值的 JSON Schema 对象。
FileSearch object { type, vector_store_ids, filters, 2 more }
搜索已上传文件中相关内容的工具。参阅文件搜索工具。
type: "file_search" (default: "file_search")
文件搜索工具类型,固定为 file_search。
"file_search"
vector_store_ids: array of string
要搜索的向量存储 ID 列表。
filters: optional ComparisonFilter { key, type, value } or unknown or null
要应用的筛选条件。
ComparisonFilter object { key, type, value }
使用指定比较运算,将某个属性键与给定值比较的筛选条件。
key: string
要与值比较的属性键。
type: "eq" or "ne" or "gt" or 5 more (default: "eq")
指定比较运算符:eq、ne、gt、gte、lt、lte、in、nin。
eq:等于。ne:不等于。gt:大于。gte:大于或等于。lt:小于。lte:小于或等于。in:属于。nin:不属于。
"eq"
"ne"
"gt"
"gte"
"lt"
"lte"
"in"
"nin"
value: string or number or boolean or array of string or number
用于与属性键比较的值,支持字符串、数字或布尔类型。
string
number
boolean
array of string or number
string
number
BetaCompoundFilter = unknown
使用 and 或 or 组合多个筛选条件。
max_num_results: optional integer
返回结果数量上限,须介于 1–50 之间,含边界。
ranking_options: optional object { hybrid_search, ranker, score_threshold }
搜索结果的排序选项。
hybrid_search: optional object { embedding_weight, text_weight }
启用混合搜索时,控制倒数排名融合如何平衡语义嵌入匹配与稀疏关键词匹配的权重。
embedding_weight: number
嵌入在倒数排名融合中的权重。
text_weight: number
文本在倒数排名融合中的权重。
ranker: optional "auto" or "default-2024-11-15"
文件搜索所用的排序器。
"auto"
"default-2024-11-15"
score_threshold: optional number
文件搜索的分数阈值,为 0–1 之间的数字。越接近 1,越倾向于只返回最相关的结果,但返回数量可能减少。
Computer object { type }
控制虚拟计算机的工具。参阅计算机工具。
type: "computer" (default: "computer")
计算机工具类型,固定为 computer。
"computer"
ComputerUsePreview object { display_height, display_width, environment, type }
控制虚拟计算机的工具。参阅计算机工具。
display_height: integer
计算机显示区域的高度。
display_width: integer
计算机显示区域的宽度。
environment: "windows" or "mac" or "linux" or 2 more
要控制的计算机环境类型。
"windows"
"mac"
"linux"
"ubuntu"
"browser"
type: "computer_use_preview" (default: "computer_use_preview")
计算机使用工具类型,固定为 computer_use_preview。
"computer_use_preview"
WebSearch object { type, external_web_access, filters, 2 more }
在互联网搜索与提示词相关的来源,详见网页搜索工具。
type: "web_search" or "web_search_2025_08_26" (default: "web_search")
网页搜索工具类型,可选 web_search 或 web_search_2025_08_26。
"web_search"
"web_search_2025_08_26"
external_web_access: optional boolean (default: true)
是否允许网页搜索实时访问互联网。省略时默认为 true。设为 false 时,网页搜索工具以离线或仅缓存模式运行,不会抓取新的外部内容。
filters: optional object { allowed_domains } or null
搜索的筛选条件。
allowed_domains: optional array of string or null (default: [])
搜索允许访问的域名。不提供时允许所有域名,所列域名的子域名也允许访问。
示例:["pubmed.ncbi.nlm.nih.gov"]
search_context_size: optional "low" or "medium" or "high" (default: "medium")
对搜索占用上下文窗口空间大小的总体指导,可选 low、medium 或 high,默认为 medium。
"low"
"medium"
"high"
user_location: optional object { city, country, region, 2 more } or null
用户的大致位置。省略或设为 null 时默认为美国。若要避免此默认值,可传入不包含位置字段的 {"type": "approximate"}。若要本地化结果,须提供相应位置字段。
city: optional string or null
用户所在城市的自由文本,例如 San Francisco。
country: optional string or null
用户所在国家/地区的两字母 ISO 代码,例如 US。
region: optional string or null
用户所在地区的自由文本,例如 California。
timezone: optional string or null
用户所在的 IANA 时区,例如 America/Los_Angeles。
type: optional "approximate" (default: "approximate")
位置估算类型,固定为 approximate。
"approximate"
Mcp object { server_label, type, allowed_callers, 9 more }
通过远程模型上下文协议(MCP)服务器向模型提供更多工具,详见MCP说明。
server_label: string
此 MCP 服务器的标签,用于在工具调用中标识服务器。
type: "mcp"
MCP 工具类型,固定为 mcp。
"mcp"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
minItems: 1
"direct"
"programmatic"
allowed_tools: optional array of string or McpToolFilter { read_only, tool_names } or null
允许的工具名称列表或筛选对象。
McpAllowedTools = array of string
允许的工具名称组成的字符串数组。
McpToolFilter object { read_only, tool_names }
用于指定允许哪些工具的筛选对象。
read_only: optional boolean
说明工具会修改数据还是仅执行只读操作。如果MCP服务器标注了readOnlyHint,就会匹配这个筛选条件。
tool_names: optional array of string
允许的工具名称列表。
authorization: optional string
用于远程MCP服务器的OAuth访问令牌,既可用于自定义MCP服务器URL,也可用于服务连接器。应用须处理OAuth授权流程,并在此提供令牌。
connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more
服务连接器的标识,例如ChatGPT中的连接器。server_url、connector_id、tunnel_id须提供其一,详见服务连接器。
此字段在2026年9月1日之后发布的模型中已弃用。远程MCP服务器改用server_url,安全MCP隧道连接改用tunnel_id。
当前支持的 connector_id 值如下:
Dropbox:connector_dropbox;Gmail:connector_gmail;Google Calendar:connector_googlecalendar;Google Drive:connector_googledrive;Microsoft Teams:connector_microsoftteams;Outlook Calendar:connector_outlookcalendar;Outlook Email:connector_outlookemail;SharePoint:connector_sharepoint。
"connector_dropbox"
"connector_gmail"
"connector_googlecalendar"
"connector_googledrive"
"connector_microsoftteams"
"connector_outlookcalendar"
"connector_outlookemail"
"connector_sharepoint"
defer_loading: optional boolean
此 MCP 工具是否延迟加载并通过工具搜索发现。
headers: optional map[string] or null
发送给MCP服务器的可选HTTP请求头,用于身份验证或其他目的。
require_approval: optional McpToolApprovalFilter { always, never } or "always" or "never" or null (default: "always")
指定 MCP 服务器的哪些工具需要批准。
McpToolApprovalFilter object { always, never }
指定哪些工具需要批准,可选always、never或筛选对象。
always: optional object { read_only, tool_names }
用于指定允许哪些工具的筛选对象。
read_only: optional boolean
说明工具会修改数据还是仅执行只读操作。如果MCP服务器标注了readOnlyHint,就会匹配这个筛选条件。
tool_names: optional array of string
允许的工具名称列表。
never: optional object { read_only, tool_names }
用于指定允许哪些工具的筛选对象。
read_only: optional boolean
说明工具会修改数据还是仅执行只读操作。如果MCP服务器标注了readOnlyHint,就会匹配这个筛选条件。
tool_names: optional array of string
允许的工具名称列表。
McpToolApprovalSetting = "always" or "never"
为所有工具统一指定批准策略,可选always或never。always要求所有工具获得批准,never表示工具无需批准。
"always"
"never"
server_description: optional string
MCP 服务器的可选描述,用于提供更多上下文。
server_url: optional string
MCP服务器URL。server_url、connector_id、tunnel_id三者必须提供其一。
format: uri
tunnel_id: optional string
替代直接服务器URL的安全MCP隧道ID。server_url、connector_id、tunnel_id三者必须提供其一。
pattern: ^tunnel_[a-z0-9]{32}$
CodeInterpreter object { container, type, allowed_callers }
运行 Python 代码以帮助生成提示词响应的工具。
container: string or CodeInterpreterToolAuto { type, file_ids, memory_limit, network_policy }
代码解释器容器,可指定容器ID,或指定包含已上传文件ID的对象,以及可选的memory_limit设置。
string
容器 ID。
CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }
代码解释器容器配置,可以指定运行代码时所处理的文件 ID。
type: "auto" (default: "auto")
固定为 auto。
"auto"
file_ids: optional array of string
可选的已上传文件列表,这些文件将提供给代码使用。
maxItems: 50
memory_limit: optional "1g" or "4g" or "16g" or "64g" or null
代码解释器容器的内存上限。
"1g"
"4g"
"16g"
"64g"
network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist
容器的网络访问策略。
BetaContainerNetworkPolicyDisabled object { type }
BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }
type: "code_interpreter"
代码解释器工具类型,固定为 code_interpreter。
"code_interpreter"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
minItems: 1
"direct"
"programmatic"
ProgrammaticToolCalling object { type }
type: "programmatic_tool_calling" (default: "programmatic_tool_calling")
工具类型,固定为 programmatic_tool_calling。
"programmatic_tool_calling"
ImageGeneration object { type, action, background, 13 more }
使用 GPT 图像模型生成图像的工具。
type: "image_generation"
图像生成工具类型,固定为 image_generation。
"image_generation"
action: optional "generate" or "edit" or "auto"
生成新图像还是编辑已有图像,默认为 auto。
"generate"
"edit"
"auto"
background: optional "transparent" or "opaque" or "auto" (default: "auto")
生成图像的背景,可选transparent、opaque或auto。gpt-image-2.5-sunburst、gpt-image-2.5-flare及其2026-09-08快照支持不透明和透明背景;gpt-image-2的透明背景为预览能力。使用transparent时,输出格式须设为png或webp。默认为auto。
"transparent"
"opaque"
"auto"
complexity: optional "low" or "medium" or "high"
图像规划使用的计算量,独立于渲染质量。生成图像时,此设置覆盖外层响应的 reasoning.effort。省略时会继承外层支持的推理强度,或使用图像模型配置的默认值。生成 SVG 时,此设置控制参考图像的规划计算量,SVG 作者模型使用自己的推理设置。
"low"
"medium"
"high"
frame_count: optional integer (default: 9)
GIF 帧数,要求 output_format 为 gif,默认为 9。
minimum: 2, maximum: 16
frame_duration_ms: optional integer (default: 200)
GIF 每帧的时长,以毫秒计,四舍五入到 10 毫秒。要求 output_format 为 gif。默认值为 200。
minimum: 20, maximum: 2000
input_fidelity: optional "high" or "low" or null
控制模型为匹配输入图像风格和特征(尤其是面部特征)投入的程度。gpt-image-1.5 支持 high 和 low,gpt-image-1-mini 仅支持 low。使用 gpt-image-2 时应省略此参数。支持该参数的模型默认为 low。
"high"
"low"
input_image_mask: optional object { file_id, image_url }
可选的局部重绘蒙版,包含可选image_url字符串和可选file_id字符串。
file_id: optional string
蒙版图像的文件 ID。
image_url: optional string
采用 Base64 编码的蒙版图像。
model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 9 more
生成图像的模型。可用值为 gpt-image-1-mini、gpt-image-1.5、gpt-image-2、gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare、gpt-image-2.5-flare-2026-09-08、gpt-image-2.6-sunburst、gpt-image-2.6-flare 或 chatgpt-image-latest。默认值为 gpt-image-2.6-sunburst。
gpt-image-1 已于 2026 年 10 月 23 日停用,可改用 gpt-image-2.5-sunburst 或 gpt-image-2.5-flare。
string
"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 9 more
生成图像的模型。可用值为 gpt-image-1-mini、gpt-image-1.5、gpt-image-2、gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare、gpt-image-2.5-flare-2026-09-08、gpt-image-2.6-sunburst、gpt-image-2.6-flare 或 chatgpt-image-latest。默认值为 gpt-image-2.6-sunburst。
gpt-image-1 已于 2026 年 10 月 23 日停用,可改用 gpt-image-2.5-sunburst 或 gpt-image-2.5-flare。
"gpt-image-1"
"gpt-image-1-mini"
"gpt-image-2"
"gpt-image-2-2026-04-21"
"gpt-image-2.5-sunburst"
"gpt-image-2.5-sunburst-2026-09-08"
"gpt-image-2.5-flare"
"gpt-image-2.5-flare-2026-09-08"
"gpt-image-2.6-sunburst"
"gpt-image-2.6-flare"
"gpt-image-1.5"
"chatgpt-image-latest"
moderation: optional "auto" or "low" (default: "auto")
生成图像的审核级别,默认为 auto。
"auto"
"low"
output_compression: optional integer (default: 100)
输出图像的压缩级别,默认为 100。
minimum: 0, maximum: 100
output_format: optional "png" or "webp" or "jpeg" or 2 more (default: "png")
生成图像的格式。可选 png、webp、jpeg、gif 或 svg,默认值为 png。GIF 和 SVG 要求模型支持对应格式。GIF 不支持部分图像流式输出(partial_images 大于 0)、input_image_mask 或自定义 output_compression。Responses 生命周期事件仍可流式返回。
"png"
"webp"
"jpeg"
"gif"
"svg"
partial_images: optional integer (default: 0)
流式模式中生成的部分图像数量,范围为 0(默认值)到 3。
minimum: 0, maximum: 3
quality: optional "low" or "medium" or "high" or 3 more (default: "auto")
生成图像的质量。GPT图像模型支持low、medium、high;gpt-image-2.5-sunburst、gpt-image-2.5-flare及其2026-09-08快照还支持xhigh和max。默认为auto。
"low"
"medium"
"high"
"xhigh"
"max"
"auto"
size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto" (default: "auto")
生成图像的尺寸。gpt-image-2、gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare 和 gpt-image-2.5-flare-2026-09-08 支持以 WIDTHxHEIGHT 字符串指定任意分辨率,例如 1536x864。宽和高均须能被 16 整除,宽高比须在 1:3 至 3:1 之间。高于 2560x1440 的分辨率属于实验功能,支持的最高分辨率为 3840x2160。尺寸还须符合模型当前的像素数与边长限制。GPT Image 模型支持标准尺寸 1024x1024、1536x1024 和 1024x1536;允许自动尺寸的模型支持 auto。
string
"1024x1024" or "1024x1536" or "1536x1024" or "auto"
生成图像的尺寸。gpt-image-2、gpt-image-2-2026-04-21、gpt-image-2.5-sunburst、gpt-image-2.5-sunburst-2026-09-08、gpt-image-2.5-flare 和 gpt-image-2.5-flare-2026-09-08 支持以 WIDTHxHEIGHT 字符串指定任意分辨率,例如 1536x864。宽和高均须能被 16 整除,宽高比须在 1:3 至 3:1 之间。高于 2560x1440 的分辨率属于实验功能,支持的最高分辨率为 3840x2160。尺寸还须符合模型当前的像素数与边长限制。GPT Image 模型支持标准尺寸 1024x1024、1536x1024 和 1024x1536;允许自动尺寸的模型支持 auto。
"1024x1024"
"1024x1536"
"1536x1024"
"auto"
svg: optional object { model, reasoning }
SVG 作者模型设置。要求 output_format 为 svg。启用 SVG 模型选择时,省略此对象将使用外层响应模型。其他情况下会使用默认 SVG 作者模型,且无法显式覆盖。
model: optional string
minLength: 1
reasoning: optional object { effort } or null
SVG 编写的推理强度。省略时,Images 和 Responses 均使用编写模型的默认值。
effort: optional "none" or "minimal" or "low" or 4 more
控制模型为此次请求投入的推理强度。
"none"
"minimal"
"low"
"medium"
"high"
"xhigh"
"max"
LocalShell object { type }
允许模型在本地环境执行 shell 命令的工具。
type: "local_shell" (default: "local_shell")
本地 shell 工具类型,固定为 local_shell。
"local_shell"
Shell object { type, allowed_callers, environment }
允许模型执行 shell 命令的工具。
type: "shell" (default: "shell")
shell 工具类型,固定为 shell。
"shell"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
minItems: 1
"direct"
"programmatic"
environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference or null
BetaContainerAuto object { type, file_ids, memory_limit, 2 more }
BetaLocalEnvironment object { type, skills }
BetaContainerReference object { container_id, type }
Custom object { name, type, allowed_callers, 4 more }
使用指定格式处理输入的自定义工具。参阅自定义工具。
name: string
自定义工具的名称,用于在工具调用中标识它。
type: "custom" (default: "custom")
自定义工具类型,固定为 custom。
"custom"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
minItems: 1
"direct"
"programmatic"
async: optional boolean
工具响应是否可以异步返回,而非在下一次创建响应时立即返回。
defer_loading: optional boolean
此工具是否应延迟加载并通过工具搜索发现。
description: optional string
自定义工具的可选描述,用于提供更多上下文。
format: optional Text { type } or Grammar { definition, syntax, type }
自定义工具的输入格式,默认为无约束文本。
Text object { type }
无约束的自由文本。
type: "text" (default: "text")
无约束文本格式,固定为 text。
"text"
Grammar object { definition, syntax, type }
用户定义的语法。
definition: string
语法定义。
syntax: "lark" or "regex"
语法定义的语法类型,可选 lark 或 regex。
"lark"
"regex"
type: "grammar" (default: "grammar")
语法格式,固定为 grammar。
"grammar"
Namespace object { description, name, tools, type }
将函数工具或自定义工具归入共享命名空间。
description: string
展示给模型的命名空间描述。
name: string
工具调用使用的命名空间名称,例如 crm。
minLength: 1
tools: array of Function { name, type, allowed_callers, 6 more } or Custom { name, type, allowed_callers, 4 more }
此命名空间内可用的函数工具或自定义工具。
minItems: 1
Function object { name, type, allowed_callers, 6 more }
name: string
pattern: ^[a-zA-Z0-9_-]+$, minLength: 1, maxLength: 128
type: "function" (default: "function")
"function"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
minItems: 1
"direct"
"programmatic"
async: optional boolean
工具响应是否可以异步返回,而非在下一次创建响应时立即返回。
defer_loading: optional boolean
此函数是否应延迟加载并通过工具搜索发现。
description: optional string or null
output_schema: optional map[unknown] or null
描述此函数工具字符串输出中编码的 JSON 值的 JSON Schema,不用于描述内容数组输出。
parameters: optional unknown or null
strict: optional boolean or null
是否强制执行严格参数校验。省略时,模式兼容的情况下 Responses 会尝试严格校验,否则退回非严格校验。
Custom object { name, type, allowed_callers, 4 more }
使用指定格式处理输入的自定义工具。参阅自定义工具。
name: string
自定义工具的名称,用于在工具调用中标识它。
type: "custom" (default: "custom")
自定义工具类型,固定为 custom。
"custom"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
minItems: 1
"direct"
"programmatic"
async: optional boolean
工具响应是否可以异步返回,而非在下一次创建响应时立即返回。
defer_loading: optional boolean
此工具是否应延迟加载并通过工具搜索发现。
description: optional string
自定义工具的可选描述,用于提供更多上下文。
format: optional Text { type } or Grammar { definition, syntax, type }
自定义工具的输入格式,默认为无约束文本。
Text object { type }
无约束的自由文本。
type: "text" (default: "text")
无约束文本格式,固定为 text。
"text"
Grammar object { definition, syntax, type }
用户定义的语法。
definition: string
语法定义。
syntax: "lark" or "regex"
语法定义的语法类型,可选 lark 或 regex。
"lark"
"regex"
type: "grammar" (default: "grammar")
语法格式,固定为 grammar。
"grammar"
type: "namespace" (default: "namespace")
工具类型,固定为 namespace。
"namespace"
ToolSearch object { type, description, execution, parameters }
用于延迟加载工具的托管工具搜索或自带工具(BYOT)搜索配置。
type: "tool_search" (default: "tool_search")
工具类型,固定为 tool_search。
"tool_search"
description: optional string or null
客户端执行的工具搜索工具展示给模型的描述。
execution: optional "server" or "client"
工具搜索由服务端还是客户端执行。
"server"
"client"
parameters: optional unknown or null
客户端执行的工具搜索工具的参数模式。
WebSearchPreview object { type, search_content_types, search_context_size, user_location }
搜索网页以获取可用于响应的相关结果的工具。参阅网页搜索工具。
type: "web_search_preview" or "web_search_preview_2025_03_11" (default: "web_search_preview")
网页搜索工具类型,可选 web_search_preview 或 web_search_preview_2025_03_11。
"web_search_preview"
"web_search_preview_2025_03_11"
search_content_types: optional array of "text" or "image"
"text"
"image"
search_context_size: optional "low" or "medium" or "high"
对搜索占用上下文窗口空间大小的总体指导,可选 low、medium 或 high,默认为 medium。
"low"
"medium"
"high"
user_location: optional object { type, city, country, 2 more } or null
用户的大致位置。省略或设为 null 时默认为美国。若要避免此默认值,可传入不包含位置字段的 {"type": "approximate"}。若要本地化结果,须提供相应位置字段。
type: "approximate" (default: "approximate")
位置估算类型,固定为 approximate。
"approximate"
city: optional string or null
用户所在城市的自由文本,例如 San Francisco。
country: optional string or null
用户所在国家/地区的两字母 ISO 代码,例如 US。
region: optional string or null
用户所在地区的自由文本,例如 California。
timezone: optional string or null
用户所在的 IANA 时区,例如 America/Los_Angeles。
ApplyPatch object { type, allowed_callers }
允许助手使用统一差异格式创建、删除或更新文件。
type: "apply_patch" (default: "apply_patch")
工具类型,固定为 apply_patch。
"apply_patch"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
minItems: 1
"direct"
"programmatic"
type: "additional_tools" (default: "additional_tools")
条目类型,固定为 additional_tools。
"additional_tools"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
AgentMessage object { id, author, content, 3 more }
id: string
此智能体消息的唯一 ID。
author: string
发送方智能体的标识。
content: array of BetaResponseInputText or BetaResponseOutputText or Text { text, type } or 7 more
智能体之间发送的加密内容。
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
BetaResponseOutputText object { annotations, logprobs, text, type }
模型输出的文本。
Text object { text, type }
文本内容。
text: string
type: "text" (default: "text")
"text"
SummaryText object { text, type }
模型生成的摘要文本。
text: string
模型到目前为止生成的推理输出摘要。
type: "summary_text" (default: "summary_text")
类型,固定为 summary_text。
"summary_text"
ReasoningText object { text, type }
模型生成的推理文本。
text: string
模型生成的推理文本。
type: "reasoning_text" (default: "reasoning_text")
类型,固定为 reasoning_text。
"reasoning_text"
BetaResponseOutputRefusal object { refusal, type }
模型的拒绝响应。
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
ComputerScreenshot object { detail, file_id, image_url, 2 more }
计算机屏幕截图。
detail: BetaImageDetail
发送给模型的截图图像的细节级别,可选 high、low、auto 或 original,默认为 auto。
file_id: string or null
包含截图的已上传文件的标识。
image_url: string or null
截图图像的 URL。
format: uri
type: "computer_screenshot" (default: "computer_screenshot")
指定事件类型。对于计算机屏幕截图,此属性固定为 computer_screenshot。
"computer_screenshot"
prompt_cache_breakpoint: optional object { mode, ttl }
标记可复用提示词前缀的精确结束位置。省略 ttl 时,断点继承请求中的 prompt_cache_options.ttl;该边界不会按词元块取整。
mode: "explicit" (default: "explicit")
断点模式,固定为 explicit。
"explicit"
ttl: optional "30m" or "12h"
此缓存断点的最短存续时间,默认为请求的 TTL。
"30m"
"12h"
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
EncryptedContent object { encrypted_content, type }
不透明的加密内容,由 Responses API 在受信任的模型执行环境中解密。
encrypted_content: string
不透明的加密内容。
type: "encrypted_content" (default: "encrypted_content")
输入条目的类型,固定为 encrypted_content。
"encrypted_content"
recipient: string
接收方智能体的标识。
type: "agent_message" (default: "agent_message")
条目类型,固定为 agent_message。
"agent_message"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
FunctionCallOutput object { output, type, id, 6 more }
函数工具调用的输出。
output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
你的代码产生的函数调用输出,可为字符串或输出内容列表。
StringOutput = string
函数调用输出的字符串。
OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
函数调用的文本、图像或文件输出。
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
type: "function_call_output"
类型,固定为 function_call_output。
"function_call_output"
id: optional string
函数工具调用输出的唯一 ID,通过 API 返回此条目时填充。
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
call_id: optional string
模型生成的函数工具调用的唯一 ID。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
调用方类型,固定为 direct。
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
minLength: 1, maxLength: 64
type: "program" (default: "program")
调用方类型,固定为 program。
"program"
name: optional string
产生输出的工具名称。
namespace: optional string
产生输出的工具所属命名空间。
status: optional "in_progress" or "completed" or "incomplete"
条目状态,可选 in_progress、completed 或 incomplete,通过 API 返回条目时填充。
"in_progress"
"completed"
"incomplete"
FileSearchCall object { id, queries, status, 3 more }
文件搜索工具调用的结果,详见文件搜索指南。
id: string
文件搜索工具调用的唯一 ID。
queries: array of string
搜索文件所用的查询。
status: "in_progress" or "searching" or "completed" or 2 more
文件搜索工具调用状态,可选in_progress、searching、incomplete或failed。
"in_progress"
"searching"
"completed"
"incomplete"
"failed"
type: "file_search_call"
类型,固定为 file_search_call。
"file_search_call"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
results: optional array of object { attributes, file_id, filename, 2 more } or null
文件搜索工具调用的结果。
attributes: optional map[string or number or boolean] or null
可附加到对象的一组16个键值对,可用于以结构化格式保存额外信息,并通过API或控制台查询对象。键为最长64个字符的字符串;值可以是最长512个字符的字符串、布尔值或数字。
string
maxLength: 512
number
boolean
file_id: optional string
文件的唯一 ID。
filename: optional string
文件名。
score: optional number
文件相关性分数,范围为 0–1。
format: float
text: optional string
从文件中检索出的文本。
WebSearchCall object { id, status, type, 2 more }
网页搜索工具调用的结果,详见网页搜索指南。
id: string
网页搜索工具调用的唯一 ID。
status: "in_progress" or "searching" or "completed" or 2 more
网页搜索工具调用的状态。
"in_progress"
"searching"
"completed"
"failed"
"incomplete"
type: "web_search_call"
类型,固定为 web_search_call。
"web_search_call"
action: optional Search { type, queries, query, sources } or OpenPage { type, url } or FindInPage { pattern, type, url }
描述此次网页搜索具体操作的对象,包括模型如何使用网页:search、open_page、find_in_page。
Search object { type, queries, query, sources }
操作类型 "search":执行网页搜索查询。
type: "search"
操作类型。
"search"
queries: optional array of string
搜索查询列表。
query: optional string
搜索查询。
sources: optional array of object { type, url }
搜索所用的信息来源。
type: "url"
来源类型,固定为 url。
"url"
url: string
来源 URL。
format: uri
OpenPage object { type, url }
操作类型 "open_page":打开搜索结果中的指定 URL。
type: "open_page"
操作类型。
"open_page"
url: optional string or null
模型打开的 URL。
format: uri
FindInPage object { pattern, type, url }
操作类型 "find_in_page":在已加载页面中搜索模式。
pattern: string
要在页面中搜索的模式或文本。
type: "find_in_page"
操作类型。
"find_in_page"
url: optional string or null
用于搜索模式的页面 URL,如可用。
format: uri
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
ImageGenerationCall object { id, result, status, 10 more }
模型发起的图像生成请求。
id: string
图像生成调用的唯一 ID。
result: string or null
Base64 编码的生成图像。
status: "in_progress" or "completed" or "generating" or "failed"
图像生成调用的状态。
"in_progress"
"completed"
"generating"
"failed"
type: "image_generation_call"
类型,固定为 image_generation_call。
"image_generation_call"
action: optional "generate" or "edit" or "auto" or null
用于图像生成的操作。
"generate"
"edit"
"auto"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
background: optional "transparent" or "opaque" or "auto" or null
生成图像使用的背景设置。
"transparent"
"opaque"
"auto"
error: optional object { code, message, param, 2 more }
审核失败的详情,如可用。
code: string or null
错误代码。
message: string
错误描述。
param: string or null
关联的请求参数。
type: string
错误类型。
moderation_details: optional object { categories, moderation_stage }
moderation_blocked 错误的公开详情,如可用。
categories: array of string
公开的审核类别,未来可能增加新的类别值。
moderation_stage: "input" or "output" or "unknown"
审核阻止图像生成调用的阶段。
"input"
"output"
"unknown"
output_format: optional "png" or "webp" or "jpeg" or 2 more or null
生成图像使用的输出格式。
"png"
"webp"
"jpeg"
"gif"
"svg"
quality: optional "low" or "medium" or "high" or 3 more or null
图像生成工具调用生成的图像质量,可选 low、medium、high、xhigh、max 或 auto。
"low"
"medium"
"high"
"xhigh"
"max"
"auto"
revised_prompt: optional string or null
模型改写提示词后实际使用的提示词。
size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or null
图像尺寸,采用 WIDTHxHEIGHT 字符串形式,例如 1536x864。
string
"1024x1024" or "1024x1536" or "1536x1024"
图像尺寸,采用 WIDTHxHEIGHT 字符串形式,例如 1536x864。
"1024x1024"
"1024x1536"
"1536x1024"
svg_usage: optional object { input_tokens, model, output_tokens, 2 more }
input_tokens: integer
model: string
output_tokens: integer
reasoning_tokens: integer
total_tokens: integer
ComputerCall object { id, call_id, pending_safety_checks, 5 more }
对计算机使用工具的调用,详见计算机使用指南。
id: string
计算机工具调用的唯一 ID。
call_id: string
通过输出回应此工具调用时使用的标识。
pending_safety_checks: array of object { id, code, message }
此计算机工具调用待处理的安全检查。
id: string
待处理安全检查的 ID。
code: optional string or null
待处理安全检查的类型。
message: optional string or null
待处理安全检查的详情。
status: "in_progress" or "completed" or "incomplete"
条目状态,可选 in_progress、completed 或 incomplete,通过 API 返回条目时填充。
"in_progress"
"completed"
"incomplete"
type: "computer_call" (default: "computer_call")
类型,固定为 computer_call。
"computer_call"
action: optional BetaComputerAction
单击操作。
Click object { button, type, x, 2 more }
单击操作。
button: "left" or "right" or "wheel" or 2 more
单击时按下的鼠标按钮,可选 left、right、wheel、back 或 forward。
"left"
"right"
"wheel"
"back"
"forward"
type: "click" (default: "click")
指定事件类型。单击操作固定为 click。
"click"
x: integer
单击位置的 x 坐标。
y: integer
单击位置的 y 坐标。
keys: optional array of string or null
单击时保持按下的按键。
DoubleClick object { keys, type, x, y }
双击操作。
keys: array of string or null
双击时保持按下的按键。
type: "double_click" (default: "double_click")
指定事件类型。双击操作固定为 double_click。
"double_click"
x: integer
双击位置的 x 坐标。
y: integer
双击位置的 y 坐标。
Drag object { path, type, keys }
拖动操作。
path: array of object { x, y }
表示拖动路径的坐标数组。坐标以对象数组形式提供,例如
[
{ x: 100, y: 200 },
{ x: 200, y: 300 }
]
x: integer
x 坐标。
y: integer
y 坐标。
type: "drag" (default: "drag")
指定事件类型。拖动操作固定为 drag。
"drag"
keys: optional array of string or null
拖动鼠标时保持按下的按键。
Keypress object { keys, type }
模型希望执行的一组按键操作。
keys: array of string
模型请求按下的按键组合,以字符串数组表示,每个字符串代表一个按键。
type: "keypress" (default: "keypress")
指定事件类型。按键操作固定为 keypress。
"keypress"
Move object { type, x, y, keys }
鼠标移动操作。
type: "move" (default: "move")
指定事件类型。移动操作固定为 move。
"move"
x: integer
移动目标的 x 坐标。
y: integer
移动目标的 y 坐标。
keys: optional array of string or null
移动鼠标时保持按下的按键。
Screenshot object { type }
截屏操作。
type: "screenshot" (default: "screenshot")
指定事件类型。截屏操作固定为 screenshot。
"screenshot"
Scroll object { scroll_x, scroll_y, type, 3 more }
滚动操作。
scroll_x: integer
水平滚动距离。
scroll_y: integer
垂直滚动距离。
type: "scroll" (default: "scroll")
指定事件类型。滚动操作固定为 scroll。
"scroll"
x: integer
滚动位置的 x 坐标。
y: integer
滚动位置的 y 坐标。
keys: optional array of string or null
滚动时保持按下的按键。
Type object { text, type }
输入文本的操作。
text: string
要输入的文本。
type: "type" (default: "type")
指定事件类型。输入操作固定为 type。
"type"
Wait object { type }
等待操作。
type: "wait" (default: "wait")
指定事件类型。等待操作固定为 wait。
"wait"
actions: optional BetaComputerActionList
computer_use的扁平化批量操作。每个操作包含type判别字段及该操作专属字段。
Click object { button, type, x, 2 more }
单击操作。
DoubleClick object { keys, type, x, y }
双击操作。
Drag object { path, type, keys }
拖动操作。
Keypress object { keys, type }
模型希望执行的一组按键操作。
Move object { type, x, y, keys }
鼠标移动操作。
Screenshot object { type }
截屏操作。
Scroll object { scroll_x, scroll_y, type, 3 more }
滚动操作。
Type object { text, type }
输入文本的操作。
Wait object { type }
等待操作。
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
ComputerCallOutput object { id, call_id, output, 5 more }
id: string
计算机工具调用输出的 ID。
call_id: string
产生此输出的计算机工具调用的 ID。
output: BetaResponseComputerToolCallOutputScreenshot
供计算机使用工具使用的屏幕截图图像。
type: "computer_screenshot" (default: "computer_screenshot")
指定事件类型。对于计算机屏幕截图,此属性固定为 computer_screenshot。
"computer_screenshot"
file_id: optional string
包含截图的已上传文件的标识。
image_url: optional string
截图图像的 URL。
format: uri
status: "completed" or "incomplete" or "failed" or "in_progress"
输入消息状态,可选 in_progress、completed 或 incomplete,通过 API 返回输入条目时填充。
"completed"
"incomplete"
"failed"
"in_progress"
type: "computer_call_output" (default: "computer_call_output")
类型,固定为 computer_call_output。
"computer_call_output"
acknowledged_safety_checks: optional array of object { id, code, message }
API 报告且开发者已确认的安全检查。
id: string
待处理安全检查的 ID。
code: optional string or null
待处理安全检查的类型。
message: optional string or null
待处理安全检查的详情。
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
created_by: optional string
创建该条目的执行主体的标识。
Reasoning object { id, summary, type, 4 more }
推理模型生成响应时所用思维链的描述。如果手动管理上下文,请在后续对话轮次发送给Responses API的input中包含这些条目。
id: string
推理内容的唯一标识。
summary: array of object { text, type }
推理摘要内容。
text: string
模型到目前为止生成的推理输出摘要。
type: "summary_text" (default: "summary_text")
类型,固定为 summary_text。
"summary_text"
type: "reasoning"
类型,固定为 reasoning。
"reasoning"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
content: optional array of object { text, type }
推理文本内容。
text: string
模型生成的推理文本。
type: "reasoning_text" (default: "reasoning_text")
类型,固定为 reasoning_text。
"reasoning_text"
encrypted_content: optional string or null
推理条目的加密内容。POST /v1/responses及WebSocket response.create请求返回的推理条目默认填充此字段。
流式处理中,后续请求应使用response.output_item.done事件中的已完成推理条目及其encrypted_content。response.output_item.added中的加密内容可能不完整。在store为false或使用零数据保留时尤其重要。
status: optional "in_progress" or "completed" or "incomplete"
条目状态,可选 in_progress、completed 或 incomplete,通过 API 返回条目时填充。
"in_progress"
"completed"
"incomplete"
Compaction object { id, encrypted_content, type, 2 more }
v1/responses/compact API生成的压缩条目。
id: string
压缩条目的唯一 ID。
encrypted_content: string
压缩生成的加密内容。
type: "compaction" (default: "compaction")
类型,固定为 compaction。
"compaction"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
created_by: optional string
创建该条目的执行主体的标识。
CodeInterpreterCall object { id, code, container_id, 4 more }
运行代码的工具调用。
id: string
代码解释器工具调用的唯一 ID。
code: string or null
要运行的代码,不可用时为 null。
container_id: string
运行代码使用的容器 ID。
outputs: array of Logs { logs, type } or Image { type, url } or null
代码解释器产生的日志、图像等输出;没有可用输出时可为null。
Logs object { logs, type }
代码解释器的日志输出。
logs: string
代码解释器的日志输出。
type: "logs" (default: "logs")
类型,固定为 logs。
"logs"
Image object { type, url }
代码解释器的图像输出。
type: "image" (default: "image")
类型,固定为 image。
"image"
url: string
代码解释器输出图像的 URL。
format: uri
status: "in_progress" or "completed" or "incomplete" or 2 more
代码解释器工具调用的状态,有效值为 in_progress、completed、incomplete、interpreting 和 failed。
"in_progress"
"completed"
"incomplete"
"interpreting"
"failed"
type: "code_interpreter_call" (default: "code_interpreter_call")
类型,固定为 code_interpreter_call。
"code_interpreter_call"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
LocalShellCall object { id, action, call_id, 3 more }
在本地 shell 上运行命令的工具调用。
id: string
本地 shell 调用的唯一 ID。
action: object { command, env, type, 3 more }
在服务器上执行 shell 命令。
command: array of string
要运行的命令。
env: map[string]
要为命令设置的环境变量。
type: "exec" (default: "exec")
类型,固定为 exec。
"exec"
timeout_ms: optional integer or null
可选的命令超时时长,单位为毫秒。
user: optional string or null
可选的运行命令的用户。
working_directory: optional string or null
可选的运行命令的工作目录。
call_id: string
模型生成的本地 shell 工具调用的唯一 ID。
status: "in_progress" or "completed" or "incomplete"
本地 shell 调用的状态。
"in_progress"
"completed"
"incomplete"
type: "local_shell_call"
类型,固定为 local_shell_call。
"local_shell_call"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
LocalShellCallOutput object { id, output, type, 2 more }
本地 shell 工具调用的输出。
id: string
模型生成的本地 shell 工具调用的唯一 ID。
output: string
本地 shell 工具调用输出的 JSON 字符串。
type: "local_shell_call_output"
类型,固定为 local_shell_call_output。
"local_shell_call_output"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
status: optional "in_progress" or "completed" or "incomplete" or null
条目状态,可选 in_progress、completed 或 incomplete。
"in_progress"
"completed"
"incomplete"
ShellCall object { id, action, call_id, 6 more }
在托管环境中执行一个或多个 shell 命令的工具调用。
id: string
shell 工具调用的唯一 ID,通过 API 返回此条目时填充。
action: object { commands, max_output_length, timeout_ms }
描述如何运行工具调用的 shell 命令及限制。
commands: array of string
max_output_length: integer or null
可选的每个命令返回的最大字符数。
timeout_ms: integer or null
可选的命令超时时长,单位为毫秒。
call_id: string
模型生成的 shell 工具调用的唯一 ID。
environment: BetaResponseLocalEnvironment or BetaResponseContainerReference or null
表示使用本地环境执行 shell 操作。
BetaResponseLocalEnvironment object { type }
表示使用本地环境执行 shell 操作。
type: "local" (default: "local")
环境类型,固定为 local。
"local"
BetaResponseContainerReference object { container_id, type }
表示通过 /v1/containers 创建的容器。
container_id: string
type: "container_reference" (default: "container_reference")
环境类型,固定为 container_reference。
"container_reference"
status: "in_progress" or "completed" or "incomplete"
shell 调用状态,可选 in_progress、completed 或 incomplete。
"in_progress"
"completed"
"incomplete"
type: "shell_call" (default: "shell_call")
类型,固定为 shell_call。
"shell_call"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建此工具调用的实体的 ID。
ShellCallOutput object { id, call_id, max_output_length, 6 more }
shell 工具调用发出的输出。
id: string
shell 调用输出的唯一 ID,通过 API 返回此条目时填充。
call_id: string
模型生成的 shell 工具调用的唯一 ID。
max_output_length: integer or null
shell 命令输出的最大长度,由模型生成,应与原始输出一并回传。
output: array of object { outcome, stderr, stdout, created_by }
shell 调用输出内容的数组。
outcome: Timeout { type } or Exit { exit_code, type }
表示 shell 调用输出块的退出结果(包含退出码)或超时结果。
Timeout object { type }
表示 shell 调用超过其配置的时间限制。
type: "timeout" (default: "timeout")
结果类型,固定为 timeout。
"timeout"
Exit object { exit_code, type }
表示 shell 命令已结束,并返回退出码。
exit_code: integer
shell 进程的退出码。
type: "exit" (default: "exit")
结果类型,固定为 exit。
"exit"
stderr: string
捕获的标准错误输出。
stdout: string
捕获的标准输出。
created_by: optional string
创建该条目的执行主体的标识。
status: "in_progress" or "completed" or "incomplete"
shell 调用输出的状态,可选 in_progress、completed 或 incomplete。
"in_progress"
"completed"
"incomplete"
type: "shell_call_output" (default: "shell_call_output")
shell 调用输出的类型,固定为 shell_call_output。
"shell_call_output"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建该条目的执行主体的标识。
ApplyPatchCall object { id, call_id, operation, 5 more }
通过创建、删除或更新文件来应用文件差异的工具调用。
id: string
apply_patch 工具调用的唯一 ID,通过 API 返回此条目时填充。
call_id: string
模型生成的 apply_patch 工具调用的唯一 ID。
operation: CreateFile { diff, path, type } or DeleteFile { path, type } or UpdateFile { diff, path, type }
通过 apply_patch 应用的 create_file、delete_file 或 update_file 操作之一。
CreateFile object { diff, path, type }
描述如何通过 apply_patch 工具创建文件的指令。
diff: string
要应用的差异。
path: string
要创建的文件路径。
type: "create_file" (default: "create_file")
使用提供的差异创建新文件。
"create_file"
DeleteFile object { path, type }
描述如何通过 apply_patch 工具删除文件的指令。
path: string
要删除的文件路径。
type: "delete_file" (default: "delete_file")
删除指定文件。
"delete_file"
UpdateFile object { diff, path, type }
描述如何通过 apply_patch 工具更新文件的指令。
diff: string
要应用的差异。
path: string
要更新的文件路径。
type: "update_file" (default: "update_file")
使用提供的差异更新已有文件。
"update_file"
status: "in_progress" or "completed"
apply_patch 工具调用状态,可选 in_progress 或 completed。
"in_progress"
"completed"
type: "apply_patch_call" (default: "apply_patch_call")
类型,固定为 apply_patch_call。
"apply_patch_call"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建此工具调用的实体的 ID。
ApplyPatchCallOutput object { id, call_id, status, 5 more }
apply_patch 工具调用发出的输出。
id: string
apply_patch 工具调用输出的唯一 ID,通过 API 返回此条目时填充。
call_id: string
模型生成的 apply_patch 工具调用的唯一 ID。
status: "completed" or "failed"
apply_patch 工具调用输出的状态,可选 completed 或 failed。
"completed"
"failed"
type: "apply_patch_call_output" (default: "apply_patch_call_output")
类型,固定为 apply_patch_call_output。
"apply_patch_call_output"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建此工具调用输出的实体的 ID。
output: optional string or null
apply_patch 工具返回的可选文本输出。
McpListTools object { id, server_label, tools, 3 more }
MCP 服务器可用的工具列表。
id: string
列表的唯一 ID。
server_label: string
MCP 服务器标签。
tools: array of object { input_schema, name, annotations, description }
服务器可用的工具。
input_schema: unknown
描述工具输入的 JSON Schema。
name: string
工具名称。
annotations: optional unknown or null
工具的额外注解。
description: optional string or null
工具描述。
type: "mcp_list_tools"
类型,固定为 mcp_list_tools。
"mcp_list_tools"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
error: optional string or null
服务器无法列出工具时的错误消息。
McpApprovalRequest object { id, arguments, name, 3 more }
工具调用的人工批准请求。
id: string
批准请求的唯一 ID。
arguments: string
工具参数的 JSON 字符串。
name: string
要运行的工具名称。
server_label: string
发出请求的 MCP 服务器标签。
type: "mcp_approval_request"
类型,固定为 mcp_approval_request。
"mcp_approval_request"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
McpApprovalResponse object { id, approval_request_id, approve, 3 more }
对 MCP 批准请求的响应。
id: string
批准响应的唯一 ID。
approval_request_id: string
所回应的批准请求的 ID。
approve: boolean
请求是否获准。
type: "mcp_approval_response"
类型,固定为 mcp_approval_response。
"mcp_approval_response"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
reason: optional string or null
决定的可选理由。
McpCall object { id, arguments, name, 7 more }
对 MCP 服务器上工具的调用。
id: string
工具调用的唯一 ID。
arguments: string
传给工具的参数组成的 JSON 字符串。
name: string
已运行的工具名称。
server_label: string
运行工具的 MCP 服务器标签。
type: "mcp_call"
类型,固定为 mcp_call。
"mcp_call"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
approval_request_id: optional string or null
MCP工具调用批准请求的唯一标识。要批准或拒绝相应调用,应在后续mcp_approval_response输入中包含此值。
error: optional BetaMcpToolCallError or null
工具调用的错误,如有。
McpProtocolError object { code, message, type }
code: integer
message: string
type: "mcp_protocol_error" (default: "mcp_protocol_error")
"mcp_protocol_error"
McpToolExecutionError object { content, type }
content: unknown
type: "mcp_tool_execution_error" (default: "mcp_tool_execution_error")
"mcp_tool_execution_error"
HTTPError object { code, message, type }
code: integer
message: string
type: "http_error" (default: "http_error")
"http_error"
output: optional string or null
工具调用的输出。
status: optional "in_progress" or "completed" or "incomplete" or 2 more
工具调用状态,可选 in_progress、completed、incomplete、calling 或 failed。
"in_progress"
"completed"
"incomplete"
"calling"
"failed"
CustomToolCall object { call_id, input, name, 6 more }
模型生成的自定义工具调用。
call_id: string
用于将此自定义工具调用映射到工具调用输出的标识。
input: string
模型生成的自定义工具调用输入。
name: string
被调用的自定义工具的名称。
type: "custom_tool_call"
类型,固定为 custom_tool_call。
"custom_tool_call"
id: optional string
自定义工具调用在 OpenAI 平台中的唯一 ID。
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
async: optional boolean
自定义工具调用是否异步运行。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
namespace: optional string
被调用的自定义工具所属的命名空间。
CustomToolCallOutput object { call_id, output, type, 3 more }
自有代码生成、回传给模型的自定义工具调用输出。
call_id: string
调用 ID,用于将此自定义工具调用输出映射到自定义工具调用。
output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
你的代码生成的自定义工具输出,可为字符串或输出内容列表。
StringOutput = string
自定义工具调用输出的字符串。
OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
自定义工具调用的文本、图像或文件输出。
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
type: "custom_tool_call_output"
类型,固定为 custom_tool_call_output。
"custom_tool_call_output"
id: optional string
自定义工具调用输出在 OpenAI 平台中的唯一 ID。
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
调用方类型,固定为 direct。
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
minLength: 1, maxLength: 64
type: "program" (default: "program")
调用方类型,固定为 program。
"program"
usage: BetaResponseUsage
压缩过程的词元统计,包括缓存、推理和总词元数。
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
使用的总词元数。
image: optional object { context_compression }
context_compression: "enabled" or "disabled"
实际采用的图像上下文优化策略。
"enabled"
"disabled"
示例
## 从环境变量读取 API 密钥,按需替换示例资源标识。
curl https://api.openai.com/v1/responses/compact \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-6-astra",
"previous_response_id": "resp_123"
}'
200 响应示例
例中文字:总结我们上周的发布检查清单。 / 你正在执行上下文检查点压缩……
{
"id": "resp_001",
"created_at": 1731459200,
"object": "response.compaction",
"output": [
{
"id": "msg_001",
"status": "completed",
"type": "message",
"role": "user",
"content": [
{
"type": "input_text",
"text": "Summarize our launch checklist from last week."
}
]
},
{
"id": "msg_002",
"status": "completed",
"type": "message",
"role": "user",
"content": [
{
"type": "input_text",
"text": "You are performing a CONTEXT CHECKPOINT COMPACTION..."
}
]
},
{
"type": "compaction",
"id": "cmp_001",
"encrypted_content": "encrypted-summary"
}
],
"usage": {
"input_tokens": 42897,
"input_tokens_details": {
"cache_write_tokens": 0,
"cached_tokens": 0,
"cache_write_tokens_details": {
"ttl_12h_tokens": 0,
"ttl_30m_tokens": 0
}
},
"output_tokens": 12000,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 54897
},
"image": {
"context_compression": "disabled"
}
}
示例
例中文字:为一家可以抚摸狗狗的咖啡馆创建简单落地页。 / 以下是可直接使用、单文件的抚狗咖啡馆落地页:……
## 从环境变量读取 API 密钥,按需替换示例资源标识。
curl -X POST https://api.openai.com/v1/responses/compact \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-6-astra",
"input": [
{
"role": "user",
"content": "Create a simple landing page for a dog petting café."
},
{
"id": "msg_001",
"type": "message",
"status": "completed",
"content": [
{
"type": "output_text",
"annotations": [],
"logprobs": [],
"text": "Below is a single file, ready-to-use landing page for a dog petting café:..."
}
],
"role": "assistant"
}
]
}'
响应示例
例中文字:为一家可以抚摸狗狗的咖啡馆创建简单落地页。
{
"id": "resp_001",
"object": "response.compaction",
"created_at": 1764967971,
"output": [
{
"id": "msg_000",
"type": "message",
"status": "completed",
"content": [
{
"type": "input_text",
"text": "Create a simple landing page for a dog petting cafe."
}
],
"role": "user"
},
{
"id": "cmp_001",
"type": "compaction",
"encrypted_content": "gAAAAABpM0Yj-...="
}
],
"usage": {
"input_tokens": 139,
"input_tokens_details": {
"cached_tokens": 0,
"cache_write_tokens": 0
},
"output_tokens": 438,
"output_tokens_details": {
"reasoning_tokens": 64
},
"total_tokens": 577
}
}
TRAE-AI编程


更多建议: