союз.ai

Ключи и авторизация

Ключ — заголовок Authorization: Bearer <ключ>. Нет ключа или он неверный — 401 invalid_api_key.

Два вида ключей

КлючНачинается сЧто делает
API-ключsk_запускает модели: чат, генерации, задачи, файлы
Ключ управленияmk_ведёт аккаунт: баланс, история, расходы, выдача API-ключей, настройки — Ключ управления

Ключ не того вида — 403 forbidden с detail[].reason requires_api_key или requires_management_key. Исключение — GET /v1/usage/{id}: API-ключ читает в нём запросы, отправленные этим ключом, без предела частоты; запрос другого ключа — 404.

API-ключ создаёт любой участник аккаунта, кроме наблюдателя (кабинет, «API-ключи»), — себе: траты ключа идут в его лимит, все ключи тратят общий баланс аккаунта. Секрет повторно открывает только тот, кто создал ключ: в кабинете или GET /v1/keys/{id}/secret своим ключом управления; остальным — 403 с detail[].reason: "not_key_author". В списке ключей вместо секрета — подсказка secret_hint: приставка, первые 4 и последние 4 знака (sk_9f3a…c1d2).

Ключ — только на сервере

  • Храните ключ на своём сервере в переменной окружения (SOUZ_API_KEY), не в коде браузера или мобильного приложения, не в логах и не в репозитории. В репозиторий — .env.example с пустым значением: SOUZ_API_KEY=.
  • Браузер к api.souz.ai напрямую не обращается: CORS у API нет, запрос из страницы браузер заблокирует. Фронтенд вызывает ваш сервер, сервер — Souz API.
  • Ключ утёк — отзовите его в кабинете («API-ключи») и выпустите новый.

Что можно без ключа

Каталог (GET /v1/models, GET /v1/models/{id}, /stats, /channels, GET /v1/channels), превью роутинга (POST /v1/models/{id}/routing/preview), состояние сервиса (GET /v1/status, Плановые работы) и документы: /, /openapi.yaml, /openapi.json, /llms.txt, /llms-full.txt.

Сам ключ — GET /v1/key

Настройки ключа запроса (схема APIKey): потолок трат (spend_limit), его период (spend_limit_reset), расход (spent), пресет и потолок цены по умолчанию, каналы по моделям (routing_options), сроки хранения (retention) и режим без хранения (no_store).

Терминал
curl https://api.souz.ai/v1/key -H "Authorization: Bearer $SOUZ_API_KEY"

Потолок трат ключа

Потолок ключа — на всё время, в день или в месяц; у участника — общий лимит на все его ключи. Исчерпан — 402 key_spend_limit_exceeded или 402 member_spend_limit_exceeded, без списания (Лимиты). Ключ субагенту с дневным потолком создаёт и отзывает ключ управления.