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

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

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

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

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

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

    

      

    
    "context": {
  "thread_id": "abc123",
  "reply_to": "msg789"
 },
  

Кроме того, при работе с нашим 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 отсутствует;
• Fine-tuning — обучение и кастомизация моделей;
• Images API — генерация изображений;
• Audio API — преобразование речи в текст и обратно (кроме аудиосообщений в чате);
• Files API — загрузка и управление файлами;
• Assistants API — создание и управление ассистентами;
• Web search — поиск и получение данных из интернета.

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

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

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

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

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

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

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

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

    

      

    
    Authorization: Bearer $TOKEN
  

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

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

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

    

      

    
    export TOKEN=ваш_токен_доступа
  

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

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

Базовый URL

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

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

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

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

    

      

    
    POST /api/v1/cloud-ai/agents/{{agent_id}}/v1/chat/completions
  

    

      

    
    curl --request POST \
  --url https://agent.timeweb.cloud/api/v1/cloud-ai/agents/{{agent_id}}/v1/chat/completions \
  --header 'authorization: Bearer $TOKEN' \
  --header 'content-type: application/json' \
  --data '{
  "model": "gpt-4.1",
  "messages": [
    {
      "role": "user",
      "content": "Привет!"
    }
  ],
  "temperature": 1,
  "max_tokens": 100,
  "stream": false
}'
  

Параметры:

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

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

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

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

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

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

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

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

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

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

    

      

    
    {
  "id": "fc8cd652-af12-4a89-8ef7-490a0526e8d3",
  "object": "chat.completion",
  "created": 1757601532,
  "model": "gpt-4.1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Привет! Чем могу помочь? 😊"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 8,
    "total_tokens": 18
  }
}
  

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

    

      

    
    POST /api/v1/cloud-ai/agents/{{agent_id}}/v1/completions
  

    

      

    
    curl --request POST \
  --url https://agent.timeweb.cloud/api/v1/cloud-ai/agents/{{agent_id}}/v1/completions \
  --header 'authorization: Bearer $TOKEN' \
  --header 'content-type: application/json' \
  --data '{
  "prompt": "Привет!",
  "model": "gpt-4.1",
  "max_tokens": 100,
  "temperature": 0.7,
  "top_p": 0.9,
  "n": 1,
  "stream": false,
  "logprobs": null,
  "echo": false,
  "stop": [
    "\n"
  ],
  "presence_penalty": 0,
  "frequency_penalty": 0,
  "best_of": 1,
  "user": "timeweb"
}'
  

Параметры:

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

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

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

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

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

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

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

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

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

    

      

    
    {
  "id": "7f967459-428c-46ad-87f0-213ff951024d",
  "object": "text_completion",
  "created": 1757601892,
  "model": "gpt-4.1",
  "choices": [
    {
      "text": "Привет! Чем могу помочь? 😊",
      "index": 0,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 8,
    "total_tokens": 18
  },
  "response_id": "ea9aa124-0c51-467c-9ab6-218ab4ec65e7"
}
  

Роли

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

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

user

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

Пример:

    

      

    
    {
  "role": "user",
  "content": "Сколько будет 2+5?"
}

  

assistant

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

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

Пример:

    

      

    
    curl --request POST \
  --url https://agent.timeweb.cloud/api/v1/cloud-ai/agents/{{agent_id}}/v1/chat/completions \
  --header 'authorization: Bearer $TOKEN' \
  --header 'content-type: application/json' \
  --data '{
  "model": "gpt-4",
  "messages": [
    {
      "role": "user",
      "content": "Сколько будет 2+5? Напиши только ответ без форматирования"
    },
    {
      "role": "assistant",
      "content": "7"
    },
    {
      "role": "user",
      "content": "Теперь умножь получившееся число на 2. Напиши только ответ без форматирования"
    }
  ]
}'

  

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

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

    

      

    
    {
  "index": 0,
  "message": {
    "role": "assistant",
    "content": "14",
    "refusal": null,
    "annotations": []
  },
  "finish_reason": "stop"
}

  

system

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

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

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

    

      

    
    Напиши только ответ без форматирования
  

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

Пример:

    

      

    
    curl --request POST \
  --url https://agent.timeweb.cloud/api/v1/cloud-ai/agents/{{agent_id}}/v1/chat/completions \
  --header 'authorization: Bearer $TOKEN' \
  --header 'content-type: application/json' \
  --data '{
  "model": "gpt-4",
  "messages": [
    {
      "role": "system",
      "content": "При ответе на вопросы отправляй только результат вычислений, без какого-либо форматирования."
    },
    {
      "role": "user",
      "content": "Сколько будет 2+5?"
    },
    {
      "role": "assistant",
      "content": "7"
    },
    {
      "role": "user",
      "content": "Теперь умножь получившееся число на 2"
    }
  ]
}'

  

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