---
title: "POST /orders/{order}/items/{item}/regenerate — Regenerate Order Item"
url: https://lumean.app/tr/developers/docs/api/post-orders-order-items-item-regenerate
locale: tr
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**

Regenerates an already **completed** chunk with new text — the way to fix a typo
without redoing the whole order.

**Paid:** this is a new generation. Your key's token quota is checked first (`429` on
excess). Do not confuse it with `retry`, which is free and applies to failed chunks.

Not available for `sfx`/`music`.

**Required key permission:** `orders.write`.

- Gerekli izin: `orders.write`

## İstek

```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": "Новая редакция фрагмента."
}'
```

## Parametreler

| Alan | Yer | Tür | Zor. | Açıklama |
| --- | --- | --- | --- | --- |
| `order` | path | `string` | zorunlu | Order UUID — 36 characters shaped like `9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c`, not a number. Take it from the `id` field: `POST /orders` returns it on creation and `GET /orders` lists it. Someone else’s order will not open with your key — you get a `404`. default: `9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c` |
| `item` | path | `string` | zorunlu | Order chunk UUID — 36 characters; neither a number nor a position. Take it from an item’s `id` field: `GET /orders/{order}/items` returns the list, and the same set sits in `items[]` of the detailed order response. The chunk’s position is the neighbouring `chunk_index` field, which does **not** go into the path. default: `2b7d1e60-5a44-4a1e-9f3c-7c0d9e8a1b23` |

## İstek gövdesi

Redoing an already finished fragment with new text. The operation is **paid** — tokens
are charged as for a fresh generation.

`text` is required. The length ceiling is the fragment capacity (`max_billable_length`
from `GET …/items/{item}/text`); a longer text gets `422` with
`reason: text_over_capacity`. The price is based on the whole new length. Only our own
pauses `{{pause=2s}}` are free: `<break/>` and any narrator direction in square
brackets (`[whisper]`, but also `[1]`, `[sic]`) are the provider’s syntax — they are
billed and take room in the fragment.

Content-Type: `application/json`

| Alan | Tür | Zor. | Açıklama |
| --- | --- | --- | --- |
| `text` | `string` — ≤ 50000 karakter | zorunlu | New text for a completed chunk — **required**. Regenerating an already finished fragment is billed as a new generation (the key's token quota is checked first, `429` on excess). |

**Örnek**

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

## Gövde senaryoları

### New fragment text

Regenerates an already completed chunk. Billed as a new generation.

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

## Yanıtlar

### 201 — The chunk was queued for regeneration. This is a paid operation: a fresh token quota is charged.

**Yanıt alanları**

| Alan | Tür | Zor. | Açıklama |
| --- | --- | --- | --- |
| `success` | `boolean` | zorunlu | Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all. |
| `message` | `string` | zorunlu | A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code. |
| `data` | `OrderItem` | zorunlu | A new regeneration record with its own `id`. The operation is paid: tokens are charged again, and the previous version stays in the history. |
| `data.id` | `string` | zorunlu | Chunk UUID. Use it in `/orders/{order}/items/{item}/…` paths. |
| `data.order_id` | `string` | zorunlu | UUID of the order this chunk belongs to. |
| `data.item_type` | `string` | zorunlu | What the record is: `chunk` is an original fragment, `retry` a free re-run of a failed one, `regeneration` a paid redo of a finished one. Retries and regenerations are separate records sharing the same `chunk_index`: the full attempt history is kept, and the last one is what the result plays. |
| `data.chunk_index` | `integer` — nullable | zorunlu | Zero-based position of the fragment within the order. It defines the order in which the final file is assembled. |
| `data.paragraph_index` | `string` | zorunlu | The paragraph this fragment belongs to — filled in only for the original fragments of a paragraph-mode order. It is `null` both in ordinary mode and on retry or regeneration records: those carry no paragraph link of their own and inherit it from the parent fragment via `parent_item_id`. The mode is switched on by the `generation_mode` key in the order's `config_override`. |
| `data.parent_item_id` | `string` | zorunlu | UUID of the source chunk — present on `retry` and `regeneration` records. `null` on an original chunk. |
| `data.original_text_length` | `integer` | zorunlu | Length of the text the fragment was created with. It is the ceiling for `text` in `regenerate`. |
| `data.current_text_length` | `integer` | zorunlu | Length of the fragment’s current text: after a regeneration it differs from `original_text_length`. |
| `data.price_units` | `integer` | zorunlu | Cost of the fragment in **tokens** — not money. The monetary amount lives on the order itself, in its own `price_units` field (LMC there, tokens here; the names match, the units do not). |
| `data.consumed_units` | `integer` | zorunlu | How many tokens were actually charged for this fragment. Zero while the fragment is unfinished. |
| `data.remaining_locked` | `integer` | zorunlu | How many tokens are still reserved for the fragment. Drops to zero once the fragment finishes or is cancelled. |
| `data.status` | `string` | zorunlu | Fragment state: `pending` waits for a worker, `processing` is in flight, `completed` is done, `failed` hit a technical error, and `policy_flagged` was rejected by the content policy. The difference between the last two dictates the fix: `failed` is cured by retrying as is, whereas `policy_flagged` requires rewording — retrying the same text is rejected again. |
| `data.result_file` | `object \| string \| null` — nullable | zorunlu | The finished fragment’s file: an absolute path, or a structure carrying path and size. Download it via `POST /storage/url`, same as order files. `null` until the fragment is ready. |
| `data.duration_ms` | `integer` — nullable | zorunlu | Duration of the produced audio in milliseconds — the length of the recording, not the generation time. `null` for non-audio tasks. |
| `data.attempt_number` | `integer` | zorunlu | Attempt number for this fragment, starting at 1. It grows with every retry. |
| `data.can_retry` | `boolean` | zorunlu | Whether a free retry is allowed right now. It already accounts for status, task type and exhausted attempts, so you need not re-check the conditions. |
| `data.can_regenerate` | `boolean` | zorunlu | Whether a paid regeneration is allowed right now. Available for finished fragments only. |
| `data.created_at` | `string` — date-time — nullable | zorunlu | When the fragment was created, ISO 8601. |
| `data.updated_at` | `string` — date-time — nullable | zorunlu | When the fragment last changed, ISO 8601. |
| `data.failure_reason` | `string` — nullable | — | Machine-readable failure reason — present only on `failed` and `policy_flagged`. Everything else gets `null`. |

**Örnek**

```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 — Any other refusal without a machine code (rare): the reason is only in `message`. Refusals with a `reason` come as 402/422/503.

**Yanıt alanları**

| Alan | Tür | Zor. | Açıklama |
| --- | --- | --- | --- |
| `success` | `boolean` | zorunlu | Always `false` in error responses. |
| `message` | `string` | zorunlu | The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes. |
| `errors` | `null` — nullable | zorunlu | A per-field breakdown — present only on validation errors (`422`): the key names a request field, the value lists the complaints about it. Other codes send `null`, since there is nothing to break down and the whole reason is in `message`. |

**Örnek**

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

### 401 — The key is missing, unknown, disabled or expired.

**Yanıt alanları**

| Alan | Tür | Zor. | Açıklama |
| --- | --- | --- | --- |
| `success` | `boolean` | zorunlu | Always `false` in error responses. |
| `message` | `string` | zorunlu | Error text in the key's language (set through the `X-Locale` header). |
| `data` | `null` — nullable | zorunlu | Always `null` when the request is rejected before processing. |

**Örnek**

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

### 402 — Not enough money for the regeneration (`reason: insufficient_balance`/`insufficient_allowance`).

**Yanıt alanları**

| Alan | Tür | Zor. | Açıklama |
| --- | --- | --- | --- |
| `success` | `boolean` | zorunlu | Always `false` in error responses. |
| `message` | `string` | zorunlu | The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes. |
| `reason` | `string` | zorunlu | Machine-readable reason of a business refusal (for example, `input_expired`, `insufficient_balance`). Branch on it, not on the `message` text. |
| `error_code` | `string` | zorunlu | The same machine-readable code as in `reason` — a second name for the field. The values always match. |

**Örnek**

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

### 403 — The key lacks the required permission, or the object belongs to another user.

**Yanıt alanları**

| Alan | Tür | Zor. | Açıklama |
| --- | --- | --- | --- |
| `message` | `string` | zorunlu | Error overview. |

**Örnek**

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

### 404 — Not found, or not reachable with this key.

**Yanıt alanları**

| Alan | Tür | Zor. | Açıklama |
| --- | --- | --- | --- |
| `message` | `string` | zorunlu | Error overview. |

**Örnek**

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

### 422 — The required `text` field is missing, or regeneration is not possible (`reason`): `invalid_status` — the chunk is not `completed`, `text_over_capacity`, `text_not_voiceable`, `content_blocked`, `generative_not_supported` (`sfx`/`music`), `retry_config_outdated` — the order's settings no longer pass the service's current schema, create a new order.

**Yanıt alanları**

| Alan | Tür | Zor. | Açıklama |
| --- | --- | --- | --- |
| `success` | `boolean` | zorunlu | Always `false` in error responses. |
| `message` | `string` | zorunlu | The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes. |
| `errors` | `null` — nullable | zorunlu | A per-field breakdown — present only on validation errors (`422`): the key names a request field, the value lists the complaints about it. Other codes send `null`, since there is nothing to break down and the whole reason is in `message`. |

**Örnek**

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

### 429 — Limit exceeded: either the key's request rate or its token quota. Retry no earlier than `Retry-After`.

**Yanıt alanları**

| Alan | Tür | Zor. | Açıklama |
| --- | --- | --- | --- |
| `success` | `boolean` | zorunlu | Always `false` in error responses. |
| `message` | `string` | zorunlu | Error text in the key's language (set through the `X-Locale` header). |
| `reason` | `string` | zorunlu | Machine-readable failure reason — branch on this, not on the message text. |
| `error_code` | `string` | zorunlu | The same machine-readable code as in `reason` — a second name for the field. The values always match; branch on either. |
| `retry_after` | `integer` — nullable | — | How many seconds to wait before retrying (the same value is in the `Retry-After` header). |

**Örnek**

```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 — Work intake for the service is temporarily paused (`reason: service_maintenance`). Try again later.

**Yanıt alanları**

| Alan | Tür | Zor. | Açıklama |
| --- | --- | --- | --- |
| `success` | `boolean` | zorunlu | Always `false` in error responses. |
| `message` | `string` | zorunlu | The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes. |
| `reason` | `string` | zorunlu | Machine-readable reason of a business refusal (for example, `input_expired`, `insufficient_balance`). Branch on it, not on the `message` text. |
| `error_code` | `string` | zorunlu | The same machine-readable code as in `reason` — a second name for the field. The values always match. |

**Örnek**

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

---

- Bu sayfa tarayıcıda: https://lumean.app/tr/developers/docs/api/post-orders-order-items-item-regenerate
- Makine tarafından okunabilir tam başvuru: https://api.lumean.app/docs/llm.md