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

Три 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.

⚠️ Переход с Gemini CLI: Gemini CLI прекратил поддержку 2026-06-18 (тарифы Pro / бесплатный) — далее используйте Google Antigravity CLI; корпоративные платные ключи это не затрагивает. QCode.cc по-прежнему обслуживает модели Gemini, а указанные выше base URL и API Key для Gemini остаются неизменными — Antigravity CLI использует тот же эндпоинт /gemini.

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

Перед подключением полноценного SDK путь и сетевую доступность можно проверить простым 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
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-ключом:

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-6","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.