API リファレンス

SUB&SUB は https://api.subnsub.com/v1 でマルチプロバイダーのリレーを公開しています。OpenAI クライアントは /v1/chat/completions に、Anthropic クライアントは /v1/messages にアクセスします。同じ sk-cf-... キーで両方にルーティングできます — リクエストボディでモデルを指定すると、リレーがアップストリームを選択します。

クイックスタート

必要なものは 3 つです:

1. ベース URL: https://api.subnsub.com/v1（OpenAI クライアント）または https://api.subnsub.com（Anthropic クライアント — SDK が /v1/messages を自動で付加します）
2. API キー: コンソールで発行する sk-cf-...
3. モデル: 検証済みの 21 モデルのいずれか — 例: gpt-5.4-mini または claude-haiku-4.5

認証

すべてのリクエストに Authorization: Bearer sk-cf-... ヘッダーを付与する必要があります。キーはコンソールで発行され、SHA-256 ハッシュとして保存されます — 作成画面を離れると平文は二度と表示されないため、すぐに保存してください。

エンドポイント

POST /v1/chat/completions

チャット補完リクエストを送信します。リクエスト形式は OpenAI Chat Completions API と一致しており、OpenAI の SDK をそのまま利用できます。

POST /v1/messages

claude-* モデル向けの Anthropic ネイティブエンドポイントです — Anthropic の SDK（anthropic-sdk-python、@anthropic-ai/sdk、claude-code）はこのパスに対してそのまま動作します。ベース URL を https://api.subnsub.com に向け、x-api-key ヘッダーで認証してください（クライアントが好む場合は Authorization-Bearer 形式も使えます）。

GET /v1/models

実際に呼び出せるモデルを一覧表示します。リレーは sub2api から OpenAI と Anthropic のカタログをマージし、現在のアカウントプールに対してエンドツーエンドで検証済みの 21 モデルに絞り込みます — ルーティング時に 503 となるファントム ID や、最初のトークンでアップストリーム 400 となる ID は非表示になります。設定済みのアップストリームがすべて到達不能な場合、誤解を招く空のリストではなく 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", ... },
    ...
  ]
}

利用可能なモデル

アップストリームのファミリーは 2 つです。7 つの OpenAI モデルは共有 ChatGPT クラスのアカウントにルーティングされ、14 の Claude モデルは Kiro リバースプロキシ経由で AWS CodeWhisperer にルーティングされます。トークンあたりの単価はティアによって異なります（料金を参照）— 同じキーで両方を利用できます。

OpenAI

Anthropic

推論エフォート

上記の OpenAI モデルはすべて推論モデルです — バックエンドは可視の出力を生成する前に、より多くまたは少ない「思考」トークンを費やせます。予算を制御するには、OpenAI の /v1/chat/completions リクエストボディに reasoning_effort を設定します。Claude の場合は Anthropic ネイティブの thinking リクエストフィールドを使う（または -thinking モデルバリアントを選ぶ）でください — /v1/messages セクションを参照してください。OpenAI モデルは同じ 5 つのエフォート値を受け付けます:

# 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]

Web 検索

エンドポイントが対応する任意のモデル ID に :online を付加すると、リレーはモデルへ転送する前に Web 検索を実行し、結果を会話の先頭に追加して、回答が最新のデータに基づくようにします。このサフィックスは /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 秒のタイムアウトがあります。結果は意図的にユーザーロールへ注入され — システムプロンプトには決して注入されません — そのため、信頼できないスニペットがシステム優先度の指示に昇格することはありません。

<search_results> ブロックは次のような形です。その前には、モデルにこのブロックを信頼できない外部データとして扱い、番号付き項目をインラインで引用するよう指示する 1 行が置かれます:

<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 を使うべき場面

リレーはリクエストごとに 1 回だけ 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 のエラーハンドラーはパースしません。そのため /v1/messages は Anthropic の SDK で呼び出してください（または生の HTTP を使ってください）。

ステータスコードは、両プロトコルで標準的な HTTP のものです:

料金と請求

従量課金で、トークンごとにマイクロドル単位（1 マイクロ = $0.000001 = 1 セントの 1/10,000）で課金されるため、1 セント未満のリクエストも正確に記録されます。単価は 1M トークンあたり、ティア別です — 各モデルがどのティアにマッピングされるかはモデル表を参照してください。

Ultra ティアの単価は Anthropic が公開している Opus のリスト価格と一致します — マージンなしの純粋なパススルーです。その他のティアは、プール化されたサブスクリプションを基盤とすることで、アップストリームの単価を下回っています。

推論トークン（OpenAI で reasoning_effort を設定した場合、または Claude の -thinking バリアントを使う場合）は、モデルのティア単価で出力トークンとしてカウントされます — 高エフォートに対する個別の追加料金はありませんが、深い思考を伴うリクエストは、エフォートなしのリクエストよりも簡単に 10–50× 多くの出力トークンを生成し得るため、それに応じて請求額も増えます。

Anthropic のプロンプトキャッシュは別個の項目として課金されます: キャッシュ書き込みはティアの入力単価の 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 で確認できます。

レート制限

現時点ではキーごとのレート制限はありません。アップストリームのアカウントプールの同時実行数と OpenAI のサーバー側スロットリングが適用されます。これらに達した場合、リレーは retry-after ヘッダー付きで 429 を返します。キーごとの RPM / TPM 制限は MVP 後に導入される予定です。