Behaviour that is easy to miss when integrating. Each note is also linked at the end of its section.
A dialogue retry changes the text and keeps the voices
In a dialogue blocked_chunks, text is the whole part with all its lines. Send it to /retry as the same text with voices inline as on creation: the same voice_id values in the same order, only the line text changes. A different set of voices or text without marks yields 409 retry_unavailable.
Clones from ElevenLabs voices do not use slots
A clone created with elevenlabs_voice_id goes into the shared catalog and does not spend max_cartesia_clones. Only a clone from your own audio uses a slot. If a clone of that voice in that language already exists, /clone returns it with reused: true and creates nothing.
Only deletion frees a slot
clones_used counts your clones in any status. To free a slot, delete the clone with DELETE /v2/voices/cartesia/{voice_id}. Shared-catalog clones cannot be deleted and do not use slots.
An ElevenLabs voice ID works in a Cartesia task
In a task with engine=cartesia you can pass an ElevenLabs voice ID that has a clone: the service takes yours first, then one from the shared catalog. If there is no clone, you get 400 voice_not_found: call /clone with elevenlabs_voice_id first.
A clone is created in the Cartesia language you set
A Sonic language code (ru, en, de, uk, ja, and the rest) is stored as the clone language. An empty code means ru. If Cartesia has no such code, an unsupported Slavic code (be, sr, bs, sl, mk, cnr) produces a ru clone and anything else an en clone. A task language selects the clone of the same ElevenLabs voice in that language when one exists, and is sent to synthesis.
ElevenLabs library voices are not for engine=original
A task with engine=original accepts only the standard ElevenLabs voices from the table. A voice from search or featured yields 400 voice_not_allowed. You can speak with it through a Cartesia clone.
Characters are charged on create
The cost is len(text), multiplied by (1 + 1.5 × number of languages) with dub_languages, and is charged immediately. Characters are refunded when you cancel a pending task, on 503 queue_unavailable, and when synthesis ends as failed. On censored they are not refunded: the spoken part is kept, and blocked fragments are resynthesized via /retry.
Only unlimited can cancel a started task
A task in processing can be cancelled only on an unlimited subscription, where nothing was charged for it. On a character package you get 409 already_processing.
Parallel task limit per license
A slot is taken by tasks in pending, processing, and pending_confirmation. Beyond the tariff max_parallel_tasks you get 429 too_many_active_tasks: wait for one task to finish. How fast a task itself runs is threads_per_task, how many chunks are synthesized in parallel.
Cartesia splits text at 500 characters
For engine=cartesia, max_chunk_length is capped at 500 in smart and max_length. In paragraphs the line is sent whole, up to 2500 characters.
Chinese, Japanese, and Korean: up to 500 characters
If more than 20% of the text is CJK characters or Hangul, chunk length is capped at 500 for any engine.
Quotes are normalized
Every kind of quote («», „“, “”, 「」) in chunks is replaced with ", and an unpaired quote at a chunk edge is removed so the model does not speak it. smart does not split text inside quotes.
voice_settings is ElevenLabs only
Cartesia ignores voice_settings. An ElevenLabs model (eleven_*) in a Cartesia task is not an error: it is replaced with sonic-3.6.
Pauses between chunks
auto_pause adds duration seconds of silence at the end of every frequency-th chunk; there is no pause after the last chunk. Pauses are included in captions from both methods. To place pauses between paragraphs, use split_type: paragraphs.
split_output: ZIP per chunk
With split_output: true, /download returns a ZIP 0000.mp3, 0001.mp3, ... without concatenation, and captions come as a ZIP with one file per chunk and local timestamps. The mode is set when the task is created and cannot be changed later.
The first download is slower
A single MP3 is assembled from chunks on the first /download and then cached. For long texts set a read timeout of at least 10 minutes. Audio is kept for a limited time, after which you get 410 result_expired.
Audio and timestamps are kept for an hour
An hour after a task finishes, the service deletes its audio and ElevenLabs timestamps: /download responds 410 result_expired, /subtitles 409 no_timestamps, and /v2/captions has nothing left to recognize. Fetch files and captions right after completed. For dubbing, the original and every track are kept until the last language is ready and for an hour after it. A censored task keeps the spoken part while it waits for /retry; the task record itself is kept for 30 days.
Retry after censorship
Only blocked_chunks are resynthesized. Indexes in corrected_chunks must match them exactly. If the new text is not longer, the retry is free and works even after the subscription ends. While the task is censored, captions via /subtitles are already available for the spoken part.
pending_confirmation needs no action
The status appears when primary ElevenLabs synthesis has temporarily degraded. The task waits for an operator; you cannot cancel it from the API. Keep polling the status.
Cartesia captions only via /v2/captions
Cartesia does not return timestamps, so /v2/tasks/{task_id}/subtitles yields 409 no_timestamps. Use POST /v2/captions with the same task_id. Recognition does not spend characters.
Maintenance
During maintenance POST /v2/tasks responds 503 maintenance. Other requests, including status and download, keep working.
Music and effects need an active subscription
POST /v2/music and POST /v2/sound-effects do not charge characters and do not take a max_parallel_tasks slot. One API key runs at most threads_per_task generations at once; music and effects share that limit. An active subscription is required: unlimited still in term, or a character pack with a remaining balance.
Extra body fields are forbidden
Bodies of POST /v2/tasks and /retry are strict: an unknown field, a typo in a name, or a value out of range yields 422 with a list of errors in detail.