OpenAI-compatible API для нескольких LLM-провайдеров

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

Совместимый endpoint повторяет основные структуры запросов и ответов OpenAI API, чтобы существующие SDK могли обращаться к другому gateway. Совместимость не означает, что каждый провайдер поддерживает абсолютно все поля. Параметры reasoning, изображения, audio и tools зависят от модели и маршрута.

Миграция Python-клиента

Начинайте с минимального запроса, затем включайте streaming, tools и специфичные параметры. Это быстрее выявляет несовместимое поле или ограничение выбранного канала.

from openai import OpenAI

client = OpenAI(
    api_key="clodex_YOUR_KEY",
    base_url="https://clodex.xyz/v1",
)

response = client.responses.create(
    model="gpt-5.6-sol",
    input="Проверь совместимость клиента",
)
print(response.output_text)

Миграция JavaScript-клиента

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.CLODEX_API_KEY,
  baseURL: "https://clodex.xyz/v1",
});

const response = await client.responses.create({
  model: "gpt-5.6-luna",
  input: "Summarize the incident",
});

Проверки перед production

• Не храните API-ключ во frontend-коде или мобильном приложении без собственного backend.
• Проверяйте HTTP status, structured error и terminal event stream.
• Логируйте request ID, фактическую модель, latency и стоимость.
• Используйте таймауты, лимиты параллельности и контролируемые retry.

Границы OpenAI compatibility

Совместимость означает знакомую авторизацию и request/response envelope, но не обещает поддержку каждого параметра любой моделью. Responses API, Chat Completions, Anthropic Messages и Gemini native — разные контракты. Перед миграцией выпишите реально используемые поля: tools, response format, reasoning, изображения, audio и stream options.

Если модель обслуживается Codex-каналом, безопасный общий пример строится на Responses API. Chat Completions используйте только после подтверждения, что выбранная модель и канал поддерживают этот маршрут.

Пошаговая проверка после замены base_url

Такой порядок локализует несовместимость: вы понимаете, сломан ли endpoint, модель, дополнительное поле или parser потока. Одновременная замена адреса, модели и всего набора параметров усложняет диагностику.

• Проверьте GET /v1/models с новым ключом.
• Отправьте минимальный non-stream запрос без необязательных полей.
• Сверьте structured error для неверного ключа и недоступной модели.
• Отдельно включите streaming и дождитесь terminal event.
• Только затем подключайте tools и business side effects.

JSON-ошибка API и HTML-ошибка proxy — не одно и то же

API обычно возвращает structured JSON с HTTP status и кодом ошибки. Если клиент получил HTML-страницу Cloudflare или nginx вместо JSON/SSE, сбой произошёл до корректного ответа приложения. Такой payload нельзя передавать в обычный parser событий или считать ответом модели.

Сохраняйте status, content-type, request ID и первые безопасные байты диагностического тела. Полный request body и Authorization header в лог писать нельзя.

Для streaming дополнительно фиксируйте последнее корректно разобранное событие. EOF после промежуточного delta не равен response.completed или message_stop, даже если пользователь успел увидеть часть текста.