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 呼叫 /v1/messages（或直接做原始 HTTP）。

狀態碼在兩種協定間都是標準的 HTTP 代碼：

重試與可靠性

請限制重試次數。中轉服務使用共享上游容量，生成請求不具備冪等性。

• 可以重試：429、502、503，以及明確屬於暫時性故障的 500。請遵循 retry-after；若無該值，則使用帶隨機抖動的指數退避（例如 1 秒、2 秒、4 秒；最多三次）。
• 不要原樣重試：400、401、402 或 403。請先修正 payload、Key、餘額或存取狀態。
• 重複風險：每次成功生成都是一筆獨立計費請求。SUB&SUB 目前不會根據 idempotency key 對生成 POST 去重，因此請在應用中保留操作 ID，並避免在收到完整回應後重試。
• 串流回應：中斷的 SSE 串流無法續傳。重新連線會開始一次新的生成，並可能產生第二次費用。

定價與帳單

按量付費，以微美元（micro）按 token 計費（1 micro = $0.000001 = 一分錢的 1/10,000），以準確追蹤不到一分錢的請求。費率以每 1M tokens 計、依級距區分 —— 見 模型表 了解各模型對應到哪個級距。

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 caching 以獨立明細計費：快取寫入為該級距輸入價的 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 日。