接入点与 API 格式

QCode.cc 的三种 API 协议（Anthropic / OpenAI / Google Gemini）、五个接入域和 BASE_URL 填写指南

title: "接入点与 API 格式" description: "QCode.cc 的三种 API 协议（Anthropic / OpenAI / Google Gemini）、四个接入域和 BASE_URL 填写指南"

接入点与 API 格式¶

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

1. 三种 API 协议¶

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

请求体 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. 四个接入域名¶

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

同一个 API Key 在四个域下都能用，随意切换即可。

🇨🇳 CN 用户提示：推荐 asia.qcode.cc（香港节点，地理就近、延迟最低），不稳定时切到 api.qcode.cc（全球 Route 53 路由）。所有域名的请求都会上报到 probe.qcode.cc，输入 API Key 即可查看请求详情、上下文长度、用量等。

3. BASE_URL 填写对照表¶

根据你使用的工具，按下表填写：

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

4. curl 自测¶

路径是否可达、网络是否通畅，用 curl 发一个 POST 即可判断：

# Anthropic 协议路径测试
curl -X POST https://api.qcode.cc/api/v1/messages
# → 返回 401 = 路径通过了，只是缺 Authorization header（预期结果）

# OpenAI Chat Completions 协议路径测试
curl -X POST https://api.qcode.cc/openai/v1/chat/completions
# → 返回 401 = 路径通

# OpenAI Responses 协议（Codex 用）
curl -X POST https://api.qcode.cc/openai/v1/responses
# → 返回 401 = 路径通

# Google Gemini 协议路径测试
curl -X POST https://api.qcode.cc/gemini/v1beta/models/gemini-2.5-pro:generateContent
# → 返回 401 / 400 = 路径通（Gemini 认证头 x-goog-api-key 或 key 查询参数）

解读：401 Unauthorized 表示路径映射正确、网络通到位，只是没带认证头 — 这是好消息。如果返回 404 说明路径前缀错了，需对照上面第 3 节的表修正。

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

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-4-5","max_tokens":64,"messages":[{"role":"user","content":"ping"}]}'

切换到 us.qcode.cc / eu.qcode.cc / asia.qcode.cc 的相同路径，应得到一致结果 — 能验证该备用接入点对你可用。

5. 常见问题¶

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（香港节点，延迟最低）或 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，输入你的 API Key 即可看到请求列表、模型、tokens 等。

Q：BASE_URL 填的时候要不要带尾部斜杠？

A：不要带。大多数 SDK 会自动拼 /v1/messages 等后缀，如果你把尾斜杠带上了，会拼成 //v1/messages 导致 404。