К содержанию
Lumean API

POST/orders/{order}/items/{item}/regenerate

Перегенерирует завершённый (completed) элемент заказа с новым текстом.

orders.writeасинхронный402 PAYG429 лимиты

Биллинг: платная операция — блокирует НОВЫЕ средства. Стоимость учитывается в токен-квоте ключа (pre-check до загрузки текста → 429 при превышении, перегенерация не выполняется; запись фактического объёма — после успеха).

Поле text обязательно. Предел длины — ёмкость фрагмента (max_billable_length из GET .../items/{item}/text); длиннее — 422 с reason: text_over_capacity. Стоимость считается по всей новой длине. Бесплатны и места не занимают только наши паузы {{pause=2s}}; <break .../> и указания диктору в […] ([шёпот]) — синтаксис провайдера: они тарифицируются и входят в лимит (llm.md §8.3). В отличие от retry, regenerate применим только к уже завершённому (completed) чанку и стоит новых токенов.

Требуемое право ключа: orders.write. Недоступно для sfx/music.

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

Параметры

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

POSThttps://api.lumean.app/api/public/orders//items//regenerate
  • stringв путиобязательный

    UUID заказа — 36 символов вида 9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c, не число.

    Берётся из поля id: его возвращает POST /orders при создании и GET /orders в списке. Чужой заказ по вашему ключу не откроется — придёт 404.

    Значение подставляется прямо в строку запроса выше.

  • stringв путиобязательный

    UUID фрагмента заказа (чанка) — 36 символов, не число и не порядковый номер.

    Берётся из поля id элемента: GET /orders/{order}/items отдаёт список, тот же набор лежит в items[] детального ответа заказа. Порядковый номер фрагмента — это соседнее поле chunk_index, в путь оно НЕ подставляется.

    Значение подставляется прямо в строку запроса выше.

Тело запроса

application/jsonобязательно

Переделка уже завершённого фрагмента новым текстом. Операция платная — токены списываются как за новую генерацию.

text обязателен. Предел длины — ёмкость фрагмента (max_billable_length из GET …/items/{item}/text); длиннее — 422 с reason: text_over_capacity. Стоимость считается по всей новой длине. Бесплатны только наши паузы {{pause=2s}}: <break/> и любые указания диктору в квадратных скобках ([шёпот], но и [1], [sic]) — синтаксис провайдера, они тарифицируются и занимают место во фрагменте.

Новый текст фрагмента
{
  "text": "Новая редакция фрагмента."
}

Поля

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

Новый текст готового чанка — обязателен. Переделка уже выполненного фрагмента тарифицируется как новая генерация (проверка токен-квоты ключа → 429 при превышении).

≤ 50000 симв.
string
Пример Новая редакция фрагмента.

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

201

Чанк отправлен на переделку. Операция платная: списывается новая токен-квота.

Пример тела
{
  "success": true,
  "message": "Order item regeneration created successfully.",
  "data": {
    "id": "b0c1d2e3-4f5a-4b6c-8d7e-8f9a0b1c2d3e",
    "order_id": "9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c",
    "item_type": "regeneration",
    "chunk_index": 0,
    "parent_item_id": "d4e5f6a7-8b9c-4d0e-8f1a-2b3c4d5e6f7a",
    "original_text_length": 210,
    "current_text_length": 210,
    "price_units": 210,
    "consumed_units": 0,
    "remaining_locked": 210,
    "status": "pending",
    "result_file": null,
    "attempt_number": 1,
    "can_retry": false,
    "can_regenerate": false,
    "created_at": "2026-07-17T14:10:00+00:00",
    "updated_at": "2026-07-17T14:10:00+00:00"
  }
}
Поля ответа
successобязательное

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

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

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

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

Новая запись перегенерации со своим id. Операция платная: токены списываются заново, прежняя версия фрагмента остаётся в истории.

OrderItemOrderItem
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
400

Прочий отказ без машинного кода (редко): причина — только в message. Отказы с reason приходят кодами 402/422/503.

Пример тела
{
  "success": false,
  "message": "The operation could not be completed."
}
Поля ответа
successобязательное

Всегда false у ошибок.

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

Причина отказа словами, на языке аккаунта. Для показа пользователю; ветвиться по ней нельзя — формулировки меняются.

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

Разбор по полям — только у ошибок валидации (422): ключ соответствует полю запроса, значение — список претензий к нему. У остальных кодов приходит null: разбирать нечего, причина целиком в message.

может быть null
null
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).

Разобрать этот ответ
Пример тела
{
  "success": false,
  "message": "Insufficient balance.",
  "reason": "insufficient_balance",
  "error_code": "insufficient_balance"
}
Поля ответа
successобязательное

Всегда false у ошибок.

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

Причина отказа словами, на языке аккаунта. Для показа пользователю; ветвиться по ней нельзя — формулировки меняются.

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

Машиночитаемая причина бизнес-отказа (например, input_expired, insufficient_balance). Ветвите обработку по ней, а не по тексту message.

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

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

string
403

Нет доступа к заказу, у ключа нет права orders.write, либо нет подписки на сервис (reason: no_subscription)

Разобрать этот ответ
Пример тела
{
  "success": false,
  "message": "This API key does not have permission to perform this action."
}
Поля ответа
messageобязательное

Error overview.

string
404

Заказ или элемент не найден

Разобрать этот ответ
Пример тела
{
  "success": false,
  "message": "Resource not found."
}
Поля ответа
messageобязательное

Error overview.

string
422

Не передан обязательный text либо переделка невозможна (reason): invalid_status — чанк не completed, text_over_capacity, text_not_voiceable, content_blocked, generative_not_supported (sfx/music), retry_config_outdated — настройки заказа не проходят текущую схему сервиса, создайте новый заказ.

Разобрать этот ответ
Пример тела
{
  "success": true,
  "message": "string",
  "errors": null
}
Поля ответа
successобязательное

Всегда false у ошибок.

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

Причина отказа словами, на языке аккаунта. Для показа пользователю; ветвиться по ней нельзя — формулировки меняются.

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

Разбор по полям — только у ошибок валидации (422): ключ соответствует полю запроса, значение — список претензий к нему. У остальных кодов приходит null: разбирать нечего, причина целиком в message.

может быть null
null
429

Превышена токен-квота ключа

Разобрать этот ответ
Пример тела
{
  "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
503

Приём работы на сервис временно приостановлен (reason: service_maintenance). Повторите позже.

Пример тела
{
  "success": false,
  "message": "The service is temporarily unavailable due to maintenance. Please try again later.",
  "reason": "service_maintenance",
  "error_code": "service_maintenance"
}
Поля ответа
successобязательное

Всегда false у ошибок.

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

Причина отказа словами, на языке аккаунта. Для показа пользователю; ветвиться по ней нельзя — формулировки меняются.

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

Машиночитаемая причина бизнес-отказа (например, input_expired, insufficient_balance). Ветвите обработку по ней, а не по тексту message.

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

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

string

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

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

Рядом

Объекты

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

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

Открыть .mdllm.md

спека 0.0.1