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

# AI Gateway

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

AI Gateway — это API для работы напрямую с языковыми моделями без использования AI-агентов.

В отличие от [OpenAI-совместимого API](https://timeweb.cloud/docs/ai-agents/api-usage/openai-compatible-api) и [нативного API](https://timeweb.cloud/docs/ai-agents/api-usage/native-api), AI Gateway не предоставляет возможности агентов, такие как:

-   RAG;
-   MCP;
-   Системные настройки (системный промпт, температура, ограничения на длину ответа).

AI Gateway подходит, когда требуется работать с моделями напрямую, без логики AI-агента.

Например:

-   если вы реализуете собственную логику поверх моделей (строите RAG, подключение MCP);
-   если нужна единая точка доступа к нескольким моделям;
-   если вы уже используете OpenAI SDK и хотите переключаться между моделями без изменения кода.

Отличия AI Gateway от OpenAI-совместимого API:

|  | **OpenAI-совместимый API** | **AI Gateway** |
| --- | --- | --- |
| **Объект работы** | Агент | Модель |
| **RAG / MCP** | Есть | Нет |
| **Системные настройки** | Можно задать в панели управления агента | Передаются с каждым запросом |
| **Выбор модели** | Модель агента | Любая доступная |

Для работы с API рекомендуется использовать OpenAI SDK — он абстрагирует различия и упрощает интеграцию.

Поддерживаемые методы и возможности зависят от используемой модели. Например, эндпоинт `responses` доступен только для моделей с поддержкой размышлений.

В AI Gateway не поддерживаются:

-   `Fine-tuning` — обучение и кастомизация моделей;
-   `Video API` — работа с видео.

## Управление AI Gateway

Для работы с AI Gateway перейдите во вкладку «AI Gateway» в разделе «ИИ-сервисы».

В интерфейсе доступны три вкладки:

-   «Модели»;
-   «Подключение»;
-   «API-ключи».

### Выбор модели

Во вкладке «Модели» отображаются доступные модели и их параметры:

-   тип;
-   объем контекста;
-   максимальная длина ответа;
-   стоимость входящих и исходящих токенов.

Чтобы найти подходящую модель, отфильтруйте список по типу или провайдеру либо введите название модели в поле поиска.

![Модели](https://content.timeweb.com/assets/dab6ed12-59ec-4741-9c82-305bd6452a98.png?width=2244&height=1596)

Для сопоставления характеристик нажмите «Сравнить модели» и выберите нужные модели.

### Получение параметров подключения

Во вкладке «Подключение» выберите модель и инструмент — язык программирования, для которого требуется пример.

В интерфейсе отобразятся:

-   базовый URL для подключения;
-   стоимость входящих и исходящих токенов выбранной модели;
-   команда для установки библиотеки OpenAI;
-   базовый пример подключения к API.

![ПОдключение](https://content.timeweb.com/assets/b6b57ae6-dfb2-4c62-a624-0e01548a8365.png?width=2166&height=1942)

### Создание API-ключа

AI Gateway использует отдельные ключи, не связанные с API-ключами аккаунта.

> [!NOTE]
> Каждый API-ключ тарифицируется отдельно и стоит 1 ₽ в месяц.

Чтобы создать API-ключ:

1.  Перейдите во вкладку «API-ключи» и нажмите «Добавить».
    
2.  Укажите имя ключа и при необходимости добавьте комментарий.
    
3.  Выберите срок действия: 30, 60 или 90 дней, один год либо бессрочно.
    
4.  Выберите проект, в который будет добавлен ключ.
    
5.  Нажмите «Создать».
    

![Создание ключа](https://content.timeweb.com/assets/f11ad7ee-c3af-4663-859b-74d2ea002377.png?width=2758&height=1962)

После создания ключ отобразится один раз. Скопируйте его и сохраните в надежном месте — повторно посмотреть ключ не получится.

### Управление API-ключами

Во вкладке «API-ключи» отображаются все созданные ключи, даты их создания, сроки действия и комментарии.

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

![Ключи](https://content.timeweb.com/assets/9be63129-4020-4eee-9c62-4445646cc30b.png?width=2180&height=1640)

Кликните на карточку ключа, чтобы перейти в его панель управления. В ней доступны две вкладки:

-   «Дашборд» — позволяет отслеживать количество входящих и исходящих токенов, их расход и количество запросов. Статистику можно отфильтровать по периоду и модели;
    
-   «Управление» — позволяет установить лимит на использование токенов.
    

![Дашборд](https://content.timeweb.com/assets/34de0159-6c21-44fb-9564-e05d39e4a7e8.png?width=2170&height=1618)

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

Для работы с AI Gateway рекомендуем использовать OpenAI SDK — с ним не нужно вручную отправлять HTTP-запросы и интеграция становится проще.

Доступные SDK:

-   [Python](https://github.com/openai/openai-python) 
    
-   [Node.js](https://github.com/openai/openai-node)
    
-   [Java](https://github.com/openai/openai-java)
    
-   [Go](https://github.com/openai/openai-go)
    

Полный список SDK доступен [в репозитории OpenAI](https://github.com/orgs/openai/repositories).

В примерах ниже мы используем Python и библиотеку `openai`. Установить ее можно с помощью `pip`:

```bash
pip install openai
```

### Отправка запроса

Для отправки сообщений используется метод `Chat Completions`. При его использовании сообщения передаются в массиве `messages`.

Каждое сообщение содержит:

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

```py
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.timeweb.ai/v1"
)

response = client.chat.completions.create(
    model="MODEL_NAME",
    messages=[
        {
            "role": "system",
            "content": "Отвечай кратко и по существу.",
        },
        {
            "role": "user",
            "content": "Объясни, что такое Kubernetes",
        },
    ],
)

print(response.choices[0].message.content)
```

Параметры:

-   `api_key` — API-ключ AI Gateway. Замените значение на ваш ключ.
    
-   `base_url` — базовый URL для подключения к AI Gateway.
    
-   `model` — имя используемой модели. Укажите модель, которую хотите использовать.
    
-   `messages` — массив сообщений с ролями и текстом.
    

### Отправка запроса с историей сообщений

Чтобы сохранить контекст диалога, передавайте предыдущие сообщения в массиве `messages`:

```py
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.timeweb.ai/v1"
)

response = client.chat.completions.create(
    model="MODEL_NAME",
    messages=[
        {
            "role": "system",
            "content": "Отвечай только короткими фразами.",
        },
        {
            "role": "user",
            "content": "Сколько будет 2 + 5?",
        },
        {
            "role": "assistant",
            "content": "7",
        },
        {
            "role": "user",
            "content": "Теперь умножь результат на 2",
        },
    ],
)

print(response.choices[0].message.content)
```

В примере передаются предыдущие сообщения (`assistant` и `user`), чтобы сохранить контекст диалога.

### Отправка запроса (Responses API)

`Responses API` — более новый способ работы с моделями. Он упрощает структуру запроса и не требует явного формирования массива `messages`.

```py
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.timeweb.ai/v1"
)

response = client.responses.create(
    model="MODEL_NAME",
    instructions="Отвечай кратко и по существу.",
    input="Объясни, что такое Kubernetes"
)

print(response.output_text)
```

Параметры:

-   `model` — имя используемой модели;
    
-   `instructions` — инструкция для модели (аналог системного промпта);
    
-   `input` — текст запроса.
    

### Отправка запроса с историей сообщений (Responses API)

Чтобы сохранить контекст диалога при использовании Responses API, укажите `previous_response_id` — идентификатор предыдущего ответа.

```py
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.timeweb.ai/v1"
)

response = client.responses.create(
    model="MODEL_NAME",
    instructions="Отвечай только короткими фразами.",
    input="Сколько будет 2 + 5?"
)

next_response = client.responses.create(
    model="MODEL_NAME",
    instructions="Отвечай только короткими фразами.",
    previous_response_id=response.id,
    input="Теперь умножь результат на 2"
)

print(next_response.output_text)
```

В этом примере первый запрос возвращает объект ответа, содержащий уникальный идентификатор `id`. Этот идентификатор передается в параметре `previous_response_id` при следующем запросе, что позволяет продолжить диалог без передачи всей истории сообщений.

Параметр `model` необходимо указывать в каждом запросе, включая последующие вызовы с `previous_response_id`.

### Получение списка моделей

AI Gateway позволяет получить список доступных моделей:

```py
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.timeweb.ai/v1"
)

models = client.models.list()

for model in models.data:
    print(model.id)
```

Метод `models.list()` возвращает список моделей, которые можно использовать в параметре `model`.

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

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

В AI Gateway для создания embeddings доступна модель `openai/text-embedding-3-large`.

```py
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.timeweb.ai/v1"
)

response = client.embeddings.create(
    model="openai/text-embedding-3-large",
    input="Текст для векторизации",
)

print(response.data[0].embedding)
```

Метод возвращает векторное представление переданного текста.