OpenAI-compatible API подходит клиентам, которые уже работают с OpenAI SDK, Chat Completions или Responses. Anthropic-compatible API нужен инструментам и приложениям, ожидающим формат Messages 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, но клиент всё равно требует конкретный формат запросов.

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

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

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

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

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

Зафиксируйте SDK, endpoint и версию API.
Возьмите точный Model ID из текущего каталога.
Отправьте короткий запрос без tools и stream.
Проверьте обычный streaming до terminal event.
Выполните безопасный tool call без внешнего действия.
Создайте контролируемую ошибку с заведомо неверным Model ID.
Сопоставьте usage, status и request ID с Dashboard.
Проверьте 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.

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