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

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

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

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

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

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

Если в настройках AI-агента выбран приватный тип 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
}'

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())

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).

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

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

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())

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