# 接入点与 API 格式

本页统一讲清 QCode.cc 的三种 API 协议、四个接入域名与 `BASE_URL` 的正确填法。**同一个 API Key 三种协议都可用**，协议由你请求的路径决定，服务端自动路由。

## 1. 三种 API 协议

QCode.cc 后端同时兼容 **Anthropic Messages**、**OpenAI** 和 **Google Gemini** 三种协议：

| 协议 | 典型客户端 | 路径 |
|------|-----------|------|
| 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（必须用这个） | `/openai/v1/responses` |
| Google Gemini API | Gemini CLI / OpenCode（`google` provider）/ Google `@google/genai` SDK | `/gemini/v1beta/models/{model}:generateContent` |

请求体 schema 与对应官方 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 专属的**，不是「跨协议一律不行」：

- 国产四家族（GLM / Kimi / DeepSeek / Qwen）**Anthropic 腿和 OpenAI Chat 腿都能走**
- GPT 系走 OpenAI 的两条腿；它也不能走 Anthropic 腿

**这对选工具意味着什么**：只支持 OpenAI 协议、不支持自定义 Anthropic 端点的客户端
（例如 DeepSeek-TUI、WorkBuddy），在 QCode 上**用不了 Claude 模型**，但可以正常使用
GPT 系与国产模型。要用 Claude，请选支持 Anthropic 协议的客户端（Claude Code、Cline、
Zed、Cursor 的 Anthropic 路径等）。

## 3. 四个接入域名

四个域名业务能力完全一致，差异只在**网络路由**：

| 域名 | 面向 | 协议 | 说明 |
|------|------|------|------|
| `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 Key 在四个域下都能用，随意切换即可。

> **🇨🇳 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 两种写法的区别**：OpenCode 的 `google` provider **不自动拼** `/v1beta/`，所以 `baseURL` 必须包含 `/gemini/v1beta`；而 Gemini CLI 和 Google 官方 `@google/genai` SDK **会自己拼** `/v1beta/`，`baseURL` 只需到 `/gemini` 即可（带上 `/v1beta` 会拼成 `/gemini/v1beta/v1beta/...` 导致 404）。

> **⚠️ Gemini CLI 迁移提示**：Gemini CLI 已于 2026-06-18 停止服务（Pro / 免费档），请改用 **Google Antigravity CLI**；企业付费 key 不受影响。QCode.cc 仍正常提供 Gemini 模型，上面的 Gemini base URL 和 API Key 填法保持不变 —— Antigravity CLI 沿用相同的 `/gemini` 接入点即可。

## 5. curl 自测

路径是否可达、网络是否通畅，用 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 = 路径与密钥都通（缺请求体属预期）；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 = 路径通
```

**解读**：带密钥后返回 `400`（缺请求体）或 `401`（密钥问题）都说明路径映射正确、网络通到位；返回 `404` 说明路径前缀错了，对照上面第 3 节的表修正。注意：**不带密钥**访问这些路径会得到一个 HTML 介绍页（HTTP 200）而不是报错——看到介绍页说明请求没带上密钥。

带真实 API Key 做端到端测试：

```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. 常见问题

**Q：为什么 `curl https://api.qcode.cc/api` 返回 404？**

A：`/api` 是路径前缀，不是端点。完整路径是 `/api/v1/messages`。

**Q：`/api/v1/messages` 和 `/claude/v1/messages` 有区别吗？**

A：没有。两种前缀都被路由到 Anthropic Messages 协议，SDK 配哪个都行。我们文档默认用 `/api` 前缀，因为这是多数 Claude 生态 SDK 的默认路径。

**Q：同一个 API Key 同时能调 Claude、Codex 和 Gemini 吗？**

A：可以。Key 不区分协议，**协议由你请求的路径决定**。路径走 `/api/v1/messages` 就是 Anthropic，走 `/openai/v1/responses` 就是 OpenAI Responses，走 `/gemini/v1beta/models/...` 就是 Google Gemini。

**Q：Gemini 的 `baseURL` 末尾要不要带 `/v1beta`？**

A：看工具而定。**OpenCode 的 `google` provider 要带**（填到 `/gemini/v1beta`），因为它不会自动拼 `/v1beta/`。**Gemini CLI 和 Google 官方 `@google/genai` SDK 不要带**（填到 `/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。