Retry Order
Creates a new order with the same parameters (a full retry of a finished order).
The source order must be completed or result_delivered with no failed chunks.
Settings of the new order are a snapshot of the SOURCE order: the template
configuration at the moment it was created plus the same config_override, not the
template's current state — editing or deleting the template does not affect a retry.
Orders created before late September 2026 have no snapshot and are retried with the
current template. If the saved settings no longer pass the service's current schema,
the response is 400 with reason: retry_config_outdated — create a new order with
POST /orders.
This is not the way to finish a
partially_completedorder — that status is rejected here. Finish it chunk by chunk withPOST /orders/{order}/items/{item}/retryon everypolicy_flagged/failedchunk.
Billing: this is a brand-new order with a fresh fund lock, charged to your key's
token quota (pre-check → 429 on excess, and no order is created).
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.
Request body
The body is optional. These fields are only needed to confirm a pay-as-you-go top-up
after a 402 response in the fallback mode with explicit confirmation; normally the
top-up is charged automatically.
{
"confirm_payg_topup": true,
"quote_token": "eyJ1Ijo0MiwicyI6MSwidCI6MTIwMCwibSI6MzUwMCwiZSI6MTc1NDMwMDAwMH0.9f2c…"
}Fields
Consent to a pay-as-you-go top-up for the new order — only in the fallback mode with explicit confirmation (otherwise ignored). Same semantics as POST /orders: valid only together with a fresh quote_token from a 402 response.
The top-up quote from this request's 402 response (fallback mode only). Lives about 60 seconds.
Possible responses
201A new order was created with the source order's parameters. The source order is unchanged.
A new order was created with the source order's parameters. The source order is unchanged.
{
"success": true,
"message": "Order retry created successfully.",
"data": {
"id": "d5e6f7a8-9b0c-4d1e-8f2a-3b4c5d6e7f8a",
"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-17T16:00:00+00:00",
"updated_at": "2026-07-17T16:00:00+00:00",
"eta_seconds": null,
"eta_at": null,
"completed_chunks": 0,
"total_chunks": 2,
"progress_percent": 0
}
}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 order with the same parameters — it has its own id. The original order is left untouched.
OrderOrder
A new order with the same parameters — it has its own id. The original order is left untouched.
Order UUID. Use it in /orders/{order}/… paths and when calling POST /orders/{order}/retry.
ID of the order owner. For orders created with an API key this is always the key owner — a key never sees someone else’s order.
Order name: the downloaded file name and the ZIP archive name are derived from it.
templateoptionalThe template the order was created from. Present only for orders that have a template_id; template-less orders (sfx/music created by task_type) omit it. Its config holds the settings THIS order runs with: the template configuration at the moment the order was created, with config_override applied on top; editing the template later does not change it. In the GET /orders list config is null — the full configuration comes from GET /orders/{order}. The template may have been deleted since: it is still shown here, but GET /templates/{template} returns 404 and a new order with that template_id returns 422. Orders created before this API version (late September 2026) have no snapshot: their config is the current template configuration with config_override applied, and editing the template changes it.
TemplateTemplate
The template the order was created from. Present only for orders that have a template_id; template-less orders (sfx/music created by task_type) omit it. Its config holds the settings THIS order runs with: the template configuration at the moment the order was created, with config_override applied on top; editing the template later does not change it. In the GET /orders list config is null — the full configuration comes from GET /orders/{order}. The template may have been deleted since: it is still shown here, but GET /templates/{template} returns 404 and a new order with that template_id returns 422. Orders created before this API version (late September 2026) have no snapshot: their config is the current template configuration with config_override applied, and editing the template changes it.
Template UUID. Put it into template_id when creating an order.
ID of the template owner.
Short public identifier used for sharing. null on a template that was never shared.
Template name — for humans only; it does not affect generation.
Code of the service whose schema validates config: elevenlabs, lumimg, and so on.
The template’s service for reference: name and pricing, without configuration schemas. null means no service with that code exists any more.
Generation settings: voice, model, speed and so on — the set of keys is defined by the service. Look up allowed values in GET /templates/config-options?service=<code>; anything outside the schema is rejected with 422. Inside an order (template in GET /orders/{order}) this is the order’s own settings — the snapshot taken at creation with config_override applied, not the template’s current configuration (for orders created before late September 2026 — the current template configuration with config_override).
Whether the template is published in the shared catalogue.
UUID of the folder holding the template, or null for the root. The folder tree is visible in GET /templates/browse.
When the template was created, ISO 8601.
When the template last changed, ISO 8601.
UUID of the template used, or null when the order was created without one.
Task type — it determines what goes into task_data and what comes back in result.
Current state of the order. Terminal values are completed, failed,
cancelled and compensated — there is nothing to poll for after those.
partially_completed means some chunks succeeded and some failed: the
finished files are already downloadable, and the failed fragments can be
requeued via POST /orders/{order}/items/retry-failed.
The amount locked for the order, in LMC minor units. Do not display this number as-is: the real value is price_units / 10^precision, where precision comes from the asset alongside. A display-ready value sits in the neighbouring decimal field.
The same amount as price_units, expressed in whole LMC and ready to display. null until the cost is settled.
currency_assetrequiredThe amount's asset is always LMC. Its precision is what converts minor units into the real value.
AssetAsset
The amount's asset is always LMC. Its precision is what converts minor units into the real value.
Internal identifier of the asset.
Asset code: LUMC is the internal currency, TOKEN the generation tokens.
Kind of asset: money or consumable units. It decides whether an amount counts as a payment or as quota consumption.
Number of decimal places. The load-bearing field: every integer amount in this asset is divided by 10^precision to obtain the real value. Do not assume the divisor is 100.
Display name of the asset, in the account language.
When the asset was retired, ISO 8601. null while it is in use.
When the asset was created, ISO 8601.
When the asset last changed, ISO 8601.
The order's full cost in tokens: the original chunks plus every retry and regeneration. This is a quota unit, not money.
Total length of the produced audio in milliseconds. This is the result's duration, not the time spent generating it.
The task input exactly as the server accepted it: text, references to uploaded files, resolved settings. The set of keys depends on task_type.
Execution result. files[] holds the primary files; service_files[] holds
auxiliary ones (subtitles .srt/.vtt/.lrc, alignment) for TTS orders.
Paths are absolute and ready to pass to POST /storage/url.
null while the order is unfinished, and also for a failed order: the public
surface does not expose error internals.
When the order was created, ISO 8601.
When the order last changed, ISO 8601. It advances on every status transition, which makes it a cheap “something happened” signal.
Retention of the order's files. files_expire_at is the deletion moment (null when the order has not finished yet, or the files are already gone); files_expired means nothing is left to download.
true means retention has elapsed and the files are already deleted: no link can be issued, and the order has to be created again.
retentionrequiredRetention deadlines by file level. For a stitched order the per-fragment tracks are removed earlier than the result itself.
object
Retention deadlines by file level. For a stitched order the per-fragment tracks are removed earlier than the result itself.
chunksrequiredLifetime of the per-fragment tracks — pause editing, re-stitching and per-fragment regeneration all operate on them.
object
Lifetime of the per-fragment tracks — pause editing, re-stitching and per-fragment regeneration all operate on them.
When the per-fragment tracks disappear, ISO 8601. Until then pause editing, re-stitching and per-fragment regeneration remain available. null means the order has not finished yet (the countdown has not started) or the fragments are already gone.
true means the per-fragment tracks are gone: editing and re-stitching are rejected. The finished result may still be available — check retention.files.
true means the fragments will disappear before the result (the order is stitched into a separate file). false means the fragments are the result, and both levels expire together.
Why the fragments are unavailable: chunks_purged — removed on their own schedule while the result is still there; storage_expired — every file of the order is gone. null means the fragments are available.
filesrequiredLifetime of every file of the order, including the result. Mirrors the top-level files_expire_at / files_expired fields.
object
Lifetime of every file of the order, including the result. Mirrors the top-level files_expire_at / files_expired fields.
When every file of the order will be deleted, ISO 8601. The same value as files_expire_at — the top-level field is kept for compatibility.
Same as files_expired: nothing is left to download.
Estimated time remaining, in seconds — present only while the order is running. null once it is finished, and before it starts.
Expected completion moment, ISO 8601 — the same forecast as eta_seconds, expressed as an absolute time.
How many source chunks are already finished. Retries and regenerations are excluded — counting them would push progress past 100%.
How many source chunks the order has in total. Zero means the split has not happened yet.
Completion percentage, 0–100 — derived from completed_chunks and total_chunks, so there is no need to compute it yourself.
true means the audio is being stitched and the result is not final yet. This also happens with status = completed: after a fragment is regenerated the final track is rebuilt, and until stitching ends result points to the previous track. Download the result once stitching = false.
paragraphsrequiredPer-paragraph summary: index, fragment count, aggregate status and progress. null means the order uses ordinary mode — use items[] instead. To get paragraphs, create the order with config_override.generation_mode = paragraph (see that field for details).
nullablearray<object>
Per-paragraph summary: index, fragment count, aggregate status and progress. null means the order uses ordinary mode — use items[] instead. To get paragraphs, create the order with config_override.generation_mode = paragraph (see that field for details).
Zero-based index of the paragraph.
How many chunks the paragraph was split into.
How many of the paragraph’s chunks are already finished.
Aggregate status of the paragraph: derived from its chunks’ statuses rather than stored separately. It uses its own, shorter vocabulary: pending, in_progress, failed, completed — a chunk blocked by moderation also reads as failed. Only the original chunks count, so a successful retry of a failed fragment does NOT change the paragraph status: check the fragment itself in items[].
Paragraph completion percentage, 0–100.
The whole paragraph stitched into one audio file: an absolute path, or a structure carrying path and size. Download it via POST /storage/url, same as the other order files. null means two different things depending on chunks_count: with chunks_count = 1 the paragraph has no file of its own and never will — the paragraph is that single fragment, so take its result_file from items[] under the same paragraph_index; with chunks_count > 1 the stitch has not happened yet — a multi-chunk paragraph gets its file ONLY after stitching, never in advance.
itemsoptionalThe order’s chunks. Present in the detailed GET /orders/{order} response; the list endpoint GET /orders omits the field — use GET /orders/{order}/items instead.
array<OrderItem>OrderItem
The order’s chunks. Present in the detailed GET /orders/{order} response; the list endpoint GET /orders omits the field — use GET /orders/{order}/items instead.
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.
How many of the spent tokens were covered by the subscription quota. null means the quota covered nothing.
How many tokens were paid for out of the LMC balance, beyond the quota. null means there was no top-up.
The sum of the two fields above: how many tokens were charged for the order (quota + top-up). Orders covered by an unlimited subscription and free versions are excluded — an unlimited order has null here; the generated volume is total_tokens. Retries are excluded — they are not billed again.
Position in the queue — only for voice-search tasks (voice_search), which are processed one at a time. Other task types omit the field.
Estimated wait in the voice-search queue, in seconds. An estimate, not a promise — recomputed on every response.
400Retry is not possible. Tell the cases apart by reason: invalid_order_status — the source order is not completed/result_delivered; has_failed_items — it has failed chunks; retry_config_outdated — the original generation settings (the template snapshot taken at creation plus config_override) no longer pass the service's current schema, so create a new order instead.
Retry is not possible. Tell the cases apart by reason: invalid_order_status — the source order is not completed/result_delivered; has_failed_items — it has failed chunks; retry_config_outdated — the original generation settings (the template snapshot taken at creation plus config_override) no longer pass the service's current schema, so create a new order instead.
{
"success": false,
"message": "This order contains items that failed and cannot be repeated.",
"reason": "has_failed_items",
"error_code": "has_failed_items"
}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 new order beyond the subscription quota (reason: insufficient_balance) — the same billing flow as creation. Only in the fallback mode: payg_topup_required — obtain a quote_token and repeat with confirm_payg_topup: true.
Not enough money for the new order beyond the subscription quota (reason: insufficient_balance) — the same billing flow as creation. Only in the fallback mode: payg_topup_required — obtain a quote_token and repeat with confirm_payg_topup: true.
{
"success": false,
"message": "Insufficient balance to cover the part of the order beyond the subscription quota.",
"reason": "insufficient_balance",
"error_code": "insufficient_balance"
}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 tokens the subscription quota did not cover — these are the ones paid from LMC.
Top-up cost in LMC, ready to show to the user.
The same amount in LMC minor units — for exact arithmetic without rounding loss.
The signed price quote: return it unchanged in the repeat request together with confirm_payg_topup: true.
The price is fixed until this moment. Afterwards, repeat the request to get a fresh quote.
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.
409Only in the fallback mode with explicit confirmation: the top-up quote is stale or got more expensive — request a fresh 402.
Only in the fallback mode with explicit confirmation: the top-up quote is stale or got more expensive — request a fresh 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
}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.
What the top-up costs right now (LMC minor units).
The price you agreed to earlier (LMC minor units).
422Validation error. Offending fields are listed in errors.
Validation error. Offending fields are listed in errors.
{
"message": "string",
"errors": {}
}Errors overview.
errorsrequiredA detailed description of each field that failed validation.
object
A detailed description of each field that failed validation.
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).
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
Neighbouring operations
Feed this page to an AI
spec 0.0.1