/v1/responses

创建一个模型响应。提供文本或图像输入来生成文本或JSON输出。让模型调用您自己的自定义代码或使用内置工具，如网络搜索或文件搜索，将您自己的数据作为模型响应的输入。

POST /v1/responses

cURL

cURL

curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-4.1",
    "input": "给我讲一个关于独角兽的三句话睡前故事。"
  }'

200

basic_response

{
  "id": "resp_67ccd2bed1ec8190b14f964abc0542670bb6a6b452d3795b",
  "object": "response",
  "created_at": 1741476542,
  "status": "completed",
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "model": "gpt-4.1-2025-04-14",
  "output": [
    {
      "type": "message",
      "id": "msg_67ccd2bf17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "人工智能（Artificial Intelligence, AI）是计算机科学的一个分支，致力于创建能够模拟人类智能的计算机系统。AI技术包括机器学习、深度学习、自然语言处理等多个领域，在医疗、金融、教育等行业都有广泛应用。",
          "annotations": []
        }
      ]
    }
  ],
  "parallel_tool_calls": true,
  "previous_response_id": null,
  "reasoning": {
    "effort": null,
    "summary": null
  },
  "store": true,
  "temperature": 1,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [],
  "top_p": 1,
  "truncation": "disabled",
  "usage": {
    "input_tokens": 12,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 150,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 162
  },
  "user": null,
  "metadata": {}
}

Authorizations

Authorization · string · header · required

ModelHub API密钥认证。在 Authorization HTTP Header 中包含您的 API-Key，格式为 Bearer {API_KEY}

Body

application/json

metadata · object

请求的元数据

top_logprobs · integer

一个介于0和20之间的整数，指定在每个token位置返回的最可能token的数量，每个token都有相关的对数概率。

Required range: 0 <= x <= 20

temperature · number | null · default: 1

采样温度，取值范围在0到2之间。较高的值（如0.8）会使输出更加随机，而较低的值（如0.2）会使输出更加集中和确定性。 通常建议仅调整temperature或top_p其中之一，不建议两者都修改。

Required range: 0 <= x <= 2

Example:

1

top_p · number | null · default: 1

核采样的替代方法，称为nucleus采样，模型考虑具有top_p概率质量的token结果。例如，0.1意味着只考虑构成前10%概率质量的token。 通常建议仅调整temperature或top_p其中之一，不建议两者都修改。

Required range: 0 <= x <= 1

Example:

1

user · string · deprecated

此字段正在被safety_identifier和prompt_cache_key替代。请使用prompt_cache_key来维持缓存优化。 用于您的终端用户的稳定标识符。用于提高缓存命中率，通过更好地分组类似请求，并帮助检测和防止滥用。

Example:

"user-1234"

safety_identifier · string

一个稳定的标识符，用于帮助检测可能违反使用政策的用户。ID应该是唯一标识每个用户的字符串。我们建议对用户名或电子邮件地址进行哈希处理，以避免向我们发送任何识别信息。

Example:

"safety-identifier-1234"

prompt_cache_key · string

用于缓存类似请求的响应以优化缓存命中率。替代user字段。

Example:

"prompt-cache-key-1234"

service_tier · enum<string>

服务层级

Available options: default, scale

previous_response_id · string | null

先前响应的唯一ID，用于创建多轮对话。了解更多关于对话状态。不能与conversation参数同时使用。

model · string

用于生成响应的模型ID，如gpt-4o或o3。OpenAI提供具有不同功能、性能特性和价格点的广泛模型。参考模型指南浏览和比较可用模型。

Example:

"gpt-4o"

reasoning · 推理配置 · object

gpt-5和o系列模型专用

推理模型的配置选项。

Show child attributes

background · boolean | null · default: false

是否在后台运行模型响应。了解更多。

max_output_tokens · integer | null

可以为响应生成的token数量的上限，包括可见输出token和推理token。

max_tool_calls · integer | null

在响应中可以处理的内置工具调用总数的最大值。此最大数量适用于所有内置工具调用，而不是每个单独工具。模型进一步尝试调用工具将被忽略。

text · object

模型文本响应的配置选项。可以是纯文本或结构化JSON数据。了解更多：

• 文本输入和输出
• 结构化输出

Show child attributes

tools · (函数工具 · object | 网络搜索工具 · object | 文件搜索工具 · object)[]

模型在生成响应时可以调用的工具数组。您可以通过设置tool_choice参数来指定使用哪个工具。

我们支持以下类别的工具：

• 内置工具：由OpenAI提供的扩展模型功能的工具，如网络搜索或文件搜索。了解更多关于内置工具。
• MCP工具：通过自定义MCP服务器或预定义连接器（如Google Drive和SharePoint）与第三方系统集成。了解更多关于MCP工具。
• 函数调用（自定义工具）：由您定义的函数，使模型能够使用强类型参数和输出调用您自己的代码。了解更多关于函数调用。您也可以使用自定义工具调用您自己的代码。

自定义函数工具，允许模型调用您定义的函数

函数工具

网络搜索工具

文件搜索工具

Show child attributes

tool_choice

模型在生成响应时应如何选择使用哪个工具（或工具）。请参阅tools参数了解如何指定模型可以调用的工具。

Available options: none, auto, required

prompt · string

用于生成或指导模型响应的提示文本。这是发送给模型的主要指令或问题。

Example:

"请解释一下机器学习的基本概念"

truncation · enum<string> | null · default: disabled

用于模型响应的截断策略。

• auto：如果此响应的输入超过模型的上下文窗口大小，模型将通过从对话开头删除项目来截断响应以适应上下文窗口。
• disabled（默认）：如果输入大小将超过模型的上下文窗口大小，请求将失败并返回400错误。

Available options: auto, disabled

input

文本、图像或文件输入到模型，用于生成响应。

了解更多：

• 文本输入和输出
• 图像输入
• 文件输入
• 对话状态
• 函数调用

include · enum<string>[] | null

指定在模型响应中包含的额外输出数据。当前支持的值有：

• web_search_call.action.sources: 包括网络搜索工具调用的来源。
• code_interpreter_call.outputs: 包括代码解释器工具调用中Python代码执行的输出。
• computer_call_output.output.image_url: 包括来自计算机调用输出的图像URL。
• file_search_call.results: 包括文件搜索工具调用的搜索结果。
• message.input_image.image_url: 包括来自输入消息的图像URL。
• message.output_text.logprobs: 包括带有助手消息的对数概率。
• reasoning.encrypted_content: 包括推理项输出中推理token的加密版本。这使得在使用Responses API无状态（如当store参数设置为false时，或当组织注册了零数据保留计划时）时，推理项可以用于多轮对话。

指定在模型响应中包含的额外输出数据。

Available options: code_interpreter_call.outputs, computer_call_output.output.image_url, file_search_call.results, message.input_image.image_url, message.output_text.logprobs, reasoning.encrypted_content

parallel_tool_calls · boolean | null · default: true

是否允许模型并行运行工具调用。

store · boolean | null · default: true

是否存储生成的模型响应以供以后通过API检索。

instructions · string | null

插入到模型上下文中的系统（或开发者）消息。

当与previous_response_id一起使用时，前一个响应的指令不会被带到下一个响应。这使得在新响应中简单地交换系统（或开发者）消息变得简单。

stream · boolean | null · default: false

如果设置为true，模型响应数据将使用服务器发送事件实时流式传输。 有关更多信息，请参阅流式响应部分。

stream_options · object

流式响应的选项。仅在设置 stream: true 时设置。

Show child attributes

conversation

此响应所属的对话。此对话中的项目会被添加到此响应请求的input_items之前。 此响应的输入项和输出项在此响应完成后会自动添加到此对话中。

Response

200

application/json

响应生成成功

metadata · object · required

请求的元数据

temperature · number | null · default: 1 · required

采样温度，取值范围在0到2之间。较高的值（如0.8）会使输出更加随机，而较低的值（如0.2）会使输出更加集中和确定性。 通常建议仅调整temperature或top_p其中之一，不建议两者都修改。

Required range: 0 <= x <= 2

Example:

1

top_p · number | null · default: 1 · required

核采样的替代方法，称为nucleus采样，模型考虑具有top_p概率质量的token结果。例如，0.1意味着只考虑构成前10%概率质量的token。 通常建议仅调整temperature或top_p其中之一，不建议两者都修改。

Required range: 0 <= x <= 1

Example:

1

model · string · required

用于生成响应的模型ID，如gpt-4o或o3。OpenAI提供具有不同功能、性能特性和价格点的广泛模型。参考模型指南浏览和比较可用模型。

Example:

"gpt-4o"

tools · (函数工具 · object | 网络搜索工具 · object | 文件搜索工具 · object)[] · required

模型在生成响应时可以调用的工具数组。您可以通过设置tool_choice参数来指定使用哪个工具。

我们支持以下类别的工具：

• 内置工具：由OpenAI提供的扩展模型功能的工具，如网络搜索或文件搜索。了解更多关于内置工具。
• MCP工具：通过自定义MCP服务器或预定义连接器（如Google Drive和SharePoint）与第三方系统集成。了解更多关于MCP工具。
• 函数调用（自定义工具）：由您定义的函数，使模型能够使用强类型参数和输出调用您自己的代码。了解更多关于函数调用。您也可以使用自定义工具调用您自己的代码。

自定义函数工具，允许模型调用您定义的函数

函数工具

网络搜索工具

文件搜索工具

Show child attributes

tool_choice · required

模型在生成响应时应如何选择使用哪个工具（或工具）。请参阅tools参数了解如何指定模型可以调用的工具。

Available options: none, auto, required

id · string · required

此响应的唯一标识符。

Example:

"resp_abc123"

object · enum<string> · required

此资源的对象类型 - 始终设置为 response。

Available options: response

Example:

"response"

created_at · number · required

创建此响应的Unix时间戳（秒）。

error · object · required

当模型无法生成响应时返回的错误对象。

Show child attributes

incomplete_details · object · required

有关响应为何不完整的详细信息。

Show child attributes

output · (输出消息 · object | 文件搜索工具调用 · object | 函数工具调用 · object | 网络搜索工具调用 · object | 计算机工具调用 · object | 推理 · object | 图像生成调用 · object | 代码解释器工具调用 · object | 本地Shell调用 · object | MCP工具调用 · object | MCP工具列表 · object | MCP审批请求 · object | 自定义工具调用 · object)[] · required

由模型生成的内容项数组。

• output 数组中项目的长度和顺序取决于模型的响应。
• 不要简单地访问 output 数组中的第一项并假设它是带有模型生成内容的 assistant 消息，您可以考虑在SDK支持的情况下使用 output_text 属性。

模型生成的输出项，可以是消息、工具调用或其他内容类型。

输出消息

文件搜索工具调用

函数工具调用

网络搜索工具调用

计算机工具调用

推理

图像生成调用

代码解释器工具调用

本地Shell调用

MCP工具调用

MCP工具列表

MCP审批请求

自定义工具调用

Show child attributes

instructions · required

插入到模型上下文中的系统（或开发者）消息。

当与 previous_response_id 一起使用时，前一个响应的指令不会被带到下一个响应。这使得在新响应中简单地交换系统（或开发者）消息变得简单。

parallel_tool_calls · boolean · default: true · required

是否允许模型并行运行工具调用。

top_logprobs · integer | null

一个介于0和20之间的整数，指定在每个token位置返回的最可能token的数量，每个token都有相关的对数概率。

Required range: 0 <= x <= 20

user · string · deprecated

此字段正在被safety_identifier和prompt_cache_key替代。请使用prompt_cache_key来维持缓存优化。 用于您的终端用户的稳定标识符。用于提高缓存命中率，通过更好地分组类似请求，并帮助检测和防止滥用。

Example:

"user-1234"

safety_identifier · string

一个稳定的标识符，用于帮助检测可能违反使用政策的用户。ID应该是唯一标识每个用户的字符串。我们建议对用户名或电子邮件地址进行哈希处理，以避免向我们发送任何识别信息。

Example:

"safety-identifier-1234"

prompt_cache_key · string

用于缓存类似请求的响应以优化缓存命中率。替代user字段。

Example:

"prompt-cache-key-1234"

service_tier · enum<string>

服务层级

Available options: default, scale

previous_response_id · string | null

先前响应的唯一ID，用于创建多轮对话。了解更多关于对话状态。不能与conversation参数同时使用。

reasoning · 推理配置 · object

gpt-5和o系列模型专用

推理模型的配置选项。

Show child attributes

background · boolean | null · default: false

是否在后台运行模型响应。了解更多。

max_output_tokens · integer | null

可以为响应生成的token数量的上限，包括可见输出token和推理token。

max_tool_calls · integer | null

在响应中可以处理的内置工具调用总数的最大值。此最大数量适用于所有内置工具调用，而不是每个单独工具。模型进一步尝试调用工具将被忽略。

text · object

模型文本响应的配置选项。可以是纯文本或结构化JSON数据。了解更多：

• 文本输入和输出
• 结构化输出

Show child attributes

prompt · string

用于生成或指导模型响应的提示文本。这是发送给模型的主要指令或问题。

Example:

"请解释一下机器学习的基本概念"

truncation · enum<string> | null · default: disabled

用于模型响应的截断策略。

• auto：如果此响应的输入超过模型的上下文窗口大小，模型将通过从对话开头删除项目来截断响应以适应上下文窗口。
• disabled（默认）：如果输入大小将超过模型的上下文窗口大小，请求将失败并返回400错误。

Available options: auto, disabled

status · enum<string>

响应生成的状态。可以是 completed、failed、in_progress、cancelled、queued 或 incomplete 之一。

Available options: completed, failed, in_progress, cancelled, queued, incomplete

output_text · string | null

仅SDK便利属性，包含 output 数组中所有 output_text 项的聚合文本输出（如果存在）。在Python和JavaScript SDK中支持。

usage · object

表示token使用详情，包括输入token、输出token、输出token的细分和使用的总token。

Show child attributes

conversation · 对话 · object

此响应所属的对话。此响应的输入项和输出项会自动添加到此对话中。

Show child attributes