Способы подключения

К AI Gateway можно подтверждённо подключиться напрямую по HTTP или через официальный OpenAI SDK для Python и JavaScript/TypeScript. Сторонний фреймворк тоже может подойти, если позволяет заменить базовый адрес, передать Bearer-ключ и обратиться к опубликованному пути, но такую совместимость нужно проверять коротким запросом.

Начните с самого простого способа, который решает задачу. Не добавляйте фреймворк ради одного вызова модели: дополнительный слой усложняет разбор тела запроса, потока и ошибок.

Подтверждённые способы подключения

Для всех способов сначала войдите или зарегистрируйтесь, создайте ключ и откройте раздел Модели. Скопируйте оттуда точный идентификатор модели и убедитесь, что у неё опубликован нужный путь. В примерах ниже вместо настоящего идентификатора оставлен заполнитель <MODEL_ID_FROM_CATALOG>.

Ключ храните в переменной окружения, а не в коде:

export AI_GATEWAY_API_KEY="<ВАШ_API-КЛЮЧ>"

Подробные правила выпуска и хранения ключа есть в руководстве по авторизации API. Первый запуск по шагам разобран в быстром старте, а форматы путей и ответов — в справочнике API.

Прямой HTTP-запрос

Прямой HTTP подходит для проверки, небольшого скрипта и интеграции, где нужен полный контроль над адресом, заголовками, телом и обработкой ответа. Минимальный запрос к Chat Completions:

curl https://route.smartaipack.ru/v1/chat/completions \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<MODEL_ID_FROM_CATALOG>",
    "messages": [
      {"role": "user", "content": "Ответь одним словом: работает?"}
    ]
  }'

Успех означает, что сервер вернул статус 200, а в choices[0].message.content есть ответ. После проверки найдите событие в разделе Использование и сверьте расход в Аналитике.

Официальный OpenAI SDK

Для обычных Chat Completions и совместимых методов можно использовать официальный пакет openai. AI Gateway не выпускает отдельный SDK: клиенту нужно передать базовый адрес https://route.smartaipack.ru/v1, ключ и точный идентификатор модели.

Python:

import os

from openai import OpenAI

client = OpenAI(
    base_url="https://route.smartaipack.ru/v1",
    api_key=os.environ["AI_GATEWAY_API_KEY"],
)

result = client.chat.completions.create(
    model="<MODEL_ID_FROM_CATALOG>",
    messages=[{"role": "user", "content": "Ответь одним словом: работает?"}],
)

print(result.choices[0].message.content)

JavaScript и TypeScript для серверной среды:

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://route.smartaipack.ru/v1",
  apiKey: process.env.AI_GATEWAY_API_KEY
});

const result = await client.chat.completions.create({
  model: "<MODEL_ID_FROM_CATALOG>",
  messages: [{ role: "user", content: "Ответь одним словом: работает?" }]
});

console.log(result.choices[0].message.content);

Не передавайте ключ в браузерный JavaScript. Подробная настройка клиента собрана в руководстве по OpenAI SDK, а чтение ответа частями — в статье о потоковой передаче.

Опубликованные пути

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

Для поиска по документам используйте отдельное руководство по векторизации и пересортировке. Если приложение вызывает собственные функции, сначала изучите руководство по вызову инструментов: формат нужно проверять на выбранной модели и пути.

Практическая матрица выбора

Стоимость до запуска сверяйте на странице Тарифы. Если прямой запрос работает, а библиотека — нет, проблема, вероятнее всего, находится в настройках или преобразованиях библиотеки.

Другие интеграции: как проверить совместимость

AI Gateway не заявляет собственные плагины или адаптеры для LangChain, LlamaIndex, Mastra, PydanticAI, Vercel AI SDK, TanStack AI, Aider, Cline и других фреймворков или ИИ-помощников. Их наличие в чужом каталоге не означает, что они протестированы со AI Gateway.

Сторонний клиент потенциально совместим, если одновременно выполняются условия:

• можно задать базовый адрес https://route.smartaipack.ru/v1 без повторного /v1;
• можно передать ключ в заголовке Authorization: Bearer <API_KEY>;
• клиент отправляет один из опубликованных путей;
• он не требует обязательных заголовков или служебных путей другого сервиса;
• можно увидеть фактический HTTP-путь, тело запроса и ответ при диагностике.

Это предварительный фильтр, а не гарантия. Перед рабочей нагрузкой проведите минимальную проверку.

Порядок проверки

1. Сначала выполните контрольный curl к /v1/chat/completions. Если он не работает, не переходите к фреймворку.
2. Настройте во фреймворке тот же базовый адрес, ключ и идентификатор модели.
3. Отправьте один короткий запрос без потока и инструментов.
4. Проверьте фактический путь и тело: библиотека не должна добавлять лишний /v1, менять model или обращаться к непубликованному служебному пути.
5. Сравните статус и тело ошибки с прямым запросом. Правила повторов и диагностики собраны в статье об ошибках API.
6. Отдельно испытайте поток, вызов инструментов и разбор usage, только если они нужны приложению. Совместимость простого текста не доказывает совместимость этих форматов.
7. Убедитесь, что запрос появился в журнале использования, а расход — в аналитике.

Если фреймворк требует OAuth, собственный плагин, специальные заголовки поставщика, непубличные маршруты или возможности, которых нет в каталоге, считать его совместимым нельзя. AI Gateway также не обещает через такой клиент автоматическую подмену поставщика, веб-поиск, фоновые задания, MCP или структурированный вывод.

Для обращения в поддержку подготовьте время запроса, точный путь, идентификатор модели, HTTP-статус и безопасный фрагмент ошибки. Полный API-ключ и содержимое секретных запросов отправлять не нужно.