Поведение, которое легко упустить при интеграции. Каждый нюанс также показан в конце своего раздела.
Повтор диалога правит текст, а голоса оставляет
В blocked_chunks диалога text это часть целиком, со всеми репликами. В /retry пришлите её тем же текстом с голосами в строках, что и при создании: те же voice_id в том же порядке, меняется только текст реплик. Другой набор голосов или текст без пометок даёт 409 retry_unavailable.
Клоны из голосов ElevenLabs не занимают слоты
Клон, созданный с elevenlabs_voice_id, попадает в общий каталог и не расходует квоту max_cartesia_clones. Слот занимает только клон из своего аудио. Если клон этого голоса на этом языке уже есть, /clone вернёт его с reused: true, ничего не создавая.
Слот освобождает только удаление
clones_used считает свои клоны в любом статусе. Чтобы освободить слот, удалите клон через DELETE /v2/voices/cartesia/{voice_id}. Клоны общего каталога удалить нельзя, и слотов они не занимают.
ID голоса ElevenLabs работает в задаче Cartesia
В задачу с engine=cartesia можно передать ID голоса ElevenLabs, у которого есть клон: сервис возьмёт сначала ваш клон, затем клон из общего каталога. Если клона нет, будет 400 voice_not_found: сначала вызовите /clone с elevenlabs_voice_id.
Клон создаётся на указанном языке Cartesia
Код из языков Sonic (ru, en, de, uk, ja и остальные) сохраняется как язык клона. Пустой код означает ru. Кода нет у Cartesia: неподдерживаемый славянский (be, sr, bs, sl, mk, cnr) даёт ru-клон, остальное даёт en-клон. language задачи выбирает клон того же голоса ElevenLabs на этом языке, если он есть, и уходит в синтез.
Библиотечные голоса ElevenLabs не для engine=original
Задача engine=original принимает только стандартные голоса ElevenLabs из таблицы. Голос из поиска или подборки даст 400 voice_not_allowed. Озвучить им можно через клон Cartesia.
Символы списываются при создании
Стоимость равна len(text), с dub_languages она умножается на (1 + 1.5 × число языков), и списывается сразу. Символы возвращаются при отмене задачи из pending, при 503 queue_unavailable и когда озвучка завершилась статусом failed. При censored символы не возвращаются: озвученная часть сохранена, а заблокированные фрагменты переозвучиваются через /retry.
Начатую задачу отменяет только безлимит
Задачу в processing можно отменить только на безлимитной подписке, где за неё ничего не списано. На пакете символов придёт 409 already_processing.
Лимит одновременных задач на лицензию
Слот занимают задачи в pending, processing и pending_confirmation. Сверх max_parallel_tasks тарифа приходит 429 too_many_active_tasks: дождитесь завершения одной из задач. Скорость самой задачи задаёт threads_per_task, сколько чанков озвучивается параллельно.
Cartesia режет текст до 500 символов
Для engine=cartesia max_chunk_length урезается до 500 в режимах smart и max_length. В режиме paragraphs строка уходит целиком, до 2500 символов.
Китайский, японский и корейский: до 500 символов
Если больше 20% текста составляют иероглифы или хангыль, длина чанка ограничивается 500 символами для любого движка.
Кавычки нормализуются
Все виды кавычек («», „“, “”, 「」) в чанках заменяются на ", а непарная кавычка на краю чанка удаляется, чтобы модель её не произносила. Режим smart не разрывает текст внутри кавычек.
voice_settings только для ElevenLabs
Cartesia игнорирует voice_settings. Модель ElevenLabs (eleven_*) в задаче Cartesia не даёт ошибку, а заменяется на sonic-3.6.
Паузы между чанками
auto_pause добавляет тишину duration секунд в конец каждого frequency-го чанка; после последнего чанка паузы нет. Паузы учитываются в субтитрах обоих способов. Чтобы паузы стояли между абзацами, используйте split_type: paragraphs.
split_output: ZIP по чанкам
С split_output: true /download отдаёт ZIP 0000.mp3, 0001.mp3, ... без склейки, а субтитры приходят ZIP-архивом с файлом на чанк и локальными таймкодами. Режим задаётся при создании задачи и потом не меняется.
Первое скачивание медленнее
Одиночный MP3 собирается из чанков при первом /download и кэшируется. Для длинных текстов ставьте таймаут чтения от 10 минут. Аудио хранится ограниченное время, после чего приходит 410 result_expired.
Аудио и метки хранятся час
Через час после завершения задачи сервис удаляет её аудио и метки ElevenLabs: /download отвечает 410 result_expired, /subtitles 409 no_timestamps, и /v2/captions распознавать уже нечего. Забирайте файлы и субтитры сразу после completed. У дубляжа оригинал и все дорожки хранятся, пока не готов последний язык, и ещё час после него. Задача в censored хранит озвученное, пока ждёт /retry; сама запись задачи хранится 30 дней.
Повтор после цензуры
Переозвучиваются только blocked_chunks. Индексы в corrected_chunks должны совпасть с ними точно. Если новый текст не длиннее, повтор бесплатен и работает даже после окончания подписки. Пока задача censored, её субтитры через /subtitles уже доступны для озвученной части.
pending_confirmation не требует действий
Статус появляется, когда основной синтез ElevenLabs временно деградировал. Задача ждёт решения оператора, отменить её из API нельзя. Продолжайте опрашивать статус.
Субтитры для Cartesia только через /v2/captions
Cartesia не возвращает временные метки, поэтому /v2/tasks/{task_id}/subtitles даёт 409 no_timestamps. Используйте POST /v2/captions с тем же task_id. Распознавание символы не тратит.
Технические работы
Во время работ POST /v2/tasks отвечает 503 maintenance. Остальные запросы, включая статус и скачивание, работают.
Музыка и эффекты при активной подписке
POST /v2/music и POST /v2/sound-effects не списывают символы и не занимают max_parallel_tasks. На один API-ключ одновременно идёт не больше threads_per_task тарифа, музыка и эффекты делят этот лимит. Нужна активная подписка: безлимит в сроке или пакет с остатком символов.
Лишние поля в теле запрещены
Тело POST /v2/tasks и /retry проверяется строго: неизвестное поле, опечатка в имени или значение вне диапазона дают 422 со списком ошибок в detail.