Create Order

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.

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

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

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

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:

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

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

What drives the price

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

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.

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"}

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 and progress), and fragments gain 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.

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.

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:

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

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 — request a new 402.

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.

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