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

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

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

Что на самом деле означает совместимость с OpenAI

Обычно без изменений можно использовать:

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

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

Актуальный каталог Модели и цены — основной источник сведений о модели, группе и поддерживаемом формате API.

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

До изменения кода приложения:

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

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

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": "Ответь названием активной модели."}
    ],
    "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": "Ответь названием активной модели.",
    "stream": false
  }'

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

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

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

При разборе медленного потока разделяйте:

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

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

Проверка перед запуском в production

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

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