# OpenAI-compatible API: реальная compatibility matrix

> Короткий ответ: Совместимость — это 4 вещи: чат, модели, Bearer-ключ и поток. Всё остальное (Responses, инструменты, structured, коды) у всех разное — пишите переносимый клиент.

Надпись «OpenAI-compatible» обещает, что код переедет сменой адреса. На практике переезжает ядро, а края у всех свои: другой формат ответов, другие инструменты, другие коды ошибок. Разбираем, что входит в фактический стандарт из четырёх вещей, пять мест, где всё ломается, и как писать клиент, который переживает смену провайдера.

- Категория: Протоколы
- Автор: Редакция NormaHub
- Техническая проверка: Техническая проверка NormaHub
- Опубликовано: 2026-10-01
- Обновлено: 2026-10-01

## Ядро: что совместимо почти везде

Минимальный контракт, на который можно рассчитывать: создание чата по POST, список моделей чтением, авторизация Bearer-ключом и поток с чанками и финальным маркером. Это и есть де-факто стандарт — всё, что сверх, уже договорённости конкретных провайдеров. Проверяйте каждое из четырёх отдельно: адрес, ключ, список, поток.

Сопутствующие мелочи стандарта: отзыв ключа вступает быстро, но распространяется с задержкой до минут — учитывайте при ротации. Свой ID операции держите в своём логе, ответный — из заголовков и тела ответа. Это та часть, которая обычно совпадает, и именно на неё опирается переносимый клиент.



- ядро: чат, модели, Bearer, поток с маркером

- каждое из четырёх проверять отдельно

- ротация ключа — с задержкой распространения

- свой и ответный ID — логировать оба

## Пять мест расхождения

Первое — Responses API: новый примитив вместо чата с другими полями (вход вместо сообщений, вывод массивом, свои форматы, нет множественных вариантов, сохранение по умолчанию). Кто-то его даёт, кто-то нет — узнавайте заранее. Свежий пример 29 сентября 2026 года: у новой модели среднего класса вызов инструментов работает только через Responses, а в чате отключён вместе с частью уровней рассуждений и настроек выборки. Второе — инструменты: вызов при рассуждающих режимах у части провайдеров работает только через Responses, а не через чат. Третье — структурированный вывод: все режут JSON-схемы по-разному, лимиты вложенности и числа полей различаются.

Четвёртое — usage в потоке: у кого-то приходит только с явным флагом и только в последнем чанке, без флага биллинг вслепую. Пятое — коды ошибок и тексты: балансы, лимиты и перегрузки кодируются по-разному, тексты сообщений вообще не договор. Разбор — только по статусу плюс коду, никогда по тексту.



- Responses — другой примитив, есть не везде

- инструменты при reasoning — бывает только в Responses

- структуры режутся по-разному, лимиты свои

- usage в потоке — с флагом и в конце

- разбор ошибок — статус плюс код, не текст

## Переносимый клиент и чеклист смены

Читайте возможности, а не бренд: модели — запросом, endpoints — из каталога, поведение — пробным вызовом. Неизвестные параметры не слать, парсер потока — под оба диалекта, модель — константой в одном месте: переезд тогда — смена адреса и ID, а не переписывание.

Логируйте связку ID каждого вызова; ретраи — только временному. Чеклист за вечер: модели читаются, запрос проходит, поток читается, ошибка разбирается, usage сходится, лимит держит пик. Не сошлось — трафик не переключать.



- возможности — запросом, модель — константой

- парсер — под оба диалекта

- ретраи — только временному

- не сошлось — не переключать

## Источники

- [Документация API](/docs)
- [Гайд по ошибкам API](/guides/errors)

## Следующие шаги

- [Зачем AI Gateway](/company/articles/ai-gateway-zachem-nuzhen-2026)
- [Первый запрос на Python](/guides/python)