Dubbing a finished order

Dubbing translates a finished voiceover into another language and voices the translation. Every phrase of the dub starts where the source phrase starts, and the track has the same length. You don't send any text: the service does the translation. The result is a new order; the source order stays as it is.

Take the languages, models, length cap, price factor and maintenance flag only from GET /orders/dubbing/options. The table above is a guide; don't hard-code it.

Options: is dubbing available

GET /orders/dubbing/options tells which dubbing kinds are open to the key owner. Pick the kind by the source order's service_key: data.kinds[order.service_key].

A closed kind comes with available: false, dub_service: null, empty lists and zeros. That is a "feature not available" answer, not an error. The top-level data fields (except kinds) repeat the cartesia kind for older clients.

Which order can be dubbed

• your own cartesia or elevenlabs voiceover order with status completed or result_delivered;
• the order's files are still stored (see Files and storage);
• the order is not in paragraph mode (generation_mode: "paragraph"): one track is required;
• no regeneration or stitching is running on the order;
• the source is no longer than max_source_chars.

Otherwise creation and the quote return 422 with a reason from the refusals table below.

The dub language must differ from the source language. For Cartesia the source language is known from the template, and a match is refused right away with 422 dub_same_language. For ElevenLabs the source language is unknown (source_language: "auto"): such a dub is created, fails at the worker and refunds in full. Watch the language yourself.

Price before ordering

GET /orders/{order}/dub/quote prices the dub and charges nothing; it doesn't spend the key's token quota either. The limit is 60 requests per minute per key. The query takes the same fields as the creation body, all optional: the price depends only on the source characters.

Amounts are in minor units: real = value / 10^currency_asset.precision. defaults.voice_id: null means the default voice is no longer available (removed from the catalog, clone deleted): pass voice_id when creating.

Creating a dub

POST /orders/{order}/dub creates the dub order. The body is JSON:

The default voice and model come from the snapshot of the source order's template, as the template was when the source was created. Explicit voice_id and model_id override the template.

The response is 201 with the new order in data: task_type is cartesia_dub or elevenlabs_dub, with one fragment. From here it is a regular order: the status arrives over WebSocket or by polling GET /orders/{order}, the track is in result.files[], subtitles are in result.service_files[], and POST /storage/url returns the link.

BASE=https://api.lumean.app/api/public
SRC=<ORDER_UUID>   # a finished voiceover order

curl -s "$BASE/orders/dubbing/options" -H "X-API-KEY: $KEY"
curl -s "$BASE/orders/$SRC/dub/quote?target_language=en" -H "X-API-KEY: $KEY"
curl -s -X POST "$BASE/orders/$SRC/dub" -H "X-API-KEY: $KEY" -H "Content-Type: application/json" \
  -d '{ "target_language": "en" }'
# → 201, data.id = <DUB_UUID>, data.task_type = "cartesia_dub"

The key needs orders.read (options and quote), orders.write (creation) and orders.download (the file link).

Payment

Payment works like a regular voiceover. The subscription quota is spent first, by the source service's entitlement: a subscription with Cartesia also pays for a Cartesia dub. The rest is charged to the balance as PAYG. The cost also counts against the key's token quota: when it is exceeded, the order is not created and the response is 429 token_quota_exceeded. A failed dub refunds in full.

A dub can be cancelled before work starts (POST /orders/{order}/cancel). It doesn't need retry: on failure the money comes back, so create the dub again.

Refusals

A field error (target_language not in the list, someone else's or a deleted template_id) is 422 with the field in errors, and nothing is charged. Someone else's or a missing order is 404, not enough money for the PAYG top-up is 402, and maintenance of the kind is 503.