Ключ, права и заголовки

Публичный API авторизуется одним заголовком и ничем больше. Анонимных ручек в нём нет: каждая операция спеки требует ключа, и почти каждая называет конкретное право в собственном описании. Исключение — каталог AI-моделей: ему подходит любой активный ключ. Страниц справочника на одну меньше, чем операций: PUT и PATCH /templates/{template} схлопнуты в одну (это одна операция под двумя методами), а POST /broadcasting/auth объясняется в разделе Realtime.

X-API-KEY: <ваш ключ>

Отдельный контур, а не второй способ входа

Публичный контур (/api/public/*) и API веб-кабинета — разные поверхности с разной аутентификацией. Bearer-токен кабинета здесь не работает; ключ, наоборот, не открывает ручки кабинета. Заголовок называется ровно X-API-KEY — ни Authorization, ни Api-Key не распознаются, и оба дают тот же ответ, что и полное отсутствие ключа.

Ключ хешируется (sha256) и резолвится с кэшем около часа. Практическое следствие: правка прав или деактивация ключа в кабинете применяется не мгновенно — запросы могут ещё какое-то время идти по старому состоянию.

Одиннадцать прав и wildcard

Право проверяется до бизнес-логики: ключ без нужного права получает 403 и ничего не выполняет. Колонка «операций» — сколько ручек публичного API открывает право (страницы справочника плюс POST /broadcasting/auth).

Две операции каталога AI-моделей (GET /ai/models и GET /ai/models/{key}) права не требуют вовсе — в таблице их нет.

Три пресета

При создании ключа права обычно набираются пресетом.

Wildcard * — отдельное значение, а не синоним пресета full: он проходит и те проверки, которых на момент выдачи ключа не существовало (но не права реселлера). Какой из двух способов «дать всё» применяет кабинет при выборе full, источники не уточняют — если это важно, сверьтесь со списком прав уже созданного ключа в кабинете.

Ловушка automation

Пресет с названием «для автоматизации» не содержит templates.write — только templates.read. Это не опечатка в документации и не баг: так он и устроен. По той же логике в нём нет и voices.write: ключу, который клонирует голоса, это право добавляют вручную либо берут full.

Последствие конкретное. Для TTS голос задаётся не полем заказа, а config.tts_settings.voice_id шаблона — значит канонический сценарий начинается с POST /templates. На ключе automation он останавливается на первом же шаге: 403, заказ так и не создан.

Если шаблон создан заранее (в вебе или другим ключом), automation достаточно: владелец шаблона — аккаунт, а не конкретный ключ. Чужой шаблон при этом не откроется никаким ключом.

Заголовки языка и таймзоны

Оба заголовка необязательны и ни один из них не объявлен параметром в OpenAPI — сгенерированный по спеке клиент про них не узнает, отправлять придётся руками.

• X-Locale — язык человекочитаемых строк: message в ответах и названия в справочниках вроде GET /voices/tags. На машинные поля (reason, статусы, коды) не влияет никак, и ветвиться по message нельзя именно поэтому. Расхождение источников: OpenAPI называет этот заголовок в 79 описаниях и ни разу не упоминает Accept-Language, а справочник для LLM — наоборот; если язык ответа критичен, проверьте фактическое поведение на своём ключе и присылайте оба заголовка.
• X-Timezone — имя зоны IANA (Europe/Moscow). Моменты времени в ответах приходят в ISO-8601 с явным оффсетом, по умолчанию UTC. Голый оффсет (+03:00) отвергается: он не знает про переход на летнее время. Фактически применённую зону сервер возвращает тем же заголовком — прислав мусор, вы увидите в ответе X-Timezone: UTC.

Что по ключу недоступно

Публичный контур не проводит платежей и не управляет собой. По ключу нельзя: пополнять баланс, делать переводы, покупать подписки, менять профиль и управлять самими API-ключами. Всё это остаётся в кабинете. Отдельно: у заказов нет update/delete — только cancel и retry, а PUT/PATCH/DELETE /orders/{order} ответят 405/404.

Смоук-тест ключа

Самая дешёвая проверка — профиль: одна операция, одно право, никаких побочных эффектов.

curl -s -o /dev/null -w '%{http_code}\n' \
  'https://api.lumean.app/api/public/user' \
  -H 'X-API-KEY: <ваш ключ>'

Ключевой нюанс — вторая строка: 403 подтверждает, что ключ жив. Если profile.read у вашего ключа нет по замыслу, проверяйте GET /orders?per_page=1 — ей нужен только orders.read.

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