API, совместимый с OpenAI: смена базового URL

Что охватывает совместимость с OpenAI, как перевести существующий клиент на Modelflare и какие границы проверить перед запуском рабочего трафика.

API, совместимый с OpenAI: смена базового URL

Совместимый с OpenAI API позволяет существующему клиенту сохранить привычный заголовок аутентификации, структуру JSON-запроса и схему потоковой передачи, но отправлять трафик через другой шлюз. Иногда достаточно заменить базовый URL и API-ключ. Однако совместимость — это контракт протокола, а не обещание, что любая модель поддерживает любой эндпоинт или специфичное поле провайдера.

В этом руководстве описан безопасный порядок перехода для приложений, скриптов и ИИ-инструментов, которые уже работают с API в стиле OpenAI.

Что на самом деле охватывает совместимость с OpenAI

Чаще всего без изменений переиспользуются такие части контракта:

  • Bearer-аутентификация через заголовок Authorization.
  • JSON-запросы и JSON-ответы на версионированных эндпоинтах /v1.
  • Распространённые эндпоинты: /v1/models, /v1/chat/completions и /v1/responses.
  • Server-Sent Events для поддерживаемых потоковых запросов.
  • Привычные поля запроса — model, messages, input, stream — и определения инструментов, если их поддерживает выбранный протокол.

Совместимость не означает, что одну модель можно свободно переключать между Chat Completions и Responses. Модель может быть доступна только через один проверенный протокол. Специфичные для провайдера поля рассуждений, поиска или мультимодального ввода тоже могут требовать передачи без изменений (raw pass-through), а не преобразования на стороне шлюза.

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

Подготовка к переходу

Прежде чем менять код приложения:

  1. Создайте отдельный ключ в разделе API-ключи, а не используйте повторно личный ключ или ключ другой интеграции.
  2. Выберите основную группу моделей с доступом к нужной модели.
  3. Добавляйте резервные группы в явном порядке, только если они тоже поддерживают эту модель и соответствуют тем же требованиям к стоимости и надёжности.
  4. Запишите текущий эндпоинт, ID модели, настройку потоковой передачи и используемые инструменты, чтобы сравнить поведение до и после перехода.

Канонический базовый URL Modelflare для API, совместимого с OpenAI:

https://modelflare.dev/v1

Большинство SDK ожидают, что базовый URL заканчивается на /v1, и сами добавляют /chat/completions или /responses. Прежде чем дописывать к пути ещё один суффикс эндпоинта, сверьтесь с документацией клиента.

Сначала проверьте аутентификацию и доступ к модели

Храните ключ в переменной окружения, а не в исходном коде:

export MODELFLARE_API_KEY='YOUR_MODELFLARE_API_KEY'

Затем убедитесь, что ключ может получить список доступных моделей:

curl -sS https://modelflare.dev/v1/models \
  -H "Authorization: Bearer $MODELFLARE_API_KEY"

Успешный ответ подтверждает, что имя хоста, TLS-соединение и ключ в порядке. Но он ещё не доказывает, что конкретный формат запроса подходит для каждой модели из списка, поэтому следующую проверку нужно выполнить на целевом эндпоинте.

Отправьте один запрос по нужному протоколу

Для модели Chat Completions, которая указана как совместимая с этим форматом:

curl -sS https://modelflare.dev/v1/chat/completions \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CHAT_MODEL",
    "messages": [
      {"role": "user", "content": "Reply with the active model name."}
    ],
    "stream": false
  }'

Для модели для программирования, совместимой с Responses:

curl -sS https://modelflare.dev/v1/responses \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "Reply with the active model name.",
    "stream": false
  }'

Используйте точный ID модели из актуального каталога. Ошибка model_not_found обычно означает, что у выбранного ключа или группы нет доступа к этой модели; смена регистра букв запрос не исправит.

Проверьте потоковую передачу отдельно

Успешного запроса без потоковой передачи недостаточно, если приложение от неё зависит. Повторите запрос с "stream": true, убедитесь, что события приходят постепенно, а клиент не буферизует весь ответ перед отображением.

Если поток идёт медленно, разделяйте:

  • время на аутентификацию и выбор маршрута;
  • время до получения заголовков ответа от поставщика;
  • время до первого полезного фрагмента контента или вызова инструмента;
  • скорость генерации после появления видимого вывода.

Для этого журнал использования Modelflare хранит временные метаданные каждого запроса, но не сохраняет промпты, тексты ответов, необработанные тела запросов, API-ключи, адреса электронной почты и IP-адреса в открытом виде.

Чек-лист перед переводом рабочего трафика

  • Храните API-ключ в хранилище секретов или в переменной окружения.
  • Зафиксируйте базовый URL https://modelflare.dev/v1.
  • Используйте модель, которая явно поддерживает выбранный эндпоинт.
  • Проверяйте режимы с потоковой передачей и без неё по отдельности.
  • Если приложение использует инструменты, структурированный вывод, настройки рассуждений или мультимодальный ввод, протестируйте и их.
  • Сохраняйте явно заданные нулевые значения и false, если в запросе клиента они несут смысл.
  • Настраивайте тайм-ауты клиента под реальную нагрузку, а не под короткий промпт для проверки работоспособности.
  • После переключения проверьте в журнале использования статус, задержку, расход токенов, выбранную группу и стоимость.

Когда граница протокола проверена, клиент обычно сохраняет прежний жизненный цикл запроса, а Modelflare за совместимым эндпоинтом обеспечивает доступ к моделям, политику маршрутизации и прозрачность каждого запроса.

Об операционном уровне за этим эндпоинтом читайте в статье Что такое API-шлюз для ИИ?. Если клиент поддерживает несколько форматов OpenAI, перед сменой путей сравните Responses API и Chat Completions.