AI Gateway — это API для работы напрямую с языковыми моделями без использования AI-агентов.
В отличие от OpenAI-совместимого API и нативного 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-ключи».
Выбор модели
Во вкладке «Модели» отображаются доступные модели и их параметры:
- тип;
- объем контекста;
- максимальная длина ответа;
- стоимость входящих и исходящих токенов.
Чтобы найти подходящую модель, отфильтруйте список по типу или провайдеру либо введите название модели в поле поиска.
Для сопоставления характеристик нажмите «Сравнить модели» и выберите нужные модели.
Получение параметров подключения
Во вкладке «Подключение» выберите модель и инструмент — язык программирования, для которого требуется пример.
В интерфейсе отобразятся:
- базовый URL для подключения;
- стоимость входящих и исходящих токенов выбранной модели;
- команда для установки библиотеки OpenAI;
- базовый пример подключения к API.
Создание API-ключа
AI Gateway использует отдельные ключи, не связанные с API-ключами аккаунта.
Каждый API-ключ тарифицируется отдельно и стоит 1 ₽ в месяц.
Чтобы создать API-ключ:
-
Перейдите во вкладку «API-ключи» и нажмите «Добавить».
-
Укажите имя ключа и при необходимости добавьте комментарий.
-
Выберите срок действия: 30, 60 или 90 дней, один год либо бессрочно.
-
Выберите проект, в который будет добавлен ключ.
-
Нажмите «Создать».
После создания ключ отобразится один раз. Скопируйте его и сохраните в надежном месте — повторно посмотреть ключ не получится.
Управление API-ключами
Во вкладке «API-ключи» отображаются все созданные ключи, даты их создания, сроки действия и комментарии.
Чтобы перегенерировать или удалить ключ, нажмите на три точки рядом с ним и выберите нужное действие.
Кликните на карточку ключа, чтобы перейти в его панель управления. В ней доступны две вкладки:
-
«Дашборд» — позволяет отслеживать количество входящих и исходящих токенов, их расход и количество запросов. Статистику можно отфильтровать по периоду и модели;
-
«Управление» — позволяет установить лимит на использование токенов.
Использование
Для работы с AI Gateway рекомендуем использовать OpenAI SDK — с ним не нужно вручную отправлять HTTP-запросы и интеграция становится проще.
Доступные SDK:
Полный список SDK доступен в репозитории OpenAI.
В примерах ниже мы используем Python и библиотеку openai. Установить ее можно с помощью pip:
pip install openai
Отправка запроса
Для отправки сообщений используется метод Chat Completions. При его использовании сообщения передаются в массиве messages.
Каждое сообщение содержит:
role— роль отправителя (user,assistant,system);content— текст сообщения.
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:
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.
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 — идентификатор предыдущего ответа.
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 позволяет получить список доступных моделей:
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.
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)
Метод возвращает векторное представление переданного текста.