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

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

定價與帳單

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

Ultra 級距的費率與 Anthropic 公布的 Opus 標價一致 —— 直接直通，不加價。其他級距得益於背後的池化訂閱，跑在低於其上游費率的水準。

推理 token（當你在 OpenAI 上設定 reasoning_effort，或使用 Claude 的 -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。快取欄位會記錄在每一筆結算列上，方便主控台呈現明細。

餘額會在每個請求回傳時即時扣除 —— 對串流請求而言，結算會在 [DONE] 區塊落地後執行。在 /console#billing 查看你的即時餘額與每個請求的結算。

速率限制

目前沒有每把 Key 的速率限制。上游帳號池的並行數與 OpenAI 伺服器端的節流仍會適用；若你碰上這些，中轉會回傳 429 並附帶 retry-after 標頭。每把 Key 的 RPM / TPM 限制會在 MVP 之後上線。