Anthropic /v1/messages

cc-router はローカルマシン上で HTTP プロキシを起動し、Anthropic Messages（主入口）、OpenAI Responses、OpenAI Chat Completions の 3 つの入口を公開します。本ページは Anthropic /v1/messages の完全リファレンスです——Claude Code、Claude Desktop および Anthropic Messages プロトコルを話す任意のクライアントの推奨入口であり、プロトコル翻訳を行わない唯一の入口でもあります。3 つの入口の比較はエンドポイント概要を参照してください。

対応バージョン：cc-router v3.0.0 以上。

待受アドレスとポート

設定項目	既定値	説明
待受アドレス	`127.0.0.1`	設定 → プロキシサービス → リッスンアドレスを「LAN」に切り替えると `0.0.0.0` になる
HTTP ポート	`23456`	既に使用中の場合は `+1` で最大 100 回まで自動探索
HTTPS ポート	`23457`	リッスンプロトコルで「HTTPS のみ」または「HTTP + HTTPS」を選ぶと有効。同じく自動で `+1`
ポート／プロトコル／アドレスの変更	アプリ再起動が必要	プロキシはホットリロード非対応

クライアント側の最小構成

export ANTHROPIC_BASE_URL=http://127.0.0.1:23456
# 認証は既定で有効。設定ページで認証を無効にした場合はこの行を省略可
export ANTHROPIC_API_KEY=<cc-router 設定ページで提供される token>

# Claude Code のモデルスロットを cc-router の仮想モデルへ向ける
export ANTHROPIC_DEFAULT_FABLE_MODEL=model-fable
export ANTHROPIC_DEFAULT_OPUS_MODEL=model-opus
export ANTHROPIC_DEFAULT_SONNET_MODEL=model-sonnet
export ANTHROPIC_DEFAULT_HAIKU_MODEL=model-haiku

認証

既定で有効。設定 → 認証と CORS → トークン認証で無効にできます（無効にすると任意のリクエストがそのまま通過します）。
有効時、cc-router は以下のいずれかのヘッダから token を読み取ります（どちらか一方でよい）：
- x-api-key: <token>（Claude Code の ANTHROPIC_API_KEY がここに入る、優先）
- Authorization: Bearer <token>（Claude Code の ANTHROPIC_AUTH_TOKEN がここに入る）
抽出した token は設定ページで構成した auth_token と完全一致する必要があります。一致しなければ 401 を返します。
許可リスト：/v1/models、/health、すべての OPTIONS プリフライトは常に通過します。認証有効時でもブロックしません。
- 設計意図：クライアント起動時の list-models やブラウザでのデバッグを認証で阻害しないため。実際に token クォータを消費するエンドポイント（/v1/messages、/v1/responses、/v1/chat/completions）は認証必須です。

ここで cc-router が受け取る token は cc-router 自身のためのもの であり、各上流プロバイダの本物の API Key とは無関係です——本物の Key は cc-router が仮想モデルのディスパッチ規則に従って上流リクエストへ差し替えます。

CORS は既定で有効：Access-Control-Allow-Origin: *、Method 許可 GET / POST / OPTIONS、すべてのヘッダ許可、プリフライトは 204 を返します。401 レスポンスにも CORS ヘッダが付くので、ブラウザの fetch でレスポンスボディを取得できます。

リクエスト

POST /v1/messages
Content-Type: application/json

ヘッダ	必須	説明
`Content-Type: application/json`	はい	リクエストボディは JSON 必須
`x-api-key` または `Authorization: Bearer ...`	認証設定による	認証有効時はいずれか必須
`x-claude-code-session-id`	いいえ	セッション固定用のセッション識別子（Claude Code が自動で付与）。なければリクエストボディの `metadata.user_id` を読み取る
`anthropic-version` / `anthropic-beta` / …	いいえ	既定では転送しない。サブスクリプション編集ページでそのサブスクリプションの「クライアントヘッダーの転送」を有効にすると、許可リスト内のヘッダがその上流へそのまま転送される

リクエストボディ は Anthropic Messages API の標準形式に準拠します。cc-router は 2 つのフィールドのみをディスパッチに使用 し、その他のフィールド（messages / system / tools / temperature / max_tokens / thinking / …）はそのまま上流へ透過転送します。

フィールド	型	必須	挙動
`model`	string	はい	仮想モデルに解決される。下記マッピング参照。欠落時は `400`
`stream`	boolean	いいえ（既定 `false`）	`true` で SSE、`false` で非ストリーミング

cc-router はリクエストボディの model フィールドを書き換えます：

model-fable / model-opus / model-sonnet / model-haiku にヒット → スロットにバインドされた実モデル名（例：glm-5.1、deepseek-v4-pro）に書き換え
fallback にヒット → 書き換えなし、そのまま上流へ透過

非ストリーミングリクエストの例

curl http://127.0.0.1:23456/v1/messages \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "model-sonnet",
    "max_tokens": 256,
    "messages": [
      { "role": "user", "content": "cc-router を一文で説明して" }
    ]
  }' | jq

レスポンス（非ストリーミング）

200 OK、Content-Type: application/json
ボディは Anthropic 標準の message JSON
cc-router は message.model を仮想モデル名に逆書き換えします（fallback は書き換えなし）。クライアント側でキャッシュや統計を仮想モデル単位で集約しやすくするため
usage.*（cache_creation_input_tokens / cache_read_input_tokens を含む）は透過。cc-router は同時に内部統計用にも抽出します

{
  "id": "msg_xxx",
  "type": "message",
  "role": "assistant",
  "model": "model-sonnet",
  "content": [
    { "type": "text", "text": "..." }
  ],
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 42, "output_tokens": 128 }
}

レスポンス（ストリーミング SSE）

200 OK、Content-Type: text/event-stream
上流の SSE フレームはほぼ全バイトそのまま透過します。以下 2 種のイベントのみ特別扱い：

イベント	cc-router の挙動
`message_start`	JSON をパースし、`message.model` を仮想モデル名へ書き換え（fallback は書き換えなし）、`usage.*` を抽出して計上、再シリアライズして送出
`message_delta`	書き換えなし。`usage.output_tokens` などを副次的に抽出して計上するのみ、バイトは透過
その他すべて（`content_block_*` / `message_stop` / `ping` など）	バイトそのまま透過

ストリーミングリクエストの例

curl -N http://127.0.0.1:23456/v1/messages \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "model-sonnet",
    "max_tokens": 256,
    "stream": true,
    "messages": [
      { "role": "user", "content": "ping" }
    ]
  }'

-N で curl のバッファを切り、SSE フレームをリアルタイム表示します。

先頭フレーム lookahead：上流が 200 を返したが先頭イベントが実は event: error の場合（典型例：GLM の 1302/1308 でクォータ枯渇が 200 に偽装される）、cc-router はそのフレームをクライアントへ転送せず、次のサブスクリプションへ自動リトライします。クライアントから見えるのは「1 回の成功」または「1 回の最終失敗」のみです。

転送中の切断：上流接続が途中で切れた場合、cc-router は既送信フレームの後ろに event: error フレーム + data: [DONE] を追記し、クライアントが永久ハングではなく中断を検知できるようにします。

仮想モデルマッピング

cc-router はリクエストの model フィールドを 1 つの仮想モデルにマップし、その仮想モデルにバインドされたサブスクリプション一覧 + ディスパッチモード（順次 / ラウンドロビン / セッション固定）に従って順に上流を試します。

クライアントが送る `model`	ヒットする仮想モデル
`model-fable`、`claude-fable`、`gpt-5.6`、`gpt--sol`	`model-fable`
`model-opus`、`claude-opus`、`gpt-5.5`、`gpt--terra`	`model-opus`
`model-sonnet`、`claude-sonnet`、`gpt-5.4`、`gpt--luna`	`model-sonnet`
`model-haiku`、`claude-haiku`、`gpt--mini`	`model-haiku`
`model-fallback`	Fallback（明示）
その他任意の値（カスタムモデル名など）	Fallback（暗黙、`model` はそのまま透過）

上記のどの書き方にも anthropic/ または openai/ プレフィックス（LiteLLM 形式）を付けられ、効果は同じです。例：anthropic/claude-opus-4-7、openai/gpt-5.5。

claude-opus* は前方一致です：claude-opus-4-7、claude-opus-4-7-20260101、claude-opus-100 はいずれも model-opus にヒットします。

gpt-*-sol は - で区切ったセグメント単位でティアを照合します：gpt-5.6-sol、gpt-6-sol-20261201 はどちらも model-fable にヒットし、gpt-5.4-mini は model-haiku にヒットします。

gpt-* 系のエイリアスは主に /v1/responses と /v1/chat/completions 入口のクライアント向けで、同じ 4 つのスロットを再利用します（新しい仮想モデルは追加しません）。

未知のベンダープレフィックス（例：google/claude-opus-4-7）は取り除かれないため、fallback になります。

エラーレスポンス

/v1/messages 入口のエラーはすべて Anthropic 形式 に従います：

{
  "type": "error",
  "error": {
    "type": "<kind>",
    "message": "<人間可読メッセージ>"
  }
}

cc-router 自身が生成するエラー：

HTTP Status	`kind`	発生条件
`400`	`invalid_request_error`	JSON パース失敗 / `model` フィールド欠落
`401`	`authentication_error`	認証有効時に token 不一致
`500`	`api_error`	パイプライン内部エラー
`503`	`overloaded_error`	その仮想モデルにサブスクリプションが 1 つもバインドされていない、またはすべてのサブスクリプションが一時的に利用不可（レート制限のクールダウン中など）。エラーメッセージに各サブスクリプションが利用できない理由が列挙される
4xx / 5xx	上流次第	全サブスクリプション失敗時、cc-router は最後の上流の status とエラーボディをそのまま返す

SSE ストリーム内の error フレーム：

先頭イベントが event: error → cc-router が遮断して次のサブスクリプションへ自動リトライ、クライアントには見えない
ストリーム途中で現れる error フレーム → そのままクライアントへ透過、kind は固定で upstream_error

未実装の Anthropic エンドポイント

下記の公式 Anthropic エンドポイントは cc-router では未実装で、これは設計上の選択です：

POST /v1/messages/count_tokens
POST /v1/messages/batches および batches 関連すべて
POST /v1/files（Files API）
Workbench / Admin API

cc-router は Claude Code 風のリアルタイム対話プロキシ用途に設計されており、Claude Code は POST /v1/messages と GET /v1/models のみに依存するため、その他は実装していません。token 数を見積りたい場合は、クライアント側で tiktoken などのローカルライブラリを使うか、/v1/messages を 1 回叩いてレスポンスの usage.input_tokens を確認してください。

クライアントが OpenAI プロトコルを話す場合は、対応する入口を使ってください。cc-router がリクエストを Anthropic Messages に自動で翻訳し、同じディスパッチ pipeline で処理します：

OpenAI Responses（Codex CLI など）→ /v1/responses
OpenAI Chat Completions（Open WebUI、Cherry Studio など）→ /v1/chat/completions