Пространства и ключи

Ключ — это пропуск к API. Пространство — раздел кабинета со своими ключами, чатами и лимитом расхода: так расход по клиенту или направлению считается отдельно, а баланс остаётся общим. Пока пространство одно («Основное» есть в каждом кабинете), ключи лежат на странице Ключи, как раньше. О нескольких пространствах — в разделе Пространства.

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

1. Откройте Ключи → «Создать ключ».
2. Дайте понятное имя: по нему вы будете узнавать ключ в журнале и в статистике. Хорошо — «прод-бот», «сайт-виджет»; плохо — «ключ 2».
3. При желании задайте лимит расхода и режим «Только чтение».
4. Скопируйте значение — оно показывается один раз. В базе остаётся только хеш, восстановить нельзя.

Окно «Новый API-ключ»: название, лимит расхода и режим «Только чтение»

Потеряли ключ — создайте новый и отзовите старый; это нормальная практика, а не авария.

Ключ ложится в то пространство, из которого вы его создаёте. Как выбрать другое и как перенести готовый ключ — в разделе Ключи в пространстве.

Защита от всплеска расхода

Страховка от утёкшего ключа или зациклившегося агента: «не больше 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.

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

Привязка к адресу

Ключ, который отвечает только на запросы с ваших серверов. На странице ключа в поле «Адреса» перечислите 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 для остальных), остальные ключи продолжают работать.

Лимит полезен, когда ключ уезжает в чужие руки: подрядчику, в тестовый стенд, в публичное демо. Без лимита один цикл в чужом коде способен съесть весь баланс. Месячный лимит удобен для регулярных трат, лимит без сброса — для разового задания или демо.

Задать или изменить — на странице ключа, поле «Лимит расхода» и выбор «Сброс». Пусто = без лимита. Под лимитом видно, сколько потрачено в текущем периоде и когда сброс. Лимит на всё пространство — отдельный, о нём ниже.

Отключение и отзыв

На странице ключа есть два разных действия:

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

История запросов в обоих случаях остаётся в журнале: отзыв ключа не стирает прошлые траты.

Пространства

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

Своего баланса у пространства нет: деньги общие на весь кабинет, пространство делит учёт и ограничивает траты, а не кошелёк.

Страница «Пространства»: у каждого лимит с полосой, число ключей и последний успешный запрос

«Основное»

«Основное» есть в каждом кабинете всегда, создавать его не нужно: пока вы не завели другие пространства, в нём лежат все ключи и чаты. Переименовать, перекрасить и удалить его нельзя, а лимит расхода поставить можно. Расход приложений, подключённых через OAuth (Битрикс24, MCP-клиенты), тоже считается в «Основном», поэтому его лимит останавливает и их.

Как завести

1. Откройте Пространства и нажмите «Создать пространство». Из раздела пространства то же можно сделать в списке пространств в шапке.
2. Введите название (до 40 знаков) и выберите цвет метки. Адрес предлагается по названию: латиница, цифры и дефис, например marketing; по нему открывается раздел пространства. После создания адрес не меняется.
3. При желании сразу поставьте лимит на месяц, остальные лимиты — в настройках пространства.

Новое пространство сразу становится активным; со страницы «Пространства» открываются его ключи. В кабинете может быть до 30 пространств, не считая «Основного».

Меню и активное пространство

Нажмите на название в списке, и левое меню сменится меню пространства: «Использование», «Логи», «Ключи» и «Настройки», а вместо баланса в нём карточка с лимитом пространства. Стрелка вверху меню («← Личный») возвращает на список. В шапке рядом с названием кабинета появляется список пространств: в нём можно переключиться, открыть все пространства или создать новое.

Одно пространство в каждый момент активное: в нём работают чат, студии картинок и видео и инструменты, и туда ложится их расход. Активное одно на сайт и приложение Hubris и запоминается на сервере. Когда пространств два и больше, выбрать его можно в списке пространств в шапке, он есть и в чате, студиях и инструментах, а в чате ещё и внизу боковой панели; в приложении — внизу панели чатов. Под полем ввода видно, в каком пространстве идёт чат.

У каждого пространства свой список чатов. Ответ, который уже идёт, дописывается и считается в том пространстве, где вы его запустили. Галерея «Мои генерации» общая на весь кабинет.

Ключи в пространстве

Ключ лежит ровно в одном пространстве. Новый ключ попадает в то, из которого вы его создаёте: в разделе пространства — в него, на странице «Все ключи кабинета» — в выбранное в окне создания. Ключи, созданные через Management API, попадают в «Основное».

Перенести ключ можно на странице ключа: поле «Пространство» (оно есть, когда пространств два и больше). Настройки ключа — лимит, доступ, адреса — при переносе не меняются.

Когда пространств два и больше, «Ключи» уходят из меню кабинета внутрь пространств. Адрес /keys открывает ключи активного пространства, а старая ссылка на страницу ключа — пространство этого ключа.

Все ключи кабинета. Ссылка под списком на странице Пространства показывает ключи всех пространств сразу: у каждой карточки метка её пространства, а в окне создания можно выбрать пространство. Если в открытом пространстве ключей нет, а в других есть, страница ключей называет, где они лежат: ключи никуда не пропали.

Лимит расхода пространства

Лимит ставят на четыре окна, в любом сочетании: день, неделя, месяц и всё время. Откройте пространство → «Настройки» → «Лимит трат» и заполните нужные поля; пустое поле — без лимита. «Основному» лимит тоже можно поставить. Потолки те же, что у лимита ключа: они описаны на странице «Лимиты частоты».

Рамка «Лимит трат» в настройках пространства: четыре окна и сколько потрачено в каждом

Лимит считает всё, что потрачено в пространстве: запросы всех его ключей, чат, студии и инструменты, вместе с суммами, удержанными под ролики в работе. Окна календарные, по Москве: день сбрасывается в 00:00, неделя — в понедельник, месяц — 1-го числа; «за всё время» не сбрасывается. Рядом с полем видно, сколько потрачено и когда сброс; при 80 % лимита к этому добавляется «почти исчерпан», при 100 % — «исчерпан». Те же отметки стоят в списке пространств и в карточке меню пространства.

Когда лимит исчерпан, останавливается всё, что тратит деньги в этом пространстве; остальные пространства работают:

• API. Запрос к модели получает 429 с кодом workspace_limit_exceeded. В Retry-After — секунды до сброса, у лимита «за всё время» его нет. Чтение (GET /v1/models, GET /v1/usage, GET /v1/key) работает. Подробнее — на страницах «Лимиты частоты» и «Ошибки».
• Чат, студии, инструменты. Вместо ответа — сообщение «Лимит пространства «Маркетинг» на ноябрь исчерпан» с суммой и датой сброса, кнопкой «Изменить лимит» и, если есть другое пространство, «Сменить пространство».
• Письмо. Один раз за окно владельцу кабинета приходит письмо со ссылкой на настройки пространства.

Поднятый лимит действует сразу. Лимит проверяется перед запросом, поэтому итог может превысить его на стоимость последних запросов, в том числе одновременных; ролик запускается, только если удержание под него помещается в остаток.

Расход и журнал

• На странице Использование при двух пространствах и больше есть карточка «Распределение расхода · по пространствам»; траты удалённых пространств собраны в строке «Удалённые пространства». В меню пространства «Использование» показывает расход только этого пространства.
• В журнале запросов появляется фильтр «Пространство»; в меню пространства «Логи» показывают только его запросы. Запрос по API, остановленный лимитом пространства, виден в журнале: в колонке «Модель» вместо названия стоит «Лимит пространства». Такой запрос не выполнен и не оплачен. Отказы в чате, студиях и инструментах в журнал не попадают.

Удаление пространства

Удалить можно любое пространство, кроме «Основного»: откройте пространство → «Настройки» → «Удалить пространство» и введите его название. Удаляется только раздел: ключи и чаты переходят в «Основное», ключи продолжают работать, менять интеграции не нужно. Дальше их расход считается в «Основном»: если его лимит исчерпан, запросы этих ключей получат 429. Траты остаются в отчётах кабинета строкой «Удалённые пространства». Отменить удаление нельзя.

Что стало с проектами

Раньше ключи группировались в проекты. Теперь это пространства: каждый проект стал пространством с тем же названием, цветом и ключами, а остальные ключи лежат в «Основном». Настройки ключей не менялись, прежние чаты оказались в «Основном». Закладки на журнал запросов с фильтром по проекту открываются как прежде и показывают то же пространство.

Что дальше

• Аутентификация — как передавать ключ в запросах
• Кабинеты клиентов — если ключи заводит подрядчик
• Лимиты частоты — ограничения на стороне API
• Использование и Логи — расход и журнал запросов

Обновлено: 12 ноября 2026 г.