Responses（OpenAI Responses 格式）

POST https://api.scirouter.cn/v1/responses

请求与响应格式与 OpenAI Responses API 一致。新版 OpenAI SDK 的 client.responses.* 与 Codex CLI（wire_api = "responses"）等按 Responses 格式发送请求的客户端，替换 base URL 与 Key 即可调用。平台上的所有对话模型均可通过此接口调用；线路不原生支持 Responses 时，网关转换请求，见请求的转发方式。

OpenAI SDK 在 base URL 后拼接 /responses，base URL 为 https://api.scirouter.cn/v1（带 /v1），与对话补全相同。Key 为 SciRouter 控制台创建的 API Key（以 sk-sr- 开头，见认证与 API Key），使用 OpenAI 官方的 Key 返回 401。

Python：

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["SCIROUTER_API_KEY"], base_url="https://api.scirouter.cn/v1")

r = client.responses.create(
    model="YOUR_MODEL_ID",
    instructions="你是一个严谨的科研助手。",
    input="这段序列的二级结构倾向？",
    max_output_tokens=1024,
)
print(r.output_text)

TypeScript：

import OpenAI from 'openai'

const client = new OpenAI({ apiKey: process.env.SCIROUTER_API_KEY, baseURL: 'https://api.scirouter.cn/v1' })

const r = await client.responses.create({
  model: 'YOUR_MODEL_ID',
  input: '这段序列的二级结构倾向？',
  max_output_tokens: 1024,
})
console.log(r.output_text)

curl：

curl https://api.scirouter.cn/v1/responses \
  -H "Authorization: Bearer $SCIROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "input": "这段序列的二级结构倾向？",
    "max_output_tokens": 1024
  }'

Codex 的 config.toml 写法与平台对 Codex 请求的处理见 Codex。

请求体上限为 32 MB（与 /messages 相同），超过时返回 413 payload_too_large。

平台无状态。以下字段返回 400 validation_failed，details.reason 为固定值：

按 id 操作已保存响应的接口（GET / DELETE / cancel）不存在，返回 404。

请求包含只能原样转发的内容时，另见只能原样转发的内容。

线路标为「原生 Responses」时，请求原样转发到上游的 /responses。该标记由平台在线路的接口能力中设置，线路可用的入口中须有 OpenAI 兼容的 openai / custom（见多厂商差异「字段生效规则」）。

平台只修改以下几处：

• model 换成上游的模型名；
• 去掉 metadata / user / safety_identifier；
• store 写为 false；
• max_output_tokens 写入生效值。

include、prompt_cache_key、text.verbosity、reasoning.summary、客户端带回的带 encrypted_content 的推理项与厂商自定义字段均到达上游。响应事件原样返回，只将 model 换回平台的模型 id；id 保留厂商的值，Codex 续接推理依赖该值。

「原样」指请求的格式与字段：鉴权、计费、限额与线路选择仍由平台完成，发给厂商的凭据是平台在该厂商的凭据，调用方的 SciRouter Key 不会到达厂商。

线路未标「原生 Responses」时，网关将请求转为对话补全格式后调用，再将结果转回 Responses 格式：

各参数的规则见参数如何被处理。

客户端带回的推理项按来源处理：

转回的响应与原生响应的差异：

推理项落到其他线路时，签名可能无效并被厂商拒绝。线路走 Anthropic Messages 入口时，平台在同一条线路上重试一次：

• 第一种方式重试后仍被拒，或线路不支持该选项时，去掉思考块再重试一次。
• 第二种方式下，平台记录该线路拒绝过的思考块。此后发往该线路的请求，去掉历史中最后一条带有被拒块的消息及其之前的思考块。
• 重试仍失败时按普通失败处理。

线路走其他入口时，厂商的 400 照旧原样交回。Anthropic 格式的 /v1/messages 不做上述重试，签名被拒的 400 照旧原样交回。

以下内容只走标为「原生 Responses」的线路：

• input_file；
• 按 file_id 引用的图片；
• include 中厂商工具的输出；
• 厂商定义的客户端工具，如 local_shell / apply_patch / custom；
• text.format 为 grammar 等非标准格式；
• context_management。

模型没有此类线路时，返回 400 unsupported_param，details.reason 为 unsupported_content，details.unsupported_content 列出相应内容（如 ["include:code_interpreter_call.outputs"]）。平台不会丢弃这些内容后作答。该错误由请求内容引起，重试无效。

非流式：

{
  "id": "resp_req_…",
  "object": "response",
  "status": "completed",
  "model": "YOUR_MODEL_ID",
  "store": false,
  "output": [
    { "id": "msg_req_…_0", "type": "message", "role": "assistant", "status": "completed",
      "content": [{ "type": "output_text", "text": "…", "annotations": [] }] }
  ],
  "usage": { "input_tokens": 42, "input_tokens_details": { "cached_tokens": 0 }, "output_tokens": 318, "output_tokens_details": { "reasoning_tokens": 0 }, "total_tokens": 360 },
  "scirouter": { "request_id": "req_…", "attempts": 1, "cost_quota": 18240, "…": "…" }
}

数值为示例。

顶层的 scirouter 是平台的扩展块，内容与对话补全相同，SDK 忽略该字段。单次调用扣除的配额见 scirouter.cost_quota。

usage 的维度与账单一一对应。

请求带 "stream": true 时按 Responses 的事件格式发送，每条事件带 event: 行与连续的 sequence_number。事件顺序：

1. response.created
2. response.in_progress
3. 每个输出项：response.output_item.added → response.content_part.added → response.output_text.delta… → response.output_text.done → response.content_part.done → response.output_item.done。推理项为 response.reasoning_text.delta / done，function_call 项为 response.function_call_arguments.delta / done
4. response.completed 或 response.incomplete

与对话补全的流式响应的差异：

• 终态事件（response.completed / response.incomplete）中的 response 为完整结果，与非流式响应逐字段相同。平台在结算后才发送终态事件，事件顶层多一个 scirouter 字段（含本次的 cost_quota）。
• 终态事件之后还有一行 data: [DONE]。OpenAI 官方不发送该行，Open Responses 规范要求发送；官方 SDK 与 Codex 在终态事件处结束读取，不受影响。
• 开始输出后出错时，发送 event: response.failed 事件，随后发送 [DONE]。response.status 为 failed，response.error 带 code / message / request_id；code 只使用原厂支持的值，平台错误码在 scirouter_code 中。上下文超长时无论在开流前后都按此发送，code 为 context_length_exceeded。
• 未收到终态事件即结束的流按失败处理。
• 流中有以 : 开头的心跳注释行，SDK 自动忽略。

非流式请求最长等待约 270 秒，超时返回 504 upstream_timeout（details.timeout 为 response），不计费；回答可能很长时使用流式，见 SDK 与框架「重试与超时」。

• 错误体为 OpenAI 格式，与对话补全相同，鉴权失败与路径错误也是如此。按小写的 error.code 分支处理，对照见错误码。
• 上下文超长、参数不支持与内容审核三类上游语义错误的 error.code 为原厂兼容值（如 context_length_exceeded），平台错误码在 error.scirouter_code 中。
• 流式请求的上下文超长返回 HTTP 200 加 response.failed 事件，不返回 400，见 Codex 与流式响应。
• 本接口特有的 400 见不支持的字段与只能原样转发的内容。

透传到「原生 Responses」线路时，service_tier 取 auto、default 以外的值会使厂商按另一档单价计费：

转换方式不带 service_tier，不做检查。规则与 Messages 相同。

其余 X-SciRouter-*、x-ratelimit-* 响应头与对话补全相同，见可观测性。

• Idempotency-Key 与平台响应缓存的规则与对话补全相同，见缓存与幂等。同一问题以三种格式调用时分别缓存，互不命中。
• OpenAI SDK 默认自动重试 429 与 5xx，并先检查 x-should-retry。
• 控制台的请求日志按调用格式筛选时，本接口的调用格式为 responses。