OpenAI Responses

使用 OpenAI Responses 兼容接口创建文本、图像、工具调用和推理响应。

Responses 接口使用 Typed Items 统一表达文本、图像、文件、工具调用和推理结果，适合需要多模态输入、内置工具、有状态交互或语义化流式事件的应用。不同模型能够使用的 Item 类型、工具和高级字段可能不同，请以当前账户可见模型及真实调用结果为准。

POST/v1/responses

根据文本、图像、文件或 Typed Input Items 创建模型响应。接口可以返回消息、推理项和工具调用等不同类型的 Output Items，并支持通过 SSE 传输语义事件。

模型是否支持图像、内置工具、推理、状态关联或结构化输出，取决于当前账户可见模型及其上游渠道。建议先完成最小文本请求，再逐项启用高级字段。

Authorization

bearerAuth

AuthorizationBearer <token>

在 Authorization Header 中使用 Bearer your-api-key。

In: header

Request Body

Responses 使用 Typed Items 表达输入、工具和输出。请根据任务选择视图，字段是否生效取决于模型与渠道。

application/json

文本输入

最短路径是直接向 input 传入字符串，也可以使用消息形式的 Typed Items。

model: 当前 API Key 可见且支持 Responses 的模型 ID。
input: 字符串或 Typed Input Items 数组。
instructions: 仅作用于本次响应的高层指令。

application/json

{
  "model": "MODEL_ID",
  "input": "请用三句话介绍你自己。"
}

基础文本响应。input 可以直接使用字符串，也可以传入 Typed Input Items。

background?boolean|null

是否在后台运行响应。后台模式的可用性取决于模型、渠道与账户权限。

Defaultfalse

context_management?array<>|null

当前请求的上下文管理配置，例如在达到指定 Token 阈值时进行压缩。

conversation?string||null

此响应所属的 Conversation。可以传入 Conversation ID 或包含 id 的对象；不能与 previous_response_id 同时使用。

model?string

要使用的 Responses 文本模型 ID。请从当前 API Key 可见模型中选择。

Length1 <= length

input?text input|array<||||||||||||||||||||||||||||||>

文本输入。可以直接传入字符串，也可以传入消息和其他 Typed Items。

include?array<>|null

指定需要附加到响应中的扩展数据。

instructions?string|array<||||||||||||||||||||||||||||||>|null

作为本次响应高层指令使用的系统或开发者消息。使用 previous_response_id 时，上一响应的 instructions 不会自动继承。

max_output_tokens?integer|null

响应可以生成的 Token 上限，包括可见输出与推理 Token。

max_tool_calls?integer|null

本次响应能够处理的内置工具调用总数上限，而不是每种工具各自的上限。

Range0 <= value

metadata?|null

附加到响应对象的键值信息。键最长 64 个字符，值最长 512 个字符。

Propertiesproperties <= 16

parallel_tool_calls?boolean|null

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

Defaulttrue

moderation?|null

对响应输入和输出执行审核的配置。

previous_response_id?string|null

前一个 Response 的唯一 ID，用于继续有状态交互。不能与 conversation 同时使用；上一响应的 instructions 不会自动继承。

prompt?|null

已保存 Prompt 模板及其变量引用。

prompt_cache_key?string|null

用于提高相似请求的提示缓存命中率，并替代 user 的缓存用途。

prompt_cache_options?|null

请求级提示缓存配置。内容块可以使用 prompt_cache_breakpoint 标记显式缓存边界。

prompt_cache_retention?string|null

Deprecated

已弃用，请使用 prompt_cache_options.ttl。该字段保留用于旧缓存保留策略兼容。

Value in

"in_memory"
"24h"
null

reasoning?|null

推理模型的配置。仅适用于支持该能力的模型。

service_tier?string|null

请求使用的服务层级。请求值与响应实际返回值可能不同，例如请求 fast 时响应可能返回 priority。

Default"auto"

Value in

"auto"
"default"
"flex"
"scale"
"priority"
"fast"
"ultrafast"
null

safety_identifier?string|null

用于安全与滥用监测的稳定最终用户标识。建议先进行哈希处理，避免传递可识别个人身份的信息。

Lengthlength <= 64

store?boolean|null

是否存储生成的响应。实际存储、读取与保留期以平台能力为准。

Defaulttrue

stream?boolean|null

为 true 时，通过 Server-Sent Events 返回 Responses 语义事件。

Defaultfalse

stream_options?|null

流式响应配置。仅在 stream 为 true 时使用。

temperature?number|null

采样温度。通常只调整 temperature 或 top_p 中的一项。

Range0 <= value <= 2

Default1

text?

tool_choice?||||||||

控制模型是否以及如何选择工具。

tools?array<|||||||||||||>

模型可以使用的内置工具或自定义函数。实际支持范围取决于模型与渠道。

top_logprobs?integer|null

返回每个输出 Token 位置最可能的候选 Token 数量，取值为 0～20。

Range0 <= value <= 20

top_p?number|null

核采样概率质量。通常只调整 top_p 或 temperature 中的一项。

Range0 <= value <= 1

Default1

truncation?string|null

Deprecated

上下文超过窗口时的截断策略。disabled 会让超限请求失败。

Default"disabled"

Value in

"auto"
"disabled"
null

user?string

Deprecated

已弃用。安全标识请使用 safety_identifier，缓存分组请使用 prompt_cache_key。

Responses 的工具、状态、推理和多模态能力可能因模型与上游渠道不同而变化；建议先完成最小文本请求，再逐项启用高级字段。

Response Body

`application/json`

curl -X POST "https://example.com/v1/responses" \  -H "Content-Type: application/json" \  -d '{    "model": "MODEL_ID",    "input": "请用三句话讲一个关于独角兽的睡前故事。"  }'

{
  "id": "resp_example",
  "object": "response",
  "created_at": 1741476542,
  "status": "completed",
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "model": "MODEL_ID",
  "output": [
    {
      "id": "msg_example",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "在月光下，一只独角兽发现了通往星空的秘密小径。",
          "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": 18,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 22,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 40
  },
  "user": null,
  "metadata": {}
}

OpenAI Responses 官方文档查看上游协议定义与最新字段变化。

Authorization

Request Body

Response Body

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

502application/json

503application/json

504application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`