{"format":"voicer-api-guide/1","title":"Voicer API v2","version":"2","language":"ru","base_url":"https://voicer.mat3u.com","summary":"Озвучка текста голосами ElevenLabs и Cartesia, клонирование голосов, субтитры, музыка и звуковые эффекты.","conventions":{"auth":{"token":"Authorization: Bearer <токен>","none":"без авторизации","signed":"подпись exp и sig в query, токен не нужен"},"markup":"`код` и [текст](#якорь), якорь ссылается на id раздела, темы или эндпоинта","error_body":{"detail":{"code":"string","message":"string"}}},"llm_notes":["Все пути относительно base_url. Авторизация: заголовок Authorization: Bearer <токен>, кроме эндпоинтов с auth = none или signed.","Ошибки: тело {\"detail\": {\"code\", \"message\", ...}}; ветвиться по code, список в error_codes.","Диалоги: POST /v2/dialogues с engine labs или cartesia; статус и скачивание как у задач.","Озвучка асинхронная: POST /v2/tasks, активные GET /v2/tasks, опрос GET /v2/tasks/{task_id} раз в 2-5 с до конечного статуса, затем GET /v2/tasks/{task_id}/download.","Примеры python используют python_preamble: сессию requests s и BASE.","Значения params[].default записаны JSON-литералами.","Музыка и эффекты синхронные и без списания символов: POST /v2/music и POST /v2/sound-effects доступны при активной подписке."],"python_preamble":"import os\nimport time\n\nimport requests\n\nBASE = \"https://voicer.mat3u.com\"\ns = requests.Session()\ns.headers[\"Authorization\"] = f\"Bearer {os.environ['VOICER_TOKEN']}\"\n","sections":[{"id":"start","title":"Начало работы","intro":["Voicer API озвучивает текст голосами ElevenLabs и Cartesia, клонирует голоса и делает субтитры. Озвучка асинхронная: вы создаёте задачу, опрашиваете её статус и скачиваете MP3, когда она готова."],"topics":[{"id":"base-url","title":"Адрес и формат","paragraphs":["Базовый адрес: `https://voicer.mat3u.com`. Все пути начинаются с `/v2`. Запросы и ответы в JSON (UTF-8), кроме загрузки файлов (`multipart/form-data`) и скачивания аудио и субтитров.","Даты в ответах в формате ISO 8601 с часовым поясом UTC, например `2026-10-11T16:34:08.984299Z`.","Списки с пагинацией принимают `page` (с нуля) и `page_size` (1-50) и возвращают `has_more`: пока он `true`, запрашивайте следующую страницу."],"table":null,"code":[]},{"id":"auth","title":"Авторизация","paragraphs":["Каждый запрос, кроме отмеченных «без токена», передаёт API-токен в заголовке `Authorization: Bearer <токен>`. Токен выдаёт Telegram-бот Voicer. Один токен соответствует одной лицензии: у неё свой баланс, тариф и лимит одновременных задач.","Без заголовка или с неверным токеном API отвечает `401` с `WWW-Authenticate: Bearer`. Проверить, чей токен, можно через [GET /v2/auth/me](#auth-me)."],"table":null,"code":[{"language":"bash","code":"curl https://voicer.mat3u.com/v2/auth/me \\\n -H \"Authorization: Bearer $VOICER_TOKEN\"","title":null}]},{"id":"errors-format","title":"Формат ошибок","paragraphs":["Ошибка бизнес-логики приходит с HTTP-статусом и телом `{\"detail\": {\"code\": \"...\", \"message\": \"...\"}}`. `code` стабилен, по нему стоит ветвить логику клиента; `message` написан для человека и может меняться. Рядом с ними бывают поля с подробностями, например `required` и `available` при нехватке символов. Полный список кодов в разделе [Коды ошибок](#error-codes).","Ошибка авторизации приходит строкой: `{\"detail\": \"Недействительный токен\"}`.","Неверный тип или формат поля даёт `422` в стандартном формате FastAPI: `{\"detail\": [{\"loc\": [\"body\", \"max_chunk_length\"], \"msg\": \"...\", \"type\": \"...\"}]}`. Лишние поля в JSON-телах задач запрещены и тоже дают `422`."],"table":null,"code":[{"language":"json","code":"{\n \"detail\": {\n \"code\": \"insufficient_characters\",\n \"message\": \"Недостаточно символов: нужно 12000, осталось 3400\",\n \"required\": 12000,\n \"available\": 3400\n }\n}","title":"402 Payment Required"}]},{"id":"quickstart","title":"Быстрый старт на Python","paragraphs":["Полный цикл: создать задачу, дождаться результата и сохранить MP3. Остальные примеры на Python в этом справочнике используют сессию `s` и переменную `BASE` из этого кода. Нужен пакет `requests` и переменная окружения `VOICER_TOKEN`."],"table":null,"code":[{"language":"python","code":"import os\nimport time\n\nimport requests\n\nBASE = \"https://voicer.mat3u.com\"\ns = requests.Session()\ns.headers[\"Authorization\"] = f\"Bearer {os.environ['VOICER_TOKEN']}\"\n\n\ndef synthesize(text: str, voice_id: str, out_path: str) -> None:\n created = s.post(f\"{BASE}/v2/tasks\", json={\"text\": text, \"voice_id\": voice_id}, timeout=60)\n if created.status_code != 202:\n raise RuntimeError(created.json()[\"detail\"])\n task_id = created.json()[\"task_id\"]\n\n while True:\n task = s.get(f\"{BASE}/v2/tasks/{task_id}\", timeout=30).json()\n if task[\"status\"] in (\"pending\", \"processing\", \"pending_confirmation\"):\n time.sleep(3)\n continue\n break\n\n if task[\"status\"] == \"censored\":\n # Перепишите заблокированные фрагменты и отправьте их в /retry (раздел «Задачи»).\n raise RuntimeError(f\"Цензура: {task['blocked_chunks']}\")\n if task[\"status\"] != \"completed\":\n raise RuntimeError(f\"Задача {task['status']}: {task['error']}\")\n\n with s.get(f\"{BASE}/v2/tasks/{task_id}/download\", stream=True, timeout=600) as r:\n r.raise_for_status()\n with open(out_path, \"wb\") as f:\n for piece in r.iter_content(1 << 16):\n f.write(piece)\n\n\nsynthesize(\"Привет! Это тест Voicer API.\", \"JBFqnCBsd6RMkjVDRZzb\", \"voice.mp3\")\n","title":null}]},{"id":"llm","title":"Справочник для нейросети","paragraphs":["Весь этот справочник в машиночитаемом виде лежит по адресу [/docs.json](/docs.json): разделы, эндпоинты, параметры со всеми значениями, примеры на curl и Python, ошибки и нюансы. Передайте файл модели целиком как контекст. OpenAPI-схема для генераторов клиентов: [/openapi.json](/openapi.json), интерактивный Swagger: [/docs/swagger](/docs/swagger)."],"table":null,"code":[]}],"endpoints":[],"nuances":[]},{"id":"concepts","title":"Основные понятия","intro":[],"topics":[{"id":"engines","title":"Движки озвучки","paragraphs":["Параметр `engine` задачи выбирает провайдера. От движка зависят допустимые голоса, модели и максимальный размер чанка.","Если `engine` не указан, берётся `original`, а на тарифе без него (например, Cartesia) `cartesia`. Движок, закрытый тарифом, даёт `403` с кодом `engine_not_allowed`. Что разрешено вашей лицензии, смотрите в `tariff` ответа [GET /v2/billing/me](#billing-me)."],"table":{"columns":["engine","Провайдер","Голоса","Модель по умолчанию"],"rows":[["`original`","ElevenLabs","Стандартные голоса ElevenLabs ([список](#voices-elevenlabs))","`eleven_multilingual_v2`"],["`cartesia`","Cartesia","Стандартные голоса Cartesia, свои клоны и общий каталог клонов","`sonic-3.6`"]]},"code":[]},{"id":"characters","title":"Символы, пакеты и лицензия","paragraphs":["Озвучка тарифицируется в символах исходного текста: `len(text)`, включая пробелы и переносы строк. Символы списываются сразу при создании задачи и возвращаются, если задачу отменили до начала озвучки, если её не удалось поставить в очередь или если озвучка закончилась статусом `failed`.","Символы лежат в пакетах, у каждого свой срок. Списание идёт из пакета, который сгорает раньше. На безлимитной подписке символы не списываются (`charged_characters = 0`), но действуют лимиты тарифа.","Лимиты тарифа: одновременных задач на лицензию (`max_parallel_tasks`), символов в задаче (`max_chars_per_task`), чанков в задаче (`max_chunks_per_task`), разрешённые движки и квота своих клонов Cartesia (`max_cartesia_clones`). `null` в лимите означает «без ограничения»."],"table":null,"code":[]},{"id":"lifecycle","title":"Жизненный цикл задачи","paragraphs":["Задача проходит статусы `pending` (в очереди), `processing` (озвучивается) и заканчивается одним из конечных. Опрашивайте [GET /v2/tasks/{task_id}](#tasks-get) раз в 2-5 секунд."],"table":{"columns":["Статус","Что значит","Что делать"],"rows":[["`pending`","В очереди, символы списаны","Ждать. Можно отменить"],["`processing`","Озвучивается, растёт `progress_percent`","Ждать"],["`pending_confirmation`","Основной TTS временно деградировал, задача ждёт решения оператора","Ждать, задача продолжится или завершится сама"],["`completed`","Готово","Скачать результат"],["`censored`","ElevenLabs заблокировал часть фрагментов, остальное озвучено","Исправить текст фрагментов из `blocked_chunks` и вызвать /retry"],["`failed`","Ошибка, подробности в `error`; символы возвращены","Создать задачу заново"],["`cancelled`","Отменена","Ничего"]]},"code":[]},{"id":"chunks","title":"Чанки","paragraphs":["Перед озвучкой текст режется на чанки, каждый озвучивается отдельным запросом к провайдеру, затем чанки склеиваются в один MP3. Как резать, задают `split_type` и `max_chunk_length`. Число чанков возвращается в `chunks_count` и ограничено тарифом.","От чанков зависят паузы (`auto_pause` вставляет тишину после каждого N-го чанка), режим `split_output` (ZIP с MP3 на каждый чанк) и повтор после цензуры (переозвучиваются только заблокированные чанки)."],"table":null,"code":[]}],"endpoints":[],"nuances":[]},{"id":"account","title":"Аккаунт и баланс","intro":["Баланс и лимиты считаются по лицензии, то есть по токену из заголовка. У одного пользователя может быть несколько токенов с разными тарифами."],"topics":[],"endpoints":["auth-me","billing-me","billing-stats","billing-tariffs"],"nuances":["parallel-limit"]},{"id":"voices","title":"Голоса ElevenLabs и модели","intro":["Для `engine=original` подходят стандартные голоса ElevenLabs из таблицы ниже. Библиотека ElevenLabs (поиск и подборка) нужна, чтобы найти голос для клона Cartesia."],"topics":[{"id":"elevenlabs-voices-table","title":"Стандартные голоса ElevenLabs","paragraphs":["Все голоса многоязычные и говорят по-русски на моделях `eleven_multilingual_v2`, `eleven_v3` и новее."],"table":{"columns":["Имя","voice_id"],"rows":[["Adam","`pNInz6obpgDQGcFmaJgB`"],["Alice","`Xb7hH8MSUJpSbSDYk0k2`"],["Bella","`hpp4J3VqNfWAUOO0d1Us`"],["Bill","`pqHfZKP75CvOlQylNhV4`"],["Brian","`nPczCjzI2devNBz1zQrb`"],["Callum","`N2lVS1w4EtoT3dr4eOWO`"],["Charlie","`IKne3meq5aSn9XLyUdCD`"],["Chris","`iP95p4xoKVk53GoZ742B`"],["Daniel","`onwK4e9ZLuTAKqWW03F9`"],["Eric","`cjVigY5qzO86Huf0OWal`"],["George","`JBFqnCBsd6RMkjVDRZzb`"],["Harry","`SOYHLrjzK2X1ezoPC6cr`"],["Jessica","`cgSgspJ2msm6clMCkdW9`"],["Laura","`FGY2WhTYpPnrIDTdsKH5`"],["Liam","`TX3LPaxmHKxFdv7VOQHJ`"],["Lily","`pFZP5JQG7iQjIQuC4Bku`"],["Matilda","`XrExE9yKIg1WjnnlVkGX`"],["River","`SAz9YHcvj6GT2YYXdXww`"],["Roger","`CwhRBWXzGAHq8TQ4Fs17`"],["Sarah","`EXAVITQu4vr4xnSDxMaL`"],["Will","`bIHbv24MWmeRgasZH58o`"]]},"code":[]},{"id":"models-table","title":"Модели по движкам","paragraphs":["Без `model_id` берётся модель по умолчанию. Для `cartesia` модель ElevenLabs (`eleven_*`) молча заменяется на `sonic-3.6`, а снятые модели (`sonic`, `sonic-2*`, `sonic-turbo*`, `sonic-english` и т.п.) дают `400` с кодом `invalid_model`. Датированные снимки вида `sonic-3.6-ГГГГ-ММ-ДД` принимаются."],"table":{"columns":["Движок","По умолчанию","Остальные"],"rows":[["`original`","`eleven_multilingual_v2`","`eleven_english_v1`, `eleven_flash_v2`, `eleven_flash_v2_5`, `eleven_multilingual_v1`, `eleven_turbo_v2`, `eleven_turbo_v2_5`, `eleven_v3`, `eleven_v4`, `eleven_v4_turbo`"],["`cartesia`","`sonic-3.6`","`sonic-3`, `sonic-3-2026-01-12`, `sonic-3.5`, `sonic-3.5-2026-05-04`, `sonic-3.6-2026-08-27`, `sonic-preview`"]]},"code":[]}],"endpoints":["voices-elevenlabs","voices-elevenlabs-search","voices-elevenlabs-featured","voices-models"],"nuances":["library-voices-original"]},{"id":"cartesia","title":"Голоса Cartesia","intro":["Для `engine=cartesia` подходят голоса трёх видов: стандартные голоса Cartesia, свои клоны и общий каталог клонов голосов ElevenLabs. Все списки требуют тарифа, разрешающего движок cartesia."],"topics":[{"id":"cartesia-voice-kinds","title":"Какой voice_id передавать в задачу","paragraphs":["В `voice_id` задачи с `engine=cartesia` можно передать любой из трёх ID. Если передан ID голоса ElevenLabs, сервис сам найдёт его готовый клон: сначала свой, затем из общего каталога."],"table":{"columns":["Что передаёте","Пример","Откуда взять"],"rows":[["ID клона Cartesia","`8d0a6f1e-3b52-4c9e-a7d4-52e1c09b7f36`","Каталог, мои клоны, ответ /clone"],["ID стандартного голоса","`f786b574-daa5-4673-aa0c-cbe3e8534c02`","/v2/voices/cartesia/standard"],["ID голоса ElevenLabs, у которого есть клон","`Wu3B7bOkdHbKnJTvbiFk`","Поиск ElevenLabs, затем /clone или /from-labs"]]},"code":[]}],"endpoints":["cartesia-voices","cartesia-catalog","cartesia-mine","cartesia-standard","cartesia-voice","cartesia-preview"],"nuances":["labs-clone-slots","labs-id-in-task"]},{"id":"cloning","title":"Клонирование голосов","intro":["Клон Cartesia создаётся двумя способами, и они по-разному расходуют квоту тарифа (`max_cartesia_clones`)."],"topics":[{"id":"clone-kinds","title":"Свой клон и клон из ElevenLabs","paragraphs":[],"table":{"columns":["","Свой клип","elevenlabs_voice_id"],"rows":[["Слот клона","Занимает","Не занимает"],["Кому виден","Только вам","Всем, попадает в общий каталог"],["Аудио","Обязательно, 10-60 с","Необязательно: берётся семпл ElevenLabs"],["Повтор","Каждый раз новый клон","Возвращается готовый (`reused: true`)"],["Удаление","DELETE освобождает слот","Нельзя (`403 shared_clone`)"]]},"code":[]}],"endpoints":["cartesia-clone","cartesia-from-labs","cartesia-delete"],"nuances":["labs-clone-slots","clone-slots-count","clone-languages"]},{"id":"tasks","title":"Задачи озвучки","intro":["Задача принадлежит лицензии (токену), который её создал. Чужие задачи для API не существуют и дают `404`. Незавершённые задачи текущего ключа: [GET /v2/tasks](#tasks-list)."],"topics":[{"id":"censorship","title":"Цензура и повтор","paragraphs":["ElevenLabs иногда отказывается озвучивать отдельные фрагменты. Тогда задача заканчивается статусом `censored`: озвученные чанки сохранены, а заблокированные перечислены в `blocked_chunks`. Перепишите их текст и отправьте в [/retry](#tasks-retry): переозвучатся только они.","Повтор бесплатен, если новый текст не длиннее исходного. Если длиннее, списывается только разница. Без доплаты повтор работает даже после окончания подписки. Данные для повтора хранятся вместе с задачей (30 дней)."],"table":null,"code":[{"language":"python","code":"task = s.get(f\"{BASE}/v2/tasks/{task_id}\", timeout=30).json()\nif task[\"status\"] == \"censored\":\n fixed = [\n {\"index\": c[\"index\"], \"text\": rewrite(c[\"text\"])} # rewrite: ваша замена слов\n for c in task[\"blocked_chunks\"]\n ]\n r = s.post(f\"{BASE}/v2/tasks/{task_id}/retry\", json={\"corrected_chunks\": fixed}, timeout=60)\n r.raise_for_status()\n # дальше снова опрашивайте статус до completed\n","title":"Повтор на Python"}]},{"id":"dubbing","title":"Дубляж","paragraphs":["С `dub_languages` задача озвучивает текст, потом переводит его на каждый язык и озвучивает перевод. По умолчанию тем же голосом (у Cartesia клоном на языке дорожки); в `dub_voices` можно задать другой `voice_id` на язык, чтобы не было акцента. Перевод подгоняется под длительность каждого чанка оригинала: если он выходит длиннее, модель сокращает формулировку, а не ускоряет речь. В конце чанки всех дорожек дополняются тишиной до самого длинного, поэтому файлы совпадают по длине и ложатся на одно видео.","Пример: оригинал голосом `JBFqnCBsd6RMkjVDRZzb`, английский `pNInz6obpgDQGcFmaJgB`, немецкий `EXAVITQu4vr4xnSDxMaL`. Язык без ключа в `dub_voices` остаётся голосом оригинала (у Cartesia клоном на языке дорожки).","Сначала озвучивается весь оригинал, потом языки по одному. Прогресс каждой дорожки виден в `dubs` основной задачи. Основная задача и дорожки становятся `completed` одновременно, когда длина выровнена.","У каждой дорожки свой `task_id`: [/download](#tasks-download), [/subtitles](#tasks-subtitles) и [/v2/captions](#captions-create) работают с ним как с обычной задачей. Для `engine=original` у дорожек есть метки ElevenLabs: субтитры приходят сразу и совпадают с выровненным аудио. Для Cartesia субтитры делаются распознаванием через /v2/captions.","Стоимость: длина текста × (1 + 1.5 × число языков), списывается с основной задачи при создании. Если дубляж закончился `failed`, символы возвращаются. Дорожку нельзя отменить отдельно, только вместе с основной задачей.","Языки зависят от движка и модели. Eleven v3 и v4 говорят на всех языках дубляжа, Multilingual v2, Flash v2.5 и Turbo v2.5 на своём списке, Cartesia на языках Sonic. Недоступный язык даёт `400 unsupported_dub_language` со списком `available`. Для Cartesia язык дубляжа не может совпадать с `language` текста."],"table":null,"code":[{"language":"python","code":"import time\nfrom pathlib import Path\n\nbody = {\n \"text\": text,\n \"voice_id\": \"JBFqnCBsd6RMkjVDRZzb\", # оригинал: George\n \"model_id\": \"eleven_v3\",\n \"dub_languages\": [\"en\", \"de\"],\n \"dub_voices\": {\n \"en\": \"pNInz6obpgDQGcFmaJgB\", # английский: Adam, не голос оригинала\n \"de\": \"EXAVITQu4vr4xnSDxMaL\", # немецкий: Sarah\n },\n}\nr = s.post(f\"{BASE}/v2/tasks\", json=body, timeout=60)\nr.raise_for_status()\ntask = r.json()\ntracks = {\"original\": task[\"task_id\"]} | {d[\"language\"]: d[\"task_id\"] for d in task[\"dubs\"]}\n\nfinal = (\"completed\", \"censored\", \"failed\", \"cancelled\")\nwhile s.get(f\"{BASE}/v2/tasks/{task['task_id']}\", timeout=30).json()[\"status\"] not in final:\n time.sleep(5)\n\n# аудио и метки всех дорожек хранятся час после последнего языка\nfor name, track_id in tracks.items():\n audio = s.get(f\"{BASE}/v2/tasks/{track_id}/download\", timeout=600)\n audio.raise_for_status()\n Path(f\"{name}.mp3\").write_bytes(audio.content)\n srt = s.get(f\"{BASE}/v2/tasks/{track_id}/subtitles\", params={\"format\": \"srt\"}, timeout=60)\n if srt.status_code == 200: # у Cartesia меток нет: 409, тогда POST /v2/captions\n Path(f\"{name}.srt\").write_bytes(srt.content)\n","title":"Дубляж на Python: все файлы и субтитры"}]}],"endpoints":["tasks-create","tasks-list","tasks-get","tasks-cancel","tasks-retry"],"nuances":["labs-id-in-task","clone-languages","library-voices-original","charge-on-create","cancel-processing","parallel-limit","cartesia-chunk","cjk-chunk","quotes","voice-settings-cartesia","auto-pause","censored-retry","pending-confirmation","maintenance","strict-body"]},{"id":"dialogues","title":"Диалоги","intro":["Диалог: это обычная задача озвучки из реплик разных голосов. Статус, скачивание и отмена идут через эндпоинты задач, а символы списываются так же, как за обычный текст той же длины."],"topics":[{"id":"dialogue-engines","title":"Движки и голоса","paragraphs":["`labs` озвучивает диалог через ElevenLabs text-to-dialogue. Голоса: стандартные голоса ElevenLabs, аудио-теги вроде `[excited]` и `[laughs]` модель отыгрывает. Модель по умолчанию `eleven_v4`, также доступны `eleven_v4_turbo` и `eleven_v3`.","`cartesia` озвучивает каждую реплику отдельным запросом Cartesia TTS и склеивает их. Голос реплики: ID клона, стандартный голос Cartesia или ID голоса ElevenLabs, у которого есть клон. Язык определяет, какой клон взять: если клона на языке текста нет, славянские языки озвучиваются ru-клоном, остальные: en-клоном, а язык синтеза остаётся языком текста. У стандартных голосов Cartesia язык свой, и чужой текст они читают с акцентом. Теги смеха и эмоций Cartesia понимает, остальные теги вырезаются.","Длинный диалог режется на части: у `labs` до 1000 символов на запрос, у `cartesia` до 500, реплики без нужды не разрываются. В диалоге не больше 10 разных голосов. Субтитров у диалогов нет: ответ провайдера без таймингов."],"table":null,"code":[{"language":"python","code":"created = s.post(f\"{BASE}/v2/dialogues\", json=body, timeout=60).json()\ntask_id = created[\"task_id\"]\nwhile True:\n task = s.get(f\"{BASE}/v2/tasks/{task_id}\", timeout=30).json()\n if task[\"status\"] in {\"completed\", \"failed\", \"cancelled\", \"censored\"}:\n break\n time.sleep(3)\nfile = s.get(f\"{BASE}/v2/tasks/{task_id}/download\", timeout=180)\n","title":"Дождаться результата"}]},{"id":"dialogue-text","title":"Как писать текст","paragraphs":["В `text` реплика начинается со строки `[voice_id]: текст`. `voice_id` это тот же ID голоса, что в обычной задаче. Строка без пометки в начале продолжает предыдущую реплику, так реплика занимает несколько строк. Пустые строки в начале текста пропускаются."],"table":null,"code":[{"language":"text","code":"[EXAVITQu4vr4xnSDxMaL]: [excited] Have you heard about dialogues?\n[CwhRBWXzGAHq8TQ4Fs17]: [laughs] I have.\nLet's check how it sounds.","title":"Текст диалога целиком"}]}],"endpoints":["dialogues-create"],"nuances":["dialogue-retry"]},{"id":"results","title":"Результат","intro":["Скачивать можно только задачу `completed`. Аудио хранится ограниченное время после завершения, затем удаляется и /download отвечает `410 result_expired`. Скачивайте результат сразу, как задача готова."],"topics":[],"endpoints":["tasks-download","tasks-download-link","tasks-file"],"nuances":["split-output","download-first","result-retention"]},{"id":"subtitles","title":"Субтитры","intro":["Есть два способа получить субтитры к озвучке. Они отличаются скоростью и движками, для которых работают."],"topics":[{"id":"subtitles-choice","title":"Какой способ выбрать","paragraphs":["Надёжная стратегия: сначала запросить /subtitles, а при `409 no_timestamps` перейти на /v2/captions."],"table":{"columns":["","/v2/tasks/{task_id}/subtitles","/v2/captions"],"rows":[["Источник","Метки ElevenLabs при озвучке","Распознавание речи"],["Движки","Только `original`","Любые, включая `cartesia`"],["Скорость","Мгновенно","Секунды или минуты"],["Форматы","`srt`, `vtt`, `json`","`srt`, `vtt`"],["Статус задачи","`completed` или `censored`","Готовая озвучка"]]},"code":[]}],"endpoints":["tasks-subtitles","captions-create","captions-upload"],"nuances":["auto-pause","split-output","result-retention","cartesia-subtitles"]},{"id":"studio","title":"Музыка и эффекты","intro":["Генерация музыки и коротких звуков. Оба метода синхронные, без очереди задач и без списания символов. Нужна активная подписка."],"topics":[],"endpoints":["studio-music","studio-sound"],"nuances":["studio-subscription"]},{"id":"error-codes","title":"Коды ошибок","intro":["Значение `detail.code` в ответе с ошибкой. Ветвите логику клиента по коду, а не по тексту `message`. Ответы `401` без кода и `422` валидации описаны в разделе [Формат ошибок](#errors-format)."],"topics":[],"endpoints":[],"nuances":[]}],"endpoints":[{"id":"auth-me","method":"GET","path":"/v2/auth/me","title":"Чей это токен","summary":"Возвращает пользователя и лицензию, которым принадлежит токен. Удобно для проверки токена при старте клиента.","auth":"token","params":[],"content_type":null,"response_type":"application/json","response":[{"name":"user_id","type":"string","description":"ID пользователя"},{"name":"token_id","type":"integer","description":"ID лицензии (API-токена)"}],"errors":[{"status":401,"code":null,"when":"Нет заголовка или токен недействителен"}],"examples":[{"title":"Проверить токен","curl":"curl \"https://voicer.mat3u.com/v2/auth/me\" \\\n -H \"Authorization: Bearer $VOICER_TOKEN\"","python":"r = s.get(f\"{BASE}/v2/auth/me\", timeout=30)\nr.raise_for_status()\nprint(r.json())","status":200,"response":"{\n \"user_id\": \"3f6c2a9e-8d41-4b7a-9c55-1e2f0a7d4b13\",\n \"token_id\": 5521\n}"}],"notes":[],"section":"account","anchor":"#auth-me"},{"id":"billing-me","method":"GET","path":"/v2/billing/me","title":"Баланс и тариф лицензии","summary":"Подписка, тариф и остаток символов лицензии из заголовка Authorization. Перед большой задачей проверьте `remaining_characters` и лимиты `tariff`.","auth":"token","params":[],"content_type":null,"response_type":"application/json","response":[{"name":"user_id","type":"string","description":"ID пользователя"},{"name":"user_active","type":"boolean","description":"`false`: пользователь заблокирован"},{"name":"token_id","type":"integer | null","description":"Лицензия, для которой посчитан баланс"},{"name":"subscription_type","type":"string","description":"`characters`, `unlimited` или `no_subscription`"},{"name":"subscription_expires_at","type":"datetime | null","description":"Конец безлимитной подписки"},{"name":"subscription_active","type":"boolean","description":"Можно ли сейчас ставить задачи (подписка и баланс)"},{"name":"total_characters","type":"integer","description":"Начислено в действующих пакетах"},{"name":"used_characters","type":"integer","description":"Списано из действующих пакетов"},{"name":"remaining_characters","type":"integer","description":"Остаток"},{"name":"tariff","type":"object | null","description":"Лимиты тарифа, как в /v2/billing/tariffs"},{"name":"packages","type":"array","description":"Действующие пакеты с остатком в порядке списания, у каждого свой срок"},{"name":"tariff_code","type":"string | null","description":"Код тарифа"}],"errors":[{"status":401,"code":null,"when":"Нет заголовка Authorization или токен недействителен"},{"status":404,"code":null,"when":"Пользователь токена не найден"}],"examples":[{"title":"Пакет символов","curl":"curl \"https://voicer.mat3u.com/v2/billing/me\" \\\n -H \"Authorization: Bearer $VOICER_TOKEN\"","python":"r = s.get(f\"{BASE}/v2/billing/me\", timeout=30)\nr.raise_for_status()\nprint(r.json())","status":200,"response":"{\n \"user_id\": \"3f6c2a9e-8d41-4b7a-9c55-1e2f0a7d4b13\",\n \"user_active\": true,\n \"token_id\": 5521,\n \"subscription_type\": \"characters\",\n \"subscription_expires_at\": null,\n \"subscription_active\": true,\n \"total_characters\": 1000000,\n \"used_characters\": 412870,\n \"remaining_characters\": 587130,\n \"tariff_code\": \"characters\",\n \"tariff\": {\n \"code\": \"characters\",\n \"name\": \"Characters\",\n \"kind\": \"package\",\n \"max_parallel_tasks\": 5,\n \"threads_per_task\": 15,\n \"max_chunks_per_task\": null,\n \"max_chars_per_task\": 200000,\n \"allow_original\": true,\n \"allow_original_accs\": false,\n \"allow_cartesia\": true,\n \"max_cartesia_clones\": 5,\n \"sort_order\": 0\n },\n \"packages\": [\n {\n \"id\": 18342,\n \"chars_granted\": 1000000,\n \"chars_used\": 412870,\n \"expires_at\": \"2026-11-09T12:04:51Z\",\n \"tariff_code\": \"characters\",\n \"source_type\": \"payment\",\n \"created_at\": \"2026-10-10T12:04:51Z\",\n \"remaining\": 587130\n }\n ]\n}"}],"notes":[],"section":"account","anchor":"#billing-me"},{"id":"billing-stats","method":"GET","path":"/v2/billing/stats","title":"Сводка: баланс, задачи, клоны","summary":"Баланс лицензии, счётчики задач и использованная квота клонов Cartesia одним запросом.","auth":"token","params":[],"content_type":null,"response_type":"application/json","response":[{"name":"subscription_type","type":"string","description":"`characters`, `unlimited` или `no_subscription`"},{"name":"subscription_expires_at","type":"datetime | null","description":"Конец безлимитной подписки"},{"name":"subscription_active","type":"boolean","description":"Можно ли сейчас ставить задачи (подписка и баланс)"},{"name":"total_characters","type":"integer","description":"Начислено в действующих пакетах"},{"name":"used_characters","type":"integer","description":"Списано из действующих пакетов"},{"name":"remaining_characters","type":"integer","description":"Остаток"},{"name":"tariff","type":"object | null","description":"Лимиты тарифа, как в /v2/billing/tariffs"},{"name":"packages","type":"array","description":"Действующие пакеты с остатком в порядке списания, у каждого свой срок"},{"name":"total_tasks","type":"integer","description":"Всего задач"},{"name":"completed_tasks","type":"integer","description":"Завершённых"},{"name":"active_tasks","type":"integer","description":"В очереди или в работе сейчас"},{"name":"clones_used","type":"integer","description":"Своих клонов Cartesia (идут в квоту)"},{"name":"clones_limit","type":"integer | null","description":"Квота клонов, `null` без лимита"}],"errors":[{"status":401,"code":null,"when":"Нет заголовка Authorization или токен недействителен"},{"status":404,"code":null,"when":"Пользователь токена не найден"}],"examples":[{"title":"Сводка","curl":"curl \"https://voicer.mat3u.com/v2/billing/stats\" \\\n -H \"Authorization: Bearer $VOICER_TOKEN\"","python":"r = s.get(f\"{BASE}/v2/billing/stats\", timeout=30)\nr.raise_for_status()\nprint(r.json())","status":200,"response":"{\n \"user_id\": \"3f6c2a9e-8d41-4b7a-9c55-1e2f0a7d4b13\",\n \"subscription_type\": \"characters\",\n \"subscription_expires_at\": null,\n \"subscription_active\": true,\n \"total_characters\": 1000000,\n \"used_characters\": 412870,\n \"remaining_characters\": 587130,\n \"tariff_code\": \"characters\",\n \"tariff\": {\n \"code\": \"characters\",\n \"name\": \"Characters\",\n \"kind\": \"package\",\n \"max_parallel_tasks\": 5,\n \"threads_per_task\": 15,\n \"max_chunks_per_task\": null,\n \"max_chars_per_task\": 200000,\n \"allow_original\": true,\n \"allow_original_accs\": false,\n \"allow_cartesia\": true,\n \"max_cartesia_clones\": 5,\n \"sort_order\": 0\n },\n \"total_tasks\": 214,\n \"completed_tasks\": 203,\n \"active_tasks\": 1,\n \"clones_used\": 2,\n \"clones_limit\": 5,\n \"packages\": [\n {\n \"id\": 18342,\n \"chars_granted\": 1000000,\n \"chars_used\": 412870,\n \"expires_at\": \"2026-11-09T12:04:51Z\",\n \"tariff_code\": \"characters\",\n \"source_type\": \"payment\",\n \"created_at\": \"2026-10-10T12:04:51Z\",\n \"remaining\": 587130\n }\n ]\n}"}],"notes":[],"section":"account","anchor":"#billing-stats"},{"id":"billing-tariffs","method":"GET","path":"/v2/billing/tariffs","title":"Тарифы","summary":"Действующие тарифы и их лимиты. Покупка пакетов и подписок в Telegram-боте.","auth":"none","params":[],"content_type":null,"response_type":"application/json","response":[{"name":"code","type":"string","description":"Код тарифа"},{"name":"kind","type":"string","description":"`package` (пакет символов) или `subscription` (подписка)"},{"name":"max_parallel_tasks","type":"integer","description":"Одновременных задач на лицензию"},{"name":"threads_per_task","type":"integer","description":"Параллельных потоков озвучки одной задачи"},{"name":"max_chunks_per_task","type":"integer | null","description":"Лимит чанков в задаче"},{"name":"max_chars_per_task","type":"integer | null","description":"Лимит символов в задаче"},{"name":"allow_original","type":"boolean","description":"Разрешён движок `original` (ElevenLabs)"},{"name":"allow_cartesia","type":"boolean","description":"Разрешён движок `cartesia`"},{"name":"max_cartesia_clones","type":"integer | null","description":"Квота своих клонов: `0` запрещены, `null` без лимита"}],"errors":[],"examples":[{"title":"Список тарифов","curl":"curl \"https://voicer.mat3u.com/v2/billing/tariffs\"","python":"r = requests.get(f\"{BASE}/v2/billing/tariffs\", timeout=30)\nr.raise_for_status()\nprint(r.json())","status":200,"response":"[\n {\n \"code\": \"characters\",\n \"name\": \"Characters\",\n \"kind\": \"package\",\n \"max_parallel_tasks\": 5,\n \"threads_per_task\": 15,\n \"max_chunks_per_task\": null,\n \"max_chars_per_task\": 200000,\n \"allow_original\": true,\n \"allow_original_accs\": false,\n \"allow_cartesia\": true,\n \"max_cartesia_clones\": 5,\n \"sort_order\": 0\n }\n]"}],"notes":[],"section":"account","anchor":"#billing-tariffs"},{"id":"voices-elevenlabs","method":"GET","path":"/v2/voices/elevenlabs","title":"Стандартные голоса ElevenLabs","summary":"Голоса, которые принимает задача с `engine=original`. Список статичный, отсортирован по имени.","auth":"token","params":[],"content_type":null,"response_type":"application/json","response":[{"name":"[].voice_id","type":"string","description":"Значение для `voice_id` задачи"},{"name":"[].name","type":"string","description":"Имя голоса"}],"errors":[{"status":401,"code":null,"when":"Нет заголовка Authorization или токен недействителен"}],"examples":[{"title":"Список","curl":"curl \"https://voicer.mat3u.com/v2/voices/elevenlabs\" \\\n -H \"Authorization: Bearer $VOICER_TOKEN\"","python":"r = s.get(f\"{BASE}/v2/voices/elevenlabs\", timeout=30)\nr.raise_for_status()\nprint(r.json())","status":200,"response":"[\n {\n \"voice_id\": \"pNInz6obpgDQGcFmaJgB\",\n \"name\": \"Adam\"\n },\n {\n \"voice_id\": \"Xb7hH8MSUJpSbSDYk0k2\",\n \"name\": \"Alice\"\n }\n]"}],"notes":[],"section":"voices","anchor":"#voices-elevenlabs"},{"id":"voices-elevenlabs-search","method":"GET","path":"/v2/voices/elevenlabs/search","title":"Поиск в библиотеке ElevenLabs","summary":"Бесплатные голоса публичной библиотеки ElevenLabs по имени, описанию или ID. Это источник для [клонирования в Cartesia](#cartesia-clone).","auth":"token","params":[{"name":"q","where":"query","type":"string","description":"Имя, описание или ID голоса. Если похоже на ID, голос с этим ID идёт первым","required":true,"default":null,"constraints":"1-100 символов, не только пробелы","values":[],"fields":[]}],"content_type":null,"response_type":"application/json","response":[{"name":"query","type":"string","description":"Запрос как его понял сервер"},{"name":"items","type":"array","description":"Голоса: сначала найденный по ID, затем по имени"},{"name":"items[].voice_id","type":"string","description":"ID голоса ElevenLabs: подходит для клонирования"},{"name":"items[].name","type":"string","description":"Имя"},{"name":"items[].source","type":"string","description":"`account` найден по ID в аккаунте, `library` публичная библиотека"},{"name":"items[].language, accent, gender, age, use_case","type":"string | null","description":"Метки голоса"},{"name":"items[].preview_url","type":"string | null","description":"Публичный семпл ElevenLabs"}],"errors":[{"status":401,"code":null,"when":"Нет заголовка Authorization или токен недействителен"},{"status":503,"code":"elevenlabs_unavailable","when":"ElevenLabs не ответил, повторите позже"}],"examples":[{"title":"Поиск по имени","curl":"curl -G \"https://voicer.mat3u.com/v2/voices/elevenlabs/search\" \\\n --data-urlencode \"q=Ярослав\" \\\n -H \"Authorization: Bearer $VOICER_TOKEN\"","python":"r = s.get(\n f\"{BASE}/v2/voices/elevenlabs/search\",\n params={\n \"q\": \"Ярослав\",\n },\n timeout=30,\n)\nr.raise_for_status()\nprint(r.json())","status":200,"response":"{\n \"query\": \"Ярослав\",\n \"items\": [\n {\n \"voice_id\": \"Wu3B7bOkdHbKnJTvbiFk\",\n \"name\": \"Ярослав\",\n \"source\": \"library\",\n \"public_owner_id\": \"6d3c0e1b0f5a4c3f8a1e9b2d7c4f6a10\",\n \"category\": \"high_quality\",\n \"description\": \"Спокойный глубокий голос для озвучки роликов\",\n \"language\": \"ru\",\n \"accent\": \"standard\",\n \"gender\": \"male\",\n \"age\": \"middle_aged\",\n \"use_case\": \"narrative_story\",\n \"preview_url\": \"https://storage.googleapis.com/eleven-public-prod/previews/Wu3B7.mp3\"\n }\n ]\n}"}],"notes":["Голоса библиотеки нельзя напрямую передать в задачу с `engine=original`: сервис принимает только [стандартные голоса](#voices-elevenlabs). Чтобы озвучить библиотечным голосом, склонируйте его в Cartesia по `elevenlabs_voice_id`."],"section":"voices","anchor":"#voices-elevenlabs-search"},{"id":"voices-elevenlabs-featured","method":"GET","path":"/v2/voices/elevenlabs/featured","title":"Подборка русских голосов ElevenLabs","summary":"Бесплатные русскоязычные голоса библиотеки высокого качества, новые сверху. Ответ кэшируется на несколько минут.","auth":"token","params":[{"name":"page","where":"query","type":"integer","description":"Номер страницы с нуля","required":false,"default":"0","constraints":"0-10000","values":[],"fields":[]},{"name":"page_size","where":"query","type":"integer","description":"Размер страницы","required":false,"default":"50","constraints":"1-50","values":[],"fields":[]}],"content_type":null,"response_type":"application/json","response":[{"name":"items","type":"array","description":"Голоса, поля как в поиске"},{"name":"page, page_size","type":"integer","description":"Страница запроса"},{"name":"has_more","type":"boolean","description":"Есть следующая страница"}],"errors":[{"status":401,"code":null,"when":"Нет заголовка Authorization или токен недействителен"},{"status":503,"code":"elevenlabs_unavailable","when":"ElevenLabs не ответил, повторите позже"}],"examples":[{"title":"Первая страница по 10","curl":"curl -G \"https://voicer.mat3u.com/v2/voices/elevenlabs/featured\" \\\n --data-urlencode \"page=0\" \\\n --data-urlencode \"page_size=10\" \\\n -H \"Authorization: Bearer $VOICER_TOKEN\"","python":"r = s.get(\n f\"{BASE}/v2/voices/elevenlabs/featured\",\n params={\n \"page\": 0,\n \"page_size\": 10,\n },\n timeout=30,\n)\nr.raise_for_status()\nprint(r.json())","status":200,"response":"{\n \"items\": [\n {\n \"voice_id\": \"Wu3B7bOkdHbKnJTvbiFk\",\n \"name\": \"Ярослав\",\n \"source\": \"library\",\n \"public_owner_id\": \"6d3c0e1b0f5a4c3f8a1e9b2d7c4f6a10\",\n \"category\": \"high_quality\",\n \"description\": \"Спокойный глубокий голос для озвучки роликов\",\n \"language\": \"ru\",\n \"accent\": \"standard\",\n \"gender\": \"male\",\n \"age\": \"middle_aged\",\n \"use_case\": \"narrative_story\",\n \"preview_url\": \"https://storage.googleapis.com/eleven-public-prod/previews/Wu3B7.mp3\"\n }\n ],\n \"page\": 0,\n \"page_size\": 10,\n \"has_more\": true\n}"}],"notes":[],"section":"voices","anchor":"#voices-elevenlabs-featured"},{"id":"voices-models","method":"GET","path":"/v2/voices/models","title":"Модели","summary":"Допустимые `model_id` по движкам. Модель по умолчанию идёт первой и отмечена `default: true`.","auth":"token","params":[],"content_type":null,"response_type":"application/json","response":[{"name":"elevenlabs","type":"array","description":"Модели для `engine=original`"},{"name":"cartesia","type":"array","description":"Модели для `engine=cartesia`"},{"name":"*[].model_id","type":"string","description":"Значение для `model_id` задачи"},{"name":"*[].default","type":"boolean","description":"Модель по умолчанию"}],"errors":[{"status":401,"code":null,"when":"Нет заголовка Authorization или токен недействителен"}],"examples":[{"title":"Модели","curl":"curl \"https://voicer.mat3u.com/v2/voices/models\" \\\n -H \"Authorization: Bearer $VOICER_TOKEN\"","python":"r = s.get(f\"{BASE}/v2/voices/models\", timeout=30)\nr.raise_for_status()\nprint(r.json())","status":200,"response":"{\n \"elevenlabs\": [\n {\n \"model_id\": \"eleven_multilingual_v2\",\n \"default\": true\n },\n {\n \"model_id\": \"eleven_v3\",\n \"default\": false\n }\n ],\n \"cartesia\": [\n {\n \"model_id\": \"sonic-3.6\",\n \"default\": true\n },\n {\n \"model_id\": \"sonic-3.5\",\n \"default\": false\n }\n ]\n}"}],"notes":[],"section":"voices","anchor":"#voices-models"},{"id":"cartesia-voices","method":"GET","path":"/v2/voices/cartesia","title":"Свои клоны и общий каталог","summary":"Свои клоны и общий каталог клонов ElevenLabs одним списком.","auth":"token","params":[{"name":"language","where":"query","type":"string","description":"Фильтр по языку: код Cartesia (`ru`, `de`, `uk`). Пусто: любой язык","required":false,"default":null,"constraints":"до 16 символов","values":[],"fields":[]},{"name":"source","where":"query","type":"string","description":"Только один источник; без параметра оба","required":false,"default":null,"constraints":null,"values":[{"value":"user","description":"Свои клоны"},{"value":"elevenlabs","description":"Общий каталог клонов голосов ElevenLabs"}],"fields":[]},{"name":"q","where":"query","type":"string","description":"Поиск по имени и ID","required":false,"default":null,"constraints":"до 100 символов","values":[],"fields":[]},{"name":"page","where":"query","type":"integer","description":"Номер страницы с нуля","required":false,"default":"0","constraints":"0-10000","values":[],"fields":[]},{"name":"page_size","where":"query","type":"integer","description":"Размер страницы","required":false,"default":"50","constraints":"1-50","values":[],"fields":[]}],"content_type":null,"response_type":"application/json","response":[{"name":"items","type":"array","description":"Голоса, поля ниже"},{"name":"total","type":"integer","description":"Всего голосов под фильтром"},{"name":"page, page_size","type":"integer","description":"Страница запроса"},{"name":"has_more","type":"boolean","description":"Есть следующая страница"},{"name":"items[].voice_id","type":"string","description":"ID для `voice_id` задачи с `engine=cartesia`"},{"name":"items[].name, tagline, description","type":"string | null","description":"Описание голоса"},{"name":"items[].language","type":"string | null","description":"Язык голоса; у клонов `ru` или `en`"},{"name":"items[].accent","type":"string | null","description":"Акцент"},{"name":"items[].gender","type":"string | null","description":"Пол, только у стандартных голосов"},{"name":"items[].source","type":"string","description":"`standard` библиотека Cartesia, `elevenlabs` общий каталог клонов, `user` свой клон"},{"name":"items[].preview_url","type":"string | null","description":"Семпл для плеера без токена"},{"name":"items[].elevenlabs_voice_id","type":"string | null","description":"Исходный голос ElevenLabs у клона"},{"name":"items[].labs_is_paid","type":"boolean | null","description":"Исходный голос ElevenLabs платный"},{"name":"items[].is_owner","type":"boolean","description":"Это ваш клон"},{"name":"items[].created_at","type":"datetime | null","description":"Когда создан клон"}],"errors":[{"status":401,"code":null,"when":"Нет заголовка Authorization или токен недействителен"},{"status":402,"code":"subscription_required","when":"Нет подписки или символов"},{"status":402,"code":"subscription_expired","when":"Безлимитная подписка закончилась"},{"status":403,"code":"engine_not_allowed","when":"Тариф не разрешает движок cartesia"},{"status":403,"code":"user_blocked","when":"Пользователь заблокирован"}],"examples":[{"title":"Русские голоса из обоих источников","curl":"curl -G \"https://voicer.mat3u.com/v2/voices/cartesia\" \\\n --data-urlencode \"language=ru\" \\\n -H \"Authorization: Bearer $VOICER_TOKEN\"","python":"r = s.get(\n f\"{BASE}/v2/voices/cartesia\",\n params={\n \"language\": \"ru\",\n },\n timeout=30,\n)\nr.raise_for_status()\nprint(r.json())","status":200,"response":"{\n \"items\": [\n {\n \"voice_id\": \"c41f7b20-95de-4a1b-8e33-7a6d2f0c9b85\",\n \"name\": \"Мой голос\",\n \"tagline\": null,\n \"description\": null,\n \"language\": \"ru\",\n \"accent\": null,\n \"gender\": null,\n \"source\": \"user\",\n \"preview_url\": null,\n \"elevenlabs_voice_id\": null,\n \"labs_is_paid\": null,\n \"is_owner\": true,\n \"created_at\": \"2026-10-11T10:02:11Z\"\n },\n {\n \"voice_id\": \"8d0a6f1e-3b52-4c9e-a7d4-52e1c09b7f36\",\n \"name\": \"Ярослав\",\n \"tagline\": null,\n \"description\": \"Спокойный глубокий голос для озвучки роликов\",\n \"language\": \"ru\",\n \"accent\": null,\n \"gender\": null,\n \"source\": \"elevenlabs\",\n \"preview_url\": \"https://storage.googleapis.com/eleven-public-prod/previews/Wu3B7.mp3\",\n \"elevenlabs_voice_id\": \"Wu3B7bOkdHbKnJTvbiFk\",\n \"labs_is_paid\": false,\n \"is_owner\": false,\n \"created_at\": \"2026-09-02T08:15:40Z\"\n }\n ],\n \"total\": 2,\n \"page\": 0,\n \"page_size\": 50,\n \"has_more\": false\n}"}],"notes":[],"section":"cartesia","anchor":"#cartesia-voices"},{"id":"cartesia-catalog","method":"GET","path":"/v2/voices/cartesia/catalog","title":"Общий каталог клонов","summary":"Клоны голосов ElevenLabs, доступные всем пользователям. Ими можно озвучивать без своих слотов клонов.","auth":"token","params":[{"name":"language","where":"query","type":"string","description":"Фильтр по языку: код Cartesia (`ru`, `de`, `uk`). Пусто: любой язык","required":false,"default":null,"constraints":"до 16 символов","values":[],"fields":[]},{"name":"paid","where":"query","type":"boolean","description":"Фильтр по исходному голосу ElevenLabs; без параметра все","required":false,"default":null,"constraints":null,"values":[{"value":"true","description":"Клоны платных голосов ElevenLabs"},{"value":"false","description":"Клоны бесплатных голосов"}],"fields":[]},{"name":"page","where":"query","type":"integer","description":"Номер страницы с нуля","required":false,"default":"0","constraints":"0-10000","values":[],"fields":[]},{"name":"page_size","where":"query","type":"integer","description":"Размер страницы","required":false,"default":"50","constraints":"1-50","values":[],"fields":[]}],"content_type":null,"response_type":"application/json","response":[{"name":"items","type":"array","description":"Голоса, поля ниже"},{"name":"total","type":"integer","description":"Всего голосов под фильтром"},{"name":"page, page_size","type":"integer","description":"Страница запроса"},{"name":"has_more","type":"boolean","description":"Есть следующая страница"},{"name":"items[].voice_id","type":"string","description":"ID для `voice_id` задачи с `engine=cartesia`"},{"name":"items[].name, tagline, description","type":"string | null","description":"Описание голоса"},{"name":"items[].language","type":"string | null","description":"Язык голоса; у клонов `ru` или `en`"},{"name":"items[].accent","type":"string | null","description":"Акцент"},{"name":"items[].gender","type":"string | null","description":"Пол, только у стандартных голосов"},{"name":"items[].source","type":"string","description":"`standard` библиотека Cartesia, `elevenlabs` общий каталог клонов, `user` свой клон"},{"name":"items[].preview_url","type":"string | null","description":"Семпл для плеера без токена"},{"name":"items[].elevenlabs_voice_id","type":"string | null","description":"Исходный голос ElevenLabs у клона"},{"name":"items[].labs_is_paid","type":"boolean | null","description":"Исходный голос ElevenLabs платный"},{"name":"items[].is_owner","type":"boolean","description":"Это ваш клон"},{"name":"items[].created_at","type":"datetime | null","description":"Когда создан клон"}],"errors":[{"status":401,"code":null,"when":"Нет заголовка Authorization или токен недействителен"},{"status":402,"code":"subscription_required","when":"Нет подписки или символов"},{"status":402,"code":"subscription_expired","when":"Безлимитная подписка закончилась"},{"status":403,"code":"engine_not_allowed","when":"Тариф не разрешает движок cartesia"},{"status":403,"code":"user_blocked","when":"Пользователь заблокирован"}],"examples":[{"title":"Каталог на русском","curl":"curl -G \"https://voicer.mat3u.com/v2/voices/cartesia/catalog\" \\\n --data-urlencode \"language=ru\" \\\n --data-urlencode \"page=0\" \\\n --data-urlencode \"page_size=50\" \\\n -H \"Authorization: Bearer $VOICER_TOKEN\"","python":"r = s.get(\n f\"{BASE}/v2/voices/cartesia/catalog\",\n params={\n \"language\": \"ru\",\n \"page\": 0,\n \"page_size\": 50,\n },\n timeout=30,\n)\nr.raise_for_status()\nprint(r.json())","status":200,"response":"{\n \"items\": [\n {\n \"voice_id\": \"8d0a6f1e-3b52-4c9e-a7d4-52e1c09b7f36\",\n \"name\": \"Ярослав\",\n \"tagline\": null,\n \"description\": \"Спокойный глубокий голос для озвучки роликов\",\n \"language\": \"ru\",\n \"accent\": null,\n \"gender\": null,\n \"source\": \"elevenlabs\",\n \"preview_url\": \"https://storage.googleapis.com/eleven-public-prod/previews/Wu3B7.mp3\",\n \"elevenlabs_voice_id\": \"Wu3B7bOkdHbKnJTvbiFk\",\n \"labs_is_paid\": false,\n \"is_owner\": false,\n \"created_at\": \"2026-09-02T08:15:40Z\"\n }\n ],\n \"total\": 1,\n \"page\": 0,\n \"page_size\": 50,\n \"has_more\": false\n}"}],"notes":[],"section":"cartesia","anchor":"#cartesia-catalog"},{"id":"cartesia-mine","method":"GET","path":"/v2/voices/cartesia/mine","title":"Мои клоны и квота","summary":"Только свои клоны и сколько слотов клонов занято.","auth":"token","params":[{"name":"language","where":"query","type":"string","description":"Фильтр по языку: код Cartesia (`ru`, `de`, `uk`). Пусто: любой язык","required":false,"default":null,"constraints":"до 16 символов","values":[],"fields":[]},{"name":"q","where":"query","type":"string","description":"Поиск по имени и ID","required":false,"default":null,"constraints":"до 100 символов","values":[],"fields":[]},{"name":"page","where":"query","type":"integer","description":"Номер страницы с нуля","required":false,"default":"0","constraints":"0-10000","values":[],"fields":[]},{"name":"page_size","where":"query","type":"integer","description":"Размер страницы","required":false,"default":"50","constraints":"1-50","values":[],"fields":[]}],"content_type":null,"response_type":"application/json","response":[{"name":"items","type":"array","description":"Голоса, поля ниже"},{"name":"total","type":"integer","description":"Всего голосов под фильтром"},{"name":"page, page_size","type":"integer","description":"Страница запроса"},{"name":"has_more","type":"boolean","description":"Есть следующая страница"},{"name":"clones_used","type":"integer","description":"Своих клонов в любом статусе (идут в квоту)"},{"name":"clones_limit","type":"integer | null","description":"Квота тарифа: `null` без лимита, `0` запрещены"},{"name":"items[].voice_id","type":"string","description":"ID для `voice_id` задачи с `engine=cartesia`"},{"name":"items[].name, tagline, description","type":"string | null","description":"Описание голоса"},{"name":"items[].language","type":"string | null","description":"Язык голоса; у клонов `ru` или `en`"},{"name":"items[].accent","type":"string | null","description":"Акцент"},{"name":"items[].gender","type":"string | null","description":"Пол, только у стандартных голосов"},{"name":"items[].source","type":"string","description":"`standard` библиотека Cartesia, `elevenlabs` общий каталог клонов, `user` свой клон"},{"name":"items[].preview_url","type":"string | null","description":"Семпл для плеера без токена"},{"name":"items[].elevenlabs_voice_id","type":"string | null","description":"Исходный голос ElevenLabs у клона"},{"name":"items[].labs_is_paid","type":"boolean | null","description":"Исходный голос ElevenLabs платный"},{"name":"items[].is_owner","type":"boolean","description":"Это ваш клон"},{"name":"items[].created_at","type":"datetime | null","description":"Когда создан клон"}],"errors":[{"status":401,"code":null,"when":"Нет заголовка Authorization или токен недействителен"},{"status":402,"code":"subscription_required","when":"Нет подписки или символов"},{"status":402,"code":"subscription_expired","when":"Безлимитная подписка закончилась"},{"status":403,"code":"engine_not_allowed","when":"Тариф не разрешает движок cartesia"},{"status":403,"code":"user_blocked","when":"Пользователь заблокирован"}],"examples":[{"title":"Мои клоны","curl":"curl \"https://voicer.mat3u.com/v2/voices/cartesia/mine\" \\\n -H \"Authorization: Bearer $VOICER_TOKEN\"","python":"r = s.get(f\"{BASE}/v2/voices/cartesia/mine\", timeout=30)\nr.raise_for_status()\nprint(r.json())","status":200,"response":"{\n \"items\": [\n {\n \"voice_id\": \"c41f7b20-95de-4a1b-8e33-7a6d2f0c9b85\",\n \"name\": \"Мой голос\",\n \"tagline\": null,\n \"description\": null,\n \"language\": \"ru\",\n \"accent\": null,\n \"gender\": null,\n \"source\": \"user\",\n \"preview_url\": null,\n \"elevenlabs_voice_id\": null,\n \"labs_is_paid\": null,\n \"is_owner\": true,\n \"created_at\": \"2026-10-11T10:02:11Z\"\n }\n ],\n \"total\": 1,\n \"page\": 0,\n \"page_size\": 50,\n \"has_more\": false,\n \"clones_used\": 1,\n \"clones_limit\": 5\n}"}],"notes":[],"section":"cartesia","anchor":"#cartesia-mine"},{"id":"cartesia-standard","method":"GET","path":"/v2/voices/cartesia/standard","title":"Стандартные голоса Cartesia","summary":"Библиотека готовых голосов Cartesia. Слоты клонов не нужны.","auth":"token","params":[{"name":"language","where":"query","type":"string","description":"Фильтр по языку: код Cartesia (`ru`, `de`, `uk`). Пусто: любой язык","required":false,"default":null,"constraints":"до 16 символов","values":[],"fields":[]},{"name":"gender","where":"query","type":"string","description":"Фильтр по полу","required":false,"default":null,"constraints":null,"values":[{"value":"masculine","description":"Мужские"},{"value":"feminine","description":"Женские"},{"value":"gender_neutral","description":"Нейтральные"}],"fields":[]},{"name":"q","where":"query","type":"string","description":"Поиск по имени и описанию","required":false,"default":null,"constraints":"до 100 символов","values":[],"fields":[]},{"name":"page","where":"query","type":"integer","description":"Номер страницы с нуля","required":false,"default":"0","constraints":"0-10000","values":[],"fields":[]},{"name":"page_size","where":"query","type":"integer","description":"Размер страницы","required":false,"default":"50","constraints":"1-50","values":[],"fields":[]}],"content_type":null,"response_type":"application/json","response":[{"name":"items","type":"array","description":"Голоса, поля ниже"},{"name":"total","type":"integer","description":"Всего голосов под фильтром"},{"name":"page, page_size","type":"integer","description":"Страница запроса"},{"name":"has_more","type":"boolean","description":"Есть следующая страница"},{"name":"items[].voice_id","type":"string","description":"ID для `voice_id` задачи с `engine=cartesia`"},{"name":"items[].name, tagline, description","type":"string | null","description":"Описание голоса"},{"name":"items[].language","type":"string | null","description":"Язык голоса; у клонов `ru` или `en`"},{"name":"items[].accent","type":"string | null","description":"Акцент"},{"name":"items[].gender","type":"string | null","description":"Пол, только у стандартных голосов"},{"name":"items[].source","type":"string","description":"`standard` библиотека Cartesia, `elevenlabs` общий каталог клонов, `user` свой клон"},{"name":"items[].preview_url","type":"string | null","description":"Семпл для плеера без токена"},{"name":"items[].elevenlabs_voice_id","type":"string | null","description":"Исходный голос ElevenLabs у клона"},{"name":"items[].labs_is_paid","type":"boolean | null","description":"Исходный голос ElevenLabs платный"},{"name":"items[].is_owner","type":"boolean","description":"Это ваш клон"},{"name":"items[].created_at","type":"datetime | null","description":"Когда создан клон"}],"errors":[{"status":401,"code":null,"when":"Нет заголовка Authorization или токен недействителен"},{"status":402,"code":"subscription_required","when":"Нет подписки или символов"},{"status":402,"code":"subscription_expired","when":"Безлимитная подписка закончилась"},{"status":403,"code":"engine_not_allowed","when":"Тариф не разрешает движок cartesia"},{"status":403,"code":"user_blocked","when":"Пользователь заблокирован"}],"examples":[{"title":"Женские русские голоса","curl":"curl -G \"https://voicer.mat3u.com/v2/voices/cartesia/standard\" \\\n --data-urlencode \"language=ru\" \\\n --data-urlencode \"gender=feminine\" \\\n -H \"Authorization: Bearer $VOICER_TOKEN\"","python":"r = s.get(\n f\"{BASE}/v2/voices/cartesia/standard\",\n params={\n \"language\": \"ru\",\n \"gender\": \"feminine\",\n },\n timeout=30,\n)\nr.raise_for_status()\nprint(r.json())","status":200,"response":"{\n \"items\": [\n {\n \"voice_id\": \"f786b574-daa5-4673-aa0c-cbe3e8534c02\",\n \"name\": \"Анна\",\n \"tagline\": \"Тёплый дикторский голос\",\n \"description\": \"Ровная подача для новостей и обучающих видео\",\n \"language\": \"ru\",\n \"accent\": null,\n \"gender\": \"feminine\",\n \"source\": \"standard\",\n \"preview_url\": \"https://voicer.mat3u.com/v2/voices/cartesia/standard/f786b574-daa5-4673-aa0c-cbe3e8534c02/preview\",\n \"elevenlabs_voice_id\": null,\n \"labs_is_paid\": null,\n \"is_owner\": false,\n \"created_at\": null\n }\n ],\n \"total\": 1,\n \"page\": 0,\n \"page_size\": 50,\n \"has_more\": false\n}"}],"notes":[],"section":"cartesia","anchor":"#cartesia-standard"},{"id":"cartesia-voice","method":"GET","path":"/v2/voices/cartesia/{voice_id}","title":"Карточка голоса Cartesia","summary":"Свой клон, клон из общего каталога или стандартный голос по ID.","auth":"token","params":[{"name":"voice_id","where":"path","type":"string","description":"ID голоса","required":true,"default":null,"constraints":"1-64","values":[],"fields":[]}],"content_type":null,"response_type":"application/json","response":[{"name":"voice_id","type":"string","description":"ID для `voice_id` задачи с `engine=cartesia`"},{"name":"name, tagline, description","type":"string | null","description":"Описание голоса"},{"name":"language","type":"string | null","description":"Язык голоса; у клонов `ru` или `en`"},{"name":"accent","type":"string | null","description":"Акцент"},{"name":"gender","type":"string | null","description":"Пол, только у стандартных голосов"},{"name":"source","type":"string","description":"`standard` библиотека Cartesia, `elevenlabs` общий каталог клонов, `user` свой клон"},{"name":"preview_url","type":"string | null","description":"Семпл для плеера без токена"},{"name":"elevenlabs_voice_id","type":"string | null","description":"Исходный голос ElevenLabs у клона"},{"name":"labs_is_paid","type":"boolean | null","description":"Исходный голос ElevenLabs платный"},{"name":"is_owner","type":"boolean","description":"Это ваш клон"},{"name":"created_at","type":"datetime | null","description":"Когда создан клон"}],"errors":[{"status":401,"code":null,"when":"Нет заголовка Authorization или токен недействителен"},{"status":402,"code":"subscription_required","when":"Нет подписки или символов"},{"status":402,"code":"subscription_expired","when":"Безлимитная подписка закончилась"},{"status":403,"code":"engine_not_allowed","when":"Тариф не разрешает движок cartesia"},{"status":403,"code":"user_blocked","when":"Пользователь заблокирован"},{"status":404,"code":"voice_not_found","when":"Голоса нет или это чужой клон"}],"examples":[{"title":"Клон из каталога","curl":"curl \"https://voicer.mat3u.com/v2/voices/cartesia/8d0a6f1e-3b52-4c9e-a7d4-52e1c09b7f36\" \\\n -H \"Authorization: Bearer $VOICER_TOKEN\"","python":"voice_id = \"8d0a6f1e-3b52-4c9e-a7d4-52e1c09b7f36\"\nr = s.get(f\"{BASE}/v2/voices/cartesia/{voice_id}\", timeout=30)\nr.raise_for_status()\nprint(r.json())","status":200,"response":"{\n \"voice_id\": \"8d0a6f1e-3b52-4c9e-a7d4-52e1c09b7f36\",\n \"name\": \"Ярослав\",\n \"tagline\": null,\n \"description\": \"Спокойный глубокий голос для озвучки роликов\",\n \"language\": \"ru\",\n \"accent\": null,\n \"gender\": null,\n \"source\": \"elevenlabs\",\n \"preview_url\": \"https://storage.googleapis.com/eleven-public-prod/previews/Wu3B7.mp3\",\n \"elevenlabs_voice_id\": \"Wu3B7bOkdHbKnJTvbiFk\",\n \"labs_is_paid\": false,\n \"is_owner\": false,\n \"created_at\": \"2026-09-02T08:15:40Z\"\n}"}],"notes":[],"section":"cartesia","anchor":"#cartesia-voice"},{"id":"cartesia-preview","method":"GET","path":"/v2/voices/cartesia/standard/{voice_id}/preview","title":"Семпл стандартного голоса","summary":"MP3-семпл стандартного голоса Cartesia. Ссылку `preview_url` из каталога можно ставить в `