对话补全

POST https://api.scirouter.cn/v1/chat/completions

请求与响应格式与 OpenAI Chat Completions 一致。字段语义以 OpenAI 文档为准，下文只列平台的处理方式。

{
  "model": "YOUR_MODEL_ID",
  "messages": [
    { "role": "system", "content": "你是一名结构生物学助手。" },
    { "role": "user", "content": "帮我判断这段序列的二级结构倾向：MKTAYIAKQR…" }
  ],
  "max_tokens": 1024,
  "temperature": 0.3,
  "stream": false
}

其他字段的处理：

请求体上限默认为 4 MB，超过时返回 413 payload_too_large。

max_tokens

预扣按「输入估算 + 输出上限」计算，未填写时按上表确定的上限；账户的充值余额大于 0 时，输出只按输出上限与平台设定值中的较小者估算。结束后按实际用量结算，实际超出的部分照扣，见认证与 API Key「预扣」。

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "created": 1758585600,
  "model": "YOUR_MODEL_ID",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "这段序列……" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 42, "completion_tokens": 318, "total_tokens": 360 },
  "scirouter": { "request_id": "req_…", "attempts": 1, "cost_quota": 18240, "…": "…" }
}

数值为示例。

• scirouter 字段与 X-SciRouter-* 响应头见可观测性。
• 单次调用扣除的配额以 scirouter.cost_quota 为准，不根据 usage 自行计算。
• finish_reason 为 length 表示回答被 max_tokens 截断。结构化数据或代码被截断时解析可能不报错，内容仍不完整；批处理按 finish_reason 判断，不按内容长度判断。

请求带 "stream": true 时，响应为 text/event-stream：

: ping

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""}}]}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"这段序列"}}]}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":42,"completion_tokens":318,"total_tokens":360}}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","choices":[],"scirouter":{"request_id":"req_…","attempts":1,"cost_quota":18240}}

data: [DONE]

读取流时处理以下四点：

1. 以 : 开头的行是注释，跳过。排队或上游长时间无输出时，网关约每 10 秒发送一行 : ping 心跳。官方 SDK 自动跳过。
2. choices 可能为空数组。末尾的用量分片（include_usage 为 true 时才有）、scirouter 扩展分片与托管工具的进度分片均如此，直接读取 choices[0] 会越界。
3. 收到 data: [DONE] 才表示正常结束。 出错时流中出现一个 {"error": {...}} 分片，随后断开，不发送 [DONE]。未收到 [DONE] 即结束的流按失败处理，错误分片的格式见错误码。
4. 错误分片可能出现在第一个内容分片之前。心跳发出后 HTTP 状态码已是 200，此后的错误（如排队超时）只能以错误分片返回。只检查状态码会将这些错误当作成功。

故障转移只发生在第一个字节之前。上游开始输出后，中途失败不换线路重试，返回错误分片。

推理模型的思考过程同时写在 reasoning_content 与 reasoning 两个字段中，内容相同，读取任一字段即可：非流式在 choices[].message 上，流式在 choices[].delta 上。

思考消耗的 token 在 usage.completion_tokens_details.reasoning_tokens 中（上游返回时才有），已包含在 completion_tokens 内。

部分模型对思考过程签名。多轮工具调用时，须将上一轮的思考块连同签名一起带回，模型才能接续；只带回 reasoning_content 的文本会丢失签名。

这类模型的助手消息上另有扩展字段 thinking_blocks：非流式在 choices[].message 上，流式在 choices[].delta 上，签名在最后一个分片中。数组中每项为以下两种之一：

[
  { "type": "thinking", "thinking": "…", "signature": "…" },
  { "type": "redacted_thinking", "data": "…" }
]

• 下一轮将助手消息原样放回 messages，包括 thinking_blocks，内容不做修改。平台原样接收，并优先将请求发回签发该签名的线路。
• 不签名的模型没有该字段。
• 字段名为上述 thinking / signature 与 redacted_thinking / data，已按此格式实现的客户端无需修改。

请求落到其他线路时，签名可能无效并被厂商拒绝。线路走 Anthropic Messages 入口时，平台不返回该 400，在同一条线路上重试一次：

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

线路走其他入口时，厂商的 400 照旧原样交回。Anthropic 格式（/v1/messages）的调用不做上述重试：签名被拒的 400 照旧原样交回，由客户端去掉思考块后重发，见 Messages。

tools 与 tool_choice 按 OpenAI 格式编写，模型返回的 tool_calls 原样交给调用方。需要平台代为执行工具（如搜索网页、读取文献）时，使用托管工具，见 MCP 与托管工具。

模型未声明工具调用能力（GET /models 的 features）时，带 tools 的请求在选择线路前返回 400 unsupported_param，details.cause 为 feature_missing。

选择线路时按以下条件过滤：

没有满足条件的线路时返回 503 model_unavailable，details.reason 指明缺少的条件：

以上几种不带 Retry-After，原样重试无效，去掉对应参数或更换模型。带 Retry-After 的 503（endpoints_busy / model_busy）表示暂时繁忙。见错误码「HTTP 503 的 details.reason」。

非流式请求最长等待约 270 秒。 非流式请求须等完整生成后才有第一个字节，平台不按开始响应的时间判定，最多等待整个响应约 270 秒。该时长短于接入层（CDN）等待源站应答的 300 秒，超时时返回 JSON 错误体，不出现 CDN 的 524。

回答可能超过数分钟（推理模型、长输出）时使用流式。流式约每 10 秒发送一行心跳，不受 270 秒限制，受上表的空闲超时与总时长上限约束。

调用方主动断开后结果不保存，带 Idempotency-Key 重试时会重新调用并照常计费，见缓存与幂等。

所有错误码与重试策略见错误码。

• 错误码与可重试的错误：错误码
• 重复请求命中缓存、重试不重复扣费：缓存与幂等
• 单次调用路由到的线路与耗时：可观测性