API 参考

SUB&SUB 在 https://api.subnsub.com/v1 提供多供应商 API 中转。OpenAI 客户端调用 /v1/chat/completions 或 /v1/responses，Anthropic 客户端调用 /v1/messages。同一把 sk-cf-... Key 通用所有受支持端点，系统会根据请求体中的模型自动路由。

服务可用范围

快速上手

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

1. Base URL：OpenAI 客户端填写 https://api.subnsub.com/v1；Anthropic 客户端填写 https://api.subnsub.com（SDK 会自动追加 /v1/messages）
2. API Key:从控制台签发的 sk-cf-...
3. 模型：18 个受支持模型之一，例如 gpt-5.4-mini、claude-opus-5 或 gemini-3-flash

身份认证

所有请求都需携带认证头（如 Authorization: Bearer sk-cf-... 或 x-api-key）。API 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 相同的兼容桥接层支持。Gemini 模型改用 /v1/messages。输入和输出 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 原生端点，同时以 Messages 兼容方式支持已列出的两个 gemini-* 模型。Anthropic SDK 无需改动即可使用此路径。请将 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

发送 Claude 提示词前计算 token 数。请使用与 /v1/messages 相同的字段。此端点不计费，且不支持 Gemini 模型。: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

列出你实际可调用的模型。当所有已配置供应商均正常时，中转会返回 18 个已验证的公开 ID，与 POST 端点执行同一份白名单。某个供应商不可用时会省略其模型；所有上游均不可达时返回 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-opus-5",       "type": "model", ... },
    ...
  ]
}

兼容性约定

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

可用模型

共有三类上游：7 个 OpenAI 模型路由至共享 ChatGPT 级账户，9 个 Claude 模型由 Anthropic 官方账户提供，2 个 Gemini 模型通过 Messages 兼容端点连接 Google Gemini 订阅池。各档位单价见定价，同一把 Key 三类通用。

OpenAI

Anthropic

Gemini

推理力度

上方所有 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），随后以 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 与 Gemini 模型），无需额外请求字段。

# 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 条网页结果（含可用正文摘录与可选摘要），再以 <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 检索并注入结果，并非多步自主浏览循环，模型不会根据初步结果自行发起二次搜索。使用时建议注意：

将最后一条用户消息写成完整的独立搜索词。检索直接读取最近一条用户消息的字面内容（上限 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 或原生 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 美分的调用也能准确计量。各档位单价按每百万（1M）token 标示，模型与档位对应关系见模型目录。

Ultra 档位与 Anthropic 公布的目录价一致。Sonnet 5 在 2026 年 8 月 31 日前采用 $2/$10 的首发价格，之后公布的标准价为 $3/$15。其余档位得益于订阅池，价格低于上游目录价。

推理 token（即在 OpenAI 中设置 reasoning_effort，或在 Claude 中使用 Anthropic 原生 thinking 字段）按模型档位单价计为输出 token。高推理强度没有额外附加费，但深度推理请求可能轻易产生无推理请求 10–50 倍的输出 token，因此费用也会相应增加。

Anthropic 提示词缓存单独计费：缓存写入为该档位输入单价的 1.25×，缓存读取为 0.10×。例如 haiku-4.5 缓存读取为 $0.02 / 1M tokens，sonnet-4.5 缓存读取为 $0.075 / 1M tokens。控制台账单明细会单列缓存 token 用量。

每笔请求完成后立即扣减余额；流式请求在输出 [DONE] 后完成结算。可在 /console#billing 查看实时余额与逐笔扣费记录。

速率限制

目前未设单 Key 硬性速率上限，但受共享上游容量与供应商服务端限流约束；触发限流时返回 429 及 retry-after 响应头。单 Key RPM / TPM 限流已在规划中。

状态与支持

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

文档最后审核日期：2026 年 10 月 23 日。