API 参考

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

服务可用范围

快速上手

对于已开通 API 的现有账户，你需要准备三项内容：

1. Base URL:https://api.subnsub.com/v1(OpenAI 客户端)或 https://api.subnsub.com(Anthropic 客户端 —— SDK 会自行追加 /v1/messages)
2. API Key:从控制台签发的 sk-cf-...
3. 模型：16 个受支持模型之一，例如 gpt-5.4-mini 或 claude-sonnet-5

身份认证

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

端点

稳定的公共接口范围见下文及机器可读的 OpenAPI 3.1 文档。未在这里列出的字段可能会透传给上游，但不会自动成为 SUB&SUB 的兼容性承诺。

POST /v1/chat/completions

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

POST /v1/responses

OpenAI Responses API —— OpenAI 较新的请求格式（client.responses.create(...)）。支持目录中的所有模型：gpt-* 原生支持，claude-* 则通过与 chat/completions 相同的兼容桥接层。计费方式相同：输入和输出 token 均按模型档位单价计费。

可直接运行的 Responses 示例：

curl https://api.subnsub.com/v1/responses \
  -H "Authorization: Bearer sk-cf-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "input": "Explain exponential backoff in two sentences."
  }'

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 形式,也同样可用)。

可直接运行的 Anthropic Messages 示例：

curl https://api.subnsub.com/v1/messages \
  -H "x-api-key: sk-cf-xxxxxxxxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

POST /v1/messages/count_tokens

在发送 Anthropic 格式的提示词前计算 token 数。请使用与 /v1/messages 相同的 x-api-key、anthropic-version、model、system、messages 和 tools 字段。此接口不计费。:online 后缀会被移除，但不会获取或计入搜索结果。

curl https://api.subnsub.com/v1/messages/count_tokens \
  -H "x-api-key: sk-cf-xxxxxxxxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [{"role": "user", "content": "Count this prompt."}]
  }'

GET /v1/models

列出你实际可用的模型。中转会对两类上游执行健康检查，并返回 16 个已验证的公开 ID；POST 端点执行的是同一份白名单，因此列表不会展示调用时必然返回 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-5",     "type": "model", ... },
    { "id": "claude-fable-5",      "type": "model", ... },
    ...
  ]
}

兼容性约定

兼容 OpenAI 并不表示每个上游模型的所有字段都能在每条路由上得到保证。我们将支持范围分为三级：

可用模型

共有两类上游：7 个 OpenAI 模型路由到共享的 ChatGPT 级账户，9 个 Claude 模型由 Anthropic 官方账户提供服务。每 token 单价取决于档位（见定价），同一把 Key 两边通用。

OpenAI

Anthropic

推理力度

上方所有 OpenAI 模型都属于推理模型：后端可以在输出可见内容前使用更多或更少的“思考”token。在 OpenAI /v1/chat/completions 请求体中设置 reasoning_effort（或在 /v1/responses 中设置 reasoning: {"effort": ...}）即可控制预算。Claude 请使用 Anthropic 原生的 thinking 和 output_config.effort 字段，详见 /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]

可直接运行的 Python 流式示例：

from openai import OpenAI

client = OpenAI(
    api_key="sk-cf-xxxxxxxxxxxx",
    base_url="https://api.subnsub.com/v1",
)

stream = client.chat.completions.create(
    model="gpt-5.4-mini",
    messages=[{"role": "user", "content": "Hello"}],
    stream=True,
)
for chunk in stream:
    text = chunk.choices[0].delta.content if chunk.choices else None
    if text:
        print(text, end="", flush=True)

联网搜索

在该端点支持的任意模型 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 状态码:

重试与可靠性

请限制重试次数。中转服务使用共享上游容量，生成请求不具备幂等性。

• 可以重试：429、502、503，以及明确属于暂时性故障的 500。请遵循 retry-after；若无该值，则使用带随机抖动的指数退避（例如 1 秒、2 秒、4 秒；最多三次）。
• 不要原样重试：400、401、402 或 403。请先修正 payload、Key、余额或访问状态。
• 重复风险：每次成功生成都是一笔独立计费请求。SUB&SUB 目前不会根据 idempotency key 对生成 POST 去重，因此请在应用中保留操作 ID，并避免在收到完整响应后重试。
• 流式响应：中断的 SSE 流无法续传。重新连接会开始一次新的生成，并可能产生第二次费用。

定价与账单

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

Fable 和 Ultra 档费率与 Anthropic 公布的标价一致。Sonnet 5 在 2026 年 8 月 31 日前采用 Anthropic 的 $2/$10 优惠价；该日期之后公布的标准价为 $3/$15。其余档位由共享订阅资源支持，因此低于上游标价。

推理 token（即在 OpenAI 中设置 reasoning_effort，或在 Claude 中使用 Anthropic 原生 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。每笔请求的账单记录都会单列缓存 token,控制台可查看明细。

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

速率限制

目前没有针对单 Key 的速率限制。共享的上游容量与提供方服务端限流仍然适用;如果你触及这些限制,中转会返回 429 并带 retry-after 头。针对单 Key 的 RPM / TPM 限制已在计划中。

状态与支持

• 已登录且开通 API 的账户可在控制台 → 服务状态查看供应商实时运行状况，并在“系统通知”中查看运营公告。
• 如需账户、计费、隐私或安全方面的帮助，请发送邮件至 [email protected]。
• 报告 API 故障时，请提供 UTC 时间、接口、模型、HTTP 状态码及可见的 API Key 前缀。除非支持人员明确要求经过脱敏的复现内容，否则切勿发送完整 API Key 或提示词内容。
• 本服务按尽力原则提供且不设 SLA。可用性与退款规则请参阅仅提供英文版的服务条款，数据处理方式请参阅隐私政策。

文档最后审核日期：2026 年 7 月 14 日。