文档中心 / OpenAI请求格式（推荐） / Openai Responses 接口请求体参数

Openai Responses 接口请求体参数

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。

其他相关项

属性 类型 必需 描述
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)

属性 类型 必需 描述
type 字符串 是 文件搜索工具的类型，始终为 file_search。
vector_store_ids 数组 是 要搜索的向量存储ID列表。
filters 对象 否 要应用的过滤器。
max_num_results 整数 否 返回的最大结果数 (1-50)。
ranking_options 对象 否 搜索排名选项。

过滤器类型 (Filter Types)

  • 比较过滤器 (Comparison Filter)

:

  • key (字符串): 要比较的键。
  • type (字符串): 比较运算符 (eq, ne, gt, gte, lt, lte)。

  • value (字符串/数字/布尔值): 要比较的值。

  • 复合过滤器 (Compound Filter)

:

  • filters (数组): 要组合的过滤器数组。
  • type (字符串): 操作类型 (and 或 or)。

排名选项 (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

  • 类型: 字符串
  • 必需: 否
  • 描述: 表示最终用户的唯一标识符，用于监控和检测滥用行为。