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


更多建议: