参考文档
完整 OpenAPI SchemaPOST
/v1/responses请求参数
Responses API 支持生成文本、执行工具以及处理多轮对话。它同时支持同步请求和流式传输以实现实时输出。
参数可以通过 application/json 或 application/x-www-form-urlencoded 格式提供。
请求头
| 请求头 | 值 | 必填？ |
|---|---|---|
Content-Type | application/json 或 application/x-www-form-urlencoded | 是 |
Authorization | 认证令牌，通常为 Bearer [secret token] 格式 | 是 |
请求体
Body Parameters
model
string
用于此请求的模型，例如 'gpt-5.2'。
input
为此请求的范围提供给模型的上下文。可以是字符串或输入项数组。如果提供字符串，则将其解释为用户消息。
previous_response_id
string
用作此请求上一轮的响应的 ID。
include
Values
| reasoning.encrypted_content | 包含加密的推理内容，以便在后续请求中重新填充 |
| message.output_text.logprobs | 在助手消息中包含采样的对数概率 |
tools
array ofFunctionToolParam
模型在生成响应时可能调用的工具列表。
tool_choice
控制模型应使用哪个工具（如果有）。
metadata
可以附加到对象的 16 个键值对。这可用于以结构化格式存储有关对象的额外信息，并通过 API 或控制台查询对象。
键为字符串，最大长度为 64 个字符。值为字符串，最大长度为 512 个字符。
text
文本输出的配置选项。
temperature
number
要使用的采样温度，介于 0 和 2 之间。较高的值会使输出更加随机。
top_p
number
核采样参数，介于 0 和 1 之间。模型仅考虑具有顶部累积概率的 token。
presence_penalty
number
根据新 token 是否已出现在迄今为止的文文中来对其进行惩罚。
frequency_penalty
number
根据新 token 在迄今为止的文本中的频率来对其进行惩罚。
parallel_tool_calls
boolean
模型是否可以并行调用多个工具。
stream
boolean
是否以服务器发送事件的形式流式传输响应事件。
stream_options
控制流式响应行为的选项。
background
boolean
是否在后台运行请求并立即返回。
max_output_tokens
integer
模型为此响应可能生成的最大 token 数。
max_tool_calls
integer
模型在生成响应时可能发起的最大工具调用次数。
reasoning
推理行为的配置选项。
safety_identifier
string
用于安全监控和滥用检测的稳定标识符。
prompt_cache_key
string
从提示缓存读取或写入时使用的密钥。
truncation
控制当输入超出模型上下文窗口时服务如何截断输入。
Values
| auto | 让服务决定如何截断 |
| disabled | 禁用服务截断。超过模型上下文限制的上下文将导致 400 错误 |
instructions
string
用于指导模型处理此请求的额外指令。
store
boolean
是否存储响应以便稍后检索。
service_tier
用于此请求的服务层级。
Values
| auto | 根据当前账户状态自动选择服务层级 |
| default | 选择默认服务层级 |
| flex | 选择弹性服务层级 |
| priority | 选择优先服务层级 |
top_logprobs
integer
在每个位置返回的最可能的 token 数量，以及它们的对数概率。
响应参数
响应头
| 响应头 | 值 | 必填？ |
|---|---|---|
Content-Type | application/json 或 text/event-stream | 是 |
响应体
响应
id
string
required
创建的响应的唯一 ID。
object
"response"
required
对象类型，始终为 `response`。
created_at
integer
required
创建响应时的 Unix 时间戳（秒）。
completed_at
required
integer
响应完成时的 Unix 时间戳（秒）（如果已完成）。
status
string
required
为响应设置的状态。
关于响应为何不完整的详细信息（如适用）。
model
string
required
生成此响应的模型。
previous_response_id
required
string
引用的链中的上一个响应的 ID（如果有）。
instructions
required
string
用于指导模型生成此响应的额外指令。
模型生成的输出项。
响应失败时发生的错误。
响应生成期间模型可用的工具。
当输入超出模型上下文窗口时服务如何截断输入。
Values
| auto | 让服务决定如何截断 |
| disabled | 禁用服务截断。超过模型上下文限制的上下文将导致 400 错误 |
parallel_tool_calls
boolean
required
模型是否被允许并行调用多个工具。
使用的文本输出配置选项。
top_p
number
required
用于此响应的核采样参数。
presence_penalty
number
required
用于根据新 token 是否已出现在迄今为止的文本中来对其进行惩罚的存在惩罚。
frequency_penalty
number
required
用于根据新 token 在迄今为止的文本中的频率来对其进行惩罚的频率惩罚。
top_logprobs
integer
required
在每个位置返回的最可能的 token 数量，以及它们的对数概率。
temperature
number
required
用于此响应的采样温度。
为此响应生成的推理配置和输出。
为响应记录的 token 使用统计信息（如果有）。
max_output_tokens
required
integer
模型被允许为此响应生成的最大 token 数。
max_tool_calls
required
integer
模型在生成响应时被允许发起的最大工具调用次数。
store
boolean
required
此响应是否已被存储以便稍后检索。
background
boolean
required
此请求是否在后台运行。
service_tier
string
required
用于此响应的服务层级。
metadata
unknown
required
与响应关联的开发者定义的元数据。
safety_identifier
required
string
用于安全监控和滥用检测的稳定标识符。
prompt_cache_key
required
string
用于从提示缓存读取或写入的密钥。
API 对象
Enums
FunctionCallOutputStatusEnum
与 `FunctionCallStatus` 类似。为兼容性，此处允许所有三个选项，但实际上由于这些项将由开发者提供，因此应仅使用 `completed`。
Values
| in_progress | — |
| completed | — |
| incomplete | — |
FunctionCallStatus
Values
| in_progress | 模型正在对此项进行采样 |
| completed | 模型已完成对此项的采样 |
| incomplete | 模型在采样此项目过程中被中断。例如，当模型遇到停止令牌或用尽输出 token 预算时可能发生这种情况 |
ImageDetail
Values
| low | 将模型限制为较低分辨率的图像版本 |
| high | 允许模型"看到"更高分辨率的图像版本，通常会增加输入 token 成本 |
| auto | 自动选择细节级别 |
IncludeEnum
Values
| reasoning.encrypted_content | 包含加密的推理内容，以便在后续请求中重新填充 |
| message.output_text.logprobs | 在助手消息中包含采样的对数概率 |
MessageRole
Values
| user | 对话中最终用户的输入 |
| assistant | 对话中模型生成的内容 |
| system | 设置全局行为的系统级指令 |
| developer | 开发者提供的指导，用于塑造助手的行为 |
MessageStatus
Values
| in_progress | 模型正在对此项进行采样 |
| completed | 模型已完成对此项的采样 |
| incomplete | 模型在采样此项目过程中被中断。例如，当模型遇到停止令牌或用尽输出 token 预算时可能发生这种情况 |
ReasoningEffortEnum
Values
| none | 限制模型在发出最终答案之前进行任何推理 |
| low | 使用较低的推理努力以加快响应速度 |
| medium | 使用平衡的推理努力 |
| high | 使用更高的推理努力以提高答案质量 |
| xhigh | 使用可用的最大推理努力 |
ReasoningSummaryEnum
Values
| concise | 输出推理内容的简明摘要 |
| detailed | 输出推理内容的详细摘要 |
| auto | 允许模型决定何时总结 |
ServiceTierEnum
Values
| auto | 根据当前账户状态自动选择服务层级 |
| default | 选择默认服务层级 |
| flex | 选择弹性服务层级 |
| priority | 选择优先服务层级 |
ToolChoiceValueEnum
Values
| none | 限制模型调用任何工具 |
| auto | 让模型从提供的工具集中选择工具 |
| required | 要求模型调用工具 |
TruncationEnum
Values
| auto | 让服务决定如何截断 |
| disabled | 禁用服务截断。超过模型上下文限制的上下文将导致 400 错误 |
VerbosityEnum
Values
| low | 指示模型输出较简短的最终响应 |
| medium | 使用模型的默认详细程度设置 |
| high | 指示模型输出更详细的最终响应 |
Unions
Annotation
应用于输出文本片段的标注。
ItemField
表示消息、工具调用、工具输出、推理或其他响应元素的项。
ItemParam
ResponsesToolParam
SpecificToolChoiceParam
TextFormatParam
Tool
可用于生成响应的工具。
ToolChoiceParam
控制模型应使用哪个工具（如果有）。
Objects
AllowedToolChoice
type
"allowed_tools"
required
toolsFunctionToolChoice[]
required
modeenum
required
Values
| none | 限制模型调用任何工具 |
| auto | 让模型从提供的工具集中选择工具 |
| required | 要求模型调用工具 |
AllowedToolsParam
type
"allowed_tools"
required
工具选择类型。始终为 `allowed_tools`。
toolsSpecificToolChoiceParam[]
required
此请求允许使用的工具列表。
modeenum
如何从允许的工具集中选择工具。
Values
| none | 限制模型调用任何工具 |
| auto | 让模型从提供的工具集中选择工具 |
| required | 要求模型调用工具 |
AssistantMessageItemParam
id
string
此消息项的唯一 ID。
type
"message"
required
项类型。始终为 `message`。
role
"assistant"
required
消息作者的角色。始终为 `assistant`。
消息内容，为内容部分的数组。
status
string
消息项的状态。
DeveloperMessageItemParam
id
string
此消息项的唯一 ID。
type
"message"
required
项类型。始终为 `message`。
role
"developer"
required
消息角色。始终为 `developer`。
消息内容，为内容部分的数组。
status
string
消息项的状态。
EmptyModelParam
Error
生成响应时发生的错误。
codestring
required
返回的机器可读错误代码。
messagestring
required
返回的错误的人工可读描述。
FunctionCall
由模型生成的函数工具调用。
type
"function_call"
required
项的类型。始终为 `function_call`。
idstring
required
函数调用项的唯一 ID。
call_idstring
required
生成的函数工具调用的唯一 ID。
namestring
required
被调用的函数名称。
argumentsstring
required
生成的参数 JSON 字符串。
statusenum
required
记录的函数调用项的状态。
Values
| in_progress | 模型正在对此项进行采样 |
| completed | 模型已完成对此项的采样 |
| incomplete | 模型在采样此项目过程中被中断。例如，当模型遇到停止令牌或用尽输出 token 预算时可能发生这种情况 |
FunctionCallItemParam
id
string
此函数工具调用的唯一 ID。
call_idstring
required
模型生成的函数工具调用的唯一 ID。
type
"function_call"
required
项类型。始终为 `function_call`。
namestring
required
要调用的函数名称。
argumentsstring
required
函数参数，格式为 JSON 字符串。
status
函数工具调用的状态。
Values
| in_progress | 模型正在对此项进行采样 |
| completed | 模型已完成对此项的采样 |
| incomplete | 模型在采样此项目过程中被中断。例如，当模型遇到停止令牌或用尽输出 token 预算时可能发生这种情况 |
FunctionCallOutput
由工具返回的函数工具调用输出。
type
"function_call_output"
required
函数工具调用的输出的类型。始终为 `function_call_output`。
idstring
required
函数工具调用的输出的唯一 ID。当通过 API 返回此项时填充。
call_idstring
required
模型生成的函数工具调用的唯一 ID。
函数工具调用的输出，格式为 JSON 字符串。
statusenum
required
项的状态。可选值为 `in_progress`、`completed` 或 `incomplete`。当通过 API 返回项时填充。
Values
| in_progress | — |
| completed | — |
| incomplete | — |
FunctionCallOutputItemParam
函数工具调用的输出。
id
string
函数工具调用的输出的唯一 ID。当通过 API 返回此项时填充。
call_idstring
required
模型生成的函数工具调用的唯一 ID。
type
"function_call_output"
required
函数工具调用的输出的类型。始终为 `function_call_output`。
output
string
required
函数工具调用的文本、图片或文件输出。
status
项的状态。可选值为 `in_progress`、`completed` 或 `incomplete`。当通过 API 返回项时填充。
Values
| in_progress | 模型正在对此项进行采样 |
| completed | 模型已完成对此项的采样 |
| incomplete | 模型在采样此项目过程中被中断。例如，当模型遇到停止令牌或用尽输出 token 预算时可能发生这种情况 |
FunctionTool
定义模型可以选择调用的您自己代码中的函数。了解有关 [函数调用](https://platform.openai.com/docs/guides/function-calling) 的更多信息。
type
"function"
required
函数工具的类型。始终为 `function`。
namestring
required
要调用的函数名称。
description
string
required
函数的描述。由模型用于确定是否调用该函数。
parameters
object
required
描述函数参数的 JSON schema 对象。
strict
boolean
required
是否强制执行严格的参数验证。默认为 `true`。
FunctionToolChoice
type
"function"
required
namestring
FunctionToolParam
IncompleteDetails
关于响应为何不完整的详细信息。
reasonstring
required
响应无法完成的原因。
InputFileContent
发送给模型的文件输入。
type
"input_file"
required
输入项的类型。始终为 `input_file`。
filenamestring
发送给模型的文件名。
file_urlstring
发送给模型的文件 URL。
InputFileContentParam
发送给模型的文件输入。
type
"input_file"
required
输入项的类型。始终为 `input_file`。
filename
string
发送给模型的文件名。
file_data
string
发送给模型的文件的 base64 编码数据。
file_url
string
发送给模型的文件 URL。
InputImageContent
发送给模型的图片输入。了解 [图片输入](/docs/guides/vision)。
type
"input_image"
required
输入项的类型。始终为 `input_image`。
image_url
string
required
发送给模型的图片 URL。可以是完整限定 URL 或 data URL 中的 base64 编码图片。
detailenum
required
发送给模型的图片的详细级别。可选值为 `high`、`low` 或 `auto`。默认为 `auto`。
Values
| low | 将模型限制为较低分辨率的图像版本 |
| high | 允许模型"看到"更高分辨率的图像版本，通常会增加输入 token 成本 |
| auto | 自动选择细节级别 |
InputImageContentParamAutoParam
发送给模型的图片输入。了解 [图片输入](/docs/guides/vision)
type
"input_image"
required
输入项的类型。始终为 `input_image`。
image_url
string
发送给模型的图片 URL。可以是完整限定 URL 或 data URL 中的 base64 编码图片。
detail
发送给模型的图片的详细级别。可选值为 `high`、`low` 或 `auto`。默认为 `auto`。
Values
| low | 将模型限制为较低分辨率的图像版本 |
| high | 允许模型"看到"更高分辨率的图像版本，通常会增加输入 token 成本 |
| auto | 自动选择细节级别 |
InputTextContent
发送给模型的文本输入。
type
"input_text"
required
输入项的类型。始终为 `input_text`。
textstring
required
发送给模型的文本输入。
InputTextContentParam
发送给模型的文本输入。
type
"input_text"
required
输入项的类型。始终为 `input_text`。
textstring
required
发送给模型的文本输入。
InputTokensDetails
记录的输入 token 使用情况的细分。
cached_tokensinteger
required
从缓存提供的输入 token 数量。
InputVideoContent
表示发送给模型的视频输入的内容块。
type
"input_video"
required
输入内容的类型。始终为 `input_video`。
video_urlstring
required
解析为视频文件的 base64 或远程 URL。
ItemReferenceParam
用于引用项的内部标识符。
type
"item_reference"
要引用的项的类型。始终为 `item_reference`。
idstring
required
要引用的项的 ID。
JsonObjectResponseFormat
type
"json_object"
required
JsonSchemaResponseFormat
type
"json_schema"
required
namestring
required
description
string
required
schemaunknown
required
strictboolean
required
JsonSchemaResponseFormatParam
type
"json_schema"
正在定义的响应格式类型。始终为 `json_schema`。
descriptionstring
响应格式的用途描述，由模型用于确定如何以该格式响应。
namestring
响应格式的名称。必须为 a-z、A-Z、0-9 或包含下划线和短横线，最大长度为 64。
schemaobject
响应格式的 schema，描述为 JSON Schema 对象。
strict
boolean
是否在生成输出时启用严格的 schema 遵守。如果设置为 true，模型将始终遵循 `schema` 字段中定义的确切 schema。当 `strict` 为 `true` 时，仅支持 JSON Schema 的子集。
LogProb
token 的对数概率。
tokenstring
required
logprobnumber
required
bytesinteger[]
required
top_logprobsTopLogProb[]
required
Message
发送给模型或来自模型的消息。
type
"message"
required
消息的类型。始终设置为 `message`。
idstring
required
消息的唯一 ID。
statusenum
required
项的状态。可选值为 `in_progress`、`completed` 或 `incomplete`。当通过 API 返回项时填充。
Values
| in_progress | 模型正在对此项进行采样 |
| completed | 模型已完成对此项的采样 |
| incomplete | 模型在采样此项目过程中被中断。例如，当模型遇到停止令牌或用尽输出 token 预算时可能发生这种情况 |
roleenum
required
消息的角色。可选值为 `unknown`、`user`、`assistant`、`system`、`critic`、`discriminator`、`developer` 或 `tool`。
Values
| user | 对话中最终用户的输入 |
| assistant | 对话中模型生成的内容 |
| system | 设置全局行为的系统级指令 |
| developer | 开发者提供的指导，用于塑造助手的行为 |
contentInputTextContent[]
required
消息的内容
MetadataParam
可以附加到对象的 16 个键值对。这可用于以结构化格式存储有关对象的额外信息，并通过 API 或控制台查询对象。
键为字符串，最大长度为 64 个字符。值为字符串，最大长度为 512 个字符。
OutputTextContent
来自模型的文本输出。
type
"output_text"
required
输出文本的类型。始终为 `output_text`。
textstring
required
来自模型的文本输出。
annotationsAnnotation[]
required
文本输出的标注。
logprobsLogProb[]
required
OutputTextContentParam
type
"output_text"
required
内容类型。始终为 `output_text`。
textstring
required
文本内容。
annotations
与文本内容关联的引用。
OutputTokensDetails
记录的输出 token 使用情况的细分。
reasoning_tokensinteger
required
归属于推理的输出 token 数量。
Reasoning
用于响应的推理配置和元数据。
为模型请求的推理力度（如果指定）。
Values
| none | 限制模型在发出最终答案之前进行任何推理 |
| low | 使用较低的推理努力以加快响应速度 |
| medium | 使用平衡的推理努力 |
| high | 使用更高的推理努力以提高答案质量 |
| xhigh | 使用可用的最大推理努力 |
模型生成的推理摘要（如果有）。
Values
| concise | 输出推理内容的简明摘要 |
| detailed | 输出推理内容的详细摘要 |
| auto | 允许模型决定何时总结 |
ReasoningBody
由模型生成的推理项。
type
"reasoning"
required
项的类型。始终为 `reasoning`。
idstring
required
推理项的唯一 ID。
contentInputTextContent[]
生成的推理内容。
summaryInputTextContent[]
required
生成的推理摘要内容。
encrypted_contentstring
生成的加密推理内容。
ReasoningItemParam
id
string
此推理项的唯一 ID。
type
"reasoning"
required
项类型。始终为 `reasoning`。
summaryReasoningSummaryContentParam[]
required
与此项关联的推理摘要内容。
contentunknown
encrypted_content
string
推理内容的加密表示形式。
ReasoningParam
**仅限 gpt-5 和 o 系列模型** [推理模型](https://platform.openai.com/docs/guides/reasoning)的配置选项。
effort
控制模型应应用的推理力度。更高的力度可能会增加延迟和成本。
Values
| none | 限制模型在发出最终答案之前进行任何推理 |
| low | 使用较低的推理努力以加快响应速度 |
| medium | 使用平衡的推理努力 |
| high | 使用更高的推理努力以提高答案质量 |
| xhigh | 使用可用的最大推理努力 |
ReasoningSummaryContentParam
type
"summary_text"
required
内容类型。始终为 `summary_text`。
textstring
required
推理摘要文本。
ReasoningTextContent
来自模型的推理文本。
type
"reasoning_text"
required
推理文本的类型。始终为 `reasoning_text`。
textstring
required
来自模型的推理文本。
RefusalContent
来自模型的拒绝响应。
type
"refusal"
required
拒绝的类型。始终为 `refusal`。
refusalstring
required
来自模型的拒绝解释。
RefusalContentParam
type
"refusal"
required
内容类型。始终为 `refusal`。
refusalstring
required
拒绝文本。
SpecificFunctionParam
type
"function"
required
要调用的工具。始终为 `function`。
namestring
required
要调用的函数工具的名称。
StreamOptionsParam
控制流式响应行为的选项。
include_obfuscationboolean
是否在流式输出中混淆敏感信息。默认为 `true`。
SummaryTextContent
来自模型的摘要文本。
type
"summary_text"
required
对象的类型。始终为 `summary_text`。
textstring
required
迄今为止模型推理输出的摘要。
SystemMessageItemParam
id
string
此消息项的唯一 ID。
type
"message"
required
项类型。始终为 `message`。
role
"system"
required
消息角色。始终为 `system`。
消息内容，为内容部分的数组。
status
string
消息项的状态。
TextContent
文本内容。
type
"text"
required
textstring
required
TextField
verbosityenum
Values
| low | 指示模型输出较简短的最终响应 |
| medium | 使用模型的默认详细程度设置 |
| high | 指示模型输出更详细的最终响应 |
TextParam
文本输出的格式配置。
verbosityenum
控制生成文本输出的详细程度。
Values
| low | 指示模型输出较简短的最终响应 |
| medium | 使用模型的默认详细程度设置 |
| high | 指示模型输出更详细的最终响应 |
TextResponseFormat
type
"text"
required
TopLogProb
token 的顶部对数概率。
tokenstring
required
logprobnumber
required
bytesinteger[]
required
UrlCitationBody
用于生成模型响应的 Web 资源的引用。
type
"url_citation"
required
URL 引用的类型。始终为 `url_citation`。
urlstring
required
Web 资源的 URL。
start_indexinteger
required
消息中 URL 引用的第一个字符的索引。
end_indexinteger
required
消息中 URL 引用的最后一个字符的索引。
titlestring
required
Web 资源的标题。
UrlCitationParam
type
"url_citation"
required
引用类型。始终为 `url_citation`。
start_indexinteger
required
消息中引用的第一个字符的索引。
end_indexinteger
required
消息中引用的最后一个字符的索引。
urlstring
required
被引用资源的 URL。
titlestring
required
被引用资源的标题。
Usage
为响应记录的 token 使用统计信息。
input_tokensinteger
required
用于生成响应的输入 token 数量。
output_tokensinteger
required
模型生成的输出 token 数量。
total_tokensinteger
required
使用的 token 总数。
input_tokens_detailsInputTokensDetails
required
记录的输入 token 使用情况的细分。
output_tokens_detailsOutputTokensDetails
required
记录的输出 token 使用情况的细分。
UserMessageItemParam
id
string
此消息项的唯一 ID。
type
"message"
required
项类型。始终为 `message`。
role
"user"
required
消息角色。始终为 `user`。
content
required
消息内容，为内容部分的数组。
status
string
消息项的状态。