---
title: "OpenAI-совместимый API в AI-агентах"
description: "OpenAI-совместимый API в AI-агентах. Документация и инструкции по использованию и настройке облачных сервисов Timeweb Cloud."
---

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

> Полный индекс документации для ИИ-агентов: [llms.txt](https://timeweb.cloud/llms.txt).

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

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

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

![Aiapi Example](https://content.timeweb.com/assets/e16f7974-1fb9-427b-8f5b-2e021a6273e7.png?width=1316&height=1004)

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

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

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

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

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

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

![Blue2](https://content.timeweb.com/assets/60563a27-fc57-4d02-9c60-d52398e5512c.png?width=1560&height=1218)

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

-   Быстрая интеграция в любое ПО, которое поддерживает OpenAI API;
-   Поддержка популярных библиотек (например, LangChain);
-   Работа с готовыми UI (например, [Open WebUI](https://timeweb.cloud/docs/ai-agents/api-usage/open-webui));
-   Минимум усилий при миграции с OpenAI.

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

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

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

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

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

-   Указанная в запросе модель игнорируется — используется модель, заданная в настройках агента.
-   Некоторые параметры могут игнорироваться в зависимости от выбранной модели агента.
-   [Промпт, указанный в настройках AI-агента](https://timeweb.cloud/docs/ai-agents/manage-agents/instructions), используется при запросах без явного указания.

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

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

> [!NOTE]
> Все доступные методы API можно найти [в документации](https://agent.timeweb.cloud/docs).

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

Вне зависимости от выбранного типа API (приватный или публичный), для отправки запросов необходимо [указывать API-токен](https://timeweb.cloud/docs/ai-agents/manage-agents/api-access-key).

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

```shell
Authorization: Bearer $TOKEN
```

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

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

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

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

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

### Базовый URL

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

![Scr 20251003 Phme](https://content.timeweb.com/assets/7ac4875b-9324-4552-a992-be4953102a21.png?width=1524&height=1750)

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

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

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

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

cURL

```js
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

```py
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

```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` — [роль отправителя](https://timeweb.cloud/docs/ai-agents/api-usage/openai-compatible-api#roli) (`user`, `assistant`, `system`),
    
-   `content` — текст сообщения.
    

-   `temperature` — креативность ответа.
    
-   `max_tokens` — ограничение длины ответа.
    
-   `stream` — потоковый вывод (true/false).
    

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

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

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

```js
{
  "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

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

cURL

```bash
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

```py
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

```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`) поддерживаются частично и в основном для совместимости.

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

```js
{
  "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` используется для передачи обычных запросов пользователя к ИИ.

**Пример**:

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

### assistant

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

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

**Пример**:

```bash
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` остается без ответа — именно на него модель сгенерирует новый ответ.

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

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

### system

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

Подробнее о системных промптах [написали в отдельной статье](https://timeweb.cloud/docs/ai-agents/manage-agents/instructions).

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

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

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

**Пример**:

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

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