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

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

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

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

Notopenaiv2

Даже при одинаковой задаче структура запросов сильно отличается. В одном 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 и названии модели.

Blue2

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

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

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

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

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

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

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

Указанная в запросе модель игнорируется — используется модель, заданная в настройках агента.
Некоторые параметры могут игнорироваться в зависимости от выбранной модели агента.
Промпт, указанный в настройках 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

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
}'

Python

import requests

url = "https://agent.timeweb.cloud/api/v1/cloud-ai/agents/{{agent_id}}/v1/chat/completions"

payload = {
    "model": "gpt.1",
    "messages": [
        {
            "role": "user",
            "content": "Привет!"
        }
    ],
    "temperature": 1,
    "max_tokens": 100,
    "stream": False
}
headers = {
    "authorization": "Bearer {{token}}",
    "content-type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

Node.js

const request = require('request');

const options = {
  method: 'POST',
  url: 'https://agent.timeweb.cloud/api/v1/cloud-ai/agents/{{agent_id}}/v1/chat/completions',
  headers: {authorization: 'Bearer {{token}}', 'content-type': 'application/json'},
  body: {
    model: 'gpt.1',
    messages: [{role: 'user', content: 'Привет!'}],
    temperature: 1,
    max_tokens: 100,
    stream: false
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Параметры:

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

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"
}'

Python

import requests

url = "https://agent.timeweb.cloud/api/v1/cloud-ai/agents/{{agent_id}}/v1/completions"

payload = {
    "prompt": "Привет!",
    "model": "4.1",
    "max_tokens": 100,
    "temperature": 0.7,
    "top_p": 0.9,
    "n": 1,
    "stream": False,
    "logprobs": None,
    "echo": False,
    "stop": ["
"],
    "presence_penalty": 0,
    "frequency_penalty": 0,
    "best_of": 1,
    "user": "timeweb"
}
headers = {
    "authorization": "Bearer {{token}}",
    "content-type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

Node.js

const request = require('request');

const options = {
  method: 'POST',
  url: 'https://agent.timeweb.cloud/api/v1/cloud-ai/agents/{{agent_id}}/v1/completions',
  headers: {authorization: 'Bearer {{token}}', 'content-type': 'application/json'},
  body: {
    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'
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Параметры:

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"
    }
  ]
}'

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

Была ли статья полезна?

Ваша оценка очень важна

Пока нет комментариев

Вход / Регистрация

Облачные сервисы

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

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

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

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

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

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

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

Базовый URL

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

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

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

Роли

user

assistant

system

Была ли статья полезна?

Сервисы

Решения

Инструменты

Партнерам

Техподдержка

Компания