OpenAI-compatible или Anthropic-compatible API: что выбрать

OpenAI-compatible API подходит клиентам, которые уже работают с OpenAI SDK, Chat Completions или Responses; параметры доступа и текущий путь подключения собраны на странице OpenAI API. Anthropic-compatible API нужен инструментам и приложениям, ожидающим формат Messages API; для этого сценария используйте страницу Claude API. Совместимость упрощает подключение, но не гарантирует одинаковые модели, параметры, streaming-события, tool use и ошибки. Протокол выбирают по контракту клиента, а перед переносом проверяют реальный запрос.

Что означает API-compatible

Совместимый API принимает знакомую структуру запроса и возвращает ответ, который способен разобрать существующий SDK или клиент. Обычно разработчик меняет Base URL, API Key и Model ID, сохраняя большую часть прикладного кода.

У этой формулировки есть граница. Провайдер может поддерживать базовую генерацию текста и не поддерживать отдельный параметр, встроенный tool, аудио, изображения или точную семантику ошибки. Даже два endpoint с одинаковым названием поля model могут по-разному формировать список доступных моделей и правила доступа к ним.

Хотите проверить выбранный протокол на реальном запросе? Можно создать собственный аккаунт BetterToken и API Key, затем открыть краткое руководство и выполнить один минимальный тест. BetterToken предоставляет отдельные OpenAI-compatible и Anthropic-compatible интерфейсы; протокол, Base URL, тип API Key и текущий Model ID должны совпасть с актуальным API reference.

Чем отличаются запросы и авторизация

В OpenAI-совместимом сценарии клиент обычно собирает messages для Chat Completions либо input для Responses API. Авторизация часто передаётся как Bearer token:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Anthropic Messages использует свою структуру сообщений, отдельный system, обязательный лимит вывода и версию протокола. В официальном API Anthropic встречаются заголовки x-api-key и anthropic-version:

x-api-key: YOUR_API_KEY
anthropic-version: CURRENT_SUPPORTED_VERSION
Content-Type: application/json

Совместимый gateway может принимать другой способ авторизации. Поэтому заголовки берут из документации конкретного endpoint. Пример официального API объясняет формат протокола, но не заменяет инструкцию провайдера.

Различается и роль системной инструкции. В одном контракте она находится среди сообщений, в другом передаётся отдельным полем. Механическая конвертация может изменить порядок контекста, cache prefix или поведение клиента.

Chat Completions, Responses и Messages — разные контракты

Слово OpenAI-compatible само по себе не отвечает, какой именно интерфейс реализован. Для миграции нужно записать точный контракт:

• Chat Completions: массив messages, ответ через choices, потоковые фрагменты через delta.
• Responses API: входные items, типизированные output items и отдельные события жизненного цикла response.
• Anthropic Messages: messages, отдельный system, content blocks и собственные события stream.

Если библиотека ожидает Responses API, наличие только /chat/completions её не спасёт. Если Claude Code ожидает Anthropic Messages, OpenAI-совместимый endpoint без адаптера тоже не подойдёт. Простая замена Base URL работает лишь тогда, когда клиент и сервер реализуют один и тот же контракт.

Как отличаются streaming и завершение ответа

Все три интерфейса могут передавать данные потоком, но названия и порядок событий различаются.

Responses API отправляет типизированные Server-Sent Events, например создание response, фрагменты текста и terminal event. Клиент должен дождаться события завершения либо обработать failed или incomplete.

Anthropic Messages передаёт события message_start, события content block, message_delta и message_stop. Ошибка может появиться уже после успешного HTTP-ответа, внутри открытого stream.

В Chat Completions клиент обычно накапливает choices[0].delta, а конец потока определяет по контракту этого endpoint. Код, который ищет только один маркер, нельзя без проверки переносить в Responses или Messages.

Минимальный обработчик хранит четыре состояния:

created -> receiving -> completed
                   \-> failed
                   \-> disconnected

disconnected не равен completed. Если соединение оборвалось после части ответа, нужно сохранить полученные события и решить, допустим ли повторный запрос.

Tool use и structured output

Названия tools и tool_calls создают впечатление прямой совместимости. В рабочем приложении проверьте как минимум:

• JSON Schema и ограничения поддерживаемых типов;
• параллельные tool calls;
• способ передачи результата tool обратно модели;
• потоковую сборку аргументов;
• поведение при невалидном JSON;
• строгий structured output и отказ модели следовать схеме.

Адаптер обязан сохранять смысл вызова, а не только переименовывать поля. Особенно это важно для инструментов с побочными эффектами: повтор одного и того же tool call может второй раз отправить сообщение, создать запись или провести операцию.

Ошибки нельзя сопоставлять только по HTTP-коду

401, 403, 404, 429 и 5xx дают полезную первую классификацию, но тело ошибки и заголовки у провайдеров различаются. Для диагностики сохраняйте:

• HTTP status;
• provider error type и code;
• короткое сообщение без секретов;
• request ID;
• retry-related headers;
• endpoint, протокол и Model ID.

Не записывайте API Key, полный prompt или чувствительный ответ. Если gateway нормализует ошибки, сохраняйте исходный provider code в безопасном внутреннем поле. Иначе model not found, отсутствие доступа и несовместимый endpoint могут превратиться в один неинформативный 400.

Как выбрать протокол

Готовый AI-инструмент

Сначала откройте документацию инструмента. Если он просит OpenAI Base URL и использует Chat Completions или Responses, выбирайте соответствующий OpenAI-compatible endpoint. Если он читает ANTHROPIC_BASE_URL и ожидает Messages API, нужен Anthropic-compatible endpoint.

Не выбирайте протокол по названию модели. Одна модель может быть доступна через определённый gateway, но клиент всё равно требует конкретный формат запросов.

Например, Codex требует Responses и корректный custom provider. Практическую разницу между CLI, Desktop App и Extension смотрите в разборе Codex CLI или Codex App и отдельной инструкции для Codex в VS Code.

Собственное приложение

Выбор зависит от уже используемого SDK и функций. При новом проекте составьте список обязательных возможностей: streaming, tools, structured output, vision, token usage, batch или другие endpoints. Затем проверьте их в официальной документации провайдера.

Миграция между провайдерами

Оцените не число изменённых строк, а поверхность контракта. Базовый чат может потребовать три новых значения конфигурации. Agent-приложение с tools, длинной историей, cache и streaming обычно нуждается в адаптере и интеграционных тестах.

Проверка перед переносом рабочего трафика

1. Зафиксируйте SDK, endpoint и версию API.
2. Возьмите точный Model ID из текущего каталога.
3. Отправьте короткий запрос без tools и stream.
4. Проверьте обычный streaming до terminal event.
5. Выполните безопасный tool call без внешнего действия.
6. Создайте контролируемую ошибку с заведомо неверным Model ID.
7. Сопоставьте usage, status и request ID с Dashboard.
8. Проверьте timeout и ограниченный retry.

Только после этого переносите реальную нагрузку. Для BetterToken начните с API reference, выберите один протокол и подтвердите минимальный запрос до подключения agent tools.

FAQ

OpenAI-compatible API полностью повторяет OpenAI API?

Нет. Термин указывает на совместимость определённого интерфейса. Поддержка моделей, параметров, tools, streaming, ошибок и дополнительных endpoints проверяется отдельно.

Можно ли использовать Anthropic-совместимый endpoint через OpenAI SDK?

Не напрямую, если SDK формирует OpenAI-контракт. Нужен клиент с поддержкой Anthropic Messages или адаптер, который корректно преобразует сообщения, stream и tool use.

Достаточно ли заменить Base URL?

Иногда — для короткого текстового запроса в уже совместимом клиенте. Для production-переноса всё равно проверьте Model ID, авторизацию, streaming, tools, ошибки и usage.

Какой протокол нужен для Claude Code?

Claude Code обычно работает с Anthropic-compatible интерфейсом. Точные переменные, Base URL и модель берите из текущей инструкции BetterToken.