OpenAI-совместимый API

OpenAI-совместимый API — это способ унифицировать структуру запросов и ответов к разным AI-провайдерам. Вместо того чтобы разбираться с десятками разных форматов, вы работаете с единым стандартом, понятным SDK, библиотекам и интерфейсам.

Зачем нужна унификация

Сравним два варианта нативных API: api.timeweb.cloud и условный api.somerandomai.com. Посмотрим, как у них реализована отправка сообщений.

Даже при одинаковой задаче структура запросов сильно отличается. В одном API для сохранения контекста используется parent_message_id, в другом — вложенный объект:

Например, в одном API для сохранения контекста используется параметр parent_message_id, а в другом — вложенный объект:

Кроме того, при работе с нашим API настройки задаются отдельным запросом, а в примере стороннего API — передаются в объекте settings вместе с каждым сообщением.

В результате приходится:

• Писать отдельный клиент под каждый API;
• Разбираться с названиями полей и особенностями работы;
• Тестировать все с нуля.

OpenAI-совместимый API решает эту проблему. Структура всегда одна и та же: массив messages с полями role и content, стандартные параметры (model, temperature, max_tokens). Отличия остаются только в URL и названии модели.

Чем это удобно:

• Быстрая интеграция в любое ПО, которое поддерживает OpenAI API;
• Поддержка популярных библиотек (например, LangChain);
• Работа с готовыми UI (например, Open WebUI);
• Минимум усилий при миграции с OpenAI.

Ограничения и особенности

В текущей реализации API не полностью совместимо с OpenAI.

Не поддерживается:

• Embeddings — эндпоинт /v1/embeddings отсутствует;
• Responses API — функциональность для создания ответов не реализована;
• Fine-tuning — обучение и кастомизация моделей;
• Images API — генерация изображений;
• Audio API — преобразование речи в текст и обратно (кроме аудиосообщений в чате);
• Files API — загрузка и управление файлами;
• Assistants API — создание и управление ассистентами;

Особенности реализации:

• Указанная в запросе модель игнорируется — используется модель, заданная в настройках агента.
• Некоторые параметры могут игнорироваться в зависимости от выбранной модели агента.
• Промпт, указанный в настройках AI-агента  используется при запросах без явного указания.

Использование

Рассмотрим как использовать OpenAI-совместимый API.

Все доступные методы API можно найти в документации.

Аутентификация

Независимо от выбранного типа API (приватный или публичный), для отправки запросов необходимо указывать API-токен.

Токен передается в заголовке запроса в следующем формате:

В cURL-примерах вы можете:

• указать токен вручную, заменив $TOKEN на ваш реальный токен в каждом запросе;

• или использовать переменную окружения, чтобы не вставлять токен каждый раз:

В этом случае менять заголовок в примерах не потребуется — переменная $TOKEN будет подставляться автоматически.

В примерах на Python и Node.js токен указывается напрямую в коде и обозначается как {{token}}. Мы рекомендуем хранить его в переменных окружения или конфигурационных файлах, а не в коде, чтобы избежать утечек.

Базовый URL

Для работы с API также потребуется базовый URL. Вы можете найти его во вкладке «Дашборд» в панели управления агентом.

Отправка сообщения агенту

Поддерживается два способа — Chat Completions и Text Completions. Способ Text Completions считается устаревшим и реализован только для поддержания обратной совместимости, мы не рекомендуем его использовать.

Пример использования Chat Completions

Параметры:

• model — необязательный, игнорируется (для совместимости).

• messages — массив сообщений:

• role — роль отправителя (user, assistant, system),

• content — текст сообщения.

• temperature — креативность ответа.

• max_tokens — ограничение длины ответа.

• stream — потоковый вывод (true/false).

Для моделей gpt-5 параметр max_tokens заменен на max_completion_tokens, а использование temperature вызовет ошибку.

Дополнительные параметры могут отличаться в зависимости от модели. При составлении запроса ориентируйтесь на параметры, доступные в панели управления для выбранной модели: если параметр есть в панели, значит он поддерживается при обращении через API.

Пример ответа:

Пример использования Text Completions

Параметры:

• prompt — текст запроса.

• model — игнорируется, указывается для совместимости.

• max_tokens — ограничение длины ответа.

• temperature — уровень креативности.

• top_p — выборка по вероятностям.

• n — количество вариантов ответа (игнорируется).

• stream — потоковый вывод.

Остальные параметры (logprobs, echo, stop, presence_penalty, frequency_penalty, best_of, user) поддерживаются частично и в основном для совместимости.

Пример ответа:

Роли

В режиме Chat Completions каждое сообщение передается с указанием роли. Существует три типа ролей:

• user — пользовательский запрос;
• assistant — ответ модели;
• system — инструкция, определяющая поведение агента.

user

Роль user используется для передачи обычных запросов пользователя к ИИ.

Пример:

assistant

Роль assistant применяется при передаче истории сообщений. Она указывает, что это ответ ИИ на предыдущий запрос.

Важно помнить, что при работе с OpenAI-совместимым API история диалога передается в каждом запросе, поэтому необходимо указывать как запросы (user), так и ответы (assistant), чтобы сохранить контекст.

Пример:

В запросе мы передали предыдущий вопрос и ответ, указав "role": "user" для сообщений пользователя и "role": "assistant" — для ответов ИИ. Последнее сообщение с ролью user остается без ответа — именно на него модель сгенерирует новый ответ.

Пример ответа:

system

Роль system используется для задания системного промпта — инструкции, которая определяет поведение агента: стиль, тон, ограничения, цели. Обычно это первое сообщение в массиве messages.

Подробнее о системных промптах написали в отдельной статье.

Если посмотреть на пример использования assistant, можно заметить, что в запросах пользователя повторяется инструкция:

Это дублирование можно избежать, указав инструкцию один раз в системном промпте.

Пример:

Теперь модель будет следовать инструкции, даже если она не повторяется в каждом запросе пользователя.