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.
On this page(5)
Parameters
The inputs live inside the request line: fill in a value and you get a ready URL. Below are the type, whether it is required and the allowed values of every parameter.
- stringin pathrequired
Order UUID — 36 characters shaped like
9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c, not a number.Take it from the
idfield:POST /ordersreturns it on creation andGET /orderslists it. Someone else’s order will not open with your key — you get a404.The value goes straight into the request line above.
- stringin pathrequired
Order chunk UUID — 36 characters; neither a number nor a position.
Take it from an item’s
idfield:GET /orders/{order}/itemsreturns the list, and the same set sits initems[]of the detailed order response. The chunk’s position is the neighbouringchunk_indexfield, which does not go into the path.The value goes straight into the request line above.
Request body
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.
{
"text": "Новая редакция фрагмента."
}Fields
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).
Possible responses
201The chunk was queued for regeneration. This is a paid operation: a fresh token quota is charged.
The chunk was queued for regeneration. This is a paid operation: a fresh token quota is charged.
{
"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 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.
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.
datarequiredA new regeneration record with its own id. The operation is paid: tokens are charged again, and the previous version stays in the history.
OrderItemOrderItem
A new regeneration record with its own id. The operation is paid: tokens are charged again, and the previous version stays in the history.
Chunk UUID. Use it in /orders/{order}/items/{item}/… paths.
UUID of the order this chunk belongs to.
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.
Zero-based position of the fragment within the order. It defines the order in which the final file is assembled.
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.
UUID of the source chunk — present on retry and regeneration records. null on an original chunk.
Length of the text the fragment was created with. It is the ceiling for text in regenerate.
Length of the fragment’s current text: after a regeneration it differs from original_text_length.
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).
How many tokens were actually charged for this fragment. Zero while the fragment is unfinished.
How many tokens are still reserved for the fragment. Drops to zero once the fragment finishes or is cancelled.
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.
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.
Duration of the produced audio in milliseconds — the length of the recording, not the generation time. null for non-audio tasks.
Attempt number for this fragment, starting at 1. It grows with every retry.
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.
Whether a paid regeneration is allowed right now. Available for finished fragments only.
When the fragment was created, ISO 8601.
When the fragment last changed, ISO 8601.
Machine-readable failure reason — present only on failed and policy_flagged. Everything else gets null.
400Any other refusal without a machine code (rare): the reason is only in message. Refusals with a reason come as 402/422/503.
Any other refusal without a machine code (rare): the reason is only in message. Refusals with a reason come as 402/422/503.
{
"success": false,
"message": "The operation could not be completed."
}Always false in error responses.
The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes.
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.
401The key is missing, unknown, disabled or expired.
The key is missing, unknown, disabled or expired.
{
"success": false,
"message": "API key is missing. Provide it in the X-API-KEY header.",
"data": null
}Always false in error responses.
Error text in the key's language (set through the X-Locale header).
Always null when the request is rejected before processing.
402Not enough money for the regeneration (reason: insufficient_balance/insufficient_allowance).
Not enough money for the regeneration (reason: insufficient_balance/insufficient_allowance).
{
"success": false,
"message": "Insufficient balance.",
"reason": "insufficient_balance",
"error_code": "insufficient_balance"
}Always false in error responses.
The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes.
Machine-readable reason of a business refusal (for example, input_expired, insufficient_balance). Branch on it, not on the message text.
The same machine-readable code as in reason — a second name for the field. The values always match.
403The key lacks the required permission, or the object belongs to another user.
The key lacks the required permission, or the object belongs to another user.
{
"success": false,
"message": "This API key does not have permission to perform this action."
}Error overview.
404Not found, or not reachable with this key.
Not found, or not reachable with this key.
{
"success": false,
"message": "Resource not found."
}Error overview.
422The 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.
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.
{
"success": true,
"message": "string",
"errors": null
}Always false in error responses.
The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes.
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.
429Limit exceeded: either the key's request rate or its token quota. Retry no earlier than Retry-After.
Limit exceeded: either the key's request rate or its token quota. Retry no earlier than 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
}Always false in error responses.
Error text in the key's language (set through the X-Locale header).
Machine-readable failure reason — branch on this, not on the message text.
The same machine-readable code as in reason — a second name for the field. The values always match; branch on either.
How many seconds to wait before retrying (the same value is in the Retry-After header).
503Work intake for the service is temporarily paused (reason: service_maintenance). Try again later.
Work intake for the service is temporarily paused (reason: service_maintenance). Try again later.
{
"success": false,
"message": "The service is temporarily unavailable due to maintenance. Please try again later.",
"reason": "service_maintenance",
"error_code": "service_maintenance"
}Always false in error responses.
The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes.
Machine-readable reason of a business refusal (for example, input_expired, insufficient_balance). Branch on it, not on the message text.
The same machine-readable code as in reason — a second name for the field. The values always match.
Events this produces
Progress arrives over WebSocket: polling the order in a loop is not required. Subscribing needs the same scope as reading orders.
Nearby
The same in words
Objects
Neighbouring operations
Feed this page to an AI
spec 0.0.1