---
title: "POST /orders/{order}/items/{item}/regenerate — Regenerate Order Item"
url: https://lumean.app/developers/docs/api/post-orders-order-items-item-regenerate
locale: ru
description: "Regenerate Order Item"
generated: 2026-10-17
operationId: orderItem.regenerate
method: POST
path: "/orders/{order}/items/{item}/regenerate"
scopes: [orders.write]
spec_version: 0.0.1
---

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

**Regenerate Order Item**

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

**Биллинг:** платная операция — блокирует НОВЫЕ средства. Стоимость учитывается
в токен-квоте ключа (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`.

- Право ключа: `orders.write`

## Запрос

```bash
curl -X POST 'https://api.lumean.app/api/public/orders/{order}/items/{item}/regenerate' \
  -H 'Accept: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "text": "Новая редакция фрагмента."
}'
```

## Параметры

| Поле | Где | Тип | Обяз. | Описание |
| --- | --- | --- | --- | --- |
| `order` | path | `string` | обяз. | UUID заказа — 36 символов вида `9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c`, не число. Берётся из поля `id`: его возвращает `POST /orders` при создании и `GET /orders` в списке. Чужой заказ по вашему ключу не откроется — придёт `404`. default: `9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c` |
| `item` | path | `string` | обяз. | UUID фрагмента заказа (чанка) — 36 символов, не число и не порядковый номер. Берётся из поля `id` элемента: `GET /orders/{order}/items` отдаёт список, тот же набор лежит в `items[]` детального ответа заказа. Порядковый номер фрагмента — это соседнее поле `chunk_index`, в путь оно НЕ подставляется. default: `2b7d1e60-5a44-4a1e-9f3c-7c0d9e8a1b23` |

## Тело запроса

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

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

Content-Type: `application/json`

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

**Пример**

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

## Сценарии тела

### Новый текст фрагмента

Переделка уже готового чанка. Тарифицируется как новая генерация.

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

## Ответы

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

**Поля ответа**

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `success` | `boolean` | обяз. | Признак успеха. Решение принимайте по HTTP-коду: у любого ответа 2xx здесь `true`, а ошибка приходит телом другой формы, где этого поля может не быть вовсе. |
| `message` | `string` | обяз. | Пояснение для человека, на языке аккаунта. Показать пользователю можно; разбирать программно — нет: формулировки меняются без предупреждения и кодом ошибки не являются. |
| `data` | `OrderItem` | обяз. | Новая запись перегенерации со своим `id`. Операция платная: токены списываются заново, прежняя версия фрагмента остаётся в истории. |
| `data.id` | `string` | обяз. | UUID чанка. Подставляется в пути `/orders/{order}/items/{item}/…`. |
| `data.order_id` | `string` | обяз. | UUID заказа, которому принадлежит чанк. |
| `data.item_type` | `string` | обяз. | Природа записи: `chunk` — исходный фрагмент, `retry` — бесплатный повтор упавшего фрагмента, `regeneration` — платная переделка готового. Повторы и перегенерации живут отдельными записями с тем же `chunk_index`: история попыток сохраняется целиком, а звучит в результате последняя. |
| `data.chunk_index` | `integer` — nullable | обяз. | Порядковый номер фрагмента в заказе, с нуля. Задаёт порядок склейки итогового файла. |
| `data.paragraph_index` | `string` | обяз. | Номер абзаца, к которому относится фрагмент, — заполняется только у исходных фрагментов абзацного заказа. `null` и в обычном режиме, и у записей повтора либо перегенерации: у них своей привязки к абзацу нет, её берут у родительского фрагмента через `parent_item_id`. Режим включается ключом `generation_mode` в `config_override` заказа. |
| `data.parent_item_id` | `string` | обяз. | UUID исходного чанка — у записей `retry` и `regeneration`. У самого исходного чанка `null`. |
| `data.original_text_length` | `integer` | обяз. | Длина текста, с которой фрагмент создавался. Служит потолком для `text` в `regenerate`. |
| `data.current_text_length` | `integer` | обяз. | Длина актуального текста фрагмента: после перегенерации отличается от `original_text_length`. |
| `data.price_units` | `integer` | обяз. | Стоимость фрагмента в **токенах** — это не деньги. Денежная сумма лежит у самого заказа, в его поле `price_units` (там LMC, здесь токены; поля называются одинаково, единицы разные). |
| `data.consumed_units` | `integer` | обяз. | Сколько токенов фактически списано по этому фрагменту. У незавершённого фрагмента — 0. |
| `data.remaining_locked` | `integer` | обяз. | Сколько токенов ещё зарезервировано под фрагмент. Обнуляется, когда фрагмент завершается или отменяется. |
| `data.status` | `string` | обяз. | Состояние фрагмента: `pending` — ждёт воркера, `processing` — в работе, `completed` — готов, `failed` — техническая ошибка, `policy_flagged` — отклонён контентной политикой. Разница между двумя последними определяет способ лечения: `failed` чинится повтором как есть, `policy_flagged` — только переформулировкой текста, повтор с прежним будет отклонён снова. |
| `data.result_file` | `object \| string \| null` — nullable | обяз. | Файл готового фрагмента: абсолютный путь либо структура с путём и размером. Скачивается через `POST /storage/url`, как и файлы заказа. `null`, пока фрагмент не готов. |
| `data.duration_ms` | `integer` — nullable | обяз. | Длительность полученного аудио в миллисекундах — длина записи, а не время генерации. У не-аудио задач `null`. |
| `data.attempt_number` | `integer` | обяз. | Номер попытки для этого фрагмента, начиная с 1. Растёт с каждым повтором. |
| `data.can_retry` | `boolean` | обяз. | Разрешён ли бесплатный повтор прямо сейчас. Учитывает статус, тип задачи и исчерпание попыток — проверять условия самому не нужно. |
| `data.can_regenerate` | `boolean` | обяз. | Разрешена ли платная перегенерация прямо сейчас. Доступна только для завершённых фрагментов. |
| `data.created_at` | `string` — date-time — nullable | обяз. | Когда фрагмент создан, ISO 8601. |
| `data.updated_at` | `string` — date-time — nullable | обяз. | Когда фрагмент последний раз менялся, ISO 8601. |
| `data.failure_reason` | `string` — nullable | — | Причина падения в машиночитаемом виде — есть только у `failed` и `policy_flagged`. Остальным приходит `null`. |

**Пример**

```json
{
  "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"
  }
}
```

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

**Поля ответа**

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `success` | `boolean` | обяз. | Всегда `false` у ошибок. |
| `message` | `string` | обяз. | Причина отказа словами, на языке аккаунта. Для показа пользователю; ветвиться по ней нельзя — формулировки меняются. |
| `errors` | `null` — nullable | обяз. | Разбор по полям — только у ошибок валидации (`422`): ключ соответствует полю запроса, значение — список претензий к нему. У остальных кодов приходит `null`: разбирать нечего, причина целиком в `message`. |

**Пример**

```json
{
  "success": false,
  "message": "The operation could not be completed."
}
```

### 401 — Не авторизован (отсутствует/невалидный X-API-KEY)

**Поля ответа**

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `success` | `boolean` | обяз. | Всегда `false` в ответах об ошибке. |
| `message` | `string` | обяз. | Текст ошибки на языке ключа (задаётся заголовком `X-Locale`). |
| `data` | `null` — nullable | обяз. | Всегда `null`, когда запрос отклонён до обработки. |

**Пример**

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

### 402 — Не хватает средств на перегенерацию (`reason: insufficient_balance`/`insufficient_allowance`).

**Поля ответа**

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `success` | `boolean` | обяз. | Всегда `false` у ошибок. |
| `message` | `string` | обяз. | Причина отказа словами, на языке аккаунта. Для показа пользователю; ветвиться по ней нельзя — формулировки меняются. |
| `reason` | `string` | обяз. | Машиночитаемая причина бизнес-отказа (например, `input_expired`, `insufficient_balance`). Ветвите обработку по ней, а не по тексту `message`. |
| `error_code` | `string` | обяз. | Тот же машинный код, что в `reason`, — второе имя поля. Значения всегда совпадают. |

**Пример**

```json
{
  "success": false,
  "message": "Insufficient balance.",
  "reason": "insufficient_balance",
  "error_code": "insufficient_balance"
}
```

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

**Поля ответа**

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `message` | `string` | обяз. | Error overview. |

**Пример**

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

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

**Поля ответа**

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `message` | `string` | обяз. | Error overview. |

**Пример**

```json
{
  "success": false,
  "message": "Resource not found."
}
```

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

**Поля ответа**

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `success` | `boolean` | обяз. | Всегда `false` у ошибок. |
| `message` | `string` | обяз. | Причина отказа словами, на языке аккаунта. Для показа пользователю; ветвиться по ней нельзя — формулировки меняются. |
| `errors` | `null` — nullable | обяз. | Разбор по полям — только у ошибок валидации (`422`): ключ соответствует полю запроса, значение — список претензий к нему. У остальных кодов приходит `null`: разбирать нечего, причина целиком в `message`. |

**Пример**

```json
{
  "success": true,
  "message": "string",
  "errors": null
}
```

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

**Поля ответа**

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `success` | `boolean` | обяз. | Всегда `false` в ответах об ошибке. |
| `message` | `string` | обяз. | Текст ошибки на языке ключа (задаётся заголовком `X-Locale`). |
| `reason` | `string` | обяз. | Машиночитаемая причина отказа — по ней ветвите обработку, а не по тексту сообщения. |
| `error_code` | `string` | обяз. | Тот же машинный код, что в `reason`, — второе имя поля. Значения всегда совпадают; ветвитесь по любому из них. |
| `retry_after` | `integer` — nullable | — | Через сколько секунд имеет смысл повторить запрос (то же значение — в заголовке `Retry-After`). |

**Пример**

```json
{
  "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
}
```

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

**Поля ответа**

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `success` | `boolean` | обяз. | Всегда `false` у ошибок. |
| `message` | `string` | обяз. | Причина отказа словами, на языке аккаунта. Для показа пользователю; ветвиться по ней нельзя — формулировки меняются. |
| `reason` | `string` | обяз. | Машиночитаемая причина бизнес-отказа (например, `input_expired`, `insufficient_balance`). Ветвите обработку по ней, а не по тексту `message`. |
| `error_code` | `string` | обяз. | Тот же машинный код, что в `reason`, — второе имя поля. Значения всегда совпадают. |

**Пример**

```json
{
  "success": false,
  "message": "The service is temporarily unavailable due to maintenance. Please try again later.",
  "reason": "service_maintenance",
  "error_code": "service_maintenance"
}
```

---

- Эта же страница в браузере: https://lumean.app/developers/docs/api/post-orders-order-items-item-regenerate
- Машинный справочник целиком: https://api.lumean.app/docs/llm.md