API リファレンス

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

サービス提供状況

クイックスタート

API が有効な既存アカウントでは、次の 3 つが必要です：

1. ベース URL: https://api.subnsub.com/v1（OpenAI クライアント）または https://api.subnsub.com（Anthropic クライアント — SDK が /v1/messages を自動で付加します）
2. API キー: コンソールで発行する sk-cf-...
3. Model: 16 サポートされているモデル の 1 つ — 例: gpt-5.4-mini または claude-sonnet-5

認証

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

エンドポイント

安定した公開インターフェースは、以下および機械可読な OpenAPI 3.1 ドキュメントに記載されています。ここにないフィールドは upstream に転送される場合がありますが、自動的に SUB&SUB の互換性保証に含まれるわけではありません。

POST /v1/chat/completions

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

POST /v1/responses

OpenAI Responses API — 新しい OpenAI リクエスト形状 (client.responses.create(...))。すべてのカタログ モデルで動作します: gpt-* はネイティブで、claude-* はチャット/補完と同じ互換性ブリッジを介して動作します。使用量は同様に測定され、入出力トークンはモデルの層レートで測定されます。

実行可能な 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）はこのパスに対してそのまま動作します。ベース 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 形式のプロンプトを数えます。/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 互換であっても、すべての upstream モデルの全フィールドが全ルートで保証されるわけではありません。サポートは次の 3 段階です：

利用可能なモデル

上流の２家族。 7 つの OpenAI モデルは、共有の ChatGPT 層アカウントにルーティングされます。 9 つの Claude モデルは、公式 Anthropic アカウントによって提供されます。トークンごとのレートは層によって異なります (価格 を参照)。同じキーが両方で機能します。

OpenAI

Anthropic

推論エフォート

上記のすべての OpenAI モデルは推論モデルです。バックエンドは、目に見える出力を発行する前に、より多くの、またはより少ない「思考」トークンを費やすことができます。予算を制御するには、OpenAI /v1/chat/completions リクエスト本文 (または /v1/responses の reasoning: {"effort": ...}) に ​​reasoning_effort を設定します。 Claude の場合は、Anthropic ネイティブの thinking および output_config.effort フィールドを使用します。/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]

実行可能な 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)

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 のものです:

再試行と信頼性

再試行回数には上限を設けてください。リレーは共有 upstream 容量を利用し、生成リクエストは冪等ではありません。

• 再試行するもの：429、502、503、明らかに一時的な 500。retry-after に従い、なければ jitter 付き指数バックオフ（例：1 秒、2 秒、4 秒、最大 3 回）を使用してください。
• 同じ内容で再試行しないもの：400、401、402、403。payload、キー、残高、アクセス状態を先に修正してください。
• 重複リスク：成功した生成は毎回、個別の課金対象リクエストです。現在 SUB&SUB は idempotency key による生成 POST の重複排除を行いません。アプリ側で操作 ID を保持し、完全な応答を受け取った後は再試行しないでください。
• ストリーミング：中断した SSE ストリームは再開できません。再接続すると新しい生成が始まり、再度課金される場合があります。

料金と請求

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

Fable と Ultra の料金は、Anthropic の公表されている定価と一致します。 Sonnet 5 は、2026 年 8 月 31 日まで Anthropic の導入価格 $2/$10 を使用します。その日以降の公開標準価格は $3/$15 です。他の階層は、プールされたサブスクリプション支援のおかげで、アップストリーム料金よりも低くなります。

推論トークン (OpenAI に reasoning_effort を設定した場合、または Anthropic のネイティブ thinking フィールドを Claude に設定した場合) は、モデルの層レートで output トークンとしてカウントされます。高い労力に対して別途追加料金は発生しませんが、深く考えたリクエストは簡単に 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 で確認できます。

レート制限

現時点ではキーごとのレート制限はありません。共有アップストリーム容量とプロバイダー側のスロットリングは引き続き適用されます。これらに達した場合、リレーは retry-after ヘッダー付きで 429 を返します。キーごとの RPM / TPM 制限は導入予定です。

稼働状況とサポート

• サインイン済みの API 有効アカウントは、コンソール → サービス状況でプロバイダーの稼働状況を、システム通知で運用上のお知らせを確認できます。
• アカウント、請求、プライバシー、セキュリティに関するお問い合わせは、[email protected] へお送りください。
• API 障害を報告する際は、UTC 時刻、エンドポイント、モデル、HTTP ステータス、表示されている API キーのプレフィックスを含めてください。サポートが明示的に編集済みの再現例を求めない限り、完全な API キーやプロンプト内容は送らないでください。
• 本サービスはベストエフォートで、SLA はありません。可用性と返金については英語版のみの利用規約、データの取り扱いについてはプライバシーポリシーをご覧ください。

ドキュメント最終確認日：2026 年 7 月 14 日。