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

Тарифы и оплата

Тариф — это фиксированная подписка с месячной квотой токенови лимитами скорости. Квота обновляется каждый месяц — и при оплате на несколько месяцев вперёд; дата ближайшего обновления видна в кабинете. За неполный месяц (остаток прежнего тарифа при смене, подарочный период) квота выдаётся пропорционально его длительности. Управление — раздел «Подписка и оплата».

• Оплата — банковской картой через ЮKassa. Тариф/баланс активируются автоматически после подтверждения платежа (обычно в течение минуты).
• Автопродление. Подписка продлевается автоматически в конце периода; его можно отключить в кабинете — тогда по окончании периода подписка завершится, а доступ сохранится по балансу (оплата по факту).
• Баланс оплачивает модели сверх тарифа и работу без подписки (PAYG), а на тарифах с overage — ещё и перерасход сверх квоты; см. «Лимиты и квоты». Пополняется отдельно в том же разделе.
• Смена тарифа доступна в любой момент; при переходе между подписками неиспользованный остаток текущей засчитывается: текущий месяц — по оставшемуся времени, но не больше доли неизрасходованной квоты, оплаченные вперёд месяцы — целиком; остаток сверх цены нового тарифа продлевает его, но не больше чем на 12 месяцев. Подарочные дни не засчитываются. При переходе на оплату по факту остаток не возвращается.
• История платежей и списаний — в таблице транзакций в кабинете.
• Промокод вводится при пополнении: бонус начисляется на баланс после того, как платёж прошёл, а сумма самого платежа не меняется — поэтому чек и закрывающие документы остаются на фактически уплаченную сумму.
• Приглашайте коллег. За первый платёж каждого приглашённого на ваш баланс начисляется процент от суммы (в пределах потолка) — через 14 дней после платежа. Если платёж возвращён, вознаграждение за него отменяется, в том числе после начисления. Ссылка и накопленное вознаграждение — в разделе «Подписка и оплата».
• Юрлицам и ИП доступна оплата по счёту: укажите ИНН, реквизиты подтянутся из реестра. Счёт, акт и закрывающие документы выставляются и печатаются из кабинета.

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. Встроенные инструменты (веб-поиск, computer use) через шлюз не поддерживаются.
• POST /v1/images/generations — генерация изображений; доступность зависит от модели в каталоге.
• Аудио на входе — модели с пометкой «аудио» в каталоге принимают звук тем же /v1/chat/completions, отдельный путь не нужен.
• Стриминг — параметр stream: true (ответ приходит частями, Server-Sent Events), как в OpenAI.

Параметры маршрутизации провайдеров и n > 1 не поддерживаются — ответ 400; встроенные инструменты провайдера (веб-поиск, исполнение кода и т. п.) через шлюз недоступны — запрос выполняется без них. Быстрый режим (speed, service_tier: priority) через шлюз не действует — запрос выполняется в обычном.

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.5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Привет!"}],
)
print(msg.content[0].text)

Модели

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

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

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

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

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

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

Вебхуки

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

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

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

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

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 минут.
• После 20 неудач подряд вебхук отключается сам, и мы присылаем об этом письмо владельцу аккаунта — включите вебхук в кабинете, когда почините приёмник.
• Адрес — только https:// и только публичный: внутренние и служебные адреса отклоняются, редиректы не выполняются.

Команда

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

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

Запросы проходят через встроенную защиту (guardrail). Секреты (API-ключи, токены, приватные ключи) и номера банковских карт, а также контакты (email и телефон) маскируются до отправки модели — в апстрим уходит [REDACTED], исходные данные модель не получает. Это значит, что модель не увидит и нужного ей адреса: в задаче «напиши письмо на ivan@…» в ответе будет [REDACTED]. Остальные персональные данные (IBAN, IP, СНИЛС, ИНН, паспорт, ОМС) защита распознаёт, но не маскирует: текст запроса уходит модели как есть. Для аудита по 152-ФЗ сохраняется только факт находки — тип и количество («email: 2»), без самих значений.

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

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

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

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

Ошибки

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

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

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