API 参考

SUB&SUB 在 https://api.subnsub.com/v1 提供多供应商中转。OpenAI 客户端请求 /v1/chat/completions;Anthropic 客户端请求 /v1/messages。同一把 sk-cf-... Key 同时路由两者 —— 在请求体里选定模型,中转会自动选择上游。

快速上手

你需要三样东西:

1. Base URL:https://api.subnsub.com/v1(OpenAI 客户端)或 https://api.subnsub.com(Anthropic 客户端 —— SDK 会自行追加 /v1/messages)
2. API Key:从控制台签发的 sk-cf-...
3. 模型:21 个已验证模型之一 —— 例如 gpt-5.4-mini 或 claude-haiku-4.5

身份认证

每个请求都必须携带 Authorization: Bearer sk-cf-... 头。Key 从控制台签发,并以 SHA-256 哈希存储 —— 一旦离开创建界面,明文将永久消失,所以请立即保存。

端点

POST /v1/chat/completions

发送一个 chat completion 请求。请求结构与 OpenAI Chat Completions API 一致 —— OpenAI SDK 无需改动即可使用。

POST /v1/messages

面向 claude-* 模型的 Anthropic 原生端点 —— Anthropic SDK(anthropic-sdk-python、@anthropic-ai/sdk、claude-code)无需改动即可对该路径使用。将 Base URL 指向 https://api.subnsub.com,并通过 x-api-key 头进行认证(如果你的客户端更倾向于 Authorization-Bearer 形式,也同样可用)。

GET /v1/models

列出你实际可以调用的模型。中转会合并来自 sub2api 的 OpenAI 与 Anthropic 目录,并筛选至我们已针对当前账号池做过端到端测试的 21 个 —— 那些在路由时 503 的幽灵 ID、或首个 token 就上游 400 的,都会被隐藏。如果所有已配置的上游都不可达,该端点会返回 502 models_unreachable,而不是给出一个具误导性的空列表。

# sample response (truncated)
{
  "object": "list",
  "data": [
    { "id": "gpt-5.4-mini",      "type": "model", ... },
    { "id": "gpt-5.4",           "type": "model", ... },
    { "id": "claude-sonnet-4.5", "type": "model", ... },
    { "id": "claude-haiku-4.5",  "type": "model", ... },
    ...
  ]
}

可用模型

两个上游家族。7 个 OpenAI 模型路由到共享的 ChatGPT 级账号;14 个 Claude 模型经由 Kiro 反向代理路由到 AWS CodeWhisperer。每 token 单价取决于档位(参见定价)—— 同一把 Key 对两者都有效。

OpenAI

Anthropic

推理力度

上面每个 OpenAI 模型都是推理模型 —— 后端可以在产出可见输出之前花费更多或更少的“思考”token。在 OpenAI /v1/chat/completions 请求体上设置 reasoning_effort 来控制预算。对于 Claude,请使用 Anthropic 原生的 thinking 请求字段(或选择 -thinking 模型变体)—— 参见 /v1/messages 一节。OpenAI 模型接受相同的五个力度取值:

# Two equivalent forms — pick whichever your SDK supports
{
  "model": "gpt-5.4-mini",
  "reasoning_effort": "high",
  "messages": [ ... ]
}

{
  "model": "gpt-5.5",
  "reasoning": { "effort": "xhigh" },
  "messages": [ ... ]
}

流式

设置 "stream": true 以接收 Server-Sent Events。最后一个分块携带 usage 块(我们对上游强制 stream_options.include_usage,因此总会输出 token 计数),随后一个字面量 data: [DONE] 关闭该流。

# Streaming format (line by line)
data: {"id":"resp_...","choices":[{"delta":{"content":"Hi"}}]}

data: {"id":"resp_...","choices":[{"delta":{"content":"!"}}]}

data: {"id":"resp_...","choices":[],"usage":{"prompt_tokens":18,"completion_tokens":11,"total_tokens":29}}

data: [DONE]

联网搜索

在该端点支持的任意模型 ID 后追加 :online,中转就会在转发给模型之前先执行一次联网搜索,并将结果前置到对话中,使答案立足于新鲜数据。该后缀在 /v1/chat/completions 和 /v1/messages 上均有效(后者仍需 claude-* 作为基础模型);不需要任何搜索专用的请求字段。

# Same call as before — just :online on the model
curl https://api.subnsub.com/v1/chat/completions \
  -H "Authorization: Bearer sk-cf-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini:online",
    "messages": [
      {"role": "user", "content": "What did Anthropic ship this week?"}
    ]
  }'

工作原理:中转剥离 :online,取最近一条用户消息作为查询(上限 400 字符),调用 Tavily 获取最多 3 条结果(在可用时附带提取的页面文本),外加一段可选的 Tavily 生成摘要,然后将它们以清晰分隔的 <search_results> 块前置到同一轮用户回合,再把请求发往上游。该搜索调用有 8 秒超时。结果被刻意注入到 user 角色 —— 绝不进入系统提示词 —— 因此不可信的片段无法被提升为系统优先级的指令。

<search_results> 块看起来如下。它前面会有一行指令,告诉模型将该块视为不可信的外部数据,并就编号条目进行行内引用:

<search_results query="What did Anthropic ship this week?" retrieved="2026-05-21">
Summary: <short LLM-generated synthesis of the result set>

[1] Anthropic launches Opus 4.8
URL: https://www.anthropic.com/news/opus-4-8
<extracted page text, or short snippet if extraction failed — up to ~2000 chars>

[2] ...
</search_results>

何时使用 :online

中转每个请求只做一次 Tavily 调用并注入结果 —— 它不是一个具备自主性的搜索循环。模型不会像 Perplexity Sonar 或 ChatGPT 浏览工具那样,根据所见内容自行决定重新搜索。请围绕这一局限来规划:

把最后一条用户消息写成一个可独立成立的搜索查询。搜索是针对你最近一轮用户回合的字面文本进行的(上限 400 字符),所以像“那最新版本呢?”这样的对话式追问会变成毫无上下文的无用查询。在多轮对话中,当你加上 :online 时请重述主题 —— 例如“Anthropic Python SDK 的最新版本”,而非“最新那个”。

对于需要多步骤综合的问题(对比分析、深度研究),请将其拆分为多轮,并在每一轮都加上 :online。模型会读取每一轮的新鲜结果;你手动引导下一个查询。注意,被注入的 <search_results> 块只发往上游 —— 它不会回传给你的客户端,也不会保留到下一个请求,所以如果后续某一轮依赖更早来源中的细节,请让模型在其可见回复中将它们总结出来。不支持一次性研究模式。

错误

错误外层结构取决于你调用的是哪个端点 —— 中转会以匹配调用方 SDK 的协议返回错误,而上游错误会被原样透传。

OpenAI 路径(/v1/chat/completions、/v1/responses、/v1/models)—— OpenAI 外层结构:

{ "error": { "message": "...", "type": "...", "code": "..." } }

Anthropic 路径(/v1/messages、/v1/messages/count_tokens)—— Anthropic 外层结构:

{ "type": "error", "error": { "type": "...", "message": "..." } }

Anthropic 外层结构采用不同的形状 —— 没有 code 字段,且判别字段 type: "error" 位于顶层(内层的 error.type 给出类别,例如 authentication_error、invalid_request_error、permission_error、api_error)。Anthropic SDK 已能解析这一形状;原生 OpenAI SDK 的错误处理器则不能,所以请用 Anthropic SDK(或直接发原始 HTTP)调用 /v1/messages。

两种协议下的状态码都是标准的 HTTP 状态码:

定价与账单

按量付费,以微美元为单位按 token 计费(1 微 = $0.000001 = 一美分的 1/10,000),因此不足一美分的请求也能被精确追踪。单价按档位以每 1M token 计 —— 各模型映射到哪个档位,见模型表。

Ultra 档位的单价与 Anthropic 公布的 Opus list 价一致 —— 直接透传,不加价。其他档位得益于背后的池化订阅,运行在低于其上游单价的水平。

推理 token(当你在 OpenAI 上设置 reasoning_effort,或使用 Claude 的 -thinking 变体时)按该模型档位单价算作输出 token —— 高力度并没有单独的附加费,但一个深度思考的请求很容易比无力度的请求多产出 10–50× 的输出 token,所以美元账单会随之放大。

Anthropic prompt 缓存作为单独的明细项计费:缓存写入按该档位输入单价的 1.25×,缓存读取按 0.10×。因此一次 haiku-4.5 缓存命中的费用为 0.20 × 0.10 = $0.02 per 1M tokens,一次 sonnet-4.5 缓存命中的费用为 0.75 × 0.10 = $0.075 per 1M tokens。每条结算行都会记录缓存列,以便控制台展示明细。

余额随每个请求返回而实时扣减 —— 对于流式请求,结算在 [DONE] 分块落地之后运行。可在 /console#billing 查看实时余额与每请求结算。

速率限制

目前没有针对单 Key 的速率限制。上游账号池的并发 & OpenAI 服务端限流仍然适用;如果你触及这些限制,中转会返回 429 并带 retry-after 头。针对单 Key 的 RPM / TPM 限制将在 MVP 之后落地。