OpenAI 创建多智能体响应
本页覆盖通用多智能体接口。专用网络安全访问配置未纳入此译稿。
创建模型响应
post /responses?beta=true
创建模型响应。提供文本或图像输入,生成文本或JSON输出。让模型调用你的自定义代码,或使用网页搜索、文件搜索等内置工具,将自有数据作为响应输入。
请求头参数
"openai-beta": optional array of "responses_multi_agent=v1"
"responses_multi_agent=v1"
请求体参数
内容类型为 application/json。
access_programs: optional object { cyber }
本次请求使用的领域专属访问计划。
background: optional boolean or null (default: false)
是否在后台运行模型响应,详见后台模式。
background_options: optional object { completion_window, continuation_id }
HTTP 请求的后台执行选项。2h 与 8h 完成窗口要求 background: true 和 Standard 处理,并须设置 stream: false 或省略 stream。
completion_window: optional "soonest" or "2h" or "8h"
后台执行的完成窗口。默认值为 soonest,2h 和 8h 用于选择有折扣的后台执行窗口。
"soonest"
"2h"
"8h"
continuation_id: optional string
由客户提供的不透明标识符,用于调整相关后台请求的优先级。它不会把此前的历史加入输入。
context_management: optional array of object { type, compact_threshold } or null
本次请求的上下文管理配置。
minItems: 1
type: string
上下文管理条目类型,目前只支持compaction。
compact_threshold: optional integer or null
触发此条目压缩的词元阈值。
minimum: 1000
conversation: optional string or BetaResponseConversationParam or null
此响应所属的对话。对话条目会放在本次请求的input_items前面;响应完成后,其输入和输出条目会自动添加到此对话。
ConversationID = string
对话的唯一 ID。
BetaResponseConversationParam object { id }
此响应所属的对话。
id: string
对话的唯一 ID。
image: optional object { context_compression }
请求级别的图像选项。
context_compression: optional "auto" or "enabled" or "disabled"
控制图像上下文优化。默认为 auto,根据模型、传输方式和输入选择策略。设为 enabled 可要求支持压缩,设为 disabled 可关闭此功能。
"auto"
"enabled"
"disabled"
include: optional array of BetaResponseIncludable or null
指定模型响应中要包含的额外输出数据。当前支持的值为:
web_search_call.action.sources:包含网页搜索工具调用的来源。code_interpreter_call.outputs:包含代码解释器工具调用中 Python 代码的输出。computer_call_output.output.image_url:包含计算机调用输出中的图像 URL。file_search_call.results:包含文件搜索工具调用的搜索结果。message.input_image.image_url:包含输入消息中的图像 URL。message.output_text.logprobs:包含助手消息中的输出文本对数概率。reasoning.encrypted_content:包含推理条目中的加密推理内容。
"file_search_call.results"
"web_search_call.results"
"web_search_call.action.sources"
"message.input_image.image_url"
"computer_call_output.output.image_url"
"code_interpreter_call.outputs"
"reasoning.encrypted_content"
"message.output_text.logprobs"
input: optional string or array of BetaEasyInputMessage or Message { content, role, agent, 2 more } or BetaResponseOutputMessage or 33 more
用于生成响应的文本、图像或文件输入。
更多说明如下。
TextInput = string
提供给模型的文本输入,等同于角色为 user 的文本输入。
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
生成该条目的智能体的规范名称。
instructions: optional string or null
插入模型上下文的系统消息或开发者消息。
与previous_response_id一起使用时,前一响应的instructions不会传入下一响应,便于在新响应中替换system或developer消息。
max_output_tokens: optional integer or null
为响应生成的词元数上限,包括可见输出词元和推理词元。
minimum: 16
max_tool_calls: optional integer or null
一个响应中可处理的内置工具调用总次数上限。此上限适用于所有内置工具调用的合计次数,而非每个工具分别计算。达到上限后,模型进一步调用工具的尝试会被忽略。
metadata: optional map[string] or null
可附加到对象的一组16个键值对,用于结构化保存附加信息,并通过API或控制台查询对象。
键为最长64个字符的字符串,值为最长512个字符的字符串。
model: optional "gpt-6-astra" or "gpt-6.2-astra" or "gpt-6.1-sol" or 112 more or string
用于生成响应的模型 ID,例如 gpt-6-astra。OpenAI 提供能力、性能特点和价格各异的多种模型。请参阅模型指南,浏览和比较可用模型。
"gpt-6-astra" or "gpt-6.2-astra" or "gpt-6.1-sol" or 112 more
用于生成响应的模型 ID,例如 gpt-6-astra。OpenAI 提供能力、性能特点和价格各异的多种模型。请参阅模型指南,浏览和比较可用模型。
"gpt-6-astra"
"gpt-6.2-astra"
"gpt-6.1-sol"
"gpt-6.2-sol"
"gpt-6.1-terra"
"gpt-6-sol"
"gpt-6-luna"
"gpt-5.6-sol"
"gpt-5.6-terra"
"gpt-5.6-luna"
"gpt-5.5"
"gpt-5.5-2026-04-23"
"gpt-5.4"
"gpt-5.4-mini"
"gpt-5.4-nano"
"gpt-5.4-mini-2026-03-17"
"gpt-5.4-nano-2026-03-17"
"gpt-5.3-chat-latest"
"gpt-5.2"
"gpt-5.2-2025-12-11"
"gpt-5.2-chat-latest"
"gpt-5.2-pro"
"gpt-5.2-pro-2025-12-11"
"gpt-5.1"
"gpt-5.1-2025-11-13"
"gpt-5.1-codex"
"gpt-5.1-mini"
"gpt-5.1-chat-latest"
"gpt-5"
"gpt-5-mini"
"gpt-5-nano"
"gpt-5-2025-08-07"
"gpt-5-mini-2025-08-07"
"gpt-5-nano-2025-08-07"
"gpt-5-chat-latest"
"gpt-4.1"
"gpt-4.1-mini"
"gpt-4.1-nano"
"gpt-4.1-2025-04-14"
"gpt-4.1-mini-2025-04-14"
"gpt-4.1-nano-2025-04-14"
"o4-mini"
"o4-mini-2025-04-16"
"o3"
"o3-2025-04-16"
"o3-mini"
"o3-mini-2025-01-31"
"o1"
"o1-2024-12-17"
"o1-preview"
"o1-preview-2024-09-12"
"o1-mini"
"o1-mini-2024-09-12"
"gpt-4o"
"gpt-4o-2024-11-20"
"gpt-4o-2024-08-06"
"gpt-4o-2024-05-13"
"gpt-audio-mini"
"gpt-audio-mini-2025-12-15"
"gpt-4o-audio-preview"
"gpt-4o-audio-preview-2024-10-01"
"gpt-4o-audio-preview-2024-12-17"
"gpt-4o-audio-preview-2025-06-03"
"gpt-4o-mini-audio-preview"
"gpt-4o-mini-audio-preview-2024-12-17"
"gpt-4o-search-preview"
"gpt-4o-mini-search-preview"
"gpt-4o-search-preview-2025-03-11"
"gpt-4o-mini-search-preview-2025-03-11"
"chatgpt-4o-latest"
"codex-mini-latest"
"gpt-4o-mini"
"gpt-4o-mini-2024-07-18"
"gpt-4-turbo"
"gpt-4-turbo-2024-04-09"
"gpt-4-0125-preview"
"gpt-4-turbo-preview"
"gpt-4-1106-preview"
"gpt-4-vision-preview"
"gpt-4"
"gpt-4-0314"
"gpt-4-0613"
"gpt-4-32k"
"gpt-4-32k-0314"
"gpt-4-32k-0613"
"gpt-3.5-turbo"
"gpt-3.5-turbo-16k"
"gpt-3.5-turbo-0301"
"gpt-3.5-turbo-0613"
"gpt-3.5-turbo-1106"
"gpt-3.5-turbo-0125"
"gpt-3.5-turbo-16k-0613"
"o1-pro"
"o1-pro-2025-03-19"
"o3-pro"
"o3-pro-2025-06-10"
"o3-deep-research"
"o3-deep-research-2025-06-26"
"o4-mini-deep-research"
"o4-mini-deep-research-2025-06-26"
"computer-use-preview"
"computer-use-preview-2025-03-11"
"gpt-5.5-pro"
"gpt-5.5-pro-2026-04-23"
"gpt-5-codex"
"gpt-5-pro"
"gpt-5-pro-2025-10-06"
"gpt-5.1-codex-max"
"gpt-daybreak-blue-latest"
"gpt-daybreak-red-latest"
"gpt-5.6-cyber"
"gpt-6-cyber"
"gpt-rosalind-research"
"gpt-6-rosalind"
"gpt-6.2-astra-law"
string
moderation: optional object { model, policy } or null
对本次响应输入和输出执行审核的配置。
model: string
审核补全内容所用的审核模型,例如 'omni-moderation-latest'。
policy: optional object { input, output } or null
对受审核响应的输入和输出应用的策略。
input: optional object { mode } or null
响应输入的审核策略。
mode: "score" or "block"
"score"
"block"
output: optional object { mode } or null
响应输出的审核策略。
mode: "score" or "block"
"score"
"block"
multi_agent: optional object { enabled, max_concurrent_subagents } or null
服务端托管的多智能体执行配置。
enabled: boolean
是否为此响应启用服务端托管的多智能体执行。
max_concurrent_subagents: optional integer
max_concurrent_subagents 设置整个智能体树中可同时处于活动状态的子智能体数量。计算所有层级的后代,根智能体不计入。API 没有为该设置规定固定上限。默认值为 3,适用于大多数工作负载。多智能体运行的树深度和单次创建的子智能体总数也无固定上限。
minimum: 1
parallel_tool_calls: optional boolean or null (default: true)
是否允许模型并行执行工具调用。
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_key: optional string or null
OpenAI 用于缓存类似请求的响应,以优化缓存命中率。替代 user 字段。了解更多。
prompt_cache_options: optional object { comparison_response_id, mode, prewarm, ttl }
提示词缓存选项,支持 gpt-5.6 及后续模型。默认由 OpenAI 自动选择一个隐式缓存断点。可通过 prompt_cache_breakpoint 为内容块添加显式断点。每个请求最多写入四个断点。缓存匹配会考虑对话中最近最多 80 个断点,不受内容块回看数量限制。将 mode 设为 explicit 可禁用隐式断点。ttl 默认为 30m。支持的存续时间取决于 API,当前详情参阅提示词缓存指南。
comparison_response_id: optional string or null
诊断提示词缓存复用时用于比较的响应ID。启用该功能时,提供此字段会请求缓存诊断。
mode: optional "implicit" or "explicit"
控制 OpenAI 是否自动创建隐式缓存断点,默认为 implicit。使用 implicit 时,创建一个隐式断点,并写入请求中最近最多三个显式断点。使用 explicit 时,不创建隐式断点,写入最近最多四个显式断点。如果没有显式断点,请求不使用提示词缓存。
"implicit"
"explicit"
prewarm: optional boolean
准备提示词缓存但不生成输出,默认为false;设为true会将generate覆盖为false。
ttl: optional "30m" or "12h"
请求写入的所有隐式和显式缓存断点的最短保留时间。支持 30m(默认值)和 12h。后端可能保留更久。
"30m"
"12h"
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"
store: optional boolean or null (default: true)
是否保存生成的响应,以供之后通过API检索。省略时默认为true;设为true时,响应数据至少保存30天,但受数据保留例外约束。
stream: optional boolean or null (default: false)
设为true时,模型响应会在生成过程中通过服务端发送事件流式传给客户端,详见流式事件。
stream_options: optional object { include_obfuscation } or null
流式响应选项,仅在设置stream: true时提供。
include_obfuscation: optional boolean
设为true启用流混淆:向流式增量事件的obfuscation字段添加随机字符,规范化载荷大小,以缓解某些侧信道攻击。默认包含这些字段,会增加少量流量开销。如果信任应用与OpenAI API之间的网络链路,可设include_obfuscation: false以节省带宽。
temperature: optional number or null (default: 1)
采样温度,范围0到2。0.8等较高值使输出更随机,0.2等较低值使输出更集中、更确定。通常建议只修改此参数或top_p中的一个。
minimum: 0, maximum: 2
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_choice: optional 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: optional 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_logprobs: optional integer or null
0到20之间的整数,指定每个词元位置返回多少个最可能词元及其对数概率;实际返回数量有时会少于请求值。
minimum: 0, maximum: 20
top_p: optional number or null (default: 1)
核采样是温度采样的替代方式:模型仅考虑累计概率达到top_p的词元。例如0.1表示只考虑累计概率质量前10%的词元。
通常建议只调整此项或 temperature 中的一项,不同时调整两者。
minimum: 0, maximum: 1
truncation: optional "auto" or "disabled" or null (default: "disabled")
模型响应的截断策略。
auto:输入超出模型的上下文窗口时,从对话开头移除条目以适配窗口。对部分模型,API 会先从输入上限扣除模型允许的最大输出量,再统计词元。因此,即使设置较低的max_output_tokens,也可能更早开始截断。disabled(默认值):输入超出模型上下文窗口时,请求会失败并返回 400 错误。
"auto"
"disabled"
user: optional string or null
此字段正被safety_identifier和prompt_cache_key取代,维持缓存优化应改用prompt_cache_key。它是终端用户的稳定标识,通过更好地归类相似请求提高命中率,也帮助OpenAI检测和防止滥用,详见安全标识。
返回值
BetaResponse object { id, access_programs, created_at, 37 more }
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-astra。OpenAI 提供能力、性能特点和价格各异的多种模型。请参阅模型指南,浏览和比较可用模型。
"gpt-6-astra" or "gpt-6.2-astra" or "gpt-6.1-sol" or 112 more
用于生成响应的模型 ID,例如 gpt-6-astra。OpenAI 提供能力、性能特点和价格各异的多种模型。请参阅模型指南,浏览和比较可用模型。
"gpt-6-astra"
"gpt-6.2-astra"
"gpt-6.1-sol"
"gpt-6.2-sol"
"gpt-6.1-terra"
"gpt-6-sol"
"gpt-6-luna"
"gpt-5.6-sol"
"gpt-5.6-terra"
"gpt-5.6-luna"
"gpt-5.5"
"gpt-5.5-2026-04-23"
"gpt-5.4"
"gpt-5.4-mini"
"gpt-5.4-nano"
"gpt-5.4-mini-2026-03-17"
"gpt-5.4-nano-2026-03-17"
"gpt-5.3-chat-latest"
"gpt-5.2"
"gpt-5.2-2025-12-11"
"gpt-5.2-chat-latest"
"gpt-5.2-pro"
"gpt-5.2-pro-2025-12-11"
"gpt-5.1"
"gpt-5.1-2025-11-13"
"gpt-5.1-codex"
"gpt-5.1-mini"
"gpt-5.1-chat-latest"
"gpt-5"
"gpt-5-mini"
"gpt-5-nano"
"gpt-5-2025-08-07"
"gpt-5-mini-2025-08-07"
"gpt-5-nano-2025-08-07"
"gpt-5-chat-latest"
"gpt-4.1"
"gpt-4.1-mini"
"gpt-4.1-nano"
"gpt-4.1-2025-04-14"
"gpt-4.1-mini-2025-04-14"
"gpt-4.1-nano-2025-04-14"
"o4-mini"
"o4-mini-2025-04-16"
"o3"
"o3-2025-04-16"
"o3-mini"
"o3-mini-2025-01-31"
"o1"
"o1-2024-12-17"
"o1-preview"
"o1-preview-2024-09-12"
"o1-mini"
"o1-mini-2024-09-12"
"gpt-4o"
"gpt-4o-2024-11-20"
"gpt-4o-2024-08-06"
"gpt-4o-2024-05-13"
"gpt-audio-mini"
"gpt-audio-mini-2025-12-15"
"gpt-4o-audio-preview"
"gpt-4o-audio-preview-2024-10-01"
"gpt-4o-audio-preview-2024-12-17"
"gpt-4o-audio-preview-2025-06-03"
"gpt-4o-mini-audio-preview"
"gpt-4o-mini-audio-preview-2024-12-17"
"gpt-4o-search-preview"
"gpt-4o-mini-search-preview"
"gpt-4o-search-preview-2025-03-11"
"gpt-4o-mini-search-preview-2025-03-11"
"chatgpt-4o-latest"
"codex-mini-latest"
"gpt-4o-mini"
"gpt-4o-mini-2024-07-18"
"gpt-4-turbo"
"gpt-4-turbo-2024-04-09"
"gpt-4-0125-preview"
"gpt-4-turbo-preview"
"gpt-4-1106-preview"
"gpt-4-vision-preview"
"gpt-4"
"gpt-4-0314"
"gpt-4-0613"
"gpt-4-32k"
"gpt-4-32k-0314"
"gpt-4-32k-0613"
"gpt-3.5-turbo"
"gpt-3.5-turbo-16k"
"gpt-3.5-turbo-0301"
"gpt-3.5-turbo-0613"
"gpt-3.5-turbo-1106"
"gpt-3.5-turbo-0125"
"gpt-3.5-turbo-16k-0613"
"o1-pro"
"o1-pro-2025-03-19"
"o3-pro"
"o3-pro-2025-06-10"
"o3-deep-research"
"o3-deep-research-2025-06-26"
"o4-mini-deep-research"
"o4-mini-deep-research-2025-06-26"
"computer-use-preview"
"computer-use-preview-2025-03-11"
"gpt-5.5-pro"
"gpt-5.5-pro-2026-04-23"
"gpt-5-codex"
"gpt-5-pro"
"gpt-5-pro-2025-10-06"
"gpt-5.1-codex-max"
"gpt-daybreak-blue-latest"
"gpt-daybreak-red-latest"
"gpt-5.6-cyber"
"gpt-6-cyber"
"gpt-rosalind-research"
"gpt-6-rosalind"
"gpt-6.2-astra-law"
string
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检测和防止滥用,详见安全标识。
示例
## 从环境变量读取 API 密钥,按需替换示例资源标识。
curl https://api.openai.com/v1/responses \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '"string"'
200 响应示例
例中文字:图中是一片风景:木栈道或小径穿过葱郁青草,天空湛蓝、点缀云朵。环境像宁静的公园或自然保护区,背景有树木和灌木。
{
"id": "resp_67ccd3a9da748190baa7f1570fe91ac604becb25c45c1d41",
"object": "response",
"access_programs": null,
"created_at": 1741476777,
"status": "completed",
"completed_at": 1741476778,
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-6-astra",
"output": [
{
"type": "message",
"id": "msg_67ccd3acc8d48190a77525dc6de64b4104becb25c45c1d41",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "The image depicts a scenic landscape with a wooden boardwalk or pathway leading through lush, green grass under a blue sky with some clouds. The setting suggests a peaceful natural area, possibly a park or nature reserve. There are trees and shrubs in the background.",
"annotations": [],
"logprobs": []
}
]
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null,
"context": null
},
"store": true,
"temperature": 1,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [],
"top_p": 1,
"truncation": "disabled",
"usage": {
"input_tokens": 328,
"input_tokens_details": {
"cached_tokens": 0,
"cache_write_tokens": 0
},
"output_tokens": 52,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 380
},
"tool_usage": {
"image_gen": {
"input_tokens": 0,
"input_tokens_details": {
"text_tokens": 0,
"image_tokens": 0
},
"output_tokens": 0,
"output_tokens_details": {
"text_tokens": 0,
"image_tokens": 0
},
"total_tokens": 0
},
"web_search": {
"num_requests": 0
}
},
"user": null,
"metadata": {},
"conversation": {
"id": "id"
},
"image": {
"context_compression": "enabled"
},
"input_transformations": [
{
"id": "id",
"action": "removed",
"reason": "organization_mismatch",
"type": "reasoning"
}
],
"moderation": {
"input": {
"categories": {
"foo": true
},
"category_applied_input_types": {
"foo": [
"text"
]
},
"category_scores": {
"foo": 0
},
"flagged": true,
"model": "model",
"type": "moderation_result"
},
"output": {
"categories": {
"foo": true
},
"category_applied_input_types": {
"foo": [
"text"
]
},
"category_scores": {
"foo": 0
},
"flagged": true,
"model": "model",
"type": "moderation_result"
}
},
"output_text": "output_text",
"prompt_cache_diagnostics": {
"cache_missed_tokens": 0,
"reason": "model_changed",
"type": "cache_miss",
"comparison_reusable_tokens": 0
},
"prompt_cache_options": {
"mode": "implicit",
"ttl": "30m",
"comparison_response_id": "comparison_response_id"
},
"service_tier": "auto"
}
文件输入
例中文字:这个文件里有什么?
## 从环境变量读取 API 密钥,按需替换示例资源标识。
curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-6-astra",
"input": [
{
"role": "user",
"content": [
{"type": "input_text", "text": "what is in this file?"},
{
"type": "input_file",
"file_url": "https://www.berkshirehathaway.com/letters/2024ltr.pdf",
"detail": "auto"
}
]
}
]
}'
响应示例
例中文字:文件似乎摘自伯克希尔·哈撒韦致股东信,可能由沃伦·巴菲特撰写。内容包括:1.沟通理念,强调向股东坦诚披露成败;2.承认商业评估与管理人员聘用错误并及时纠正;3.提及Greg Abel接任首席执行官及延续诚实沟通;4.收购Forest River及与创始人Pete Liegl的信任关系;5.2024年保险和投资业绩,尤其GEICO的改善;6.向美国财政部缴税及股东再投资的贡献;7.控股子公司与证券投资、长期持有策略;8.美国经济发展与伯克希尔的角色;9.财产与意外险模式的挑战和优势;10.日本企业投资及未来计划;11.奥马哈年度大会、日程变化与新书;12.家庭趣事及个人化表达;13.与标普500比较的年度业绩表及长期收益。总体强调透明、投资自身业务与整体经济、强有力领导和审慎财务管理。这是来源中的历史示例回答译文,不是本手册对当前公司事实的核验。
{
"id": "resp_686eef60237881a2bd1180bb8b13de430e34c516d176ff86",
"object": "response",
"access_programs": null,
"created_at": 1752100704,
"status": "completed",
"completed_at": 1752100705,
"background": false,
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"max_tool_calls": null,
"model": "gpt-6-astra",
"output": [
{
"id": "msg_686eef60d3e081a29283bdcbc4322fd90e34c516d176ff86",
"type": "message",
"status": "completed",
"content": [
{
"type": "output_text",
"annotations": [],
"logprobs": [],
"text": "The file seems to contain excerpts from a letter to the shareholders of Berkshire Hathaway Inc., likely written by Warren Buffett. It covers several topics:\n\n1. **Communication Philosophy**: Buffett emphasizes the importance of transparency and candidness in reporting mistakes and successes to shareholders.\n\n2. **Mistakes and Learnings**: The letter acknowledges past mistakes in business assessments and management hires, highlighting the importance of correcting errors promptly.\n\n3. **CEO Succession**: Mention of Greg Abel stepping in as the new CEO and continuing the tradition of honest communication.\n\n4. **Pete Liegl Story**: A detailed account of acquiring Forest River and the relationship with its founder, highlighting trust and effective business decisions.\n\n5. **2024 Performance**: Overview of business performance, particularly in insurance and investment activities, with a focus on GEICO's improvement.\n\n6. **Tax Contributions**: Discussion of significant tax payments to the U.S. Treasury, credited to shareholders' reinvestments.\n\n7. **Investment Strategy**: A breakdown of Berkshire\u2019s investments in both controlled subsidiaries and marketable equities, along with a focus on long-term holding strategies.\n\n8. **American Capitalism**: Reflections on America\u2019s economic development and Berkshire\u2019s role within it.\n\n9. **Property-Casualty Insurance**: Insights into the P/C insurance business model and its challenges and benefits.\n\n10. **Japanese Investments**: Information about Berkshire\u2019s investments in Japanese companies and future plans.\n\n11. **Annual Meeting**: Details about the upcoming annual gathering in Omaha, including schedule changes and new book releases.\n\n12. **Personal Anecdotes**: Light-hearted stories about family and interactions, conveying Buffett's personable approach.\n\n13. **Financial Performance Data**: Tables comparing Berkshire\u2019s annual performance to the S&P 500, showing impressive long-term gains.\n\nOverall, the letter reinforces Berkshire Hathaway's commitment to transparency, investment in both its businesses and the wider economy, and emphasizes strong leadership and prudent financial management."
}
],
"role": "assistant"
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null
},
"service_tier": "default",
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [],
"top_logprobs": 0,
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 8438,
"input_tokens_details": {
"cached_tokens": 0,
"cache_write_tokens": 0
},
"output_tokens": 398,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 8836
},
"user": null,
"metadata": {}
}
文件搜索
例中文字:古老棕龙有哪些属性?
## 从环境变量读取 API 密钥,按需替换示例资源标识。
curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-6-astra",
"tools": [{
"type": "file_search",
"vector_store_ids": ["vs_1234567890"],
"max_num_results": 20
}],
"input": "What are the attributes of an ancient brown dragon?"
}'
响应示例
例中文字:古老棕龙的属性 / 古老棕龙的属性包括……
{
"id": "resp_67ccf4c55fc48190b71bd0463ad3306d09504fb6872380d7",
"object": "response",
"access_programs": null,
"created_at": 1741485253,
"status": "completed",
"completed_at": 1741485254,
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-6-astra",
"output": [
{
"type": "file_search_call",
"id": "fs_67ccf4c63cd08190887ef6464ba5681609504fb6872380d7",
"status": "completed",
"queries": [
"attributes of an ancient brown dragon"
],
"results": null
},
{
"type": "message",
"id": "msg_67ccf4c93e5c81909d595b369351a9d309504fb6872380d7",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "The attributes of an ancient brown dragon include...",
"annotations": [
{
"type": "file_citation",
"index": 320,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 576,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 815,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 815,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 1030,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 1030,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 1156,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 1225,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
}
],
"logprobs": []
}
]
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [
{
"type": "file_search",
"filters": null,
"max_num_results": 20,
"ranking_options": {
"ranker": "auto",
"score_threshold": 0.0
},
"vector_store_ids": [
"vs_1234567890"
]
}
],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 18307,
"input_tokens_details": {
"cached_tokens": 0,
"cache_write_tokens": 0
},
"output_tokens": 348,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 18655
},
"user": null,
"metadata": {}
}
函数
例中文字:波士顿今天天气如何? / 获取指定地点的当前天气。 / 城市和州,例如加利福尼亚州旧金山。
## 从环境变量读取 API 密钥,按需替换示例资源标识。
curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-6-astra",
"input": "What is the weather like in Boston today?",
"tools": [
{
"type": "function",
"name": "get_current_weather",
"description": "Get the current weather in a given location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"]
}
},
"required": ["location", "unit"]
}
}
],
"tool_choice": "auto"
}'
响应示例
例中文字:获取指定地点的当前天气。 / 城市和州,例如加利福尼亚州旧金山。
{
"id": "resp_67ca09c5efe0819096d0511c92b8c890096610f474011cc0",
"object": "response",
"access_programs": null,
"created_at": 1741294021,
"status": "completed",
"completed_at": 1741294022,
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-6-astra",
"output": [
{
"type": "function_call",
"id": "fc_67ca09c6bedc8190a7abfec07b1a1332096610f474011cc0",
"call_id": "call_unLAR8MvFNptuiZK6K6HCy5k",
"name": "get_current_weather",
"arguments": "{\"location\":\"Boston, MA\",\"unit\":\"celsius\"}",
"status": "completed"
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [
{
"type": "function",
"description": "Get the current weather in a given location",
"name": "get_current_weather",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
},
"unit": {
"type": "string",
"enum": [
"celsius",
"fahrenheit"
]
}
},
"required": [
"location",
"unit"
]
},
"strict": true
}
],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 291,
"output_tokens": 23,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 314,
"input_tokens_details": {
"cached_tokens": 0,
"cache_write_tokens": 0
}
},
"user": null,
"metadata": {}
}
图像输入
例中文字:这张图里有什么?
## 从环境变量读取 API 密钥,按需替换示例资源标识。
curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-6-astra",
"input": [
{
"role": "user",
"content": [
{"type": "input_text", "text": "what is in this image?"},
{
"type": "input_image",
"image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
}
]
}
]
}'
响应示例
例中文字:图中是一片风景:木栈道或小径穿过葱郁青草,天空湛蓝、点缀云朵。环境像宁静的公园或自然保护区,背景有树木和灌木。
{
"id": "resp_67ccd3a9da748190baa7f1570fe91ac604becb25c45c1d41",
"object": "response",
"access_programs": null,
"created_at": 1741476777,
"status": "completed",
"completed_at": 1741476778,
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-6-astra",
"output": [
{
"type": "message",
"id": "msg_67ccd3acc8d48190a77525dc6de64b4104becb25c45c1d41",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "The image depicts a scenic landscape with a wooden boardwalk or pathway leading through lush, green grass under a blue sky with some clouds. The setting suggests a peaceful natural area, possibly a park or nature reserve. There are trees and shrubs in the background.",
"annotations": [],
"logprobs": []
}
]
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 328,
"input_tokens_details": {
"cached_tokens": 0,
"cache_write_tokens": 0
},
"output_tokens": 52,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 380
},
"user": null,
"metadata": {}
}
推理
例中文字:土拨鼠能扔多少木头?
## 从环境变量读取 API 密钥,按需替换示例资源标识。
curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-6-astra",
"input": "How much wood would a woodchuck chuck?",
"reasoning": {
"effort": "high"
}
}'
响应示例
例中文字:经典绕口令……
{
"id": "resp_67ccd7eca01881908ff0b5146584e408072912b2993db808",
"object": "response",
"access_programs": null,
"created_at": 1741477868,
"status": "completed",
"completed_at": 1741477869,
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-6-astra",
"output": [
{
"type": "message",
"id": "msg_67ccd7f7b5848190a6f3e95d809f6b44072912b2993db808",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "The classic tongue twister...",
"annotations": [],
"logprobs": []
}
]
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": "high",
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 81,
"input_tokens_details": {
"cached_tokens": 0,
"cache_write_tokens": 0
},
"output_tokens": 1035,
"output_tokens_details": {
"reasoning_tokens": 832
},
"total_tokens": 1116
},
"user": null,
"metadata": {}
}
流式传输示例
例中文字:你是一位乐于助人的助手。
## 从环境变量读取 API 密钥,按需替换示例资源标识。
curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-6-astra",
"instructions": "You are a helpful assistant.",
"input": "Hello!",
"stream": true
}'
响应示例
该示例展示 SSE 事件格式。
event: response.created
data: {"type":"response.created","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","access_programs":null,"created_at":1741290958,"status":"in_progress","error":null,"incomplete_details":null,"instructions":"You are a helpful assistant.","max_output_tokens":null,"model":"gpt-6-astra","output":[],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":null,"user":null,"metadata":{}},"sequence_number":0}
event: response.in_progress
data: {"type":"response.in_progress","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","access_programs":null,"created_at":1741290958,"status":"in_progress","error":null,"incomplete_details":null,"instructions":"You are a helpful assistant.","max_output_tokens":null,"model":"gpt-6-astra","output":[],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":null,"user":null,"metadata":{}},"sequence_number":1}
event: response.output_item.added
data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"in_progress","role":"assistant","content":[]},"sequence_number":2}
event: response.content_part.added
data: {"type":"response.content_part.added","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"part":{"type":"output_text","text":"","annotations":[],"logprobs":[]},"sequence_number":3}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"Hi","sequence_number":4,"logprobs":[]}
: Intermediate response events omitted.
event: response.output_text.done
data: {"type":"response.output_text.done","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"text":"Hi there! How can I assist you today?","sequence_number":10,"logprobs":[]}
event: response.content_part.done
data: {"type":"response.content_part.done","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"part":{"type":"output_text","text":"Hi there! How can I assist you today?","annotations":[],"logprobs":[]},"sequence_number":11}
event: response.output_item.done
data: {"type":"response.output_item.done","output_index":0,"item":{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"Hi there! How can I assist you today?","annotations":[],"logprobs":[]}]},"sequence_number":12}
event: response.completed
data: {"type":"response.completed","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","access_programs":null,"created_at":1741290958,"status":"completed","error":null,"incomplete_details":null,"instructions":"You are a helpful assistant.","max_output_tokens":null,"model":"gpt-6-astra","output":[{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"Hi there! How can I assist you today?","annotations":[],"logprobs":[]}]}],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":{"input_tokens":37,"output_tokens":11,"output_tokens_details":{"reasoning_tokens":0},"total_tokens":48,"input_tokens_details":{"cached_tokens":0,"cache_write_tokens":0}},"user":null,"metadata":{}},"sequence_number":13}
文本输入
例中文字:讲一个关于独角兽的三句话睡前故事。
## 从环境变量读取 API 密钥,按需替换示例资源标识。
curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-6-astra",
"input": "Tell me a three sentence bedtime story about a unicorn."
}'
响应示例
例中文字:银色月光下,宁静树林中的独角兽Lumina发现了映照星辰的隐秘水池。她把角浸入水中,池水开始闪烁,显现出通往无尽夜空魔法世界的小径。她满怀惊奇,轻声许愿,希望每个心怀梦想的人都能找到自己的隐秘魔法;回望时,她的蹄印像星尘一样闪耀。
{
"id": "resp_67ccd2bed1ec8190b14f964abc0542670bb6a6b452d3795b",
"object": "response",
"access_programs": null,
"created_at": 1741476542,
"status": "completed",
"completed_at": 1741476543,
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-6-astra",
"output": [
{
"type": "message",
"id": "msg_67ccd2bf17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "In a peaceful grove beneath a silver moon, a unicorn named Lumina discovered a hidden pool that reflected the stars. As she dipped her horn into the water, the pool began to shimmer, revealing a pathway to a magical realm of endless night skies. Filled with wonder, Lumina whispered a wish for all who dream to find their own hidden magic, and as she glanced back, her hoofprints sparkled like stardust.",
"annotations": [],
"logprobs": []
}
]
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 36,
"input_tokens_details": {
"cached_tokens": 0,
"cache_write_tokens": 0
},
"output_tokens": 87,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 123
},
"user": null,
"metadata": {}
}
网页搜索
例中文字:今天有什么积极的新闻?
## 从环境变量读取 API 密钥,按需替换示例资源标识。
curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-6-astra",
"tools": [{ "type": "web_search_preview" }],
"input": "What was a positive news story from today?"
}'
响应示例
例中文字:截至原示例所称的今天(2025年3月9日),一条值得关注的积极新闻是……
{
"id": "resp_67ccf18ef5fc8190b16dbee19bc54e5f087bb177ab789d5c",
"object": "response",
"access_programs": null,
"created_at": 1741484430,
"status": "completed",
"completed_at": 1741484431,
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-6-astra",
"output": [
{
"type": "web_search_call",
"id": "ws_67ccf18f64008190a39b619f4c8455ef087bb177ab789d5c",
"status": "completed"
},
{
"type": "message",
"id": "msg_67ccf190ca3881909d433c50b1f6357e087bb177ab789d5c",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "As of today, March 9, 2025, one notable positive news story...",
"annotations": [
{
"type": "url_citation",
"start_index": 442,
"end_index": 557,
"url": "https://.../?utm_source=chatgpt.com",
"title": "..."
},
{
"type": "url_citation",
"start_index": 962,
"end_index": 1077,
"url": "https://.../?utm_source=chatgpt.com",
"title": "..."
},
{
"type": "url_citation",
"start_index": 1336,
"end_index": 1451,
"url": "https://.../?utm_source=chatgpt.com",
"title": "..."
}
],
"logprobs": []
}
]
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [
{
"type": "web_search_preview",
"domains": [],
"search_context_size": "medium",
"user_location": {
"type": "approximate",
"city": null,
"country": "US",
"region": null,
"timezone": null
}
}
],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 328,
"input_tokens_details": {
"cached_tokens": 0,
"cache_write_tokens": 0
},
"output_tokens": 356,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 684
},
"user": null,
"metadata": {}
}
TRAE-AI编程


更多建议: