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

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

## 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 (обязателен для Codex) | `/openai/v1/responses` |
| Google Gemini API | Gemini CLI / OpenCode (`google` provider) / Google `@google/genai` SDK | `/gemini/v1beta/models/{model}:generateContent` |

Схема тела запроса совпадает с соответствующими официальными 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), **не смогут
использовать модели Claude** через QCode — при этом GPT и китайские модели работают нормально.
Для Claude выбирайте клиент с поддержкой протокола Anthropic (Claude Code, Cline, Zed или
Anthropic-путь в Cursor).

## 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 | Гонконг |

Один API-ключ работает в четырёх доменах — переключайтесь свободно.

> **🇨🇳 Для пользователей из КНР**: рекомендуем `asia.qcode.cc` (гонконгский узел, минимальная задержка); при нестабильности переключитесь на `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 | Base URL Anthropic-режима | `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 две формы записи?** Провайдер `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`.

## 5. Самопроверка через curl

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

**Пояснение**: с ключом ответы `400` (нет тела запроса) или `401` (проблема с ключом) означают, что маршрутизация пути и сеть в порядке; `404` — неверный префикс пути, сверьтесь с таблицей в разделе 3. Важно: запрос к этим путям **без ключа** вернёт HTML-страницу-заглушку (HTTP 200), а не ошибку — это признак того, что ключ не был передан.

Сквозной тест с реальным API-ключом:

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

**В: Почему `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](https://probe.qcode.cc). Введите свой API Key, чтобы увидеть список запросов, модели, токены и т.д.

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

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