POST/orders

Создаёт заказ на генерацию от имени владельца ключа и сразу ставит его в очередь. Ответ приходит немедленно, со статусом created/pending — результата в нём ещё нет.

orders.writeасинхронный402 PAYG 409 конфликт 429 лимиты

Поправки к спецификации · 2

В enum TaskType не хватает voice_search
Спека перечисляет восемь типов задач, сервис принимает девять: voice_search (подбор похожих голосов по аудиофрагменту) в enum не попал, хотя работает и валидацию проходит. Мы дописали его в списки на этой странице.
Тарификация разметки [шёпот] и <break/> не согласована
Три места в спеке утверждают, что теги разметки ([шёпот], <break/>) не тарифицируются, а описание поля billable_length — что тарифицируются. Пока расхождение не разрешено бэкендом, считайте худший случай: закладывайте символы разметки в оценку стоимости. Точную цену конкретного текста даёт POST /orders/chunks/preview — он возвращает уже посчитанную длину.

Два способа создать заказ

По шаблону — template_id + input_text. Шаблон задаёт сервис, тип задачи, голос и все настройки; в заказе остаётся прислать только текст. Разово отклониться от настроек шаблона можно через config_override, не создавая новый шаблон.

Без шаблона — task_type + task_data. Так работают sfx и music (весь промпт и параметры в task_data) и voice_search (аудиофрагмент в input_files). Для tts нужен шаблон — в нём выбор голоса и модели.

Одно из двух полей (template_id или task_type) обязательно. Полный разбор каждого поля и готовые примеры — во вкладке Body.

Как режется текст

По умолчанию текст режется на фрагменты подряд, по техническому размеру: границы абзацев роли не играют. Абзацный режим делит текст сначала по пустой строке, и абзац становится самостоятельной единицей генерации — в ответе появляются paragraphs[], а у фрагментов paragraph_index.

Включается ключом generation_mode в config_override (пример — во вкладке Body, сценарий «TTS по абзацам»). Учтите: минимальный тарифицируемый объём в этом режиме считается по каждому абзацу. Подробности — в описании поля config_override.

Разметка внутри текста (озвучка)

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

Вид	Пример	Что делает
Пауза	`{{pause=2.5}}`, `{{pause:500ms}}`, `{{pause}}`	Тишина указанной длины; без значения — 1 секунда
Пауза SSML	`<break time="2s"/>`, `<break time="500ms"/>`	То же самое в SSML-нотации
Указание диктору	`[шёпот]`, `[Тихий голос]`	Подсказка модели о манере чтения

Квадратные скобки — это ВСЯ разметка, а не список ключевых слов. Вырезается любой фрагмент вида […] без переноса строки внутри. Сноска [1], пометка [sic], тайм-код [00:12], ссылка [рис. 3] — всё это исчезнет из озвучки. Если квадратные скобки должны прозвучать, замените их.

Обратная сторона: круглые и угловые скобки, звёздочки и прочая типографика озвучиваются и тарифицируются. Ремарки сценария (пауза), <Fade out>, *шёпотом* диктор прочитает вслух — их нужно убирать самим либо переводить в […].

Ограничения размера и пауз

Проверяются до создания заказа, превышение → 422, деньги не резервируются:

Ограничение	Значение
Фрагментов в заказе	не больше 1500
Пауз в тексте	не больше 500
Одна пауза	не длиннее 10 секунд
Суммарная тишина	не больше 3600 секунд

Считаются только паузы; указания диктору в […] под эти лимиты не подпадают.

Фрагменты — это не символы. Сколько их выйдет, показывает POST /orders/chunks/preview (summary.chunks_count); там же превышение видно заранее как caps_ok=false + caps_exceeded="chunks", без отказа. Предел технический: финал заказа собирается из фрагментов одной операцией, и сверх этого числа она не успевает завершиться. Текст, который упирается в потолок, нужно разделить на несколько заказов.

Отдельный отказ — текст, в котором после вырезания разметки не осталось ничего произносимого: только теги, только знаки препинания (..., !!!, —) или только скобочные ремарки. Такой заказ не создаётся.

Что сервер меняет в тексте

Перед нарезкой текст приводится к канону — сохранённый заказ и все смещения фрагментов считаются уже от изменённого текста:

Что	Как
Переносы строк	`\r\n` и `\r` → `\n`
Табуляция	Заменяется пробелом
Больше 3 переносов подряд	Схлопываются до 3
Больше 5 пробелов подряд	Схлопываются до 5
`Привет.Мир` (только озвучка)	Пробел после `.`, `!`, `?` перед буквой или цифрой → `Привет. Мир`

Последнее правило не трогает десятичные (3.14), сокращения (т.д.), акронимы (U.S.A.), URL со схемой, email, многоточия и содержимое тегов разметки. Голый домен без схемы (example.com в середине фразы) от Привет.Мир неотличим и пробел получит — пишите такие адреса со схемой.

Что делать после ответа

Запомните id заказа из ответа.
Дождитесь готовности: подпишитесь на WebSocket-канал private-order.task.{orderId} (без поллинга) либо опрашивайте GET /orders/{order}.
Терминальные статусы: completed, result_delivered, failed, compensated, cancelled. Отдельно partially_completed — часть чанков не удалась и ждёт вашего решения (см. POST /orders/{order}/items/{item}/retry).
Файлы результата — в result.files[]; ссылку на скачивание даёт POST /storage/url.

Оплата

Сначала расходуется квота подписки, и только остаток — из LMC-баланса: если квоты не хватило, добор списывается автоматически и заказ создаётся сразу (201). Не хватает денег на добор — 402 insufficient_balance. Поля confirm_payg_topup и quote_token нужны только в режиме отката к явному подтверждению (его включает оператор платформы: тогда вместо заказа приходит 402 payg_topup_required с суммой добора) — подробности в описании поля confirm_payg_topup.

Стоимость заказа списывается с токен-квоты вашего ключа. Проверка идёт до создания заказа: при превышении вернётся 429, заказ не создастся и файлы не загрузятся.

Провенанс (source=api, api_key_id) проставляет сервер — передавать его не нужно.

Требуемое право ключа: orders.write.

На этой странице(4)

Тело запроса

multipart/form-dataapplication/json

Заказ создаётся одним из двух способов: по шаблону (template_id + input_text) или без шаблона (task_type + task_data). Выберите готовый пример ниже — он подставится в редактор.

Сценарии

TTS по шаблону TTS по абзацам TTS другим голосом SFX без шаблона Музыка без шаблона Подтверждение PAYG-добора

TTS по шаблону

{
  "template_id": "4d3e9f8b-2c1a-4f5a-8b9c-0d1e2f3a4b5c",
  "input_text": "Здравствуйте! Рады видеть вас в Lumean.",
  "name": "Приветствие для лендинга"
}

Поля

template_idнеобязательное

UUID шаблона — он определяет сервис, тип задачи и все настройки генерации. Либо template_id, либо task_type обязателен; если переданы оба, ведущим считается шаблон.

Шаблон — обычный способ работы: настройки заданы один раз, в заказе остаётся прислать только текст. Разовое отклонение от настроек шаблона — config_override.

может быть nulluuid

string

Пример 4d3e9f8b-2c1a-4f5a-8b9c-0d1e2f3a4b5c

task_typeнеобязательное

Тип задачи для генерации без шаблона. Обязателен, если не передан template_id.

Значение	Что делает	Где параметры
`sfx`	Звуковой эффект по текстовому описанию	`task_data`
`music`	Музыкальный трек по описанию	`task_data`
`voice_search`	Подбор похожих голосов по вашему аудиофрагменту	`input_files` (аудио) + `task_data.top`

Для tts шаблон нужен — в нём лежит выбор голоса и модели.

может быть null

Значенияttsimagetxt2imgremiximage_editvoice_clonesfxmusicvoice_search

string

Пример sfx

nameнеобязательное

Человекочитаемое имя заказа: определяет имя скачиваемого файла и имя ZIP-архива.

Не передано — сервер выведет сам в таком порядке: имя загруженного файла без расширения → первые ~60 символов текста по границе слова (паузные теги {{pause=…}} вырезаются).

может быть null≤ 120 симв.

string

Пример Приветствие для лендинга

task_dataнеобязательное

Параметры генерации для заказа без шаблона — «временный шаблон» на один заказ. JSON-объект; multipart-клиент может прислать его одной JSON-строкой.

Ключи кладите в корень объекта, без обёртки. GET /templates/config-options показывает те же параметры сгруппированными в секцию (sfx_settings, music_settings) — это форма для интерфейса настроек, а не форма запроса. Прислав {"sfx_settings": {"text": "…"}}, вы получите 422 «text обязателен»: обёртка спрятала ключ.

SFX (task_type: "sfx") — одна генерация = один файл:

Ключ	Тип	Дефолт	Назначение
`text`	string, обязателен	—	Описание звука; английский промпт работает лучше
`prompt_influence`	number `0..1`	`0.3`	Насколько строго держаться промпта
`duration_seconds`	number `0.5..30`	`null`	`null` = авто-длительность
`loop`	boolean	`false`	Бесшовное зацикливание
`output_format`	`mp3_44100_128` \| `mp3_44100_192` \| `opus_48000_128`	`mp3_44100_128`	Формат результата

Music (task_type: "music") — n_variants генераций = столько же файлов:

Ключ	Тип	Дефолт	Назначение
`prompt`	string, обязателен	—	Описание трека: жанр, настроение, инструменты
`n_variants`	integer `1..4`	`1`	Сколько вариантов сгенерировать. Умножает цену и даёт столько же файлов в `result.files[]`
`lyrics_text`	string	`null`	Текст песни; пусто и без `force_instrumental` — модель может добавить вокал сама
`force_instrumental`	boolean	`false`	Инструментал без вокала
`music_length_ms`	integer `10000..30000`	`30000`	Длительность в миллисекундах: 10–30 сек максимум, больше `30000` → 422
`model_id`	`music_v2`	`music_v2`	Пока единственное значение

Voice Search (task_type: "voice_search") — аудиофрагмент едет в input_files, здесь только один параметр:

Ключ	Тип	Дефолт	Назначение
`top`	integer `1..50`	`10`	Сколько похожих голосов вернуть

Что определяет цену

Считается число генераций, а не их размер:

Тип	Цена	На цену НЕ влияют
`sfx`	Одна ставка сервиса за заказ	`duration_seconds`, длина `text`
`music`	Ставка × `n_variants`	`music_length_ms`, длина `prompt`, `lyrics_text`
`voice_search`	Одна ставка за заказ	Длительность записи, `top`

Пятиминутный трек стоит столько же, сколько десятисекундный, — платите за обращение к модели. Фактически списанное придёт в price_units созданного заказа.

Сервер домешивает к вашим значениям default_config сервиса (ваши приоритетнее) — отключается флагом skip_service_defaults. Значение вне диапазона или enum → 422 до биллинга, заказ не создаётся и деньги не резервируются.

object

Пример {"text":"Тяжёлая деревянная дверь скрипит и захлопывается","duration_seconds":4}

config_overrideнеобязательное

Разовое отклонение от настроек шаблона — единственный способ поменять параметры под конкретный заказ, не создавая новый шаблон. Форма — тот же JSON-объект, что и config шаблона; применяется поверх него только к этому заказу.

Например, озвучить один заказ другим голосом: {"tts_settings": {"voice_id": "<OTHER_VOICE_ID>"}} — остальной конфиг шаблона сохранится.

Пути, которых нет в схеме сервиса, молча отбрасываются (опечатка в ключе выглядит как «настройка не применилась»); оставшиеся значения валидируются по схеме — вне диапазона или enum → 422. Работает только вместе с template_id: у template-less sfx/music все параметры и так в task_data.

Присылайте только те ключи, которые меняете. Явный null — не «оставить как в шаблоне», а «стереть»: он перезапишет значение шаблона на пустое для этого заказа. Клиент, который сериализует всю форму настроек целиком и кладёт null в незаполненные поля, таким образом молча сбросит половину шаблона. Отсутствующий ключ — единственный способ сказать «не трогать».

Абзацный режим озвучки

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

Ключ лежит НЕ внутри tts_settings, а рядом с ним, в корне config_override:

{"generation_mode": "paragraph"}

Значение	Что делает
`paragraph`	Абзац — самостоятельная единица генерации
`default`	Сплошной рез по размеру фрагмента (так же, как без ключа)

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

Что изменится в ответе: у заказа появится paragraphs[] (по каждому абзацу — индекс, число фрагментов, общий статус и прогресс), у фрагментов — paragraph_index.

Влияет на цену. Минимальный тарифицируемый объём применяется к КАЖДОМУ абзацу отдельно, а не к заказу целиком: пять коротких абзацев стоят пять минимумов, тогда как тот же текст в обычном режиме обошёлся бы в один.

Влияет и на скорость. Абзац — самостоятельная задача, и одновременно исполняются не больше 10 однофрагментных абзацев плюс 5 многофрагментных на заказ; остальные ждут освобождения места. Текст из сотни коротких абзацев пойдёт волнами, зато первые результаты придут раньше, чем при сплошной нарезке.

Тот же ключ принимает и config шаблона — тогда режим станет постоянным для всех заказов по этому шаблону. В GET /templates/config-options он не перечислен: справочник описывает настройки сервиса, а режим задаётся на заказ.

object

Пример {"tts_settings":{"voice_id":"EXAVITQu4vr4xnSDxMaL"}}

skip_service_defaultsнеобязательное

Не подмешивать default_config сервиса к task_data. Пришлите true, если у вас уже есть полный набор параметров и воркер должен получить ровно его — сервер не добавит ни одного ключа по умолчанию.

Флаг сохраняется на заказе: POST /orders/{order}/retry воспроизведёт то же поведение. На заказы по шаблону не влияет — там конфиг берётся из template.config и config_override, а не из настроек сервиса.

может быть nullпо умолчанию false

boolean

input_textнеобязательное

Текст задачи. Для tts — то, что будет озвучено; сервер сам режет его на чанки.

Каналов текста три, и они равноправны — проверки (капы пауз, «текст нечем озвучить») применяются к каждому:

Канал	Когда использовать
`input_text`	Обычный способ: текст прямо в запросе
`.txt` в `input_files[]`	Длинный текст файлом; содержимое читается как текст задачи
`task_data.text`	Только для заказа без шаблона

Что происходит с текстом до нарезки и как разметка внутри него влияет на цену — в разделах «Разметка внутри текста» и «Как режется текст» описания этого метода.

Для template-less sfx/music это поле не используется — описание звука кладите в task_data.text (SFX) или task_data.prompt (Music).

может быть null

string

Пример Здравствуйте! Рады видеть вас в Lumean.

confirm_payg_topupнеобязательное

Согласие доплатить из LMC-баланса, когда квоты подписки не хватило на весь заказ. В норме не нужно: добор списывается автоматически, а поле игнорируется. Оно действует только в режиме отката к явному подтверждению, который может включить оператор платформы, — правила ниже описывают этот режим.

Порядок списания всегда один: сначала квота подписки, LMC — только за остаток. Если квоты хватает, флаг ничего не меняет и баланс не трогается вообще.

Один флаг ничего не спишет. Согласие действительно только вместе со свежим quote_token из ответа 402, привязанным к вам, сервису и точному объёму задачи. Присланный без токена (или с истёкшим/чужим) confirm_payg_topup: true снова вернёт 402 — списания не произойдёт.

Рабочий цикл: отправили заказ → 402 с shortfall_tokens, shortfall_lmc, quote_token, expires_at → показали сумму пользователю → повторили тот же запрос с confirm_payg_topup: true и этим quote_token. Токен живёт ~60 секунд.

Согласие — верхняя граница: если к моменту списания добор подешевел, спишется фактическая сумма; если подорожал (параллельный заказ съел квоту) — 409 quote_mismatch, запросите 402 заново.

может быть nullпо умолчанию false

boolean

quote_tokenнеобязательное

Подписанная котировка добора из ответа 402 — передавайте строку «как есть», вместе с confirm_payg_topup: true.

Токен привязан к пользователю, сервису и объёму задачи и живёт ~60 секунд. Просроченный, изменённый или выданный на другой заказ токен не действует: запрос вернёт 402 с новой котировкой.

может быть null

string

input_filesнеобязательное

Входные файлы — только multipart/form-data, до 20 МБ на файл. Одиночный файл можно прислать полем input_file.

Тип задачи	Файл
`tts` (озвучка)	`.txt` — полноценная замена `input_text`: содержимое читается как текст озвучки
`voice_search`	Аудиофрагмент, обязателен. Тип проверяется по содержимому, не по расширению; чужой формат (картинка, архив) → `422` до списания. Длиннее 60 секунд — обрезается, признак придёт в результате
`sfx`, `music`	Не используются — всё описание в `task_data`

может быть null

array<file>

Возможные ответы

201

Заказ создан и поставлен в очередь. В data — заказ со статусом created/pending; результата в нём ещё нет.

Пример тела

{
  "success": true,
  "message": "Order created successfully.",
  "data": {
    "id": "c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
    "user_id": 501,
    "template_id": "7e2a4c1d-8b3f-4a5e-9c6d-1f2e3a4b5c6d",
    "task_type": "tts",
    "status": "created",
    "price_units": 420,
    "total_tokens": 0,
    "task_data": {
      "text": "Welcome to our platform! This narration greets every new listener.",
      "total_length": 420
    },
    "result": null,
    "created_at": "2026-07-17T15:00:00+00:00",
    "updated_at": "2026-07-17T15:00:00+00:00",
    "eta_seconds": null,
    "eta_at": null,
    "completed_chunks": 0,
    "total_chunks": 2,
    "progress_percent": 0
  }
}

Поля ответа

successобязательное

Признак успеха. Решение принимайте по HTTP-коду: у любого ответа 2xx здесь true, а ошибка приходит телом другой формы, где этого поля может не быть вовсе.

boolean

messageобязательное

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

string

dataобязательное

Созданный заказ. Он уже в очереди: status = pending, result пуст. Сохраните id и следите за статусом — опросом или по WebSocket.

OrderOrder

idобязательное

UUID заказа. Его подставляют в пути /orders/{order}/… и передают в POST /orders/{order}/retry.

string

user_idобязательное

ID владельца заказа. У заказов, созданных по API-ключу, это всегда владелец ключа — чужой заказ по ключу не увидеть.

integer

nameобязательное

Название заказа: из него берутся имя скачиваемого файла и имя ZIP-архива.

string

templateнеобязательное

Шаблон, по которому создан заказ. Приходит только у заказов с template_id; у заказа без шаблона (sfx/music по task_type) поля нет. config внутри — настройки, с которыми выполняется ИМЕННО этот заказ: конфиг шаблона на момент создания заказа с наложенным config_override; правка шаблона после создания его не меняет. В списке GET /orders config приходит null — полный конфиг отдаёт GET /orders/{order}. Шаблон могли удалить после создания заказа: здесь он виден по-прежнему, но GET /templates/{template} ответит 404, а новый заказ с этим template_id — 422. У заказов, созданных до выхода этой версии API (конец сентября 2026 года), снимка нет: там config — текущий конфиг шаблона с наложенным config_override, и правка шаблона его меняет.

TemplateTemplate

idобязательное

UUID шаблона. Его кладут в template_id при создании заказа.

string

user_idобязательное

ID владельца шаблона.

integer

slugобязательное

Короткий публичный идентификатор для расшаривания. null у шаблона, которым не делились.

string

nameобязательное

Название шаблона — только для человека, на поведение генерации не влияет.

string

service_keyобязательное

Код сервиса, по схеме которого валидируется config: elevenlabs, lumimg и т. д.

string

serviceобязательное

Сервис шаблона справочно: название и тарификация, без схем конфигурации. null означает, что сервиса с таким кодом больше нет.

может быть null

Service | null

configобязательное

Настройки генерации: голос, модель, скорость и прочее — набор ключей задаёт сервис. Допустимые значения смотрите в GET /templates/config-options?service=<код>, значение вне схемы отклоняется с 422. В заказе (template в GET /orders/{order}) это настройки самого заказа — снимок на момент его создания с config_override, а не текущий конфиг шаблона (у заказов, созданных до конца сентября 2026 года, — текущий конфиг шаблона с config_override).

object

is_publicобязательное

Опубликован ли шаблон в общем каталоге.

boolean

folder_idобязательное

UUID папки, в которой лежит шаблон, либо null для корня. Структура папок видна в GET /templates/browse.

string

created_atобязательное

Когда шаблон создан, ISO 8601.

может быть nulldate-time

string

updated_atобязательное

Когда шаблон последний раз менялся, ISO 8601.

может быть nulldate-time

string

template_idобязательное

UUID использованного шаблона либо null, если заказ создан без шаблона.

string

task_typeобязательное

Тип задачи — он определяет, что лежит в task_data и что придёт в result.

Значенияttsimagetxt2imgremiximage_editvoice_clonesfxmusicvoice_search

TaskTypeTaskType

statusобязательное

Текущее состояние заказа. Терминальные — completed, failed, cancelled, compensated; опрашивать заказ дальше смысла нет.

partially_completed — часть чанков готова, часть упала: файлы уже можно забирать, а сбойные фрагменты перезапускать через POST /orders/{order}/items/retry-failed.

Значенияcreatedpendingin_progresscompletedresult_deliveredfailedcompensatedcancelledpartially_completed

OrderStatusOrderStatus

price_unitsобязательное

Заблокированная под заказ сумма в минимальных единицах LMC. Показывать это число как есть нельзя: реальное значение — price_units / 10^precision, где precision берётся из актива рядом. Готовое к показу значение лежит в соседнем decimal-поле.

integer

price_formattedобязательное

Та же сумма, что и price_units, но в целых LMC — готова к показу. null, пока стоимость не зафиксирована.

может быть null

number

currency_assetобязательное

Актив суммы — всегда LMC. Его precision нужен, чтобы перевести минимальные единицы в реальное значение.

AssetAsset

idобязательное

Внутренний идентификатор актива.

integer

codeобязательное

Код актива: LUMC — внутренняя валюта, TOKEN — токены генерации.

string

kindобязательное

Вид актива: деньги или расходуемые единицы. От него зависит, где сумма считается платежом, а где — расходом квоты.

Значенияmoneyunit

AssetKindAssetKind

precisionобязательное

Число десятичных знаков. Ключевое поле: любая целая сумма этого актива делится на 10^precision, чтобы получить реальное значение. Не считайте, что делитель равен 100.

integer

nameобязательное

Название актива для показа, на языке аккаунта.

string

deleted_atобязательное

Когда актив выведен из обращения, ISO 8601. null у действующего.

может быть nulldate-time

string

created_atобязательное

Когда актив заведён, ISO 8601.

может быть nulldate-time

string

updated_atобязательное

Когда актив последний раз менялся, ISO 8601.

может быть nulldate-time

string

total_tokensобязательное

Полная стоимость заказа в токенах: исходные чанки плюс все повторы и перегенерации. Это единица квоты, а не деньги.

может быть null

integer

total_duration_msобязательное

Суммарная длительность полученного аудио в миллисекундах. Это длина результата, а не время, потраченное на генерацию.

может быть null

integer

task_dataобязательное

Входные данные задачи ровно в том виде, в каком их принял сервер: текст, ссылки на загруженные файлы, применённые настройки. Набор ключей зависит от task_type.

может быть null

object

resultобязательное

Результат выполнения. files[] — основные файлы; service_files[] — вспомогательные (субтитры .srt/.vtt/.lrc, alignment) у TTS-заказов. Пути абсолютные и готовы к передаче в POST /storage/url.

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

может быть null

object

created_atобязательное

Когда заказ создан, ISO 8601.

может быть nulldate-time

string

updated_atобязательное

Когда заказ последний раз менялся, ISO 8601. Растёт на каждом переходе статуса — годится как дешёвый признак «что-то произошло».

может быть nulldate-time

string

files_expire_atобязательное

Срок хранения файлов заказа. files_expire_at — момент удаления (null, если заказ ещё не завершён или файлы уже удалены); files_expired — файлов больше нет, скачивать нечего.

может быть null

string

files_expiredобязательное

true — срок хранения истёк и файлы уже удалены: ссылку на них получить нельзя, заказ нужно создавать заново.

boolean

retentionобязательное

Сроки хранения по уровням файлов. Пофрагментные дорожки склеенного заказа удаляются раньше самого результата.

object

chunksобязательное

Срок жизни пофрагментных дорожек — ими работают правка пауз, пересборка финала и перегенерация отдельного фрагмента.

object

expires_atобязательное

Когда исчезнут пофрагментные дорожки, ISO 8601. До этого момента доступны правка пауз, пересборка и перегенерация отдельного фрагмента. null — заказ ещё не завершён (отсчёт не начат) либо фрагментов уже нет.

string

expiredобязательное

true — пофрагментных дорожек больше нет: правка и пересборка отклоняются. Готовый результат при этом может быть ещё доступен — смотрите retention.files.

boolean

expires_earlyобязательное

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

boolean

reasonобязательное

Почему фрагменты недоступны: chunks_purged — удалены по своему сроку, результат ещё на месте; storage_expired — удалены все файлы заказа. null — фрагменты доступны.

может быть null

Значенияchunks_purgedstorage_expired

string

filesобязательное

Срок жизни всех файлов заказа, включая результат. Дублирует поля files_expire_at / files_expired верхнего уровня.

object

expires_atобязательное

Когда будут удалены все файлы заказа, ISO 8601. То же значение, что в files_expire_at — поле верхнего уровня сохранено для совместимости.

может быть null

string

expiredобязательное

То же, что files_expired: файлов больше нет, скачивать нечего.

boolean

eta_secondsобязательное

Оценка оставшегося времени, в секундах — только пока заказ выполняется. У завершённого и у ещё не начатого null.

может быть null

integer

eta_atобязательное

Ожидаемый момент готовности, ISO 8601 — тот же прогноз, что и eta_seconds, только абсолютным временем.

может быть nulldate-time

string

completed_chunksобязательное

Сколько исходных чанков уже готово. Повторы и перегенерации сюда не входят — иначе прогресс уезжал бы выше 100 %.

может быть null

integer

total_chunksобязательное

Сколько исходных чанков в заказе всего. Ноль означает, что разбиение ещё не выполнено.

может быть null

integer

progress_percentобязательное

Готовность в процентах, 0–100 — производная от completed_chunks и total_chunks, считать самому не нужно.

может быть null

integer

stitchingобязательное

true — идёт склейка аудио: результат ещё не финальный. Бывает и при status = completed — после перегенерации фрагмента финал пересобирается, и до конца склейки result указывает на прежнюю дорожку. Скачивать итог — когда stitching = false.

boolean

paragraphsобязательное

Сводка по абзацам: индекс, число фрагментов, общий статус и прогресс каждого абзаца. null — заказ создан в обычном режиме, ориентируйтесь на items[]. Чтобы абзацы появились, создавайте заказ с config_override.generation_mode = paragraph (подробности — в описании этого поля).

может быть null

array<object>

элемент массива

paragraph_indexобязательное

Номер абзаца, с нуля.

integer

chunks_countобязательное

Сколько чанков попало в этот абзац.

integer | number

completed_chunksобязательное

Сколько чанков абзаца уже готово.

string | integer

statusобязательное

Сводный статус абзаца: он выводится из статусов его чанков, а не хранится отдельно. Словарь свой, короче общего: pending, in_progress, failed, completed — заблокированный модерацией чанк тоже даёт failed. Считаются только исходные чанки, поэтому успешный повтор упавшего фрагмента статус абзаца НЕ меняет: смотрите на сам фрагмент в items[].

string

progress_percentобязательное

Готовность абзаца в процентах, 0–100.

integer

result_fileобязательное

Склеенное аудио абзаца целиком: абсолютный путь либо структура с путём и размером. Скачивается через POST /storage/url, как и остальные файлы заказа. null читается по-разному в зависимости от chunks_count: при chunks_count = 1 собственного файла у абзаца нет и не будет — абзац это и есть тот единственный фрагмент, берите его result_file из items[] по тому же paragraph_index; при chunks_count > 1 склейки ещё не было — многочанковый абзац получает файл ТОЛЬКО после неё, никогда заранее.

может быть null

string

itemsнеобязательное

Чанки заказа. Приходят в детальном ответе GET /orders/{order}; в списке GET /orders поля нет — за ними идите в GET /orders/{order}/items.

array<OrderItem>OrderItem

элемент массива

idобязательное

UUID чанка. Подставляется в пути /orders/{order}/items/{item}/….

string

order_idобязательное

UUID заказа, которому принадлежит чанк.

string

item_typeобязательное

Природа записи: chunk — исходный фрагмент, retry — бесплатный повтор упавшего фрагмента, regeneration — платная переделка готового.

Повторы и перегенерации живут отдельными записями с тем же chunk_index: история попыток сохраняется целиком, а звучит в результате последняя.

string

chunk_indexобязательное

Порядковый номер фрагмента в заказе, с нуля. Задаёт порядок склейки итогового файла.

может быть null

integer

paragraph_indexобязательное

Номер абзаца, к которому относится фрагмент, — заполняется только у исходных фрагментов абзацного заказа. null и в обычном режиме, и у записей повтора либо перегенерации: у них своей привязки к абзацу нет, её берут у родительского фрагмента через parent_item_id. Режим включается ключом generation_mode в config_override заказа.

string

parent_item_idобязательное

UUID исходного чанка — у записей retry и regeneration. У самого исходного чанка null.

string

original_text_lengthобязательное

Длина текста, с которой фрагмент создавался. Служит потолком для text в regenerate.

integer

current_text_lengthобязательное

Длина актуального текста фрагмента: после перегенерации отличается от original_text_length.

integer

price_unitsобязательное

Стоимость фрагмента в токенах — это не деньги. Денежная сумма лежит у самого заказа, в его поле price_units (там LMC, здесь токены; поля называются одинаково, единицы разные).

integer

consumed_unitsобязательное

Сколько токенов фактически списано по этому фрагменту. У незавершённого фрагмента — 0.

integer

remaining_lockedобязательное

Сколько токенов ещё зарезервировано под фрагмент. Обнуляется, когда фрагмент завершается или отменяется.

integer

statusобязательное

Состояние фрагмента: pending — ждёт воркера, processing — в работе, completed — готов, failed — техническая ошибка, policy_flagged — отклонён контентной политикой.

Разница между двумя последними определяет способ лечения: failed чинится повтором как есть, policy_flagged — только переформулировкой текста, повтор с прежним будет отклонён снова.

string

result_fileобязательное

Файл готового фрагмента: абсолютный путь либо структура с путём и размером. Скачивается через POST /storage/url, как и файлы заказа. null, пока фрагмент не готов.

может быть null

object | string | null

duration_msобязательное

Длительность полученного аудио в миллисекундах — длина записи, а не время генерации. У не-аудио задач null.

может быть null

integer

attempt_numberобязательное

Номер попытки для этого фрагмента, начиная с 1. Растёт с каждым повтором.

integer

can_retryобязательное

Разрешён ли бесплатный повтор прямо сейчас. Учитывает статус, тип задачи и исчерпание попыток — проверять условия самому не нужно.

boolean

can_regenerateобязательное

Разрешена ли платная перегенерация прямо сейчас. Доступна только для завершённых фрагментов.

boolean

created_atобязательное

Когда фрагмент создан, ISO 8601.

может быть nulldate-time

string

updated_atобязательное

Когда фрагмент последний раз менялся, ISO 8601.

может быть nulldate-time

string

failure_reasonнеобязательное

Причина падения в машиночитаемом виде — есть только у failed и policy_flagged. Остальным приходит null.

может быть null

string

tokens_from_quotaнеобязательное

Сколько из потраченных токенов покрыла квота подписки. null — из квоты не покрыто ничего.

может быть null

integer

tokens_from_paygнеобязательное

Сколько токенов оплачено сверх квоты, из баланса LMC. null — доплаты не было.

может быть null

integer

tokens_spentнеобязательное

Итог по двум предыдущим полям: сколько токенов списано за заказ (квота + доплата). Заказ, покрытый безлимитом подписки, и бесплатные версии сюда не входят — у безлимитного заказа поле null; объём генерации — total_tokens. Повторы (retry) не входят — они не тарифицируются заново.

может быть null

integer

queue_positionнеобязательное

Место в очереди — только у задач поиска голоса (voice_search), которые обслуживаются по одной. У остальных типов задач поля нет.

может быть null

integer

queue_wait_secondsнеобязательное

Оценка ожидания в очереди поиска голоса, в секундах. Оценка, а не обещание: пересчитывается на каждый ответ.

может быть null

integer

400

Ошибка создания

Пример тела

{
  "success": false,
  "message": "The request could not be processed."
}

Поля ответа

successобязательное

Всегда false в ответах об ошибке.

boolean

messageобязательное

Текст ошибки на языке ключа (задаётся заголовком X-Locale).

string

reasonнеобязательное

Машиночитаемая причина — приходит у бизнес-отказов (например, invalid_order_status); у прочих ошибок поля нет. Ветвите обработку по нему, а не по тексту сообщения.

string

error_codeнеобязательное

Тот же машинный код, что в reason, — второе имя поля. Приходит вместе с reason, значения всегда совпадают.

string

401

Невалидный или отсутствующий X-API-KEY

Разобрать этот ответ

Пример тела

{
  "success": false,
  "message": "API key is missing. Provide it in the X-API-KEY header.",
  "data": null
}

Поля ответа

successобязательное

Всегда false в ответах об ошибке.

boolean

messageобязательное

Текст ошибки на языке ключа (задаётся заголовком X-Locale).

string

dataобязательное

Всегда null, когда запрос отклонён до обработки.

может быть null

null

402

Не хватает денег на часть заказа сверх квоты подписки (reason: insufficient_balance) либо тариф запрещает добор (insufficient_allowance). Добор, который покрывает баланс, списывается автоматически, и заказ создаётся с 201. Только в режиме отката к явному подтверждению: payg_topup_required — тело несёт shortfall_tokens, shortfall_lmc, quote_token и expires_at, повторите запрос с confirm_payg_topup: true и этим токеном. Различайте случаи по полю reason.

Разобрать этот ответ

Пример тела

{
  "success": false,
  "message": "Insufficient balance to cover the part of the order beyond the subscription quota.",
  "reason": "insufficient_balance",
  "error_code": "insufficient_balance"
}

Поля ответа

successобязательное

Всегда false в ответах об ошибке.

boolean

messageобязательное

Текст ошибки на языке ключа (задаётся заголовком X-Locale).

string

reasonобязательное

Машиночитаемая причина отказа — по ней ветвите обработку, а не по тексту сообщения.

Значенияinsufficient_balanceinsufficient_allowancepayg_topup_required

string

error_codeобязательное

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

Значенияinsufficient_balanceinsufficient_allowancepayg_topup_required

string

shortfall_tokensнеобязательное

Сколько токенов не покрыла квота подписки — именно они оплачиваются из LMC.

integer

Пример 1200

shortfall_lmcнеобязательное

Стоимость доплаты в LMC, готовая к показу пользователю.

number

Пример 3.6

shortfall_lmc_minorнеобязательное

Та же сумма в минимальных единицах LMC — для точных расчётов без потери копеек.

integer

Пример 360000000

quote_tokenнеобязательное

Подписанная котировка цены: верните её без изменений в повторном запросе вместе с confirm_payg_topup: true.

может быть null

string

Пример q_9f8b2c1a4d3e

expires_atнеобязательное

До этого момента цена зафиксирована. Позже — повторите запрос и получите новую котировку.

может быть nulldate-time

string

Пример 2026-07-25T12:34:56+00:00

403

У ключа нет права orders.write

Разобрать этот ответ

Пример тела

{
  "success": false,
  "message": "This API key does not have permission to perform this action."
}

Поля ответа

successобязательное

Всегда false в ответах об ошибке.

boolean

messageобязательное

Текст ошибки на языке ключа (задаётся заголовком X-Locale).

string

409

Только в режиме отката к явному подтверждению: котировка добора устарела или подорожала (reason: quote_mismatch) — параллельный заказ съел квоту. Повторите запрос без подтверждения, получите новый 402 и новую сумму.

Разобрать этот ответ

Пример тела

{
  "success": false,
  "message": "The pay-as-you-go quote is stale — request a fresh one.",
  "reason": "quote_mismatch",
  "error_code": "quote_mismatch",
  "actual_lmc_minor": 380000000,
  "quoted_lmc_minor": 360000000
}

Поля ответа

successобязательное

Всегда false в ответах об ошибке.

boolean

messageобязательное

Текст ошибки на языке ключа (задаётся заголовком X-Locale).

string

reasonобязательное

Машиночитаемая причина отказа — по ней ветвите обработку, а не по тексту сообщения.

Значенияquote_mismatch

string

error_codeобязательное

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

Значенияquote_mismatch

string

actual_lmc_minorобязательное

Во сколько добор обходится сейчас (минимальные единицы LMC).

integer

Пример 380000000

quoted_lmc_minorобязательное

Цена, на которую вы согласились ранее (минимальные единицы LMC).

integer

Пример 360000000

422

Ошибка валидации. Сюда же попадает reason: content_blocked — фрагмент уже отклонялся контентной политикой и занесён в блоклист, и reason: paragraph_not_voiceable — в тексте есть фрагмент из одних пауз, служебных тегов или ремарок, озвучивать в нём нечего. Отдельный случай — reason: text_empty: озвучивать нечего вовсе, потому что текста в заказе нет ни одним из каналов (input_text, загруженный файл, task_data.text) либо в присланном не нашлось ни одного произносимого фрагмента. Повтор такого запроса даст тот же отказ — исправьте текст. Когда текста нет уже на входе, поле перечислено в errors и reason не приходит. Ещё один случай — reason: template_model_outdated: шаблон или config_override несут настройки прежней схемы сервиса (модель или движок, которых в текущей схеме нет), пути этих настроек — в поле fields. Тихого перевода на новую схему нет: выберите модель в шаблоне заново (PUT /templates/{template}) и повторите запрос.

Разобрать этот ответ

Пример тела

{
  "message": "string",
  "errors": {
    "key": [
      "string"
    ]
  }
}

Поля ответа

messageобязательное

Errors overview.

string

errorsобязательное

A detailed description of each field that failed validation.

object

*необязательное

произвольные ключи

array<string>

429

Превышена токен-квота ключа или исчерпаны слоты одновременных задач. Отдельный случай — reason: policy_cooldown_active: кулдаун после серии блокировок по контентной политике, время в retry_after/retry_at и в заголовке Retry-After.

Разобрать этот ответ

Пример тела

{
  "success": false,
  "message": "Too many attempts. Please wait a moment and try again.",
  "reason": "rate_limit_exceeded",
  "error_code": "rate_limit_exceeded",
  "retry_after": 30
}

Поля ответа

successобязательное

Всегда false в ответах об ошибке.

boolean

messageобязательное

Текст ошибки на языке ключа (задаётся заголовком X-Locale).

string

reasonобязательное

Машиночитаемая причина отказа — по ней ветвите обработку, а не по тексту сообщения.

string

error_codeобязательное

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

string

retry_afterнеобязательное

Через сколько секунд имеет смысл повторить запрос (то же значение — в заголовке Retry-After).

может быть null

integer

События, которые это порождает

Ход выполнения приезжает по WebSocket: опрашивать заказ в цикле не обязательно. Подписка требует того же права, что и чтение заказов.

Об этом словами

Объекты

Соседние операции

Ещё

Скормить страницу ИИ

Открыть .md llm.md

спека 0.0.1

Два способа создать заказ

Как режется текст

Разметка внутри текста (озвучка)

Ограничения размера и пауз

Что сервер меняет в тексте

Что делать после ответа

Оплата

Тело запроса

Что определяет цену

Абзацный режим озвучки

Возможные ответы

События, которые это порождает

Рядом

Скормить страницу ИИ