AI Gateway

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

В отличие от OpenAI-совместимого API и нативного API, AI Gateway не предоставляет возможности агентов, такие как:

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

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

Например:

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

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

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

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

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

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

Подключение

Для подключения к AI Gateway перейдите во вкладку «AI Gateway» в разделе «AI-агенты».

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

• «API-ключи»

• «Подключение»

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

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

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

Для создания ключа перейдите во вкладку «API-ключи» и нажмите кнопку «Добавить». Укажите имя ключа и сохраните его.

Скопируйте полученный ключ и сохраните его локально.

Удаление API-ключа

Чтобы удалить API-ключ, перейдите во вкладку «API-ключи», нажмите на три точки напротив нужного ключа и нажмите кнопку «Удалить». В открывшемся окне подтвердите удаление.

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

После создания API-ключа перейдите во вкладку «Подключение».

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

Ниже будет приведен пример кода для подключения и команда для установки библиотеки OpenAI.

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

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

Доступные SDK:

• Python 

• Node.js

• Java

• Go

Полный список 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)
  

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