Точки доступа и форматы API

Три API-протокола QCode.cc (Anthropic / OpenAI / Google Gemini), пять точек доступа и правильное заполнение BASE_URL

title: "Точки доступа и форматы API" description: "Три API-протокола QCode.cc (Anthropic / OpenAI / Google Gemini), четыре точки доступа и правильное заполнение BASE_URL"

Точки доступа и форматы API¶

Эта страница объясняет, как QCode.cc предоставляет три API-протокола, четыре домена доступа и как корректно указывать BASE_URL. Один и тот же API-ключ работает со всеми тремя протоколами — протокол определяется путём запроса, маршрутизация происходит на стороне сервера автоматически.

1. Три API-протокола¶

QCode.cc совместим с протоколами Anthropic Messages, OpenAI и Google Gemini:

Схема тела запроса совпадает с соответствующими официальными 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-ключ работает в четырёх доменах — переключайтесь свободно.

🇨🇳 Для пользователей из КНР: рекомендуем asia.qcode.cc (гонконгский узел, минимальная задержка); при нестабильности переключитесь на api.qcode.cc (глобальный Route 53). Запросы со всех доменов отправляются на probe.qcode.cc — введите свой API Key, чтобы увидеть детали запросов, длину контекста, расход токенов и т.д.

3. Таблица BASE_URL¶

Заполняйте согласно используемому инструменту:

Почему для Gemini две формы записи? Провайдер google в OpenCode не добавляет /v1beta/ автоматически, поэтому baseURL должен включать его (/gemini/v1beta). Gemini CLI и официальный SDK Google @google/genai сами добавляют /v1beta/, поэтому base URL должен заканчиваться на /gemini. Если добавить /v1beta вручную, получится /gemini/v1beta/v1beta/... и ошибка 404.

4. Самопроверка через curl¶

Перед подключением полноценного SDK путь и сетевую доступность можно проверить простым POST:

# Тест пути для Anthropic
curl -X POST https://api.qcode.cc/api/v1/messages
# → 401 = путь корректен, отсутствует только Authorization (ожидаемо)

# Тест OpenAI Chat Completions
curl -X POST https://api.qcode.cc/openai/v1/chat/completions
# → 401 = путь OK

# OpenAI Responses (для Codex)
curl -X POST https://api.qcode.cc/openai/v1/responses
# → 401 = путь OK

# Тест пути для 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-ключом:

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. Часто задаваемые вопросы¶

В: Почему curl https://api.qcode.cc/api возвращает 404?

О: /api — это префикс, а не конечная точка. Полный путь: /api/v1/messages.

В: Есть ли разница между /api/v1/messages и /claude/v1/messages?

О: Нет. Оба префикса маршрутизируются в протокол Anthropic Messages. В документации мы используем /api, так как это значение по умолчанию в большинстве SDK экосистемы Claude.

В: Можно ли одним API-ключом вызывать Claude, Codex и Gemini?

О: Да. Ключ не зависит от протокола, протокол определяется путём запроса. /api/v1/messages — Anthropic, /openai/v1/responses — OpenAI Responses, /gemini/v1beta/models/... — Google Gemini.

В: Нужен ли у Gemini хвост /v1beta в baseURL?

О: Зависит от инструмента. В провайдере google OpenCode нужен (укажите baseURL = /gemini/v1beta) — этот провайдер не добавляет /v1beta/ автоматически. Для Gemini CLI и официального SDK Google @google/genai — не нужен (base URL до /gemini), SDK добавит /v1beta/ сам; иначе получится /gemini/v1beta/v1beta/... и ошибка 404.

В: Какой эндпоинт выбрать?

О: Материковый Китай → asia.qcode.cc (Гонконг, минимальная задержка) или api.qcode.cc (глобальный Route 53); Северная Америка → us.qcode.cc; Европа → eu.qcode.cc. Если основной домен нестабилен, свободно переключайтесь на любой резервный.

В: Могу ли я посмотреть свою историю запросов?

О: Да. Запросы, отправленные через любой домен (api.qcode.cc / asia.qcode.cc / us.qcode.cc / eu.qcode.cc), отправляются на probe.qcode.cc. Введите свой API Key, чтобы увидеть список запросов, модели, токены и т.д.

В: Нужен ли конечный слэш в BASE_URL?

О: Нет. Большинство SDK сами добавляют /v1/messages и т. п.; при наличии слэша получится //v1/messages и ошибка 404.