OpenAI compatible API: что это, зачем base_url и как проверить подключение

В описаниях сервисов и настройках программ всё чаще встречается фраза «openai compatible api». Она важна всем, кто хочет подключить к приложению или IDE не только модели OpenAI: если сервис совместим, клиенту достаточно сменить адрес и ключ. Ниже — что именно означает совместимость, где её границы, чем отличается формат Anthropic и как проверить подключение к Zukko одной командой curl.

Что значит OpenAI compatible API

OpenAI-совместимый API — это сервер, который принимает запросы и отвечает в том же формате, что и API OpenAI. Совпадает «контракт»: пути, поля JSON, способ авторизации и формат потоковой передачи. Клиенту неважно, кто стоит за адресом: он отправляет тот же JSON и получает ответ привычной структуры.

Минимальный набор, который подразумевают под совместимостью:

• Путь POST /v1/chat/completions для чат-запросов и GET /v1/models для списка моделей.
• Авторизация заголовком Authorization: Bearer <ключ>.
• Запрос с полями model и messages, где у сообщений есть role (system, user, assistant) и content.
• Ответ с массивом choices, текстом в choices[0].message.content и счётчиками токенов в usage (prompt_tokens, completion_tokens).
• Стриминг при "stream": true — строки data: {...} в формате Server-Sent Events и завершающая data: [DONE].

Чего совместимость не гарантирует:

• Все эндпоинты. У OpenAI их много (эмбеддинги, аудио, файлы и другие). Совместимый сервис может реализовать только часть. В Zukko OpenAI-формат — это POST /v1/chat/completions, GET /v1/models и POST /v1/responses.
• Все параметры для каждой модели. Поля вроде tools или response_format передаются, но поддержка зависит от конкретной модели. Проверяйте на своих запросах.
• Одинаковые имена моделей. Названия задаёт сервис. Актуальный список и цены — GET https://api.zukko.pro/v1/models или страница «Модели» в кабинете.

Что такое base_url и почему в нём /v1

base_url — это начало адреса, к которому SDK приклеивает путь конкретного метода. Официальный Python SDK OpenAI для чат-запроса добавляет к base_url путь /chat/completions. Поэтому для OpenAI-формата в base_url уже должен быть /v1:

Две частые ошибки:

• Забыли /v1. Запрос уходит на https://api.zukko.pro/chat/completions, такого пути нет — ответ 404.
• Добавили /v1 дважды. Если вписать полный путь https://api.zukko.pro/v1/chat/completions в поле base URL, клиент допишет ещё один хвост, и снова будет 404.

У клиентов Anthropic логика другая: официальный Anthropic SDK и Claude Code сами добавляют /v1/messages, поэтому им нужен адрес без /v1. Подробный разбор — в статье base URL с /v1 или без↗.

Какие клиенты подключаются через base_url

Почти всё, что умеет работать с OpenAI, умеет работать и с совместимым сервисом:

• Официальные SDK. Python: OpenAI(base_url="https://api.zukko.pro/v1", api_key="fetch_..."); также SDK читает переменные OPENAI_BASE_URL и OPENAI_API_KEY. Node.js: new OpenAI({ baseURL: "https://api.zukko.pro/v1", apiKey: ... }).
• Фреймворки, например LangChain: в клиенте OpenAI задаётся тот же base URL.
• IDE и агенты: Cursor, Cline, Kilo Code, Codex — указываете base URL https://api.zukko.pro/v1 и ключ.
• Веб-интерфейсы для чата: LibreChat, Open WebUI и похожие.

Поле в настройках называется по-разному: Base URL, API Base, Endpoint, OpenAI API URL. Если не уверены, какое именно, сверьтесь с документацией самого инструмента. Смысл везде один: адрес до /v1 включительно и ключ.

Чем отличается Anthropic-формат

Второй распространённый стандарт — Messages API от Anthropic, родной формат моделей Claude. Его используют Claude Code, официальный Anthropic SDK и Roo Code. Главные отличия:

В Zukko любую модель можно вызвать в любом из двух форматов: шлюз конвертирует запрос. Разница появляется в цене при кэше. Для Claude скидку за чтение кэша даёт только Anthropic-формат: там шлюз видит, сколько входа пришло из кэша. В OpenAI-формате весь вход Claude идёт по цене входа. Пример по ценам на 7 октября 2026: у claude-sonnet-5 вход стоит $0.4 за 1M токенов, чтение кэша — $0.05. У GPT-моделей кэш виден в обоих форматах через prompt_tokens_details.cached_tokens. Как выбрать формат под задачу — в документации Anthropic или OpenAI формат↗.

Адреса Zukko

• OpenAI-формат: base URL https://api.zukko.pro/v1 → POST /v1/chat/completions, GET /v1/models, POST /v1/responses.
• Anthropic-формат: POST https://api.zukko.pro/v1/messages и POST /v1/messages/count_tokens.
• Клиенты, которые сами добавляют /v1 (Claude Code, Anthropic SDK, Roo Code): https://api.zukko.pro.
• OpenCode (провайдер anthropic через AI SDK): https://api.zukko.pro/v1.
• Claude Code: ANTHROPIC_BASE_URL=https://api.zukko.pro и ANTHROPIC_AUTH_TOKEN=fetch_..., плюс модели из каталога в ANTHROPIC_MODEL и ANTHROPIC_DEFAULT_HAIKU_MODEL: фоновые запросы идут на слот Haiku (по умолчанию claude-haiku-*), которого нет в каталоге, и без этой переменной получат 404 model_not_found.

Как проверить подключение через curl

Три команды покажут, что адрес, ключ и баланс в порядке.

1. Список моделей. Эндпоинт публичный, ключ не нужен:

curl https://api.zukko.pro/v1/models

2. Запрос в OpenAI-формате:

curl https://api.zukko.pro/v1/chat/completions \
  -H "Authorization: Bearer fetch_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-6.1-sol", "messages": [{"role": "user", "content": "Ответь одним словом: работает?"}]}'

3. Тот же вопрос в Anthropic-формате:

curl https://api.zukko.pro/v1/messages \
  -H "Authorization: Bearer fetch_ваш_ключ" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model": "claude-sonnet-5", "max_tokens": 64, "messages": [{"role": "user", "content": "Ответь одним словом: работает?"}]}'

Что означают ответы:

• 200 и текст — всё подключено.
• 401 — ключ неверный, с опечаткой или отозван.
• 402 — не хватает баланса.
• 403 model_not_allowed_for_key — модели нет в списке разрешённых для этого ключа.
• 404 model_not_found — неизвестное имя модели; сверьтесь с GET /v1/models.
• 404 с кодом not_found — такого пути нет: проверьте /v1 в адресе.

Если curl работает, а программа нет, проблема почти всегда в поле base URL или в имени модели в настройках клиента.

Минимальный пример на Python

from openai import OpenAI

client = OpenAI(base_url="https://api.zukko.pro/v1", api_key="fetch_ваш_ключ")

resp = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "Привет! Ответь одной фразой."}],
)
print(resp.choices[0].message.content)
print(resp.usage.prompt_tokens, resp.usage.completion_tokens)

Чтобы сменить модель, меняете только model, например на gpt-6.1-sol или deepseek-v4.1-flash. Полный справочник полей — в документации chat/completions↗, а пошаговое подключение к своему сервису — в статье как подключить нейросеть к своему приложению↗.

Если ключа ещё нет, создайте его на странице API-ключей↗ и подставьте в любой из примеров выше.

Частые вопросы

OpenAI compatible API — это только для моделей OpenAI?

Нет. Совместимость касается формата запросов, а не моделей. Через OpenAI-формат Zukko можно вызвать Claude, GPT, Gemini, DeepSeek, Qwen и GLM — меняется только значение model.

Почему клиент пишет 404, хотя ключ правильный?

Чаще всего из-за /v1: для OpenAI-клиентов он должен быть в base URL, для Claude Code и Anthropic SDK — нет. Второй вариант — неизвестное имя модели, тогда в ответе будет код model_not_found; в Claude Code так проявляется незаданный ANTHROPIC_DEFAULT_HAIKU_MODEL.

Какой формат выбрать для Claude?

Если важен кэш (агенты, длинные диалоги, большой системный промпт) — Anthropic-формат: только в нём шлюз учитывает чтение кэша Claude по сниженной цене. Для простых разовых запросов подойдёт любой.

Все ли параметры OpenAI поддерживаются?

Основные (model, messages, max_tokens, stream) — да. Поддержка tools, response_format и других зависит от модели; проверьте на своём запросе, прежде чем строить на них логику. Отдельный случай — temperature: по документации Zukko новые модели Claude могут отклонять нестандартные значения, поэтому для них её лучше не передавать.