Responses API

OpenAI 的新一代对话协议，输出以 item / content part 的层级结构组织，比 Chat Completions 更适合表达工具调用与推理过程。Codex CLI / Codex Desktop 用的就是它。

POST https://www.apigoto.com/v1/responses

🧭

该不该用这个端点

只有当你的客户端本身就说 Responses 协议时才用它（典型是 Codex）。自己写代码接入的话，Chat Completions 字段更稳定、生态更广。网关内部会做协议转换，两边能调的模型是同一批。

请求头

Authorizationstring必填

Bearer sk-rouertcode-…

Content-Typestring必填

application/json

请求体

modelstring必填

平台模型 ID，见模型、准入与回退。

inputstring | array必填

输入内容。可以是一个字符串（等价于单条 user 消息），也可以是 item 数组以表达多轮对话与工具结果。

instructionsstring可选

系统级指令，作用相当于 Chat Completions 里的 system 消息。

streamboolean可选

默认 false。置 true 返回 response.* 事件流。

max_output_tokensinteger可选

最大输出 token 数。注意名字与 Chat Completions 的 max_tokens 不同。

toolsarray可选

工具定义。Responses 协议的工具是扁平结构，字段直接放在对象上，没有 function 这层嵌套。

reasoningobject可选

推理配置（如 {"effort": "medium"}）。 仅推理型模型有效，其余模型上游会忽略或报错。

temperature / top_pnumber可选

采样参数，语义与 Chat Completions 一致。

userstring可选

终端用户标识，会记入调用日志。

响应

200 OK

{
  "id": "resp_a1b2c3",
  "object": "response",
  "created_at": 1755500000,
  "status": "completed",
  "model": "claude-sonnet-5",
  "output": [
    {
      "type": "message",
      "id": "msg_...",
      "role": "assistant",
      "content": [
        { "type": "output_text", "text": "你好！" }
      ]
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 4,
    "total_tokens": 16
  }
}

⚠️

文本不在固定位置，要遍历取

output 是数组，元素可能是消息、工具调用、推理块。 不要写死 output[0].content[0].text—— 推理型模型会把 reasoning item 排在前面，写死索引拿到的就是空。正确做法是过滤出 type === "message" 的项再取其 output_text。

字段	说明
status	`completed` / `in_progress` / `incomplete` / `failed`
output[].type	`message` / `function_call` / `reasoning`
usage	字段名是 `input_tokens` / `output_tokens`，与 Chat Completions 的 `prompt_tokens` / `completion_tokens` 不同

调用示例

responses.sh

curl https://www.apigoto.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $APIGOTO_API_KEY" \
  -d '{
    "model": "claude-sonnet-5",
    "instructions": "你是一个简洁的助手。",
    "input": "用一句话解释什么是 API 网关",
    "max_output_tokens": 200
  }'

responses.py

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://www.apigoto.com/v1",
    api_key=os.environ["APIGOTO_API_KEY"],
)

resp = client.responses.create(
    model="claude-sonnet-5",
    instructions="你是一个简洁的助手。",
    input="用一句话解释什么是 API 网关",
    max_output_tokens=200,
)
# SDK 提供的便捷属性，等价于遍历 output 取所有 output_text 拼接
print(resp.output_text)

流式事件

事件带具名类型，按生命周期推进：

response stream

event: response.created
data: {"type":"response.created","response":{"id":"resp_...","status":"in_progress"}}

event: response.output_item.added
data: {"type":"response.output_item.added","output_index":0,"item":{"type":"message"}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","output_index":0,"delta":"你好"}

event: response.output_text.done
data: {"type":"response.output_text.done","output_index":0,"text":"你好！"}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_...","status":"completed"}}

data: [DONE]

事件	含义
response.created	响应对象已创建，开始生成
response.output_item.added	新增一个输出项（消息 / 工具调用 / 推理块）
response.output_text.delta	文本增量，拼接 `delta` 即得完整文本
response.function_call_arguments.delta	工具调用参数的增量
response.completed	终止事件，收到它才算成功

output_index 用来区分是哪一个输出项的增量——多个工具调用并行生成时， 必须按 index 分桶累积，否则参数会串在一起。

与 Chat Completions 的字段对照

Chat Completions	Responses
messages	input
system 消息	instructions
max_tokens	max_output_tokens
choices[].message.content	output[] 中 message 项的 output_text
usage.prompt_tokens	usage.input_tokens
tools[].function.name	tools[].name（无 function 嵌套）
data: [DONE]	response.completed（其后仍会有 [DONE]）

可能的错误

错误结构与错误码与其余兼容端点完全一致——error.type 为 "gateway_error" 的是网关错误，否则是上游原样透传。常见的是 40002（缺 model）、40203（模型准入）、 50201（模型名写错）。完整清单见错误码总表。