创建响应

{
  "id": "resp_example",
  "object": "response",
  "created_at": 1700000000,
  "model": "YOUR_MODEL_ID",
  "status": "completed",
  "output": [
    {
      "id": "msg_example",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Hello!",
          "annotations": []
        }
      ]
    }
  ],
  "error": null,
  "incomplete_details": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 3,
    "total_tokens": 15
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "id": "resp_example",
  "object": "response",
  "created_at": 1700000000,
  "model": "YOUR_MODEL_ID",
  "status": "completed",
  "output": [
    {
      "id": "msg_example",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Hello!",
          "annotations": []
        }
      ]
    }
  ],
  "error": null,
  "incomplete_details": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 3,
    "total_tokens": 15
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>",
    "code": "<unknown>"
  }
}

POST /v1/responses 提供 model 和 input。文本输入可直接使用字符串；输入项数组、多模态和工具格式需符合目标模型支持的 Responses 协议。

读取结果

先检查 status，仅在 completed 时按完整结果处理。对于文本，遍历 output 中的消息项，再遍历 content 中的 output_text 项读取 text；输出还可能含推理、工具调用和其他项。SDK 的 output_text 是便捷属性，不是原始 JSON 必有字段。流式请求使用具名 SSE 事件，不能套用 Chat Completions 的 choices[].delta 解析器。详情见流式输出。

状态和渠道限制

previous_response_id、store、内置工具、后台任务和响应检索依赖渠道、模型及部署配置。普通转发与任务插件的能力可能不同，不能把它们视为全局保证。此页只描述同步与流式创建，不承诺后台模式、任意响应 ID 检索或跨渠道会话续接。无需服务端状态时，将所需上下文放入 input；依赖先前响应时，先和管理员确认保存与路由行为。store: false 也不能替代部署方的数据保留说明。 HTTP 示例 · Python · TypeScript · 错误处理

应用示例与扩展输出

多轮对话：显式重放完整历史，不依赖已保存的响应 ID。
函数工具：通过 call_id 关联 function_call_output。
结构化输出：使用 text.format 并校验业务字段。
图片理解：发送 input_text 和 input_image。

include 可请求模型支持的附加输出，例如 reasoning.encrypted_content。需要重放推理状态时，保留完整输出项和渠道返回的 phase、encrypted_content 等字段。原生 Responses 转发与其他协议转换的保留能力可能不同，必须通过目标渠道验证。响应参数表展示的可选字段不代表所有转换路径都会返回它们。文本内容中可能出现 type: refusal；即使整体状态为 completed，也要检查消息状态、拒答及空输出，不能仅凭 output_text 判断成功。接口支持范围 · 生产接入 · 接入排障上下文压缩 · 后台任务与查询 Read in English

缓存、推理与上下文控制

原生请求 DTO 包含 prompt_cache_key、prompt_cache_retention、prompt_cache_options、reasoning、truncation 和 context_management。字段存在仅说明项目能表达它，不保证每个模型、插件或转换路径都支持。当前 Responses 转 Chat 会拒绝 previous_response_id、conversation、prompt 和 context_management；prompt_cache_options、truncation 也没有对应映射。需要这些语义时确认使用支持它们的原生链路。reasoning 中的 effort、summary、mode、context 均应按目标模型确认，不能套用 Chat 的嵌套预算结构。 usage.input_tokens_details.cached_tokens 与 output_tokens_details.reasoning_tokens 是可选统计。无状态续聊保留完整输出项；include: ["reasoning.encrypted_content"] 不能弥补不支持密文的渠道。手动压缩仍使用独立的 /v1/responses/compact。新增字段核对版本：30a6d88a4。提示词缓存 · 推理模型 · 上下文管理

文件输入与内置搜索

原生 input 消息可携带 input_file 内容项：filename 和 Data URL file_data 与 type 同层。file_id 需要目标上游已经存在且可访问的文件；本网关未实现通用 /v1/files 管理。原生 tools 可携带上游支持的搜索工具，配合 tool_choice。它们不保证跨协议保留或适用于所有渠道。完成搜索项为 web_search_call；引用位于消息 content[].annotations 中的 url_citation，索引属于该原始文本块。status: completed 本身不保证执行了搜索或存在引用。 PDF 示例 · 搜索示例 · 参数过滤

工具策略与 JSON 模式

tool_choice 可请求 auto、required、none 或指定函数，parallel_tool_calls: false 请求单轮最多一个函数调用。字段形状、strict 转换限制与完整示例见工具控制。 JSON 模式只请求 JSON，不提供业务 Schema 保证；两个协议的字段形状和可运行示例见 JSON 模式。

授权

Authorization

string

header

必填

模型调用 API Key，不是控制台登录凭据 / Model API key, not console login credentials

请求体

application/json

model

string

必填

模型列表返回的原始 ID；需要支持当前接口 / Exact ID from the model list; must support this endpoint

示例:

"YOUR_MODEL_ID"

input

必填

文本或输入项数组；内容块和工具项需模型支持 / Text or input items; content blocks and tool items require model support；原生 input_file 可携带 filename 和 Data URL file_data，需上游支持 / Native input_file may carry filename and Data URL file_data; upstream support required

instructions

string

stream

boolean

默认值:false

是否返回 SSE 事件；取决于模型和渠道支持 / Return SSE events when supported by the model and channel

max_output_tokens

integer

生成上限；模型可能要求更小的值，并限制与其他字段组合 / Output limit; models may impose a smaller limit or parameter restrictions

必填范围: 0 <= x <= 1073741823

temperature

number

采样温度；范围、默认值和是否可用由模型决定 / Sampling temperature; range, default, and support depend on the model

top_p

number

核采样；范围、默认值和是否可用由模型决定 / Nucleus sampling; range, default, and support depend on the model

previous_response_id

string

关联先前响应；依赖渠道的状态保存及路由能力 / Reference a previous response; requires compatible state retention and routing

store

boolean

默认允许；DisableStore 删除字段而非强制 false，不是保留策略保证 / Allowed by default; DisableStore removes rather than forces false; not a retention guarantee

tools

object[]

工具定义；不同于 Chat Completions 工具结构 / Tool definitions; differ from Chat Completions tool objects；内置 web_search_preview / web_search 需原生上游支持，不保证跨协议语义 / Built-in web_search_preview or web_search needs native upstream support; cross-protocol semantics not guaranteed

tool_choice

auto / required / none 或指定函数；Chat 为嵌套 function.name，Responses 为同层 name，需模型支持 / auto / required / none or a selected function; nested function.name in Chat, sibling name in Responses; requires model support

reasoning

object

Responses 推理配置；可用字段和值由模型和转换路径决定 / Responses reasoning configuration; supported fields and values depend on model and conversion

Show child attributes

text

object

输出文本及格式选项；需模型支持 / Text output and format options; require model support

Show child attributes

include

string[]

请求附加输出，如 reasoning.encrypted_content；依赖模型和渠道支持 / Request extra output such as reasoning.encrypted_content; requires model and channel support

示例:

["reasoning.encrypted_content"]

background

boolean

后台执行依赖渠道；插件必须声明 background，检索仅适用于宿主任务响应 / Background execution depends on the channel; plugins must declare background; retrieval covers only host task responses

prompt_cache_key

string

缓存分组提示；不保证命中、亲和或权限隔离 / Cache grouping hint; no guarantee of hits, affinity, or authorization isolation

prompt_cache_retention

string

缓存保留提示，值依赖上游模型；跨协议转换不保证保留 / Retention hint with model-dependent values; not guaranteed across conversion

prompt_cache_options

object

支持该字段的原生上游专用；Responses 转 Chat 当前不映射 / For supporting native upstreams; currently not mapped from Responses to Chat

truncation

string

上游截断策略，例如 disabled / auto；原生模型需支持，转 Chat 不映射 / Upstream truncation policy such as disabled / auto; native support required, not mapped to Chat

context_management

object[]

原生上下文管理条目；依赖模型，Responses 转 Chat 会拒绝该字段 / Native context-management entries; model dependent; Responses-to-Chat conversion rejects this field

service_tier

string

默认过滤，需渠道允许和上游支持 / Filtered by default; requires channel permission and upstream support

safety_identifier

string

默认过滤，需渠道允许 / Filtered by default; requires channel permission

parallel_tool_calls

boolean

显式 false 请求单轮最多一个函数调用；模型/渠道条件支持，不调度应用并发 / Explicit false requests at most one function call per turn; model/channel dependent, not application concurrency control

响应

成功响应；stream=true 时返回 SSE，仍需检查终止事件。 / Successful response; stream=true returns SSE; still check terminal events.

string

object

string

示例:

"response"

created_at

number

model

string

status

string

必须检查完成状态，例如 completed、failed、incomplete / Check completion status, for example completed, failed, or incomplete

output

object[]

Show child attributes

error

object | null

incomplete_details

object | null

usage

object | null

Show child attributes

开始使用

接入指南

应用实践

多模态接入

检索与重排

生产与排障

补充协议与任务

API 参考

读取结果

状态和渠道限制

应用示例与扩展输出

缓存、推理与上下文控制

文件输入与内置搜索

工具策略与 JSON 模式

授权

请求体

响应

​读取结果

​状态和渠道限制

​应用示例与扩展输出

​缓存、推理与上下文控制

​文件输入与内置搜索

​工具策略与 JSON 模式

授权

请求体

响应

读取结果

状态和渠道限制

应用示例与扩展输出

缓存、推理与上下文控制

文件输入与内置搜索

工具策略与 JSON 模式