Документация

API-ключ

Ключ вида sk-aigate-… создаётся в кабинете (кнопка «Создать», можно задать название). Им вы и обращаетесь к API.

• Показывается один раз. Скопируйте ключ сразу — на сервере хранится только его хеш, повторно показать ключ нельзя.
• Можно завести несколько ключей (например, для разных приложений) и удалять их по отдельности.
• Удаление = мгновенный отзыв. Удалённый/скомпрометированный ключ сразу перестаёт работать на шлюзе — перевыпустите новый.

Первый запрос

Подставьте свой ключ и base_url в привычный клиент OpenAI — менять остальной код не нужно:

from openai import OpenAI

client = OpenAI(
    base_url="https://ai-gatewey.ru/v1",
    api_key="sk-aigate-ваш_ключ",
)

resp = client.chat.completions.create(
    model="deepseek/deepseek-v4-flash",
    messages=[{"role": "user", "content": "Привет!"}],
)
print(resp.choices[0].message.content)

Эндпоинты

• POST /v1/chat/completions — основной: ответы в чате.
• GET /v1/models — список моделей, доступных вашему ключу.
• POST /v1/messages — формат Anthropic Messages: для SDK anthropic и Claude Code.
• POST /v1/responses — OpenAI Responses API, включая встроенные инструменты.
• POST /v1/images/generations — генерация изображений; доступность зависит от модели в каталоге.
• Аудио на входе — модели с пометкой «аудио» в каталоге принимают звук тем же /v1/chat/completions, отдельный путь не нужен.
• Стриминг — параметр stream: true (ответ приходит частями, Server-Sent Events), как в OpenAI.

API совместим с официальными OpenAI SDK (Python, Node.js и др.) и с любым инструментом, умеющим работать с OpenAI-совместимым endpoint. Ключ, тарификация и лимиты общие для всех эндпоинтов — меняется только формат запроса.

Потоковый ответ

from openai import OpenAI

client = OpenAI(
    base_url="https://ai-gatewey.ru/v1",
    api_key="sk-aigate-ваш_ключ",
)

stream = client.chat.completions.create(
    model="deepseek/deepseek-v4-flash",
    messages=[{"role": "user", "content": "Расскажи про токены"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Формат Anthropic и Claude Code

В поле model — код из нашего каталога, а не имя модели Anthropic.

from anthropic import Anthropic

client = Anthropic(
    base_url="https://ai-gatewey.ru",
    api_key="sk-aigate-ваш_ключ",
)

msg = client.messages.create(
    model="anthropic/claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Привет!"}],
)
print(msg.content[0].text)

Модели

Модель выбирается параметром model (например deepseek/deepseek-v4-flash). Модели вашего тарифа оплачиваются из квоты; модели сверх тарифа доступны без апгрейда — оплачиваются по токенам с баланса. Если баланс исчерпан, сверх-тарифные модели ставятся на паузу (вернут 402), включённые в тариф работают.

Актуальный список с ценами и провайдерами — на странице «Модели»; программно доступные именно вашему ключу модели вернёт GET /v1/models.

Лимиты и квоты

• Месячная квота — включённый в тариф объём. Считаются токены запроса и ответа суммарно. Обновляется каждый платёжный период. Премиум-модели расходуют квоту быстрее: токен дорогой модели может списывать несколько единиц квоты (коэффициент зависит от модели) — на базовых моделях 1 токен = 1 единица.
• Запросов в минуту (RPM) и число параллельных запросов — ограничения скорости по тарифу (см. таблицу выше).
• Перерасход (overage) — на тарифах с этой опцией расход сверх квоты списывается с вашего баланса до жёсткого потолка (значение в колонке «Перерасход»). Дойдя до потолка, ключ останавливается, чтобы исключить неконтролируемые траты.
• Без overage (бюджетные тарифы) при исчерпании квоты включённые модели возвращают 429 до следующего периода; модели сверх тарифа продолжают работать за счёт баланса.
• Текущий расход и остаток квоты видны в кабинете в реальном времени.

Контроль расхода

В разделе «Расход» видны потреблённые токены и затраты по дням и по моделям. Сводка (тариф, токены за 30 дней, баланс) — на главной кабинета. Так можно заранее заметить приближение к квоте и при необходимости сменить тариф или пополнить баланс.

Вебхуки

Чтобы не опрашивать API в цикле, подпишитесь на события в разделе «Вебхуки». Мы отправим POST с телом JSON на ваш адрес. Событий шесть:

• payment.succeeded — платёж зачислен на баланс.
• balance.low — баланс опустился ниже вашего порога.
• key.quota_exceeded — ключ упёрся в потолок расхода.
• key.expired — истёк срок жизни ключа.
• subscription.renewed — подписка продлена на новый период.
• invoice.paid — счёт для юрлица оплачен.

Проверка подписи

Каждая доставка подписана: X-AIGateway-Signature — это HMAC-SHA256 в hex от строки {timestamp}.{тело}, где секрет выдаётся при создании вебхука, а timestamp дублируется в заголовке X-AIGateway-Timestamp. Имя события — в X-AIGateway-Event.

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

import hmac, hashlib, time

def valid(secret: str, body: bytes, signature: str, timestamp: str) -> bool:
    # Отклоняем старые доставки: подпись у повтора верная, но это не новое событие
    if abs(time.time() - int(timestamp)) > 300:
        return False
    expected = hmac.new(
        secret.encode(), f"{timestamp}.".encode() + body, hashlib.sha256
    ).hexdigest()
    # Сравнение постоянного времени: обычное == подсказывает подбор по задержке
    return hmac.compare_digest(expected, signature)

Повторы и требования к адресу

• Успехом считается любой ответ 2xx в течение 10 секунд. Ответы 408, 429 и 5xx — повторяем; остальные 4xx считаем окончательным отказом.
• До 6 попыток с растущей паузой: 1, 2, 4, 8, 16 и 32 минуты.
• После 20 неудач подряд вебхук отключается сам — включите его в кабинете, когда почините приёмник.
• Адрес — только https:// и только публичный: внутренние и служебные адреса отклоняются, редиректы не выполняются.

Команда

В разделе «Команда» владелец аккаунта приглашает участников и выдаёт каждому свой ключ с потолком расхода. Участник видит только свои ключи и свой расход, владелец — расход по каждому. Ключ участника не расширяет тариф: ограничения только сужают доступ.

Защита данных

Запросы проходят через встроенную защиту (guardrail). Секреты (API-ключи, токены, приватные ключи) и номера банковских карт маскируются до отправки модели — в апстрим уходит [REDACTED], исходные данные модель не получает. Персональные данные (email, телефон, СНИЛС/ИНН и т.п.) защита распознаёт, но не маскирует: текст запроса уходит модели как есть. Для аудита по 152-ФЗ сохраняется только факт находки — тип и количество («email: 2»), без самих значений.

Защиту можно отключить переключателем в кабинете (на свой риск — тогда секреты и номера карт тоже уйдут провайдеру как есть). Учтите: модели размещены за пределами России, поэтому содержимое любого запроса — это трансграничная передача. Наши серверы, журналы и платежи — в РФ; ваши запросы мы не сохраняем. Подробнее — в политике конфиденциальности.

Безопасность ключа

• Храните ключ как пароль: не публикуйте в репозиториях, чатах, скриншотах.
• В коде передавайте ключ через переменные окружения, а не строкой в исходниках.
• Для разных приложений заводите разные ключи — скомпрометированный можно отозвать, не задев остальные.
• При утечке немедленно удалите ключ в кабинете и создайте новый.

Ошибки

Формат и коды — как в OpenAI API:

• 401 — неверный или отсутствующий ключ. Проверьте заголовок Authorization: Bearer sk-aigate-….
• 402 — нужна оплата: исчерпана месячная квота, пуст баланс либо модель не входит в тариф. Тип ошибки — insufficient_quota, в тексте сказано, что делать. Пополните баланс или смените тариф.
• 429 — превышен лимит запросов в минуту. Снизьте темп.
• 400 — некорректный запрос (например, неизвестное имя модели или неверный формат тела).
• 5xx — временная проблема на стороне сервиса или провайдера модели; повторите запрос позже.

Вопросы и ответы