# Lumean Public API — справочник для LLM > Этот файл — самодостаточная спецификация публичного API Lumean для языковых моделей. > Отдайте его нейросети целиком: в нём есть авторизация, соглашения, все эндпоинты с точными > полями, enum'ы, схемы ответов, real-time (WebSocket) и сквозные рабочие примеры. > Все идентификаторы, имена полей, enum-значения и JSON приведены **дословно** — используйте их > буква-в-букву. Пояснения на русском, технические имена — в оригинале. Машиночитаемые спецификации (истина о схемах, дополняют этот файл): `GET /docs/public-openapi.json` (OpenAPI 3.1, REST) и `GET /docs/public-asyncapi.json` (AsyncAPI 2.6, WebSocket). Английский вариант REST-спеки — `GET /docs/public-openapi.en.json` (то же дерево, переведённые описания). --- ## 0. Что это за API Lumean — SaaS для генерации медиа ИИ: **озвучка текста (TTS)** на трёх сервисах (`elevenlabs`, `heygen`, `cartesia`), **генерация и редактирование изображений**, **звуковые эффекты (SFX)**, **музыка**, **клонирование голоса** (по API — для Cartesia и Fish Audio, §7.12). Работа строится вокруг **заказов** (`order`): вы отправляете задачу, сервер разбивает её на чанки, обрабатывает асинхронно воркерами и отдаёт файлы-результаты. Публичный API (`/api/public/*`) предназначен для программных интеграций **по API-ключу** (заголовок `X-API-KEY`). Это отдельный контур от фронтового JWT-API. Ключ создаётся пользователем в личном кабинете (веб), у него набор **прав** (permissions) и **лимиты**. Здесь описан ТОЛЬКО публичный контур по ключу. **Ключевые факты, которые часто понимают неверно (прочитайте до генерации запросов):** 1. **TTS-голос задаётся только через шаблон**, а не полем заказа. Нет `orders.voice_id`. Порядок: положить `voice_id` в `config.tts_settings.voice_id` шаблона → создать заказ по этому шаблону. См. §11 (Рецепты). 2. **Текст для TTS передаётся в top-level поле `input_text`** запроса `POST /orders` (сырая строка). НЕ кладите текст TTS в `task_data`. А вот для template-less SFX/music промпт идёт в `task_data`. 3. **У заказов НЕТ update/delete.** Доступны только `index`, `store`, `show`, плюс действия `cancel`/`retry`. `PUT/PATCH/DELETE /orders/{order}` вернут 405/404. 4. **Два независимых лимита:** rate-limit по числу запросов (429, без `Retry-After`) и токен-квота по объёму генерации (429, `reason: token_quota_exceeded`, **с** `Retry-After`). См. §6. 5. **Пагинация с разными базами:** внешние каталоги голосов (`voices/elevenlabs/library`, `voices/heygen`) считают `page` **с 0**; обычные списки (`orders`, `templates`, `templates/browse`, а также каталог и клоны Cartesia `voices/cartesia`, `voices/cartesia/clones`, а также Fish Audio `voices/fishaudio`, `voices/fishaudio/clones`) — `current_page` **с 1**. 6. **Субтитры и другие сервисные файлы лежат ОТДЕЛЬНО** — в `result.service_files[]`, не в `result.files[]`. Оба поля — плоские массивы строк-путей (напр. `.../output/final/service/subtitles.srt`), генерируется только для TTS. Скачивается тем же `POST /storage/url`. См. §7.10. 7. **Сбой чанка чинится на уровне чанка, не заказа.** У чанка бывают статусы `failed` (тех. ошибка) и `policy_flagged` (контент отклонён политикой провайдера). Частично готовый заказ (`partially_completed`) доводят до `completed` так: один вызов `POST /orders/{order}/items/retry-failed` забирает все `failed` разом, а `policy_flagged` добивают поштучно `POST /orders/{order}/items/{item}/retry` с **исправленным** `text` (повтор с тем же текстом бессмыслен). Order-level `retry` для этого не годится — он создаёт новый заказ. См. §7.11. 8. **Любые квадратные скобки в тексте озвучки вырезаются** — это разметка для диктора, а не список ключевых слов. `[1]`, `[sic]`, `[00:12]` не прозвучат (и не будут оплачены). А вот `(ремарка)`, `<тег>`, `*звёздочки*` — прозвучат и тарифицируются. См. §8.3. 9. **Тонкие настройки голоса включаются флагом.** Без `tts_settings.advanced_voice_settings: true` (по умолчанию `false`) на `eleven_v3*` до движка доезжает только `stability`, на `eleven_v4*` — `stability` и `similarity_boost`; остальные значения (в том числе `speed`) молча не влияют на звук — ошибки не будет. На прочих моделях флаг на звук не влияет. См. §8.2. 10. **Свой голос для Cartesia клонируется по API, но асинхронно.** `POST /voices/cartesia/clones` (право `voices.write`) сразу отвечает `201` с клоном в статусе `pending`, а `voice_id` появляется только в статусе `ready` — ждите событие `voice_clone.updated` (§10) или опрашивайте `GET /voices/cartesia/clones`. В шаблон кладут `voice_id` клона, а НЕ его `id`. Клонирование требует живой подписки с Cartesia, только если сервис закрыт для оплаты с баланса (иначе 402 `no_subscription`), и упирается в потолок клонов: 2 без подписки, лимит тарифа с подпиской. См. §7.12, Рецепт H. То же у Fish Audio (`POST /voices/fishaudio/clones`, §7.12): правила те же, что у Cartesia, лимит клонов у Fish свой, `voice_id` — строка из 32 hex-символов, а не UUID. 11. **Не подбирайте адреса — все эндпоинты описаны в этом файле.** Путь, которого нет, отвечает **404** с `reason: "endpoint_not_found"`, текстом-подсказкой и ссылками на этот файл. Перебор несуществующих путей распознаётся как http probing: после нескольких таких 404 IP банится на ВСЕХ путях — **429** `reason: "ip_banned"` (5 мин → 10 → 30 → 1 ч → 24 ч). Получили `endpoint_not_found` — остановитесь и найдите нужный запрос здесь. См. §6.1, §12. 12. **Есть отдельный AI API (LLM-гейтвей), не входящий в `/api/public/*`.** OpenAI- и Anthropic-совместимые ручки на `https://api.lumean.app/v1` (`/chat/completions`, `/responses`, `/messages`, `/models`, `/images/*`) работают с ЛЮБЫМ ключом кабинета (`Authorization: Bearer` или `x-api-key`), оплата с баланса LUMC. Полностью — §14. 13. **Цены AI-моделей не фиксированы.** Они меняются вслед за поставщиками (иногда несколько раз в день), модель может временно пропасть. Перед дорогой генерацией сверяйте цену — `GET /api/public/ai/models/{key}` (любой ключ, ETag → 304, пока цена прежняя) — и держите месячный лимит ключа. См. §14.6. --- ## 1. TL;DR — путь от нуля до готового TTS-заказа Предполагается, что у вас уже есть API-ключ с правами `orders.write`, `templates.write`, `voices.read`, `orders.download`, `billing.read`. **Внимание:** готовый пресет `automation` НЕ включает `templates.write` (только `templates.read`) — для этого сценария (создание шаблона) берите пресет `full` либо добавьте `templates.write` к `automation` вручную при создании ключа. ```bash BASE=https://api.lumean.app/api/public KEY=<ваш_api_ключ> # 1. Найти voice_id (например, из публичной библиотеки ElevenLabs) curl -s "$BASE/voices/elevenlabs/library?page=0&page_size=20" -H "X-API-KEY: $KEY" # 2. Создать шаблон TTS с этим voice_id curl -s -X POST "$BASE/templates" -H "X-API-KEY: $KEY" -H "Content-Type: application/json" -d '{ "service_key": "elevenlabs", "name": "My TTS", "config": { "tts_settings": { "mode": "mode_v1", "model_id": "eleven_multilingual_v2", "voice_id": "", "advanced_voice_settings": true, "voice_settings": { "stability": 0.5, "similarity_boost": 0.75, "use_speaker_boost": true, "speed": 1.0 } } } }' # → data.id = # 3. Создать заказ по шаблону (текст в input_text) curl -s -X POST "$BASE/orders" -H "X-API-KEY: $KEY" -H "Content-Type: application/json" -d '{ "template_id": "", "input_text": "Привет! Это тестовая озвучка через Lumean API." }' # → data.id = , data.status = "created" # 4. Дождаться готовности: опрос статуса (или WebSocket, см. §10) curl -s "$BASE/orders/" -H "X-API-KEY: $KEY" # ждём data.status = "completed" (или "partially_completed") # 5. Забрать файл-результат: путь берём из data.result.files[] (элемент — строка-путь) curl -s -X POST "$BASE/storage/url" -H "X-API-KEY: $KEY" -H "Content-Type: application/json" \ -d '{ "path": "<строка_из_result.files[]>" }' # → data.url = временная ссылка; качаем обычным GET ``` В шаге 2 `tts_settings.mode` — обязателен, а `tts_settings.language_code` — опциональный ISO-639-1 код (не показан выше для краткости минимального примера); подробнее — §8.2. --- ## 2. Базовый URL и окружения | Что | Значение (production) | | --- | --- | | REST base | `https://api.lumean.app/api/public` | | WebSocket host / port / scheme | `ws.lumean.app` / `443` / `wss` | | WS app key (публичный) | `7c4dd881d8116ac76fe89aff71d8c2ff` | | WS auth endpoint | `POST https://api.lumean.app/api/public/broadcasting/auth` | | OpenAPI (REST) | `https://api.lumean.app/docs/public-openapi.json` | | OpenAPI (REST, EN) | `https://api.lumean.app/docs/public-openapi.en.json` | | AsyncAPI (WS) | `https://api.lumean.app/docs/public-asyncapi.json` | Все запросы — HTTPS. Тело — JSON (`Content-Type: application/json`), кроме загрузки файлов (`multipart/form-data`). Ответы — JSON в UTF-8. --- ## 3. Аутентификация — заголовок `X-API-KEY` Каждый запрос обязан нести заголовок: ``` X-API-KEY: <ваш_ключ> ``` Ключ хешируется (sha256) и резолвится с кэшем ~1 час. При успехе сервер действует от имени владельца ключа. ### Необязательный заголовок `X-Timezone` ``` X-Timezone: Europe/Moscow ``` Все моменты времени в ответах — ISO-8601 с **явным оффсетом** (`2026-08-10T15:34:56+03:00`). По умолчанию это UTC; прислав `X-Timezone`, вы получите те же моменты, записанные в вашей зоне. Принимается только имя зоны IANA — голый оффсет (`+03:00`) отвергается, потому что не знает про переход на летнее время. Ответ сообщает **фактически применённую** зону тем же заголовком: прислав мусор, вы увидите `X-Timezone: UTC` и поймёте причину. Календарные даты (`Y-m-d`: границы периодов действия) по зоне не конвертируются — у них её нет. **Ошибки авторизации (HTTP 401), тело `{ "success": false, "message": <строка>, "data": null }`:** | Причина | message-ключ | | --- | --- | | Нет заголовка | `auth.api_key.missing` | | Неизвестный / неактивный ключ / удалённый или заблокированный пользователь | `auth.api_key.invalid` | | Ключ истёк (`expires_at` в прошлом) | `auth.api_key.expired` | ### Права (permissions) Каждый эндпоинт требует конкретное право. Ключ без нужного права → **HTTP 403** `{ "success": false, "message": , "data": null }`. | Право | Открывает | | --- | --- | | `orders.read` | Чтение заказов, чанков, WebSocket-подписка на заказы | | `orders.write` | Создание/отмена/повтор заказов, retry/regenerate чанков | | `orders.download` | `POST /storage/url` — ссылки на файлы-результаты | | `templates.read` | Чтение шаблонов, `browse`, `config-options` | | `templates.write` | Создание/изменение/удаление шаблонов | | `voices.read` | Все каталоги голосов (LumVoice + ElevenLabs + HeyGen + Cartesia + Fish Audio), список своих клонов Cartesia и Fish Audio, WebSocket-подписка на клоны | | `voices.write` | Создание, повтор и архивирование клонов голоса Cartesia и Fish Audio | | `billing.read` | `usage`, `subscriptions`, (при включённом кошельке) `wallets`/`ledger-transactions` | | `profile.read` | `GET /user` (профиль) | | `reseller.read` | Кабинет реселлера (§7.13): профиль и баланс, настройки кодов, статистика, список и один код **с полным значением**, WebSocket-подписка на канал кодов | | `reseller.write` | Выпуск подарочных кодов с баланса реселлера и их отмена (§7.13) | | `*` (wildcard) | Проходит любую проверку прав, **кроме** `reseller.read`/`reseller.write` | **Пресеты прав** (набор, который обычно назначают ключу): - `read_only` = все read-права: `orders.read`, `templates.read`, `voices.read`, `billing.read`, `profile.read`, `orders.download`. - `automation` = `orders.read`, `orders.write`, `orders.download`, `templates.read`, `voices.read`, `billing.read`, `profile.read`. - `full` = все права (включая `voices.write`), кроме прав реселлера. `reseller.read` и `reseller.write` не входят ни в один пресет и не покрываются `*` — только явным перечислением в правах ключа: код — деньги на предъявителя. В форме ключа группа «Реселлер» видна только пользователю с профилем реселлера. `voices.write` — write-право: в `read_only` и `automation` его нет. Ключу, который клонирует голоса, добавьте его вручную либо возьмите `full`. > Можно перечислить несколько прав через запятую в требовании — достаточно любого. `orders.download` > — это отдельное право для скачивания (не покрывается `orders.read`). --- ## 4. Соглашения ### Конверт ответа **Успех** (200/201): ```json { "success": true, "message": "<человекочитаемо>", "data": } ``` **Ошибка домена/инфраструктуры** (400, 404, 429 rate-limit, 500, 503 и пр.): ```json { "success": false, "message": "<причина>" } ``` Ключ `errors` в публичном API на этих кодах не используется — не путайте с 422 ниже, где он обязателен. Некоторые доменные 4xx (напр. 402/409 биллинга, 429 квоты) несут дополнительные машиночитаемые поля поверх `success`/`message` — см. §12. 404 на путь, которого нет, несёт `reason: "endpoint_not_found"` и подсказку — это сигнал прекратить перебор адресов (§6.1). **Ошибка валидации** (422) — стандартный формат Laravel, **без** ключа `success`: ```json { "message": "<итоговое>", "errors": { "field.name": ["текст ошибки", "..."] } } ``` ### Пагинация Пагинированные списки кладут в `data`: ```json { "items": [ ... ], "current_page": 1, "last_page": 5, "per_page": 20, "total": 93 } ``` Параметры запроса: `page` (с 1), `per_page` (обычно 1..100). **Исключение:** внешние каталоги голосов используют свою обёртку `{ voices, total, page, page_size, has_more }` с `page` **от 0**. ### Типы идентификаторов | Ресурс | Тип `id` | | --- | --- | | Order | **UUID** (строка) | | Template | **UUID** (строка) | | User, ApiKey, Subscription, Service | **integer** | | LumVoice | id голоса (в пути `voices/{voice}`) | | Внешний голос (ElevenLabs/HeyGen/Cartesia/Fish Audio) | строковый `voice_id` провайдера (у Fish — 32 hex-символа, не UUID) | | Клон голоса Cartesia | **UUID** (`id` — для путей `voices/cartesia/clones/{voiceClone}`); в шаблон идёт его строковый `voice_id` | | Клон голоса Fish Audio | **UUID** (`id` — для путей `voices/fishaudio/clones/{voiceClone}`); в шаблон идёт его `voice_id` (32 hex-символа, не UUID) | Даты — ISO-8601 (`2026-07-08T12:34:56+00:00`). Локаль ответа — по `Accept-Language`/настройке пользователя (влияет на локализованные `message`/labels). --- ## 5. Типы заказов (`task_type`) Enum `task_type` (дословно, 9 значений): `tts`, `image`, `txt2img`, `remix`, `image_edit`, `voice_clone`, `sfx`, `music`, `voice_search`. Это полный список enum'а (валидные значения фильтра `GET /orders?task_type[]=…`), но **создаются** через публичный `POST /orders` не все — см. ниже. Как создаётся каждый **доступный** тип на `POST /orders`: | task_type | Способ | Что передавать | Файлов в `result.files[]` | | --- | --- | --- | --- | | `tts` | по шаблону (сервис `elevenlabs`, `heygen` или `cartesia`) | `template_id` + `input_text` (текст озвучки) | 1 (склеенная дорожка) + субтитры в `service_files` | | `sfx` | template-less | `task_type: "sfx"` + `task_data.text` (см. §8.1, рецепт §11-B) | **ровно 1** аудиофайл | | `music` | template-less | `task_type: "music"` + `task_data.prompt` (см. §8.1, рецепт §11-C) | **`n_variants`** аудиофайлов (1..4) | | `voice_search` | template-less | `task_type: "voice_search"` + аудио в `input_files` (multipart), опционально `task_data.top` | файлов нет — результат это список похожих голосов | Правило: на `POST /orders` обязателен **один из** `template_id` **или** `task_type`. Шаблон однозначно задаёт сервис и его настройки; `task_type` без шаблона работает **только** для сервисов, у которых код сервиса совпадает с типом задачи — это **`sfx`**, **`music`** и **`voice_search`**. > **Через публичный `POST /orders` создаются `tts` (по шаблону), `sfx`, `music` и > `voice_search` (template-less).** Значения `image`, `txt2img`, `remix`, `image_edit`, > `voice_clone` валидны только как фильтр `GET /orders?task_type[]=…` (могут встречаться на > ранее созданных заказах); создать заказ такого типа по API-ключу нельзя — сервиса с таким > кодом нет, попытка даст **422** `service_not_found`. Не пытайтесь их создавать. > Клонирование голоса Cartesia — это НЕ заказ: у него свои эндпоинты `voices/cartesia/clones` > (§7.12), и `task_type: "voice_clone"` для него не нужен. Так же у Fish Audio — `voices/fishaudio/clones`. **`voice_search`** — подбор похожих голосов по вашему аудиофрагменту (не по текстовому описанию). Аудио обязательно (без файла → отказ `source_file_required` до списания), тип проверяется по содержимому файла, а не по расширению: картинка или архив дадут `source_file_unsupported`. Запись длиннее 60 секунд обрезается — вектор диктора насыщается раньше, признак обрезки приходит в результате. `task_data.top` (1..50, по умолчанию 10) задаёт число кандидатов. Цена — одна ставка за заказ, от длительности записи не зависит. ### Статусы заказов (`order.status`) Enum `OrderStatus` (дословно, 9 значений): `created`, `pending`, `in_progress`, `completed`, `result_delivered`, `failed`, `compensated`, `cancelled`, `partially_completed`. **Терминальные** (заказ достиг финального состояния, дальше не меняется): `completed`, `result_delivered`, `failed`, `compensated`, `cancelled`. **Нетерминальные**: `created`, `pending`, `in_progress`, `partially_completed` — последний не терминален специально: его можно доретраить в `completed` через `POST /orders/{order}/items/retry-failed` (все `failed` разом) или `POST /orders/{order}/items/{item}/retry` (поштучно, в т.ч. `policy_flagged`) — §7.2. Строгий фильтр `status` в `GET /orders` (§7.1) принимает только эти значения — иное → 422. --- ## 6. Лимиты: rate-limit и токен-квота Это **два разных** механизма, оба возвращают 429 — различайте по телу. ### 6.1 Rate-limit (число запросов) Ограничение частоты по окнам ключа (`limits.requests.per_minute|per_hour|per_day`). Превышение → **HTTP 429**, тело `{ "success": false, "message": "...", "reason": "rate_limit_exceeded", "error_code": "rate_limit_exceeded", "retry_after": <секунды> }` и заголовки `Retry-After`, `X-RateLimit-*` — ждите `retry_after` секунд и повторяйте. > **Бан IP — тоже 429, но не про ключ.** Адрес, замеченный в переборе несуществующих путей, > банится на время (5 мин → 10 → 30 → 1 ч → 24 ч) на ВСЕХ путях, до проверки ключа: 429 с > `reason`/`error_code` = `ip_banned`, `retry_after`, `banned_until`, `ban_step`, > `ban_ladder_seconds` и заголовком `Retry-After`. Повтор до `banned_until` бан не снимет — > остановите перебор и дождитесь срока. Предупреждение приходит ДО бана: каждый 404 на путь, > которого нет, несёт `reason`/`error_code` = `endpoint_not_found`, `message` (ru) и `message_en` > с подсказкой, `method`, `path`, `docs` (адреса этого файла), `developers` и `ban_warning` > (`status: 429`, `reason: "ip_banned"`, `ban_ladder_seconds`). Такой 404 — сигнал прекратить > перебор, а не пробовать соседний адрес. > **Дефолт по частоте — «без лимита», а не 60/мин.** Ключ, созданный без явных request-окон, > по умолчанию **не ограничивается по частоте** (`limits.requests.* = null` → сервер применяет > `Limit::none()`). Числовой дефолт включается, только если оператор задал его в окружении > (`API_KEY_DEFAULT_RATE_PER_MINUTE|_HOUR|_DAY`). Действующие окна вашего ключа — в личном > кабинете (`limits.requests.*`). Реальный расход всё равно ограничен квотой аккаунта (см. §6.2), > даже когда частота не лимитирована. Есть **третий** источник 429 — usage-лимит подписки > (`reason: limit_exceeded`, §12), без `Retry-After`, и **четвёртый** — лимит одновременно активных задач (`reason: concurrency_limit_exceeded`, §12), тоже без `Retry-After`. Последний не про частоту и не про объём: он ограничивает, сколько ваших заказов может выполняться ОДНОВРЕМЕННО. Пачка из сотен заказов, отправленная залпом, упрётся именно в него — лечится не паузой между запросами, а ожиданием завершения уже запущенных. **Пятый** — кулдаун после серии контентных блокировок (`reason: policy_cooldown_active`, §12); он единственный из «заказных» 429 несёт `Retry-After` и `retry_after`/`retry_at`. Лечится не паузой и не ожиданием чужих задач, а правкой текста: пять подряд заблокированных политикой задач ограничивают создание новых на 5 минут, дальше 10 и 15. ### 6.2 Токен-квота (объём генерации) Поверх rate-limit'а, но считает **токены** — учётную единицу объёма работы сервиса (`токены = стоимость операции в токенах`; это НЕ деньги/LMC). Окна: `per_minute`, `per_hour`, `per_day`, `per_month` из `limits.tokens.*` ключа. Ключ без токен-лимитов — без ограничения по токенам. Кроме окон, у ключа может быть **пул** — `limits.tokens.quota` (`{limit, used, remaining}`): объём токенов, который выдаёт администратор платформы. Пул **не сбрасывается по времени**: заказы тратят его, пока не кончится, затем ключ получает 429 до следующей довыдачи. `limit: null` — пула у ключа нет, он не участвует в проверке. Выдать пул себе нельзя; текущий остаток виден в личном кабинете и в `GET /api-keys/{id}/statistics` (`limits.quota`). Проверяется **до** создания при `POST /orders` (по оценке), `POST /orders/{order}/retry` (по сумме чанков оригинала) и `.../regenerate`. Превышение → **HTTP 429** + `Retry-After`: ```json { "success": false, "message": "API key token quota exceeded", "reason": "token_quota_exceeded", "window": "per_minute", "limit": 10000, "used": 9800, "requested": 500, "reset_at": "2026-07-08T13:00:00+00:00", "retry_after": 42 } ``` `window` — первое нарушенное окно. При 429 по квоте заказ **не создаётся**. Исчерпан пул — тот же `reason`, но `window: "quota"`, `reset_at: null`, `retry_after: null` и **без** заголовка `Retry-After`: ожидание не поможет, нужна довыдача администратором. Если исчерпаны и пул, и окно, приходит `quota`. ```json { "success": false, "message": "API key token quota exhausted: it does not reset over time, ask the administrator to grant more tokens", "reason": "token_quota_exceeded", "window": "quota", "limit": 1000000, "used": 999990, "requested": 500, "reset_at": null, "retry_after": null } ``` ### 6.3 PAYG-добор (квоты подписки не хватило) Отдельная от лимитов развилка **оплаты**, а не отказа. Если заказ стоит больше, чем осталось токенов в квоте подписки, и сервис разрешает pay-as-you-go (`Service.payg_access` ≠ `disabled`), недостающая часть **списывается с LMC-баланса автоматически**, и заказ создаётся сразу (**201**) — отдельного подтверждения не нужно (с 04.09.2026). Сколько ушло из квоты и сколько доплачено — в заказе: `tokens_from_quota` / `tokens_from_payg` (§9). Не хватает и квоты, и денег на добор → **402 `insufficient_balance`**; PAYG у сервиса отключён → `insufficient_allowance` / `no_subscription` (§12) — доплатить нельзя. Поля `confirm_payg_topup` и `quote_token` принимаются ради совместимости и **игнорируются**. Ответы **402 `payg_topup_required`** и **409 `quote_mismatch`** приходят только в режиме отката к явному подтверждению, который включает оператор платформы: в норме их не бывает, но обработчик стоит оставить как запасной путь — **Рецепт G (§11)**; формы тел — §12. --- ## 7. Справочник эндпоинтов Формат: `МЕТОД путь` — `право` — параметры → ответ. Все пути относительны base `…/api/public`. ### 7.1 Orders - **`GET /orders`** — `orders.read` Query: `page` (int≥1), `per_page` (int 1..100, деф. 20), `template_id` (uuid). `status` — строгий enum (невалидное значение → 422): `created`, `pending`, `in_progress`, `completed`, `result_delivered`, `failed`, `compensated`, `cancelled`, `partially_completed` (терминальные статусы — см. §5). `task_type` — строка или массив (`?task_type[]=tts&task_type[]=sfx`); мягкая валидация: неизвестный тип → пустой список, не ошибка. → `data` = пагинированный список `Order` (только ваши заказы). - **`POST /orders`** — `orders.write` — см. §8.0 (тело). → 201, `data` = `Order`. - **`GET /orders/{order}`** — `orders.read`. → `data` = `Order` (с `items`). 404/403. - **`POST /orders/{order}/cancel`** — `orders.write`. Отменяет заказ в статусе `created`/`pending`/`partially_completed`, разблокирует средства, возвращает токен-квоту. → `data` = `Order`. Недопустимо → 400. - **`POST /orders/{order}/retry`** — `orders.write`. Создаёт **новый** заказ с теми же параметрами (исходный должен быть `completed`/`result_delivered`, без `failed`-чанков). Оценка квоты = сумма `price_units` чанков оригинала. Параметры — **снимок исходного заказа**: конфиг шаблона на момент его создания и тот же `config_override`, а не текущее состояние шаблона; правка и удаление шаблона на повтор не влияют (заказы, созданные до конца сентября 2026 года, снимка не имеют и повторяются по текущему шаблону). Снимок, который больше не проходит текущую схему сервиса, → **400** `retry_config_outdated` (§12). **Тело (оба поля опциональны, как у `POST /orders`):** `confirm_payg_topup` (boolean), `quote_token` (string) — нужны только в режиме отката (§6.3), иначе игнорируются. Retry проходит **тот же биллинг-flow, что и создание**: добор сверх квоты подписки списывается автоматически, не хватает денег → **402** `insufficient_balance`, доменный отказ → **403/422**, токен-квота ключа → **429** (см. §8.0 и таблицу reason в §12). → 201, `data` = новый `Order`. - **`POST /orders/chunks/preview`** — `orders.read` (preview не мутирует данные — логически чтение). **Бесплатно**, токен-квоту ключа не тратит. Dry-run разбиения текста на чанки и расчёта стоимости — БЕЗ создания заказа, тот же расчётный конвейер, что и `POST /orders`. Тело: `{ template_id, input_text, task_type?, previous_preview_id?, text_hash?, generation_mode? }`. Throttle: 30/мин (`public-chunks-preview`, отдельный от `orders.write`). → **200** `{ status: "ready", preview_id, summary, chunks, page }` — TTS-текст ≤ 50 000 символов (и любой non-TTS). → **202** `{ status: "processing", preview_id }` — TTS-текст длиннее порога, расчёт в фоне, результат — WS-событие `.ready` на канале `private-chunks.preview.{userId}` (см. §10) либо ручной поллинг GET ниже. → 422 без `input_text`, и тот же `422` `template_model_outdated`, что у `POST /orders` (§12), если шаблон несёт настройки прежней схемы сервиса. Превышение пауз-капов НЕ роняет запрос (в отличие от `POST /orders`) — приходит `summary.caps_ok=false`. `preview_id` — sha256-хеш (64 hex, БЕЗ дефисов), детерминирован по (текст+шаблон+режим): повторный запрос того же текста отдаётся из кэша мгновенно, в т.ч. если тот же текст уже считался веб-сессией того же аккаунта (кэш общий по `user_id`, не по способу входа). Полный референс — `docs/PUBLIC_API_CHUNK_PREVIEW.md`. - **`GET /orders/chunks/preview`** — `orders.read`. Preflight по хешу текста — без пересылки самого текста. Query: `template_id` (uuid), `text_hash` (sha256 сырого `input_text`, нижний регистр hex), `generation_mode?`. Throttle: 120/мин (`public-chunks-preview-read`). → 200 (ready)/202 (processing)/404 (нет в кэше — шлите POST). - **`GET /orders/chunks/preview/{previewId}`** — `orders.read`. Страница уже посчитанных чанков (без пересчёта). `{previewId}` — sha256-хеш, НЕ UUID. Query: `page?` (с 1), `per_page?` (деф. 100, макс 500). Throttle: 120/мин (`public-chunks-preview-read`). → 200/202/404 (протухло/упало — пере-отправьте POST). ### 7.2 Order Items (чанки заказа) Все — ownership по заказу (право `orders.*`). - **`GET /orders/{order}/items`** — `orders.read` → `data` = массив `OrderItem` (без пагинации). - **`GET /orders/{order}/items/{item}`** — `orders.read` → `data` = `OrderItem`. - **`GET /orders/{order}/items/{item}/text`** — `orders.read` → `data` = `{ "text": string|null, "length": int, "original_text_length": int, "free_length": int, "billable_length": int, "max_billable_length": int, "max_raw_length": int, "surcharge_applies": bool, "capacity_unit": "chars"|"utf8_bytes", "raw_length": int }` — готовые пределы правки: `free_length` — оплаченный объём, `max_billable_length` — предел с доплатой, `max_raw_length` — ёмкость фрагмента (её оплатой не снять) в единице `capacity_unit`: `chars` — символы, `utf8_bytes` — байты UTF-8 (Fish Audio: русская буква — 2 байта, латинская — 1); `raw_length` — длина текущего текста в той же единице. Текст, удалённый по сроку хранения, — `422` `input_expired`. - **`POST /orders/{order}/items/{item}/retry`** — `orders.write`. Тело: `{ "text"?: string(max 50000) }`. Повторяет **сбойный** чанк — `policy_flagged` **или** `failed` (заказ при этом `partially_completed`). В пределах оплаченной длины (`free_length`) новых денег и токен-квоты НЕ тратит (использует уже залоченный остаток `price_units − consumed_units`); текст длиннее оплаченного (до `max_billable_length`) берёт доплату за превышение — она учитывается в токен-квоте ключа и возвращается, если повтор не удался. Без `text` повторяется **тот же** текст; с `text` — заменяет текст чанка. Лимит попыток — 5. Недоступно для `sfx`/`music`. → 201, `data` = `OrderItem`. Отказы — с `reason`/`error_code`: `402` (`insufficient_funds`, `insufficient_balance`, `insufficient_allowance`), `409` (`active_retry_exists`, `stitch_in_progress`), `422` (`invalid_status`, `invalid_order_status`, `max_attempts_reached`, `text_over_capacity`, `content_blocked`, `input_expired`, `retry_config_outdated` — настройки заказа не проходят текущую схему сервиса, §12, …), `503` (`service_maintenance`), `429` — токен-квота ключа за доплату. **При `policy_flagged` шлите исправленный `text` — см. плейбук §7.11.** - **`POST /orders/{order}/items/retry-failed`** — `orders.write`. **Массовый повтор.** Тело **пустое**. Ставит на повтор все чанки заказа в статусе `failed` разом — вместо обхода `.../items/{item}/retry` в цикле. `policy_flagged` сюда **не входит**: тот же текст отклонят снова, такие чанки перезапускают поштучно с исправленным `text`. → **`202`** (не 201): план принят, работа идёт в фоне. `data`: ```json { "queued_count": 2, "queued": [ { "item_id": "9a1e4f60-2b77-4a1c-8d33-5c0e1b7a9f21", "chunk_index": 3 }, { "item_id": "7c4b18ad-6e02-4f9b-91a7-0d2c5e8b3f14", "chunk_index": 5 } ], "skipped_count": 1, "skipped": [ { "item_id": "1f2d90c4-3a15-4e6b-b8d2-7f4a6c1e0b93", "chunk_index": 7, "reason": "policy_flagged", "reason_label": "Чанк отклонён политикой контента — перезапустите его отдельно с исправленным текстом." } ] } ``` Синхронного результата у вызова нет **по построению** (повтор чанка — это чтение/запись S3 и транзакция на каждый элемент): дождитесь `GET .../items` либо слушайте WebSocket — событие `bulk_retry.completed` (§10). `reason` каждого пропуска — машинный код: | `reason` | Смысл | Что делать | | --- | --- | --- | | `superseded` | у чанка уже есть успешная версия (либо последняя версия — перегенерация) | ничего, чанк здоров | | `active_retry_exists` | повтор уже идёт (`pending`/`processing`) | дождаться | | `policy_flagged` | нужен исправленный текст | поштучный retry с новым `text` (§7.11) | | `max_attempts_reached` | исчерпан лимит попыток (5) | только новый заказ | | `insufficient_funds` | не осталось залоченного остатка (`price_units − consumed_units`) | только новый заказ | `reason_label` — тот же код словами, на языке ключа; **логику стройте по `reason`**, не по label. **Биллинг:** бесплатно, как и поштучный retry (переиспользует уже заблокированный остаток), токен-квоту ключа не расходует. **Отказы на уровне заказа** — телом `{ "success": false, "message": "…", "reason": "<машинный>", "error_code": "<то же значение>" }`: `409` `stitch_in_progress` (по заказу идёт склейка), `422` `invalid_order_status` (заказ не `partially_completed`), `422` `generative_not_supported` (`sfx`/`music`), `422` `nothing_to_retry` (перезапускать нечего), `422` `retry_config_outdated` (настройки заказа не проходят текущую схему сервиса — отказ синхронный, повтор не ставится, §12), `503` `service_maintenance` (приём сервиса, исполняющего заказ, приостановлен — тоже синхронно, план не принимается). Отдельными схемами в спеке они не описаны: коды рождаются в бизнес-исключении, а не в валидации запроса. - **`POST /orders/{order}/items/{item}/regenerate`** — `orders.write`. Тело: `{ "text": string(required, max 50000) }` (пустой → 422; длиннее ёмкости фрагмента `max_billable_length` → `422` `text_over_capacity`). Платная перегенерация **`completed`**-чанка (не сбойного!): стоимость — по всей новой длине, квота-precheck → 429. Отказы: `402` (`insufficient_balance`, `insufficient_allowance`), `422` (`invalid_status`, `text_not_voiceable`, `content_blocked`, `retry_config_outdated` — §12, …), `503` (`service_maintenance`). Недоступно для `sfx`/`music`. → 201, `data` = `OrderItem`. ### 7.3 Storage (скачивание результатов) - **`POST /storage/url`** — `orders.download`. Тело: | Поле | Правило | Дефолт | Назначение | | --- | --- | --- | --- | | `path` | **required**, string | — | Путь файла как в `result.files[]`/`service_files[]` (строка целиком) | | `download` | sometimes, boolean | `false` | `true` — ссылка помечается как attachment: файл скачается под человекочитаемым именем заказа, а не откроется во вкладке | | `number_base` | sometimes, integer (`0` или `1`) | `1` | С какого числа нумеруются чанки в имени файла (`0` → первый чанк «0») | | `number_padding` | sometimes, integer (`1..4`) | `3` | Ширина номера чанка с ведущими нулями (`3` → «007») | → `data` = `{ "url": string }` (временная ссылка, качать обычным GET; TTL по умолчанию ~60 мин — после истечения запросите заново, сам файл живёт до ретенции заказа, см. §13). Коды: 200 / 403 (чужой файл) / 404 (файл не найден/истёк по ретенции) / 422 (`path` не передан) / 500 (временная ошибка генерации, повторить). > `number_base`/`number_padding` держите одинаковыми с запросом ZIP-архива, иначе один и тот же > чанк называется по-разному поштучно и внутри архива. ### 7.4 Templates - **`GET /templates`** — `templates.read`. Постраничный список шаблонов, новые первыми. Query: `page` (≥1), `per_page` (**1..30**, деф. 30), `search` (подстрока названия, ≤100), `service` (code сервиса), `folder_id` (uuid; без него — корень, `folder_id = null`), `sort_by` (`created_at|name`, деф. `created_at`), `sort_order` (`asc|desc`, деф. `desc`). → `data` = `{ items:[Template], current_page, last_page, per_page, total }`. `per_page > 30` → **422**. Все шаблоны — проходом `page=1, 2, …` до `current_page = last_page`; искать нужный — `search`/`service`, а не выкачкой всего списка. > **Устарело (с 06.10.2026):** запрос **без единого параметра** по-прежнему отдаёт все корневые > шаблоны массивом в `data` (без пагинации) и несёт заголовки `Deprecation`, `Sunset` (дата > снятия, 06.11.2026) и `Link: <…?page=1&per_page=30>; rel="successor-version"`. После даты снятия > такой запрос получит первую страницу (`data` станет объектом). Переход: добавить `?page=1` и > читать `data.items`. > Шаблон на каждый заказ заводить не нужно: один шаблон переиспользуется, а настройки под > конкретный заказ (голос, скорость и т.п.) меняет `config_override` в `POST /orders` (§8.1). - **`GET /templates/browse`** — `templates.read`. Query: `page` (≥1), `per_page` (1..100, деф. 15), `sort_by` (`name|created_at`, деф. `name`), `sort_order` (`asc|desc`, деф. `asc`), `folder_id` (uuid), `service` (code сервиса). → `data` = `{ items:[Template-lite], current_page, last_page, per_page, total, current_folder, breadcrumbs }`. - **`GET /templates/config-options`** — `templates.read`. Query: `service` (required, code активного сервиса). → `data` = карта опций конфига сервиса (дескрипторы полей: `type`, `options`, `min`, `max`, `step`, `default`, `nullable`). Используйте её, чтобы узнать допустимые ключи/значения `config` для шаблона данного сервиса. - **`POST /templates`** — `templates.write` — см. §8.2 (тело). → 201, `data` = `Template`. - **`GET /templates/{template}`** — `templates.read` → `data` = `Template`. - **`PUT|PATCH /templates/{template}`** — `templates.write`. Частичное обновление (`name`, `is_public`, `folder_id`, и `service_key`+`config` вместе). → `data` = `Template`. Уже созданные заказы правка не меняет: они выполняются, повторяются и показываются (`template.config` в `GET /orders/{order}`) с настройками на момент своего создания (§9). Исключение — заказы, созданные до конца сентября 2026 года: снимка у них нет, они идут по текущему конфигу шаблона с `config_override`, и правка их затрагивает. - **`DELETE /templates/{template}`** — `templates.write` → `data: null`. Шаблон пропадает из `GET /templates` и `/templates/browse`, запросы к `/templates/{template}` → **404**, новый заказ или превью с этим `template_id` → **422**, как на несуществующий шаблон. Созданные по нему заказы выполняются дальше (заказы до конца сентября 2026 года — по конфигу шаблона на момент удаления); если они есть, шаблон сохраняется скрытым, и `GET /orders/{order}` по-прежнему показывает его в `template` (§9). ### 7.5 Voices — LumVoice (внутренние голоса) Право `voices.read`. Элемент — `LumVoice` (см. §9). - **`GET /voices`** — мои голоса. Query: `voice_status` (`pending_clone|cloning|ready|partially_ready|clone_failed|archived`; `partially_ready` — часть языков склонирована, часть упала, рабочие языки доступны), `publication_status` (`private|pending_review|public|rejected`), `language_code`, `search`, `sort_by` (`created_at|updated_at|display_name|last_used_at|usage_count_total`, деф. `created_at`), `sort_order` (`asc|desc`, деф. `desc`), `per_page` (1..100, деф. 20). → пагинированный список `LumVoice`. - **`GET /voices/library`** — моя библиотека. Query: `available` (bool), `search`, `language_code`, `sort_by` (`added_at|created_at|nickname`), `sort_order`, `per_page`. → пагинированный список `{ id, voice_id, nickname, added_at, available, unavailable_reason, origin("own"|"library"), voice: LumVoice|null }`. - **`GET /voices/public`** — публичный каталог. Query: `tag_ids` (array: `tag_ids[]=1&tag_ids[]=2`; одно значение `tag_ids=5` и список через запятую `tag_ids=1,2` тоже принимаются), `language_code`, `gender` (`male|female|neutral`), `search`, `sort` (`popular|newest|name`, деф. `popular`), `per_page`. → пагинированный список `LumVoice` (только публичные, ready, разрешённые в заказах). - Во всех трёх списках тип query проверяется: массив на месте строки (`search[]=x`), нечисловой `per_page` или элемент `tag_ids`, не-булев `available` → `422` с `errors.<поле>`. Неизвестное значение перечисления (`sort_by=foo`, `voice_status=foo`) — не ошибка: фильтр игнорируется, `per_page` сверх 100 зажимается до 100. - **`GET /voices/tags`** → `data` = массив `{ id, code, name, description, color, sort_order }`. - **`GET /voices/{voice}`** → `data` = `LumVoice` (свой / публичный / из библиотеки). 404/403. ### 7.6 Voices — внешние провайдеры (ElevenLabs, HeyGen, Cartesia, Fish Audio) Право `voices.read`, read-only. Отсюда берут `voice_id` для TTS-шаблонов. У ElevenLabs и HeyGen обёртка — **внутри `data`**: `data = { voices: [...], total, page, page_size, has_more }`, `page` **с 0**. У Cartesia — обычная пагинация (`items`, `page` с 1), см. последний пункт. - **`GET /voices/elevenlabs/library`** — публичная Voice Library ElevenLabs. Query: `search`, `sort`, `required_languages`, `accent`, `use_cases`, `page` (≥0, деф. 0), `page_size` (≥1, деф. 30); `gender` — строгий enum `male|female`; `age` — строгий enum `young|middle_aged|old` (именно так, через нижнее подчёркивание; «middle-aged» → 422). Элементы — объекты ElevenLabs. **Зависит от внешнего API ElevenLabs → 503 при недоступности.** - **`GET /voices/heygen`** — каталог голосов HeyGen. Query: `language`, `accent`, `voice_engine` (CSV), `search`, `sort` (`name|newest|default`), `page` (≥0, деф. 0), `page_size` (1..200, деф. 55); `gender` — enum `male|female|unknown`. Третье значение есть **только здесь**: у ElevenLabs — `male|female`, у LumVoice (`GET /voices/public`) — `male|female|neutral`. HeyGen отдаёт часть голосов без указанного пола. Элемент: `{ voice_id, voice_name, display_name, gender, language, locale, accent, flag_url, preview_url, voice_engines:[...], labels:{...}, support_realtime, emotion_support, support_locale }`. - **`GET /voices/heygen/filters`** → `data = { voice_engines:[{value,count}], genders:[...], languages:[...], accents:[...], labels:[...] }`. - **`GET /voices/cartesia`** — каталог голосов Cartesia (около тысячи голосов, ~40 языков). Query: `language` (ISO 639-1, напр. `ru`), `gender` (`masculine|feminine|gender_neutral` — написание Cartesia, не `male/female`), `search` (по названию и описанию), `page` (≥1), `per_page` (1..200, деф. 50). → пагинированный список `{ items:[CartesiaVoice], current_page, last_page, per_page, total }` (§9). `voice_id` элемента кладут в `tts_settings.voice_id` шаблона `cartesia`. Свои клоны в каталог не попадают — их `voice_id` отдаёт `GET /voices/cartesia/clones` (§7.12). Если сервис закрыт для владельца ключа (закрытый тест), ответ — **404** `reason: service_not_found`. `language` и `gender` — свободные строки, а не enum: опечатка (`gender=male`, `language=russian`) даёт **200 с пустым `items`**, а не 422. 422 бывает только на форме параметров (`per_page` > 200, `page` < 1, строка длиннее лимита). Пустой `items` при `total: 0` — проверьте написание фильтров. - **`GET /voices/fishaudio`** — каталог голосов Fish Audio (публичные TTS-голоса Fish, обновляются раз в сутки; языки каталога — `ru`, `en`, `es`). Query: `language` (`ru|en|es`), `gender` (`male|female`), `search` (по названию и описанию), `page` (≥1), `per_page` (1..200, деф. 50). → пагинированный список `{ items:[FishAudioVoice], current_page, last_page, per_page, total }` (§9), порядок — по популярности (`task_count`). `voice_id` элемента (32 hex-символа, не UUID) кладут в `tts_settings.voice_id` шаблона `fishaudio`. Свои клоны в каталог не попадают — их `voice_id` отдаёт `GET /voices/fishaudio/clones` (§7.12). Сервис в закрытом тесте и ключ не бета-тестера → **404** `reason: service_not_found`. Фильтры — свободные строки: опечатка даёт **200 с пустым `items`**, а не 422. Подписка для каталога не нужна — только право `voices.read` и доступ к сервису. Полные примеры ответов — §7.12, «Ответы по кодам». `preview_url` — подписанная ссылка на аудио-превью, играется обычным `