OpenAI 多智能体流式事件
本页覆盖通用多智能体接口。专用网络安全访问配置未纳入此译稿。
创建Response时将stream设为true,服务器会在生成响应的同时向客户端发出SSE事件。本节列出服务端发出的事件。
处理compaction_trigger时,response.compaction.compacting最多每30秒报告一次新采样摘要输出,但不携带摘要内容,也不修改压缩输出条目。已有的response.output_item.added与response.output_item.done标记条目生命周期,后者携带最终加密内容。较短的压缩可能在未发出进度事件前就已完成。
详见流式响应。
response.created
创建响应时发出的事件。
结构定义
结构名称: BetaResponseCreatedEvent
response: BetaResponse
已创建的响应。
id: string
此响应的唯一标识符。
access_programs: object { cyber } or null
created_at: number
此响应创建时的 Unix 时间戳,单位为秒。
format: unixtime
error: BetaResponseError or null
模型未能生成响应时返回的错误对象。
code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 18 more
此响应的错误代码。
"server_error"
"rate_limit_exceeded"
"invalid_prompt"
"data_residency_mismatch"
"bio_policy"
"misalignment_policy_violation"
"vector_store_timeout"
"invalid_image"
"invalid_image_format"
"invalid_base64_image"
"invalid_image_url"
"image_too_large"
"image_too_small"
"image_parse_error"
"image_content_policy_violation"
"invalid_image_mode"
"image_file_too_large"
"unsupported_image_media_type"
"empty_image_file"
"failed_to_download_image"
"image_file_not_found"
message: string
便于人阅读的错误说明。
misalignment: optional object { detailed_explanation, error_type, review_target, steer }
detailed_explanation: optional string
对此次阻止操作的公开说明。
error_type: optional string or "potentially_unintended_data_transfer" or "potentially_unintended_data_access" or "potentially_unintended_destructive_activity" or "other"
可选的分类;客户端必须能够接受其他值。
string
SafetyAlertErrorType = "potentially_unintended_data_transfer" or "potentially_unintended_data_access" or "potentially_unintended_destructive_activity" or "other"
可选的分类;客户端必须能够接受其他值。
"potentially_unintended_data_transfer"
"potentially_unintended_data_access"
"potentially_unintended_destructive_activity"
"other"
review_target: optional string or null
用于明确继续此次审查的不透明目标;不可用时为 null。
pattern: ^[A-Za-z0-9._~:-]+$, minLength: 1, maxLength: 96
steer: optional object { message }
可选的公开继续指令。
message: string
公开的继续指令。
param: optional string or null
与错误相关的请求参数;未记录时为 null。
type: optional string or null
原始错误类型;未记录时为 null。
incomplete_details: object { reason } or null
说明响应为何未完成的详细信息。
reason: optional "max_output_tokens" or "max_messages" or "content_filter" or "steered"
响应未完成的原因。steered表示响应在收到WebSocket response.steer事件后于安全输出边界停止;服务器随后可自动使用排队输入创建后继响应。
"max_output_tokens"
"max_messages"
"content_filter"
"steered"
instructions: string or array of BetaEasyInputMessage or Message { content, role, agent, 2 more } or BetaResponseOutputMessage or 33 more or null
插入模型上下文的系统消息或开发者消息。
与previous_response_id一起使用时,前一响应的instructions不会传入下一响应,便于在新响应中替换system或developer消息。
string
提供给模型的文本输入,等同于developer角色的文本输入。
InputItemList = array of BetaEasyInputMessage or Message { content, role, agent, 2 more } or BetaResponseOutputMessage or 33 more
提供给模型的一个或多个输入条目组成的列表,其中可以包含不同类型的内容。
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
生成该条目的智能体的规范名称。
metadata: map[string] or null
可附加到对象的一组16个键值对,用于结构化保存附加信息,并通过API或控制台查询对象。
键为最长64个字符的字符串,值为最长512个字符的字符串。
model: "gpt-6-astra" or "gpt-6.2-astra" or "gpt-6.1-sol" or 112 more or string
生成响应的模型ID,例如gpt-6.2-astra。OpenAI提供能力、性能和价格各异的模型,可在模型指南浏览比较。
"gpt-6-astra" or "gpt-6.2-astra" or "gpt-6.1-sol" or 112 more
生成响应的模型ID,例如gpt-6.2-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
object: "response"
此资源的对象类型,始终为 response。
"response"
output: array of BetaResponseOutputItem
模型生成的内容条目数组。
output数组的长度和顺序取决于模型响应。不要假定首个条目一定是包含生成内容的assistant消息;可考虑使用SDK支持的output_text属性。
BetaResponseOutputMessage object { id, content, role, 4 more }
模型输出的消息。
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
从文件中检索出的文本。
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 { id, output, status, 7 more }
id: string
函数调用工具输出的唯一 ID。
output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
你的代码产生的函数调用输出,可为字符串或输出内容列表。
StringOutput = string
函数调用输出的字符串。
OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
函数调用的文本、图像或文件输出。
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
status: "in_progress" or "completed" or "incomplete"
条目状态,可选 in_progress、completed 或 incomplete,通过 API 返回条目时填充。
"in_progress"
"completed"
"incomplete"
type: "function_call_output"
类型,固定为 function_call_output。
"function_call_output"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
call_id: optional string
模型生成的函数工具调用的唯一 ID。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
调用方类型,固定为 direct。
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
minLength: 1, maxLength: 64
type: "program" (default: "program")
调用方类型,固定为 program。
"program"
created_by: optional string
创建该条目的执行主体的标识。
name: optional string
产生输出的工具名称。
namespace: optional string
产生输出的工具所属命名空间。
AgentMessage object { id, author, content, 3 more }
id: string
此智能体消息的唯一 ID。
author: string
发送方智能体的标识。
content: array of BetaResponseInputText or BetaResponseOutputText or Text { text, type } or 7 more
智能体之间发送的加密内容。
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
BetaResponseOutputText object { annotations, logprobs, text, type }
模型输出的文本。
Text object { text, type }
文本内容。
text: string
type: "text" (default: "text")
"text"
SummaryText object { text, type }
模型生成的摘要文本。
text: string
模型到目前为止生成的推理输出摘要。
type: "summary_text" (default: "summary_text")
类型,固定为 summary_text。
"summary_text"
ReasoningText object { text, type }
模型生成的推理文本。
text: string
模型生成的推理文本。
type: "reasoning_text" (default: "reasoning_text")
类型,固定为 reasoning_text。
"reasoning_text"
BetaResponseOutputRefusal object { refusal, type }
模型的拒绝响应。
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
ComputerScreenshot object { detail, file_id, image_url, 2 more }
计算机屏幕截图。
detail: BetaImageDetail
发送给模型的截图图像的细节级别,可选 high、low、auto 或 original,默认为 auto。
file_id: string or null
包含截图的已上传文件的标识。
image_url: string or null
截图图像的 URL。
format: uri
type: "computer_screenshot" (default: "computer_screenshot")
指定事件类型。对于计算机屏幕截图,此属性固定为 computer_screenshot。
"computer_screenshot"
prompt_cache_breakpoint: optional object { mode, ttl }
标记可复用提示词前缀的精确结束位置。省略 ttl 时,断点继承请求中的 prompt_cache_options.ttl;该边界不会按词元块取整。
mode: "explicit" (default: "explicit")
断点模式,固定为 explicit。
"explicit"
ttl: optional "30m" or "12h"
此缓存断点的最短存续时间,默认为请求的 TTL。
"30m"
"12h"
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
EncryptedContent object { encrypted_content, type }
不透明的加密内容,由 Responses API 在受信任的模型执行环境中解密。
encrypted_content: string
不透明的加密内容。
type: "encrypted_content" (default: "encrypted_content")
输入条目的类型,固定为 encrypted_content。
"encrypted_content"
recipient: string
接收方智能体的标识。
type: "agent_message" (default: "agent_message")
条目类型,固定为 agent_message。
"agent_message"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
MultiAgentCall object { id, action, arguments, 3 more }
id: string
该多智能体调用条目的唯一 ID。
action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more
要执行的多智能体操作。
"spawn_agent"
"interrupt_agent"
"list_agents"
"send_message"
"followup_task"
"wait_agent"
arguments: string
为该操作生成的参数,格式为 JSON 字符串。
call_id: string
关联调用与其输出的唯一 ID。
type: "multi_agent_call" (default: "multi_agent_call")
多智能体调用的类型,固定为 multi_agent_call。
"multi_agent_call"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
MultiAgentCallOutput object { id, action, call_id, 3 more }
id: string
此多智能体调用输出条目的唯一 ID。
action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more
生成此结果的多智能体操作。
"spawn_agent"
"interrupt_agent"
"list_agents"
"send_message"
"followup_task"
"wait_agent"
call_id: string
此多智能体调用的唯一 ID。
output: array of BetaResponseOutputText
多智能体操作返回的文本。
annotations: array of FileCitation { file_id, filename, index, type } or URLCitation { end_index, start_index, title, 2 more } or ContainerFileCitation { container_id, end_index, file_id, 3 more } or FilePath { file_id, index, type }
文本输出的注解。
logprobs: array of object { token, bytes, logprob, top_logprobs }
text: string
模型输出的文本内容。
type: "output_text" (default: "output_text")
输出文本类型,固定为 output_text。
type: "multi_agent_call_output" (default: "multi_agent_call_output")
多智能体结果的类型,固定为 multi_agent_call_output。
"multi_agent_call_output"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
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
生成该条目的智能体的规范名称。
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
单击操作。
actions: optional BetaComputerActionList
computer_use的扁平化批量操作。每个操作包含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
供计算机使用工具使用的屏幕截图图像。
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"
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
生成该条目的智能体的规范名称。
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 }
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: "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
生成该条目的智能体的规范名称。
Compaction object { id, encrypted_content, type, 2 more }
v1/responses/compact API生成的压缩条目。
id: string
压缩条目的唯一 ID。
encrypted_content: string
压缩生成的加密内容。
type: "compaction" (default: "compaction")
类型,固定为 compaction。
"compaction"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
created_by: optional string
创建该条目的执行主体的标识。
ImageGenerationCall object { id, result, status, 10 more }
模型发起的图像生成请求。
id: string
图像生成调用的唯一 ID。
result: string or null
Base64 编码的生成图像。
status: "in_progress" or "completed" or "generating" or "failed"
图像生成调用的状态。
"in_progress"
"completed"
"generating"
"failed"
type: "image_generation_call"
类型,固定为 image_generation_call。
"image_generation_call"
action: optional "generate" or "edit" or "auto" or null
用于图像生成的操作。
"generate"
"edit"
"auto"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
background: optional "transparent" or "opaque" or "auto" or null
生成图像使用的背景设置。
"transparent"
"opaque"
"auto"
error: optional object { code, message, param, 2 more }
审核失败的详情,如可用。
code: string or null
错误代码。
message: string
错误描述。
param: string or null
关联的请求参数。
type: string
错误类型。
moderation_details: optional object { categories, moderation_stage }
moderation_blocked 错误的公开详情,如可用。
categories: array of string
公开的审核类别,未来可能增加新的类别值。
moderation_stage: "input" or "output" or "unknown"
审核阻止图像生成调用的阶段。
"input"
"output"
"unknown"
output_format: optional "png" or "webp" or "jpeg" or 2 more or null
生成图像使用的输出格式。
"png"
"webp"
"jpeg"
"gif"
"svg"
quality: optional "low" or "medium" or "high" or 3 more or null
图像生成工具调用生成的图像质量,可选 low、medium、high、xhigh、max 或 auto。
"low"
"medium"
"high"
"xhigh"
"max"
"auto"
revised_prompt: optional string or null
模型改写提示词后实际使用的提示词。
size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or null
图像尺寸,采用 WIDTHxHEIGHT 字符串形式,例如 1536x864。
string
"1024x1024" or "1024x1536" or "1536x1024"
图像尺寸,采用 WIDTHxHEIGHT 字符串形式,例如 1536x864。
"1024x1024"
"1024x1536"
"1536x1024"
svg_usage: optional object { input_tokens, model, output_tokens, 2 more }
input_tokens: integer
model: string
output_tokens: integer
reasoning_tokens: integer
total_tokens: integer
CodeInterpreterCall object { id, code, container_id, 4 more }
运行代码的工具调用。
id: string
代码解释器工具调用的唯一 ID。
code: string or null
要运行的代码,不可用时为 null。
container_id: string
运行代码使用的容器 ID。
outputs: array of Logs { logs, type } or Image { type, url } or null
代码解释器产生的日志、图像等输出;没有可用输出时可为null。
Logs object { logs, type }
代码解释器的日志输出。
logs: string
代码解释器的日志输出。
type: "logs" (default: "logs")
类型,固定为 logs。
"logs"
Image object { type, url }
代码解释器的图像输出。
type: "image" (default: "image")
类型,固定为 image。
"image"
url: string
代码解释器输出图像的 URL。
format: uri
status: "in_progress" or "completed" or "incomplete" or 2 more
代码解释器工具调用的状态,有效值为 in_progress、completed、incomplete、interpreting 和 failed。
"in_progress"
"completed"
"incomplete"
"interpreting"
"failed"
type: "code_interpreter_call" (default: "code_interpreter_call")
类型,固定为 code_interpreter_call。
"code_interpreter_call"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
LocalShellCall object { id, action, call_id, 3 more }
在本地 shell 上运行命令的工具调用。
id: string
本地 shell 调用的唯一 ID。
action: object { command, env, type, 3 more }
在服务器上执行 shell 命令。
command: array of string
要运行的命令。
env: map[string]
要为命令设置的环境变量。
type: "exec" (default: "exec")
类型,固定为 exec。
"exec"
timeout_ms: optional integer or null
可选的命令超时时长,单位为毫秒。
user: optional string or null
可选的运行命令的用户。
working_directory: optional string or null
可选的运行命令的工作目录。
call_id: string
模型生成的本地 shell 工具调用的唯一 ID。
status: "in_progress" or "completed" or "incomplete"
本地 shell 调用的状态。
"in_progress"
"completed"
"incomplete"
type: "local_shell_call"
类型,固定为 local_shell_call。
"local_shell_call"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
LocalShellCallOutput object { id, output, type, 2 more }
本地 shell 工具调用的输出。
id: string
模型生成的本地 shell 工具调用的唯一 ID。
output: string
本地 shell 工具调用输出的 JSON 字符串。
type: "local_shell_call_output"
类型,固定为 local_shell_call_output。
"local_shell_call_output"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
status: optional "in_progress" or "completed" or "incomplete" or null
条目状态,可选 in_progress、completed 或 incomplete。
"in_progress"
"completed"
"incomplete"
ShellCall object { id, action, call_id, 6 more }
在托管环境中执行一个或多个 shell 命令的工具调用。
id: string
shell 工具调用的唯一 ID,通过 API 返回此条目时填充。
action: object { commands, max_output_length, timeout_ms }
描述如何运行工具调用的 shell 命令及限制。
commands: array of string
max_output_length: integer or null
可选的每个命令返回的最大字符数。
timeout_ms: integer or null
可选的命令超时时长,单位为毫秒。
call_id: string
模型生成的 shell 工具调用的唯一 ID。
environment: BetaResponseLocalEnvironment or BetaResponseContainerReference or null
表示使用本地环境执行 shell 操作。
BetaResponseLocalEnvironment object { type }
表示使用本地环境执行 shell 操作。
type: "local" (default: "local")
环境类型,固定为 local。
"local"
BetaResponseContainerReference object { container_id, type }
表示通过 /v1/containers 创建的容器。
container_id: string
type: "container_reference" (default: "container_reference")
环境类型,固定为 container_reference。
"container_reference"
status: "in_progress" or "completed" or "incomplete"
shell 调用状态,可选 in_progress、completed 或 incomplete。
"in_progress"
"completed"
"incomplete"
type: "shell_call" (default: "shell_call")
类型,固定为 shell_call。
"shell_call"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建此工具调用的实体的 ID。
ShellCallOutput object { id, call_id, max_output_length, 6 more }
shell 工具调用发出的输出。
id: string
shell 调用输出的唯一 ID,通过 API 返回此条目时填充。
call_id: string
模型生成的 shell 工具调用的唯一 ID。
max_output_length: integer or null
shell 命令输出的最大长度,由模型生成,应与原始输出一并回传。
output: array of object { outcome, stderr, stdout, created_by }
shell 调用输出内容的数组。
outcome: Timeout { type } or Exit { exit_code, type }
表示 shell 调用输出块的退出结果(包含退出码)或超时结果。
Timeout object { type }
表示 shell 调用超过其配置的时间限制。
type: "timeout" (default: "timeout")
结果类型,固定为 timeout。
"timeout"
Exit object { exit_code, type }
表示 shell 命令已结束,并返回退出码。
exit_code: integer
shell 进程的退出码。
type: "exit" (default: "exit")
结果类型,固定为 exit。
"exit"
stderr: string
捕获的标准错误输出。
stdout: string
捕获的标准输出。
created_by: optional string
创建该条目的执行主体的标识。
status: "in_progress" or "completed" or "incomplete"
shell 调用输出的状态,可选 in_progress、completed 或 incomplete。
"in_progress"
"completed"
"incomplete"
type: "shell_call_output" (default: "shell_call_output")
shell 调用输出的类型,固定为 shell_call_output。
"shell_call_output"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建该条目的执行主体的标识。
ApplyPatchCall object { id, call_id, operation, 5 more }
通过创建、删除或更新文件来应用文件差异的工具调用。
id: string
apply_patch 工具调用的唯一 ID,通过 API 返回此条目时填充。
call_id: string
模型生成的 apply_patch 工具调用的唯一 ID。
operation: CreateFile { diff, path, type } or DeleteFile { path, type } or UpdateFile { diff, path, type }
通过 apply_patch 应用的 create_file、delete_file 或 update_file 操作之一。
CreateFile object { diff, path, type }
描述如何通过 apply_patch 工具创建文件的指令。
diff: string
要应用的差异。
path: string
要创建的文件路径。
type: "create_file" (default: "create_file")
使用提供的差异创建新文件。
"create_file"
DeleteFile object { path, type }
描述如何通过 apply_patch 工具删除文件的指令。
path: string
要删除的文件路径。
type: "delete_file" (default: "delete_file")
删除指定文件。
"delete_file"
UpdateFile object { diff, path, type }
描述如何通过 apply_patch 工具更新文件的指令。
diff: string
要应用的差异。
path: string
要更新的文件路径。
type: "update_file" (default: "update_file")
使用提供的差异更新已有文件。
"update_file"
status: "in_progress" or "completed"
apply_patch 工具调用状态,可选 in_progress 或 completed。
"in_progress"
"completed"
type: "apply_patch_call" (default: "apply_patch_call")
类型,固定为 apply_patch_call。
"apply_patch_call"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建此工具调用的实体的 ID。
ApplyPatchCallOutput object { id, call_id, status, 5 more }
apply_patch 工具调用发出的输出。
id: string
apply_patch 工具调用输出的唯一 ID,通过 API 返回此条目时填充。
call_id: string
模型生成的 apply_patch 工具调用的唯一 ID。
status: "completed" or "failed"
apply_patch 工具调用输出的状态,可选 completed 或 failed。
"completed"
"failed"
type: "apply_patch_call_output" (default: "apply_patch_call_output")
类型,固定为 apply_patch_call_output。
"apply_patch_call_output"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建此工具调用输出的实体的 ID。
output: optional string or null
apply_patch 工具返回的可选文本输出。
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
工具调用的错误,如有。
output: optional string or null
工具调用的输出。
status: optional "in_progress" or "completed" or "incomplete" or 2 more
工具调用状态,可选 in_progress、completed、incomplete、calling 或 failed。
"in_progress"
"completed"
"incomplete"
"calling"
"failed"
McpListTools object { id, server_label, tools, 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
决定的可选理由。
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 { id, call_id, output, 5 more }
id: string
自定义工具调用输出条目的唯一 ID。
call_id: string
调用 ID,用于将此自定义工具调用输出映射到自定义工具调用。
output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
你的代码生成的自定义工具输出,可为字符串或输出内容列表。
StringOutput = string
自定义工具调用输出的字符串。
OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
自定义工具调用的文本、图像或文件输出。
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
status: "in_progress" or "completed" or "incomplete"
条目状态,可选 in_progress、completed 或 incomplete,通过 API 返回条目时填充。
"in_progress"
"completed"
"incomplete"
type: "custom_tool_call_output"
类型,固定为 custom_tool_call_output。
"custom_tool_call_output"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
调用方类型,固定为 direct。
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
minLength: 1, maxLength: 64
type: "program" (default: "program")
调用方类型,固定为 program。
"program"
created_by: optional string
创建该条目的执行主体的标识。
parallel_tool_calls: boolean (default: true)
是否允许模型并行执行工具调用。
temperature: number or null (default: 1)
采样温度,范围0到2。0.8等较高值使输出更随机,0.2等较低值使输出更集中、更确定。通常建议只修改此参数或top_p中的一个。
minimum: 0, maximum: 2
tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more
模型生成响应时如何选择工具,参见tools参数了解可调用工具的定义方式。
BetaToolChoiceOptions = "none" or "auto" or "required"
控制模型调用哪个工具,或是否调用工具。
none 表示模型直接生成消息,不调用工具。
auto 表示模型可选择生成消息,或调用一个或多个工具。
required 表示模型必须调用一个或多个工具。
"none"
"auto"
"required"
BetaToolChoiceAllowed object { mode, tools, type }
将模型可用的工具限制为预先定义的集合。
mode: "auto" or "required"
将模型可用的工具限制为预先定义的集合。
auto 允许模型从可用工具中选择,或生成消息。
required 要求模型至少调用一个可用工具。
"auto"
"required"
tools: array of map[unknown]
应允许模型调用的工具定义列表。
对于 Responses API,工具定义列表可以如下所示:
[
{ "type": "function", "name": "get_weather" },
{ "type": "mcp", "server_label": "deepwiki" },
{ "type": "image_generation" }
]
type: "allowed_tools"
允许的工具配置类型,固定为 allowed_tools。
"allowed_tools"
BetaToolChoiceTypes object { type }
指定模型应使用内置工具生成响应,详见内置工具。
type: "file_search" or "web_search_preview" or "computer" or 5 more
模型应使用的托管工具类型,详见内置工具。
允许的值为:
file_searchweb_search_previewcomputercomputer_use_previewcomputer_usecode_interpreterimage_generation
"file_search"
"web_search_preview"
"computer"
"computer_use_preview"
"computer_use"
"web_search_preview_2025_03_11"
"image_generation"
"code_interpreter"
BetaToolChoiceFunction object { name, type }
使用此选项强制模型调用指定函数。
name: string
要调用的函数名称。
type: "function"
对于函数调用,类型固定为 function。
"function"
BetaToolChoiceMcp object { server_label, type, name }
使用此选项强制模型调用远程 MCP 服务器上的指定工具。
server_label: string
要使用的 MCP 服务器标签。
type: "mcp"
对于 MCP 工具,类型固定为 mcp。
"mcp"
name: optional string or null
要在服务器上调用的工具名称。
BetaToolChoiceCustom object { name, type }
使用此选项强制模型调用特定的自定义工具。
name: string
要调用的自定义工具名称。
type: "custom"
对于自定义工具调用,类型固定为 custom。
"custom"
BetaSpecificProgrammaticToolCallingParam object { type }
type: "programmatic_tool_calling" (default: "programmatic_tool_calling")
要调用的工具,固定为 programmatic_tool_calling。
"programmatic_tool_calling"
BetaToolChoiceApplyPatch object { type }
执行工具调用时,强制模型调用 apply_patch 工具。
type: "apply_patch" (default: "apply_patch")
要调用的工具,固定为 apply_patch。
"apply_patch"
BetaToolChoiceShell object { type }
需要调用工具时,强制模型调用 shell 工具。
type: "shell" (default: "shell")
要调用的工具,固定为 shell。
"shell"
tools: array of Function { name, parameters, strict, 6 more } or FileSearch { type, vector_store_ids, filters, 2 more } or Computer { type } or 13 more
模型生成响应时可以调用的工具数组。可以通过设置 tool_choice 参数指定使用哪个工具。
支持以下几类工具:
内置工具:OpenAI提供的扩展能力,如网页搜索和文件搜索,详见内置工具。MCP工具:通过自定义MCP服务器或Google Drive、SharePoint等预定义连接器集成第三方系统,详见MCP工具。函数调用(自定义工具):开发者定义的函数,让模型以强类型参数和输出调用你的代码,详见函数调用;也可使用自定义工具调用自己的代码。
Function object { name, parameters, strict, 6 more }
定义模型可以选择调用的自有代码函数。参阅函数调用。
name: string
要调用的函数名称。
parameters: map[unknown] or null
描述函数参数的 JSON Schema 对象。
strict: boolean or null
是否对此函数工具强制执行严格参数校验。
type: "function" (default: "function")
函数工具类型,固定为 function。
"function"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
"direct"
"programmatic"
async: optional boolean
defer_loading: optional boolean
此函数是否延迟加载并通过工具搜索加载。
description: optional string or null
函数描述,模型据此判断是否调用该函数。
output_schema: optional map[unknown] or null
描述此函数字符串输出中编码的 JSON 值的 JSON Schema 对象。
FileSearch object { type, vector_store_ids, filters, 2 more }
搜索已上传文件中相关内容的工具。参阅文件搜索工具。
type: "file_search" (default: "file_search")
文件搜索工具类型,固定为 file_search。
"file_search"
vector_store_ids: array of string
要搜索的向量存储 ID 列表。
filters: optional ComparisonFilter { 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"
top_p: number or null (default: 1)
核采样是温度采样的替代方式:模型仅考虑累计概率达到top_p的词元。例如0.1表示只考虑累计概率质量前10%的词元。
通常建议只调整此项或 temperature 中的一项,不同时调整两者。
minimum: 0, maximum: 1
background: optional boolean or null (default: false)
是否在后台运行模型响应,详见后台模式。
completed_at: optional number or null
Response完成时的Unix时间戳,单位为秒,仅在状态为completed时存在。
format: unixtime
conversation: optional object { id } or null
此响应所属的对话。该响应的输入条目和输出条目已自动添加到此对话。
id: string
与此响应关联的对话的唯一 ID。
image: optional object { context_compression }
context_compression: "enabled" or "disabled"
实际采用的图像上下文优化策略。
"enabled"
"disabled"
input_transformations: optional array of object { id, action, reason, type }
未传给模型的推理输入,按输入顺序排列。
id: string
原始推理条目的 ID。
action: "removed" (default: "removed")
"removed"
reason: "organization_mismatch" or "end_user_mismatch" or "model_mismatch" or 2 more
"organization_mismatch"
"end_user_mismatch"
"model_mismatch"
"prefix_mismatch"
"turn_boundary"
type: "reasoning" (default: "reasoning")
"reasoning"
max_output_tokens: optional integer or null
响应可生成词元数的上限,包括可见输出词元及推理词元。
max_tool_calls: optional integer or null
一个响应中可处理的内置工具调用总次数上限。此上限适用于所有内置工具调用的合计次数,而非每个工具分别计算。达到上限后,模型进一步调用工具的尝试会被忽略。
moderation: optional object { input, output } or null
如果请求了经审核的补全,则包含响应输入和输出的审核结果。
input: ModerationResult { categories, category_applied_input_types, category_scores, 3 more } or Error { code, message, type }
对响应输入的审核。
ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }
针对响应输入或输出生成的审核结果。
categories: map[boolean]
审核类别到布尔值的映射。输入被某类别标记时,该类别值为 true。
category_applied_input_types: map[array of "text" or "image"]
各类别评分所涵盖的输入模态。
"text"
"image"
category_scores: map[number]
审核类别到分数的映射。
flagged: boolean
表示内容是否被任一类别标记的布尔值。
model: string
生成此结果的审核模型。
type: "moderation_result" (default: "moderation_result")
对象类型,成功审核结果中固定为 moderation_result。
"moderation_result"
Error object { code, message, type }
尝试审核响应输入或输出时产生的错误。
code: string
错误代码。
message: string
错误消息。
type: "error" (default: "error")
对象类型;审核失败时始终为 error。
"error"
output: ModerationResult { categories, category_applied_input_types, category_scores, 3 more } or Error { code, message, type }
对响应输出的审核。
ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }
针对响应输入或输出生成的审核结果。
categories: map[boolean]
审核类别到布尔值的映射。输入被某类别标记时,该类别值为 true。
category_applied_input_types: map[array of "text" or "image"]
各类别评分所涵盖的输入模态。
"text"
"image"
category_scores: map[number]
审核类别到分数的映射。
flagged: boolean
表示内容是否被任一类别标记的布尔值。
model: string
生成此结果的审核模型。
type: "moderation_result" (default: "moderation_result")
对象类型,成功审核结果中固定为 moderation_result。
"moderation_result"
Error object { code, message, type }
尝试审核响应输入或输出时产生的错误。
code: string
错误代码。
message: string
错误消息。
type: "error" (default: "error")
对象类型;审核失败时始终为 error。
"error"
output_text: optional string or null
仅SDK提供的便利属性,聚合output数组中所有output_text条目的文本(若存在),Python和JavaScript SDK支持此属性。
previous_response_id: optional string or null
前一次模型响应的唯一ID,用于多轮对话,详见对话状态。不能与conversation同时使用。
prompt: optional BetaResponsePrompt or null
提示词模板及其变量的引用,详见代码中的提示词版本。
id: string
要使用的提示词模板的唯一标识。
variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile] or null
可选的变量替换映射,用于替换提示词中的变量。替换值可为字符串,也可为图像或文件等其他Response输入类型。
string
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
version: optional string or null
提示词模板的可选版本。
prompt_cache_diagnostics: optional CacheMiss { cache_missed_tokens, reason, type, comparison_reusable_tokens } or CacheHit { type } or ComparisonResponseNotFound { type } or Unavailable { type }
为此响应请求的提示词缓存诊断信息。
CacheMiss object { cache_missed_tokens, reason, type, comparison_reusable_tokens }
cache_missed_tokens: integer
首次检测到差异之后,受影响的输入词元数量估计值。
reason: "model_changed" or "prompt_cache_key_changed" or "tools_changed" or 6 more
未复用提示词缓存的原因。
"model_changed"
"prompt_cache_key_changed"
"tools_changed"
"text_format_changed"
"reasoning_effort_changed"
"verbosity_changed"
"context_compacted"
"input_changed"
"service_tier_changed"
type: "cache_miss" (default: "cache_miss")
"cache_miss"
comparison_reusable_tokens: optional integer
在所比较的响应中,可复用前缀的原始词元数。
CacheHit object { type }
type: "cache_hit" (default: "cache_hit")
"cache_hit"
ComparisonResponseNotFound object { type }
type: "comparison_response_not_found" (default: "comparison_response_not_found")
"comparison_response_not_found"
Unavailable object { type }
type: "unavailable" (default: "unavailable")
"unavailable"
prompt_cache_key: optional string or null
供OpenAI缓存相似请求的响应,以优化缓存命中率,替代user字段,详见提示词缓存。
prompt_cache_options: optional object { mode, ttl, comparison_response_id }
应用于该响应的提示词缓存选项。支持 gpt-5.6 及更新模型。
mode: "implicit" or "explicit"
是否启用了隐式提示词缓存断点。
"implicit"
"explicit"
ttl: "30m" or "12h"
应用于每个缓存断点的最短保留时间。
"30m"
"12h"
comparison_response_id: optional string or null
用于提示词缓存诊断比较的响应 ID。
prompt_cache_retention: optional "in_memory" or "24h" or null
已弃用,改用 prompt_cache_options.ttl。
提示词缓存保留策略。设为24h启用扩展缓存,使缓存前缀保持活跃更久,最长24小时,详见缓存保留。此字段表达最长保留策略,prompt_cache_options.ttl表达最短缓存寿命;两者独立、互不影响。gpt-5.5、gpt-5.5-pro及后续模型仅支持24h。
对于同时支持 in_memory 和 24h 的较早模型,默认值取决于组织的数据保留策略:
未启用ZDR的组织默认使用24h;启用ZDR且未指定prompt_cache_retention的组织默认使用in_memory。
"in_memory"
"24h"
reasoning: optional object { context, effort, generate_summary, 2 more } or null
推理模型的配置选项。
context: optional "auto" or "current_turn" or "all_turns" or null
控制后续轮次向模型呈现哪些推理条目。省略或设为auto时由模型决定上下文模式。gpt-5.6系列默认all_turns,更早模型默认current_turn。
在响应中返回时,表示本次响应实际使用的推理上下文模式。
"auto"
"current_turn"
"all_turns"
effort: optional "none" or "minimal" or "low" or 4 more or null (default: "medium")
限制推理模型的推理努力程度。目前支持none、minimal、low、medium、high、xhigh和max。降低努力程度可能加快响应并减少推理词元。并非所有模型支持每个值,具体见推理指南。
"none"
"minimal"
"low"
"medium"
"high"
"xhigh"
"max"
generate_summary: optional "auto" or "concise" or "detailed" or null
已弃用:请改用 summary。
模型推理的摘要,有助于调试和理解推理过程。可选auto、concise或detailed。
"auto"
"concise"
"detailed"
mode: optional string or "standard" or "pro"
控制请求的推理执行模式。
当此字段出现在返回的响应中时,表示实际使用的执行模式。
string
"standard" or "pro"
控制请求的推理执行模式。
当此字段出现在返回的响应中时,表示实际使用的执行模式。
"standard"
"pro"
summary: optional "auto" or "concise" or "detailed" or null
模型推理的摘要,有助于调试和理解推理过程。可选auto、concise或detailed。
computer-use-preview 模型及 gpt-5 之后的推理模型均支持 concise。
"auto"
"concise"
"detailed"
safety_identifier: optional string or null
稳定的用户标识,帮助检测应用中可能违反OpenAI使用政策的用户。应使用唯一标识各用户、最长128字符的字符串。建议对用户名或电子邮箱进行哈希,避免发送个人身份信息,详见安全标识。
maxLength: 128
service_tier: optional BetaServiceTier or null (default: "auto")
指定处理请求所采用的服务类型。
auto使用项目设置中的服务层级,未另行配置时为default。default使用所选模型的标准价格及性能;flex使用Flex处理。在Responses或Chat Completions请求中设置service_tier=fast或service_tier=priority可启用快速模式,不论传入哪一个,原文此处写明响应显示priority。ultrafast使用受访问控制的Ultrafast层级,当前此原文列为可供gpt-5.6-sol使用,响应显示ultrafast。未设置时默认auto。
设置 service_tier 后,响应体中的同名字段反映实际采用的处理模式,可能与请求参数的值不同。
"auto"
"default"
"flex"
"scale"
"priority"
"fast"
"ultrafast"
status: optional BetaResponseStatus
响应生成状态,可选completed、failed、in_progress、cancelled、queued或incomplete。
"completed"
"failed"
"in_progress"
"cancelled"
"queued"
"incomplete"
text: optional BetaResponseTextConfig
模型文本响应的配置选项,可为纯文本或结构化JSON数据,详见下列指南。
format: optional BetaResponseFormatTextConfig
指定模型必须输出的格式的对象。
配置{ "type": "json_schema" }可启用结构化输出,确保模型匹配提供的JSON Schema,详见结构化输出指南。
默认格式为 { "type": "text" },没有额外选项。
不建议用于 gpt-4o 及后续模型:
设置{ "type": "json_object" }可启用旧版JSON模式,确保模型生成合法JSON。支持json_schema的模型优先使用后者。
Text object { type }
默认响应格式,用于生成文本响应。
type: "text"
定义的响应格式类型,固定为 text。
"text"
BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }
JSON Schema响应格式,用于生成结构化JSON,详见结构化输出。
JSONObject object { type }
JSON对象响应格式,是生成JSON响应的旧方式。支持json_schema的模型建议使用后者。注意,若system或user消息没有明确要求生成JSON,模型不会自行生成JSON。
type: "json_object"
定义的响应格式类型,固定为 json_object。
"json_object"
verbosity: optional "low" or "medium" or "high" or null (default: "medium")
约束模型响应的详细程度。较低值生成更简洁的响应,较高值生成更详细的响应。目前支持low、medium和high,默认为medium。
"low"
"medium"
"high"
tool_usage: optional object { image_gen, web_search }
托管工具报告的用量,独立于基础模型的 usage。无法取得工具用量时可省略。若返回该字段,没有用量记录的工具类别计数为零。
image_gen 合计所有图像生成调用中可取得的词元计数。可能跳过用量记录不完整的调用。输出词元明细和缓存输入计数可省略,省略缓存计数表示缓存用量未知。
web_search.num_requests 统计可计费的搜索次数。打折搜索与打开网页等操作不计入。最终费用请以账单记录为准。
image_gen: object { input_tokens, input_tokens_details, output_tokens, 4 more }
图像生成工具调用的汇总用量统计。
input_tokens: integer
输入提示词中的图像与文本词元数量。
input_tokens_details: object { image_tokens, text_tokens }
图像生成的输入词元明细。
image_tokens: integer
输入提示词中的图像词元数量。
text_tokens: integer
输入提示词中的文本词元数量。
output_tokens: integer
模型生成的输出词元数量。
total_tokens: integer
图像生成使用的图像和文本词元总数。
cached_tokens: optional integer
cached_tokens_details: optional object { cached_image_tokens, cached_text_tokens }
cached_image_tokens: integer
cached_text_tokens: integer
output_tokens_details: optional object { image_tokens, text_tokens }
图像生成的输出词元明细。
image_tokens: integer
模型生成的图像输出词元数量。
text_tokens: integer
模型生成的文本输出词元数量。
web_search: object { num_requests }
网页搜索工具调用的汇总计费用量统计。
num_requests: integer
发起的计费网页搜索请求次数。
top_logprobs: optional integer or null
0到20之间的整数,指定每个词元位置返回多少个最可能词元及其对数概率;实际返回数量有时会少于请求值。
minimum: 0, maximum: 20
truncation: optional "auto" or "disabled" or null (default: "disabled")
模型响应的截断策略。
auto:输入超出模型的上下文窗口时,从对话开头移除条目以适配窗口。对部分模型,API 会先从输入上限扣除模型允许的最大输出量,再统计词元。因此,即使设置较低的max_output_tokens,也可能更早开始截断。disabled(默认值):输入超出模型上下文窗口时,请求会失败并返回 400 错误。
"auto"
"disabled"
usage: optional BetaResponseUsage or null
词元用量详情,包括输入词元、输出词元、输出词元分类和词元总数。
input_tokens: integer
输入词元数量。
input_tokens_details: object { cache_write_tokens, cached_tokens, cache_write_tokens_details }
输入词元的详细分类统计。
cache_write_tokens: integer
已写入缓存的输入词元数量。
cached_tokens: integer
从缓存读取的词元数量,详见提示词缓存。
cache_write_tokens_details: optional object { ttl_12h_tokens, ttl_30m_tokens }
ttl_12h_tokens: integer
以保留 12 小时的方式写入的输入词元数量。
ttl_30m_tokens: integer
以保留 30 分钟的方式写入的输入词元数量。
output_tokens: integer
输出词元数量。
output_tokens_details: object { reasoning_tokens }
输出词元的详细分类统计。
reasoning_tokens: integer
推理词元数量。
total_tokens: integer
使用的总词元数。
user: optional string or null
此字段正被safety_identifier和prompt_cache_key取代,维持缓存优化应改用prompt_cache_key。它是终端用户的稳定标识,通过更好地归类相似请求提高命中率,也帮助OpenAI检测和防止滥用,详见安全标识。
sequence_number: integer
此事件的序列号。
type: "response.created"
类型,固定为response.created。
"response.created"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.created",
"response": {
"id": "resp_67ccfcdd16748190a91872c75d38539e09e4d4aac714747c",
"object": "response",
"access_programs": null,
"created_at": 1741487325,
"status": "in_progress",
"completed_at": null,
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-6.2-astra",
"output": [],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null
},
"store": true,
"temperature": 1,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [],
"top_p": 1,
"truncation": "disabled",
"usage": null,
"user": null,
"metadata": {}
},
"sequence_number": 1
}
response.in_progress
响应进行中时发出。
结构定义
结构名称: BetaResponseInProgressEvent
response: BetaResponse
正在进行的响应。
id: string
此响应的唯一标识符。
access_programs: object { cyber } or null
created_at: number
此响应创建时的 Unix 时间戳,单位为秒。
format: unixtime
error: BetaResponseError or null
模型未能生成响应时返回的错误对象。
code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 18 more
此响应的错误代码。
"server_error"
"rate_limit_exceeded"
"invalid_prompt"
"data_residency_mismatch"
"bio_policy"
"misalignment_policy_violation"
"vector_store_timeout"
"invalid_image"
"invalid_image_format"
"invalid_base64_image"
"invalid_image_url"
"image_too_large"
"image_too_small"
"image_parse_error"
"image_content_policy_violation"
"invalid_image_mode"
"image_file_too_large"
"unsupported_image_media_type"
"empty_image_file"
"failed_to_download_image"
"image_file_not_found"
message: string
便于人阅读的错误说明。
misalignment: optional object { detailed_explanation, error_type, review_target, steer }
detailed_explanation: optional string
对此次阻止操作的公开说明。
error_type: optional string or "potentially_unintended_data_transfer" or "potentially_unintended_data_access" or "potentially_unintended_destructive_activity" or "other"
可选的分类;客户端必须能够接受其他值。
string
SafetyAlertErrorType = "potentially_unintended_data_transfer" or "potentially_unintended_data_access" or "potentially_unintended_destructive_activity" or "other"
可选的分类;客户端必须能够接受其他值。
"potentially_unintended_data_transfer"
"potentially_unintended_data_access"
"potentially_unintended_destructive_activity"
"other"
review_target: optional string or null
用于明确继续此次审查的不透明目标;不可用时为 null。
pattern: ^[A-Za-z0-9._~:-]+$, minLength: 1, maxLength: 96
steer: optional object { message }
可选的公开继续指令。
message: string
公开的继续指令。
param: optional string or null
与错误相关的请求参数;未记录时为 null。
type: optional string or null
原始错误类型;未记录时为 null。
incomplete_details: object { reason } or null
说明响应为何未完成的详细信息。
reason: optional "max_output_tokens" or "max_messages" or "content_filter" or "steered"
响应未完成的原因。steered表示响应在收到WebSocket response.steer事件后于安全输出边界停止;服务器随后可自动使用排队输入创建后继响应。
"max_output_tokens"
"max_messages"
"content_filter"
"steered"
instructions: string or array of BetaEasyInputMessage or Message { content, role, agent, 2 more } or BetaResponseOutputMessage or 33 more or null
插入模型上下文的系统消息或开发者消息。
与previous_response_id一起使用时,前一响应的instructions不会传入下一响应,便于在新响应中替换system或developer消息。
string
提供给模型的文本输入,等同于developer角色的文本输入。
InputItemList = array of BetaEasyInputMessage or Message { content, role, agent, 2 more } or BetaResponseOutputMessage or 33 more
提供给模型的一个或多个输入条目组成的列表,其中可以包含不同类型的内容。
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
生成该条目的智能体的规范名称。
metadata: map[string] or null
可附加到对象的一组16个键值对,用于结构化保存附加信息,并通过API或控制台查询对象。
键为最长64个字符的字符串,值为最长512个字符的字符串。
model: "gpt-6-astra" or "gpt-6.2-astra" or "gpt-6.1-sol" or 112 more or string
生成响应的模型ID,例如gpt-6.2-astra。OpenAI提供能力、性能和价格各异的模型,可在模型指南浏览比较。
"gpt-6-astra" or "gpt-6.2-astra" or "gpt-6.1-sol" or 112 more
生成响应的模型ID,例如gpt-6.2-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
object: "response"
此资源的对象类型,始终为 response。
"response"
output: array of BetaResponseOutputItem
模型生成的内容条目数组。
output数组的长度和顺序取决于模型响应。不要假定首个条目一定是包含生成内容的assistant消息;可考虑使用SDK支持的output_text属性。
BetaResponseOutputMessage object { id, content, role, 4 more }
模型输出的消息。
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
从文件中检索出的文本。
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 { id, output, status, 7 more }
id: string
函数调用工具输出的唯一 ID。
output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
你的代码产生的函数调用输出,可为字符串或输出内容列表。
StringOutput = string
函数调用输出的字符串。
OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
函数调用的文本、图像或文件输出。
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
status: "in_progress" or "completed" or "incomplete"
条目状态,可选 in_progress、completed 或 incomplete,通过 API 返回条目时填充。
"in_progress"
"completed"
"incomplete"
type: "function_call_output"
类型,固定为 function_call_output。
"function_call_output"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
call_id: optional string
模型生成的函数工具调用的唯一 ID。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
调用方类型,固定为 direct。
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
minLength: 1, maxLength: 64
type: "program" (default: "program")
调用方类型,固定为 program。
"program"
created_by: optional string
创建该条目的执行主体的标识。
name: optional string
产生输出的工具名称。
namespace: optional string
产生输出的工具所属命名空间。
AgentMessage object { id, author, content, 3 more }
id: string
此智能体消息的唯一 ID。
author: string
发送方智能体的标识。
content: array of BetaResponseInputText or BetaResponseOutputText or Text { text, type } or 7 more
智能体之间发送的加密内容。
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
BetaResponseOutputText object { annotations, logprobs, text, type }
模型输出的文本。
Text object { text, type }
文本内容。
text: string
type: "text" (default: "text")
"text"
SummaryText object { text, type }
模型生成的摘要文本。
text: string
模型到目前为止生成的推理输出摘要。
type: "summary_text" (default: "summary_text")
类型,固定为 summary_text。
"summary_text"
ReasoningText object { text, type }
模型生成的推理文本。
text: string
模型生成的推理文本。
type: "reasoning_text" (default: "reasoning_text")
类型,固定为 reasoning_text。
"reasoning_text"
BetaResponseOutputRefusal object { refusal, type }
模型的拒绝响应。
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
ComputerScreenshot object { detail, file_id, image_url, 2 more }
计算机屏幕截图。
detail: BetaImageDetail
发送给模型的截图图像的细节级别,可选 high、low、auto 或 original,默认为 auto。
file_id: string or null
包含截图的已上传文件的标识。
image_url: string or null
截图图像的 URL。
format: uri
type: "computer_screenshot" (default: "computer_screenshot")
指定事件类型。对于计算机屏幕截图,此属性固定为 computer_screenshot。
"computer_screenshot"
prompt_cache_breakpoint: optional object { mode, ttl }
标记可复用提示词前缀的精确结束位置。省略 ttl 时,断点继承请求中的 prompt_cache_options.ttl;该边界不会按词元块取整。
mode: "explicit" (default: "explicit")
断点模式,固定为 explicit。
"explicit"
ttl: optional "30m" or "12h"
此缓存断点的最短存续时间,默认为请求的 TTL。
"30m"
"12h"
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
EncryptedContent object { encrypted_content, type }
不透明的加密内容,由 Responses API 在受信任的模型执行环境中解密。
encrypted_content: string
不透明的加密内容。
type: "encrypted_content" (default: "encrypted_content")
输入条目的类型,固定为 encrypted_content。
"encrypted_content"
recipient: string
接收方智能体的标识。
type: "agent_message" (default: "agent_message")
条目类型,固定为 agent_message。
"agent_message"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
MultiAgentCall object { id, action, arguments, 3 more }
id: string
该多智能体调用条目的唯一 ID。
action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more
要执行的多智能体操作。
"spawn_agent"
"interrupt_agent"
"list_agents"
"send_message"
"followup_task"
"wait_agent"
arguments: string
为该操作生成的参数,格式为 JSON 字符串。
call_id: string
关联调用与其输出的唯一 ID。
type: "multi_agent_call" (default: "multi_agent_call")
多智能体调用的类型,固定为 multi_agent_call。
"multi_agent_call"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
MultiAgentCallOutput object { id, action, call_id, 3 more }
id: string
此多智能体调用输出条目的唯一 ID。
action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more
生成此结果的多智能体操作。
"spawn_agent"
"interrupt_agent"
"list_agents"
"send_message"
"followup_task"
"wait_agent"
call_id: string
此多智能体调用的唯一 ID。
output: array of BetaResponseOutputText
多智能体操作返回的文本。
annotations: array of FileCitation { file_id, filename, index, type } or URLCitation { end_index, start_index, title, 2 more } or ContainerFileCitation { container_id, end_index, file_id, 3 more } or FilePath { file_id, index, type }
文本输出的注解。
logprobs: array of object { token, bytes, logprob, top_logprobs }
text: string
模型输出的文本内容。
type: "output_text" (default: "output_text")
输出文本类型,固定为 output_text。
type: "multi_agent_call_output" (default: "multi_agent_call_output")
多智能体结果的类型,固定为 multi_agent_call_output。
"multi_agent_call_output"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
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
生成该条目的智能体的规范名称。
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
单击操作。
actions: optional BetaComputerActionList
computer_use的扁平化批量操作。每个操作包含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
供计算机使用工具使用的屏幕截图图像。
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"
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
生成该条目的智能体的规范名称。
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 }
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: "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
生成该条目的智能体的规范名称。
Compaction object { id, encrypted_content, type, 2 more }
v1/responses/compact API生成的压缩条目。
id: string
压缩条目的唯一 ID。
encrypted_content: string
压缩生成的加密内容。
type: "compaction" (default: "compaction")
类型,固定为 compaction。
"compaction"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
created_by: optional string
创建该条目的执行主体的标识。
ImageGenerationCall object { id, result, status, 10 more }
模型发起的图像生成请求。
id: string
图像生成调用的唯一 ID。
result: string or null
Base64 编码的生成图像。
status: "in_progress" or "completed" or "generating" or "failed"
图像生成调用的状态。
"in_progress"
"completed"
"generating"
"failed"
type: "image_generation_call"
类型,固定为 image_generation_call。
"image_generation_call"
action: optional "generate" or "edit" or "auto" or null
用于图像生成的操作。
"generate"
"edit"
"auto"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
background: optional "transparent" or "opaque" or "auto" or null
生成图像使用的背景设置。
"transparent"
"opaque"
"auto"
error: optional object { code, message, param, 2 more }
审核失败的详情,如可用。
code: string or null
错误代码。
message: string
错误描述。
param: string or null
关联的请求参数。
type: string
错误类型。
moderation_details: optional object { categories, moderation_stage }
moderation_blocked 错误的公开详情,如可用。
categories: array of string
公开的审核类别,未来可能增加新的类别值。
moderation_stage: "input" or "output" or "unknown"
审核阻止图像生成调用的阶段。
"input"
"output"
"unknown"
output_format: optional "png" or "webp" or "jpeg" or 2 more or null
生成图像使用的输出格式。
"png"
"webp"
"jpeg"
"gif"
"svg"
quality: optional "low" or "medium" or "high" or 3 more or null
图像生成工具调用生成的图像质量,可选 low、medium、high、xhigh、max 或 auto。
"low"
"medium"
"high"
"xhigh"
"max"
"auto"
revised_prompt: optional string or null
模型改写提示词后实际使用的提示词。
size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or null
图像尺寸,采用 WIDTHxHEIGHT 字符串形式,例如 1536x864。
string
"1024x1024" or "1024x1536" or "1536x1024"
图像尺寸,采用 WIDTHxHEIGHT 字符串形式,例如 1536x864。
"1024x1024"
"1024x1536"
"1536x1024"
svg_usage: optional object { input_tokens, model, output_tokens, 2 more }
input_tokens: integer
model: string
output_tokens: integer
reasoning_tokens: integer
total_tokens: integer
CodeInterpreterCall object { id, code, container_id, 4 more }
运行代码的工具调用。
id: string
代码解释器工具调用的唯一 ID。
code: string or null
要运行的代码,不可用时为 null。
container_id: string
运行代码使用的容器 ID。
outputs: array of Logs { logs, type } or Image { type, url } or null
代码解释器产生的日志、图像等输出;没有可用输出时可为null。
Logs object { logs, type }
代码解释器的日志输出。
logs: string
代码解释器的日志输出。
type: "logs" (default: "logs")
类型,固定为 logs。
"logs"
Image object { type, url }
代码解释器的图像输出。
type: "image" (default: "image")
类型,固定为 image。
"image"
url: string
代码解释器输出图像的 URL。
format: uri
status: "in_progress" or "completed" or "incomplete" or 2 more
代码解释器工具调用的状态,有效值为 in_progress、completed、incomplete、interpreting 和 failed。
"in_progress"
"completed"
"incomplete"
"interpreting"
"failed"
type: "code_interpreter_call" (default: "code_interpreter_call")
类型,固定为 code_interpreter_call。
"code_interpreter_call"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
LocalShellCall object { id, action, call_id, 3 more }
在本地 shell 上运行命令的工具调用。
id: string
本地 shell 调用的唯一 ID。
action: object { command, env, type, 3 more }
在服务器上执行 shell 命令。
command: array of string
要运行的命令。
env: map[string]
要为命令设置的环境变量。
type: "exec" (default: "exec")
类型,固定为 exec。
"exec"
timeout_ms: optional integer or null
可选的命令超时时长,单位为毫秒。
user: optional string or null
可选的运行命令的用户。
working_directory: optional string or null
可选的运行命令的工作目录。
call_id: string
模型生成的本地 shell 工具调用的唯一 ID。
status: "in_progress" or "completed" or "incomplete"
本地 shell 调用的状态。
"in_progress"
"completed"
"incomplete"
type: "local_shell_call"
类型,固定为 local_shell_call。
"local_shell_call"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
LocalShellCallOutput object { id, output, type, 2 more }
本地 shell 工具调用的输出。
id: string
模型生成的本地 shell 工具调用的唯一 ID。
output: string
本地 shell 工具调用输出的 JSON 字符串。
type: "local_shell_call_output"
类型,固定为 local_shell_call_output。
"local_shell_call_output"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
status: optional "in_progress" or "completed" or "incomplete" or null
条目状态,可选 in_progress、completed 或 incomplete。
"in_progress"
"completed"
"incomplete"
ShellCall object { id, action, call_id, 6 more }
在托管环境中执行一个或多个 shell 命令的工具调用。
id: string
shell 工具调用的唯一 ID,通过 API 返回此条目时填充。
action: object { commands, max_output_length, timeout_ms }
描述如何运行工具调用的 shell 命令及限制。
commands: array of string
max_output_length: integer or null
可选的每个命令返回的最大字符数。
timeout_ms: integer or null
可选的命令超时时长,单位为毫秒。
call_id: string
模型生成的 shell 工具调用的唯一 ID。
environment: BetaResponseLocalEnvironment or BetaResponseContainerReference or null
表示使用本地环境执行 shell 操作。
BetaResponseLocalEnvironment object { type }
表示使用本地环境执行 shell 操作。
type: "local" (default: "local")
环境类型,固定为 local。
"local"
BetaResponseContainerReference object { container_id, type }
表示通过 /v1/containers 创建的容器。
container_id: string
type: "container_reference" (default: "container_reference")
环境类型,固定为 container_reference。
"container_reference"
status: "in_progress" or "completed" or "incomplete"
shell 调用状态,可选 in_progress、completed 或 incomplete。
"in_progress"
"completed"
"incomplete"
type: "shell_call" (default: "shell_call")
类型,固定为 shell_call。
"shell_call"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建此工具调用的实体的 ID。
ShellCallOutput object { id, call_id, max_output_length, 6 more }
shell 工具调用发出的输出。
id: string
shell 调用输出的唯一 ID,通过 API 返回此条目时填充。
call_id: string
模型生成的 shell 工具调用的唯一 ID。
max_output_length: integer or null
shell 命令输出的最大长度,由模型生成,应与原始输出一并回传。
output: array of object { outcome, stderr, stdout, created_by }
shell 调用输出内容的数组。
outcome: Timeout { type } or Exit { exit_code, type }
表示 shell 调用输出块的退出结果(包含退出码)或超时结果。
Timeout object { type }
表示 shell 调用超过其配置的时间限制。
type: "timeout" (default: "timeout")
结果类型,固定为 timeout。
"timeout"
Exit object { exit_code, type }
表示 shell 命令已结束,并返回退出码。
exit_code: integer
shell 进程的退出码。
type: "exit" (default: "exit")
结果类型,固定为 exit。
"exit"
stderr: string
捕获的标准错误输出。
stdout: string
捕获的标准输出。
created_by: optional string
创建该条目的执行主体的标识。
status: "in_progress" or "completed" or "incomplete"
shell 调用输出的状态,可选 in_progress、completed 或 incomplete。
"in_progress"
"completed"
"incomplete"
type: "shell_call_output" (default: "shell_call_output")
shell 调用输出的类型,固定为 shell_call_output。
"shell_call_output"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建该条目的执行主体的标识。
ApplyPatchCall object { id, call_id, operation, 5 more }
通过创建、删除或更新文件来应用文件差异的工具调用。
id: string
apply_patch 工具调用的唯一 ID,通过 API 返回此条目时填充。
call_id: string
模型生成的 apply_patch 工具调用的唯一 ID。
operation: CreateFile { diff, path, type } or DeleteFile { path, type } or UpdateFile { diff, path, type }
通过 apply_patch 应用的 create_file、delete_file 或 update_file 操作之一。
CreateFile object { diff, path, type }
描述如何通过 apply_patch 工具创建文件的指令。
diff: string
要应用的差异。
path: string
要创建的文件路径。
type: "create_file" (default: "create_file")
使用提供的差异创建新文件。
"create_file"
DeleteFile object { path, type }
描述如何通过 apply_patch 工具删除文件的指令。
path: string
要删除的文件路径。
type: "delete_file" (default: "delete_file")
删除指定文件。
"delete_file"
UpdateFile object { diff, path, type }
描述如何通过 apply_patch 工具更新文件的指令。
diff: string
要应用的差异。
path: string
要更新的文件路径。
type: "update_file" (default: "update_file")
使用提供的差异更新已有文件。
"update_file"
status: "in_progress" or "completed"
apply_patch 工具调用状态,可选 in_progress 或 completed。
"in_progress"
"completed"
type: "apply_patch_call" (default: "apply_patch_call")
类型,固定为 apply_patch_call。
"apply_patch_call"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建此工具调用的实体的 ID。
ApplyPatchCallOutput object { id, call_id, status, 5 more }
apply_patch 工具调用发出的输出。
id: string
apply_patch 工具调用输出的唯一 ID,通过 API 返回此条目时填充。
call_id: string
模型生成的 apply_patch 工具调用的唯一 ID。
status: "completed" or "failed"
apply_patch 工具调用输出的状态,可选 completed 或 failed。
"completed"
"failed"
type: "apply_patch_call_output" (default: "apply_patch_call_output")
类型,固定为 apply_patch_call_output。
"apply_patch_call_output"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建此工具调用输出的实体的 ID。
output: optional string or null
apply_patch 工具返回的可选文本输出。
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
工具调用的错误,如有。
output: optional string or null
工具调用的输出。
status: optional "in_progress" or "completed" or "incomplete" or 2 more
工具调用状态,可选 in_progress、completed、incomplete、calling 或 failed。
"in_progress"
"completed"
"incomplete"
"calling"
"failed"
McpListTools object { id, server_label, tools, 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
决定的可选理由。
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 { id, call_id, output, 5 more }
id: string
自定义工具调用输出条目的唯一 ID。
call_id: string
调用 ID,用于将此自定义工具调用输出映射到自定义工具调用。
output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
你的代码生成的自定义工具输出,可为字符串或输出内容列表。
StringOutput = string
自定义工具调用输出的字符串。
OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
自定义工具调用的文本、图像或文件输出。
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
status: "in_progress" or "completed" or "incomplete"
条目状态,可选 in_progress、completed 或 incomplete,通过 API 返回条目时填充。
"in_progress"
"completed"
"incomplete"
type: "custom_tool_call_output"
类型,固定为 custom_tool_call_output。
"custom_tool_call_output"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
调用方类型,固定为 direct。
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
minLength: 1, maxLength: 64
type: "program" (default: "program")
调用方类型,固定为 program。
"program"
created_by: optional string
创建该条目的执行主体的标识。
parallel_tool_calls: boolean (default: true)
是否允许模型并行执行工具调用。
temperature: number or null (default: 1)
采样温度,范围0到2。0.8等较高值使输出更随机,0.2等较低值使输出更集中、更确定。通常建议只修改此参数或top_p中的一个。
minimum: 0, maximum: 2
tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more
模型生成响应时如何选择工具,参见tools参数了解可调用工具的定义方式。
BetaToolChoiceOptions = "none" or "auto" or "required"
控制模型调用哪个工具,或是否调用工具。
none 表示模型直接生成消息,不调用工具。
auto 表示模型可选择生成消息,或调用一个或多个工具。
required 表示模型必须调用一个或多个工具。
"none"
"auto"
"required"
BetaToolChoiceAllowed object { mode, tools, type }
将模型可用的工具限制为预先定义的集合。
mode: "auto" or "required"
将模型可用的工具限制为预先定义的集合。
auto 允许模型从可用工具中选择,或生成消息。
required 要求模型至少调用一个可用工具。
"auto"
"required"
tools: array of map[unknown]
应允许模型调用的工具定义列表。
对于 Responses API,工具定义列表可以如下所示:
[
{ "type": "function", "name": "get_weather" },
{ "type": "mcp", "server_label": "deepwiki" },
{ "type": "image_generation" }
]
type: "allowed_tools"
允许的工具配置类型,固定为 allowed_tools。
"allowed_tools"
BetaToolChoiceTypes object { type }
指定模型应使用内置工具生成响应,详见内置工具。
type: "file_search" or "web_search_preview" or "computer" or 5 more
模型应使用的托管工具类型,详见内置工具。
允许的值为:
file_searchweb_search_previewcomputercomputer_use_previewcomputer_usecode_interpreterimage_generation
"file_search"
"web_search_preview"
"computer"
"computer_use_preview"
"computer_use"
"web_search_preview_2025_03_11"
"image_generation"
"code_interpreter"
BetaToolChoiceFunction object { name, type }
使用此选项强制模型调用指定函数。
name: string
要调用的函数名称。
type: "function"
对于函数调用,类型固定为 function。
"function"
BetaToolChoiceMcp object { server_label, type, name }
使用此选项强制模型调用远程 MCP 服务器上的指定工具。
server_label: string
要使用的 MCP 服务器标签。
type: "mcp"
对于 MCP 工具,类型固定为 mcp。
"mcp"
name: optional string or null
要在服务器上调用的工具名称。
BetaToolChoiceCustom object { name, type }
使用此选项强制模型调用特定的自定义工具。
name: string
要调用的自定义工具名称。
type: "custom"
对于自定义工具调用,类型固定为 custom。
"custom"
BetaSpecificProgrammaticToolCallingParam object { type }
type: "programmatic_tool_calling" (default: "programmatic_tool_calling")
要调用的工具,固定为 programmatic_tool_calling。
"programmatic_tool_calling"
BetaToolChoiceApplyPatch object { type }
执行工具调用时,强制模型调用 apply_patch 工具。
type: "apply_patch" (default: "apply_patch")
要调用的工具,固定为 apply_patch。
"apply_patch"
BetaToolChoiceShell object { type }
需要调用工具时,强制模型调用 shell 工具。
type: "shell" (default: "shell")
要调用的工具,固定为 shell。
"shell"
tools: array of Function { name, parameters, strict, 6 more } or FileSearch { type, vector_store_ids, filters, 2 more } or Computer { type } or 13 more
模型生成响应时可以调用的工具数组。可以通过设置 tool_choice 参数指定使用哪个工具。
支持以下几类工具:
内置工具:OpenAI提供的扩展能力,如网页搜索和文件搜索,详见内置工具。MCP工具:通过自定义MCP服务器或Google Drive、SharePoint等预定义连接器集成第三方系统,详见MCP工具。函数调用(自定义工具):开发者定义的函数,让模型以强类型参数和输出调用你的代码,详见函数调用;也可使用自定义工具调用自己的代码。
Function object { name, parameters, strict, 6 more }
定义模型可以选择调用的自有代码函数。参阅函数调用。
name: string
要调用的函数名称。
parameters: map[unknown] or null
描述函数参数的 JSON Schema 对象。
strict: boolean or null
是否对此函数工具强制执行严格参数校验。
type: "function" (default: "function")
函数工具类型,固定为 function。
"function"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
"direct"
"programmatic"
async: optional boolean
defer_loading: optional boolean
此函数是否延迟加载并通过工具搜索加载。
description: optional string or null
函数描述,模型据此判断是否调用该函数。
output_schema: optional map[unknown] or null
描述此函数字符串输出中编码的 JSON 值的 JSON Schema 对象。
FileSearch object { type, vector_store_ids, filters, 2 more }
搜索已上传文件中相关内容的工具。参阅文件搜索工具。
type: "file_search" (default: "file_search")
文件搜索工具类型,固定为 file_search。
"file_search"
vector_store_ids: array of string
要搜索的向量存储 ID 列表。
filters: optional ComparisonFilter { 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"
top_p: number or null (default: 1)
核采样是温度采样的替代方式:模型仅考虑累计概率达到top_p的词元。例如0.1表示只考虑累计概率质量前10%的词元。
通常建议只调整此项或 temperature 中的一项,不同时调整两者。
minimum: 0, maximum: 1
background: optional boolean or null (default: false)
是否在后台运行模型响应,详见后台模式。
completed_at: optional number or null
Response完成时的Unix时间戳,单位为秒,仅在状态为completed时存在。
format: unixtime
conversation: optional object { id } or null
此响应所属的对话。该响应的输入条目和输出条目已自动添加到此对话。
id: string
与此响应关联的对话的唯一 ID。
image: optional object { context_compression }
context_compression: "enabled" or "disabled"
实际采用的图像上下文优化策略。
"enabled"
"disabled"
input_transformations: optional array of object { id, action, reason, type }
未传给模型的推理输入,按输入顺序排列。
id: string
原始推理条目的 ID。
action: "removed" (default: "removed")
"removed"
reason: "organization_mismatch" or "end_user_mismatch" or "model_mismatch" or 2 more
"organization_mismatch"
"end_user_mismatch"
"model_mismatch"
"prefix_mismatch"
"turn_boundary"
type: "reasoning" (default: "reasoning")
"reasoning"
max_output_tokens: optional integer or null
响应可生成词元数的上限,包括可见输出词元及推理词元。
max_tool_calls: optional integer or null
一个响应中可处理的内置工具调用总次数上限。此上限适用于所有内置工具调用的合计次数,而非每个工具分别计算。达到上限后,模型进一步调用工具的尝试会被忽略。
moderation: optional object { input, output } or null
如果请求了经审核的补全,则包含响应输入和输出的审核结果。
input: ModerationResult { categories, category_applied_input_types, category_scores, 3 more } or Error { code, message, type }
对响应输入的审核。
ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }
针对响应输入或输出生成的审核结果。
categories: map[boolean]
审核类别到布尔值的映射。输入被某类别标记时,该类别值为 true。
category_applied_input_types: map[array of "text" or "image"]
各类别评分所涵盖的输入模态。
"text"
"image"
category_scores: map[number]
审核类别到分数的映射。
flagged: boolean
表示内容是否被任一类别标记的布尔值。
model: string
生成此结果的审核模型。
type: "moderation_result" (default: "moderation_result")
对象类型,成功审核结果中固定为 moderation_result。
"moderation_result"
Error object { code, message, type }
尝试审核响应输入或输出时产生的错误。
code: string
错误代码。
message: string
错误消息。
type: "error" (default: "error")
对象类型;审核失败时始终为 error。
"error"
output: ModerationResult { categories, category_applied_input_types, category_scores, 3 more } or Error { code, message, type }
对响应输出的审核。
ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }
针对响应输入或输出生成的审核结果。
categories: map[boolean]
审核类别到布尔值的映射。输入被某类别标记时,该类别值为 true。
category_applied_input_types: map[array of "text" or "image"]
各类别评分所涵盖的输入模态。
"text"
"image"
category_scores: map[number]
审核类别到分数的映射。
flagged: boolean
表示内容是否被任一类别标记的布尔值。
model: string
生成此结果的审核模型。
type: "moderation_result" (default: "moderation_result")
对象类型,成功审核结果中固定为 moderation_result。
"moderation_result"
Error object { code, message, type }
尝试审核响应输入或输出时产生的错误。
code: string
错误代码。
message: string
错误消息。
type: "error" (default: "error")
对象类型;审核失败时始终为 error。
"error"
output_text: optional string or null
仅SDK提供的便利属性,聚合output数组中所有output_text条目的文本(若存在),Python和JavaScript SDK支持此属性。
previous_response_id: optional string or null
前一次模型响应的唯一ID,用于多轮对话,详见对话状态。不能与conversation同时使用。
prompt: optional BetaResponsePrompt or null
提示词模板及其变量的引用,详见代码中的提示词版本。
id: string
要使用的提示词模板的唯一标识。
variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile] or null
可选的变量替换映射,用于替换提示词中的变量。替换值可为字符串,也可为图像或文件等其他Response输入类型。
string
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
version: optional string or null
提示词模板的可选版本。
prompt_cache_diagnostics: optional CacheMiss { cache_missed_tokens, reason, type, comparison_reusable_tokens } or CacheHit { type } or ComparisonResponseNotFound { type } or Unavailable { type }
为此响应请求的提示词缓存诊断信息。
CacheMiss object { cache_missed_tokens, reason, type, comparison_reusable_tokens }
cache_missed_tokens: integer
首次检测到差异之后,受影响的输入词元数量估计值。
reason: "model_changed" or "prompt_cache_key_changed" or "tools_changed" or 6 more
未复用提示词缓存的原因。
"model_changed"
"prompt_cache_key_changed"
"tools_changed"
"text_format_changed"
"reasoning_effort_changed"
"verbosity_changed"
"context_compacted"
"input_changed"
"service_tier_changed"
type: "cache_miss" (default: "cache_miss")
"cache_miss"
comparison_reusable_tokens: optional integer
在所比较的响应中,可复用前缀的原始词元数。
CacheHit object { type }
type: "cache_hit" (default: "cache_hit")
"cache_hit"
ComparisonResponseNotFound object { type }
type: "comparison_response_not_found" (default: "comparison_response_not_found")
"comparison_response_not_found"
Unavailable object { type }
type: "unavailable" (default: "unavailable")
"unavailable"
prompt_cache_key: optional string or null
供OpenAI缓存相似请求的响应,以优化缓存命中率,替代user字段,详见提示词缓存。
prompt_cache_options: optional object { mode, ttl, comparison_response_id }
应用于该响应的提示词缓存选项。支持 gpt-5.6 及更新模型。
mode: "implicit" or "explicit"
是否启用了隐式提示词缓存断点。
"implicit"
"explicit"
ttl: "30m" or "12h"
应用于每个缓存断点的最短保留时间。
"30m"
"12h"
comparison_response_id: optional string or null
用于提示词缓存诊断比较的响应 ID。
prompt_cache_retention: optional "in_memory" or "24h" or null
已弃用,改用 prompt_cache_options.ttl。
提示词缓存保留策略。设为24h启用扩展缓存,使缓存前缀保持活跃更久,最长24小时,详见缓存保留。此字段表达最长保留策略,prompt_cache_options.ttl表达最短缓存寿命;两者独立、互不影响。gpt-5.5、gpt-5.5-pro及后续模型仅支持24h。
对于同时支持 in_memory 和 24h 的较早模型,默认值取决于组织的数据保留策略:
未启用ZDR的组织默认使用24h;启用ZDR且未指定prompt_cache_retention的组织默认使用in_memory。
"in_memory"
"24h"
reasoning: optional object { context, effort, generate_summary, 2 more } or null
推理模型的配置选项。
context: optional "auto" or "current_turn" or "all_turns" or null
控制后续轮次向模型呈现哪些推理条目。省略或设为auto时由模型决定上下文模式。gpt-5.6系列默认all_turns,更早模型默认current_turn。
在响应中返回时,表示本次响应实际使用的推理上下文模式。
"auto"
"current_turn"
"all_turns"
effort: optional "none" or "minimal" or "low" or 4 more or null (default: "medium")
限制推理模型的推理努力程度。目前支持none、minimal、low、medium、high、xhigh和max。降低努力程度可能加快响应并减少推理词元。并非所有模型支持每个值,具体见推理指南。
"none"
"minimal"
"low"
"medium"
"high"
"xhigh"
"max"
generate_summary: optional "auto" or "concise" or "detailed" or null
已弃用:请改用 summary。
模型推理的摘要,有助于调试和理解推理过程。可选auto、concise或detailed。
"auto"
"concise"
"detailed"
mode: optional string or "standard" or "pro"
控制请求的推理执行模式。
当此字段出现在返回的响应中时,表示实际使用的执行模式。
string
"standard" or "pro"
控制请求的推理执行模式。
当此字段出现在返回的响应中时,表示实际使用的执行模式。
"standard"
"pro"
summary: optional "auto" or "concise" or "detailed" or null
模型推理的摘要,有助于调试和理解推理过程。可选auto、concise或detailed。
computer-use-preview 模型及 gpt-5 之后的推理模型均支持 concise。
"auto"
"concise"
"detailed"
safety_identifier: optional string or null
稳定的用户标识,帮助检测应用中可能违反OpenAI使用政策的用户。应使用唯一标识各用户、最长128字符的字符串。建议对用户名或电子邮箱进行哈希,避免发送个人身份信息,详见安全标识。
maxLength: 128
service_tier: optional BetaServiceTier or null (default: "auto")
指定处理请求所采用的服务类型。
auto使用项目设置中的服务层级,未另行配置时为default。default使用所选模型的标准价格及性能;flex使用Flex处理。在Responses或Chat Completions请求中设置service_tier=fast或service_tier=priority可启用快速模式,不论传入哪一个,原文此处写明响应显示priority。ultrafast使用受访问控制的Ultrafast层级,当前此原文列为可供gpt-5.6-sol使用,响应显示ultrafast。未设置时默认auto。
设置 service_tier 后,响应体中的同名字段反映实际采用的处理模式,可能与请求参数的值不同。
"auto"
"default"
"flex"
"scale"
"priority"
"fast"
"ultrafast"
status: optional BetaResponseStatus
响应生成状态,可选completed、failed、in_progress、cancelled、queued或incomplete。
"completed"
"failed"
"in_progress"
"cancelled"
"queued"
"incomplete"
text: optional BetaResponseTextConfig
模型文本响应的配置选项,可为纯文本或结构化JSON数据,详见下列指南。
format: optional BetaResponseFormatTextConfig
指定模型必须输出的格式的对象。
配置{ "type": "json_schema" }可启用结构化输出,确保模型匹配提供的JSON Schema,详见结构化输出指南。
默认格式为 { "type": "text" },没有额外选项。
不建议用于 gpt-4o 及后续模型:
设置{ "type": "json_object" }可启用旧版JSON模式,确保模型生成合法JSON。支持json_schema的模型优先使用后者。
Text object { type }
默认响应格式,用于生成文本响应。
type: "text"
定义的响应格式类型,固定为 text。
"text"
BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }
JSON Schema响应格式,用于生成结构化JSON,详见结构化输出。
JSONObject object { type }
JSON对象响应格式,是生成JSON响应的旧方式。支持json_schema的模型建议使用后者。注意,若system或user消息没有明确要求生成JSON,模型不会自行生成JSON。
type: "json_object"
定义的响应格式类型,固定为 json_object。
"json_object"
verbosity: optional "low" or "medium" or "high" or null (default: "medium")
约束模型响应的详细程度。较低值生成更简洁的响应,较高值生成更详细的响应。目前支持low、medium和high,默认为medium。
"low"
"medium"
"high"
tool_usage: optional object { image_gen, web_search }
托管工具报告的用量,独立于基础模型的 usage。无法取得工具用量时可省略。若返回该字段,没有用量记录的工具类别计数为零。
image_gen 合计所有图像生成调用中可取得的词元计数。可能跳过用量记录不完整的调用。输出词元明细和缓存输入计数可省略,省略缓存计数表示缓存用量未知。
web_search.num_requests 统计可计费的搜索次数。打折搜索与打开网页等操作不计入。最终费用请以账单记录为准。
image_gen: object { input_tokens, input_tokens_details, output_tokens, 4 more }
图像生成工具调用的汇总用量统计。
input_tokens: integer
输入提示词中的图像与文本词元数量。
input_tokens_details: object { image_tokens, text_tokens }
图像生成的输入词元明细。
image_tokens: integer
输入提示词中的图像词元数量。
text_tokens: integer
输入提示词中的文本词元数量。
output_tokens: integer
模型生成的输出词元数量。
total_tokens: integer
图像生成使用的图像和文本词元总数。
cached_tokens: optional integer
cached_tokens_details: optional object { cached_image_tokens, cached_text_tokens }
cached_image_tokens: integer
cached_text_tokens: integer
output_tokens_details: optional object { image_tokens, text_tokens }
图像生成的输出词元明细。
image_tokens: integer
模型生成的图像输出词元数量。
text_tokens: integer
模型生成的文本输出词元数量。
web_search: object { num_requests }
网页搜索工具调用的汇总计费用量统计。
num_requests: integer
发起的计费网页搜索请求次数。
top_logprobs: optional integer or null
0到20之间的整数,指定每个词元位置返回多少个最可能词元及其对数概率;实际返回数量有时会少于请求值。
minimum: 0, maximum: 20
truncation: optional "auto" or "disabled" or null (default: "disabled")
模型响应的截断策略。
auto:输入超出模型的上下文窗口时,从对话开头移除条目以适配窗口。对部分模型,API 会先从输入上限扣除模型允许的最大输出量,再统计词元。因此,即使设置较低的max_output_tokens,也可能更早开始截断。disabled(默认值):输入超出模型上下文窗口时,请求会失败并返回 400 错误。
"auto"
"disabled"
usage: optional BetaResponseUsage or null
词元用量详情,包括输入词元、输出词元、输出词元分类和词元总数。
input_tokens: integer
输入词元数量。
input_tokens_details: object { cache_write_tokens, cached_tokens, cache_write_tokens_details }
输入词元的详细分类统计。
cache_write_tokens: integer
已写入缓存的输入词元数量。
cached_tokens: integer
从缓存读取的词元数量,详见提示词缓存。
cache_write_tokens_details: optional object { ttl_12h_tokens, ttl_30m_tokens }
ttl_12h_tokens: integer
以保留 12 小时的方式写入的输入词元数量。
ttl_30m_tokens: integer
以保留 30 分钟的方式写入的输入词元数量。
output_tokens: integer
输出词元数量。
output_tokens_details: object { reasoning_tokens }
输出词元的详细分类统计。
reasoning_tokens: integer
推理词元数量。
total_tokens: integer
使用的总词元数。
user: optional string or null
此字段正被safety_identifier和prompt_cache_key取代,维持缓存优化应改用prompt_cache_key。它是终端用户的稳定标识,通过更好地归类相似请求提高命中率,也帮助OpenAI检测和防止滥用,详见安全标识。
sequence_number: integer
事件序列号。
type: "response.in_progress"
类型,固定为response.in_progress。
"response.in_progress"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.in_progress",
"response": {
"id": "resp_67ccfcdd16748190a91872c75d38539e09e4d4aac714747c",
"object": "response",
"access_programs": null,
"created_at": 1741487325,
"status": "in_progress",
"completed_at": null,
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-6.2-astra",
"output": [],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null
},
"store": true,
"temperature": 1,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [],
"top_p": 1,
"truncation": "disabled",
"usage": null,
"user": null,
"metadata": {}
},
"sequence_number": 1
}
response.completed
模型响应完成时发出。
结构定义
结构名称: BetaResponseCompletedEvent
response: BetaResponse
已完成响应的属性。
id: string
此响应的唯一标识符。
access_programs: object { cyber } or null
created_at: number
此响应创建时的 Unix 时间戳,单位为秒。
format: unixtime
error: BetaResponseError or null
模型未能生成响应时返回的错误对象。
code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 18 more
此响应的错误代码。
"server_error"
"rate_limit_exceeded"
"invalid_prompt"
"data_residency_mismatch"
"bio_policy"
"misalignment_policy_violation"
"vector_store_timeout"
"invalid_image"
"invalid_image_format"
"invalid_base64_image"
"invalid_image_url"
"image_too_large"
"image_too_small"
"image_parse_error"
"image_content_policy_violation"
"invalid_image_mode"
"image_file_too_large"
"unsupported_image_media_type"
"empty_image_file"
"failed_to_download_image"
"image_file_not_found"
message: string
便于人阅读的错误说明。
misalignment: optional object { detailed_explanation, error_type, review_target, steer }
detailed_explanation: optional string
对此次阻止操作的公开说明。
error_type: optional string or "potentially_unintended_data_transfer" or "potentially_unintended_data_access" or "potentially_unintended_destructive_activity" or "other"
可选的分类;客户端必须能够接受其他值。
string
SafetyAlertErrorType = "potentially_unintended_data_transfer" or "potentially_unintended_data_access" or "potentially_unintended_destructive_activity" or "other"
可选的分类;客户端必须能够接受其他值。
"potentially_unintended_data_transfer"
"potentially_unintended_data_access"
"potentially_unintended_destructive_activity"
"other"
review_target: optional string or null
用于明确继续此次审查的不透明目标;不可用时为 null。
pattern: ^[A-Za-z0-9._~:-]+$, minLength: 1, maxLength: 96
steer: optional object { message }
可选的公开继续指令。
message: string
公开的继续指令。
param: optional string or null
与错误相关的请求参数;未记录时为 null。
type: optional string or null
原始错误类型;未记录时为 null。
incomplete_details: object { reason } or null
说明响应为何未完成的详细信息。
reason: optional "max_output_tokens" or "max_messages" or "content_filter" or "steered"
响应未完成的原因。steered表示响应在收到WebSocket response.steer事件后于安全输出边界停止;服务器随后可自动使用排队输入创建后继响应。
"max_output_tokens"
"max_messages"
"content_filter"
"steered"
instructions: string or array of BetaEasyInputMessage or Message { content, role, agent, 2 more } or BetaResponseOutputMessage or 33 more or null
插入模型上下文的系统消息或开发者消息。
与previous_response_id一起使用时,前一响应的instructions不会传入下一响应,便于在新响应中替换system或developer消息。
string
提供给模型的文本输入,等同于developer角色的文本输入。
InputItemList = array of BetaEasyInputMessage or Message { content, role, agent, 2 more } or BetaResponseOutputMessage or 33 more
提供给模型的一个或多个输入条目组成的列表,其中可以包含不同类型的内容。
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
生成该条目的智能体的规范名称。
metadata: map[string] or null
可附加到对象的一组16个键值对,用于结构化保存附加信息,并通过API或控制台查询对象。
键为最长64个字符的字符串,值为最长512个字符的字符串。
model: "gpt-6-astra" or "gpt-6.2-astra" or "gpt-6.1-sol" or 112 more or string
生成响应的模型ID,例如gpt-6.2-astra。OpenAI提供能力、性能和价格各异的模型,可在模型指南浏览比较。
"gpt-6-astra" or "gpt-6.2-astra" or "gpt-6.1-sol" or 112 more
生成响应的模型ID,例如gpt-6.2-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
object: "response"
此资源的对象类型,始终为 response。
"response"
output: array of BetaResponseOutputItem
模型生成的内容条目数组。
output数组的长度和顺序取决于模型响应。不要假定首个条目一定是包含生成内容的assistant消息;可考虑使用SDK支持的output_text属性。
BetaResponseOutputMessage object { id, content, role, 4 more }
模型输出的消息。
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
从文件中检索出的文本。
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 { id, output, status, 7 more }
id: string
函数调用工具输出的唯一 ID。
output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
你的代码产生的函数调用输出,可为字符串或输出内容列表。
StringOutput = string
函数调用输出的字符串。
OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
函数调用的文本、图像或文件输出。
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
status: "in_progress" or "completed" or "incomplete"
条目状态,可选 in_progress、completed 或 incomplete,通过 API 返回条目时填充。
"in_progress"
"completed"
"incomplete"
type: "function_call_output"
类型,固定为 function_call_output。
"function_call_output"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
call_id: optional string
模型生成的函数工具调用的唯一 ID。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
调用方类型,固定为 direct。
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
minLength: 1, maxLength: 64
type: "program" (default: "program")
调用方类型,固定为 program。
"program"
created_by: optional string
创建该条目的执行主体的标识。
name: optional string
产生输出的工具名称。
namespace: optional string
产生输出的工具所属命名空间。
AgentMessage object { id, author, content, 3 more }
id: string
此智能体消息的唯一 ID。
author: string
发送方智能体的标识。
content: array of BetaResponseInputText or BetaResponseOutputText or Text { text, type } or 7 more
智能体之间发送的加密内容。
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
BetaResponseOutputText object { annotations, logprobs, text, type }
模型输出的文本。
Text object { text, type }
文本内容。
text: string
type: "text" (default: "text")
"text"
SummaryText object { text, type }
模型生成的摘要文本。
text: string
模型到目前为止生成的推理输出摘要。
type: "summary_text" (default: "summary_text")
类型,固定为 summary_text。
"summary_text"
ReasoningText object { text, type }
模型生成的推理文本。
text: string
模型生成的推理文本。
type: "reasoning_text" (default: "reasoning_text")
类型,固定为 reasoning_text。
"reasoning_text"
BetaResponseOutputRefusal object { refusal, type }
模型的拒绝响应。
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
ComputerScreenshot object { detail, file_id, image_url, 2 more }
计算机屏幕截图。
detail: BetaImageDetail
发送给模型的截图图像的细节级别,可选 high、low、auto 或 original,默认为 auto。
file_id: string or null
包含截图的已上传文件的标识。
image_url: string or null
截图图像的 URL。
format: uri
type: "computer_screenshot" (default: "computer_screenshot")
指定事件类型。对于计算机屏幕截图,此属性固定为 computer_screenshot。
"computer_screenshot"
prompt_cache_breakpoint: optional object { mode, ttl }
标记可复用提示词前缀的精确结束位置。省略 ttl 时,断点继承请求中的 prompt_cache_options.ttl;该边界不会按词元块取整。
mode: "explicit" (default: "explicit")
断点模式,固定为 explicit。
"explicit"
ttl: optional "30m" or "12h"
此缓存断点的最短存续时间,默认为请求的 TTL。
"30m"
"12h"
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
EncryptedContent object { encrypted_content, type }
不透明的加密内容,由 Responses API 在受信任的模型执行环境中解密。
encrypted_content: string
不透明的加密内容。
type: "encrypted_content" (default: "encrypted_content")
输入条目的类型,固定为 encrypted_content。
"encrypted_content"
recipient: string
接收方智能体的标识。
type: "agent_message" (default: "agent_message")
条目类型,固定为 agent_message。
"agent_message"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
MultiAgentCall object { id, action, arguments, 3 more }
id: string
该多智能体调用条目的唯一 ID。
action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more
要执行的多智能体操作。
"spawn_agent"
"interrupt_agent"
"list_agents"
"send_message"
"followup_task"
"wait_agent"
arguments: string
为该操作生成的参数,格式为 JSON 字符串。
call_id: string
关联调用与其输出的唯一 ID。
type: "multi_agent_call" (default: "multi_agent_call")
多智能体调用的类型,固定为 multi_agent_call。
"multi_agent_call"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
MultiAgentCallOutput object { id, action, call_id, 3 more }
id: string
此多智能体调用输出条目的唯一 ID。
action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more
生成此结果的多智能体操作。
"spawn_agent"
"interrupt_agent"
"list_agents"
"send_message"
"followup_task"
"wait_agent"
call_id: string
此多智能体调用的唯一 ID。
output: array of BetaResponseOutputText
多智能体操作返回的文本。
annotations: array of FileCitation { file_id, filename, index, type } or URLCitation { end_index, start_index, title, 2 more } or ContainerFileCitation { container_id, end_index, file_id, 3 more } or FilePath { file_id, index, type }
文本输出的注解。
logprobs: array of object { token, bytes, logprob, top_logprobs }
text: string
模型输出的文本内容。
type: "output_text" (default: "output_text")
输出文本类型,固定为 output_text。
type: "multi_agent_call_output" (default: "multi_agent_call_output")
多智能体结果的类型,固定为 multi_agent_call_output。
"multi_agent_call_output"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
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
生成该条目的智能体的规范名称。
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
单击操作。
actions: optional BetaComputerActionList
computer_use的扁平化批量操作。每个操作包含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
供计算机使用工具使用的屏幕截图图像。
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"
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
生成该条目的智能体的规范名称。
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 }
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: "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
生成该条目的智能体的规范名称。
Compaction object { id, encrypted_content, type, 2 more }
v1/responses/compact API生成的压缩条目。
id: string
压缩条目的唯一 ID。
encrypted_content: string
压缩生成的加密内容。
type: "compaction" (default: "compaction")
类型,固定为 compaction。
"compaction"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
created_by: optional string
创建该条目的执行主体的标识。
ImageGenerationCall object { id, result, status, 10 more }
模型发起的图像生成请求。
id: string
图像生成调用的唯一 ID。
result: string or null
Base64 编码的生成图像。
status: "in_progress" or "completed" or "generating" or "failed"
图像生成调用的状态。
"in_progress"
"completed"
"generating"
"failed"
type: "image_generation_call"
类型,固定为 image_generation_call。
"image_generation_call"
action: optional "generate" or "edit" or "auto" or null
用于图像生成的操作。
"generate"
"edit"
"auto"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
background: optional "transparent" or "opaque" or "auto" or null
生成图像使用的背景设置。
"transparent"
"opaque"
"auto"
error: optional object { code, message, param, 2 more }
审核失败的详情,如可用。
code: string or null
错误代码。
message: string
错误描述。
param: string or null
关联的请求参数。
type: string
错误类型。
moderation_details: optional object { categories, moderation_stage }
moderation_blocked 错误的公开详情,如可用。
categories: array of string
公开的审核类别,未来可能增加新的类别值。
moderation_stage: "input" or "output" or "unknown"
审核阻止图像生成调用的阶段。
"input"
"output"
"unknown"
output_format: optional "png" or "webp" or "jpeg" or 2 more or null
生成图像使用的输出格式。
"png"
"webp"
"jpeg"
"gif"
"svg"
quality: optional "low" or "medium" or "high" or 3 more or null
图像生成工具调用生成的图像质量,可选 low、medium、high、xhigh、max 或 auto。
"low"
"medium"
"high"
"xhigh"
"max"
"auto"
revised_prompt: optional string or null
模型改写提示词后实际使用的提示词。
size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or null
图像尺寸,采用 WIDTHxHEIGHT 字符串形式,例如 1536x864。
string
"1024x1024" or "1024x1536" or "1536x1024"
图像尺寸,采用 WIDTHxHEIGHT 字符串形式,例如 1536x864。
"1024x1024"
"1024x1536"
"1536x1024"
svg_usage: optional object { input_tokens, model, output_tokens, 2 more }
input_tokens: integer
model: string
output_tokens: integer
reasoning_tokens: integer
total_tokens: integer
CodeInterpreterCall object { id, code, container_id, 4 more }
运行代码的工具调用。
id: string
代码解释器工具调用的唯一 ID。
code: string or null
要运行的代码,不可用时为 null。
container_id: string
运行代码使用的容器 ID。
outputs: array of Logs { logs, type } or Image { type, url } or null
代码解释器产生的日志、图像等输出;没有可用输出时可为null。
Logs object { logs, type }
代码解释器的日志输出。
logs: string
代码解释器的日志输出。
type: "logs" (default: "logs")
类型,固定为 logs。
"logs"
Image object { type, url }
代码解释器的图像输出。
type: "image" (default: "image")
类型,固定为 image。
"image"
url: string
代码解释器输出图像的 URL。
format: uri
status: "in_progress" or "completed" or "incomplete" or 2 more
代码解释器工具调用的状态,有效值为 in_progress、completed、incomplete、interpreting 和 failed。
"in_progress"
"completed"
"incomplete"
"interpreting"
"failed"
type: "code_interpreter_call" (default: "code_interpreter_call")
类型,固定为 code_interpreter_call。
"code_interpreter_call"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
LocalShellCall object { id, action, call_id, 3 more }
在本地 shell 上运行命令的工具调用。
id: string
本地 shell 调用的唯一 ID。
action: object { command, env, type, 3 more }
在服务器上执行 shell 命令。
command: array of string
要运行的命令。
env: map[string]
要为命令设置的环境变量。
type: "exec" (default: "exec")
类型,固定为 exec。
"exec"
timeout_ms: optional integer or null
可选的命令超时时长,单位为毫秒。
user: optional string or null
可选的运行命令的用户。
working_directory: optional string or null
可选的运行命令的工作目录。
call_id: string
模型生成的本地 shell 工具调用的唯一 ID。
status: "in_progress" or "completed" or "incomplete"
本地 shell 调用的状态。
"in_progress"
"completed"
"incomplete"
type: "local_shell_call"
类型,固定为 local_shell_call。
"local_shell_call"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
LocalShellCallOutput object { id, output, type, 2 more }
本地 shell 工具调用的输出。
id: string
模型生成的本地 shell 工具调用的唯一 ID。
output: string
本地 shell 工具调用输出的 JSON 字符串。
type: "local_shell_call_output"
类型,固定为 local_shell_call_output。
"local_shell_call_output"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
status: optional "in_progress" or "completed" or "incomplete" or null
条目状态,可选 in_progress、completed 或 incomplete。
"in_progress"
"completed"
"incomplete"
ShellCall object { id, action, call_id, 6 more }
在托管环境中执行一个或多个 shell 命令的工具调用。
id: string
shell 工具调用的唯一 ID,通过 API 返回此条目时填充。
action: object { commands, max_output_length, timeout_ms }
描述如何运行工具调用的 shell 命令及限制。
commands: array of string
max_output_length: integer or null
可选的每个命令返回的最大字符数。
timeout_ms: integer or null
可选的命令超时时长,单位为毫秒。
call_id: string
模型生成的 shell 工具调用的唯一 ID。
environment: BetaResponseLocalEnvironment or BetaResponseContainerReference or null
表示使用本地环境执行 shell 操作。
BetaResponseLocalEnvironment object { type }
表示使用本地环境执行 shell 操作。
type: "local" (default: "local")
环境类型,固定为 local。
"local"
BetaResponseContainerReference object { container_id, type }
表示通过 /v1/containers 创建的容器。
container_id: string
type: "container_reference" (default: "container_reference")
环境类型,固定为 container_reference。
"container_reference"
status: "in_progress" or "completed" or "incomplete"
shell 调用状态,可选 in_progress、completed 或 incomplete。
"in_progress"
"completed"
"incomplete"
type: "shell_call" (default: "shell_call")
类型,固定为 shell_call。
"shell_call"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建此工具调用的实体的 ID。
ShellCallOutput object { id, call_id, max_output_length, 6 more }
shell 工具调用发出的输出。
id: string
shell 调用输出的唯一 ID,通过 API 返回此条目时填充。
call_id: string
模型生成的 shell 工具调用的唯一 ID。
max_output_length: integer or null
shell 命令输出的最大长度,由模型生成,应与原始输出一并回传。
output: array of object { outcome, stderr, stdout, created_by }
shell 调用输出内容的数组。
outcome: Timeout { type } or Exit { exit_code, type }
表示 shell 调用输出块的退出结果(包含退出码)或超时结果。
Timeout object { type }
表示 shell 调用超过其配置的时间限制。
type: "timeout" (default: "timeout")
结果类型,固定为 timeout。
"timeout"
Exit object { exit_code, type }
表示 shell 命令已结束,并返回退出码。
exit_code: integer
shell 进程的退出码。
type: "exit" (default: "exit")
结果类型,固定为 exit。
"exit"
stderr: string
捕获的标准错误输出。
stdout: string
捕获的标准输出。
created_by: optional string
创建该条目的执行主体的标识。
status: "in_progress" or "completed" or "incomplete"
shell 调用输出的状态,可选 in_progress、completed 或 incomplete。
"in_progress"
"completed"
"incomplete"
type: "shell_call_output" (default: "shell_call_output")
shell 调用输出的类型,固定为 shell_call_output。
"shell_call_output"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建该条目的执行主体的标识。
ApplyPatchCall object { id, call_id, operation, 5 more }
通过创建、删除或更新文件来应用文件差异的工具调用。
id: string
apply_patch 工具调用的唯一 ID,通过 API 返回此条目时填充。
call_id: string
模型生成的 apply_patch 工具调用的唯一 ID。
operation: CreateFile { diff, path, type } or DeleteFile { path, type } or UpdateFile { diff, path, type }
通过 apply_patch 应用的 create_file、delete_file 或 update_file 操作之一。
CreateFile object { diff, path, type }
描述如何通过 apply_patch 工具创建文件的指令。
diff: string
要应用的差异。
path: string
要创建的文件路径。
type: "create_file" (default: "create_file")
使用提供的差异创建新文件。
"create_file"
DeleteFile object { path, type }
描述如何通过 apply_patch 工具删除文件的指令。
path: string
要删除的文件路径。
type: "delete_file" (default: "delete_file")
删除指定文件。
"delete_file"
UpdateFile object { diff, path, type }
描述如何通过 apply_patch 工具更新文件的指令。
diff: string
要应用的差异。
path: string
要更新的文件路径。
type: "update_file" (default: "update_file")
使用提供的差异更新已有文件。
"update_file"
status: "in_progress" or "completed"
apply_patch 工具调用状态,可选 in_progress 或 completed。
"in_progress"
"completed"
type: "apply_patch_call" (default: "apply_patch_call")
类型,固定为 apply_patch_call。
"apply_patch_call"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建此工具调用的实体的 ID。
ApplyPatchCallOutput object { id, call_id, status, 5 more }
apply_patch 工具调用发出的输出。
id: string
apply_patch 工具调用输出的唯一 ID,通过 API 返回此条目时填充。
call_id: string
模型生成的 apply_patch 工具调用的唯一 ID。
status: "completed" or "failed"
apply_patch 工具调用输出的状态,可选 completed 或 failed。
"completed"
"failed"
type: "apply_patch_call_output" (default: "apply_patch_call_output")
类型,固定为 apply_patch_call_output。
"apply_patch_call_output"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建此工具调用输出的实体的 ID。
output: optional string or null
apply_patch 工具返回的可选文本输出。
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
工具调用的错误,如有。
output: optional string or null
工具调用的输出。
status: optional "in_progress" or "completed" or "incomplete" or 2 more
工具调用状态,可选 in_progress、completed、incomplete、calling 或 failed。
"in_progress"
"completed"
"incomplete"
"calling"
"failed"
McpListTools object { id, server_label, tools, 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
决定的可选理由。
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 { id, call_id, output, 5 more }
id: string
自定义工具调用输出条目的唯一 ID。
call_id: string
调用 ID,用于将此自定义工具调用输出映射到自定义工具调用。
output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
你的代码生成的自定义工具输出,可为字符串或输出内容列表。
StringOutput = string
自定义工具调用输出的字符串。
OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
自定义工具调用的文本、图像或文件输出。
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
status: "in_progress" or "completed" or "incomplete"
条目状态,可选 in_progress、completed 或 incomplete,通过 API 返回条目时填充。
"in_progress"
"completed"
"incomplete"
type: "custom_tool_call_output"
类型,固定为 custom_tool_call_output。
"custom_tool_call_output"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
调用方类型,固定为 direct。
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
minLength: 1, maxLength: 64
type: "program" (default: "program")
调用方类型,固定为 program。
"program"
created_by: optional string
创建该条目的执行主体的标识。
parallel_tool_calls: boolean (default: true)
是否允许模型并行执行工具调用。
temperature: number or null (default: 1)
采样温度,范围0到2。0.8等较高值使输出更随机,0.2等较低值使输出更集中、更确定。通常建议只修改此参数或top_p中的一个。
minimum: 0, maximum: 2
tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more
模型生成响应时如何选择工具,参见tools参数了解可调用工具的定义方式。
BetaToolChoiceOptions = "none" or "auto" or "required"
控制模型调用哪个工具,或是否调用工具。
none 表示模型直接生成消息,不调用工具。
auto 表示模型可选择生成消息,或调用一个或多个工具。
required 表示模型必须调用一个或多个工具。
"none"
"auto"
"required"
BetaToolChoiceAllowed object { mode, tools, type }
将模型可用的工具限制为预先定义的集合。
mode: "auto" or "required"
将模型可用的工具限制为预先定义的集合。
auto 允许模型从可用工具中选择,或生成消息。
required 要求模型至少调用一个可用工具。
"auto"
"required"
tools: array of map[unknown]
应允许模型调用的工具定义列表。
对于 Responses API,工具定义列表可以如下所示:
[
{ "type": "function", "name": "get_weather" },
{ "type": "mcp", "server_label": "deepwiki" },
{ "type": "image_generation" }
]
type: "allowed_tools"
允许的工具配置类型,固定为 allowed_tools。
"allowed_tools"
BetaToolChoiceTypes object { type }
指定模型应使用内置工具生成响应,详见内置工具。
type: "file_search" or "web_search_preview" or "computer" or 5 more
模型应使用的托管工具类型,详见内置工具。
允许的值为:
file_searchweb_search_previewcomputercomputer_use_previewcomputer_usecode_interpreterimage_generation
"file_search"
"web_search_preview"
"computer"
"computer_use_preview"
"computer_use"
"web_search_preview_2025_03_11"
"image_generation"
"code_interpreter"
BetaToolChoiceFunction object { name, type }
使用此选项强制模型调用指定函数。
name: string
要调用的函数名称。
type: "function"
对于函数调用,类型固定为 function。
"function"
BetaToolChoiceMcp object { server_label, type, name }
使用此选项强制模型调用远程 MCP 服务器上的指定工具。
server_label: string
要使用的 MCP 服务器标签。
type: "mcp"
对于 MCP 工具,类型固定为 mcp。
"mcp"
name: optional string or null
要在服务器上调用的工具名称。
BetaToolChoiceCustom object { name, type }
使用此选项强制模型调用特定的自定义工具。
name: string
要调用的自定义工具名称。
type: "custom"
对于自定义工具调用,类型固定为 custom。
"custom"
BetaSpecificProgrammaticToolCallingParam object { type }
type: "programmatic_tool_calling" (default: "programmatic_tool_calling")
要调用的工具,固定为 programmatic_tool_calling。
"programmatic_tool_calling"
BetaToolChoiceApplyPatch object { type }
执行工具调用时,强制模型调用 apply_patch 工具。
type: "apply_patch" (default: "apply_patch")
要调用的工具,固定为 apply_patch。
"apply_patch"
BetaToolChoiceShell object { type }
需要调用工具时,强制模型调用 shell 工具。
type: "shell" (default: "shell")
要调用的工具,固定为 shell。
"shell"
tools: array of Function { name, parameters, strict, 6 more } or FileSearch { type, vector_store_ids, filters, 2 more } or Computer { type } or 13 more
模型生成响应时可以调用的工具数组。可以通过设置 tool_choice 参数指定使用哪个工具。
支持以下几类工具:
内置工具:OpenAI提供的扩展能力,如网页搜索和文件搜索,详见内置工具。MCP工具:通过自定义MCP服务器或Google Drive、SharePoint等预定义连接器集成第三方系统,详见MCP工具。函数调用(自定义工具):开发者定义的函数,让模型以强类型参数和输出调用你的代码,详见函数调用;也可使用自定义工具调用自己的代码。
Function object { name, parameters, strict, 6 more }
定义模型可以选择调用的自有代码函数。参阅函数调用。
name: string
要调用的函数名称。
parameters: map[unknown] or null
描述函数参数的 JSON Schema 对象。
strict: boolean or null
是否对此函数工具强制执行严格参数校验。
type: "function" (default: "function")
函数工具类型,固定为 function。
"function"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
"direct"
"programmatic"
async: optional boolean
defer_loading: optional boolean
此函数是否延迟加载并通过工具搜索加载。
description: optional string or null
函数描述,模型据此判断是否调用该函数。
output_schema: optional map[unknown] or null
描述此函数字符串输出中编码的 JSON 值的 JSON Schema 对象。
FileSearch object { type, vector_store_ids, filters, 2 more }
搜索已上传文件中相关内容的工具。参阅文件搜索工具。
type: "file_search" (default: "file_search")
文件搜索工具类型,固定为 file_search。
"file_search"
vector_store_ids: array of string
要搜索的向量存储 ID 列表。
filters: optional ComparisonFilter { 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"
top_p: number or null (default: 1)
核采样是温度采样的替代方式:模型仅考虑累计概率达到top_p的词元。例如0.1表示只考虑累计概率质量前10%的词元。
通常建议只调整此项或 temperature 中的一项,不同时调整两者。
minimum: 0, maximum: 1
background: optional boolean or null (default: false)
是否在后台运行模型响应,详见后台模式。
completed_at: optional number or null
Response完成时的Unix时间戳,单位为秒,仅在状态为completed时存在。
format: unixtime
conversation: optional object { id } or null
此响应所属的对话。该响应的输入条目和输出条目已自动添加到此对话。
id: string
与此响应关联的对话的唯一 ID。
image: optional object { context_compression }
context_compression: "enabled" or "disabled"
实际采用的图像上下文优化策略。
"enabled"
"disabled"
input_transformations: optional array of object { id, action, reason, type }
未传给模型的推理输入,按输入顺序排列。
id: string
原始推理条目的 ID。
action: "removed" (default: "removed")
"removed"
reason: "organization_mismatch" or "end_user_mismatch" or "model_mismatch" or 2 more
"organization_mismatch"
"end_user_mismatch"
"model_mismatch"
"prefix_mismatch"
"turn_boundary"
type: "reasoning" (default: "reasoning")
"reasoning"
max_output_tokens: optional integer or null
响应可生成词元数的上限,包括可见输出词元及推理词元。
max_tool_calls: optional integer or null
一个响应中可处理的内置工具调用总次数上限。此上限适用于所有内置工具调用的合计次数,而非每个工具分别计算。达到上限后,模型进一步调用工具的尝试会被忽略。
moderation: optional object { input, output } or null
如果请求了经审核的补全,则包含响应输入和输出的审核结果。
input: ModerationResult { categories, category_applied_input_types, category_scores, 3 more } or Error { code, message, type }
对响应输入的审核。
ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }
针对响应输入或输出生成的审核结果。
categories: map[boolean]
审核类别到布尔值的映射。输入被某类别标记时,该类别值为 true。
category_applied_input_types: map[array of "text" or "image"]
各类别评分所涵盖的输入模态。
"text"
"image"
category_scores: map[number]
审核类别到分数的映射。
flagged: boolean
表示内容是否被任一类别标记的布尔值。
model: string
生成此结果的审核模型。
type: "moderation_result" (default: "moderation_result")
对象类型,成功审核结果中固定为 moderation_result。
"moderation_result"
Error object { code, message, type }
尝试审核响应输入或输出时产生的错误。
code: string
错误代码。
message: string
错误消息。
type: "error" (default: "error")
对象类型;审核失败时始终为 error。
"error"
output: ModerationResult { categories, category_applied_input_types, category_scores, 3 more } or Error { code, message, type }
对响应输出的审核。
ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }
针对响应输入或输出生成的审核结果。
categories: map[boolean]
审核类别到布尔值的映射。输入被某类别标记时,该类别值为 true。
category_applied_input_types: map[array of "text" or "image"]
各类别评分所涵盖的输入模态。
"text"
"image"
category_scores: map[number]
审核类别到分数的映射。
flagged: boolean
表示内容是否被任一类别标记的布尔值。
model: string
生成此结果的审核模型。
type: "moderation_result" (default: "moderation_result")
对象类型,成功审核结果中固定为 moderation_result。
"moderation_result"
Error object { code, message, type }
尝试审核响应输入或输出时产生的错误。
code: string
错误代码。
message: string
错误消息。
type: "error" (default: "error")
对象类型;审核失败时始终为 error。
"error"
output_text: optional string or null
仅SDK提供的便利属性,聚合output数组中所有output_text条目的文本(若存在),Python和JavaScript SDK支持此属性。
previous_response_id: optional string or null
前一次模型响应的唯一ID,用于多轮对话,详见对话状态。不能与conversation同时使用。
prompt: optional BetaResponsePrompt or null
提示词模板及其变量的引用,详见代码中的提示词版本。
id: string
要使用的提示词模板的唯一标识。
variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile] or null
可选的变量替换映射,用于替换提示词中的变量。替换值可为字符串,也可为图像或文件等其他Response输入类型。
string
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
version: optional string or null
提示词模板的可选版本。
prompt_cache_diagnostics: optional CacheMiss { cache_missed_tokens, reason, type, comparison_reusable_tokens } or CacheHit { type } or ComparisonResponseNotFound { type } or Unavailable { type }
为此响应请求的提示词缓存诊断信息。
CacheMiss object { cache_missed_tokens, reason, type, comparison_reusable_tokens }
cache_missed_tokens: integer
首次检测到差异之后,受影响的输入词元数量估计值。
reason: "model_changed" or "prompt_cache_key_changed" or "tools_changed" or 6 more
未复用提示词缓存的原因。
"model_changed"
"prompt_cache_key_changed"
"tools_changed"
"text_format_changed"
"reasoning_effort_changed"
"verbosity_changed"
"context_compacted"
"input_changed"
"service_tier_changed"
type: "cache_miss" (default: "cache_miss")
"cache_miss"
comparison_reusable_tokens: optional integer
在所比较的响应中,可复用前缀的原始词元数。
CacheHit object { type }
type: "cache_hit" (default: "cache_hit")
"cache_hit"
ComparisonResponseNotFound object { type }
type: "comparison_response_not_found" (default: "comparison_response_not_found")
"comparison_response_not_found"
Unavailable object { type }
type: "unavailable" (default: "unavailable")
"unavailable"
prompt_cache_key: optional string or null
供OpenAI缓存相似请求的响应,以优化缓存命中率,替代user字段,详见提示词缓存。
prompt_cache_options: optional object { mode, ttl, comparison_response_id }
应用于该响应的提示词缓存选项。支持 gpt-5.6 及更新模型。
mode: "implicit" or "explicit"
是否启用了隐式提示词缓存断点。
"implicit"
"explicit"
ttl: "30m" or "12h"
应用于每个缓存断点的最短保留时间。
"30m"
"12h"
comparison_response_id: optional string or null
用于提示词缓存诊断比较的响应 ID。
prompt_cache_retention: optional "in_memory" or "24h" or null
已弃用,改用 prompt_cache_options.ttl。
提示词缓存保留策略。设为24h启用扩展缓存,使缓存前缀保持活跃更久,最长24小时,详见缓存保留。此字段表达最长保留策略,prompt_cache_options.ttl表达最短缓存寿命;两者独立、互不影响。gpt-5.5、gpt-5.5-pro及后续模型仅支持24h。
对于同时支持 in_memory 和 24h 的较早模型,默认值取决于组织的数据保留策略:
未启用ZDR的组织默认使用24h;启用ZDR且未指定prompt_cache_retention的组织默认使用in_memory。
"in_memory"
"24h"
reasoning: optional object { context, effort, generate_summary, 2 more } or null
推理模型的配置选项。
context: optional "auto" or "current_turn" or "all_turns" or null
控制后续轮次向模型呈现哪些推理条目。省略或设为auto时由模型决定上下文模式。gpt-5.6系列默认all_turns,更早模型默认current_turn。
在响应中返回时,表示本次响应实际使用的推理上下文模式。
"auto"
"current_turn"
"all_turns"
effort: optional "none" or "minimal" or "low" or 4 more or null (default: "medium")
限制推理模型的推理努力程度。目前支持none、minimal、low、medium、high、xhigh和max。降低努力程度可能加快响应并减少推理词元。并非所有模型支持每个值,具体见推理指南。
"none"
"minimal"
"low"
"medium"
"high"
"xhigh"
"max"
generate_summary: optional "auto" or "concise" or "detailed" or null
已弃用:请改用 summary。
模型推理的摘要,有助于调试和理解推理过程。可选auto、concise或detailed。
"auto"
"concise"
"detailed"
mode: optional string or "standard" or "pro"
控制请求的推理执行模式。
当此字段出现在返回的响应中时,表示实际使用的执行模式。
string
"standard" or "pro"
控制请求的推理执行模式。
当此字段出现在返回的响应中时,表示实际使用的执行模式。
"standard"
"pro"
summary: optional "auto" or "concise" or "detailed" or null
模型推理的摘要,有助于调试和理解推理过程。可选auto、concise或detailed。
computer-use-preview 模型及 gpt-5 之后的推理模型均支持 concise。
"auto"
"concise"
"detailed"
safety_identifier: optional string or null
稳定的用户标识,帮助检测应用中可能违反OpenAI使用政策的用户。应使用唯一标识各用户、最长128字符的字符串。建议对用户名或电子邮箱进行哈希,避免发送个人身份信息,详见安全标识。
maxLength: 128
service_tier: optional BetaServiceTier or null (default: "auto")
指定处理请求所采用的服务类型。
auto使用项目设置中的服务层级,未另行配置时为default。default使用所选模型的标准价格及性能;flex使用Flex处理。在Responses或Chat Completions请求中设置service_tier=fast或service_tier=priority可启用快速模式,不论传入哪一个,原文此处写明响应显示priority。ultrafast使用受访问控制的Ultrafast层级,当前此原文列为可供gpt-5.6-sol使用,响应显示ultrafast。未设置时默认auto。
设置 service_tier 后,响应体中的同名字段反映实际采用的处理模式,可能与请求参数的值不同。
"auto"
"default"
"flex"
"scale"
"priority"
"fast"
"ultrafast"
status: optional BetaResponseStatus
响应生成状态,可选completed、failed、in_progress、cancelled、queued或incomplete。
"completed"
"failed"
"in_progress"
"cancelled"
"queued"
"incomplete"
text: optional BetaResponseTextConfig
模型文本响应的配置选项,可为纯文本或结构化JSON数据,详见下列指南。
format: optional BetaResponseFormatTextConfig
指定模型必须输出的格式的对象。
配置{ "type": "json_schema" }可启用结构化输出,确保模型匹配提供的JSON Schema,详见结构化输出指南。
默认格式为 { "type": "text" },没有额外选项。
不建议用于 gpt-4o 及后续模型:
设置{ "type": "json_object" }可启用旧版JSON模式,确保模型生成合法JSON。支持json_schema的模型优先使用后者。
Text object { type }
默认响应格式,用于生成文本响应。
type: "text"
定义的响应格式类型,固定为 text。
"text"
BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }
JSON Schema响应格式,用于生成结构化JSON,详见结构化输出。
JSONObject object { type }
JSON对象响应格式,是生成JSON响应的旧方式。支持json_schema的模型建议使用后者。注意,若system或user消息没有明确要求生成JSON,模型不会自行生成JSON。
type: "json_object"
定义的响应格式类型,固定为 json_object。
"json_object"
verbosity: optional "low" or "medium" or "high" or null (default: "medium")
约束模型响应的详细程度。较低值生成更简洁的响应,较高值生成更详细的响应。目前支持low、medium和high,默认为medium。
"low"
"medium"
"high"
tool_usage: optional object { image_gen, web_search }
托管工具报告的用量,独立于基础模型的 usage。无法取得工具用量时可省略。若返回该字段,没有用量记录的工具类别计数为零。
image_gen 合计所有图像生成调用中可取得的词元计数。可能跳过用量记录不完整的调用。输出词元明细和缓存输入计数可省略,省略缓存计数表示缓存用量未知。
web_search.num_requests 统计可计费的搜索次数。打折搜索与打开网页等操作不计入。最终费用请以账单记录为准。
image_gen: object { input_tokens, input_tokens_details, output_tokens, 4 more }
图像生成工具调用的汇总用量统计。
input_tokens: integer
输入提示词中的图像与文本词元数量。
input_tokens_details: object { image_tokens, text_tokens }
图像生成的输入词元明细。
image_tokens: integer
输入提示词中的图像词元数量。
text_tokens: integer
输入提示词中的文本词元数量。
output_tokens: integer
模型生成的输出词元数量。
total_tokens: integer
图像生成使用的图像和文本词元总数。
cached_tokens: optional integer
cached_tokens_details: optional object { cached_image_tokens, cached_text_tokens }
cached_image_tokens: integer
cached_text_tokens: integer
output_tokens_details: optional object { image_tokens, text_tokens }
图像生成的输出词元明细。
image_tokens: integer
模型生成的图像输出词元数量。
text_tokens: integer
模型生成的文本输出词元数量。
web_search: object { num_requests }
网页搜索工具调用的汇总计费用量统计。
num_requests: integer
发起的计费网页搜索请求次数。
top_logprobs: optional integer or null
0到20之间的整数,指定每个词元位置返回多少个最可能词元及其对数概率;实际返回数量有时会少于请求值。
minimum: 0, maximum: 20
truncation: optional "auto" or "disabled" or null (default: "disabled")
模型响应的截断策略。
auto:输入超出模型的上下文窗口时,从对话开头移除条目以适配窗口。对部分模型,API 会先从输入上限扣除模型允许的最大输出量,再统计词元。因此,即使设置较低的max_output_tokens,也可能更早开始截断。disabled(默认值):输入超出模型上下文窗口时,请求会失败并返回 400 错误。
"auto"
"disabled"
usage: optional BetaResponseUsage or null
词元用量详情,包括输入词元、输出词元、输出词元分类和词元总数。
input_tokens: integer
输入词元数量。
input_tokens_details: object { cache_write_tokens, cached_tokens, cache_write_tokens_details }
输入词元的详细分类统计。
cache_write_tokens: integer
已写入缓存的输入词元数量。
cached_tokens: integer
从缓存读取的词元数量,详见提示词缓存。
cache_write_tokens_details: optional object { ttl_12h_tokens, ttl_30m_tokens }
ttl_12h_tokens: integer
以保留 12 小时的方式写入的输入词元数量。
ttl_30m_tokens: integer
以保留 30 分钟的方式写入的输入词元数量。
output_tokens: integer
输出词元数量。
output_tokens_details: object { reasoning_tokens }
输出词元的详细分类统计。
reasoning_tokens: integer
推理词元数量。
total_tokens: integer
使用的总词元数。
user: optional string or null
此字段正被safety_identifier和prompt_cache_key取代,维持缓存优化应改用prompt_cache_key。它是终端用户的稳定标识,通过更好地归类相似请求提高命中率,也帮助OpenAI检测和防止滥用,详见安全标识。
sequence_number: integer
此事件的序列号。
type: "response.completed"
类型,固定为response.completed。
"response.completed"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
例中文字:繁星下闪烁的森林里,孤独的独角兽Lila发现了一片泛着月光的小池塘。她每晚在岸边留下闪耀的魔法花朵,希望与他人分享美丽。某个迷人的夜晚,她醒来发现友善的小动物聚在身旁,渴望与她成为朋友、共享魔法。
{
"type": "response.completed",
"response": {
"id": "resp_123",
"object": "response",
"access_programs": null,
"created_at": 1740855869,
"status": "completed",
"completed_at": 1740855870,
"error": null,
"incomplete_details": null,
"input": [],
"instructions": null,
"max_output_tokens": null,
"model": "gpt-6.2-astra",
"output": [
{
"id": "msg_123",
"type": "message",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "In a shimmering forest under a sky full of stars, a lonely unicorn named Lila discovered a hidden pond that glowed with moonlight. Every night, she would leave sparkling, magical flowers by the water's edge, hoping to share her beauty with others. One enchanting evening, she woke to find a group of friendly animals gathered around, eager to be friends and share in her magic.",
"annotations": [],
"logprobs": []
}
],
"status": "completed"
}
],
"previous_response_id": null,
"reasoning_effort": null,
"store": false,
"temperature": 1,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [],
"top_p": 1,
"truncation": "disabled",
"usage": {
"input_tokens": 0,
"output_tokens": 0,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 0,
"input_tokens_details": {
"cached_tokens": 0,
"cache_write_tokens": 0
}
},
"user": null,
"metadata": {},
"parallel_tool_calls": true
},
"sequence_number": 1
}
response.failed
响应失败时发出的事件。
结构定义
结构名称: BetaResponseFailedEvent
response: BetaResponse
失败的响应。
id: string
此响应的唯一标识符。
access_programs: object { cyber } or null
created_at: number
此响应创建时的 Unix 时间戳,单位为秒。
format: unixtime
error: BetaResponseError or null
模型未能生成响应时返回的错误对象。
code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 18 more
此响应的错误代码。
"server_error"
"rate_limit_exceeded"
"invalid_prompt"
"data_residency_mismatch"
"bio_policy"
"misalignment_policy_violation"
"vector_store_timeout"
"invalid_image"
"invalid_image_format"
"invalid_base64_image"
"invalid_image_url"
"image_too_large"
"image_too_small"
"image_parse_error"
"image_content_policy_violation"
"invalid_image_mode"
"image_file_too_large"
"unsupported_image_media_type"
"empty_image_file"
"failed_to_download_image"
"image_file_not_found"
message: string
便于人阅读的错误说明。
misalignment: optional object { detailed_explanation, error_type, review_target, steer }
detailed_explanation: optional string
对此次阻止操作的公开说明。
error_type: optional string or "potentially_unintended_data_transfer" or "potentially_unintended_data_access" or "potentially_unintended_destructive_activity" or "other"
可选的分类;客户端必须能够接受其他值。
string
SafetyAlertErrorType = "potentially_unintended_data_transfer" or "potentially_unintended_data_access" or "potentially_unintended_destructive_activity" or "other"
可选的分类;客户端必须能够接受其他值。
"potentially_unintended_data_transfer"
"potentially_unintended_data_access"
"potentially_unintended_destructive_activity"
"other"
review_target: optional string or null
用于明确继续此次审查的不透明目标;不可用时为 null。
pattern: ^[A-Za-z0-9._~:-]+$, minLength: 1, maxLength: 96
steer: optional object { message }
可选的公开继续指令。
message: string
公开的继续指令。
param: optional string or null
与错误相关的请求参数;未记录时为 null。
type: optional string or null
原始错误类型;未记录时为 null。
incomplete_details: object { reason } or null
说明响应为何未完成的详细信息。
reason: optional "max_output_tokens" or "max_messages" or "content_filter" or "steered"
响应未完成的原因。steered表示响应在收到WebSocket response.steer事件后于安全输出边界停止;服务器随后可自动使用排队输入创建后继响应。
"max_output_tokens"
"max_messages"
"content_filter"
"steered"
instructions: string or array of BetaEasyInputMessage or Message { content, role, agent, 2 more } or BetaResponseOutputMessage or 33 more or null
插入模型上下文的系统消息或开发者消息。
与previous_response_id一起使用时,前一响应的instructions不会传入下一响应,便于在新响应中替换system或developer消息。
string
提供给模型的文本输入,等同于developer角色的文本输入。
InputItemList = array of BetaEasyInputMessage or Message { content, role, agent, 2 more } or BetaResponseOutputMessage or 33 more
提供给模型的一个或多个输入条目组成的列表,其中可以包含不同类型的内容。
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
生成该条目的智能体的规范名称。
metadata: map[string] or null
可附加到对象的一组16个键值对,用于结构化保存附加信息,并通过API或控制台查询对象。
键为最长64个字符的字符串,值为最长512个字符的字符串。
model: "gpt-6-astra" or "gpt-6.2-astra" or "gpt-6.1-sol" or 112 more or string
生成响应的模型ID,例如gpt-6.2-astra。OpenAI提供能力、性能和价格各异的模型,可在模型指南浏览比较。
"gpt-6-astra" or "gpt-6.2-astra" or "gpt-6.1-sol" or 112 more
生成响应的模型ID,例如gpt-6.2-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
object: "response"
此资源的对象类型,始终为 response。
"response"
output: array of BetaResponseOutputItem
模型生成的内容条目数组。
output数组的长度和顺序取决于模型响应。不要假定首个条目一定是包含生成内容的assistant消息;可考虑使用SDK支持的output_text属性。
BetaResponseOutputMessage object { id, content, role, 4 more }
模型输出的消息。
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
从文件中检索出的文本。
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 { id, output, status, 7 more }
id: string
函数调用工具输出的唯一 ID。
output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
你的代码产生的函数调用输出,可为字符串或输出内容列表。
StringOutput = string
函数调用输出的字符串。
OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
函数调用的文本、图像或文件输出。
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
status: "in_progress" or "completed" or "incomplete"
条目状态,可选 in_progress、completed 或 incomplete,通过 API 返回条目时填充。
"in_progress"
"completed"
"incomplete"
type: "function_call_output"
类型,固定为 function_call_output。
"function_call_output"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
call_id: optional string
模型生成的函数工具调用的唯一 ID。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
调用方类型,固定为 direct。
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
minLength: 1, maxLength: 64
type: "program" (default: "program")
调用方类型,固定为 program。
"program"
created_by: optional string
创建该条目的执行主体的标识。
name: optional string
产生输出的工具名称。
namespace: optional string
产生输出的工具所属命名空间。
AgentMessage object { id, author, content, 3 more }
id: string
此智能体消息的唯一 ID。
author: string
发送方智能体的标识。
content: array of BetaResponseInputText or BetaResponseOutputText or Text { text, type } or 7 more
智能体之间发送的加密内容。
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
BetaResponseOutputText object { annotations, logprobs, text, type }
模型输出的文本。
Text object { text, type }
文本内容。
text: string
type: "text" (default: "text")
"text"
SummaryText object { text, type }
模型生成的摘要文本。
text: string
模型到目前为止生成的推理输出摘要。
type: "summary_text" (default: "summary_text")
类型,固定为 summary_text。
"summary_text"
ReasoningText object { text, type }
模型生成的推理文本。
text: string
模型生成的推理文本。
type: "reasoning_text" (default: "reasoning_text")
类型,固定为 reasoning_text。
"reasoning_text"
BetaResponseOutputRefusal object { refusal, type }
模型的拒绝响应。
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
ComputerScreenshot object { detail, file_id, image_url, 2 more }
计算机屏幕截图。
detail: BetaImageDetail
发送给模型的截图图像的细节级别,可选 high、low、auto 或 original,默认为 auto。
file_id: string or null
包含截图的已上传文件的标识。
image_url: string or null
截图图像的 URL。
format: uri
type: "computer_screenshot" (default: "computer_screenshot")
指定事件类型。对于计算机屏幕截图,此属性固定为 computer_screenshot。
"computer_screenshot"
prompt_cache_breakpoint: optional object { mode, ttl }
标记可复用提示词前缀的精确结束位置。省略 ttl 时,断点继承请求中的 prompt_cache_options.ttl;该边界不会按词元块取整。
mode: "explicit" (default: "explicit")
断点模式,固定为 explicit。
"explicit"
ttl: optional "30m" or "12h"
此缓存断点的最短存续时间,默认为请求的 TTL。
"30m"
"12h"
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
EncryptedContent object { encrypted_content, type }
不透明的加密内容,由 Responses API 在受信任的模型执行环境中解密。
encrypted_content: string
不透明的加密内容。
type: "encrypted_content" (default: "encrypted_content")
输入条目的类型,固定为 encrypted_content。
"encrypted_content"
recipient: string
接收方智能体的标识。
type: "agent_message" (default: "agent_message")
条目类型,固定为 agent_message。
"agent_message"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
MultiAgentCall object { id, action, arguments, 3 more }
id: string
该多智能体调用条目的唯一 ID。
action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more
要执行的多智能体操作。
"spawn_agent"
"interrupt_agent"
"list_agents"
"send_message"
"followup_task"
"wait_agent"
arguments: string
为该操作生成的参数,格式为 JSON 字符串。
call_id: string
关联调用与其输出的唯一 ID。
type: "multi_agent_call" (default: "multi_agent_call")
多智能体调用的类型,固定为 multi_agent_call。
"multi_agent_call"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
MultiAgentCallOutput object { id, action, call_id, 3 more }
id: string
此多智能体调用输出条目的唯一 ID。
action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more
生成此结果的多智能体操作。
"spawn_agent"
"interrupt_agent"
"list_agents"
"send_message"
"followup_task"
"wait_agent"
call_id: string
此多智能体调用的唯一 ID。
output: array of BetaResponseOutputText
多智能体操作返回的文本。
annotations: array of FileCitation { file_id, filename, index, type } or URLCitation { end_index, start_index, title, 2 more } or ContainerFileCitation { container_id, end_index, file_id, 3 more } or FilePath { file_id, index, type }
文本输出的注解。
logprobs: array of object { token, bytes, logprob, top_logprobs }
text: string
模型输出的文本内容。
type: "output_text" (default: "output_text")
输出文本类型,固定为 output_text。
type: "multi_agent_call_output" (default: "multi_agent_call_output")
多智能体结果的类型,固定为 multi_agent_call_output。
"multi_agent_call_output"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
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
生成该条目的智能体的规范名称。
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
单击操作。
actions: optional BetaComputerActionList
computer_use的扁平化批量操作。每个操作包含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
供计算机使用工具使用的屏幕截图图像。
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"
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
生成该条目的智能体的规范名称。
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 }
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: "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
生成该条目的智能体的规范名称。
Compaction object { id, encrypted_content, type, 2 more }
v1/responses/compact API生成的压缩条目。
id: string
压缩条目的唯一 ID。
encrypted_content: string
压缩生成的加密内容。
type: "compaction" (default: "compaction")
类型,固定为 compaction。
"compaction"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
created_by: optional string
创建该条目的执行主体的标识。
ImageGenerationCall object { id, result, status, 10 more }
模型发起的图像生成请求。
id: string
图像生成调用的唯一 ID。
result: string or null
Base64 编码的生成图像。
status: "in_progress" or "completed" or "generating" or "failed"
图像生成调用的状态。
"in_progress"
"completed"
"generating"
"failed"
type: "image_generation_call"
类型,固定为 image_generation_call。
"image_generation_call"
action: optional "generate" or "edit" or "auto" or null
用于图像生成的操作。
"generate"
"edit"
"auto"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
background: optional "transparent" or "opaque" or "auto" or null
生成图像使用的背景设置。
"transparent"
"opaque"
"auto"
error: optional object { code, message, param, 2 more }
审核失败的详情,如可用。
code: string or null
错误代码。
message: string
错误描述。
param: string or null
关联的请求参数。
type: string
错误类型。
moderation_details: optional object { categories, moderation_stage }
moderation_blocked 错误的公开详情,如可用。
categories: array of string
公开的审核类别,未来可能增加新的类别值。
moderation_stage: "input" or "output" or "unknown"
审核阻止图像生成调用的阶段。
"input"
"output"
"unknown"
output_format: optional "png" or "webp" or "jpeg" or 2 more or null
生成图像使用的输出格式。
"png"
"webp"
"jpeg"
"gif"
"svg"
quality: optional "low" or "medium" or "high" or 3 more or null
图像生成工具调用生成的图像质量,可选 low、medium、high、xhigh、max 或 auto。
"low"
"medium"
"high"
"xhigh"
"max"
"auto"
revised_prompt: optional string or null
模型改写提示词后实际使用的提示词。
size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or null
图像尺寸,采用 WIDTHxHEIGHT 字符串形式,例如 1536x864。
string
"1024x1024" or "1024x1536" or "1536x1024"
图像尺寸,采用 WIDTHxHEIGHT 字符串形式,例如 1536x864。
"1024x1024"
"1024x1536"
"1536x1024"
svg_usage: optional object { input_tokens, model, output_tokens, 2 more }
input_tokens: integer
model: string
output_tokens: integer
reasoning_tokens: integer
total_tokens: integer
CodeInterpreterCall object { id, code, container_id, 4 more }
运行代码的工具调用。
id: string
代码解释器工具调用的唯一 ID。
code: string or null
要运行的代码,不可用时为 null。
container_id: string
运行代码使用的容器 ID。
outputs: array of Logs { logs, type } or Image { type, url } or null
代码解释器产生的日志、图像等输出;没有可用输出时可为null。
Logs object { logs, type }
代码解释器的日志输出。
logs: string
代码解释器的日志输出。
type: "logs" (default: "logs")
类型,固定为 logs。
"logs"
Image object { type, url }
代码解释器的图像输出。
type: "image" (default: "image")
类型,固定为 image。
"image"
url: string
代码解释器输出图像的 URL。
format: uri
status: "in_progress" or "completed" or "incomplete" or 2 more
代码解释器工具调用的状态,有效值为 in_progress、completed、incomplete、interpreting 和 failed。
"in_progress"
"completed"
"incomplete"
"interpreting"
"failed"
type: "code_interpreter_call" (default: "code_interpreter_call")
类型,固定为 code_interpreter_call。
"code_interpreter_call"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
LocalShellCall object { id, action, call_id, 3 more }
在本地 shell 上运行命令的工具调用。
id: string
本地 shell 调用的唯一 ID。
action: object { command, env, type, 3 more }
在服务器上执行 shell 命令。
command: array of string
要运行的命令。
env: map[string]
要为命令设置的环境变量。
type: "exec" (default: "exec")
类型,固定为 exec。
"exec"
timeout_ms: optional integer or null
可选的命令超时时长,单位为毫秒。
user: optional string or null
可选的运行命令的用户。
working_directory: optional string or null
可选的运行命令的工作目录。
call_id: string
模型生成的本地 shell 工具调用的唯一 ID。
status: "in_progress" or "completed" or "incomplete"
本地 shell 调用的状态。
"in_progress"
"completed"
"incomplete"
type: "local_shell_call"
类型,固定为 local_shell_call。
"local_shell_call"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
LocalShellCallOutput object { id, output, type, 2 more }
本地 shell 工具调用的输出。
id: string
模型生成的本地 shell 工具调用的唯一 ID。
output: string
本地 shell 工具调用输出的 JSON 字符串。
type: "local_shell_call_output"
类型,固定为 local_shell_call_output。
"local_shell_call_output"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
status: optional "in_progress" or "completed" or "incomplete" or null
条目状态,可选 in_progress、completed 或 incomplete。
"in_progress"
"completed"
"incomplete"
ShellCall object { id, action, call_id, 6 more }
在托管环境中执行一个或多个 shell 命令的工具调用。
id: string
shell 工具调用的唯一 ID,通过 API 返回此条目时填充。
action: object { commands, max_output_length, timeout_ms }
描述如何运行工具调用的 shell 命令及限制。
commands: array of string
max_output_length: integer or null
可选的每个命令返回的最大字符数。
timeout_ms: integer or null
可选的命令超时时长,单位为毫秒。
call_id: string
模型生成的 shell 工具调用的唯一 ID。
environment: BetaResponseLocalEnvironment or BetaResponseContainerReference or null
表示使用本地环境执行 shell 操作。
BetaResponseLocalEnvironment object { type }
表示使用本地环境执行 shell 操作。
type: "local" (default: "local")
环境类型,固定为 local。
"local"
BetaResponseContainerReference object { container_id, type }
表示通过 /v1/containers 创建的容器。
container_id: string
type: "container_reference" (default: "container_reference")
环境类型,固定为 container_reference。
"container_reference"
status: "in_progress" or "completed" or "incomplete"
shell 调用状态,可选 in_progress、completed 或 incomplete。
"in_progress"
"completed"
"incomplete"
type: "shell_call" (default: "shell_call")
类型,固定为 shell_call。
"shell_call"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建此工具调用的实体的 ID。
ShellCallOutput object { id, call_id, max_output_length, 6 more }
shell 工具调用发出的输出。
id: string
shell 调用输出的唯一 ID,通过 API 返回此条目时填充。
call_id: string
模型生成的 shell 工具调用的唯一 ID。
max_output_length: integer or null
shell 命令输出的最大长度,由模型生成,应与原始输出一并回传。
output: array of object { outcome, stderr, stdout, created_by }
shell 调用输出内容的数组。
outcome: Timeout { type } or Exit { exit_code, type }
表示 shell 调用输出块的退出结果(包含退出码)或超时结果。
Timeout object { type }
表示 shell 调用超过其配置的时间限制。
type: "timeout" (default: "timeout")
结果类型,固定为 timeout。
"timeout"
Exit object { exit_code, type }
表示 shell 命令已结束,并返回退出码。
exit_code: integer
shell 进程的退出码。
type: "exit" (default: "exit")
结果类型,固定为 exit。
"exit"
stderr: string
捕获的标准错误输出。
stdout: string
捕获的标准输出。
created_by: optional string
创建该条目的执行主体的标识。
status: "in_progress" or "completed" or "incomplete"
shell 调用输出的状态,可选 in_progress、completed 或 incomplete。
"in_progress"
"completed"
"incomplete"
type: "shell_call_output" (default: "shell_call_output")
shell 调用输出的类型,固定为 shell_call_output。
"shell_call_output"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建该条目的执行主体的标识。
ApplyPatchCall object { id, call_id, operation, 5 more }
通过创建、删除或更新文件来应用文件差异的工具调用。
id: string
apply_patch 工具调用的唯一 ID,通过 API 返回此条目时填充。
call_id: string
模型生成的 apply_patch 工具调用的唯一 ID。
operation: CreateFile { diff, path, type } or DeleteFile { path, type } or UpdateFile { diff, path, type }
通过 apply_patch 应用的 create_file、delete_file 或 update_file 操作之一。
CreateFile object { diff, path, type }
描述如何通过 apply_patch 工具创建文件的指令。
diff: string
要应用的差异。
path: string
要创建的文件路径。
type: "create_file" (default: "create_file")
使用提供的差异创建新文件。
"create_file"
DeleteFile object { path, type }
描述如何通过 apply_patch 工具删除文件的指令。
path: string
要删除的文件路径。
type: "delete_file" (default: "delete_file")
删除指定文件。
"delete_file"
UpdateFile object { diff, path, type }
描述如何通过 apply_patch 工具更新文件的指令。
diff: string
要应用的差异。
path: string
要更新的文件路径。
type: "update_file" (default: "update_file")
使用提供的差异更新已有文件。
"update_file"
status: "in_progress" or "completed"
apply_patch 工具调用状态,可选 in_progress 或 completed。
"in_progress"
"completed"
type: "apply_patch_call" (default: "apply_patch_call")
类型,固定为 apply_patch_call。
"apply_patch_call"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建此工具调用的实体的 ID。
ApplyPatchCallOutput object { id, call_id, status, 5 more }
apply_patch 工具调用发出的输出。
id: string
apply_patch 工具调用输出的唯一 ID,通过 API 返回此条目时填充。
call_id: string
模型生成的 apply_patch 工具调用的唯一 ID。
status: "completed" or "failed"
apply_patch 工具调用输出的状态,可选 completed 或 failed。
"completed"
"failed"
type: "apply_patch_call_output" (default: "apply_patch_call_output")
类型,固定为 apply_patch_call_output。
"apply_patch_call_output"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建此工具调用输出的实体的 ID。
output: optional string or null
apply_patch 工具返回的可选文本输出。
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
工具调用的错误,如有。
output: optional string or null
工具调用的输出。
status: optional "in_progress" or "completed" or "incomplete" or 2 more
工具调用状态,可选 in_progress、completed、incomplete、calling 或 failed。
"in_progress"
"completed"
"incomplete"
"calling"
"failed"
McpListTools object { id, server_label, tools, 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
决定的可选理由。
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 { id, call_id, output, 5 more }
id: string
自定义工具调用输出条目的唯一 ID。
call_id: string
调用 ID,用于将此自定义工具调用输出映射到自定义工具调用。
output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
你的代码生成的自定义工具输出,可为字符串或输出内容列表。
StringOutput = string
自定义工具调用输出的字符串。
OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
自定义工具调用的文本、图像或文件输出。
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
status: "in_progress" or "completed" or "incomplete"
条目状态,可选 in_progress、completed 或 incomplete,通过 API 返回条目时填充。
"in_progress"
"completed"
"incomplete"
type: "custom_tool_call_output"
类型,固定为 custom_tool_call_output。
"custom_tool_call_output"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
调用方类型,固定为 direct。
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
minLength: 1, maxLength: 64
type: "program" (default: "program")
调用方类型,固定为 program。
"program"
created_by: optional string
创建该条目的执行主体的标识。
parallel_tool_calls: boolean (default: true)
是否允许模型并行执行工具调用。
temperature: number or null (default: 1)
采样温度,范围0到2。0.8等较高值使输出更随机,0.2等较低值使输出更集中、更确定。通常建议只修改此参数或top_p中的一个。
minimum: 0, maximum: 2
tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more
模型生成响应时如何选择工具,参见tools参数了解可调用工具的定义方式。
BetaToolChoiceOptions = "none" or "auto" or "required"
控制模型调用哪个工具,或是否调用工具。
none 表示模型直接生成消息,不调用工具。
auto 表示模型可选择生成消息,或调用一个或多个工具。
required 表示模型必须调用一个或多个工具。
"none"
"auto"
"required"
BetaToolChoiceAllowed object { mode, tools, type }
将模型可用的工具限制为预先定义的集合。
mode: "auto" or "required"
将模型可用的工具限制为预先定义的集合。
auto 允许模型从可用工具中选择,或生成消息。
required 要求模型至少调用一个可用工具。
"auto"
"required"
tools: array of map[unknown]
应允许模型调用的工具定义列表。
对于 Responses API,工具定义列表可以如下所示:
[
{ "type": "function", "name": "get_weather" },
{ "type": "mcp", "server_label": "deepwiki" },
{ "type": "image_generation" }
]
type: "allowed_tools"
允许的工具配置类型,固定为 allowed_tools。
"allowed_tools"
BetaToolChoiceTypes object { type }
指定模型应使用内置工具生成响应,详见内置工具。
type: "file_search" or "web_search_preview" or "computer" or 5 more
模型应使用的托管工具类型,详见内置工具。
允许的值为:
file_searchweb_search_previewcomputercomputer_use_previewcomputer_usecode_interpreterimage_generation
"file_search"
"web_search_preview"
"computer"
"computer_use_preview"
"computer_use"
"web_search_preview_2025_03_11"
"image_generation"
"code_interpreter"
BetaToolChoiceFunction object { name, type }
使用此选项强制模型调用指定函数。
name: string
要调用的函数名称。
type: "function"
对于函数调用,类型固定为 function。
"function"
BetaToolChoiceMcp object { server_label, type, name }
使用此选项强制模型调用远程 MCP 服务器上的指定工具。
server_label: string
要使用的 MCP 服务器标签。
type: "mcp"
对于 MCP 工具,类型固定为 mcp。
"mcp"
name: optional string or null
要在服务器上调用的工具名称。
BetaToolChoiceCustom object { name, type }
使用此选项强制模型调用特定的自定义工具。
name: string
要调用的自定义工具名称。
type: "custom"
对于自定义工具调用,类型固定为 custom。
"custom"
BetaSpecificProgrammaticToolCallingParam object { type }
type: "programmatic_tool_calling" (default: "programmatic_tool_calling")
要调用的工具,固定为 programmatic_tool_calling。
"programmatic_tool_calling"
BetaToolChoiceApplyPatch object { type }
执行工具调用时,强制模型调用 apply_patch 工具。
type: "apply_patch" (default: "apply_patch")
要调用的工具,固定为 apply_patch。
"apply_patch"
BetaToolChoiceShell object { type }
需要调用工具时,强制模型调用 shell 工具。
type: "shell" (default: "shell")
要调用的工具,固定为 shell。
"shell"
tools: array of Function { name, parameters, strict, 6 more } or FileSearch { type, vector_store_ids, filters, 2 more } or Computer { type } or 13 more
模型生成响应时可以调用的工具数组。可以通过设置 tool_choice 参数指定使用哪个工具。
支持以下几类工具:
内置工具:OpenAI提供的扩展能力,如网页搜索和文件搜索,详见内置工具。MCP工具:通过自定义MCP服务器或Google Drive、SharePoint等预定义连接器集成第三方系统,详见MCP工具。函数调用(自定义工具):开发者定义的函数,让模型以强类型参数和输出调用你的代码,详见函数调用;也可使用自定义工具调用自己的代码。
Function object { name, parameters, strict, 6 more }
定义模型可以选择调用的自有代码函数。参阅函数调用。
name: string
要调用的函数名称。
parameters: map[unknown] or null
描述函数参数的 JSON Schema 对象。
strict: boolean or null
是否对此函数工具强制执行严格参数校验。
type: "function" (default: "function")
函数工具类型,固定为 function。
"function"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
"direct"
"programmatic"
async: optional boolean
defer_loading: optional boolean
此函数是否延迟加载并通过工具搜索加载。
description: optional string or null
函数描述,模型据此判断是否调用该函数。
output_schema: optional map[unknown] or null
描述此函数字符串输出中编码的 JSON 值的 JSON Schema 对象。
FileSearch object { type, vector_store_ids, filters, 2 more }
搜索已上传文件中相关内容的工具。参阅文件搜索工具。
type: "file_search" (default: "file_search")
文件搜索工具类型,固定为 file_search。
"file_search"
vector_store_ids: array of string
要搜索的向量存储 ID 列表。
filters: optional ComparisonFilter { 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"
top_p: number or null (default: 1)
核采样是温度采样的替代方式:模型仅考虑累计概率达到top_p的词元。例如0.1表示只考虑累计概率质量前10%的词元。
通常建议只调整此项或 temperature 中的一项,不同时调整两者。
minimum: 0, maximum: 1
background: optional boolean or null (default: false)
是否在后台运行模型响应,详见后台模式。
completed_at: optional number or null
Response完成时的Unix时间戳,单位为秒,仅在状态为completed时存在。
format: unixtime
conversation: optional object { id } or null
此响应所属的对话。该响应的输入条目和输出条目已自动添加到此对话。
id: string
与此响应关联的对话的唯一 ID。
image: optional object { context_compression }
context_compression: "enabled" or "disabled"
实际采用的图像上下文优化策略。
"enabled"
"disabled"
input_transformations: optional array of object { id, action, reason, type }
未传给模型的推理输入,按输入顺序排列。
id: string
原始推理条目的 ID。
action: "removed" (default: "removed")
"removed"
reason: "organization_mismatch" or "end_user_mismatch" or "model_mismatch" or 2 more
"organization_mismatch"
"end_user_mismatch"
"model_mismatch"
"prefix_mismatch"
"turn_boundary"
type: "reasoning" (default: "reasoning")
"reasoning"
max_output_tokens: optional integer or null
响应可生成词元数的上限,包括可见输出词元及推理词元。
max_tool_calls: optional integer or null
一个响应中可处理的内置工具调用总次数上限。此上限适用于所有内置工具调用的合计次数,而非每个工具分别计算。达到上限后,模型进一步调用工具的尝试会被忽略。
moderation: optional object { input, output } or null
如果请求了经审核的补全,则包含响应输入和输出的审核结果。
input: ModerationResult { categories, category_applied_input_types, category_scores, 3 more } or Error { code, message, type }
对响应输入的审核。
ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }
针对响应输入或输出生成的审核结果。
categories: map[boolean]
审核类别到布尔值的映射。输入被某类别标记时,该类别值为 true。
category_applied_input_types: map[array of "text" or "image"]
各类别评分所涵盖的输入模态。
"text"
"image"
category_scores: map[number]
审核类别到分数的映射。
flagged: boolean
表示内容是否被任一类别标记的布尔值。
model: string
生成此结果的审核模型。
type: "moderation_result" (default: "moderation_result")
对象类型,成功审核结果中固定为 moderation_result。
"moderation_result"
Error object { code, message, type }
尝试审核响应输入或输出时产生的错误。
code: string
错误代码。
message: string
错误消息。
type: "error" (default: "error")
对象类型;审核失败时始终为 error。
"error"
output: ModerationResult { categories, category_applied_input_types, category_scores, 3 more } or Error { code, message, type }
对响应输出的审核。
ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }
针对响应输入或输出生成的审核结果。
categories: map[boolean]
审核类别到布尔值的映射。输入被某类别标记时,该类别值为 true。
category_applied_input_types: map[array of "text" or "image"]
各类别评分所涵盖的输入模态。
"text"
"image"
category_scores: map[number]
审核类别到分数的映射。
flagged: boolean
表示内容是否被任一类别标记的布尔值。
model: string
生成此结果的审核模型。
type: "moderation_result" (default: "moderation_result")
对象类型,成功审核结果中固定为 moderation_result。
"moderation_result"
Error object { code, message, type }
尝试审核响应输入或输出时产生的错误。
code: string
错误代码。
message: string
错误消息。
type: "error" (default: "error")
对象类型;审核失败时始终为 error。
"error"
output_text: optional string or null
仅SDK提供的便利属性,聚合output数组中所有output_text条目的文本(若存在),Python和JavaScript SDK支持此属性。
previous_response_id: optional string or null
前一次模型响应的唯一ID,用于多轮对话,详见对话状态。不能与conversation同时使用。
prompt: optional BetaResponsePrompt or null
提示词模板及其变量的引用,详见代码中的提示词版本。
id: string
要使用的提示词模板的唯一标识。
variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile] or null
可选的变量替换映射,用于替换提示词中的变量。替换值可为字符串,也可为图像或文件等其他Response输入类型。
string
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
version: optional string or null
提示词模板的可选版本。
prompt_cache_diagnostics: optional CacheMiss { cache_missed_tokens, reason, type, comparison_reusable_tokens } or CacheHit { type } or ComparisonResponseNotFound { type } or Unavailable { type }
为此响应请求的提示词缓存诊断信息。
CacheMiss object { cache_missed_tokens, reason, type, comparison_reusable_tokens }
cache_missed_tokens: integer
首次检测到差异之后,受影响的输入词元数量估计值。
reason: "model_changed" or "prompt_cache_key_changed" or "tools_changed" or 6 more
未复用提示词缓存的原因。
"model_changed"
"prompt_cache_key_changed"
"tools_changed"
"text_format_changed"
"reasoning_effort_changed"
"verbosity_changed"
"context_compacted"
"input_changed"
"service_tier_changed"
type: "cache_miss" (default: "cache_miss")
"cache_miss"
comparison_reusable_tokens: optional integer
在所比较的响应中,可复用前缀的原始词元数。
CacheHit object { type }
type: "cache_hit" (default: "cache_hit")
"cache_hit"
ComparisonResponseNotFound object { type }
type: "comparison_response_not_found" (default: "comparison_response_not_found")
"comparison_response_not_found"
Unavailable object { type }
type: "unavailable" (default: "unavailable")
"unavailable"
prompt_cache_key: optional string or null
供OpenAI缓存相似请求的响应,以优化缓存命中率,替代user字段,详见提示词缓存。
prompt_cache_options: optional object { mode, ttl, comparison_response_id }
应用于该响应的提示词缓存选项。支持 gpt-5.6 及更新模型。
mode: "implicit" or "explicit"
是否启用了隐式提示词缓存断点。
"implicit"
"explicit"
ttl: "30m" or "12h"
应用于每个缓存断点的最短保留时间。
"30m"
"12h"
comparison_response_id: optional string or null
用于提示词缓存诊断比较的响应 ID。
prompt_cache_retention: optional "in_memory" or "24h" or null
已弃用,改用 prompt_cache_options.ttl。
提示词缓存保留策略。设为24h启用扩展缓存,使缓存前缀保持活跃更久,最长24小时,详见缓存保留。此字段表达最长保留策略,prompt_cache_options.ttl表达最短缓存寿命;两者独立、互不影响。gpt-5.5、gpt-5.5-pro及后续模型仅支持24h。
对于同时支持 in_memory 和 24h 的较早模型,默认值取决于组织的数据保留策略:
未启用ZDR的组织默认使用24h;启用ZDR且未指定prompt_cache_retention的组织默认使用in_memory。
"in_memory"
"24h"
reasoning: optional object { context, effort, generate_summary, 2 more } or null
推理模型的配置选项。
context: optional "auto" or "current_turn" or "all_turns" or null
控制后续轮次向模型呈现哪些推理条目。省略或设为auto时由模型决定上下文模式。gpt-5.6系列默认all_turns,更早模型默认current_turn。
在响应中返回时,表示本次响应实际使用的推理上下文模式。
"auto"
"current_turn"
"all_turns"
effort: optional "none" or "minimal" or "low" or 4 more or null (default: "medium")
限制推理模型的推理努力程度。目前支持none、minimal、low、medium、high、xhigh和max。降低努力程度可能加快响应并减少推理词元。并非所有模型支持每个值,具体见推理指南。
"none"
"minimal"
"low"
"medium"
"high"
"xhigh"
"max"
generate_summary: optional "auto" or "concise" or "detailed" or null
已弃用:请改用 summary。
模型推理的摘要,有助于调试和理解推理过程。可选auto、concise或detailed。
"auto"
"concise"
"detailed"
mode: optional string or "standard" or "pro"
控制请求的推理执行模式。
当此字段出现在返回的响应中时,表示实际使用的执行模式。
string
"standard" or "pro"
控制请求的推理执行模式。
当此字段出现在返回的响应中时,表示实际使用的执行模式。
"standard"
"pro"
summary: optional "auto" or "concise" or "detailed" or null
模型推理的摘要,有助于调试和理解推理过程。可选auto、concise或detailed。
computer-use-preview 模型及 gpt-5 之后的推理模型均支持 concise。
"auto"
"concise"
"detailed"
safety_identifier: optional string or null
稳定的用户标识,帮助检测应用中可能违反OpenAI使用政策的用户。应使用唯一标识各用户、最长128字符的字符串。建议对用户名或电子邮箱进行哈希,避免发送个人身份信息,详见安全标识。
maxLength: 128
service_tier: optional BetaServiceTier or null (default: "auto")
指定处理请求所采用的服务类型。
auto使用项目设置中的服务层级,未另行配置时为default。default使用所选模型的标准价格及性能;flex使用Flex处理。在Responses或Chat Completions请求中设置service_tier=fast或service_tier=priority可启用快速模式,不论传入哪一个,原文此处写明响应显示priority。ultrafast使用受访问控制的Ultrafast层级,当前此原文列为可供gpt-5.6-sol使用,响应显示ultrafast。未设置时默认auto。
设置 service_tier 后,响应体中的同名字段反映实际采用的处理模式,可能与请求参数的值不同。
"auto"
"default"
"flex"
"scale"
"priority"
"fast"
"ultrafast"
status: optional BetaResponseStatus
响应生成状态,可选completed、failed、in_progress、cancelled、queued或incomplete。
"completed"
"failed"
"in_progress"
"cancelled"
"queued"
"incomplete"
text: optional BetaResponseTextConfig
模型文本响应的配置选项,可为纯文本或结构化JSON数据,详见下列指南。
format: optional BetaResponseFormatTextConfig
指定模型必须输出的格式的对象。
配置{ "type": "json_schema" }可启用结构化输出,确保模型匹配提供的JSON Schema,详见结构化输出指南。
默认格式为 { "type": "text" },没有额外选项。
不建议用于 gpt-4o 及后续模型:
设置{ "type": "json_object" }可启用旧版JSON模式,确保模型生成合法JSON。支持json_schema的模型优先使用后者。
Text object { type }
默认响应格式,用于生成文本响应。
type: "text"
定义的响应格式类型,固定为 text。
"text"
BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }
JSON Schema响应格式,用于生成结构化JSON,详见结构化输出。
JSONObject object { type }
JSON对象响应格式,是生成JSON响应的旧方式。支持json_schema的模型建议使用后者。注意,若system或user消息没有明确要求生成JSON,模型不会自行生成JSON。
type: "json_object"
定义的响应格式类型,固定为 json_object。
"json_object"
verbosity: optional "low" or "medium" or "high" or null (default: "medium")
约束模型响应的详细程度。较低值生成更简洁的响应,较高值生成更详细的响应。目前支持low、medium和high,默认为medium。
"low"
"medium"
"high"
tool_usage: optional object { image_gen, web_search }
托管工具报告的用量,独立于基础模型的 usage。无法取得工具用量时可省略。若返回该字段,没有用量记录的工具类别计数为零。
image_gen 合计所有图像生成调用中可取得的词元计数。可能跳过用量记录不完整的调用。输出词元明细和缓存输入计数可省略,省略缓存计数表示缓存用量未知。
web_search.num_requests 统计可计费的搜索次数。打折搜索与打开网页等操作不计入。最终费用请以账单记录为准。
image_gen: object { input_tokens, input_tokens_details, output_tokens, 4 more }
图像生成工具调用的汇总用量统计。
input_tokens: integer
输入提示词中的图像与文本词元数量。
input_tokens_details: object { image_tokens, text_tokens }
图像生成的输入词元明细。
image_tokens: integer
输入提示词中的图像词元数量。
text_tokens: integer
输入提示词中的文本词元数量。
output_tokens: integer
模型生成的输出词元数量。
total_tokens: integer
图像生成使用的图像和文本词元总数。
cached_tokens: optional integer
cached_tokens_details: optional object { cached_image_tokens, cached_text_tokens }
cached_image_tokens: integer
cached_text_tokens: integer
output_tokens_details: optional object { image_tokens, text_tokens }
图像生成的输出词元明细。
image_tokens: integer
模型生成的图像输出词元数量。
text_tokens: integer
模型生成的文本输出词元数量。
web_search: object { num_requests }
网页搜索工具调用的汇总计费用量统计。
num_requests: integer
发起的计费网页搜索请求次数。
top_logprobs: optional integer or null
0到20之间的整数,指定每个词元位置返回多少个最可能词元及其对数概率;实际返回数量有时会少于请求值。
minimum: 0, maximum: 20
truncation: optional "auto" or "disabled" or null (default: "disabled")
模型响应的截断策略。
auto:输入超出模型的上下文窗口时,从对话开头移除条目以适配窗口。对部分模型,API 会先从输入上限扣除模型允许的最大输出量,再统计词元。因此,即使设置较低的max_output_tokens,也可能更早开始截断。disabled(默认值):输入超出模型上下文窗口时,请求会失败并返回 400 错误。
"auto"
"disabled"
usage: optional BetaResponseUsage or null
词元用量详情,包括输入词元、输出词元、输出词元分类和词元总数。
input_tokens: integer
输入词元数量。
input_tokens_details: object { cache_write_tokens, cached_tokens, cache_write_tokens_details }
输入词元的详细分类统计。
cache_write_tokens: integer
已写入缓存的输入词元数量。
cached_tokens: integer
从缓存读取的词元数量,详见提示词缓存。
cache_write_tokens_details: optional object { ttl_12h_tokens, ttl_30m_tokens }
ttl_12h_tokens: integer
以保留 12 小时的方式写入的输入词元数量。
ttl_30m_tokens: integer
以保留 30 分钟的方式写入的输入词元数量。
output_tokens: integer
输出词元数量。
output_tokens_details: object { reasoning_tokens }
输出词元的详细分类统计。
reasoning_tokens: integer
推理词元数量。
total_tokens: integer
使用的总词元数。
user: optional string or null
此字段正被safety_identifier和prompt_cache_key取代,维持缓存优化应改用prompt_cache_key。它是终端用户的稳定标识,通过更好地归类相似请求提高命中率,也帮助OpenAI检测和防止滥用,详见安全标识。
sequence_number: integer
事件序列号。
type: "response.failed"
类型,固定为response.failed。
"response.failed"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
例中文字:模型未能生成响应。
{
"type": "response.failed",
"response": {
"id": "resp_123",
"object": "response",
"access_programs": null,
"created_at": 1740855869,
"status": "failed",
"completed_at": null,
"error": {
"code": "server_error",
"message": "The model failed to generate a response."
},
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-6.2-astra",
"output": [],
"previous_response_id": null,
"reasoning_effort": null,
"store": false,
"temperature": 1,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [],
"top_p": 1,
"truncation": "disabled",
"usage": null,
"user": null,
"metadata": {},
"parallel_tool_calls": true
},
"sequence_number": 1
}
response.incomplete
响应以未完成状态结束时发出。
WebSocket中的转向输入可使响应以response.incomplete_details.reason: steered结束;随后服务器自动发出后继response.created,提交排队的转向输入。
结构定义
结构名称: BetaResponseIncompleteEvent
response: BetaResponse
未完成的响应。
id: string
此响应的唯一标识符。
access_programs: object { cyber } or null
created_at: number
此响应创建时的 Unix 时间戳,单位为秒。
format: unixtime
error: BetaResponseError or null
模型未能生成响应时返回的错误对象。
code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 18 more
此响应的错误代码。
"server_error"
"rate_limit_exceeded"
"invalid_prompt"
"data_residency_mismatch"
"bio_policy"
"misalignment_policy_violation"
"vector_store_timeout"
"invalid_image"
"invalid_image_format"
"invalid_base64_image"
"invalid_image_url"
"image_too_large"
"image_too_small"
"image_parse_error"
"image_content_policy_violation"
"invalid_image_mode"
"image_file_too_large"
"unsupported_image_media_type"
"empty_image_file"
"failed_to_download_image"
"image_file_not_found"
message: string
便于人阅读的错误说明。
misalignment: optional object { detailed_explanation, error_type, review_target, steer }
detailed_explanation: optional string
对此次阻止操作的公开说明。
error_type: optional string or "potentially_unintended_data_transfer" or "potentially_unintended_data_access" or "potentially_unintended_destructive_activity" or "other"
可选的分类;客户端必须能够接受其他值。
string
SafetyAlertErrorType = "potentially_unintended_data_transfer" or "potentially_unintended_data_access" or "potentially_unintended_destructive_activity" or "other"
可选的分类;客户端必须能够接受其他值。
"potentially_unintended_data_transfer"
"potentially_unintended_data_access"
"potentially_unintended_destructive_activity"
"other"
review_target: optional string or null
用于明确继续此次审查的不透明目标;不可用时为 null。
pattern: ^[A-Za-z0-9._~:-]+$, minLength: 1, maxLength: 96
steer: optional object { message }
可选的公开继续指令。
message: string
公开的继续指令。
param: optional string or null
与错误相关的请求参数;未记录时为 null。
type: optional string or null
原始错误类型;未记录时为 null。
incomplete_details: object { reason } or null
说明响应为何未完成的详细信息。
reason: optional "max_output_tokens" or "max_messages" or "content_filter" or "steered"
响应未完成的原因。steered表示响应在收到WebSocket response.steer事件后于安全输出边界停止;服务器随后可自动使用排队输入创建后继响应。
"max_output_tokens"
"max_messages"
"content_filter"
"steered"
instructions: string or array of BetaEasyInputMessage or Message { content, role, agent, 2 more } or BetaResponseOutputMessage or 33 more or null
插入模型上下文的系统消息或开发者消息。
与previous_response_id一起使用时,前一响应的instructions不会传入下一响应,便于在新响应中替换system或developer消息。
string
提供给模型的文本输入,等同于developer角色的文本输入。
InputItemList = array of BetaEasyInputMessage or Message { content, role, agent, 2 more } or BetaResponseOutputMessage or 33 more
提供给模型的一个或多个输入条目组成的列表,其中可以包含不同类型的内容。
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
生成该条目的智能体的规范名称。
metadata: map[string] or null
可附加到对象的一组16个键值对,用于结构化保存附加信息,并通过API或控制台查询对象。
键为最长64个字符的字符串,值为最长512个字符的字符串。
model: "gpt-6-astra" or "gpt-6.2-astra" or "gpt-6.1-sol" or 112 more or string
生成响应的模型ID,例如gpt-6.2-astra。OpenAI提供能力、性能和价格各异的模型,可在模型指南浏览比较。
"gpt-6-astra" or "gpt-6.2-astra" or "gpt-6.1-sol" or 112 more
生成响应的模型ID,例如gpt-6.2-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
object: "response"
此资源的对象类型,始终为 response。
"response"
output: array of BetaResponseOutputItem
模型生成的内容条目数组。
output数组的长度和顺序取决于模型响应。不要假定首个条目一定是包含生成内容的assistant消息;可考虑使用SDK支持的output_text属性。
BetaResponseOutputMessage object { id, content, role, 4 more }
模型输出的消息。
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
从文件中检索出的文本。
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 { id, output, status, 7 more }
id: string
函数调用工具输出的唯一 ID。
output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
你的代码产生的函数调用输出,可为字符串或输出内容列表。
StringOutput = string
函数调用输出的字符串。
OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
函数调用的文本、图像或文件输出。
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
status: "in_progress" or "completed" or "incomplete"
条目状态,可选 in_progress、completed 或 incomplete,通过 API 返回条目时填充。
"in_progress"
"completed"
"incomplete"
type: "function_call_output"
类型,固定为 function_call_output。
"function_call_output"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
call_id: optional string
模型生成的函数工具调用的唯一 ID。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
调用方类型,固定为 direct。
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
minLength: 1, maxLength: 64
type: "program" (default: "program")
调用方类型,固定为 program。
"program"
created_by: optional string
创建该条目的执行主体的标识。
name: optional string
产生输出的工具名称。
namespace: optional string
产生输出的工具所属命名空间。
AgentMessage object { id, author, content, 3 more }
id: string
此智能体消息的唯一 ID。
author: string
发送方智能体的标识。
content: array of BetaResponseInputText or BetaResponseOutputText or Text { text, type } or 7 more
智能体之间发送的加密内容。
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
BetaResponseOutputText object { annotations, logprobs, text, type }
模型输出的文本。
Text object { text, type }
文本内容。
text: string
type: "text" (default: "text")
"text"
SummaryText object { text, type }
模型生成的摘要文本。
text: string
模型到目前为止生成的推理输出摘要。
type: "summary_text" (default: "summary_text")
类型,固定为 summary_text。
"summary_text"
ReasoningText object { text, type }
模型生成的推理文本。
text: string
模型生成的推理文本。
type: "reasoning_text" (default: "reasoning_text")
类型,固定为 reasoning_text。
"reasoning_text"
BetaResponseOutputRefusal object { refusal, type }
模型的拒绝响应。
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
ComputerScreenshot object { detail, file_id, image_url, 2 more }
计算机屏幕截图。
detail: BetaImageDetail
发送给模型的截图图像的细节级别,可选 high、low、auto 或 original,默认为 auto。
file_id: string or null
包含截图的已上传文件的标识。
image_url: string or null
截图图像的 URL。
format: uri
type: "computer_screenshot" (default: "computer_screenshot")
指定事件类型。对于计算机屏幕截图,此属性固定为 computer_screenshot。
"computer_screenshot"
prompt_cache_breakpoint: optional object { mode, ttl }
标记可复用提示词前缀的精确结束位置。省略 ttl 时,断点继承请求中的 prompt_cache_options.ttl;该边界不会按词元块取整。
mode: "explicit" (default: "explicit")
断点模式,固定为 explicit。
"explicit"
ttl: optional "30m" or "12h"
此缓存断点的最短存续时间,默认为请求的 TTL。
"30m"
"12h"
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
EncryptedContent object { encrypted_content, type }
不透明的加密内容,由 Responses API 在受信任的模型执行环境中解密。
encrypted_content: string
不透明的加密内容。
type: "encrypted_content" (default: "encrypted_content")
输入条目的类型,固定为 encrypted_content。
"encrypted_content"
recipient: string
接收方智能体的标识。
type: "agent_message" (default: "agent_message")
条目类型,固定为 agent_message。
"agent_message"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
MultiAgentCall object { id, action, arguments, 3 more }
id: string
该多智能体调用条目的唯一 ID。
action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more
要执行的多智能体操作。
"spawn_agent"
"interrupt_agent"
"list_agents"
"send_message"
"followup_task"
"wait_agent"
arguments: string
为该操作生成的参数,格式为 JSON 字符串。
call_id: string
关联调用与其输出的唯一 ID。
type: "multi_agent_call" (default: "multi_agent_call")
多智能体调用的类型,固定为 multi_agent_call。
"multi_agent_call"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
MultiAgentCallOutput object { id, action, call_id, 3 more }
id: string
此多智能体调用输出条目的唯一 ID。
action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more
生成此结果的多智能体操作。
"spawn_agent"
"interrupt_agent"
"list_agents"
"send_message"
"followup_task"
"wait_agent"
call_id: string
此多智能体调用的唯一 ID。
output: array of BetaResponseOutputText
多智能体操作返回的文本。
annotations: array of FileCitation { file_id, filename, index, type } or URLCitation { end_index, start_index, title, 2 more } or ContainerFileCitation { container_id, end_index, file_id, 3 more } or FilePath { file_id, index, type }
文本输出的注解。
logprobs: array of object { token, bytes, logprob, top_logprobs }
text: string
模型输出的文本内容。
type: "output_text" (default: "output_text")
输出文本类型,固定为 output_text。
type: "multi_agent_call_output" (default: "multi_agent_call_output")
多智能体结果的类型,固定为 multi_agent_call_output。
"multi_agent_call_output"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
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
生成该条目的智能体的规范名称。
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
单击操作。
actions: optional BetaComputerActionList
computer_use的扁平化批量操作。每个操作包含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
供计算机使用工具使用的屏幕截图图像。
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"
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
生成该条目的智能体的规范名称。
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 }
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: "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
生成该条目的智能体的规范名称。
Compaction object { id, encrypted_content, type, 2 more }
v1/responses/compact API生成的压缩条目。
id: string
压缩条目的唯一 ID。
encrypted_content: string
压缩生成的加密内容。
type: "compaction" (default: "compaction")
类型,固定为 compaction。
"compaction"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
created_by: optional string
创建该条目的执行主体的标识。
ImageGenerationCall object { id, result, status, 10 more }
模型发起的图像生成请求。
id: string
图像生成调用的唯一 ID。
result: string or null
Base64 编码的生成图像。
status: "in_progress" or "completed" or "generating" or "failed"
图像生成调用的状态。
"in_progress"
"completed"
"generating"
"failed"
type: "image_generation_call"
类型,固定为 image_generation_call。
"image_generation_call"
action: optional "generate" or "edit" or "auto" or null
用于图像生成的操作。
"generate"
"edit"
"auto"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
background: optional "transparent" or "opaque" or "auto" or null
生成图像使用的背景设置。
"transparent"
"opaque"
"auto"
error: optional object { code, message, param, 2 more }
审核失败的详情,如可用。
code: string or null
错误代码。
message: string
错误描述。
param: string or null
关联的请求参数。
type: string
错误类型。
moderation_details: optional object { categories, moderation_stage }
moderation_blocked 错误的公开详情,如可用。
categories: array of string
公开的审核类别,未来可能增加新的类别值。
moderation_stage: "input" or "output" or "unknown"
审核阻止图像生成调用的阶段。
"input"
"output"
"unknown"
output_format: optional "png" or "webp" or "jpeg" or 2 more or null
生成图像使用的输出格式。
"png"
"webp"
"jpeg"
"gif"
"svg"
quality: optional "low" or "medium" or "high" or 3 more or null
图像生成工具调用生成的图像质量,可选 low、medium、high、xhigh、max 或 auto。
"low"
"medium"
"high"
"xhigh"
"max"
"auto"
revised_prompt: optional string or null
模型改写提示词后实际使用的提示词。
size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or null
图像尺寸,采用 WIDTHxHEIGHT 字符串形式,例如 1536x864。
string
"1024x1024" or "1024x1536" or "1536x1024"
图像尺寸,采用 WIDTHxHEIGHT 字符串形式,例如 1536x864。
"1024x1024"
"1024x1536"
"1536x1024"
svg_usage: optional object { input_tokens, model, output_tokens, 2 more }
input_tokens: integer
model: string
output_tokens: integer
reasoning_tokens: integer
total_tokens: integer
CodeInterpreterCall object { id, code, container_id, 4 more }
运行代码的工具调用。
id: string
代码解释器工具调用的唯一 ID。
code: string or null
要运行的代码,不可用时为 null。
container_id: string
运行代码使用的容器 ID。
outputs: array of Logs { logs, type } or Image { type, url } or null
代码解释器产生的日志、图像等输出;没有可用输出时可为null。
Logs object { logs, type }
代码解释器的日志输出。
logs: string
代码解释器的日志输出。
type: "logs" (default: "logs")
类型,固定为 logs。
"logs"
Image object { type, url }
代码解释器的图像输出。
type: "image" (default: "image")
类型,固定为 image。
"image"
url: string
代码解释器输出图像的 URL。
format: uri
status: "in_progress" or "completed" or "incomplete" or 2 more
代码解释器工具调用的状态,有效值为 in_progress、completed、incomplete、interpreting 和 failed。
"in_progress"
"completed"
"incomplete"
"interpreting"
"failed"
type: "code_interpreter_call" (default: "code_interpreter_call")
类型,固定为 code_interpreter_call。
"code_interpreter_call"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
LocalShellCall object { id, action, call_id, 3 more }
在本地 shell 上运行命令的工具调用。
id: string
本地 shell 调用的唯一 ID。
action: object { command, env, type, 3 more }
在服务器上执行 shell 命令。
command: array of string
要运行的命令。
env: map[string]
要为命令设置的环境变量。
type: "exec" (default: "exec")
类型,固定为 exec。
"exec"
timeout_ms: optional integer or null
可选的命令超时时长,单位为毫秒。
user: optional string or null
可选的运行命令的用户。
working_directory: optional string or null
可选的运行命令的工作目录。
call_id: string
模型生成的本地 shell 工具调用的唯一 ID。
status: "in_progress" or "completed" or "incomplete"
本地 shell 调用的状态。
"in_progress"
"completed"
"incomplete"
type: "local_shell_call"
类型,固定为 local_shell_call。
"local_shell_call"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
LocalShellCallOutput object { id, output, type, 2 more }
本地 shell 工具调用的输出。
id: string
模型生成的本地 shell 工具调用的唯一 ID。
output: string
本地 shell 工具调用输出的 JSON 字符串。
type: "local_shell_call_output"
类型,固定为 local_shell_call_output。
"local_shell_call_output"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
status: optional "in_progress" or "completed" or "incomplete" or null
条目状态,可选 in_progress、completed 或 incomplete。
"in_progress"
"completed"
"incomplete"
ShellCall object { id, action, call_id, 6 more }
在托管环境中执行一个或多个 shell 命令的工具调用。
id: string
shell 工具调用的唯一 ID,通过 API 返回此条目时填充。
action: object { commands, max_output_length, timeout_ms }
描述如何运行工具调用的 shell 命令及限制。
commands: array of string
max_output_length: integer or null
可选的每个命令返回的最大字符数。
timeout_ms: integer or null
可选的命令超时时长,单位为毫秒。
call_id: string
模型生成的 shell 工具调用的唯一 ID。
environment: BetaResponseLocalEnvironment or BetaResponseContainerReference or null
表示使用本地环境执行 shell 操作。
BetaResponseLocalEnvironment object { type }
表示使用本地环境执行 shell 操作。
type: "local" (default: "local")
环境类型,固定为 local。
"local"
BetaResponseContainerReference object { container_id, type }
表示通过 /v1/containers 创建的容器。
container_id: string
type: "container_reference" (default: "container_reference")
环境类型,固定为 container_reference。
"container_reference"
status: "in_progress" or "completed" or "incomplete"
shell 调用状态,可选 in_progress、completed 或 incomplete。
"in_progress"
"completed"
"incomplete"
type: "shell_call" (default: "shell_call")
类型,固定为 shell_call。
"shell_call"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建此工具调用的实体的 ID。
ShellCallOutput object { id, call_id, max_output_length, 6 more }
shell 工具调用发出的输出。
id: string
shell 调用输出的唯一 ID,通过 API 返回此条目时填充。
call_id: string
模型生成的 shell 工具调用的唯一 ID。
max_output_length: integer or null
shell 命令输出的最大长度,由模型生成,应与原始输出一并回传。
output: array of object { outcome, stderr, stdout, created_by }
shell 调用输出内容的数组。
outcome: Timeout { type } or Exit { exit_code, type }
表示 shell 调用输出块的退出结果(包含退出码)或超时结果。
Timeout object { type }
表示 shell 调用超过其配置的时间限制。
type: "timeout" (default: "timeout")
结果类型,固定为 timeout。
"timeout"
Exit object { exit_code, type }
表示 shell 命令已结束,并返回退出码。
exit_code: integer
shell 进程的退出码。
type: "exit" (default: "exit")
结果类型,固定为 exit。
"exit"
stderr: string
捕获的标准错误输出。
stdout: string
捕获的标准输出。
created_by: optional string
创建该条目的执行主体的标识。
status: "in_progress" or "completed" or "incomplete"
shell 调用输出的状态,可选 in_progress、completed 或 incomplete。
"in_progress"
"completed"
"incomplete"
type: "shell_call_output" (default: "shell_call_output")
shell 调用输出的类型,固定为 shell_call_output。
"shell_call_output"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建该条目的执行主体的标识。
ApplyPatchCall object { id, call_id, operation, 5 more }
通过创建、删除或更新文件来应用文件差异的工具调用。
id: string
apply_patch 工具调用的唯一 ID,通过 API 返回此条目时填充。
call_id: string
模型生成的 apply_patch 工具调用的唯一 ID。
operation: CreateFile { diff, path, type } or DeleteFile { path, type } or UpdateFile { diff, path, type }
通过 apply_patch 应用的 create_file、delete_file 或 update_file 操作之一。
CreateFile object { diff, path, type }
描述如何通过 apply_patch 工具创建文件的指令。
diff: string
要应用的差异。
path: string
要创建的文件路径。
type: "create_file" (default: "create_file")
使用提供的差异创建新文件。
"create_file"
DeleteFile object { path, type }
描述如何通过 apply_patch 工具删除文件的指令。
path: string
要删除的文件路径。
type: "delete_file" (default: "delete_file")
删除指定文件。
"delete_file"
UpdateFile object { diff, path, type }
描述如何通过 apply_patch 工具更新文件的指令。
diff: string
要应用的差异。
path: string
要更新的文件路径。
type: "update_file" (default: "update_file")
使用提供的差异更新已有文件。
"update_file"
status: "in_progress" or "completed"
apply_patch 工具调用状态,可选 in_progress 或 completed。
"in_progress"
"completed"
type: "apply_patch_call" (default: "apply_patch_call")
类型,固定为 apply_patch_call。
"apply_patch_call"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建此工具调用的实体的 ID。
ApplyPatchCallOutput object { id, call_id, status, 5 more }
apply_patch 工具调用发出的输出。
id: string
apply_patch 工具调用输出的唯一 ID,通过 API 返回此条目时填充。
call_id: string
模型生成的 apply_patch 工具调用的唯一 ID。
status: "completed" or "failed"
apply_patch 工具调用输出的状态,可选 completed 或 failed。
"completed"
"failed"
type: "apply_patch_call_output" (default: "apply_patch_call_output")
类型,固定为 apply_patch_call_output。
"apply_patch_call_output"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建此工具调用输出的实体的 ID。
output: optional string or null
apply_patch 工具返回的可选文本输出。
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
工具调用的错误,如有。
output: optional string or null
工具调用的输出。
status: optional "in_progress" or "completed" or "incomplete" or 2 more
工具调用状态,可选 in_progress、completed、incomplete、calling 或 failed。
"in_progress"
"completed"
"incomplete"
"calling"
"failed"
McpListTools object { id, server_label, tools, 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
决定的可选理由。
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 { id, call_id, output, 5 more }
id: string
自定义工具调用输出条目的唯一 ID。
call_id: string
调用 ID,用于将此自定义工具调用输出映射到自定义工具调用。
output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
你的代码生成的自定义工具输出,可为字符串或输出内容列表。
StringOutput = string
自定义工具调用输出的字符串。
OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
自定义工具调用的文本、图像或文件输出。
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
status: "in_progress" or "completed" or "incomplete"
条目状态,可选 in_progress、completed 或 incomplete,通过 API 返回条目时填充。
"in_progress"
"completed"
"incomplete"
type: "custom_tool_call_output"
类型,固定为 custom_tool_call_output。
"custom_tool_call_output"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
调用方类型,固定为 direct。
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
minLength: 1, maxLength: 64
type: "program" (default: "program")
调用方类型,固定为 program。
"program"
created_by: optional string
创建该条目的执行主体的标识。
parallel_tool_calls: boolean (default: true)
是否允许模型并行执行工具调用。
temperature: number or null (default: 1)
采样温度,范围0到2。0.8等较高值使输出更随机,0.2等较低值使输出更集中、更确定。通常建议只修改此参数或top_p中的一个。
minimum: 0, maximum: 2
tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more
模型生成响应时如何选择工具,参见tools参数了解可调用工具的定义方式。
BetaToolChoiceOptions = "none" or "auto" or "required"
控制模型调用哪个工具,或是否调用工具。
none 表示模型直接生成消息,不调用工具。
auto 表示模型可选择生成消息,或调用一个或多个工具。
required 表示模型必须调用一个或多个工具。
"none"
"auto"
"required"
BetaToolChoiceAllowed object { mode, tools, type }
将模型可用的工具限制为预先定义的集合。
mode: "auto" or "required"
将模型可用的工具限制为预先定义的集合。
auto 允许模型从可用工具中选择,或生成消息。
required 要求模型至少调用一个可用工具。
"auto"
"required"
tools: array of map[unknown]
应允许模型调用的工具定义列表。
对于 Responses API,工具定义列表可以如下所示:
[
{ "type": "function", "name": "get_weather" },
{ "type": "mcp", "server_label": "deepwiki" },
{ "type": "image_generation" }
]
type: "allowed_tools"
允许的工具配置类型,固定为 allowed_tools。
"allowed_tools"
BetaToolChoiceTypes object { type }
指定模型应使用内置工具生成响应,详见内置工具。
type: "file_search" or "web_search_preview" or "computer" or 5 more
模型应使用的托管工具类型,详见内置工具。
允许的值为:
file_searchweb_search_previewcomputercomputer_use_previewcomputer_usecode_interpreterimage_generation
"file_search"
"web_search_preview"
"computer"
"computer_use_preview"
"computer_use"
"web_search_preview_2025_03_11"
"image_generation"
"code_interpreter"
BetaToolChoiceFunction object { name, type }
使用此选项强制模型调用指定函数。
name: string
要调用的函数名称。
type: "function"
对于函数调用,类型固定为 function。
"function"
BetaToolChoiceMcp object { server_label, type, name }
使用此选项强制模型调用远程 MCP 服务器上的指定工具。
server_label: string
要使用的 MCP 服务器标签。
type: "mcp"
对于 MCP 工具,类型固定为 mcp。
"mcp"
name: optional string or null
要在服务器上调用的工具名称。
BetaToolChoiceCustom object { name, type }
使用此选项强制模型调用特定的自定义工具。
name: string
要调用的自定义工具名称。
type: "custom"
对于自定义工具调用,类型固定为 custom。
"custom"
BetaSpecificProgrammaticToolCallingParam object { type }
type: "programmatic_tool_calling" (default: "programmatic_tool_calling")
要调用的工具,固定为 programmatic_tool_calling。
"programmatic_tool_calling"
BetaToolChoiceApplyPatch object { type }
执行工具调用时,强制模型调用 apply_patch 工具。
type: "apply_patch" (default: "apply_patch")
要调用的工具,固定为 apply_patch。
"apply_patch"
BetaToolChoiceShell object { type }
需要调用工具时,强制模型调用 shell 工具。
type: "shell" (default: "shell")
要调用的工具,固定为 shell。
"shell"
tools: array of Function { name, parameters, strict, 6 more } or FileSearch { type, vector_store_ids, filters, 2 more } or Computer { type } or 13 more
模型生成响应时可以调用的工具数组。可以通过设置 tool_choice 参数指定使用哪个工具。
支持以下几类工具:
内置工具:OpenAI提供的扩展能力,如网页搜索和文件搜索,详见内置工具。MCP工具:通过自定义MCP服务器或Google Drive、SharePoint等预定义连接器集成第三方系统,详见MCP工具。函数调用(自定义工具):开发者定义的函数,让模型以强类型参数和输出调用你的代码,详见函数调用;也可使用自定义工具调用自己的代码。
Function object { name, parameters, strict, 6 more }
定义模型可以选择调用的自有代码函数。参阅函数调用。
name: string
要调用的函数名称。
parameters: map[unknown] or null
描述函数参数的 JSON Schema 对象。
strict: boolean or null
是否对此函数工具强制执行严格参数校验。
type: "function" (default: "function")
函数工具类型,固定为 function。
"function"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
"direct"
"programmatic"
async: optional boolean
defer_loading: optional boolean
此函数是否延迟加载并通过工具搜索加载。
description: optional string or null
函数描述,模型据此判断是否调用该函数。
output_schema: optional map[unknown] or null
描述此函数字符串输出中编码的 JSON 值的 JSON Schema 对象。
FileSearch object { type, vector_store_ids, filters, 2 more }
搜索已上传文件中相关内容的工具。参阅文件搜索工具。
type: "file_search" (default: "file_search")
文件搜索工具类型,固定为 file_search。
"file_search"
vector_store_ids: array of string
要搜索的向量存储 ID 列表。
filters: optional ComparisonFilter { 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"
top_p: number or null (default: 1)
核采样是温度采样的替代方式:模型仅考虑累计概率达到top_p的词元。例如0.1表示只考虑累计概率质量前10%的词元。
通常建议只调整此项或 temperature 中的一项,不同时调整两者。
minimum: 0, maximum: 1
background: optional boolean or null (default: false)
是否在后台运行模型响应,详见后台模式。
completed_at: optional number or null
Response完成时的Unix时间戳,单位为秒,仅在状态为completed时存在。
format: unixtime
conversation: optional object { id } or null
此响应所属的对话。该响应的输入条目和输出条目已自动添加到此对话。
id: string
与此响应关联的对话的唯一 ID。
image: optional object { context_compression }
context_compression: "enabled" or "disabled"
实际采用的图像上下文优化策略。
"enabled"
"disabled"
input_transformations: optional array of object { id, action, reason, type }
未传给模型的推理输入,按输入顺序排列。
id: string
原始推理条目的 ID。
action: "removed" (default: "removed")
"removed"
reason: "organization_mismatch" or "end_user_mismatch" or "model_mismatch" or 2 more
"organization_mismatch"
"end_user_mismatch"
"model_mismatch"
"prefix_mismatch"
"turn_boundary"
type: "reasoning" (default: "reasoning")
"reasoning"
max_output_tokens: optional integer or null
响应可生成词元数的上限,包括可见输出词元及推理词元。
max_tool_calls: optional integer or null
一个响应中可处理的内置工具调用总次数上限。此上限适用于所有内置工具调用的合计次数,而非每个工具分别计算。达到上限后,模型进一步调用工具的尝试会被忽略。
moderation: optional object { input, output } or null
如果请求了经审核的补全,则包含响应输入和输出的审核结果。
input: ModerationResult { categories, category_applied_input_types, category_scores, 3 more } or Error { code, message, type }
对响应输入的审核。
ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }
针对响应输入或输出生成的审核结果。
categories: map[boolean]
审核类别到布尔值的映射。输入被某类别标记时,该类别值为 true。
category_applied_input_types: map[array of "text" or "image"]
各类别评分所涵盖的输入模态。
"text"
"image"
category_scores: map[number]
审核类别到分数的映射。
flagged: boolean
表示内容是否被任一类别标记的布尔值。
model: string
生成此结果的审核模型。
type: "moderation_result" (default: "moderation_result")
对象类型,成功审核结果中固定为 moderation_result。
"moderation_result"
Error object { code, message, type }
尝试审核响应输入或输出时产生的错误。
code: string
错误代码。
message: string
错误消息。
type: "error" (default: "error")
对象类型;审核失败时始终为 error。
"error"
output: ModerationResult { categories, category_applied_input_types, category_scores, 3 more } or Error { code, message, type }
对响应输出的审核。
ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }
针对响应输入或输出生成的审核结果。
categories: map[boolean]
审核类别到布尔值的映射。输入被某类别标记时,该类别值为 true。
category_applied_input_types: map[array of "text" or "image"]
各类别评分所涵盖的输入模态。
"text"
"image"
category_scores: map[number]
审核类别到分数的映射。
flagged: boolean
表示内容是否被任一类别标记的布尔值。
model: string
生成此结果的审核模型。
type: "moderation_result" (default: "moderation_result")
对象类型,成功审核结果中固定为 moderation_result。
"moderation_result"
Error object { code, message, type }
尝试审核响应输入或输出时产生的错误。
code: string
错误代码。
message: string
错误消息。
type: "error" (default: "error")
对象类型;审核失败时始终为 error。
"error"
output_text: optional string or null
仅SDK提供的便利属性,聚合output数组中所有output_text条目的文本(若存在),Python和JavaScript SDK支持此属性。
previous_response_id: optional string or null
前一次模型响应的唯一ID,用于多轮对话,详见对话状态。不能与conversation同时使用。
prompt: optional BetaResponsePrompt or null
提示词模板及其变量的引用,详见代码中的提示词版本。
id: string
要使用的提示词模板的唯一标识。
variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile] or null
可选的变量替换映射,用于替换提示词中的变量。替换值可为字符串,也可为图像或文件等其他Response输入类型。
string
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
version: optional string or null
提示词模板的可选版本。
prompt_cache_diagnostics: optional CacheMiss { cache_missed_tokens, reason, type, comparison_reusable_tokens } or CacheHit { type } or ComparisonResponseNotFound { type } or Unavailable { type }
为此响应请求的提示词缓存诊断信息。
CacheMiss object { cache_missed_tokens, reason, type, comparison_reusable_tokens }
cache_missed_tokens: integer
首次检测到差异之后,受影响的输入词元数量估计值。
reason: "model_changed" or "prompt_cache_key_changed" or "tools_changed" or 6 more
未复用提示词缓存的原因。
"model_changed"
"prompt_cache_key_changed"
"tools_changed"
"text_format_changed"
"reasoning_effort_changed"
"verbosity_changed"
"context_compacted"
"input_changed"
"service_tier_changed"
type: "cache_miss" (default: "cache_miss")
"cache_miss"
comparison_reusable_tokens: optional integer
在所比较的响应中,可复用前缀的原始词元数。
CacheHit object { type }
type: "cache_hit" (default: "cache_hit")
"cache_hit"
ComparisonResponseNotFound object { type }
type: "comparison_response_not_found" (default: "comparison_response_not_found")
"comparison_response_not_found"
Unavailable object { type }
type: "unavailable" (default: "unavailable")
"unavailable"
prompt_cache_key: optional string or null
供OpenAI缓存相似请求的响应,以优化缓存命中率,替代user字段,详见提示词缓存。
prompt_cache_options: optional object { mode, ttl, comparison_response_id }
应用于该响应的提示词缓存选项。支持 gpt-5.6 及更新模型。
mode: "implicit" or "explicit"
是否启用了隐式提示词缓存断点。
"implicit"
"explicit"
ttl: "30m" or "12h"
应用于每个缓存断点的最短保留时间。
"30m"
"12h"
comparison_response_id: optional string or null
用于提示词缓存诊断比较的响应 ID。
prompt_cache_retention: optional "in_memory" or "24h" or null
已弃用,改用 prompt_cache_options.ttl。
提示词缓存保留策略。设为24h启用扩展缓存,使缓存前缀保持活跃更久,最长24小时,详见缓存保留。此字段表达最长保留策略,prompt_cache_options.ttl表达最短缓存寿命;两者独立、互不影响。gpt-5.5、gpt-5.5-pro及后续模型仅支持24h。
对于同时支持 in_memory 和 24h 的较早模型,默认值取决于组织的数据保留策略:
未启用ZDR的组织默认使用24h;启用ZDR且未指定prompt_cache_retention的组织默认使用in_memory。
"in_memory"
"24h"
reasoning: optional object { context, effort, generate_summary, 2 more } or null
推理模型的配置选项。
context: optional "auto" or "current_turn" or "all_turns" or null
控制后续轮次向模型呈现哪些推理条目。省略或设为auto时由模型决定上下文模式。gpt-5.6系列默认all_turns,更早模型默认current_turn。
在响应中返回时,表示本次响应实际使用的推理上下文模式。
"auto"
"current_turn"
"all_turns"
effort: optional "none" or "minimal" or "low" or 4 more or null (default: "medium")
限制推理模型的推理努力程度。目前支持none、minimal、low、medium、high、xhigh和max。降低努力程度可能加快响应并减少推理词元。并非所有模型支持每个值,具体见推理指南。
"none"
"minimal"
"low"
"medium"
"high"
"xhigh"
"max"
generate_summary: optional "auto" or "concise" or "detailed" or null
已弃用:请改用 summary。
模型推理的摘要,有助于调试和理解推理过程。可选auto、concise或detailed。
"auto"
"concise"
"detailed"
mode: optional string or "standard" or "pro"
控制请求的推理执行模式。
当此字段出现在返回的响应中时,表示实际使用的执行模式。
string
"standard" or "pro"
控制请求的推理执行模式。
当此字段出现在返回的响应中时,表示实际使用的执行模式。
"standard"
"pro"
summary: optional "auto" or "concise" or "detailed" or null
模型推理的摘要,有助于调试和理解推理过程。可选auto、concise或detailed。
computer-use-preview 模型及 gpt-5 之后的推理模型均支持 concise。
"auto"
"concise"
"detailed"
safety_identifier: optional string or null
稳定的用户标识,帮助检测应用中可能违反OpenAI使用政策的用户。应使用唯一标识各用户、最长128字符的字符串。建议对用户名或电子邮箱进行哈希,避免发送个人身份信息,详见安全标识。
maxLength: 128
service_tier: optional BetaServiceTier or null (default: "auto")
指定处理请求所采用的服务类型。
auto使用项目设置中的服务层级,未另行配置时为default。default使用所选模型的标准价格及性能;flex使用Flex处理。在Responses或Chat Completions请求中设置service_tier=fast或service_tier=priority可启用快速模式,不论传入哪一个,原文此处写明响应显示priority。ultrafast使用受访问控制的Ultrafast层级,当前此原文列为可供gpt-5.6-sol使用,响应显示ultrafast。未设置时默认auto。
设置 service_tier 后,响应体中的同名字段反映实际采用的处理模式,可能与请求参数的值不同。
"auto"
"default"
"flex"
"scale"
"priority"
"fast"
"ultrafast"
status: optional BetaResponseStatus
响应生成状态,可选completed、failed、in_progress、cancelled、queued或incomplete。
"completed"
"failed"
"in_progress"
"cancelled"
"queued"
"incomplete"
text: optional BetaResponseTextConfig
模型文本响应的配置选项,可为纯文本或结构化JSON数据,详见下列指南。
format: optional BetaResponseFormatTextConfig
指定模型必须输出的格式的对象。
配置{ "type": "json_schema" }可启用结构化输出,确保模型匹配提供的JSON Schema,详见结构化输出指南。
默认格式为 { "type": "text" },没有额外选项。
不建议用于 gpt-4o 及后续模型:
设置{ "type": "json_object" }可启用旧版JSON模式,确保模型生成合法JSON。支持json_schema的模型优先使用后者。
Text object { type }
默认响应格式,用于生成文本响应。
type: "text"
定义的响应格式类型,固定为 text。
"text"
BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }
JSON Schema响应格式,用于生成结构化JSON,详见结构化输出。
JSONObject object { type }
JSON对象响应格式,是生成JSON响应的旧方式。支持json_schema的模型建议使用后者。注意,若system或user消息没有明确要求生成JSON,模型不会自行生成JSON。
type: "json_object"
定义的响应格式类型,固定为 json_object。
"json_object"
verbosity: optional "low" or "medium" or "high" or null (default: "medium")
约束模型响应的详细程度。较低值生成更简洁的响应,较高值生成更详细的响应。目前支持low、medium和high,默认为medium。
"low"
"medium"
"high"
tool_usage: optional object { image_gen, web_search }
托管工具报告的用量,独立于基础模型的 usage。无法取得工具用量时可省略。若返回该字段,没有用量记录的工具类别计数为零。
image_gen 合计所有图像生成调用中可取得的词元计数。可能跳过用量记录不完整的调用。输出词元明细和缓存输入计数可省略,省略缓存计数表示缓存用量未知。
web_search.num_requests 统计可计费的搜索次数。打折搜索与打开网页等操作不计入。最终费用请以账单记录为准。
image_gen: object { input_tokens, input_tokens_details, output_tokens, 4 more }
图像生成工具调用的汇总用量统计。
input_tokens: integer
输入提示词中的图像与文本词元数量。
input_tokens_details: object { image_tokens, text_tokens }
图像生成的输入词元明细。
image_tokens: integer
输入提示词中的图像词元数量。
text_tokens: integer
输入提示词中的文本词元数量。
output_tokens: integer
模型生成的输出词元数量。
total_tokens: integer
图像生成使用的图像和文本词元总数。
cached_tokens: optional integer
cached_tokens_details: optional object { cached_image_tokens, cached_text_tokens }
cached_image_tokens: integer
cached_text_tokens: integer
output_tokens_details: optional object { image_tokens, text_tokens }
图像生成的输出词元明细。
image_tokens: integer
模型生成的图像输出词元数量。
text_tokens: integer
模型生成的文本输出词元数量。
web_search: object { num_requests }
网页搜索工具调用的汇总计费用量统计。
num_requests: integer
发起的计费网页搜索请求次数。
top_logprobs: optional integer or null
0到20之间的整数,指定每个词元位置返回多少个最可能词元及其对数概率;实际返回数量有时会少于请求值。
minimum: 0, maximum: 20
truncation: optional "auto" or "disabled" or null (default: "disabled")
模型响应的截断策略。
auto:输入超出模型的上下文窗口时,从对话开头移除条目以适配窗口。对部分模型,API 会先从输入上限扣除模型允许的最大输出量,再统计词元。因此,即使设置较低的max_output_tokens,也可能更早开始截断。disabled(默认值):输入超出模型上下文窗口时,请求会失败并返回 400 错误。
"auto"
"disabled"
usage: optional BetaResponseUsage or null
词元用量详情,包括输入词元、输出词元、输出词元分类和词元总数。
input_tokens: integer
输入词元数量。
input_tokens_details: object { cache_write_tokens, cached_tokens, cache_write_tokens_details }
输入词元的详细分类统计。
cache_write_tokens: integer
已写入缓存的输入词元数量。
cached_tokens: integer
从缓存读取的词元数量,详见提示词缓存。
cache_write_tokens_details: optional object { ttl_12h_tokens, ttl_30m_tokens }
ttl_12h_tokens: integer
以保留 12 小时的方式写入的输入词元数量。
ttl_30m_tokens: integer
以保留 30 分钟的方式写入的输入词元数量。
output_tokens: integer
输出词元数量。
output_tokens_details: object { reasoning_tokens }
输出词元的详细分类统计。
reasoning_tokens: integer
推理词元数量。
total_tokens: integer
使用的总词元数。
user: optional string or null
此字段正被safety_identifier和prompt_cache_key取代,维持缓存优化应改用prompt_cache_key。它是终端用户的稳定标识,通过更好地归类相似请求提高命中率,也帮助OpenAI检测和防止滥用,详见安全标识。
sequence_number: integer
事件序列号。
type: "response.incomplete"
类型,固定为response.incomplete。
"response.incomplete"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.incomplete",
"response": {
"id": "resp_123",
"object": "response",
"access_programs": null,
"created_at": 1740855869,
"status": "incomplete",
"completed_at": null,
"error": null,
"incomplete_details": {
"reason": "max_output_tokens"
},
"instructions": null,
"max_output_tokens": null,
"model": "gpt-6.2-astra",
"output": [],
"previous_response_id": null,
"reasoning_effort": null,
"store": false,
"temperature": 1,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [],
"top_p": 1,
"truncation": "disabled",
"usage": null,
"user": null,
"metadata": {},
"parallel_tool_calls": true
},
"sequence_number": 1
}
response.output_item.added
添加新输出条目时发出。
结构定义
结构名称: BetaResponseOutputItemAddedEvent
item: BetaResponseOutputItem
新增输出条目。推理条目仍在进行中时,encrypted_content可能不完整;后续请求应使用对应response.output_item.done事件中的推理条目作为输入。
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
从文件中检索出的文本。
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 { id, output, status, 7 more }
id: string
函数调用工具输出的唯一 ID。
output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
你的代码产生的函数调用输出,可为字符串或输出内容列表。
StringOutput = string
函数调用输出的字符串。
OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
函数调用的文本、图像或文件输出。
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
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"
status: "in_progress" or "completed" or "incomplete"
条目状态,可选 in_progress、completed 或 incomplete,通过 API 返回条目时填充。
"in_progress"
"completed"
"incomplete"
type: "function_call_output"
类型,固定为 function_call_output。
"function_call_output"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
call_id: optional string
模型生成的函数工具调用的唯一 ID。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
调用方类型,固定为 direct。
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
minLength: 1, maxLength: 64
type: "program" (default: "program")
调用方类型,固定为 program。
"program"
created_by: optional string
创建该条目的执行主体的标识。
name: optional string
产生输出的工具名称。
namespace: optional string
产生输出的工具所属命名空间。
AgentMessage object { id, author, content, 3 more }
id: string
此智能体消息的唯一 ID。
author: string
发送方智能体的标识。
content: array of BetaResponseInputText or BetaResponseOutputText or Text { text, type } or 7 more
智能体之间发送的加密内容。
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
BetaResponseOutputText object { annotations, logprobs, text, type }
模型输出的文本。
Text object { text, type }
文本内容。
text: string
type: "text" (default: "text")
"text"
SummaryText object { text, type }
模型生成的摘要文本。
text: string
模型到目前为止生成的推理输出摘要。
type: "summary_text" (default: "summary_text")
类型,固定为 summary_text。
"summary_text"
ReasoningText object { text, type }
模型生成的推理文本。
text: string
模型生成的推理文本。
type: "reasoning_text" (default: "reasoning_text")
类型,固定为 reasoning_text。
"reasoning_text"
BetaResponseOutputRefusal object { refusal, type }
模型的拒绝响应。
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
ComputerScreenshot object { detail, file_id, image_url, 2 more }
计算机屏幕截图。
detail: BetaImageDetail
发送给模型的截图图像的细节级别,可选 high、low、auto 或 original,默认为 auto。
file_id: string or null
包含截图的已上传文件的标识。
image_url: string or null
截图图像的 URL。
format: uri
type: "computer_screenshot" (default: "computer_screenshot")
指定事件类型。对于计算机屏幕截图,此属性固定为 computer_screenshot。
"computer_screenshot"
prompt_cache_breakpoint: optional object { mode, ttl }
标记可复用提示词前缀的精确结束位置。省略 ttl 时,断点继承请求中的 prompt_cache_options.ttl;该边界不会按词元块取整。
mode: "explicit" (default: "explicit")
断点模式,固定为 explicit。
"explicit"
ttl: optional "30m" or "12h"
此缓存断点的最短存续时间,默认为请求的 TTL。
"30m"
"12h"
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
EncryptedContent object { encrypted_content, type }
不透明的加密内容,由 Responses API 在受信任的模型执行环境中解密。
encrypted_content: string
不透明的加密内容。
type: "encrypted_content" (default: "encrypted_content")
输入条目的类型,固定为 encrypted_content。
"encrypted_content"
recipient: string
接收方智能体的标识。
type: "agent_message" (default: "agent_message")
条目类型,固定为 agent_message。
"agent_message"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
MultiAgentCall object { id, action, arguments, 3 more }
id: string
该多智能体调用条目的唯一 ID。
action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more
要执行的多智能体操作。
"spawn_agent"
"interrupt_agent"
"list_agents"
"send_message"
"followup_task"
"wait_agent"
arguments: string
为该操作生成的参数,格式为 JSON 字符串。
call_id: string
关联调用与其输出的唯一 ID。
type: "multi_agent_call" (default: "multi_agent_call")
多智能体调用的类型,固定为 multi_agent_call。
"multi_agent_call"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
MultiAgentCallOutput object { id, action, call_id, 3 more }
id: string
此多智能体调用输出条目的唯一 ID。
action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more
生成此结果的多智能体操作。
"spawn_agent"
"interrupt_agent"
"list_agents"
"send_message"
"followup_task"
"wait_agent"
call_id: string
此多智能体调用的唯一 ID。
output: array of BetaResponseOutputText
多智能体操作返回的文本。
annotations: array of FileCitation { file_id, filename, index, type } or URLCitation { end_index, start_index, title, 2 more } or ContainerFileCitation { container_id, end_index, file_id, 3 more } or FilePath { file_id, index, type }
文本输出的注解。
logprobs: array of object { token, bytes, logprob, top_logprobs }
text: string
模型输出的文本内容。
type: "output_text" (default: "output_text")
输出文本类型,固定为 output_text。
type: "multi_agent_call_output" (default: "multi_agent_call_output")
多智能体结果的类型,固定为 multi_agent_call_output。
"multi_agent_call_output"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
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
生成该条目的智能体的规范名称。
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"
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
生成该条目的智能体的规范名称。
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
生成该条目的智能体的规范名称。
Compaction object { id, encrypted_content, type, 2 more }
v1/responses/compact API生成的压缩条目。
id: string
压缩条目的唯一 ID。
encrypted_content: string
压缩生成的加密内容。
type: "compaction" (default: "compaction")
类型,固定为 compaction。
"compaction"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
created_by: optional string
创建该条目的执行主体的标识。
ImageGenerationCall object { id, result, status, 10 more }
模型发起的图像生成请求。
id: string
图像生成调用的唯一 ID。
result: string or null
Base64 编码的生成图像。
status: "in_progress" or "completed" or "generating" or "failed"
图像生成调用的状态。
"in_progress"
"completed"
"generating"
"failed"
type: "image_generation_call"
类型,固定为 image_generation_call。
"image_generation_call"
action: optional "generate" or "edit" or "auto" or null
用于图像生成的操作。
"generate"
"edit"
"auto"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
background: optional "transparent" or "opaque" or "auto" or null
生成图像使用的背景设置。
"transparent"
"opaque"
"auto"
error: optional object { code, message, param, 2 more }
审核失败的详情,如可用。
code: string or null
错误代码。
message: string
错误描述。
param: string or null
关联的请求参数。
type: string
错误类型。
moderation_details: optional object { categories, moderation_stage }
moderation_blocked 错误的公开详情,如可用。
categories: array of string
公开的审核类别,未来可能增加新的类别值。
moderation_stage: "input" or "output" or "unknown"
审核阻止图像生成调用的阶段。
"input"
"output"
"unknown"
output_format: optional "png" or "webp" or "jpeg" or 2 more or null
生成图像使用的输出格式。
"png"
"webp"
"jpeg"
"gif"
"svg"
quality: optional "low" or "medium" or "high" or 3 more or null
图像生成工具调用生成的图像质量,可选 low、medium、high、xhigh、max 或 auto。
"low"
"medium"
"high"
"xhigh"
"max"
"auto"
revised_prompt: optional string or null
模型改写提示词后实际使用的提示词。
size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or null
图像尺寸,采用 WIDTHxHEIGHT 字符串形式,例如 1536x864。
string
"1024x1024" or "1024x1536" or "1536x1024"
图像尺寸,采用 WIDTHxHEIGHT 字符串形式,例如 1536x864。
"1024x1024"
"1024x1536"
"1536x1024"
svg_usage: optional object { input_tokens, model, output_tokens, 2 more }
input_tokens: integer
model: string
output_tokens: integer
reasoning_tokens: integer
total_tokens: integer
CodeInterpreterCall object { id, code, container_id, 4 more }
运行代码的工具调用。
id: string
代码解释器工具调用的唯一 ID。
code: string or null
要运行的代码,不可用时为 null。
container_id: string
运行代码使用的容器 ID。
outputs: array of Logs { logs, type } or Image { type, url } or null
代码解释器产生的日志、图像等输出;没有可用输出时可为null。
Logs object { logs, type }
代码解释器的日志输出。
logs: string
代码解释器的日志输出。
type: "logs" (default: "logs")
类型,固定为 logs。
"logs"
Image object { type, url }
代码解释器的图像输出。
type: "image" (default: "image")
类型,固定为 image。
"image"
url: string
代码解释器输出图像的 URL。
format: uri
status: "in_progress" or "completed" or "incomplete" or 2 more
代码解释器工具调用的状态,有效值为 in_progress、completed、incomplete、interpreting 和 failed。
"in_progress"
"completed"
"incomplete"
"interpreting"
"failed"
type: "code_interpreter_call" (default: "code_interpreter_call")
类型,固定为 code_interpreter_call。
"code_interpreter_call"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
LocalShellCall object { id, action, call_id, 3 more }
在本地 shell 上运行命令的工具调用。
id: string
本地 shell 调用的唯一 ID。
action: object { command, env, type, 3 more }
在服务器上执行 shell 命令。
command: array of string
要运行的命令。
env: map[string]
要为命令设置的环境变量。
type: "exec" (default: "exec")
类型,固定为 exec。
"exec"
timeout_ms: optional integer or null
可选的命令超时时长,单位为毫秒。
user: optional string or null
可选的运行命令的用户。
working_directory: optional string or null
可选的运行命令的工作目录。
call_id: string
模型生成的本地 shell 工具调用的唯一 ID。
status: "in_progress" or "completed" or "incomplete"
本地 shell 调用的状态。
"in_progress"
"completed"
"incomplete"
type: "local_shell_call"
类型,固定为 local_shell_call。
"local_shell_call"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
LocalShellCallOutput object { id, output, type, 2 more }
本地 shell 工具调用的输出。
id: string
模型生成的本地 shell 工具调用的唯一 ID。
output: string
本地 shell 工具调用输出的 JSON 字符串。
type: "local_shell_call_output"
类型,固定为 local_shell_call_output。
"local_shell_call_output"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
status: optional "in_progress" or "completed" or "incomplete" or null
条目状态,可选 in_progress、completed 或 incomplete。
"in_progress"
"completed"
"incomplete"
ShellCall object { id, action, call_id, 6 more }
在托管环境中执行一个或多个 shell 命令的工具调用。
id: string
shell 工具调用的唯一 ID,通过 API 返回此条目时填充。
action: object { commands, max_output_length, timeout_ms }
描述如何运行工具调用的 shell 命令及限制。
commands: array of string
max_output_length: integer or null
可选的每个命令返回的最大字符数。
timeout_ms: integer or null
可选的命令超时时长,单位为毫秒。
call_id: string
模型生成的 shell 工具调用的唯一 ID。
environment: BetaResponseLocalEnvironment or BetaResponseContainerReference or null
表示使用本地环境执行 shell 操作。
BetaResponseLocalEnvironment object { type }
表示使用本地环境执行 shell 操作。
type: "local" (default: "local")
环境类型,固定为 local。
"local"
BetaResponseContainerReference object { container_id, type }
表示通过 /v1/containers 创建的容器。
container_id: string
type: "container_reference" (default: "container_reference")
环境类型,固定为 container_reference。
"container_reference"
status: "in_progress" or "completed" or "incomplete"
shell 调用状态,可选 in_progress、completed 或 incomplete。
"in_progress"
"completed"
"incomplete"
type: "shell_call" (default: "shell_call")
类型,固定为 shell_call。
"shell_call"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建此工具调用的实体的 ID。
ShellCallOutput object { id, call_id, max_output_length, 6 more }
shell 工具调用发出的输出。
id: string
shell 调用输出的唯一 ID,通过 API 返回此条目时填充。
call_id: string
模型生成的 shell 工具调用的唯一 ID。
max_output_length: integer or null
shell 命令输出的最大长度,由模型生成,应与原始输出一并回传。
output: array of object { outcome, stderr, stdout, created_by }
shell 调用输出内容的数组。
outcome: Timeout { type } or Exit { exit_code, type }
表示 shell 调用输出块的退出结果(包含退出码)或超时结果。
Timeout object { type }
表示 shell 调用超过其配置的时间限制。
type: "timeout" (default: "timeout")
结果类型,固定为 timeout。
"timeout"
Exit object { exit_code, type }
表示 shell 命令已结束,并返回退出码。
exit_code: integer
shell 进程的退出码。
type: "exit" (default: "exit")
结果类型,固定为 exit。
"exit"
stderr: string
捕获的标准错误输出。
stdout: string
捕获的标准输出。
created_by: optional string
创建该条目的执行主体的标识。
status: "in_progress" or "completed" or "incomplete"
shell 调用输出的状态,可选 in_progress、completed 或 incomplete。
"in_progress"
"completed"
"incomplete"
type: "shell_call_output" (default: "shell_call_output")
shell 调用输出的类型,固定为 shell_call_output。
"shell_call_output"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建该条目的执行主体的标识。
ApplyPatchCall object { id, call_id, operation, 5 more }
通过创建、删除或更新文件来应用文件差异的工具调用。
id: string
apply_patch 工具调用的唯一 ID,通过 API 返回此条目时填充。
call_id: string
模型生成的 apply_patch 工具调用的唯一 ID。
operation: CreateFile { diff, path, type } or DeleteFile { path, type } or UpdateFile { diff, path, type }
通过 apply_patch 应用的 create_file、delete_file 或 update_file 操作之一。
CreateFile object { diff, path, type }
描述如何通过 apply_patch 工具创建文件的指令。
diff: string
要应用的差异。
path: string
要创建的文件路径。
type: "create_file" (default: "create_file")
使用提供的差异创建新文件。
"create_file"
DeleteFile object { path, type }
描述如何通过 apply_patch 工具删除文件的指令。
path: string
要删除的文件路径。
type: "delete_file" (default: "delete_file")
删除指定文件。
"delete_file"
UpdateFile object { diff, path, type }
描述如何通过 apply_patch 工具更新文件的指令。
diff: string
要应用的差异。
path: string
要更新的文件路径。
type: "update_file" (default: "update_file")
使用提供的差异更新已有文件。
"update_file"
status: "in_progress" or "completed"
apply_patch 工具调用状态,可选 in_progress 或 completed。
"in_progress"
"completed"
type: "apply_patch_call" (default: "apply_patch_call")
类型,固定为 apply_patch_call。
"apply_patch_call"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建此工具调用的实体的 ID。
ApplyPatchCallOutput object { id, call_id, status, 5 more }
apply_patch 工具调用发出的输出。
id: string
apply_patch 工具调用输出的唯一 ID,通过 API 返回此条目时填充。
call_id: string
模型生成的 apply_patch 工具调用的唯一 ID。
status: "completed" or "failed"
apply_patch 工具调用输出的状态,可选 completed 或 failed。
"completed"
"failed"
type: "apply_patch_call_output" (default: "apply_patch_call_output")
类型,固定为 apply_patch_call_output。
"apply_patch_call_output"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建此工具调用输出的实体的 ID。
output: optional string or null
apply_patch 工具返回的可选文本输出。
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"
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
决定的可选理由。
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 { id, call_id, output, 5 more }
id: string
自定义工具调用输出条目的唯一 ID。
call_id: string
调用 ID,用于将此自定义工具调用输出映射到自定义工具调用。
output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
你的代码生成的自定义工具输出,可为字符串或输出内容列表。
StringOutput = string
自定义工具调用输出的字符串。
OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
自定义工具调用的文本、图像或文件输出。
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
status: "in_progress" or "completed" or "incomplete"
条目状态,可选 in_progress、completed 或 incomplete,通过 API 返回条目时填充。
"in_progress"
"completed"
"incomplete"
type: "custom_tool_call_output"
类型,固定为 custom_tool_call_output。
"custom_tool_call_output"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
调用方类型,固定为 direct。
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
minLength: 1, maxLength: 64
type: "program" (default: "program")
调用方类型,固定为 program。
"program"
created_by: optional string
创建该条目的执行主体的标识。
output_index: integer
新增输出条目的索引。
sequence_number: integer
事件序列号。
type: "response.output_item.added"
类型,固定为response.output_item.added。
"response.output_item.added"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.output_item.added",
"output_index": 0,
"item": {
"id": "msg_123",
"status": "in_progress",
"type": "message",
"role": "assistant",
"content": []
},
"sequence_number": 1
}
response.output_item.done
输出条目标记为完成时发出。
结构定义
结构名称: BetaResponseOutputItemDoneEvent
item: BetaResponseOutputItem
标记为完成的输出条目。
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
从文件中检索出的文本。
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 { id, output, status, 7 more }
id: string
函数调用工具输出的唯一 ID。
output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
你的代码产生的函数调用输出,可为字符串或输出内容列表。
StringOutput = string
函数调用输出的字符串。
OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
函数调用的文本、图像或文件输出。
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
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"
status: "in_progress" or "completed" or "incomplete"
条目状态,可选 in_progress、completed 或 incomplete,通过 API 返回条目时填充。
"in_progress"
"completed"
"incomplete"
type: "function_call_output"
类型,固定为 function_call_output。
"function_call_output"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
call_id: optional string
模型生成的函数工具调用的唯一 ID。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
调用方类型,固定为 direct。
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
minLength: 1, maxLength: 64
type: "program" (default: "program")
调用方类型,固定为 program。
"program"
created_by: optional string
创建该条目的执行主体的标识。
name: optional string
产生输出的工具名称。
namespace: optional string
产生输出的工具所属命名空间。
AgentMessage object { id, author, content, 3 more }
id: string
此智能体消息的唯一 ID。
author: string
发送方智能体的标识。
content: array of BetaResponseInputText or BetaResponseOutputText or Text { text, type } or 7 more
智能体之间发送的加密内容。
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
BetaResponseOutputText object { annotations, logprobs, text, type }
模型输出的文本。
Text object { text, type }
文本内容。
text: string
type: "text" (default: "text")
"text"
SummaryText object { text, type }
模型生成的摘要文本。
text: string
模型到目前为止生成的推理输出摘要。
type: "summary_text" (default: "summary_text")
类型,固定为 summary_text。
"summary_text"
ReasoningText object { text, type }
模型生成的推理文本。
text: string
模型生成的推理文本。
type: "reasoning_text" (default: "reasoning_text")
类型,固定为 reasoning_text。
"reasoning_text"
BetaResponseOutputRefusal object { refusal, type }
模型的拒绝响应。
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
ComputerScreenshot object { detail, file_id, image_url, 2 more }
计算机屏幕截图。
detail: BetaImageDetail
发送给模型的截图图像的细节级别,可选 high、low、auto 或 original,默认为 auto。
file_id: string or null
包含截图的已上传文件的标识。
image_url: string or null
截图图像的 URL。
format: uri
type: "computer_screenshot" (default: "computer_screenshot")
指定事件类型。对于计算机屏幕截图,此属性固定为 computer_screenshot。
"computer_screenshot"
prompt_cache_breakpoint: optional object { mode, ttl }
标记可复用提示词前缀的精确结束位置。省略 ttl 时,断点继承请求中的 prompt_cache_options.ttl;该边界不会按词元块取整。
mode: "explicit" (default: "explicit")
断点模式,固定为 explicit。
"explicit"
ttl: optional "30m" or "12h"
此缓存断点的最短存续时间,默认为请求的 TTL。
"30m"
"12h"
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
EncryptedContent object { encrypted_content, type }
不透明的加密内容,由 Responses API 在受信任的模型执行环境中解密。
encrypted_content: string
不透明的加密内容。
type: "encrypted_content" (default: "encrypted_content")
输入条目的类型,固定为 encrypted_content。
"encrypted_content"
recipient: string
接收方智能体的标识。
type: "agent_message" (default: "agent_message")
条目类型,固定为 agent_message。
"agent_message"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
MultiAgentCall object { id, action, arguments, 3 more }
id: string
该多智能体调用条目的唯一 ID。
action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more
要执行的多智能体操作。
"spawn_agent"
"interrupt_agent"
"list_agents"
"send_message"
"followup_task"
"wait_agent"
arguments: string
为该操作生成的参数,格式为 JSON 字符串。
call_id: string
关联调用与其输出的唯一 ID。
type: "multi_agent_call" (default: "multi_agent_call")
多智能体调用的类型,固定为 multi_agent_call。
"multi_agent_call"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
MultiAgentCallOutput object { id, action, call_id, 3 more }
id: string
此多智能体调用输出条目的唯一 ID。
action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more
生成此结果的多智能体操作。
"spawn_agent"
"interrupt_agent"
"list_agents"
"send_message"
"followup_task"
"wait_agent"
call_id: string
此多智能体调用的唯一 ID。
output: array of BetaResponseOutputText
多智能体操作返回的文本。
annotations: array of FileCitation { file_id, filename, index, type } or URLCitation { end_index, start_index, title, 2 more } or ContainerFileCitation { container_id, end_index, file_id, 3 more } or FilePath { file_id, index, type }
文本输出的注解。
logprobs: array of object { token, bytes, logprob, top_logprobs }
text: string
模型输出的文本内容。
type: "output_text" (default: "output_text")
输出文本类型,固定为 output_text。
type: "multi_agent_call_output" (default: "multi_agent_call_output")
多智能体结果的类型,固定为 multi_agent_call_output。
"multi_agent_call_output"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
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
生成该条目的智能体的规范名称。
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"
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
生成该条目的智能体的规范名称。
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
生成该条目的智能体的规范名称。
Compaction object { id, encrypted_content, type, 2 more }
v1/responses/compact API生成的压缩条目。
id: string
压缩条目的唯一 ID。
encrypted_content: string
压缩生成的加密内容。
type: "compaction" (default: "compaction")
类型,固定为 compaction。
"compaction"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
created_by: optional string
创建该条目的执行主体的标识。
ImageGenerationCall object { id, result, status, 10 more }
模型发起的图像生成请求。
id: string
图像生成调用的唯一 ID。
result: string or null
Base64 编码的生成图像。
status: "in_progress" or "completed" or "generating" or "failed"
图像生成调用的状态。
"in_progress"
"completed"
"generating"
"failed"
type: "image_generation_call"
类型,固定为 image_generation_call。
"image_generation_call"
action: optional "generate" or "edit" or "auto" or null
用于图像生成的操作。
"generate"
"edit"
"auto"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
background: optional "transparent" or "opaque" or "auto" or null
生成图像使用的背景设置。
"transparent"
"opaque"
"auto"
error: optional object { code, message, param, 2 more }
审核失败的详情,如可用。
code: string or null
错误代码。
message: string
错误描述。
param: string or null
关联的请求参数。
type: string
错误类型。
moderation_details: optional object { categories, moderation_stage }
moderation_blocked 错误的公开详情,如可用。
categories: array of string
公开的审核类别,未来可能增加新的类别值。
moderation_stage: "input" or "output" or "unknown"
审核阻止图像生成调用的阶段。
"input"
"output"
"unknown"
output_format: optional "png" or "webp" or "jpeg" or 2 more or null
生成图像使用的输出格式。
"png"
"webp"
"jpeg"
"gif"
"svg"
quality: optional "low" or "medium" or "high" or 3 more or null
图像生成工具调用生成的图像质量,可选 low、medium、high、xhigh、max 或 auto。
"low"
"medium"
"high"
"xhigh"
"max"
"auto"
revised_prompt: optional string or null
模型改写提示词后实际使用的提示词。
size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or null
图像尺寸,采用 WIDTHxHEIGHT 字符串形式,例如 1536x864。
string
"1024x1024" or "1024x1536" or "1536x1024"
图像尺寸,采用 WIDTHxHEIGHT 字符串形式,例如 1536x864。
"1024x1024"
"1024x1536"
"1536x1024"
svg_usage: optional object { input_tokens, model, output_tokens, 2 more }
input_tokens: integer
model: string
output_tokens: integer
reasoning_tokens: integer
total_tokens: integer
CodeInterpreterCall object { id, code, container_id, 4 more }
运行代码的工具调用。
id: string
代码解释器工具调用的唯一 ID。
code: string or null
要运行的代码,不可用时为 null。
container_id: string
运行代码使用的容器 ID。
outputs: array of Logs { logs, type } or Image { type, url } or null
代码解释器产生的日志、图像等输出;没有可用输出时可为null。
Logs object { logs, type }
代码解释器的日志输出。
logs: string
代码解释器的日志输出。
type: "logs" (default: "logs")
类型,固定为 logs。
"logs"
Image object { type, url }
代码解释器的图像输出。
type: "image" (default: "image")
类型,固定为 image。
"image"
url: string
代码解释器输出图像的 URL。
format: uri
status: "in_progress" or "completed" or "incomplete" or 2 more
代码解释器工具调用的状态,有效值为 in_progress、completed、incomplete、interpreting 和 failed。
"in_progress"
"completed"
"incomplete"
"interpreting"
"failed"
type: "code_interpreter_call" (default: "code_interpreter_call")
类型,固定为 code_interpreter_call。
"code_interpreter_call"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
LocalShellCall object { id, action, call_id, 3 more }
在本地 shell 上运行命令的工具调用。
id: string
本地 shell 调用的唯一 ID。
action: object { command, env, type, 3 more }
在服务器上执行 shell 命令。
command: array of string
要运行的命令。
env: map[string]
要为命令设置的环境变量。
type: "exec" (default: "exec")
类型,固定为 exec。
"exec"
timeout_ms: optional integer or null
可选的命令超时时长,单位为毫秒。
user: optional string or null
可选的运行命令的用户。
working_directory: optional string or null
可选的运行命令的工作目录。
call_id: string
模型生成的本地 shell 工具调用的唯一 ID。
status: "in_progress" or "completed" or "incomplete"
本地 shell 调用的状态。
"in_progress"
"completed"
"incomplete"
type: "local_shell_call"
类型,固定为 local_shell_call。
"local_shell_call"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
LocalShellCallOutput object { id, output, type, 2 more }
本地 shell 工具调用的输出。
id: string
模型生成的本地 shell 工具调用的唯一 ID。
output: string
本地 shell 工具调用输出的 JSON 字符串。
type: "local_shell_call_output"
类型,固定为 local_shell_call_output。
"local_shell_call_output"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
status: optional "in_progress" or "completed" or "incomplete" or null
条目状态,可选 in_progress、completed 或 incomplete。
"in_progress"
"completed"
"incomplete"
ShellCall object { id, action, call_id, 6 more }
在托管环境中执行一个或多个 shell 命令的工具调用。
id: string
shell 工具调用的唯一 ID,通过 API 返回此条目时填充。
action: object { commands, max_output_length, timeout_ms }
描述如何运行工具调用的 shell 命令及限制。
commands: array of string
max_output_length: integer or null
可选的每个命令返回的最大字符数。
timeout_ms: integer or null
可选的命令超时时长,单位为毫秒。
call_id: string
模型生成的 shell 工具调用的唯一 ID。
environment: BetaResponseLocalEnvironment or BetaResponseContainerReference or null
表示使用本地环境执行 shell 操作。
BetaResponseLocalEnvironment object { type }
表示使用本地环境执行 shell 操作。
type: "local" (default: "local")
环境类型,固定为 local。
"local"
BetaResponseContainerReference object { container_id, type }
表示通过 /v1/containers 创建的容器。
container_id: string
type: "container_reference" (default: "container_reference")
环境类型,固定为 container_reference。
"container_reference"
status: "in_progress" or "completed" or "incomplete"
shell 调用状态,可选 in_progress、completed 或 incomplete。
"in_progress"
"completed"
"incomplete"
type: "shell_call" (default: "shell_call")
类型,固定为 shell_call。
"shell_call"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建此工具调用的实体的 ID。
ShellCallOutput object { id, call_id, max_output_length, 6 more }
shell 工具调用发出的输出。
id: string
shell 调用输出的唯一 ID,通过 API 返回此条目时填充。
call_id: string
模型生成的 shell 工具调用的唯一 ID。
max_output_length: integer or null
shell 命令输出的最大长度,由模型生成,应与原始输出一并回传。
output: array of object { outcome, stderr, stdout, created_by }
shell 调用输出内容的数组。
outcome: Timeout { type } or Exit { exit_code, type }
表示 shell 调用输出块的退出结果(包含退出码)或超时结果。
Timeout object { type }
表示 shell 调用超过其配置的时间限制。
type: "timeout" (default: "timeout")
结果类型,固定为 timeout。
"timeout"
Exit object { exit_code, type }
表示 shell 命令已结束,并返回退出码。
exit_code: integer
shell 进程的退出码。
type: "exit" (default: "exit")
结果类型,固定为 exit。
"exit"
stderr: string
捕获的标准错误输出。
stdout: string
捕获的标准输出。
created_by: optional string
创建该条目的执行主体的标识。
status: "in_progress" or "completed" or "incomplete"
shell 调用输出的状态,可选 in_progress、completed 或 incomplete。
"in_progress"
"completed"
"incomplete"
type: "shell_call_output" (default: "shell_call_output")
shell 调用输出的类型,固定为 shell_call_output。
"shell_call_output"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建该条目的执行主体的标识。
ApplyPatchCall object { id, call_id, operation, 5 more }
通过创建、删除或更新文件来应用文件差异的工具调用。
id: string
apply_patch 工具调用的唯一 ID,通过 API 返回此条目时填充。
call_id: string
模型生成的 apply_patch 工具调用的唯一 ID。
operation: CreateFile { diff, path, type } or DeleteFile { path, type } or UpdateFile { diff, path, type }
通过 apply_patch 应用的 create_file、delete_file 或 update_file 操作之一。
CreateFile object { diff, path, type }
描述如何通过 apply_patch 工具创建文件的指令。
diff: string
要应用的差异。
path: string
要创建的文件路径。
type: "create_file" (default: "create_file")
使用提供的差异创建新文件。
"create_file"
DeleteFile object { path, type }
描述如何通过 apply_patch 工具删除文件的指令。
path: string
要删除的文件路径。
type: "delete_file" (default: "delete_file")
删除指定文件。
"delete_file"
UpdateFile object { diff, path, type }
描述如何通过 apply_patch 工具更新文件的指令。
diff: string
要应用的差异。
path: string
要更新的文件路径。
type: "update_file" (default: "update_file")
使用提供的差异更新已有文件。
"update_file"
status: "in_progress" or "completed"
apply_patch 工具调用状态,可选 in_progress 或 completed。
"in_progress"
"completed"
type: "apply_patch_call" (default: "apply_patch_call")
类型,固定为 apply_patch_call。
"apply_patch_call"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建此工具调用的实体的 ID。
ApplyPatchCallOutput object { id, call_id, status, 5 more }
apply_patch 工具调用发出的输出。
id: string
apply_patch 工具调用输出的唯一 ID,通过 API 返回此条目时填充。
call_id: string
模型生成的 apply_patch 工具调用的唯一 ID。
status: "completed" or "failed"
apply_patch 工具调用输出的状态,可选 completed 或 failed。
"completed"
"failed"
type: "apply_patch_call_output" (default: "apply_patch_call_output")
类型,固定为 apply_patch_call_output。
"apply_patch_call_output"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建此工具调用输出的实体的 ID。
output: optional string or null
apply_patch 工具返回的可选文本输出。
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"
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
决定的可选理由。
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 { id, call_id, output, 5 more }
id: string
自定义工具调用输出条目的唯一 ID。
call_id: string
调用 ID,用于将此自定义工具调用输出映射到自定义工具调用。
output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
你的代码生成的自定义工具输出,可为字符串或输出内容列表。
StringOutput = string
自定义工具调用输出的字符串。
OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
自定义工具调用的文本、图像或文件输出。
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
status: "in_progress" or "completed" or "incomplete"
条目状态,可选 in_progress、completed 或 incomplete,通过 API 返回条目时填充。
"in_progress"
"completed"
"incomplete"
type: "custom_tool_call_output"
类型,固定为 custom_tool_call_output。
"custom_tool_call_output"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
调用方类型,固定为 direct。
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
minLength: 1, maxLength: 64
type: "program" (default: "program")
调用方类型,固定为 program。
"program"
created_by: optional string
创建该条目的执行主体的标识。
output_index: integer
标记为完成的输出条目索引。
sequence_number: integer
事件序列号。
type: "response.output_item.done"
类型,固定为response.output_item.done。
"response.output_item.done"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
例中文字:繁星下闪烁的森林里,孤独的独角兽Lila发现了一片泛着月光的小池塘。她每晚在岸边留下闪耀的魔法花朵,希望与他人分享美丽。某个迷人的夜晚,她醒来发现友善的小动物聚在身旁,渴望与她成为朋友、共享魔法。
{
"type": "response.output_item.done",
"output_index": 0,
"item": {
"id": "msg_123",
"status": "completed",
"type": "message",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "In a shimmering forest under a sky full of stars, a lonely unicorn named Lila discovered a hidden pond that glowed with moonlight. Every night, she would leave sparkling, magical flowers by the water's edge, hoping to share her beauty with others. One enchanting evening, she woke to find a group of friendly animals gathered around, eager to be friends and share in her magic.",
"annotations": [],
"logprobs": []
}
]
},
"sequence_number": 1
}
response.content_part.added
添加新内容部分时发出。
结构定义
结构名称: BetaResponseContentPartAddedEvent
content_index: integer
新增内容部分的索引。
item_id: string
新增内容部分所属的输出条目ID。
output_index: integer
新增内容部分所属的输出条目索引。
part: BetaResponseOutputText or BetaResponseOutputRefusal or ReasoningText { text, type }
添加的内容部分。
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"
ReasoningText object { text, type }
模型生成的推理文本。
text: string
模型生成的推理文本。
type: "reasoning_text" (default: "reasoning_text")
类型,固定为 reasoning_text。
"reasoning_text"
sequence_number: integer
事件序列号。
type: "response.content_part.added"
类型,固定为response.content_part.added。
"response.content_part.added"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.content_part.added",
"item_id": "msg_123",
"output_index": 0,
"content_index": 0,
"part": {
"type": "output_text",
"text": "",
"annotations": [],
"logprobs": []
},
"sequence_number": 1
}
response.content_part.done
内容部分完成时发出。
结构定义
结构名称: BetaResponseContentPartDoneEvent
content_index: integer
已完成内容部分的索引。
item_id: string
新增内容部分所属的输出条目ID。
output_index: integer
新增内容部分所属的输出条目索引。
part: BetaResponseOutputText or BetaResponseOutputRefusal or ReasoningText { text, type }
已完成的内容部分。
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"
ReasoningText object { text, type }
模型生成的推理文本。
text: string
模型生成的推理文本。
type: "reasoning_text" (default: "reasoning_text")
类型,固定为 reasoning_text。
"reasoning_text"
sequence_number: integer
事件序列号。
type: "response.content_part.done"
类型,固定为response.content_part.done。
"response.content_part.done"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
例中文字:繁星下闪烁的森林里,孤独的独角兽Lila发现了一片泛着月光的小池塘。她每晚在岸边留下闪耀的魔法花朵,希望与他人分享美丽。某个迷人的夜晚,她醒来发现友善的小动物聚在身旁,渴望与她成为朋友、共享魔法。
{
"type": "response.content_part.done",
"item_id": "msg_123",
"output_index": 0,
"content_index": 0,
"sequence_number": 1,
"part": {
"type": "output_text",
"text": "In a shimmering forest under a sky full of stars, a lonely unicorn named Lila discovered a hidden pond that glowed with moonlight. Every night, she would leave sparkling, magical flowers by the water's edge, hoping to share her beauty with others. One enchanting evening, she woke to find a group of friendly animals gathered around, eager to be friends and share in her magic.",
"annotations": [],
"logprobs": []
}
}
response.output_text.delta
产生额外文本增量时发出。
结构定义
结构名称: BetaResponseTextDeltaEvent
content_index: integer
接收文本增量的内容部分索引。
delta: string
新增文本增量。
item_id: string
接收文本增量的输出条目ID。
logprobs: array of object { token, logprob, top_logprobs }
增量中各词元的对数概率。
token: string
可能出现的文本词元。
logprob: number
此词元的对数概率。
top_logprobs: optional array of object { token, logprob }
最多20个最可能词元的对数概率。
token: optional string
可能出现的文本词元。
logprob: optional number
此词元的对数概率。
output_index: integer
接收文本增量的输出条目索引。
sequence_number: integer
此事件的序列号。
type: "response.output_text.delta"
类型,固定为response.output_text.delta。
"response.output_text.delta"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.output_text.delta",
"item_id": "msg_123",
"output_index": 0,
"content_index": 0,
"delta": "In",
"sequence_number": 1,
"logprobs": []
}
response.output_text.done
文本内容确定后发出。
结构定义
结构名称: BetaResponseTextDoneEvent
content_index: integer
文本内容确定时对应的内容部分索引。
item_id: string
文本内容确定时对应的输出条目ID。
logprobs: array of object { token, logprob, top_logprobs }
增量中各词元的对数概率。
token: string
可能出现的文本词元。
logprob: number
此词元的对数概率。
top_logprobs: optional array of object { token, logprob }
最多20个最可能词元的对数概率。
token: optional string
可能出现的文本词元。
logprob: optional number
此词元的对数概率。
output_index: integer
文本内容确定时对应的输出条目索引。
sequence_number: integer
此事件的序列号。
text: string
已确定的文本内容。
type: "response.output_text.done"
类型,固定为response.output_text.done。
"response.output_text.done"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
例中文字:繁星下闪烁的森林里,孤独的独角兽Lila发现了一片泛着月光的小池塘。她每晚在岸边留下闪耀的魔法花朵,希望与他人分享美丽。某个迷人的夜晚,她醒来发现友善的小动物聚在身旁,渴望与她成为朋友、共享魔法。
{
"type": "response.output_text.done",
"item_id": "msg_123",
"output_index": 0,
"content_index": 0,
"text": "In a shimmering forest under a sky full of stars, a lonely unicorn named Lila discovered a hidden pond that glowed with moonlight. Every night, she would leave sparkling, magical flowers by the water's edge, hoping to share her beauty with others. One enchanting evening, she woke to find a group of friendly animals gathered around, eager to be friends and share in her magic.",
"sequence_number": 1,
"logprobs": []
}
response.refusal.delta
产生部分拒绝文本时发出。
结构定义
结构名称: BetaResponseRefusalDeltaEvent
content_index: integer
接收新增拒绝文本的内容部分索引。
delta: string
新增的拒绝文本。
item_id: string
接收新增拒绝文本的输出条目ID。
output_index: integer
接收新增拒绝文本的输出条目索引。
sequence_number: integer
事件序列号。
type: "response.refusal.delta"
类型,固定为response.refusal.delta。
"response.refusal.delta"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
例中文字:截至当前的拒绝文本
{
"type": "response.refusal.delta",
"item_id": "msg_123",
"output_index": 0,
"content_index": 0,
"delta": "refusal text so far",
"sequence_number": 1
}
response.refusal.done
拒绝文本确定后发出。
结构定义
结构名称: BetaResponseRefusalDoneEvent
content_index: integer
拒绝文本确定时对应的内容部分索引。
item_id: string
拒绝文本确定时对应的输出条目ID。
output_index: integer
拒绝文本确定时对应的输出条目索引。
refusal: string
已确定的拒绝文本。
sequence_number: integer
事件序列号。
type: "response.refusal.done"
类型,固定为response.refusal.done。
"response.refusal.done"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
例中文字:最终拒绝文本
{
"type": "response.refusal.done",
"item_id": "item-abc",
"output_index": 1,
"content_index": 2,
"refusal": "final refusal text",
"sequence_number": 1
}
response.function_call_arguments.delta
函数调用参数产生部分增量时发出。
结构定义
结构名称: BetaResponseFunctionCallArgumentsDeltaEvent
delta: string
新增的函数调用参数增量。
item_id: string
接收函数调用参数增量的输出条目ID。
output_index: integer
接收函数调用参数增量的输出条目索引。
sequence_number: integer
事件序列号。
type: "response.function_call_arguments.delta"
类型,固定为response.function_call_arguments.delta。
"response.function_call_arguments.delta"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.function_call_arguments.delta",
"item_id": "item-abc",
"output_index": 0,
"delta": "{ \"arg\":",
"sequence_number": 1
}
response.function_call_arguments.done
函数调用参数确定后发出。
结构定义
结构名称: BetaResponseFunctionCallArgumentsDoneEvent
arguments: string
函数调用参数。
item_id: string
条目 ID。
output_index: integer
输出条目索引。
sequence_number: integer
事件序列号。
type: "response.function_call_arguments.done"
"response.function_call_arguments.done"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.function_call_arguments.done",
"item_id": "item-abc",
"output_index": 1,
"arguments": "{ \"arg\": 123 }",
"sequence_number": 1
}
response.file_search_call.in_progress
发起文件搜索调用时发出。
结构定义
结构名称: BetaResponseFileSearchCallInProgressEvent
item_id: string
发起文件搜索调用的输出条目ID。
output_index: integer
发起文件搜索调用的输出条目索引。
sequence_number: integer
事件序列号。
type: "response.file_search_call.in_progress"
类型,固定为response.file_search_call.in_progress。
"response.file_search_call.in_progress"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.file_search_call.in_progress",
"output_index": 0,
"item_id": "fs_123",
"sequence_number": 1
}
response.file_search_call.searching
文件搜索正在搜索时发出。
结构定义
结构名称: BetaResponseFileSearchCallSearchingEvent
item_id: string
发起文件搜索调用的输出条目ID。
output_index: integer
正在执行文件搜索的输出条目索引。
sequence_number: integer
事件序列号。
type: "response.file_search_call.searching"
类型,固定为response.file_search_call.searching。
"response.file_search_call.searching"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.file_search_call.searching",
"output_index": 0,
"item_id": "fs_123",
"sequence_number": 1
}
response.file_search_call.completed
文件搜索调用完成、已找到结果时发出。
结构定义
结构名称: BetaResponseFileSearchCallCompletedEvent
item_id: string
发起文件搜索调用的输出条目ID。
output_index: integer
发起文件搜索调用的输出条目索引。
sequence_number: integer
事件序列号。
type: "response.file_search_call.completed"
类型,固定为response.file_search_call.completed。
"response.file_search_call.completed"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.file_search_call.completed",
"output_index": 0,
"item_id": "fs_123",
"sequence_number": 1
}
response.web_search_call.in_progress
发起网页搜索调用时发出。
结构定义
结构名称: BetaResponseWebSearchCallInProgressEvent
item_id: string
与网页搜索调用关联的输出条目唯一ID。
output_index: integer
与网页搜索调用关联的输出条目索引。
sequence_number: integer
正在处理的网页搜索调用序列号。
type: "response.web_search_call.in_progress"
类型,固定为response.web_search_call.in_progress。
"response.web_search_call.in_progress"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.web_search_call.in_progress",
"output_index": 0,
"item_id": "ws_123",
"sequence_number": 0
}
response.web_search_call.searching
网页搜索调用正在执行时发出。
结构定义
结构名称: BetaResponseWebSearchCallSearchingEvent
item_id: string
与网页搜索调用关联的输出条目唯一ID。
output_index: integer
与网页搜索调用关联的输出条目索引。
sequence_number: integer
正在处理的网页搜索调用序列号。
type: "response.web_search_call.searching"
类型,固定为response.web_search_call.searching。
"response.web_search_call.searching"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.web_search_call.searching",
"output_index": 0,
"item_id": "ws_123",
"sequence_number": 0
}
response.web_search_call.completed
网页搜索调用完成时发出。
结构定义
结构名称: BetaResponseWebSearchCallCompletedEvent
item_id: string
与网页搜索调用关联的输出条目唯一ID。
output_index: integer
与网页搜索调用关联的输出条目索引。
sequence_number: integer
正在处理的网页搜索调用序列号。
type: "response.web_search_call.completed"
类型,固定为response.web_search_call.completed。
"response.web_search_call.completed"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.web_search_call.completed",
"output_index": 0,
"item_id": "ws_123",
"sequence_number": 0
}
response.reasoning_summary_part.added
添加新的推理摘要部分时发出。
结构定义
结构名称: BetaResponseReasoningSummaryPartAddedEvent
item_id: string
此摘要部分关联的条目ID。
output_index: integer
此摘要部分关联的输出条目索引。
part: object { text, type }
新增摘要部分。
text: string
摘要部分的文本。
type: "summary_text"
类型,固定为summary_text。
"summary_text"
sequence_number: integer
事件序列号。
summary_index: integer
摘要部分在推理摘要中的索引。
type: "response.reasoning_summary_part.added"
类型,固定为response.reasoning_summary_part.added。
"response.reasoning_summary_part.added"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.reasoning_summary_part.added",
"item_id": "rs_6806bfca0b2481918a5748308061a2600d3ce51bdffd5476",
"output_index": 0,
"summary_index": 0,
"part": {
"type": "summary_text",
"text": ""
},
"sequence_number": 1
}
response.reasoning_summary_part.done
推理摘要部分完成时发出。
结构定义
结构名称: BetaResponseReasoningSummaryPartDoneEvent
item_id: string
此摘要部分关联的条目ID。
output_index: integer
此摘要部分关联的输出条目索引。
part: object { text, type }
已完成的摘要部分。
text: string
摘要部分的文本。
type: "summary_text"
类型,固定为summary_text。
"summary_text"
sequence_number: integer
事件序列号。
summary_index: integer
摘要部分在推理摘要中的索引。
type: "response.reasoning_summary_part.done"
类型,固定为response.reasoning_summary_part.done。
"response.reasoning_summary_part.done"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
status: optional "incomplete"
摘要部分的完成状态。正常完成时省略;生成被中断时为incomplete。
"incomplete"
示例
例中文字:回应问候:用户刚刚说了“你好!”,看来我需要接话。既然用户想聊天,我会回以问候,并表示愿意提供帮助。我可以这样说:“你好!今天有什么可以帮你?”这样的回应显得友好而开放。用户没有提出具体问题,因此这种方式很适合开启对话。接下来看看对话会如何发展!
{
"type": "response.reasoning_summary_part.done",
"item_id": "rs_6806bfca0b2481918a5748308061a2600d3ce51bdffd5476",
"output_index": 0,
"summary_index": 0,
"part": {
"type": "summary_text",
"text": "**Responding to a greeting**\n\nThe user just said, \"Hello!\" So, it seems I need to engage. I'll greet them back and offer help since they're looking to chat. I could say something like, \"Hello! How can I assist you today?\" That feels friendly and open. They didn't ask a specific question, so this approach will work well for starting a conversation. Let's see where it goes from there!"
},
"sequence_number": 1
}
response.reasoning_summary_text.delta
向推理摘要文本添加增量时发出。
结构定义
结构名称: BetaResponseReasoningSummaryTextDeltaEvent
delta: string
新增到摘要的文本增量。
item_id: string
此摘要文本增量关联的条目ID。
output_index: integer
此摘要文本增量关联的输出条目索引。
sequence_number: integer
事件序列号。
summary_index: integer
摘要部分在推理摘要中的索引。
type: "response.reasoning_summary_text.delta"
类型,固定为response.reasoning_summary_text.delta。
"response.reasoning_summary_text.delta"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
例中文字:回应问候:用户刚刚说了“你好!”,看来我需要接话。既然用户想聊天,我会回以问候,并表示愿意提供帮助。我可以这样说:“你好!今天有什么可以帮你?”这样的回应显得友好而开放。用户没有提出具体问题,因此这种方式很适合开启对话。接下来看看对话会如何发展!
{
"type": "response.reasoning_summary_text.delta",
"item_id": "rs_6806bfca0b2481918a5748308061a2600d3ce51bdffd5476",
"output_index": 0,
"summary_index": 0,
"delta": "**Responding to a greeting**\n\nThe user just said, \"Hello!\" So, it seems I need to engage. I'll greet them back and offer help since they're looking to chat. I could say something like, \"Hello! How can I assist you today?\" That feels friendly and open. They didn't ask a specific question, so this approach will work well for starting a conversation. Let's see where it goes from there!",
"sequence_number": 1
}
response.reasoning_summary_text.done
推理摘要文本完成时发出。
结构定义
结构名称: BetaResponseReasoningSummaryTextDoneEvent
item_id: string
此摘要文本关联的条目ID。
output_index: integer
此摘要文本关联的输出条目索引。
sequence_number: integer
事件序列号。
summary_index: integer
摘要部分在推理摘要中的索引。
text: string
已完成推理摘要的完整文本。
type: "response.reasoning_summary_text.done"
类型,固定为response.reasoning_summary_text.done。
"response.reasoning_summary_text.done"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
例中文字:回应问候:用户刚刚说了“你好!”,看来我需要接话。既然用户想聊天,我会回以问候,并表示愿意提供帮助。我可以这样说:“你好!今天有什么可以帮你?”这样的回应显得友好而开放。用户没有提出具体问题,因此这种方式很适合开启对话。接下来看看对话会如何发展!
{
"type": "response.reasoning_summary_text.done",
"item_id": "rs_6806bfca0b2481918a5748308061a2600d3ce51bdffd5476",
"output_index": 0,
"summary_index": 0,
"text": "**Responding to a greeting**\n\nThe user just said, \"Hello!\" So, it seems I need to engage. I'll greet them back and offer help since they're looking to chat. I could say something like, \"Hello! How can I assist you today?\" That feels friendly and open. They didn't ask a specific question, so this approach will work well for starting a conversation. Let's see where it goes from there!",
"sequence_number": 1
}
response.reasoning_text.delta
向推理文本添加增量时发出。
结构定义
结构名称: BetaResponseReasoningTextDeltaEvent
content_index: integer
此增量关联的推理内容部分索引。
delta: string
新增到推理内容的文本增量。
item_id: string
此推理文本增量关联的条目ID。
output_index: integer
此推理文本增量关联的输出条目索引。
sequence_number: integer
事件序列号。
type: "response.reasoning_text.delta"
类型,固定为response.reasoning_text.delta。
"response.reasoning_text.delta"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.reasoning_text.delta",
"item_id": "rs_123",
"output_index": 0,
"content_index": 0,
"delta": "The",
"sequence_number": 1
}
response.reasoning_text.done
推理文本完成时发出。
结构定义
结构名称: BetaResponseReasoningTextDoneEvent
content_index: integer
推理内容部分的索引。
item_id: string
此推理文本关联的条目ID。
output_index: integer
此推理文本关联的输出条目索引。
sequence_number: integer
事件序列号。
text: string
已完成推理内容的完整文本。
type: "response.reasoning_text.done"
类型,固定为response.reasoning_text.done。
"response.reasoning_text.done"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
例中文字:用户正在询问……
{
"type": "response.reasoning_text.done",
"item_id": "rs_123",
"output_index": 0,
"content_index": 0,
"text": "The user is asking...",
"sequence_number": 4
}
response.image_generation_call.completed
图像生成工具调用完成、最终图像可用时发出。
结构定义
结构名称: BetaResponseImageGenCallCompletedEvent
item_id: string
正在处理的图像生成条目的唯一标识。
output_index: integer
输出条目在响应output数组中的索引。
sequence_number: integer
事件序列号。
type: "response.image_generation_call.completed"
类型,固定为response.image_generation_call.completed。
"response.image_generation_call.completed"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.image_generation_call.completed",
"output_index": 0,
"item_id": "item-123",
"sequence_number": 1
}
response.image_generation_call.generating
图像生成工具正在生成图像的中间阶段发出。
结构定义
结构名称: BetaResponseImageGenCallGeneratingEvent
item_id: string
正在处理的图像生成条目的唯一标识。
output_index: integer
输出条目在响应output数组中的索引。
sequence_number: integer
正在处理的图像生成条目的序列号。
type: "response.image_generation_call.generating"
类型,固定为response.image_generation_call.generating。
"response.image_generation_call.generating"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.image_generation_call.generating",
"output_index": 0,
"item_id": "item-123",
"sequence_number": 0
}
response.image_generation_call.in_progress
图像生成工具调用进行中时发出。
结构定义
结构名称: BetaResponseImageGenCallInProgressEvent
item_id: string
正在处理的图像生成条目的唯一标识。
output_index: integer
输出条目在响应output数组中的索引。
sequence_number: integer
正在处理的图像生成条目的序列号。
type: "response.image_generation_call.in_progress"
类型,固定为response.image_generation_call.in_progress。
"response.image_generation_call.in_progress"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.image_generation_call.in_progress",
"output_index": 0,
"item_id": "item-123",
"sequence_number": 0
}
response.image_generation_call.partial_image
图像生成流式传输期间,部分图像可用时发出。
结构定义
结构名称: BetaResponseImageGenCallPartialImageEvent
item_id: string
正在处理的图像生成条目的唯一标识。
output_index: integer
输出条目在响应output数组中的索引。
partial_image_b64: string
Base64 编码的部分图像数据,可用于渲染图像。
partial_image_index: integer
部分图像从0开始的索引;后端从1开始,但面向用户时从0开始。
sequence_number: integer
正在处理的图像生成条目的序列号。
type: "response.image_generation_call.partial_image"
类型,固定为response.image_generation_call.partial_image。
"response.image_generation_call.partial_image"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
background: optional string
实际使用的背景设置。
output_format: optional string
实际使用的输出格式。
quality: optional string
实际使用的图像质量。
size: optional string
实际使用的图像尺寸。
示例
{
"type": "response.image_generation_call.partial_image",
"output_index": 0,
"item_id": "item-123",
"sequence_number": 0,
"partial_image_index": 0,
"partial_image_b64": "..."
}
response.mcp_call_arguments.delta
MCP工具调用参数产生部分增量时发出。
结构定义
结构名称: BetaResponseMCPCallArgumentsDeltaEvent
delta: string
包含MCP工具调用参数部分更新的JSON字符串。
item_id: string
正在处理的MCP工具调用条目的唯一标识。
output_index: integer
输出条目在响应output数组中的索引。
sequence_number: integer
事件序列号。
type: "response.mcp_call_arguments.delta"
类型,固定为response.mcp_call_arguments.delta。
"response.mcp_call_arguments.delta"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.mcp_call_arguments.delta",
"output_index": 0,
"item_id": "item-abc",
"delta": "{",
"sequence_number": 1
}
response.mcp_call_arguments.done
MCP工具调用参数确定后发出。
结构定义
结构名称: BetaResponseMCPCallArgumentsDoneEvent
arguments: string
包含已确定MCP工具调用参数的JSON字符串。
item_id: string
正在处理的MCP工具调用条目的唯一标识。
output_index: integer
输出条目在响应output数组中的索引。
sequence_number: integer
事件序列号。
type: "response.mcp_call_arguments.done"
类型,固定为response.mcp_call_arguments.done。
"response.mcp_call_arguments.done"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.mcp_call_arguments.done",
"output_index": 0,
"item_id": "item-abc",
"arguments": "{\"arg1\": \"value1\", \"arg2\": \"value2\"}",
"sequence_number": 1
}
response.mcp_call.completed
MCP工具调用成功完成时发出。
结构定义
结构名称: BetaResponseMCPCallCompletedEvent
item_id: string
已完成MCP工具调用条目的ID。
output_index: integer
已完成输出条目的索引。
sequence_number: integer
事件序列号。
type: "response.mcp_call.completed"
类型,固定为response.mcp_call.completed。
"response.mcp_call.completed"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.mcp_call.completed",
"sequence_number": 1,
"item_id": "mcp_682d437d90a88191bf88cd03aae0c3e503937d5f622d7a90",
"output_index": 0
}
response.mcp_call.failed
MCP工具调用失败时发出。
结构定义
结构名称: BetaResponseMCPCallFailedEvent
item_id: string
失败的MCP工具调用条目ID。
output_index: integer
失败的输出条目索引。
sequence_number: integer
事件序列号。
type: "response.mcp_call.failed"
类型,固定为response.mcp_call.failed。
"response.mcp_call.failed"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.mcp_call.failed",
"sequence_number": 1,
"item_id": "mcp_682d437d90a88191bf88cd03aae0c3e503937d5f622d7a90",
"output_index": 0
}
response.mcp_call.in_progress
MCP工具调用进行中时发出。
结构定义
结构名称: BetaResponseMCPCallInProgressEvent
item_id: string
正在处理的MCP工具调用条目的唯一标识。
output_index: integer
输出条目在响应output数组中的索引。
sequence_number: integer
事件序列号。
type: "response.mcp_call.in_progress"
类型,固定为response.mcp_call.in_progress。
"response.mcp_call.in_progress"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.mcp_call.in_progress",
"sequence_number": 1,
"output_index": 0,
"item_id": "mcp_682d437d90a88191bf88cd03aae0c3e503937d5f622d7a90"
}
response.mcp_list_tools.completed
成功取得可用MCP工具列表时发出。
结构定义
结构名称: BetaResponseMCPListToolsCompletedEvent
item_id: string
产生此输出的MCP工具调用条目ID。
output_index: integer
已处理输出条目的索引。
sequence_number: integer
事件序列号。
type: "response.mcp_list_tools.completed"
类型,固定为response.mcp_list_tools.completed。
"response.mcp_list_tools.completed"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.mcp_list_tools.completed",
"sequence_number": 1,
"output_index": 0,
"item_id": "mcpl_682d4379df088191886b70f4ec39f90403937d5f622d7a90"
}
response.mcp_list_tools.failed
尝试列出可用MCP工具失败时发出。
结构定义
结构名称: BetaResponseMCPListToolsFailedEvent
item_id: string
失败的MCP工具调用条目ID。
output_index: integer
失败的输出条目索引。
sequence_number: integer
事件序列号。
type: "response.mcp_list_tools.failed"
类型,固定为response.mcp_list_tools.failed。
"response.mcp_list_tools.failed"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.mcp_list_tools.failed",
"sequence_number": 1,
"output_index": 0,
"item_id": "mcpl_682d4379df088191886b70f4ec39f90403937d5f622d7a90"
}
response.mcp_list_tools.in_progress
系统正在取得可用MCP工具列表时发出。
结构定义
结构名称: BetaResponseMCPListToolsInProgressEvent
item_id: string
正在处理的MCP工具调用条目ID。
output_index: integer
正在处理的输出条目索引。
sequence_number: integer
事件序列号。
type: "response.mcp_list_tools.in_progress"
类型,固定为response.mcp_list_tools.in_progress。
"response.mcp_list_tools.in_progress"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.mcp_list_tools.in_progress",
"sequence_number": 1,
"output_index": 0,
"item_id": "mcpl_682d4379df088191886b70f4ec39f90403937d5f622d7a90"
}
response.code_interpreter_call.in_progress
代码解释器调用进行中时发出。
结构定义
结构名称: BetaResponseCodeInterpreterCallInProgressEvent
item_id: string
代码解释器工具调用条目的唯一标识。
output_index: integer
响应中代码解释器调用正在进行的输出条目索引。
sequence_number: integer
此事件序列号,用于对流式事件排序。
type: "response.code_interpreter_call.in_progress"
类型,固定为response.code_interpreter_call.in_progress。
"response.code_interpreter_call.in_progress"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.code_interpreter_call.in_progress",
"output_index": 0,
"item_id": "ci_12345",
"sequence_number": 1
}
response.code_interpreter_call.interpreting
代码解释器正在解释代码片段时发出。
结构定义
结构名称: BetaResponseCodeInterpreterCallInterpretingEvent
item_id: string
代码解释器工具调用条目的唯一标识。
output_index: integer
响应中代码解释器正在解释代码的输出条目索引。
sequence_number: integer
此事件序列号,用于对流式事件排序。
type: "response.code_interpreter_call.interpreting"
类型,固定为response.code_interpreter_call.interpreting。
"response.code_interpreter_call.interpreting"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.code_interpreter_call.interpreting",
"output_index": 4,
"item_id": "ci_12345",
"sequence_number": 1
}
response.code_interpreter_call.completed
代码解释器调用完成时发出。
结构定义
结构名称: BetaResponseCodeInterpreterCallCompletedEvent
item_id: string
代码解释器工具调用条目的唯一标识。
output_index: integer
响应中代码解释器调用已完成的输出条目索引。
sequence_number: integer
此事件序列号,用于对流式事件排序。
type: "response.code_interpreter_call.completed"
类型,固定为response.code_interpreter_call.completed。
"response.code_interpreter_call.completed"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.code_interpreter_call.completed",
"output_index": 5,
"item_id": "ci_12345",
"sequence_number": 1
}
response.code_interpreter_call_code.delta
代码解释器流式输出部分代码时发出。
结构定义
结构名称: BetaResponseCodeInterpreterCallCodeDeltaEvent
delta: string
代码解释器正在流式输出的部分代码片段。
item_id: string
代码解释器工具调用条目的唯一标识。
output_index: integer
响应中正在流式输出代码的输出条目索引。
sequence_number: integer
此事件序列号,用于对流式事件排序。
type: "response.code_interpreter_call_code.delta"
类型,固定为response.code_interpreter_call_code.delta。
"response.code_interpreter_call_code.delta"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.code_interpreter_call_code.delta",
"output_index": 0,
"item_id": "ci_12345",
"delta": "print('Hello, world')",
"sequence_number": 1
}
response.code_interpreter_call_code.done
代码解释器确定最终代码片段时发出。
结构定义
结构名称: BetaResponseCodeInterpreterCallCodeDoneEvent
code: string
代码解释器输出的最终代码片段。
item_id: string
代码解释器工具调用条目的唯一标识。
output_index: integer
响应中代码已确定的输出条目索引。
sequence_number: integer
此事件序列号,用于对流式事件排序。
type: "response.code_interpreter_call_code.done"
类型,固定为response.code_interpreter_call_code.done。
"response.code_interpreter_call_code.done"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.code_interpreter_call_code.done",
"output_index": 3,
"item_id": "ci_12345",
"code": "print('done')",
"sequence_number": 1
}
response.output_text.annotation.added
向输出文本内容添加注解时发出。
结构定义
结构名称: BetaResponseOutputTextAnnotationAddedEvent
annotation: 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 } or null
新增的注解对象,详见注解schema。
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"
annotation_index: integer
注解在内容部分中的索引。
content_index: integer
内容部分在输出条目中的索引。
item_id: string
接收新增注解的条目唯一标识。
output_index: integer
输出条目在响应output数组中的索引。
sequence_number: integer
事件序列号。
type: "response.output_text.annotation.added"
类型,固定为response.output_text.annotation.added。
"response.output_text.annotation.added"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.output_text.annotation.added",
"item_id": "item-abc",
"output_index": 0,
"content_index": 0,
"annotation_index": 0,
"annotation": {
"type": "file_citation",
"file_id": "file-abc",
"index": 0,
"filename": "example.txt"
},
"sequence_number": 1
}
response.queued
响应进入队列、等待处理时发出。
结构定义
结构名称: BetaResponseQueuedEvent
response: BetaResponse
正在排队的完整响应对象。
id: string
此响应的唯一标识符。
access_programs: object { cyber } or null
created_at: number
此响应创建时的 Unix 时间戳,单位为秒。
format: unixtime
error: BetaResponseError or null
模型未能生成响应时返回的错误对象。
code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 18 more
此响应的错误代码。
"server_error"
"rate_limit_exceeded"
"invalid_prompt"
"data_residency_mismatch"
"bio_policy"
"misalignment_policy_violation"
"vector_store_timeout"
"invalid_image"
"invalid_image_format"
"invalid_base64_image"
"invalid_image_url"
"image_too_large"
"image_too_small"
"image_parse_error"
"image_content_policy_violation"
"invalid_image_mode"
"image_file_too_large"
"unsupported_image_media_type"
"empty_image_file"
"failed_to_download_image"
"image_file_not_found"
message: string
便于人阅读的错误说明。
misalignment: optional object { detailed_explanation, error_type, review_target, steer }
detailed_explanation: optional string
对此次阻止操作的公开说明。
error_type: optional string or "potentially_unintended_data_transfer" or "potentially_unintended_data_access" or "potentially_unintended_destructive_activity" or "other"
可选的分类;客户端必须能够接受其他值。
string
SafetyAlertErrorType = "potentially_unintended_data_transfer" or "potentially_unintended_data_access" or "potentially_unintended_destructive_activity" or "other"
可选的分类;客户端必须能够接受其他值。
"potentially_unintended_data_transfer"
"potentially_unintended_data_access"
"potentially_unintended_destructive_activity"
"other"
review_target: optional string or null
用于明确继续此次审查的不透明目标;不可用时为 null。
pattern: ^[A-Za-z0-9._~:-]+$, minLength: 1, maxLength: 96
steer: optional object { message }
可选的公开继续指令。
message: string
公开的继续指令。
param: optional string or null
与错误相关的请求参数;未记录时为 null。
type: optional string or null
原始错误类型;未记录时为 null。
incomplete_details: object { reason } or null
说明响应为何未完成的详细信息。
reason: optional "max_output_tokens" or "max_messages" or "content_filter" or "steered"
响应未完成的原因。steered表示响应在收到WebSocket response.steer事件后于安全输出边界停止;服务器随后可自动使用排队输入创建后继响应。
"max_output_tokens"
"max_messages"
"content_filter"
"steered"
instructions: string or array of BetaEasyInputMessage or Message { content, role, agent, 2 more } or BetaResponseOutputMessage or 33 more or null
插入模型上下文的系统消息或开发者消息。
与previous_response_id一起使用时,前一响应的instructions不会传入下一响应,便于在新响应中替换system或developer消息。
string
提供给模型的文本输入,等同于developer角色的文本输入。
InputItemList = array of BetaEasyInputMessage or Message { content, role, agent, 2 more } or BetaResponseOutputMessage or 33 more
提供给模型的一个或多个输入条目组成的列表,其中可以包含不同类型的内容。
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
生成该条目的智能体的规范名称。
metadata: map[string] or null
可附加到对象的一组16个键值对,用于结构化保存附加信息,并通过API或控制台查询对象。
键为最长64个字符的字符串,值为最长512个字符的字符串。
model: "gpt-6-astra" or "gpt-6.2-astra" or "gpt-6.1-sol" or 112 more or string
生成响应的模型ID,例如gpt-6.2-astra。OpenAI提供能力、性能和价格各异的模型,可在模型指南浏览比较。
"gpt-6-astra" or "gpt-6.2-astra" or "gpt-6.1-sol" or 112 more
生成响应的模型ID,例如gpt-6.2-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
object: "response"
此资源的对象类型,始终为 response。
"response"
output: array of BetaResponseOutputItem
模型生成的内容条目数组。
output数组的长度和顺序取决于模型响应。不要假定首个条目一定是包含生成内容的assistant消息;可考虑使用SDK支持的output_text属性。
BetaResponseOutputMessage object { id, content, role, 4 more }
模型输出的消息。
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
从文件中检索出的文本。
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 { id, output, status, 7 more }
id: string
函数调用工具输出的唯一 ID。
output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
你的代码产生的函数调用输出,可为字符串或输出内容列表。
StringOutput = string
函数调用输出的字符串。
OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
函数调用的文本、图像或文件输出。
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
status: "in_progress" or "completed" or "incomplete"
条目状态,可选 in_progress、completed 或 incomplete,通过 API 返回条目时填充。
"in_progress"
"completed"
"incomplete"
type: "function_call_output"
类型,固定为 function_call_output。
"function_call_output"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
call_id: optional string
模型生成的函数工具调用的唯一 ID。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
调用方类型,固定为 direct。
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
minLength: 1, maxLength: 64
type: "program" (default: "program")
调用方类型,固定为 program。
"program"
created_by: optional string
创建该条目的执行主体的标识。
name: optional string
产生输出的工具名称。
namespace: optional string
产生输出的工具所属命名空间。
AgentMessage object { id, author, content, 3 more }
id: string
此智能体消息的唯一 ID。
author: string
发送方智能体的标识。
content: array of BetaResponseInputText or BetaResponseOutputText or Text { text, type } or 7 more
智能体之间发送的加密内容。
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
BetaResponseOutputText object { annotations, logprobs, text, type }
模型输出的文本。
Text object { text, type }
文本内容。
text: string
type: "text" (default: "text")
"text"
SummaryText object { text, type }
模型生成的摘要文本。
text: string
模型到目前为止生成的推理输出摘要。
type: "summary_text" (default: "summary_text")
类型,固定为 summary_text。
"summary_text"
ReasoningText object { text, type }
模型生成的推理文本。
text: string
模型生成的推理文本。
type: "reasoning_text" (default: "reasoning_text")
类型,固定为 reasoning_text。
"reasoning_text"
BetaResponseOutputRefusal object { refusal, type }
模型的拒绝响应。
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
ComputerScreenshot object { detail, file_id, image_url, 2 more }
计算机屏幕截图。
detail: BetaImageDetail
发送给模型的截图图像的细节级别,可选 high、low、auto 或 original,默认为 auto。
file_id: string or null
包含截图的已上传文件的标识。
image_url: string or null
截图图像的 URL。
format: uri
type: "computer_screenshot" (default: "computer_screenshot")
指定事件类型。对于计算机屏幕截图,此属性固定为 computer_screenshot。
"computer_screenshot"
prompt_cache_breakpoint: optional object { mode, ttl }
标记可复用提示词前缀的精确结束位置。省略 ttl 时,断点继承请求中的 prompt_cache_options.ttl;该边界不会按词元块取整。
mode: "explicit" (default: "explicit")
断点模式,固定为 explicit。
"explicit"
ttl: optional "30m" or "12h"
此缓存断点的最短存续时间,默认为请求的 TTL。
"30m"
"12h"
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
EncryptedContent object { encrypted_content, type }
不透明的加密内容,由 Responses API 在受信任的模型执行环境中解密。
encrypted_content: string
不透明的加密内容。
type: "encrypted_content" (default: "encrypted_content")
输入条目的类型,固定为 encrypted_content。
"encrypted_content"
recipient: string
接收方智能体的标识。
type: "agent_message" (default: "agent_message")
条目类型,固定为 agent_message。
"agent_message"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
MultiAgentCall object { id, action, arguments, 3 more }
id: string
该多智能体调用条目的唯一 ID。
action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more
要执行的多智能体操作。
"spawn_agent"
"interrupt_agent"
"list_agents"
"send_message"
"followup_task"
"wait_agent"
arguments: string
为该操作生成的参数,格式为 JSON 字符串。
call_id: string
关联调用与其输出的唯一 ID。
type: "multi_agent_call" (default: "multi_agent_call")
多智能体调用的类型,固定为 multi_agent_call。
"multi_agent_call"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
MultiAgentCallOutput object { id, action, call_id, 3 more }
id: string
此多智能体调用输出条目的唯一 ID。
action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more
生成此结果的多智能体操作。
"spawn_agent"
"interrupt_agent"
"list_agents"
"send_message"
"followup_task"
"wait_agent"
call_id: string
此多智能体调用的唯一 ID。
output: array of BetaResponseOutputText
多智能体操作返回的文本。
annotations: array of FileCitation { file_id, filename, index, type } or URLCitation { end_index, start_index, title, 2 more } or ContainerFileCitation { container_id, end_index, file_id, 3 more } or FilePath { file_id, index, type }
文本输出的注解。
logprobs: array of object { token, bytes, logprob, top_logprobs }
text: string
模型输出的文本内容。
type: "output_text" (default: "output_text")
输出文本类型,固定为 output_text。
type: "multi_agent_call_output" (default: "multi_agent_call_output")
多智能体结果的类型,固定为 multi_agent_call_output。
"multi_agent_call_output"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
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
生成该条目的智能体的规范名称。
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
单击操作。
actions: optional BetaComputerActionList
computer_use的扁平化批量操作。每个操作包含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
供计算机使用工具使用的屏幕截图图像。
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"
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
生成该条目的智能体的规范名称。
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 }
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: "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
生成该条目的智能体的规范名称。
Compaction object { id, encrypted_content, type, 2 more }
v1/responses/compact API生成的压缩条目。
id: string
压缩条目的唯一 ID。
encrypted_content: string
压缩生成的加密内容。
type: "compaction" (default: "compaction")
类型,固定为 compaction。
"compaction"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
created_by: optional string
创建该条目的执行主体的标识。
ImageGenerationCall object { id, result, status, 10 more }
模型发起的图像生成请求。
id: string
图像生成调用的唯一 ID。
result: string or null
Base64 编码的生成图像。
status: "in_progress" or "completed" or "generating" or "failed"
图像生成调用的状态。
"in_progress"
"completed"
"generating"
"failed"
type: "image_generation_call"
类型,固定为 image_generation_call。
"image_generation_call"
action: optional "generate" or "edit" or "auto" or null
用于图像生成的操作。
"generate"
"edit"
"auto"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
background: optional "transparent" or "opaque" or "auto" or null
生成图像使用的背景设置。
"transparent"
"opaque"
"auto"
error: optional object { code, message, param, 2 more }
审核失败的详情,如可用。
code: string or null
错误代码。
message: string
错误描述。
param: string or null
关联的请求参数。
type: string
错误类型。
moderation_details: optional object { categories, moderation_stage }
moderation_blocked 错误的公开详情,如可用。
categories: array of string
公开的审核类别,未来可能增加新的类别值。
moderation_stage: "input" or "output" or "unknown"
审核阻止图像生成调用的阶段。
"input"
"output"
"unknown"
output_format: optional "png" or "webp" or "jpeg" or 2 more or null
生成图像使用的输出格式。
"png"
"webp"
"jpeg"
"gif"
"svg"
quality: optional "low" or "medium" or "high" or 3 more or null
图像生成工具调用生成的图像质量,可选 low、medium、high、xhigh、max 或 auto。
"low"
"medium"
"high"
"xhigh"
"max"
"auto"
revised_prompt: optional string or null
模型改写提示词后实际使用的提示词。
size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or null
图像尺寸,采用 WIDTHxHEIGHT 字符串形式,例如 1536x864。
string
"1024x1024" or "1024x1536" or "1536x1024"
图像尺寸,采用 WIDTHxHEIGHT 字符串形式,例如 1536x864。
"1024x1024"
"1024x1536"
"1536x1024"
svg_usage: optional object { input_tokens, model, output_tokens, 2 more }
input_tokens: integer
model: string
output_tokens: integer
reasoning_tokens: integer
total_tokens: integer
CodeInterpreterCall object { id, code, container_id, 4 more }
运行代码的工具调用。
id: string
代码解释器工具调用的唯一 ID。
code: string or null
要运行的代码,不可用时为 null。
container_id: string
运行代码使用的容器 ID。
outputs: array of Logs { logs, type } or Image { type, url } or null
代码解释器产生的日志、图像等输出;没有可用输出时可为null。
Logs object { logs, type }
代码解释器的日志输出。
logs: string
代码解释器的日志输出。
type: "logs" (default: "logs")
类型,固定为 logs。
"logs"
Image object { type, url }
代码解释器的图像输出。
type: "image" (default: "image")
类型,固定为 image。
"image"
url: string
代码解释器输出图像的 URL。
format: uri
status: "in_progress" or "completed" or "incomplete" or 2 more
代码解释器工具调用的状态,有效值为 in_progress、completed、incomplete、interpreting 和 failed。
"in_progress"
"completed"
"incomplete"
"interpreting"
"failed"
type: "code_interpreter_call" (default: "code_interpreter_call")
类型,固定为 code_interpreter_call。
"code_interpreter_call"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
LocalShellCall object { id, action, call_id, 3 more }
在本地 shell 上运行命令的工具调用。
id: string
本地 shell 调用的唯一 ID。
action: object { command, env, type, 3 more }
在服务器上执行 shell 命令。
command: array of string
要运行的命令。
env: map[string]
要为命令设置的环境变量。
type: "exec" (default: "exec")
类型,固定为 exec。
"exec"
timeout_ms: optional integer or null
可选的命令超时时长,单位为毫秒。
user: optional string or null
可选的运行命令的用户。
working_directory: optional string or null
可选的运行命令的工作目录。
call_id: string
模型生成的本地 shell 工具调用的唯一 ID。
status: "in_progress" or "completed" or "incomplete"
本地 shell 调用的状态。
"in_progress"
"completed"
"incomplete"
type: "local_shell_call"
类型,固定为 local_shell_call。
"local_shell_call"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
LocalShellCallOutput object { id, output, type, 2 more }
本地 shell 工具调用的输出。
id: string
模型生成的本地 shell 工具调用的唯一 ID。
output: string
本地 shell 工具调用输出的 JSON 字符串。
type: "local_shell_call_output"
类型,固定为 local_shell_call_output。
"local_shell_call_output"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
status: optional "in_progress" or "completed" or "incomplete" or null
条目状态,可选 in_progress、completed 或 incomplete。
"in_progress"
"completed"
"incomplete"
ShellCall object { id, action, call_id, 6 more }
在托管环境中执行一个或多个 shell 命令的工具调用。
id: string
shell 工具调用的唯一 ID,通过 API 返回此条目时填充。
action: object { commands, max_output_length, timeout_ms }
描述如何运行工具调用的 shell 命令及限制。
commands: array of string
max_output_length: integer or null
可选的每个命令返回的最大字符数。
timeout_ms: integer or null
可选的命令超时时长,单位为毫秒。
call_id: string
模型生成的 shell 工具调用的唯一 ID。
environment: BetaResponseLocalEnvironment or BetaResponseContainerReference or null
表示使用本地环境执行 shell 操作。
BetaResponseLocalEnvironment object { type }
表示使用本地环境执行 shell 操作。
type: "local" (default: "local")
环境类型,固定为 local。
"local"
BetaResponseContainerReference object { container_id, type }
表示通过 /v1/containers 创建的容器。
container_id: string
type: "container_reference" (default: "container_reference")
环境类型,固定为 container_reference。
"container_reference"
status: "in_progress" or "completed" or "incomplete"
shell 调用状态,可选 in_progress、completed 或 incomplete。
"in_progress"
"completed"
"incomplete"
type: "shell_call" (default: "shell_call")
类型,固定为 shell_call。
"shell_call"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建此工具调用的实体的 ID。
ShellCallOutput object { id, call_id, max_output_length, 6 more }
shell 工具调用发出的输出。
id: string
shell 调用输出的唯一 ID,通过 API 返回此条目时填充。
call_id: string
模型生成的 shell 工具调用的唯一 ID。
max_output_length: integer or null
shell 命令输出的最大长度,由模型生成,应与原始输出一并回传。
output: array of object { outcome, stderr, stdout, created_by }
shell 调用输出内容的数组。
outcome: Timeout { type } or Exit { exit_code, type }
表示 shell 调用输出块的退出结果(包含退出码)或超时结果。
Timeout object { type }
表示 shell 调用超过其配置的时间限制。
type: "timeout" (default: "timeout")
结果类型,固定为 timeout。
"timeout"
Exit object { exit_code, type }
表示 shell 命令已结束,并返回退出码。
exit_code: integer
shell 进程的退出码。
type: "exit" (default: "exit")
结果类型,固定为 exit。
"exit"
stderr: string
捕获的标准错误输出。
stdout: string
捕获的标准输出。
created_by: optional string
创建该条目的执行主体的标识。
status: "in_progress" or "completed" or "incomplete"
shell 调用输出的状态,可选 in_progress、completed 或 incomplete。
"in_progress"
"completed"
"incomplete"
type: "shell_call_output" (default: "shell_call_output")
shell 调用输出的类型,固定为 shell_call_output。
"shell_call_output"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建该条目的执行主体的标识。
ApplyPatchCall object { id, call_id, operation, 5 more }
通过创建、删除或更新文件来应用文件差异的工具调用。
id: string
apply_patch 工具调用的唯一 ID,通过 API 返回此条目时填充。
call_id: string
模型生成的 apply_patch 工具调用的唯一 ID。
operation: CreateFile { diff, path, type } or DeleteFile { path, type } or UpdateFile { diff, path, type }
通过 apply_patch 应用的 create_file、delete_file 或 update_file 操作之一。
CreateFile object { diff, path, type }
描述如何通过 apply_patch 工具创建文件的指令。
diff: string
要应用的差异。
path: string
要创建的文件路径。
type: "create_file" (default: "create_file")
使用提供的差异创建新文件。
"create_file"
DeleteFile object { path, type }
描述如何通过 apply_patch 工具删除文件的指令。
path: string
要删除的文件路径。
type: "delete_file" (default: "delete_file")
删除指定文件。
"delete_file"
UpdateFile object { diff, path, type }
描述如何通过 apply_patch 工具更新文件的指令。
diff: string
要应用的差异。
path: string
要更新的文件路径。
type: "update_file" (default: "update_file")
使用提供的差异更新已有文件。
"update_file"
status: "in_progress" or "completed"
apply_patch 工具调用状态,可选 in_progress 或 completed。
"in_progress"
"completed"
type: "apply_patch_call" (default: "apply_patch_call")
类型,固定为 apply_patch_call。
"apply_patch_call"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建此工具调用的实体的 ID。
ApplyPatchCallOutput object { id, call_id, status, 5 more }
apply_patch 工具调用发出的输出。
id: string
apply_patch 工具调用输出的唯一 ID,通过 API 返回此条目时填充。
call_id: string
模型生成的 apply_patch 工具调用的唯一 ID。
status: "completed" or "failed"
apply_patch 工具调用输出的状态,可选 completed 或 failed。
"completed"
"failed"
type: "apply_patch_call_output" (default: "apply_patch_call_output")
类型,固定为 apply_patch_call_output。
"apply_patch_call_output"
agent: optional object { agent_name }
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
type: "program" (default: "program")
"program"
created_by: optional string
创建此工具调用输出的实体的 ID。
output: optional string or null
apply_patch 工具返回的可选文本输出。
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
工具调用的错误,如有。
output: optional string or null
工具调用的输出。
status: optional "in_progress" or "completed" or "incomplete" or 2 more
工具调用状态,可选 in_progress、completed、incomplete、calling 或 failed。
"in_progress"
"completed"
"incomplete"
"calling"
"failed"
McpListTools object { id, server_label, tools, 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
决定的可选理由。
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 { id, call_id, output, 5 more }
id: string
自定义工具调用输出条目的唯一 ID。
call_id: string
调用 ID,用于将此自定义工具调用输出映射到自定义工具调用。
output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
你的代码生成的自定义工具输出,可为字符串或输出内容列表。
StringOutput = string
自定义工具调用输出的字符串。
OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile
自定义工具调用的文本、图像或文件输出。
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
status: "in_progress" or "completed" or "incomplete"
条目状态,可选 in_progress、completed 或 incomplete,通过 API 返回条目时填充。
"in_progress"
"completed"
"incomplete"
type: "custom_tool_call_output"
类型,固定为 custom_tool_call_output。
"custom_tool_call_output"
agent: optional object { agent_name } or null
生成该条目的智能体。
agent_name: string
生成该条目的智能体的规范名称。
caller: optional Direct { type } or Program { caller_id, type } or null
产生此工具调用的执行上下文。
Direct object { type }
type: "direct" (default: "direct")
调用方类型,固定为 direct。
"direct"
Program object { caller_id, type }
caller_id: string
产生此工具调用的 program 条目的调用 ID。
minLength: 1, maxLength: 64
type: "program" (default: "program")
调用方类型,固定为 program。
"program"
created_by: optional string
创建该条目的执行主体的标识。
parallel_tool_calls: boolean (default: true)
是否允许模型并行执行工具调用。
temperature: number or null (default: 1)
采样温度,范围0到2。0.8等较高值使输出更随机,0.2等较低值使输出更集中、更确定。通常建议只修改此参数或top_p中的一个。
minimum: 0, maximum: 2
tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more
模型生成响应时如何选择工具,参见tools参数了解可调用工具的定义方式。
BetaToolChoiceOptions = "none" or "auto" or "required"
控制模型调用哪个工具,或是否调用工具。
none 表示模型直接生成消息,不调用工具。
auto 表示模型可选择生成消息,或调用一个或多个工具。
required 表示模型必须调用一个或多个工具。
"none"
"auto"
"required"
BetaToolChoiceAllowed object { mode, tools, type }
将模型可用的工具限制为预先定义的集合。
mode: "auto" or "required"
将模型可用的工具限制为预先定义的集合。
auto 允许模型从可用工具中选择,或生成消息。
required 要求模型至少调用一个可用工具。
"auto"
"required"
tools: array of map[unknown]
应允许模型调用的工具定义列表。
对于 Responses API,工具定义列表可以如下所示:
[
{ "type": "function", "name": "get_weather" },
{ "type": "mcp", "server_label": "deepwiki" },
{ "type": "image_generation" }
]
type: "allowed_tools"
允许的工具配置类型,固定为 allowed_tools。
"allowed_tools"
BetaToolChoiceTypes object { type }
指定模型应使用内置工具生成响应,详见内置工具。
type: "file_search" or "web_search_preview" or "computer" or 5 more
模型应使用的托管工具类型,详见内置工具。
允许的值为:
file_searchweb_search_previewcomputercomputer_use_previewcomputer_usecode_interpreterimage_generation
"file_search"
"web_search_preview"
"computer"
"computer_use_preview"
"computer_use"
"web_search_preview_2025_03_11"
"image_generation"
"code_interpreter"
BetaToolChoiceFunction object { name, type }
使用此选项强制模型调用指定函数。
name: string
要调用的函数名称。
type: "function"
对于函数调用,类型固定为 function。
"function"
BetaToolChoiceMcp object { server_label, type, name }
使用此选项强制模型调用远程 MCP 服务器上的指定工具。
server_label: string
要使用的 MCP 服务器标签。
type: "mcp"
对于 MCP 工具,类型固定为 mcp。
"mcp"
name: optional string or null
要在服务器上调用的工具名称。
BetaToolChoiceCustom object { name, type }
使用此选项强制模型调用特定的自定义工具。
name: string
要调用的自定义工具名称。
type: "custom"
对于自定义工具调用,类型固定为 custom。
"custom"
BetaSpecificProgrammaticToolCallingParam object { type }
type: "programmatic_tool_calling" (default: "programmatic_tool_calling")
要调用的工具,固定为 programmatic_tool_calling。
"programmatic_tool_calling"
BetaToolChoiceApplyPatch object { type }
执行工具调用时,强制模型调用 apply_patch 工具。
type: "apply_patch" (default: "apply_patch")
要调用的工具,固定为 apply_patch。
"apply_patch"
BetaToolChoiceShell object { type }
需要调用工具时,强制模型调用 shell 工具。
type: "shell" (default: "shell")
要调用的工具,固定为 shell。
"shell"
tools: array of Function { name, parameters, strict, 6 more } or FileSearch { type, vector_store_ids, filters, 2 more } or Computer { type } or 13 more
模型生成响应时可以调用的工具数组。可以通过设置 tool_choice 参数指定使用哪个工具。
支持以下几类工具:
内置工具:OpenAI提供的扩展能力,如网页搜索和文件搜索,详见内置工具。MCP工具:通过自定义MCP服务器或Google Drive、SharePoint等预定义连接器集成第三方系统,详见MCP工具。函数调用(自定义工具):开发者定义的函数,让模型以强类型参数和输出调用你的代码,详见函数调用;也可使用自定义工具调用自己的代码。
Function object { name, parameters, strict, 6 more }
定义模型可以选择调用的自有代码函数。参阅函数调用。
name: string
要调用的函数名称。
parameters: map[unknown] or null
描述函数参数的 JSON Schema 对象。
strict: boolean or null
是否对此函数工具强制执行严格参数校验。
type: "function" (default: "function")
函数工具类型,固定为 function。
"function"
allowed_callers: optional array of "direct" or "programmatic" or null
工具调用的上下文。
"direct"
"programmatic"
async: optional boolean
defer_loading: optional boolean
此函数是否延迟加载并通过工具搜索加载。
description: optional string or null
函数描述,模型据此判断是否调用该函数。
output_schema: optional map[unknown] or null
描述此函数字符串输出中编码的 JSON 值的 JSON Schema 对象。
FileSearch object { type, vector_store_ids, filters, 2 more }
搜索已上传文件中相关内容的工具。参阅文件搜索工具。
type: "file_search" (default: "file_search")
文件搜索工具类型,固定为 file_search。
"file_search"
vector_store_ids: array of string
要搜索的向量存储 ID 列表。
filters: optional ComparisonFilter { 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"
top_p: number or null (default: 1)
核采样是温度采样的替代方式:模型仅考虑累计概率达到top_p的词元。例如0.1表示只考虑累计概率质量前10%的词元。
通常建议只调整此项或 temperature 中的一项,不同时调整两者。
minimum: 0, maximum: 1
background: optional boolean or null (default: false)
是否在后台运行模型响应,详见后台模式。
completed_at: optional number or null
Response完成时的Unix时间戳,单位为秒,仅在状态为completed时存在。
format: unixtime
conversation: optional object { id } or null
此响应所属的对话。该响应的输入条目和输出条目已自动添加到此对话。
id: string
与此响应关联的对话的唯一 ID。
image: optional object { context_compression }
context_compression: "enabled" or "disabled"
实际采用的图像上下文优化策略。
"enabled"
"disabled"
input_transformations: optional array of object { id, action, reason, type }
未传给模型的推理输入,按输入顺序排列。
id: string
原始推理条目的 ID。
action: "removed" (default: "removed")
"removed"
reason: "organization_mismatch" or "end_user_mismatch" or "model_mismatch" or 2 more
"organization_mismatch"
"end_user_mismatch"
"model_mismatch"
"prefix_mismatch"
"turn_boundary"
type: "reasoning" (default: "reasoning")
"reasoning"
max_output_tokens: optional integer or null
响应可生成词元数的上限,包括可见输出词元及推理词元。
max_tool_calls: optional integer or null
一个响应中可处理的内置工具调用总次数上限。此上限适用于所有内置工具调用的合计次数,而非每个工具分别计算。达到上限后,模型进一步调用工具的尝试会被忽略。
moderation: optional object { input, output } or null
如果请求了经审核的补全,则包含响应输入和输出的审核结果。
input: ModerationResult { categories, category_applied_input_types, category_scores, 3 more } or Error { code, message, type }
对响应输入的审核。
ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }
针对响应输入或输出生成的审核结果。
categories: map[boolean]
审核类别到布尔值的映射。输入被某类别标记时,该类别值为 true。
category_applied_input_types: map[array of "text" or "image"]
各类别评分所涵盖的输入模态。
"text"
"image"
category_scores: map[number]
审核类别到分数的映射。
flagged: boolean
表示内容是否被任一类别标记的布尔值。
model: string
生成此结果的审核模型。
type: "moderation_result" (default: "moderation_result")
对象类型,成功审核结果中固定为 moderation_result。
"moderation_result"
Error object { code, message, type }
尝试审核响应输入或输出时产生的错误。
code: string
错误代码。
message: string
错误消息。
type: "error" (default: "error")
对象类型;审核失败时始终为 error。
"error"
output: ModerationResult { categories, category_applied_input_types, category_scores, 3 more } or Error { code, message, type }
对响应输出的审核。
ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }
针对响应输入或输出生成的审核结果。
categories: map[boolean]
审核类别到布尔值的映射。输入被某类别标记时,该类别值为 true。
category_applied_input_types: map[array of "text" or "image"]
各类别评分所涵盖的输入模态。
"text"
"image"
category_scores: map[number]
审核类别到分数的映射。
flagged: boolean
表示内容是否被任一类别标记的布尔值。
model: string
生成此结果的审核模型。
type: "moderation_result" (default: "moderation_result")
对象类型,成功审核结果中固定为 moderation_result。
"moderation_result"
Error object { code, message, type }
尝试审核响应输入或输出时产生的错误。
code: string
错误代码。
message: string
错误消息。
type: "error" (default: "error")
对象类型;审核失败时始终为 error。
"error"
output_text: optional string or null
仅SDK提供的便利属性,聚合output数组中所有output_text条目的文本(若存在),Python和JavaScript SDK支持此属性。
previous_response_id: optional string or null
前一次模型响应的唯一ID,用于多轮对话,详见对话状态。不能与conversation同时使用。
prompt: optional BetaResponsePrompt or null
提示词模板及其变量的引用,详见代码中的提示词版本。
id: string
要使用的提示词模板的唯一标识。
variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile] or null
可选的变量替换映射,用于替换提示词中的变量。替换值可为字符串,也可为图像或文件等其他Response输入类型。
string
BetaResponseInputText object { text, type, prompt_cache_breakpoint }
输入模型的文本。
BetaResponseInputImage object { detail, type, file_id, 2 more }
输入模型的图像。参阅图像输入。
BetaResponseInputFile object { type, detail, file_data, 4 more }
输入模型的文件。
version: optional string or null
提示词模板的可选版本。
prompt_cache_diagnostics: optional CacheMiss { cache_missed_tokens, reason, type, comparison_reusable_tokens } or CacheHit { type } or ComparisonResponseNotFound { type } or Unavailable { type }
为此响应请求的提示词缓存诊断信息。
CacheMiss object { cache_missed_tokens, reason, type, comparison_reusable_tokens }
cache_missed_tokens: integer
首次检测到差异之后,受影响的输入词元数量估计值。
reason: "model_changed" or "prompt_cache_key_changed" or "tools_changed" or 6 more
未复用提示词缓存的原因。
"model_changed"
"prompt_cache_key_changed"
"tools_changed"
"text_format_changed"
"reasoning_effort_changed"
"verbosity_changed"
"context_compacted"
"input_changed"
"service_tier_changed"
type: "cache_miss" (default: "cache_miss")
"cache_miss"
comparison_reusable_tokens: optional integer
在所比较的响应中,可复用前缀的原始词元数。
CacheHit object { type }
type: "cache_hit" (default: "cache_hit")
"cache_hit"
ComparisonResponseNotFound object { type }
type: "comparison_response_not_found" (default: "comparison_response_not_found")
"comparison_response_not_found"
Unavailable object { type }
type: "unavailable" (default: "unavailable")
"unavailable"
prompt_cache_key: optional string or null
供OpenAI缓存相似请求的响应,以优化缓存命中率,替代user字段,详见提示词缓存。
prompt_cache_options: optional object { mode, ttl, comparison_response_id }
应用于该响应的提示词缓存选项。支持 gpt-5.6 及更新模型。
mode: "implicit" or "explicit"
是否启用了隐式提示词缓存断点。
"implicit"
"explicit"
ttl: "30m" or "12h"
应用于每个缓存断点的最短保留时间。
"30m"
"12h"
comparison_response_id: optional string or null
用于提示词缓存诊断比较的响应 ID。
prompt_cache_retention: optional "in_memory" or "24h" or null
已弃用,改用 prompt_cache_options.ttl。
提示词缓存保留策略。设为24h启用扩展缓存,使缓存前缀保持活跃更久,最长24小时,详见缓存保留。此字段表达最长保留策略,prompt_cache_options.ttl表达最短缓存寿命;两者独立、互不影响。gpt-5.5、gpt-5.5-pro及后续模型仅支持24h。
对于同时支持 in_memory 和 24h 的较早模型,默认值取决于组织的数据保留策略:
未启用ZDR的组织默认使用24h;启用ZDR且未指定prompt_cache_retention的组织默认使用in_memory。
"in_memory"
"24h"
reasoning: optional object { context, effort, generate_summary, 2 more } or null
推理模型的配置选项。
context: optional "auto" or "current_turn" or "all_turns" or null
控制后续轮次向模型呈现哪些推理条目。省略或设为auto时由模型决定上下文模式。gpt-5.6系列默认all_turns,更早模型默认current_turn。
在响应中返回时,表示本次响应实际使用的推理上下文模式。
"auto"
"current_turn"
"all_turns"
effort: optional "none" or "minimal" or "low" or 4 more or null (default: "medium")
限制推理模型的推理努力程度。目前支持none、minimal、low、medium、high、xhigh和max。降低努力程度可能加快响应并减少推理词元。并非所有模型支持每个值,具体见推理指南。
"none"
"minimal"
"low"
"medium"
"high"
"xhigh"
"max"
generate_summary: optional "auto" or "concise" or "detailed" or null
已弃用:请改用 summary。
模型推理的摘要,有助于调试和理解推理过程。可选auto、concise或detailed。
"auto"
"concise"
"detailed"
mode: optional string or "standard" or "pro"
控制请求的推理执行模式。
当此字段出现在返回的响应中时,表示实际使用的执行模式。
string
"standard" or "pro"
控制请求的推理执行模式。
当此字段出现在返回的响应中时,表示实际使用的执行模式。
"standard"
"pro"
summary: optional "auto" or "concise" or "detailed" or null
模型推理的摘要,有助于调试和理解推理过程。可选auto、concise或detailed。
computer-use-preview 模型及 gpt-5 之后的推理模型均支持 concise。
"auto"
"concise"
"detailed"
safety_identifier: optional string or null
稳定的用户标识,帮助检测应用中可能违反OpenAI使用政策的用户。应使用唯一标识各用户、最长128字符的字符串。建议对用户名或电子邮箱进行哈希,避免发送个人身份信息,详见安全标识。
maxLength: 128
service_tier: optional BetaServiceTier or null (default: "auto")
指定处理请求所采用的服务类型。
auto使用项目设置中的服务层级,未另行配置时为default。default使用所选模型的标准价格及性能;flex使用Flex处理。在Responses或Chat Completions请求中设置service_tier=fast或service_tier=priority可启用快速模式,不论传入哪一个,原文此处写明响应显示priority。ultrafast使用受访问控制的Ultrafast层级,当前此原文列为可供gpt-5.6-sol使用,响应显示ultrafast。未设置时默认auto。
设置 service_tier 后,响应体中的同名字段反映实际采用的处理模式,可能与请求参数的值不同。
"auto"
"default"
"flex"
"scale"
"priority"
"fast"
"ultrafast"
status: optional BetaResponseStatus
响应生成状态,可选completed、failed、in_progress、cancelled、queued或incomplete。
"completed"
"failed"
"in_progress"
"cancelled"
"queued"
"incomplete"
text: optional BetaResponseTextConfig
模型文本响应的配置选项,可为纯文本或结构化JSON数据,详见下列指南。
format: optional BetaResponseFormatTextConfig
指定模型必须输出的格式的对象。
配置{ "type": "json_schema" }可启用结构化输出,确保模型匹配提供的JSON Schema,详见结构化输出指南。
默认格式为 { "type": "text" },没有额外选项。
不建议用于 gpt-4o 及后续模型:
设置{ "type": "json_object" }可启用旧版JSON模式,确保模型生成合法JSON。支持json_schema的模型优先使用后者。
Text object { type }
默认响应格式,用于生成文本响应。
type: "text"
定义的响应格式类型,固定为 text。
"text"
BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }
JSON Schema响应格式,用于生成结构化JSON,详见结构化输出。
JSONObject object { type }
JSON对象响应格式,是生成JSON响应的旧方式。支持json_schema的模型建议使用后者。注意,若system或user消息没有明确要求生成JSON,模型不会自行生成JSON。
type: "json_object"
定义的响应格式类型,固定为 json_object。
"json_object"
verbosity: optional "low" or "medium" or "high" or null (default: "medium")
约束模型响应的详细程度。较低值生成更简洁的响应,较高值生成更详细的响应。目前支持low、medium和high,默认为medium。
"low"
"medium"
"high"
tool_usage: optional object { image_gen, web_search }
托管工具报告的用量,独立于基础模型的 usage。无法取得工具用量时可省略。若返回该字段,没有用量记录的工具类别计数为零。
image_gen 合计所有图像生成调用中可取得的词元计数。可能跳过用量记录不完整的调用。输出词元明细和缓存输入计数可省略,省略缓存计数表示缓存用量未知。
web_search.num_requests 统计可计费的搜索次数。打折搜索与打开网页等操作不计入。最终费用请以账单记录为准。
image_gen: object { input_tokens, input_tokens_details, output_tokens, 4 more }
图像生成工具调用的汇总用量统计。
input_tokens: integer
输入提示词中的图像与文本词元数量。
input_tokens_details: object { image_tokens, text_tokens }
图像生成的输入词元明细。
image_tokens: integer
输入提示词中的图像词元数量。
text_tokens: integer
输入提示词中的文本词元数量。
output_tokens: integer
模型生成的输出词元数量。
total_tokens: integer
图像生成使用的图像和文本词元总数。
cached_tokens: optional integer
cached_tokens_details: optional object { cached_image_tokens, cached_text_tokens }
cached_image_tokens: integer
cached_text_tokens: integer
output_tokens_details: optional object { image_tokens, text_tokens }
图像生成的输出词元明细。
image_tokens: integer
模型生成的图像输出词元数量。
text_tokens: integer
模型生成的文本输出词元数量。
web_search: object { num_requests }
网页搜索工具调用的汇总计费用量统计。
num_requests: integer
发起的计费网页搜索请求次数。
top_logprobs: optional integer or null
0到20之间的整数,指定每个词元位置返回多少个最可能词元及其对数概率;实际返回数量有时会少于请求值。
minimum: 0, maximum: 20
truncation: optional "auto" or "disabled" or null (default: "disabled")
模型响应的截断策略。
auto:输入超出模型的上下文窗口时,从对话开头移除条目以适配窗口。对部分模型,API 会先从输入上限扣除模型允许的最大输出量,再统计词元。因此,即使设置较低的max_output_tokens,也可能更早开始截断。disabled(默认值):输入超出模型上下文窗口时,请求会失败并返回 400 错误。
"auto"
"disabled"
usage: optional BetaResponseUsage or null
词元用量详情,包括输入词元、输出词元、输出词元分类和词元总数。
input_tokens: integer
输入词元数量。
input_tokens_details: object { cache_write_tokens, cached_tokens, cache_write_tokens_details }
输入词元的详细分类统计。
cache_write_tokens: integer
已写入缓存的输入词元数量。
cached_tokens: integer
从缓存读取的词元数量,详见提示词缓存。
cache_write_tokens_details: optional object { ttl_12h_tokens, ttl_30m_tokens }
ttl_12h_tokens: integer
以保留 12 小时的方式写入的输入词元数量。
ttl_30m_tokens: integer
以保留 30 分钟的方式写入的输入词元数量。
output_tokens: integer
输出词元数量。
output_tokens_details: object { reasoning_tokens }
输出词元的详细分类统计。
reasoning_tokens: integer
推理词元数量。
total_tokens: integer
使用的总词元数。
user: optional string or null
此字段正被safety_identifier和prompt_cache_key取代,维持缓存优化应改用prompt_cache_key。它是终端用户的稳定标识,通过更好地归类相似请求提高命中率,也帮助OpenAI检测和防止滥用,详见安全标识。
sequence_number: integer
此事件的序列号。
type: "response.queued"
类型,固定为response.queued。
"response.queued"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.queued",
"response": {
"id": "resp_123",
"object": "response",
"access_programs": null,
"created_at": 1609459200,
"status": "queued",
"error": null,
"incomplete_details": null,
"instructions": null,
"model": "gpt-6.2-astra",
"output": [],
"parallel_tool_calls": true,
"temperature": 1,
"tool_choice": "auto",
"tools": [],
"top_p": 1,
"metadata": {}
},
"sequence_number": 1
}
response.custom_tool_call_input.delta
表示自定义工具调用输入增量更新的事件。
结构定义
结构名称: BetaResponseCustomToolCallInputDeltaEvent
delta: string
自定义工具调用的增量输入数据。
item_id: string
与此事件关联的API条目唯一标识。
output_index: integer
此增量适用的输出索引。
sequence_number: integer
事件序列号。
type: "response.custom_tool_call_input.delta"
事件类型标识。
"response.custom_tool_call_input.delta"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
例中文字:部分输入文本
{
"type": "response.custom_tool_call_input.delta",
"sequence_number": 1,
"output_index": 0,
"item_id": "ctc_1234567890abcdef",
"delta": "partial input text"
}
response.custom_tool_call_input.done
表示自定义工具调用输入已经完整的事件。
结构定义
结构名称: BetaResponseCustomToolCallInputDoneEvent
input: string
自定义工具调用的完整输入数据。
item_id: string
与此事件关联的API条目唯一标识。
output_index: integer
此事件适用的输出索引。
sequence_number: integer
事件序列号。
type: "response.custom_tool_call_input.done"
事件类型标识。
"response.custom_tool_call_input.done"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
例中文字:最终完整输入文本
{
"type": "response.custom_tool_call_input.done",
"sequence_number": 1,
"output_index": 0,
"item_id": "ctc_1234567890abcdef",
"input": "final complete input text"
}
error
发生错误时发出。
结构定义
结构名称: BetaResponseErrorEvent
code: string or null
错误代码。
message: string
错误消息。
param: string or null
错误参数。
sequence_number: integer
事件序列号。
type: "error"
类型,固定为error。
"error"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
例中文字:发生了错误。
{
"type": "error",
"code": "ERR_SOMETHING",
"message": "Something went wrong",
"param": null,
"sequence_number": 1
}
response.audio.delta
产生部分音频响应时发出。
结构定义
结构名称: BetaResponseAudioDeltaEvent
delta: string
一块Base64编码的响应音频字节。
sequence_number: integer
流式响应中此分块的序列号。
type: "response.audio.delta"
类型,固定为response.audio.delta。
"response.audio.delta"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.audio.delta",
"response_id": "resp_123",
"delta": "base64encoded...",
"sequence_number": 1
}
response.audio.done
音频响应完成时发出。
结构定义
结构名称: BetaResponseAudioDoneEvent
sequence_number: integer
增量的序列号。
type: "response.audio.done"
类型,固定为response.audio.done。
"response.audio.done"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.audio.done",
"response_id": "resp-123",
"sequence_number": 1
}
response.audio.transcript.delta
产生部分音频转录文本时发出。
结构定义
结构名称: BetaResponseAudioTranscriptDeltaEvent
delta: string
音频响应的部分转录文本。
sequence_number: integer
事件序列号。
type: "response.audio.transcript.delta"
类型,固定为response.audio.transcript.delta。
"response.audio.transcript.delta"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
例中文字:……部分转录文本……
{
"type": "response.audio.transcript.delta",
"response_id": "resp_123",
"delta": " ... partial transcript ... ",
"sequence_number": 1
}
response.audio.transcript.done
完整音频转录完成时发出。
结构定义
结构名称: BetaResponseAudioTranscriptDoneEvent
sequence_number: integer
事件序列号。
type: "response.audio.transcript.done"
类型,固定为response.audio.transcript.done。
"response.audio.transcript.done"
agent: optional object { agent_name } or null
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.audio.transcript.done",
"response_id": "resp_123",
"sequence_number": 1
}
response.compaction.compacting
为压缩触发器采样新的摘要内容时发出,事件本身不包含摘要内容。
结构定义
结构名称: BetaResponseCompactionCompactingStreamingEvent
item_id: string
压缩输出条目的ID。
output_index: integer
压缩输出条目的索引。
sequence_number: integer
已发出事件的序列号。
type: "response.compaction.compacting" (default: "response.compaction.compacting")
事件类型,固定为response.compaction.compacting。
"response.compaction.compacting"
agent: optional object { agent_name }
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.compaction.compacting",
"sequence_number": 0,
"agent": {
"agent_name": "agent_name"
},
"output_index": 0,
"item_id": "item_id"
}
response.shell_call_command.added
向工具调用添加shell命令的流式事件。
结构定义
结构名称: BetaResponseShellCallCommandAddedStreamingEvent
command: string
新增的shell命令。
command_index: integer
新增shell命令的索引。
output_index: integer
被更新输出条目的索引。
sequence_number: integer
已发出事件的序列号。
type: "response.shell_call_command.added" (default: "response.shell_call_command.added")
类型,固定为response.shell_call_command.added。
"response.shell_call_command.added"
agent: optional object { agent_name }
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.shell_call_command.added",
"sequence_number": 0,
"agent": {
"agent_name": "agent_name"
},
"output_index": 0,
"command_index": 0,
"command": "command"
}
response.shell_call_command.delta
增量更新shell命令的流式事件。
结构定义
结构名称: BetaResponseShellCallCommandDeltaStreamingEvent
command_index: integer
已更新shell命令的索引。
delta: string
追加的shell命令增量。
output_index: integer
被更新输出条目的索引。
sequence_number: integer
已发出事件的序列号。
type: "response.shell_call_command.delta" (default: "response.shell_call_command.delta")
类型,固定为response.shell_call_command.delta。
"response.shell_call_command.delta"
agent: optional object { agent_name }
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
obfuscation: optional string
用于填充事件载荷的混淆字符串。
示例
{
"type": "response.shell_call_command.delta",
"sequence_number": 0,
"agent": {
"agent_name": "agent_name"
},
"output_index": 0,
"command_index": 0,
"delta": "delta",
"obfuscation": "obfuscation"
}
response.shell_call_command.done
shell命令完成的流式事件。
结构定义
结构名称: BetaResponseShellCallCommandDoneStreamingEvent
command: string
发出的最终shell命令。
command_index: integer
已完成shell命令的索引。
output_index: integer
被更新输出条目的索引。
sequence_number: integer
已发出事件的序列号。
type: "response.shell_call_command.done" (default: "response.shell_call_command.done")
类型,固定为response.shell_call_command.done。
"response.shell_call_command.done"
agent: optional object { agent_name }
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.shell_call_command.done",
"sequence_number": 0,
"agent": {
"agent_name": "agent_name"
},
"output_index": 0,
"command_index": 0,
"command": "command"
}
response.shell_call_output_content.delta
增量添加shell调用输出的流式事件。
结构定义
结构名称: BetaResponseShellCallOutputContentDeltaStreamingEvent
command_index: integer
产生输出的shell命令索引。
delta: object { stderr, stdout }
发出的标准输出或标准错误增量。
stderr: optional string
发出的标准错误增量。
stdout: optional string
发出的标准输出增量。
item_id: string
已更新输出条目的ID。
output_index: integer
被更新输出条目的索引。
sequence_number: integer
已发出事件的序列号。
type: "response.shell_call_output_content.delta" (default: "response.shell_call_output_content.delta")
类型,固定为response.shell_call_output_content.delta。
"response.shell_call_output_content.delta"
agent: optional object { agent_name }
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.shell_call_output_content.delta",
"sequence_number": 0,
"agent": {
"agent_name": "agent_name"
},
"item_id": "item_id",
"output_index": 0,
"command_index": 0,
"delta": {
"stdout": "stdout",
"stderr": "stderr"
}
}
response.shell_call_output_content.done
shell调用输出完成的流式事件。
结构定义
结构名称: BetaResponseShellCallOutputContentDoneStreamingEvent
command_index: integer
产生输出的shell命令索引。
item_id: string
已更新输出条目的ID。
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
创建该条目的执行主体的标识。
output_index: integer
被更新输出条目的索引。
sequence_number: integer
已发出事件的序列号。
type: "response.shell_call_output_content.done" (default: "response.shell_call_output_content.done")
类型,固定为response.shell_call_output_content.done。
"response.shell_call_output_content.done"
agent: optional object { agent_name }
此多智能体流式事件所属的智能体。
agent_name: string
生成该条目的智能体的规范名称。
示例
{
"type": "response.shell_call_output_content.done",
"sequence_number": 0,
"agent": {
"agent_name": "agent_name"
},
"item_id": "item_id",
"output_index": 0,
"command_index": 0,
"output": [
{
"stdout": "stdout",
"stderr": "stderr",
"outcome": {
"type": "timeout"
},
"created_by": "created_by"
}
]
}
TRAE-AI编程


更多建议: