# エンドポイントと API パス

このページでは QCode.cc が提供する 3 種類の API プロトコル、4 つのアクセスドメイン、そして `BASE_URL` の正しい指定方法をまとめて説明します。**同じ API キーで 3 つのプロトコルすべてが使えます** — プロトコルはリクエストのパスによって決まり、バックエンドが自動でルーティングします。

## 1. 3 つの API プロトコル

QCode.cc は **Anthropic Messages**、**OpenAI**、**Google Gemini** の 3 プロトコルに対応しています：

| プロトコル | 主なクライアント | パス |
|-----------|----------------|------|
| Anthropic Messages | Claude Code / Claude Agent SDK / Cline / Aider | `/api/v1/messages` または等価な `/claude/v1/messages` |
| OpenAI Chat Completions | OpenAI 公式 SDK / LangChain / DeepSeek-TUI など汎用クライアント | `/openai/v1/chat/completions` |
| OpenAI Responses | Codex CLI（Codex には必須） | `/openai/v1/responses` |
| Google Gemini API | Gemini CLI / OpenCode（`google` provider）/ Google `@google/genai` SDK | `/gemini/v1beta/models/{model}:generateContent` |

リクエストボディのスキーマは各公式 API（Anthropic `POST /v1/messages` / OpenAI `POST /v1/chat/completions` / OpenAI `POST /v1/responses` / Google `POST /v1beta/models/{model}:generateContent`）と同一です。

> **注意**：`/api`、`/claude`、`/openai/v1` はいずれも**パスプレフィックス**であり、単独のエンドポイントではありません。SDK が `/v1/messages`、`/chat/completions`、`/responses` などを自動で付加します。`curl https://api.qcode.cc/api` を直接実行すると 404 が返りますが、これは**正常な挙動**です。

## 2. どのモデルがどのプロトコルで使えるか

**プロトコルはリクエストパスで決まりますが、すべてのモデルファミリーがすべてのプロトコルで
使えるわけではありません。** 下表が唯一の正典であり、他のページはこの表に従います。

| モデルファミリー | Anthropic<br>`/api/v1/messages` | OpenAI Chat<br>`/openai/v1/chat/completions` | OpenAI Responses<br>`/openai/v1/responses` | Gemini<br>`/gemini/v1beta/…` |
|---|:--:|:--:|:--:|:--:|
| Claude（`claude-opus-*` / `-sonnet-*` / `-haiku-*` / `-fable-*`） | ✅ | ❌ | ❌ | — |
| GPT 系（`gpt-5.x`） | ❌ | ✅ | ✅ Codex はこちら | — |
| GLM / Kimi / DeepSeek / Qwen | ✅ | ✅ | ❌ | — |
| Gemini 系 | ❌ | ❌ | — | ✅ |

🔴 **Claude モデルは Anthropic プロトコルでしか使えません。** `claude-…` を
`/openai/v1/chat/completions` に指定すると次が返ります：

```json
{"error":{"code":"model_not_available_on_endpoint",
          "message":"Model 'claude-sonnet-5' is not available on this endpoint.",
          "type":"invalid_request_error"}}
```

**この検証は認証より前に走ります** —— 無効なキーでもこのエラーが先に出ます。つまり
`model_not_available_on_endpoint` は**プロトコルの選択ミスであってキーの問題ではありません**。
キーが不正な場合は `Invalid API key` が返ります。両者を混同しないでください。

**この制限は Claude 固有**であり、「クロスプロトコルは一律不可」ではありません：

- 中国系 4 ファミリー（GLM / Kimi / DeepSeek / Qwen）は Anthropic と OpenAI Chat の**両方**で動作
- GPT 系は OpenAI の 2 つのレッグを使い、Anthropic レッグでは動作しません

**ツール選定への影響**：OpenAI プロトコルのみ対応でカスタム Anthropic エンドポイントを
持たないクライアント（例：DeepSeek-TUI、WorkBuddy）は、QCode 経由で **Claude モデルを
利用できません**（GPT 系と中国系モデルは利用可）。Claude を使うには Anthropic プロトコル対応の
クライアント（Claude Code、Cline、Zed、Cursor の Anthropic パスなど）を選んでください。

## 3. 4 つのアクセスドメイン

4 つのドメインが提供する機能は同一で、違いは**ネットワークルーティング**のみ：

| ドメイン | 対象地域 | スキーム | 備考 |
|---------|---------|---------|------|
| `api.qcode.cc` | グローバル（Route 53 遅延ベース） | HTTPS | 海外ユーザー推奨、最寄りノードへ自動ルーティング |
| `us.qcode.cc` | 北米（Backup） | HTTPS | ロサンゼルスノード、2026-04-22 稼働 |
| `eu.qcode.cc` | 欧州（Backup） | HTTPS | フランクフルトノード |
| `asia.qcode.cc` | アジア（Backup） | HTTPS | アジアノード（HK/JP の近い方） |

同じ API キーで 4 つのドメインすべてを利用でき、いつでも切り替え可能です。

> **🇨🇳 CN ユーザーへのお知らせ**：`asia.qcode.cc`（アジアノード、HK/JP の近い方、最低レイテンシ）を推奨します。不安定なら `api.qcode.cc`（グローバル Route 53）に切り替えてください。すべてのドメインのリクエストは [probe.qcode.cc](https://probe.qcode.cc) に報告されます——API Key を入力するとリクエスト詳細、コンテキスト長、使用量などを確認できます。

## 4. BASE_URL 設定対応表

ご利用のツールに応じて下表のとおり設定してください：

| ツール | 環境変数 / 設定キー | 設定値 | SDK が送信する先 |
|-------|-------------------|-------|----------------|
| Claude Code | `ANTHROPIC_BASE_URL` | `https://api.qcode.cc/api` | `/api/v1/messages` |
| Claude Agent SDK | `base_url=` コンストラクタ引数 | `https://api.qcode.cc/api` | `/api/v1/messages` |
| Cline / Aider | Anthropic モードの base URL | `https://api.qcode.cc/api` | `/api/v1/messages` |
| OpenAI Python/JS SDK | `base_url=` コンストラクタ引数 | `https://api.qcode.cc/openai/v1` | `/openai/v1/chat/completions` |
| DeepSeek-TUI（`openai` provider） | TOML `base_url =` または `OPENAI_BASE_URL` | `https://api.qcode.cc/openai/v1` | `/openai/v1/chat/completions` |
| Codex CLI | TOML `base_url =` | `https://api.qcode.cc/openai` | `/openai/v1/responses` |
| OpenCode（`google` provider） | `baseURL` | `https://api.qcode.cc/gemini/v1beta` | `/gemini/v1beta/models/{model}:generateContent` |
| Gemini CLI / Google `@google/genai` SDK | base URL | `https://api.qcode.cc/gemini` | `/gemini/v1beta/models/{model}:generateContent` |


> **Gemini の 2 通りの書き方について**：OpenCode の `google` provider は `/v1beta/` を**自動で付加しない**ため、`baseURL` は `/gemini/v1beta` まで含める必要があります。Gemini CLI と Google 公式 `@google/genai` SDK は `/v1beta/` を**自動で付加する**ため、base URL は `/gemini` までで十分です（`/v1beta` まで書くと `/gemini/v1beta/v1beta/...` となり 404 になります）。

> **⚠️ Gemini CLI 移行のお知らせ**：Gemini CLI は 2026-06-18 にサポート終了となりました（Pro / 無料プラン）。今後は **Google Antigravity CLI** をご利用ください。エンタープライズの有料キーは影響を受けません。QCode.cc は引き続き Gemini モデルを提供しており、上記の Gemini の base URL と API Key の指定方法は変わりません —— Antigravity CLI も同じ `/gemini` エンドポイントをそのまま利用できます。

## 5. curl によるセルフテスト

SDK を組み込む前に、パスの可達性とネットワーク疎通は curl で POST を打つだけで確認できます：

```bash
KEY="cr_あなたのキー"

# Anthropic プロトコル パステスト
curl -s -o /dev/null -w '%{http_code}\n' -X POST https://api.qcode.cc/api/v1/messages \
  -H "Authorization: Bearer $KEY"
# → 400 = パスもキーも OK（ボディ未指定は想定内）；401 = キー無効

# OpenAI Chat Completions パステスト
curl -s -o /dev/null -w '%{http_code}\n' -X POST https://api.qcode.cc/openai/v1/chat/completions \
  -H "Authorization: Bearer $KEY"
# → 400 / 401 同上

# OpenAI Responses（Codex 用）
curl -s -o /dev/null -w '%{http_code}\n' -X POST https://api.qcode.cc/openai/v1/responses \
  -H "Authorization: Bearer $KEY"
# → 400 / 401 同上

# Google Gemini プロトコル パステスト
curl -s -o /dev/null -w '%{http_code}\n' -X POST "https://api.qcode.cc/gemini/v1beta/models/gemini-2.5-pro:generateContent" \
  -H "x-goog-api-key: $KEY"
# → 400 / 401 = パス OK
```

**解釈**：キー付きで `400`（ボディ未指定）または `401`（キーの問題）が返れば、パスのマッピングとネットワークは正常です。`404` はパスプレフィックスの誤り——上のセクション 3 の表で修正してください。注意：**キーなし**でこれらのパスにアクセスすると HTML 紹介ページ（HTTP 200）が返ります——それはキーが付いていないサインです。

実際の API キーを使ったエンドツーエンドテスト：

```bash
curl -X POST https://api.qcode.cc/api/v1/messages \
  -H "x-api-key: YOUR_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":64,"messages":[{"role":"user","content":"ping"}]}'
```

同じパスでドメインを `us.qcode.cc` / `eu.qcode.cc` / `asia.qcode.cc` に切り替えても同じ結果が得られるはずです — これにより、その代替ドメインが利用可能であることを確認できます。

## 6. FAQ

**Q：`curl https://api.qcode.cc/api` が 404 を返すのはなぜ？**

A：`/api` はパスプレフィックスでありエンドポイントではないためです。正しいパスは `/api/v1/messages` です。

**Q：`/api/v1/messages` と `/claude/v1/messages` に違いはありますか？**

A：ありません。両方のプレフィックスが Anthropic Messages プロトコルにルーティングされます。ドキュメントでは Claude エコシステム SDK のデフォルトに合わせて `/api` を使っています。

**Q：1 つの API キーで Claude、Codex、Gemini をすべて呼び出せますか？**

A：はい。キーはプロトコル非依存で、**プロトコルはリクエストパスで決まります**。`/api/v1/messages` なら Anthropic、`/openai/v1/responses` なら OpenAI Responses、`/gemini/v1beta/models/...` なら Google Gemini。

**Q：Gemini の `baseURL` は末尾に `/v1beta` が必要ですか？**

A：ツールによって異なります。**OpenCode の `google` provider では必要です**（`baseURL` を `/gemini/v1beta` に設定）— このプロバイダは `/v1beta/` を自動で付加しません。**Gemini CLI と Google 公式 `@google/genai` SDK では不要です**（base URL は `/gemini` まで）— SDK が `/v1beta/` を自動で付加するため、手動で追加すると `/gemini/v1beta/v1beta/...` となり 404 になります。

**Q：どのアクセスドメインを選べばいい？**

A：中国本土 → `asia.qcode.cc`（アジアノード、HK/JP の近い方、最低レイテンシ）または `api.qcode.cc`（グローバル Route 53）；北米 → `us.qcode.cc`；欧州 → `eu.qcode.cc`。主ドメインが不安定なら別の予備ドメインに自由に切り替えてください。

**Q: 自分のリクエスト履歴を確認できますか？**

A：はい。すべてのドメイン（`api.qcode.cc` / `asia.qcode.cc` / `us.qcode.cc` / `eu.qcode.cc`）経由で送信したリクエストは [probe.qcode.cc](https://probe.qcode.cc) に報告されます。自身の API Key を入力すると、リクエスト一覧、モデル、tokens などを確認できます。

**Q：BASE_URL に末尾スラッシュは必要？**

A：**不要です**。多くの SDK は `/v1/messages` などを自動で付加するので、末尾スラッシュが付いていると `//v1/messages` となり 404 になります。