Openai API官方网址(以官方为准)
https://platform.openai.com/docs/api-reference/responses
input
- 类型:
字符串 或 数组
- 必需: 是
- 描述: 提供给模型的文本、图像或文件输入，用于生成响应。
input 的可能类型
| 类型 |
描述 |
| 字符串 |
文本输入，相当于具有用户角色的文本输入输入项。 |
| 数组 |
包含不同内容类型的一个或多个输入项列表。 |
输入消息对象 (Input Message Object)
当 input 是一个数组时，其元素为输入消息对象。
| 属性 |
类型 |
必需 |
描述 |
content |
字符串 或 数组 |
是 |
提供给模型的文本、图像或音频输入。也可以包含之前的助手响应。 |
role |
字符串 |
是 |
输入消息的角色。可选值：user、assistant、system 或 developer。 |
type |
字符串 |
否 |
输入消息的类型，始终为 message。 |
内容项类型 (Content Item Types)
文本输入 (Text Input)
| 属性 |
类型 |
必需 |
描述 |
text |
字符串 |
是 |
提供给模型的文本输入。 |
type |
字符串 |
是 |
输入项的类型，始终为 input_text。 |
图像输入 (Image Input)
| 属性 |
类型 |
必需 |
描述 |
detail |
字符串 |
否 |
要发送给模型的图像的详细级别。可选值：high、low 或 auto。默认为 auto。 |
type |
字符串 |
是 |
输入项的类型，始终为 input_image。 |
file_id |
字符串 |
否 |
要发送给模型的文件ID。 |
image_url |
字符串 |
否 |
要发送给模型的图像URL。可以是完整的URL或数据URL中的base64编码图像。 |
文件输入 (File Input)
| 属性 |
类型 |
必需 |
描述 |
type |
字符串 |
是 |
输入项的类型，始终为 input_file。 |
file_data |
字符串 |
否 |
要发送给模型的文件内容。 |
file_id |
字符串 |
否 |
要发送给模型的文件ID。 |
filename |
字符串 |
否 |
要发送给模型的文件名。 |
API 输出项类型
输出文本 (Output Text)
| 属性 |
类型 |
必需 |
描述 |
text |
字符串 |
是 |
模型生成的文本输出。 |
type |
字符串 |
是 |
输出项的类型，始终为 output_text。 |
annotations |
数组 |
是 |
文本输出的注释。 |
注释类型 (Annotation Types)
文件引用 (File Citation)
| 属性 |
类型 |
必需 |
描述 |
file_id |
字符串 |
是 |
文件的ID。 |
index |
整数 |
是 |
文件在文件列表中的索引。 |
type |
字符串 |
是 |
文件引用的类型，始终为 file_citation。 |
URL引用 (URL Citation)
| 属性 |
类型 |
必需 |
描述 |
end_index |
整数 |
是 |
URL引用在消息中的最后一个字符的索引。 |
start_index |
整数 |
是 |
URL引用在消息中的第一个字符的索引。 |
title |
字符串 |
是 |
网络资源的标题。 |
type |
字符串 |
是 |
URL引用的类型，始终为 url_citation。 |
url |
字符串 |
是 |
网络资源的URL。 |
文件路径 (File Path)
| 属性 |
类型 |
必需 |
描述 |
file_id |
字符串 |
是 |
文件的ID。 |
index |
整数 |
是 |
文件在文件列表中的索引。 |
type |
字符串 |
是 |
文件路径的类型，始终为 file_path。 |
拒绝响应 (Refusal Response)
| 属性 |
类型 |
必需 |
描述 |
refusal |
字符串 |
是 |
模型的拒绝解释。 |
type |
字符串 |
是 |
拒绝的类型，始终为 refusal。 |
工具调用类型 (Tool Call Types)
文件搜索工具调用 (File Search Tool Call)
| 属性 |
类型 |
必需 |
描述 |
id |
字符串 |
是 |
文件搜索工具调用的唯一ID。 |
queries |
数组 |
是 |
用于搜索文件的查询。 |
status |
字符串 |
是 |
文件搜索工具调用的状态。可能值：in_progress、searching、incomplete 或 failed。 |
type |
字符串 |
是 |
文件搜索工具调用的类型，始终为 file_search_call。 |
results |
数组 或 null |
否 |
文件搜索工具调用的结果。 |
网络搜索工具调用 (Web Search Tool Call)
| 属性 |
类型 |
必需 |
描述 |
id |
字符串 |
是 |
网络搜索工具调用的唯一ID。 |
status |
字符串 |
是 |
网络搜索工具调用的状态。 |
type |
字符串 |
是 |
网络搜索工具调用的类型，始终为 web_search_call。 |
函数工具调用 (Function Tool Call)
| 属性 |
类型 |
必需 |
描述 |
arguments |
字符串 |
是 |
传递给函数的参数的JSON字符串。 |
call_id |
字符串 |
是 |
模型生成的函数工具调用的唯一ID。 |
name |
字符串 |
是 |
要运行的函数的名称。 |
type |
字符串 |
是 |
函数工具调用的类型，始终为 function_call。 |
id |
字符串 |
否 |
函数工具调用的唯一ID。 |
status |
字符串 |
否 |
项目的状态。可能值：in_progress、completed或incomplete。 |
计算机工具调用 (Computer Tool Call)
| 属性 |
类型 |
必需 |
描述 |
action |
对象 |
是 |
计算机交互的操作，如点击、拖拽等。 |
call_id |
字符串 |
是 |
响应工具调用输出时使用的标识符。 |
id |
字符串 |
是 |
计算机调用的唯一ID。 |
pending_safety_checks |
数组 |
是 |
计算机调用的待处理安全检查。 |
status |
字符串 |
是 |
项目的状态。可能值：in_progress、completed或incomplete。 |
type |
字符串 |
是 |
计算机调用的类型，始终为 computer_call。 |
计算机操作类型 (Computer Action Types)
| 操作类型 |
描述 |
click |
鼠标点击操作 |
double_click |
鼠标双击操作 |
drag |
拖拽操作 |
keypress |
按键操作 |
move |
鼠标移动操作 |
screenshot |
屏幕截图操作 |
scroll |
滚动操作 |
type |
文本输入操作 |
wait |
等待操作 |
工具调用输出类型 (Tool Call Output Types)
计算机工具调用输出 (Computer Tool Call Output)
| 属性 |
类型 |
必需 |
描述 |
call_id |
字符串 |
是 |
产生输出的计算机工具调用的ID。 |
output |
对象 |
是 |
用于计算机使用工具的计算机屏幕截图图像。 |
type |
字符串 |
是 |
计算机工具调用输出的类型，始终为 computer_call_output。 |
acknowledged_safety_checks |
数组 |
否 |
API报告的已被开发者确认的安全检查。 |
id |
字符串 |
否 |
计算机工具调用输出的ID。 |
status |
字符串 |
否 |
输入消息的状态。可能值：in_progress、completed或incomplete。 |
函数工具调用输出 (Function Tool Call Output)
| 属性 |
类型 |
必需 |
描述 |
call_id |
字符串 |
是 |
模型生成的函数工具调用的唯一ID。 |
output |
字符串 |
是 |
函数工具调用输出的JSON字符串。 |
type |
字符串 |
是 |
函数工具调用输出的类型，始终为 function_call_output。 |
id |
字符串 |
否 |
函数工具调用输出的唯一ID。 |
status |
字符串 |
否 |
项目的状态。可能值：in_progress、completed或incomplete。 |
其他相关项
推理相关项 (Reasoning-related Items)
| 属性 |
类型 |
必需 |
描述 |
id |
字符串 |
是 |
推理内容的唯一标识符。 |
summary |
数组 |
是 |
推理文本内容。 |
type |
字符串 |
是 |
对象的类型，始终为 reasoning。 |
encrypted_content |
字符串 或 null |
否 |
推理项的加密内容 - 当使用 reasoning.encrypted_content 包含参数生成响应时填充。 |
status |
字符串 |
否 |
项目的状态。可能值：in_progress、completed或incomplete。 |
推理摘要 (Reasoning Summary)
| 属性 |
类型 |
必需 |
描述 |
text |
字符串 |
是 |
模型生成响应时使用的推理的简短摘要。 |
type |
字符串 |
是 |
对象的类型，始终为 summary_text。 |
项目引用 (Item Reference)
| 属性 |
类型 |
必需 |
描述 |
id |
字符串 |
是 |
要引用的项目的ID。 |
type |
字符串 |
否 |
要引用的项目类型，始终为 item_reference。 |
顶层请求参数
model
- 类型:
字符串
- 必需: 是
- 描述: 用于生成响应的模型ID，例如
gpt-4.1 或 o3。
include
-
类型: 数组 或 null
-
必需: 否
-
描述: 指定要在模型响应中包含的附加输出数据。
-
支持的值
:
| 值 |
描述 |
file_search_call.results |
包含文件搜索工具调用的搜索结果。 |
message.input_image.image_url |
包含输入消息中的图像URL。 |
computer_call_output.output.image_url |
包含电脑调用输出中的图像URL。 |
reasoning.encrypted_content |
在推理项输出中包含推理标记的加密版本。 |
instructions
- 类型:
字符串 或 null
- 必需: 否
- 描述: 作为模型上下文中的第一项插入系统（或开发者）消息。当与
previous_response_id 一起使用时，前一个响应中的指令不会被带到下一个响应。
max_output_tokens
- 类型:
整数 或 null
- 必需: 否
- 描述: 可以为响应生成的令牌数量的上限，包括可见输出令牌和推理令牌。
metadata
- 类型:
对象
- 必需: 否
- 描述: 可以附加到对象的16个键值对集合。键最大长度64字符，值最大长度512字符。
parallel_tool_calls
- 类型:
布尔值 或 null
- 必需: 否
- 默认值:
true
- 描述: 是否允许模型并行运行工具调用。
previous_response_id
- 类型:
字符串 或 null
- 必需: 否
- 描述: 模型的前一个响应的唯一ID，用于创建多轮对话。
reasoning
-
类型: 对象 或 null
-
必需: 否
-
描述
: (仅适用于o系列模型) 推理模型的配置选项。
| 属性 |
类型 |
必需 |
描述 |
effort |
字符串 或 null |
否 |
推理的努力程度。可选值: low, medium, high。默认为 medium。 |
summary |
字符串 或 null |
否 |
模型执行的推理摘要。可选值: auto, concise, detailed。 |
generate_summary |
字符串 或 null |
否 |
已弃用: 请使用 summary 替代。 |
service_tier
-
类型: 字符串 或 null
-
必需: 否
-
默认值: auto
-
描述
: 指定用于处理请求的延迟层级。
| 值 |
描述 |
auto |
如果项目启用了 Scale tier，则使用 scale tier 信用，否则使用默认服务层级。 |
default |
请求将使用默认服务层级处理。 |
flex |
请求将使用 Flex Processing 服务层级处理。 |
store
- 类型:
布尔值 或 null
- 必需: 否
- 默认值:
true
- 描述: 是否存储生成的模型响应以供以后通过 API 检索。
stream
- 类型:
布尔值 或 null
- 必需: 否
- 默认值:
false
- 描述: 如果设置为
true，模型响应数据将使用服务器发送的事件流式传输到客户端。
temperature
- 类型:
数字 或 null
- 必需: 否
- 默认值:
1
- 描述: 要使用的采样温度，介于 0 和 2 之间。建议更改此值或
top_p，但不要同时更改。
text
-
类型: 对象
-
必需: 否
-
描述: 模型文本响应的配置选项。
| 属性 |
类型 |
必需 |
描述 |
format |
对象 |
否 |
指定模型必须输出的格式。 |
{ "type": "json_schema" }: 启用结构化输出，模型将匹配您提供的JSON模式。{ "type": "text" }: 默认格式，纯文本。{ "type": "json_object" }: (不推荐用于gpt-4o及更新模型) 启用较旧的JSON模式。
文本格式类型 (Text Format Types)
文本 (Text)
| 属性 |
类型 |
必需 |
描述 |
type |
字符串 |
是 |
定义的响应格式类型。始终为 text。 |
JSON模式 (JSON Schema)
| 属性 |
类型 |
必需 |
描述 |
name |
字符串 |
是 |
响应格式的名称 (a-z, A-Z, 0-9, _, -), 最大长度64。 |
schema |
对象 |
是 |
描述为JSON Schema对象的响应格式模式。 |
type |
字符串 |
是 |
定义的响应格式类型。始终为 json_schema。 |
description |
字符串 |
否 |
响应格式用途的描述。 |
strict |
布尔值 或 null |
否 |
是否启用严格模式。默认为 false。 |
JSON对象 (JSON Object)
| 属性 |
类型 |
必需 |
描述 |
type |
字符串 |
是 |
定义的响应格式类型。始终为 json_object。 |
- 注意: 对于支持的模型，建议使用
json_schema。
tool_choice
- 类型:
字符串 或 对象
- 必需: 否
- 描述: 模型如何选择生成响应时使用的工具。
tool_choice 的可能类型
工具选择模式 (Tool choice mode) - (字符串类型)
| 值 |
描述 |
none |
模型不会调用任何工具。 |
auto |
模型可以在生成消息或调用工具之间选择。 |
required |
模型必须调用一个或多个工具。 |
托管工具 (Hosted tool) - (对象类型)
| 属性 |
类型 |
必需 |
描述 |
type |
字符串 |
是 |
模型应使用的托管工具类型。允许的值：file_search、web_search_preview、computer_use_preview。 |
函数工具 (Function tool) - (对象类型)
| 属性 |
类型 |
必需 |
描述 |
name |
字符串 |
是 |
要调用的函数名称。 |
type |
字符串 |
是 |
对于函数调用，类型始终为 function。 |
tools
- 类型:
数组
- 必需: 否
- 描述: 模型在生成响应时可能调用的工具数组。
工具类型 (Tool Types)
文件搜索工具 (File search)
| 属性 |
类型 |
必需 |
描述 |
type |
字符串 |
是 |
文件搜索工具的类型，始终为 file_search。 |
vector_store_ids |
数组 |
是 |
要搜索的向量存储ID列表。 |
filters |
对象 |
否 |
要应用的过滤器。 |
max_num_results |
整数 |
否 |
返回的最大结果数 (1-50)。 |
ranking_options |
对象 |
否 |
搜索排名选项。 |
过滤器类型 (Filter Types)
排名选项 (Ranking Options)
| 属性 |
类型 |
必需 |
描述 |
ranker |
字符串 |
否 |
文件搜索使用的排名器。 |
score_threshold |
数字 |
否 |
分数阈值 (0-1)。 |
函数工具 (Function)
| 属性 |
类型 |
必需 |
描述 |
type |
字符串 |
是 |
函数工具的类型，始终为 function。 |
name |
字符串 |
是 |
要调用的函数名称。 |
parameters |
对象 |
是 |
描述函数参数的JSON模式对象。 |
strict |
布尔值 |
是 |
是否强制严格参数验证。默认为 true。 |
description |
字符串 |
否 |
函数的描述。 |
网络搜索工具 (Web search preview)
| 属性 |
类型 |
必需 |
描述 |
type |
字符串 |
是 |
网络搜索工具的类型。可选值: web_search_preview 或 web_search_preview_2025_03_11。 |
search_context_size |
字符串 |
否 |
上下文窗口空间量指导。可选值: low, medium, high。默认为 medium。 |
user_location |
对象 |
否 |
用户的位置。 |
domains |
数组 |
否 |
限制搜索的域名列表。 |
用户位置 (User Location)
| 属性 |
类型 |
必需 |
描述 |
type |
字符串 |
是 |
位置近似类型。始终为 approximate。 |
city |
字符串 |
否 |
用户所在城市的自由文本输入。 |
country |
字符串 |
否 |
用户的两字母ISO国家代码。 |
region |
字符串 |
否 |
用户所在区域的自由文本输入。 |
timezone |
字符串 |
否 |
用户的IANA时区。 |
计算机使用工具 (Computer use preview)
| 属性 |
类型 |
必需 |
描述 |
type |
字符串 |
是 |
计算机使用工具的类型。始终为 computer_use_preview。 |
display_height |
整数 |
是 |
计算机显示器的高度。 |
display_width |
整数 |
是 |
计算机显示器的宽度。 |
environment |
字符串 |
是 |
要控制的计算机环境类型。 |
top_p
- 类型:
数字 或 null
- 必需: 否
- 默认值:
1
- 描述: 核采样，模型考虑具有 top_p 概率质量的标记结果。建议更改此值或
temperature，但不要同时更改。
truncation
-
类型: 字符串 或 null
-
必需: 否
-
默认值: disabled
-
描述
: 用于模型响应的截断策略。
| 值 |
描述 |
auto |
如果上下文超过模型的上下文窗口大小，模型将通过删除对话中间的输入项来截断。 |
disabled |
如果模型响应将超过模型的上下文窗口大小，请求将失败并显示400错误。 |
user
- 类型:
字符串
- 必需: 否
- 描述: 表示最终用户的唯一标识符，用于监控和检测滥用行为。