接入点与 API 格式

QCode.cc 的 Anthropic / OpenAI API 协议（Gemini 协议路径暂不可用）、三个接入域和 BASE_URL 填写指南

需要 API Key？ 前往注册 →·端点与 Base URL →

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

任何方案的 Key 用法都一样。还没选方案？先看 如何选方案，选好后在控制台拿到 Key。

1. API 协议¶

QCode.cc 后端兼容 Anthropic Messages、OpenAI 两类协议；另有 Google Gemini 协议路径，但 QCode 目前暂时下架 Gemini 全系，该路径暂不可用，下文 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 会拿到一个 HTML 介绍页（HTTP 200）——那不是报错，也不能说明这条路径可用；要验证路径请用下面第 5 节的 POST 自测。

2. 哪些模型走哪种接口¶

协议由请求路径决定，但不是每个模型家族都能走每种接口。 下表是唯一真源，其它文档以本表为准。

🔴 Claude 模型只能走 Anthropic 接口。 把 claude-… 填进 /openai/v1/chat/completions 会得到：

{"error":{"code":"model_not_available_on_endpoint",
          "message":"Model 'claude-sonnet-5' is not available on this endpoint. Claude models are served only through the Anthropic Messages API: use a base URL ending in /api (or /claude) and send POST /v1/messages. OpenAI-compatible endpoints do not serve Claude models. / Claude 模型只能走 Anthropic Messages 接口：BASE_URL 以 /api（或 /claude）结尾，请求 POST /v1/messages；OpenAI 兼容接口不提供 Claude 模型。",
          "param":"model",
          "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 Key 在三个域下都能用，随意切换即可。

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

4. BASE_URL 填写对照表¶

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

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

⚠️ Gemini 暂不可用：QCode 目前暂时下架 Gemini 全系，上面两行 Gemini 的 base URL 仅作协议参考，请改用 Claude、GPT 或国产模型。另：Gemini CLI 已于 2026-06-18 停止为个人账号档提供服务，官方建议改用 Google Antigravity CLI。

桌面客户端怎么填：Cherry Studio 支持以上四类协议端的自定义填写，见 Cherry Studio 接入；各工具的协议支持与 Claude 可用性对照，见 工具兼容总览；「订阅能不能当 API 用」见 订阅、官方 API 与 QCode Key。

5. curl 自测¶

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

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 协议路径测试（QCode 暂不提供 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 说明路径前缀错了，对照上面第 4 节的表修正。带密钥后若返回 402，且 code 是 *_cost_limit_exceeded，同样说明路径和 Key 都通，只是这把 Key 的额度用完了（见 错误码参考）。注意：不带密钥访问这些路径会得到一个 HTML 介绍页（HTTP 200）而不是报错——看到介绍页说明请求没带上密钥。

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

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

6. 常见问题¶

Q：为什么 curl https://api.qcode.cc/api 返回的是一个 HTML 页面？

A：/api 是路径前缀，不是端点；未匹配到 API 路由的请求会被引导到介绍页（HTTP 200）。完整路径是 /api/v1/messages，验证请用第 5 节的 POST 自测（返回 401 才说明走到了鉴权环节）。

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

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

Q：同一个 API Key 同时能调 Claude 和 Codex（GPT）吗？

A：可以。Key 不区分协议，协议由你请求的路径决定。路径走 /api/v1/messages 就是 Anthropic，走 /openai/v1/responses 就是 OpenAI Responses。QCode 目前暂不提供 Gemini 模型。

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

A：（QCode 暂不提供 Gemini，以下仅作协议参考。）看工具而定。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。主用域不稳时可切换到其他接入域。

Q：能否查看我自己的请求记录？

A：可以。所有域名（api.qcode.cc / asia.qcode.cc / us.qcode.cc）发的请求都会上报到 probe.qcode.cc，输入你的 API Key 即可看到请求列表、模型、tokens 等。

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

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

企业团队版 →