Ключи и проекты
Создание API-ключей, дневной лимит, отключение и отзыв, группировка ключей по проектам и расход по каждому.
Ключ — это пропуск к API. Проект — папка для ключей, чтобы считать расход по клиенту или направлению отдельно. Всё живёт на странице Ключи.
Создание ключа
- Откройте Ключи → «Создать ключ».
- Дайте понятное имя: по нему вы будете узнавать ключ в журнале и в статистике. Хорошо — «прод-бот», «сайт-виджет»; плохо — «ключ 2».
- При желании задайте дневной лимит и проект.
- Скопируйте значение — оно показывается один раз. В базе остаётся только хеш, восстановить нельзя.
Потеряли ключ — создайте новый и отзовите старый; это нормальная практика, а не авария.
Защита от всплеска расхода
Страховка от утёкшего ключа или зациклившегося агента: «не больше X ₽ за Y минут». Порог — любая сумма, окно — 1, 5, 15, 30 минут или 1 час. Если ключ потратит больше, он замораживается в ту же секунду: любой запрос получает 401 key_frozen_spike, остальные ключи работают. Сразу уходит письмо (что за ключ, сколько потрачено, порог, баланс), в кабинете появляется баннер, а на карточке ключа — бейдж «заморожен» и запись в логах.
Обратно — тумблером «Ключ включён» на странице ключа. Или автоматически: выберите период охлаждения (15 минут, 1, 6 или 24 часа) — ключ включится сам, окно расхода обнулится, а письмо и баннер скажут, когда именно.
Защита выключена по умолчанию: включается на странице ключа в блоке «Защита от всплеска», по API — полями spike_limit_kopecks, spike_window_minutes, spike_cooldown_minutes в Management API. Отличие от лимита расхода: лимит отпускает сам по календарю, заморозка — сигнал «что-то не так», и по умолчанию ждёт вас.
Ключ только для чтения
Ключ, который видит каталог моделей, баланс и статистику, но не может тратить: любой запрос к моделям — чат, эмбеддинги, картинки, видео, аудио — получает 403 key_read_only. Отдайте такой ключ дашборду, мониторингу или подрядчику «посмотреть» — если он утечёт, баланс не пострадает.
Включается чекбоксом при создании ключа или переключателем «Доступ» на странице ключа; обратимо, действует со следующего запроса. По API — поле read_only в Management API.
Привязка к адресу
Ключ, который отвечает только на запросы с ваших серверов. На странице ключа в поле «Адреса» перечислите IPv4/IPv6-адреса или подсети (CIDR) — до 32 записей, например 203.0.113.5 или 198.51.100.0/24. Запрос с любого другого адреса получает 403 key_ip_not_allowed до обращения к модели — баланс не тронут, а в тексте ошибки написано, с какого адреса он пришёл: если это ваш новый сервер, просто добавьте адрес в список. Каждая такая попытка видна в логах ключа строкой (ip_denied), и не чаще раза в час приходит письмо — если адрес вам незнаком, ключ мог утечь: отзовите его и создайте новый.
Привязывайте серверы, а не ноутбуки: у домашнего и мобильного интернета адрес меняется, и ключ перестанет работать посреди дня. Подсказка «ваш адрес сейчас» в поле показывает, откуда открыт кабинет. Пустой список — с любого адреса, как раньше; маска /0 («весь интернет») не принимается — чтобы снять привязку, очистите список. Привязка действует только на API-ключи sk-gw-…: вход в кабинет и OAuth-подключения она не ограничивает. По API — поле allowed_ips в Management API.
Лимит расхода
Лимит ограничивает траты по ключу за период: каждый день (сброс в 00:00 по Москве), каждую неделю (с понедельника), каждый месяц (с 1-го числа) или без сброса — на весь расход ключа. Превышение — ошибка 429 (daily_limit_exceeded для суточного лимита, key_limit_exceeded для остальных), остальные ключи продолжают работать.
Лимит полезен, когда ключ уезжает в чужие руки: подрядчику, в тестовый стенд, в публичное демо. Без лимита один цикл в чужом коде способен съесть весь баланс. Месячный лимит удобен для бюджета проекта, лимит без сброса — для разового задания или демо.
Задать или изменить — на странице ключа, поле «Лимит расхода» и выбор «Сброс». Пусто = без лимита. Под лимитом видно, сколько потрачено в текущем периоде и когда сброс.
Отключение и отзыв
На странице ключа есть два разных действия:
| Действие | Что происходит | Обратимо |
|---|---|---|
| Отключить | Ключ отвечает 401, статистика и значение сохраняются | Да, включается обратно |
| Отозвать | Ключ перестаёт работать навсегда | Нет |
Отключение удобно, когда нужно быстро остановить подозрительный трафик и разобраться. Отзыв — когда ключ точно скомпрометирован или больше не нужен.
История запросов в обоих случаях остаётся в журнале: отзыв ключа не стирает прошлые траты.
Проекты
Проект группирует ключи внутри вашего кабинета. Это удобно, если вы ведёте нескольких клиентов или несколько направлений и хотите видеть, сколько потратил каждый.
Своего баланса у проекта нет: деньги общие, проект делит учёт, а не кошелёк.
Как завести
- На странице Ключи нажмите «+ Проект».
- Задайте название и цвет метки.
- Разложите ключи: на странице ключа поле «Проект», либо выберите проект сразу при создании.
Над списком ключей появится полоса вкладок: «Все ключи», затем ваши проекты и «Без проекта». Выбранная вкладка фильтрует список, а в подзаголовке показывает сводку — сколько ключей и сколько потрачено за 30 дней.
Расход по проекту
- На странице Использование — карточка «Распределение расхода по проектам».
- В журнале запросов — фильтр «Проект» рядом с фильтром «API-ключ».
Ключ можно переложить в другой проект в любой момент — история его расходов переезжает вместе с ним. Это сделано специально: первая раскладка ключей по клиентам почти всегда получается неточной, и её нужно уметь исправить задним числом.
Удаление проекта
Удаляется только группировка: ключи возвращаются в «Без проекта» и продолжают работать. Ни одна интеграция от удаления проекта не сломается.
Что дальше
- Аутентификация — как передавать ключ в запросах
- Кабинеты клиентов — если ключи заводит подрядчик
- Лимиты частоты — ограничения на стороне API
Обновлено: