Ключи и аутентификация

Публичный только GET /v1/models — все генерирующие эндпоинты требуют ключ в заголовке:

Authorization: Bearer mxn-...

Выпуск ключа

Кабинет → Профиль → API-ключи → «Создать ключ».

Полный ключ показывается один раз, сразу после создания. Мы храним только sha256-хэш, префикс и последние символы — восстановить ключ невозможно, потерянный проще удалить и выпустить новый.

Области доступа

При создании ключа можно ограничить его набором возможностей. Доступны семь:

Область	Что открывает
`chat`	`POST /chat/completions`
`search`	Модели с веб-поиском внутри `/chat/completions`
`images`	`POST /images/generations`, `POST /images/edits`
`video`	Все эндпоинты `/videos`
`music`	Все эндпоинты `/audio/music`
`audio`	`POST /audio/speech`, `POST /audio/transcriptions`
`embeddings`	`POST /embeddings`

Ключ без ограничений (все области отмечены) получает доступ ко всему каталогу. Запрос вне разрешённых областей возвращает 403. GET /balance не входит в список: баланс читает любой рабочий ключ — иначе узкий ключ не сможет узнать, на что хватит денег.

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

Список моделей и дневной лимит

Две настройки ключа точнее областей — задаются при создании и меняются в кабинете в любой момент:

Настройка Что делает

Разрешённые модели Список id из каталога (GET /models). Запрос с другой моделью — 403 с кодом model_not_allowed. Пусто — любая модель в пределах областей

Дневной лимит, ₽ Потолок списаний по этому ключу за календарные сутки (UTC). Когда сумма успешных списаний с полуночи достигла лимита — 429 с кодом daily_limit_exceeded и заголовком X-Mixen-Daily-Reset (время сброса). Баланс аккаунта и другие ключи не затрагиваются

Настройка	Что делает
Разрешённые модели	Список `id` из каталога (`GET /models`). Запрос с другой моделью — `403` с кодом `model_not_allowed`. Пусто — любая модель в пределах областей
Дневной лимит, ₽	Потолок списаний по этому ключу за календарные сутки (UTC). Когда сумма успешных списаний с полуночи достигла лимита — `429` с кодом `daily_limit_exceeded` и заголовком `X-Mixen-Daily-Reset` (время сброса). Баланс аккаунта и другие ключи не затрагиваются

Пока лимит не исчерпан, каждый ответ несёт заголовки X-Mixen-Daily-Limit, X-Mixen-Daily-Spent, X-Mixen-Daily-Reset — по ним удобно следить за бюджетом без отдельных запросов. Лимит проверяется до запроса, а цена известна по факту, поэтому последний запрос суток может немного его превысить.

Типовой набор для интеграции, которую нельзя оставить без присмотра: одна область, одна–две модели, лимит на день — утёкший ключ в худшем случае потратит дневной бюджет, а не баланс.

Хранение

Ключ — это доступ к вашему балансу. Правила те же, что для любого платёжного секрета:

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

Проверка ключа

Самая дешёвая проверка — баланс: она не тратит токены и не зависит от скоупов ключа.

curl https://api.mixen.ai/v1/balance \
  -H "Authorization: Bearer $MIXEN_API_KEY"

{"balance_rub": "123.46", "currency": "RUB"}

balance_rub — строка с двумя знаками: парсите как decimal, не как float, чтобы не терять копейки. Баланс один для бота, кабинета и API.

Генерирующий запрос для полноты картины:

curl https://api.mixen.ai/v1/chat/completions \
  -H "Authorization: Bearer $MIXEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.6-luna","messages":[{"role":"user","content":"ping"}],"max_tokens":5}'

Ответ 401 означает, что ключ не найден или отозван. 402 — ключ рабочий, но на балансе не хватает денег.