Skip to content
Lumean
POST/orders

Create Order

Creates a generation order on behalf of the key owner and queues it immediately. The response comes back at once with status created/pending — it does not contain the result yet.

Two ways to create an order

From a template — template_id + input_text. The template carries the service, task type, voice and every setting; the order only supplies the text. To deviate from the template just once, use config_override instead of creating a new template.

Without a template — task_type + task_data. This is how sfx and music work (the whole prompt and its parameters live in task_data), along with voice_search (the audio clip goes into input_files). tts requires a template, because that is where the voice and model are chosen.

One of the two fields (template_id or task_type) is required. Every field is documented, with ready-made examples, under the Body tab.

How the text is cut

By default the text is cut into fragments back to back, by technical size: paragraph boundaries play no part. Paragraph mode splits the text on blank lines first, and a paragraph becomes a unit of generation in its own right — the response then carries paragraphs[], and fragments carry paragraph_index.

It is switched on by the generation_mode key inside config_override (there is a ready example under the Body tab, “TTS by paragraphs”). Note that in this mode the minimum billable volume is counted per paragraph. Full details are on the config_override field.

Markup inside the text (speech)

Exactly three kinds of markup are recognised, and only one of them is free — our own {{…}} pause:

KindExampleWhat it doesBilled
Pause{{pause=2.5}}, {{pause:500ms}}, {{pause}}Silence of the given length; with no value, one secondNo
SSML pause<break time="2s"/>, <break time="500ms"/>The same thing in SSML notationYes
Direction to the narrator[whisper], [soft voice]A hint to the model about deliveryYes

{{…}} is our own format: the server builds the silence itself and the string never reaches the speech provider, so it is not billed and takes no room in a fragment. <break/> and […] are the provider’s own syntax: the provider receives them as they are, so they are billed as characters and take room in a fragment (a 999-character fragment with [confident] inside holds 988 spoken characters).

Square brackets are the whole of the markup, not a list of keywords. Any […] span without a line break inside counts as a direction to the narrator. A footnote [1], an editorial [sic], a timecode [00:12], a reference [fig. 3] — the model takes them for directions instead of reading them out. If square brackets are meant to be heard, replace them.

The flip side: round brackets, angle brackets, asterisks and other typography are spoken and billed. Stage directions such as (pause), <Fade out> or *whispering* will be read aloud — strip them yourself, or convert them to […].

Limits on pauses

Checked before the order is created; exceeding one gives 422 and reserves no money:

LimitValue
Pauses in the textat most 500
A single pauseat most 10 seconds
Total silenceat most 3600 seconds

Only pauses count; narrator directions in […] fall outside these limits.

A separate rejection awaits text that has nothing speakable left once the markup is stripped: only tags, only punctuation (..., !!!, —), or only bracketed stage directions. Such an order is not created.

What the server changes in the text

Before it is cut up, the text is normalised — the stored order and every fragment offset are computed against the changed text:

WhatHow
Line breaks\r\n and \r become \n
TabsReplaced with a space
More than 3 consecutive line breaksCollapsed to 3
More than 5 consecutive spacesCollapsed to 5
Hey.today (speech only)A space after ., !, ? before a letter or digit → Hey. today

That last rule leaves decimals (3.14), abbreviations (Mr.), acronyms (U.S.A.), URLs with a scheme, email addresses, ellipses and the contents of markup tags alone. A bare domain with no scheme (example.com mid-sentence) is indistinguishable from Hey.today and will get the space — write such addresses with a scheme.

What to do with the response

  1. Keep the order id.
  2. Wait for completion: subscribe to the WebSocket channel private-order.task.{orderId} (no polling) or poll GET /orders/{order}.
  3. Terminal statuses: completed, result_delivered, failed, compensated, cancelled. partially_completed is separate — some chunks failed and are waiting for your decision (see POST /orders/{order}/items/{item}/retry).
  4. Result files arrive in result.files[]; POST /storage/url turns a path into a download link.

Payment

Subscription quota is spent first, and only the remainder is charged to the LMC balance: when the quota falls short, the top-up is charged automatically and the order is created right away (201). Not enough money for the top-up gives 402 insufficient_balance. The confirm_payg_topup and quote_token fields only matter in the fallback mode with explicit confirmation (enabled by the platform operator: the order is then not created and you get 402 payg_topup_required with the top-up amount) — details are on the confirm_payg_topup field itself.

The cost also counts against your key's token quota. That check runs before the order is created: on excess you get 429, no order is created and no files are stored.

Provenance (source=api, api_key_id) is filled in by the server — do not send it.

Required key permission: orders.write.

Parameters

Values go straight into the request line, and the URL is built for you. Below are each parameter’s type, whether it is required, and its allowed values.

POSThttps://api.lumean.app/api/public/orders

    Request body

    multipart/form-dataapplication/json

    An order is created in one of two ways: from a template (template_id + input_text) or without one (task_type + task_data). Pick a ready-made example below — it drops straight into the editor.

    TTS from a template
    {
      "template_id": "4d3e9f8b-2c1a-4f5a-8b9c-0d1e2f3a4b5c",
      "input_text": "Hello! Glad to see you at Lumean.",
      "name": "Landing page greeting"
    }

    Fields

    template_idoptional

    Template UUID — it determines the service, the task type and every generation setting. Either template_id or task_type is required; if both are sent, the template wins.

    Templates are the usual way to work: settings are defined once, and the order only carries the text. To deviate from them just once, use config_override.

    nullableuuid
    string
    Example 4d3e9f8b-2c1a-4f5a-8b9c-0d1e2f3a4b5c
    task_typeoptional

    Task type for generation without a template. Required when template_id is not sent.

    ValueWhat it doesWhere the parameters go
    sfxA sound effect from a text descriptiontask_data
    musicA music track from a descriptiontask_data
    voice_searchFinding voices similar to your audio clipinput_files (audio) + task_data.top

    tts requires a template — that is where the voice and model live.

    nullable
    Valuesttsimagetxt2imgremiximage_editvoice_clonesfxmusicvoice_search
    string
    Example sfx
    nameoptional

    Human-readable order name: it becomes the name of the downloaded file and of the ZIP archive.

    If omitted, the server derives one, in this order: the uploaded file's name without its extension → the first ~60 characters of the text on a word boundary (pause tags {{pause=…}} are stripped).

    nullable≤ 120 chars
    string
    Example Landing page greeting
    task_dataoptional

    Generation parameters for a template-less order — a one-off "temporary template". A JSON object; multipart clients may send it as a single JSON string.

    Put the keys at the root of the object, with no wrapper. GET /templates/config-options shows the same parameters grouped into a section (sfx_settings, music_settings) — that is the shape of a settings UI, not the shape of a request. Sending {"sfx_settings": {"text": "…"}} returns 422 "text is required": the wrapper hid the key.

    SFX (task_type: "sfx") — one generation yields exactly one file:

    KeyTypeDefaultPurpose
    textstring, required—Description of the sound; English prompts work best
    prompt_influencenumber 0..10.3How strictly to follow the prompt
    duration_secondsnumber 0.5..30nullnull = automatic length
    loopbooleanfalseSeamless looping
    output_formatmp3_44100_128 | mp3_44100_192 | opus_48000_128mp3_44100_128Output format

    Music (task_type: "music") — n_variants generations yield that many files:

    KeyTypeDefaultPurpose
    promptstring, required—Description of the track: genre, mood, instruments
    n_variantsinteger 1..41How many variants to generate. Multiplies the price and yields the same number of files in result.files[]
    lyrics_textstringnullSong lyrics; if empty and force_instrumental is off, the model may add vocals on its own
    force_instrumentalbooleanfalseInstrumental only, no vocals
    music_length_msinteger 10000..3000030000Track length in milliseconds: 10–30 s at most, above 30000 → 422
    model_idmusic_v2music_v2Currently the only value

    Voice Search (task_type: "voice_search") — the audio clip travels in input_files; only one parameter lives here:

    KeyTypeDefaultPurpose
    topinteger 1..5010How many similar voices to return

    What drives the price

    What counts is the number of generations, not their size:

    TypePriceDoes NOT affect the price
    sfxOne service rate per orderduration_seconds, the length of text
    musicRate × n_variantsmusic_length_ms, the length of prompt, lyrics_text
    voice_searchOne rate per orderClip duration, top

    A five-minute track costs exactly what a ten-second one costs — you pay per call to the model. What was actually charged comes back in the order's price_units.

    The server merges the service's default_config underneath your values (yours win) — switch that off with skip_service_defaults. A value outside its range or enum returns 422 before billing: no order is created and no funds are reserved.

    object
    Example {"text":"A heavy wooden door creaks and slams shut","duration_seconds":4}
    config_overrideoptional

    A one-off deviation from the template's settings — the only way to change parameters for a single order without creating a new template. The shape is the same JSON object as the template's config, applied on top of it for this order only.

    For example, to narrate one order with a different voice: {"tts_settings": {"voice_id": "<OTHER_VOICE_ID>"}} — the rest of the template survives.

    Paths absent from the service schema are silently dropped (a typo in a key looks like "the setting did not apply"); the remaining values are validated against the schema — out of range or enum returns 422. Works only together with template_id: template-less sfx/music already keep everything in task_data.

    Send only the keys you are changing. An explicit null does not mean "keep the template value" — it means "erase it": it overwrites the template's value with an empty one for this order. A client that serialises its whole settings form and puts null into the untouched fields will silently reset half the template that way. An absent key is the only way to say "leave this alone".

    Paragraph narration mode

    By default the text is cut into fragments back to back, by technical size, and paragraph boundaries play no part. Paragraph mode changes the order of operations: the text is first split on blank lines into paragraphs, and each paragraph is then cut within itself.

    The key sits next to tts_settings, not inside it — at the root of config_override:

    {"generation_mode": "paragraph"}
    ValueWhat it does
    paragraphA paragraph becomes a unit of generation in its own right
    defaultContinuous cutting by fragment size (same as omitting the key)

    Supported by elevenlabs and heygen; other services ignore the key — there is no rejection, the mode simply does not engage.

    What changes in the response: the order gains paragraphs[] (per paragraph: its index, fragment count, aggregate status, progress and result_file — the whole paragraph's audio), and fragments gain paragraph_index. There is no need to cut the order's stitched track into paragraphs: for a multi-fragment paragraph result_file is its stitch (null until then), while for a single-fragment paragraph (chunks_count = 1) result_file is always null — the paragraph's file is items[].result_file of the fragment with the same paragraph_index.

    This affects the price. The minimum billable volume applies to EVERY paragraph separately rather than to the order as a whole: five short paragraphs cost five minimums, whereas the same text in the default mode would cost one.

    It affects speed too. A paragraph is a task of its own, and no more than 10 single-fragment paragraphs plus 5 multi-fragment ones run at a time per order; the rest wait for a slot. A text of a hundred short paragraphs therefore proceeds in waves — but the first results arrive sooner than with continuous cutting.

    A template's config accepts the same key, which makes the mode permanent for every order built from that template. GET /templates/config-options does not list it: that directory describes the service's settings, while the mode is chosen per order.

    object
    Example {"tts_settings":{"voice_id":"EXAVITQu4vr4xnSDxMaL"}}
    skip_service_defaultsoptional

    Do not merge the service's default_config into task_data. Send true when you already have the complete parameter set and the worker should receive exactly that — the server will not add a single default key.

    The flag is stored on the order: POST /orders/{order}/retry reproduces the same behaviour. It has no effect on template-based orders — those take their config from template.config plus config_override, not from the service defaults.

    nullabledefault false
    boolean
    input_textoptional

    The task text. For tts this is what gets narrated; the server splits it into chunks by itself.

    There are three channels for text and they are equal — every check (pause limits, "nothing to narrate") applies to each of them:

    ChannelWhen to use it
    input_textThe usual way: the text right in the request
    A .txt in input_files[]Long text as a file; its contents become the task text
    task_data.textTemplate-less orders only

    What happens to the text before it is cut, and how markup inside it affects the price, is covered in the “Markup inside the text” and “How the text is cut” sections of this method's description.

    For template-less sfx/music this field is unused — put the description into task_data.text (SFX) or task_data.prompt (Music).

    nullable
    string
    Example Hello! Glad to see you at Lumean.
    confirm_payg_topupoptional

    Consent to top up from the LMC balance when the subscription quota does not cover the whole order. Normally not needed: the top-up is charged automatically, and the field is ignored. It only matters in the fallback mode with explicit confirmation, which the platform operator may enable — the rules below describe that mode.

    The spending order never changes: subscription quota first, LMC only for the remainder. If the quota covers the order, this flag changes nothing and the balance is not touched at all.

    The flag alone charges nothing. Consent is only valid together with a fresh quote_token from a 402 response, bound to you, the service and the exact task volume. Sent without a token (or with an expired or foreign one), confirm_payg_topup: true simply returns 402 again — nothing is charged.

    The working cycle: send the order → 402 with shortfall_tokens, shortfall_lmc, quote_token, expires_at → show the amount to your user → repeat the same request with confirm_payg_topup: true and that quote_token. The token lives about 60 seconds.

    Consent is an upper bound: if the top-up turns out cheaper at charge time, the actual amount is taken; if it got more expensive (a concurrent order ate the quota), you get 409 quote_mismatch: it already carries a fresh quote_token and expires_at for the new amount (actual_lmc_minor) — repeat the request with them, no new 402 needed.

    nullabledefault false
    boolean
    quote_tokenoptional

    The signed top-up quote from a 402 response — pass the string as-is, together with confirm_payg_topup: true.

    The token is bound to the user, the service and the task volume, and lives about 60 seconds. An expired, altered or foreign token does not apply: the request returns 402 with a new quote.

    nullable
    string
    input_filesoptional

    Input files — multipart/form-data only, up to 20 MB per file. A single file may be sent in the input_file field instead.

    Task typeFile
    tts (narration)A .txt — a full replacement for input_text: its contents become the text to narrate
    voice_searchAn audio clip, required. The type is checked by content rather than extension; a foreign format (image, archive) gives 422 before any charge. Longer than 60 seconds is truncated, and the response says so
    sfx, musicUnused — the whole description lives in task_data
    nullable
    array<file>

    Possible responses

    201

    Order created and queued. data holds the order with status created/pending; it carries no result yet.

    Body example
    {
      "success": true,
      "message": "Order created successfully.",
      "data": {
        "id": "c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
        "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-17T15:00:00+00:00",
        "updated_at": "2026-07-17T15:00:00+00:00",
        "eta_seconds": null,
        "eta_at": null,
        "completed_chunks": 0,
        "total_chunks": 2,
        "progress_percent": 0
      }
    }
    Response fields
    successrequired

    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.

    boolean
    messagerequired

    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.

    string
    datarequired

    The order just created. It is already queued: status is pending and result is empty. Keep the id and watch the status — by polling or over WebSocket.

    OrderOrder
    idrequired

    Order UUID. Use it in /orders/{order}/… paths and when calling POST /orders/{order}/retry.

    string
    user_idrequired

    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.

    integer
    namerequired

    Order name: the downloaded file name and the ZIP archive name are derived from it.

    string
    templateoptional

    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.

    TemplateTemplate
    idrequired

    Template UUID. Put it into template_id when creating an order.

    string
    user_idrequired

    ID of the template owner.

    integer
    slugrequired

    Short public identifier used for sharing. null on a template that was never shared.

    string
    namerequired

    Template name — for humans only; it does not affect generation.

    string
    service_keyrequired

    Code of the service whose schema validates config: elevenlabs, lumimg, and so on.

    string
    servicerequired

    The template’s service for reference: name and pricing, without configuration schemas. null means no service with that code exists any more.

    nullable
    Service | null
    configrequired

    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).

    object
    is_publicrequired

    Whether the template is published in the shared catalogue.

    boolean
    folder_idrequired

    UUID of the folder holding the template, or null for the root. The folder tree is visible in GET /templates/browse.

    string
    created_atrequired

    When the template was created, ISO 8601.

    nullabledate-time
    string
    updated_atrequired

    When the template last changed, ISO 8601.

    nullabledate-time
    string
    template_idrequired

    UUID of the template used, or null when the order was created without one.

    string
    task_typerequired

    Task type — it determines what goes into task_data and what comes back in result.

    Valuesttsimagetxt2imgremiximage_editvoice_clonesfxmusicvoice_searchcartesia_dubelevenlabs_dub
    TaskTypeTaskType
    statusrequired

    Current state of the order. There are five terminal values — completed, result_delivered, failed, compensated and cancelled; there is nothing to poll for after those.

    partially_completed is NOT terminal: 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 — after the retry the order can move on to completed.

    compensated and failed mean the order closed without a result. compensated is the normal outcome: no fragment succeeded (a generation failure, or every fragment was rejected by the content policy), the order’s lock is released and the quota returned; only the fee for policy_flagged attempts is withheld (see items[].status). failed is rare: the order failed while its input files were being prepared (the refund is made right away), or the automatic refund did not go through — such an order is settled by support. If at least one fragment is ready, a failure yields partially_completed instead: what is done is paid for, and what failed can be retried.

    Valuescreatedpendingin_progresscompletedresult_deliveredfailedcompensatedcancelledpartially_completed
    OrderStatusOrderStatus
    price_unitsrequired

    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.

    integer
    price_formattedrequired

    The same amount as price_units, expressed in whole LMC and ready to display. null until the cost is settled.

    nullable
    number
    currency_assetrequired

    The amount's asset is always LMC. Its precision is what converts minor units into the real value.

    AssetAsset
    idrequired

    Internal identifier of the asset.

    integer
    coderequired

    Asset code: LUMC is the internal currency, TOKEN the generation tokens.

    string
    kindrequired

    Kind of asset: money or consumable units. It decides whether an amount counts as a payment or as quota consumption.

    Valuesmoneyunit
    AssetKindAssetKind
    precisionrequired

    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.

    integer
    namerequired

    Display name of the asset, in the account language.

    string
    deleted_atrequired

    When the asset was retired, ISO 8601. null while it is in use.

    nullabledate-time
    string
    created_atrequired

    When the asset was created, ISO 8601.

    nullabledate-time
    string
    updated_atrequired

    When the asset last changed, ISO 8601.

    nullabledate-time
    string
    total_tokensrequired

    The order's full cost in tokens: the original chunks plus every retry and regeneration. This is a quota unit, not money.

    nullable
    integer
    total_duration_msrequired

    Total length of the produced audio in milliseconds. This is the result's duration, not the time spent generating it.

    nullable
    integer
    task_datarequired

    The task input exactly as the server accepted it: text, references to uploaded files, resolved settings. The set of keys depends on task_type.

    nullable
    object
    resultrequired

    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.

    nullable
    object
    created_atrequired

    When the order was created, ISO 8601.

    nullabledate-time
    string
    updated_atrequired

    When the order last changed, ISO 8601. It advances on every status transition, which makes it a cheap “something happened” signal.

    nullabledate-time
    string
    files_expire_atrequired

    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.

    nullable
    string
    files_expiredrequired

    true means retention has elapsed and the files are already deleted: no link can be issued, and the order has to be created again.

    boolean
    retentionrequired

    Retention deadlines by file level. For a stitched order the per-fragment tracks are removed earlier than the result itself.

    object
    chunksrequired

    Lifetime of the per-fragment tracks — pause editing, re-stitching and per-fragment regeneration all operate on them.

    object
    expires_atrequired

    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.

    string
    expiredrequired

    true means the per-fragment tracks are gone: editing and re-stitching are rejected. The finished result may still be available — check retention.files.

    boolean
    expires_earlyrequired

    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.

    boolean
    reasonrequired

    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.

    nullable
    Valueschunks_purgedstorage_expired
    string
    filesrequired

    Lifetime of every file of the order, including the result. Mirrors the top-level files_expire_at / files_expired fields.

    object
    expires_atrequired

    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.

    nullable
    string
    expiredrequired

    Same as files_expired: nothing is left to download.

    boolean
    eta_secondsrequired

    Estimated time remaining, in seconds — present only while the order is running. null once it is finished, and before it starts.

    nullable
    integer
    eta_atrequired

    Expected completion moment, ISO 8601 — the same forecast as eta_seconds, expressed as an absolute time.

    nullabledate-time
    string
    completed_chunksrequired

    How many source chunks are already finished. Retries and regenerations are excluded — counting them would push progress past 100%.

    nullable
    integer
    total_chunksrequired

    How many source chunks the order has in total. Zero means the split has not happened yet.

    nullable
    integer
    progress_percentrequired

    Completion percentage, 0–100 — derived from completed_chunks and total_chunks, so there is no need to compute it yourself.

    nullable
    integer
    stitchingrequired

    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.

    boolean
    paragraphsrequired

    Per-paragraph summary: index, fragment count, aggregate status, progress and audio file (result_file). 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).

    nullable
    array<object>
    array item
    paragraph_indexrequired

    Zero-based index of the paragraph.

    integer
    chunks_countrequired

    How many chunks the paragraph was split into.

    integer | number
    completed_chunksrequired

    How many of the paragraph’s chunks are already finished.

    string | integer
    statusrequired

    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[].

    string
    progress_percentrequired

    Paragraph completion percentage, 0–100.

    integer
    result_filerequired

    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.

    nullable
    string
    itemsoptional

    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.

    array<OrderItem>OrderItem
    array item
    idrequired

    Chunk UUID. Use it in /orders/{order}/items/{item}/… paths.

    string
    order_idrequired

    UUID of the order this chunk belongs to.

    string
    item_typerequired

    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.

    string
    chunk_indexrequired

    Zero-based position of the fragment within the order. It defines the order in which the final file is assembled.

    nullable
    integer
    paragraph_indexrequired

    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.

    string
    parent_item_idrequired

    UUID of the source chunk — present on retry and regeneration records. null on an original chunk.

    string
    original_text_lengthrequired

    Length of the text the fragment was created with. It is the ceiling for text in regenerate.

    integer
    current_text_lengthrequired

    Length of the fragment’s current text: after a regeneration it differs from original_text_length.

    integer
    price_unitsrequired

    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).

    integer
    consumed_unitsrequired

    How many tokens were actually charged for this fragment. Zero while the fragment is unfinished.

    integer
    remaining_lockedrequired

    How many tokens are still reserved for the fragment. Drops to zero once the fragment finishes or is cancelled.

    integer
    statusrequired

    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.

    A policy_flagged attempt on ElevenLabs is not free: it consumes the provider’s resources even without a result, so a fixed per-attempt fee is withheld from the amount that would otherwise be returned for the fragment (on quota-funded orders — the equivalent in tokens). It is withheld only from what is being returned — nothing is charged beyond the order’s lock, and the balance never goes negative. The money part shows up in the transaction history as policy_block_fee; from the quota, simply fewer tokens are returned.

    string
    result_filerequired

    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.

    nullable
    object | string | null
    duration_msrequired

    Duration of the produced audio in milliseconds — the length of the recording, not the generation time. null for non-audio tasks.

    nullable
    integer
    attempt_numberrequired

    Attempt number for this fragment, starting at 1. It grows with every retry.

    integer
    can_retryrequired

    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.

    boolean
    can_regeneraterequired

    Whether a paid regeneration is allowed right now. Available for finished fragments only.

    boolean
    created_atrequired

    When the fragment was created, ISO 8601.

    nullabledate-time
    string
    updated_atrequired

    When the fragment last changed, ISO 8601.

    nullabledate-time
    string
    failure_reasonoptional

    The reason the fragment failed, for display to the user — localised text in the request language, not a machine code (do not branch on it, the wording changes). Present only on failed and policy_flagged; everything else, and a failure whose reason could not be determined, gets null.

    nullable
    string
    tokens_from_quotaoptional

    How many of the spent tokens were covered by the subscription quota. null means the quota covered nothing.

    nullable
    integer
    tokens_from_paygoptional

    How many tokens were paid for out of the LMC balance, beyond the quota. null means there was no top-up.

    nullable
    integer
    tokens_spentoptional

    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.

    nullable
    integer
    queue_positionoptional

    The order’s place in the queue: how many orders are ahead of it, 0 means next. Present for any task type while the order waits for a free worker (for voice_search, until the check is done); once processing starts, the field is gone. A missing key means "not queued", not "position unknown".

    nullable
    integer
    queue_wait_secondsoptional

    Estimated wait in the queue, in seconds. Computed only for voice search; for other tasks, and while no statistics exist, it is null. An estimate, not a promise — recomputed on every response.

    nullable
    integer
    400

    The order could not be created.

    Body example
    {
      "success": false,
      "message": "The request could not be processed."
    }
    Response fields
    successrequired

    Always false in error responses.

    boolean
    messagerequired

    Error text in the key's language (set through the X-Locale header).

    string
    reasonoptional

    Machine-readable reason — present on business refusals (for example, invalid_order_status); other errors omit it. Branch on it, not on the message text.

    string
    error_codeoptional

    The same machine-readable code as in reason — a second name for the field. Arrives together with reason; the values always match.

    string
    401

    The key is missing, unknown, disabled or expired.

    Analyse this response
    Body example
    {
      "success": false,
      "message": "API key is missing. Provide it in the X-API-KEY header.",
      "data": null
    }
    Response fields
    successrequired

    Always false in error responses.

    boolean
    messagerequired

    Error text in the key's language (set through the X-Locale header).

    string
    datarequired

    Always null when the request is rejected before processing.

    nullable
    null
    402

    Not enough money to cover the part of the order beyond the subscription quota (reason: insufficient_balance), or the plan forbids a top-up (insufficient_allowance). A top-up that the balance covers is charged automatically and the order is created with 201. Only in the fallback mode with explicit confirmation: payg_topup_required — the body carries shortfall_tokens, shortfall_lmc, quote_token and expires_at; repeat the request with confirm_payg_topup: true and that token. Tell the cases apart by reason.

    Analyse this response
    Body example
    {
      "success": false,
      "message": "Insufficient balance to cover the part of the order beyond the subscription quota.",
      "reason": "insufficient_balance",
      "error_code": "insufficient_balance"
    }
    Response fields
    successrequired

    Always false in error responses.

    boolean
    messagerequired

    Error text in the key's language (set through the X-Locale header).

    string
    reasonrequired

    Machine-readable failure reason — branch on this, not on the message text.

    Valuesinsufficient_balanceinsufficient_allowancepayg_topup_required
    string
    error_coderequired

    The same machine-readable code as in reason — a second name for the field. The values always match; branch on either.

    Valuesinsufficient_balanceinsufficient_allowancepayg_topup_required
    string
    shortfall_tokensoptional

    How many tokens the subscription quota did not cover — these are the ones paid from LMC.

    integer
    Example 1200
    shortfall_lmcoptional

    Top-up cost in LMC, ready to show to the user.

    number
    Example 3.6
    shortfall_lmc_minoroptional

    The same amount in LMC minor units — for exact arithmetic without rounding loss.

    integer
    Example 360000000
    quote_tokenoptional

    The signed price quote: return it unchanged in the repeat request together with confirm_payg_topup: true.

    nullable
    string
    Example q_9f8b2c1a4d3e
    expires_atoptional

    The price is fixed until this moment. Afterwards, repeat the request to get a fresh quote.

    nullabledate-time
    string
    Example 2026-07-25T12:34:56+00:00
    403

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

    Analyse this response
    Body example
    {
      "success": false,
      "message": "This API key does not have permission to perform this action."
    }
    Response fields
    successrequired

    Always false in error responses.

    boolean
    messagerequired

    Error text in the key's language (set through the X-Locale header).

    string
    409

    Only in the fallback mode with explicit confirmation: the top-up turned out more expensive than the agreed quote (reason: quote_mismatch; an expired token is a 402, not a 409) — a concurrent order consumed the quota, or the per-paragraph recount came out higher. The body already carries a fresh quote for the actual amount: quote_token, expires_at, actual_lmc_minor (and the earlier quoted_lmc_minor). Show the new amount and repeat the same request with confirm_payg_topup: true and this quote_token — there is no need to request a new 402.

    Analyse this response
    Body example
    {
      "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
    }
    Response fields
    successrequired

    Always false in error responses.

    boolean
    messagerequired

    Error text in the key's language (set through the X-Locale header).

    string
    reasonrequired

    Machine-readable failure reason — branch on this, not on the message text.

    Valuesquote_mismatch
    string
    error_coderequired

    The same machine-readable code as in reason — a second name for the field. The values always match; branch on either.

    Valuesquote_mismatch
    string
    actual_lmc_minorrequired

    What the top-up costs right now (LMC minor units).

    integer
    Example 380000000
    quoted_lmc_minorrequired

    The price you agreed to earlier (LMC minor units).

    integer
    Example 360000000
    422

    Validation error. This also covers reason: content_blocked — the fragment was already rejected by the content policy and is on the blocklist — and reason: paragraph_not_voiceable — the text contains a piece made up solely of pauses, service tags or stage directions, with nothing to voice. A distinct case is reason: text_empty: there is nothing to voice at all, because the order carries no text through any channel (input_text, an uploaded file, task_data.text), or nothing pronounceable was found in what you sent. Repeating such a request yields the same refusal — fix the text. When the text is missing at the request itself, the field is listed in errors and no reason is returned. One more case is reason: template_model_outdated: the template or config_override carries settings of the service's previous schema (a model or engine the current schema no longer has), and the paths of those settings are listed in fields. Nothing is migrated silently: pick the model in the template again (PUT /templates/{template}) and repeat the request.

    Analyse this response
    Body example
    {
      "message": "string",
      "errors": {
        "key": [
          "string"
        ]
      }
    }
    Response fields
    messagerequired

    A summary of the validation errors in words, in the response language (X-Locale).

    string
    errorsrequired

    A per-field breakdown: the key names a request field, the value lists the complaints about it.

    object
    *optional
    arbitrary keys
    array<string>
    429

    The key's token quota is exhausted, or all concurrent task slots are busy. A distinct case is reason: policy_cooldown_active: a cooldown after repeated content-policy blocks, with the wait in retry_after/retry_at and in the Retry-After header.

    Analyse this response
    Body example
    {
      "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
    }
    Response fields
    successrequired

    Always false in error responses.

    boolean
    messagerequired

    Error text in the key's language (set through the X-Locale header).

    string
    reasonrequired

    Machine-readable failure reason — branch on this, not on the message text.

    string
    error_coderequired

    The same machine-readable code as in reason — a second name for the field. The values always match; branch on either.

    string
    retry_afteroptional

    How many seconds to wait before retrying (the same value is in the Retry-After header).

    nullable
    integer

    Events this produces

    Progress arrives over WebSocket: polling the order in a loop is not required. Subscribing needs the same scope as reading orders.

    This page for AI

    Open .mdllm.md

    API version 1.0.0