Voicer APIv2

Voicer API v2

Озвучка текста голосами ElevenLabs и Cartesia, клонирование голосов, субтитры, музыка и звуковые эффекты.

Начало работы

Voicer API озвучивает текст голосами ElevenLabs и Cartesia, клонирует голоса и делает субтитры. Озвучка асинхронная: вы создаёте задачу, опрашиваете её статус и скачиваете MP3, когда она готова.

Адрес и формат

Базовый адрес: 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, запрашивайте следующую страницу.

Авторизация

Каждый запрос, кроме отмеченных «без токена», передаёт API-токен в заголовке Authorization: Bearer <токен>. Токен выдаёт Telegram-бот Voicer. Один токен соответствует одной лицензии: у неё свой баланс, тариф и лимит одновременных задач.

Без заголовка или с неверным токеном API отвечает 401 с WWW-Authenticate: Bearer. Проверить, чей токен, можно через GET /v2/auth/me.

curl https://voicer.mat3u.com/v2/auth/me \
  -H "Authorization: Bearer $VOICER_TOKEN"

Формат ошибок

Ошибка бизнес-логики приходит с HTTP-статусом и телом {"detail": {"code": "...", "message": "..."}}. code стабилен, по нему стоит ветвить логику клиента; message написан для человека и может меняться. Рядом с ними бывают поля с подробностями, например required и available при нехватке символов. Полный список кодов в разделе Коды ошибок.

Ошибка авторизации приходит строкой: {"detail": "Недействительный токен"}.

Неверный тип или формат поля даёт 422 в стандартном формате FastAPI: {"detail": [{"loc": ["body", "max_chunk_length"], "msg": "...", "type": "..."}]}. Лишние поля в JSON-телах задач запрещены и тоже дают 422.

402 Payment Required
{
  "detail": {
    "code": "insufficient_characters",
    "message": "Недостаточно символов: нужно 12000, осталось 3400",
    "required": 12000,
    "available": 3400
  }
}

Быстрый старт на Python

Полный цикл: создать задачу, дождаться результата и сохранить MP3. Остальные примеры на Python в этом справочнике используют сессию s и переменную BASE из этого кода. Нужен пакет requests и переменная окружения VOICER_TOKEN.

import os
import time

import requests

BASE = "https://voicer.mat3u.com"
s = requests.Session()
s.headers["Authorization"] = f"Bearer {os.environ['VOICER_TOKEN']}"


def synthesize(text: str, voice_id: str, out_path: str) -> None:
    created = s.post(f"{BASE}/v2/tasks", json={"text": text, "voice_id": voice_id}, timeout=60)
    if created.status_code != 202:
        raise RuntimeError(created.json()["detail"])
    task_id = created.json()["task_id"]

    while True:
        task = s.get(f"{BASE}/v2/tasks/{task_id}", timeout=30).json()
        if task["status"] in ("pending", "processing", "pending_confirmation"):
            time.sleep(3)
            continue
        break

    if task["status"] == "censored":
        # Перепишите заблокированные фрагменты и отправьте их в /retry (раздел «Задачи»).
        raise RuntimeError(f"Цензура: {task['blocked_chunks']}")
    if task["status"] != "completed":
        raise RuntimeError(f"Задача {task['status']}: {task['error']}")

    with s.get(f"{BASE}/v2/tasks/{task_id}/download", stream=True, timeout=600) as r:
        r.raise_for_status()
        with open(out_path, "wb") as f:
            for piece in r.iter_content(1 << 16):
                f.write(piece)


synthesize("Привет! Это тест Voicer API.", "JBFqnCBsd6RMkjVDRZzb", "voice.mp3")

Справочник для нейросети

Весь этот справочник в машиночитаемом виде лежит по адресу /docs.json: разделы, эндпоинты, параметры со всеми значениями, примеры на curl и Python, ошибки и нюансы. Передайте файл модели целиком как контекст. OpenAPI-схема для генераторов клиентов: /openapi.json, интерактивный Swagger: /docs/swagger.

Основные понятия

Движки озвучки

Параметр engine задачи выбирает провайдера. От движка зависят допустимые голоса, модели и максимальный размер чанка.

Если engine не указан, берётся original, а на тарифе без него (например, Cartesia) cartesia. Движок, закрытый тарифом, даёт 403 с кодом engine_not_allowed. Что разрешено вашей лицензии, смотрите в tariff ответа GET /v2/billing/me.

engineПровайдерГолосаМодель по умолчанию
originalElevenLabsСтандартные голоса ElevenLabs (список)eleven_multilingual_v2
cartesiaCartesiaСтандартные голоса Cartesia, свои клоны и общий каталог клоновsonic-3.6

Символы, пакеты и лицензия

Озвучка тарифицируется в символах исходного текста: len(text), включая пробелы и переносы строк. Символы списываются сразу при создании задачи и возвращаются, если задачу отменили до начала озвучки, если её не удалось поставить в очередь или если озвучка закончилась статусом failed.

Символы лежат в пакетах, у каждого свой срок. Списание идёт из пакета, который сгорает раньше. На безлимитной подписке символы не списываются (charged_characters = 0), но действуют лимиты тарифа.

Лимиты тарифа: одновременных задач на лицензию (max_parallel_tasks), символов в задаче (max_chars_per_task), чанков в задаче (max_chunks_per_task), разрешённые движки и квота своих клонов Cartesia (max_cartesia_clones). null в лимите означает «без ограничения».

Жизненный цикл задачи

Задача проходит статусы pending (в очереди), processing (озвучивается) и заканчивается одним из конечных. Опрашивайте GET /v2/tasks/{task_id} раз в 2-5 секунд.

СтатусЧто значитЧто делать
pendingВ очереди, символы списаныЖдать. Можно отменить
processingОзвучивается, растёт progress_percentЖдать
pending_confirmationОсновной TTS временно деградировал, задача ждёт решения оператораЖдать, задача продолжится или завершится сама
completedГотовоСкачать результат
censoredElevenLabs заблокировал часть фрагментов, остальное озвученоИсправить текст фрагментов из blocked_chunks и вызвать /retry
failedОшибка, подробности в error; символы возвращеныСоздать задачу заново
cancelledОтмененаНичего

Чанки

Перед озвучкой текст режется на чанки, каждый озвучивается отдельным запросом к провайдеру, затем чанки склеиваются в один MP3. Как резать, задают split_type и max_chunk_length. Число чанков возвращается в chunks_count и ограничено тарифом.

От чанков зависят паузы (auto_pause вставляет тишину после каждого N-го чанка), режим split_output (ZIP с MP3 на каждый чанк) и повтор после цензуры (переозвучиваются только заблокированные чанки).

Аккаунт и баланс

Баланс и лимиты считаются по лицензии, то есть по токену из заголовка. У одного пользователя может быть несколько токенов с разными тарифами.

Чей это токен

GET/v2/auth/meТокен в заголовке Authorization

Возвращает пользователя и лицензию, которым принадлежит токен. Удобно для проверки токена при старте клиента.

Ответapplication/json

ПолеТипОписание
user_idstringID пользователя
token_idintegerID лицензии (API-токена)

Ошибки

СтатусКодКогда
401Нет заголовка или токен недействителен

Примеры

Проверить токен
curl "https://voicer.mat3u.com/v2/auth/me" \
  -H "Authorization: Bearer $VOICER_TOKEN"
Ответ 200
{
  "user_id": "3f6c2a9e-8d41-4b7a-9c55-1e2f0a7d4b13",
  "token_id": 5521
}

Баланс и тариф лицензии

GET/v2/billing/meТокен в заголовке Authorization

Подписка, тариф и остаток символов лицензии из заголовка Authorization. Перед большой задачей проверьте remaining_characters и лимиты tariff.

Ответapplication/json

ПолеТипОписание
user_idstringID пользователя
user_activebooleanfalse: пользователь заблокирован
token_idinteger | nullЛицензия, для которой посчитан баланс
subscription_typestringcharacters, unlimited или no_subscription
subscription_expires_atdatetime | nullКонец безлимитной подписки
subscription_activebooleanМожно ли сейчас ставить задачи (подписка и баланс)
total_charactersintegerНачислено в действующих пакетах
used_charactersintegerСписано из действующих пакетов
remaining_charactersintegerОстаток
tariffobject | nullЛимиты тарифа, как в /v2/billing/tariffs
packagesarrayДействующие пакеты с остатком в порядке списания, у каждого свой срок
tariff_codestring | nullКод тарифа

Ошибки

СтатусКодКогда
401Нет заголовка Authorization или токен недействителен
404Пользователь токена не найден

Примеры

Пакет символов
curl "https://voicer.mat3u.com/v2/billing/me" \
  -H "Authorization: Bearer $VOICER_TOKEN"
Ответ 200
{
  "user_id": "3f6c2a9e-8d41-4b7a-9c55-1e2f0a7d4b13",
  "user_active": true,
  "token_id": 5521,
  "subscription_type": "characters",
  "subscription_expires_at": null,
  "subscription_active": true,
  "total_characters": 1000000,
  "used_characters": 412870,
  "remaining_characters": 587130,
  "tariff_code": "characters",
  "tariff": {
    "code": "characters",
    "name": "Characters",
    "kind": "package",
    "max_parallel_tasks": 5,
    "threads_per_task": 15,
    "max_chunks_per_task": null,
    "max_chars_per_task": 200000,
    "allow_original": true,
    "allow_original_accs": false,
    "allow_cartesia": true,
    "max_cartesia_clones": 5,
    "sort_order": 0
  },
  "packages": [
    {
      "id": 18342,
      "chars_granted": 1000000,
      "chars_used": 412870,
      "expires_at": "2026-11-09T12:04:51Z",
      "tariff_code": "characters",
      "source_type": "payment",
      "created_at": "2026-10-10T12:04:51Z",
      "remaining": 587130
    }
  ]
}

Сводка: баланс, задачи, клоны

GET/v2/billing/statsТокен в заголовке Authorization

Баланс лицензии, счётчики задач и использованная квота клонов Cartesia одним запросом.

Ответapplication/json

ПолеТипОписание
subscription_typestringcharacters, unlimited или no_subscription
subscription_expires_atdatetime | nullКонец безлимитной подписки
subscription_activebooleanМожно ли сейчас ставить задачи (подписка и баланс)
total_charactersintegerНачислено в действующих пакетах
used_charactersintegerСписано из действующих пакетов
remaining_charactersintegerОстаток
tariffobject | nullЛимиты тарифа, как в /v2/billing/tariffs
packagesarrayДействующие пакеты с остатком в порядке списания, у каждого свой срок
total_tasksintegerВсего задач
completed_tasksintegerЗавершённых
active_tasksintegerВ очереди или в работе сейчас
clones_usedintegerСвоих клонов Cartesia (идут в квоту)
clones_limitinteger | nullКвота клонов, null без лимита

Ошибки

СтатусКодКогда
401Нет заголовка Authorization или токен недействителен
404Пользователь токена не найден

Примеры

Сводка
curl "https://voicer.mat3u.com/v2/billing/stats" \
  -H "Authorization: Bearer $VOICER_TOKEN"
Ответ 200
{
  "user_id": "3f6c2a9e-8d41-4b7a-9c55-1e2f0a7d4b13",
  "subscription_type": "characters",
  "subscription_expires_at": null,
  "subscription_active": true,
  "total_characters": 1000000,
  "used_characters": 412870,
  "remaining_characters": 587130,
  "tariff_code": "characters",
  "tariff": {
    "code": "characters",
    "name": "Characters",
    "kind": "package",
    "max_parallel_tasks": 5,
    "threads_per_task": 15,
    "max_chunks_per_task": null,
    "max_chars_per_task": 200000,
    "allow_original": true,
    "allow_original_accs": false,
    "allow_cartesia": true,
    "max_cartesia_clones": 5,
    "sort_order": 0
  },
  "total_tasks": 214,
  "completed_tasks": 203,
  "active_tasks": 1,
  "clones_used": 2,
  "clones_limit": 5,
  "packages": [
    {
      "id": 18342,
      "chars_granted": 1000000,
      "chars_used": 412870,
      "expires_at": "2026-11-09T12:04:51Z",
      "tariff_code": "characters",
      "source_type": "payment",
      "created_at": "2026-10-10T12:04:51Z",
      "remaining": 587130
    }
  ]
}

Тарифы

GET/v2/billing/tariffsБез токена

Действующие тарифы и их лимиты. Покупка пакетов и подписок в Telegram-боте.

Ответapplication/json

ПолеТипОписание
codestringКод тарифа
kindstringpackage (пакет символов) или subscription (подписка)
max_parallel_tasksintegerОдновременных задач на лицензию
threads_per_taskintegerПараллельных потоков озвучки одной задачи
max_chunks_per_taskinteger | nullЛимит чанков в задаче
max_chars_per_taskinteger | nullЛимит символов в задаче
allow_originalbooleanРазрешён движок original (ElevenLabs)
allow_cartesiabooleanРазрешён движок cartesia
max_cartesia_clonesinteger | nullКвота своих клонов: 0 запрещены, null без лимита

Примеры

Список тарифов
curl "https://voicer.mat3u.com/v2/billing/tariffs"
Ответ 200
[
  {
    "code": "characters",
    "name": "Characters",
    "kind": "package",
    "max_parallel_tasks": 5,
    "threads_per_task": 15,
    "max_chunks_per_task": null,
    "max_chars_per_task": 200000,
    "allow_original": true,
    "allow_original_accs": false,
    "allow_cartesia": true,
    "max_cartesia_clones": 5,
    "sort_order": 0
  }
]

Голоса ElevenLabs и модели

Для engine=original подходят стандартные голоса ElevenLabs из таблицы ниже. Библиотека ElevenLabs (поиск и подборка) нужна, чтобы найти голос для клона Cartesia.

Стандартные голоса ElevenLabs

Все голоса многоязычные и говорят по-русски на моделях eleven_multilingual_v2, eleven_v3 и новее.

Имяvoice_id
AdampNInz6obpgDQGcFmaJgB
AliceXb7hH8MSUJpSbSDYk0k2
Bellahpp4J3VqNfWAUOO0d1Us
BillpqHfZKP75CvOlQylNhV4
BriannPczCjzI2devNBz1zQrb
CallumN2lVS1w4EtoT3dr4eOWO
CharlieIKne3meq5aSn9XLyUdCD
ChrisiP95p4xoKVk53GoZ742B
DanielonwK4e9ZLuTAKqWW03F9
EriccjVigY5qzO86Huf0OWal
GeorgeJBFqnCBsd6RMkjVDRZzb
HarrySOYHLrjzK2X1ezoPC6cr
JessicacgSgspJ2msm6clMCkdW9
LauraFGY2WhTYpPnrIDTdsKH5
LiamTX3LPaxmHKxFdv7VOQHJ
LilypFZP5JQG7iQjIQuC4Bku
MatildaXrExE9yKIg1WjnnlVkGX
RiverSAz9YHcvj6GT2YYXdXww
RogerCwhRBWXzGAHq8TQ4Fs17
SarahEXAVITQu4vr4xnSDxMaL
WillbIHbv24MWmeRgasZH58o

Модели по движкам

Без model_id берётся модель по умолчанию. Для cartesia модель ElevenLabs (eleven_*) молча заменяется на sonic-3.6, а снятые модели (sonic, sonic-2*, sonic-turbo*, sonic-english и т.п.) дают 400 с кодом invalid_model. Датированные снимки вида sonic-3.6-ГГГГ-ММ-ДД принимаются.

ДвижокПо умолчаниюОстальные
originaleleven_multilingual_v2eleven_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
cartesiasonic-3.6sonic-3, sonic-3-2026-01-12, sonic-3.5, sonic-3.5-2026-05-04, sonic-3.6-2026-08-27, sonic-preview

Стандартные голоса ElevenLabs

GET/v2/voices/elevenlabsТокен в заголовке Authorization

Голоса, которые принимает задача с engine=original. Список статичный, отсортирован по имени.

Ответapplication/json

ПолеТипОписание
[].voice_idstringЗначение для voice_id задачи
[].namestringИмя голоса

Ошибки

СтатусКодКогда
401Нет заголовка Authorization или токен недействителен

Примеры

Список
curl "https://voicer.mat3u.com/v2/voices/elevenlabs" \
  -H "Authorization: Bearer $VOICER_TOKEN"
Ответ 200
[
  {
    "voice_id": "pNInz6obpgDQGcFmaJgB",
    "name": "Adam"
  },
  {
    "voice_id": "Xb7hH8MSUJpSbSDYk0k2",
    "name": "Alice"
  }
]

Модели

GET/v2/voices/modelsТокен в заголовке Authorization

Допустимые model_id по движкам. Модель по умолчанию идёт первой и отмечена default: true.

Ответapplication/json

ПолеТипОписание
elevenlabsarrayМодели для engine=original
cartesiaarrayМодели для engine=cartesia
*[].model_idstringЗначение для model_id задачи
*[].defaultbooleanМодель по умолчанию

Ошибки

СтатусКодКогда
401Нет заголовка Authorization или токен недействителен

Примеры

Модели
curl "https://voicer.mat3u.com/v2/voices/models" \
  -H "Authorization: Bearer $VOICER_TOKEN"
Ответ 200
{
  "elevenlabs": [
    {
      "model_id": "eleven_multilingual_v2",
      "default": true
    },
    {
      "model_id": "eleven_v3",
      "default": false
    }
  ],
  "cartesia": [
    {
      "model_id": "sonic-3.6",
      "default": true
    },
    {
      "model_id": "sonic-3.5",
      "default": false
    }
  ]
}

Голоса Cartesia

Для engine=cartesia подходят голоса трёх видов: стандартные голоса Cartesia, свои клоны и общий каталог клонов голосов ElevenLabs. Все списки требуют тарифа, разрешающего движок cartesia.

Какой voice_id передавать в задачу

В voice_id задачи с engine=cartesia можно передать любой из трёх ID. Если передан ID голоса ElevenLabs, сервис сам найдёт его готовый клон: сначала свой, затем из общего каталога.

Что передаётеПримерОткуда взять
ID клона Cartesia8d0a6f1e-3b52-4c9e-a7d4-52e1c09b7f36Каталог, мои клоны, ответ /clone
ID стандартного голосаf786b574-daa5-4673-aa0c-cbe3e8534c02/v2/voices/cartesia/standard
ID голоса ElevenLabs, у которого есть клонWu3B7bOkdHbKnJTvbiFkПоиск ElevenLabs, затем /clone или /from-labs

Свои клоны и общий каталог

GET/v2/voices/cartesiaТокен в заголовке Authorization

Свои клоны и общий каталог клонов ElevenLabs одним списком.

Query-параметры

languagestring

Фильтр по языку: код Cartesia (ru, de, uk). Пусто: любой язык

до 16 символов
sourcestring

Только один источник; без параметра оба

  • userСвои клоны
  • elevenlabsОбщий каталог клонов голосов ElevenLabs
qstring

Поиск по имени и ID

до 100 символов
pageinteger

Номер страницы с нуля

По умолчанию: 0. 0-10000
page_sizeinteger

Размер страницы

По умолчанию: 50. 1-50

Ответapplication/json

ПолеТипОписание
itemsarrayГолоса, поля ниже
totalintegerВсего голосов под фильтром
page, page_sizeintegerСтраница запроса
has_morebooleanЕсть следующая страница
items[].voice_idstringID для voice_id задачи с engine=cartesia
items[].name, tagline, descriptionstring | nullОписание голоса
items[].languagestring | nullЯзык голоса; у клонов ru или en
items[].accentstring | nullАкцент
items[].genderstring | nullПол, только у стандартных голосов
items[].sourcestringstandard библиотека Cartesia, elevenlabs общий каталог клонов, user свой клон
items[].preview_urlstring | nullСемпл для плеера без токена
items[].elevenlabs_voice_idstring | nullИсходный голос ElevenLabs у клона
items[].labs_is_paidboolean | nullИсходный голос ElevenLabs платный
items[].is_ownerbooleanЭто ваш клон
items[].created_atdatetime | nullКогда создан клон

Ошибки

СтатусКодКогда
401Нет заголовка Authorization или токен недействителен
402subscription_requiredНет подписки или символов
402subscription_expiredБезлимитная подписка закончилась
403engine_not_allowedТариф не разрешает движок cartesia
403user_blockedПользователь заблокирован

Примеры

Русские голоса из обоих источников
curl -G "https://voicer.mat3u.com/v2/voices/cartesia" \
  --data-urlencode "language=ru" \
  -H "Authorization: Bearer $VOICER_TOKEN"
Ответ 200
{
  "items": [
    {
      "voice_id": "c41f7b20-95de-4a1b-8e33-7a6d2f0c9b85",
      "name": "Мой голос",
      "tagline": null,
      "description": null,
      "language": "ru",
      "accent": null,
      "gender": null,
      "source": "user",
      "preview_url": null,
      "elevenlabs_voice_id": null,
      "labs_is_paid": null,
      "is_owner": true,
      "created_at": "2026-10-11T10:02:11Z"
    },
    {
      "voice_id": "8d0a6f1e-3b52-4c9e-a7d4-52e1c09b7f36",
      "name": "Ярослав",
      "tagline": null,
      "description": "Спокойный глубокий голос для озвучки роликов",
      "language": "ru",
      "accent": null,
      "gender": null,
      "source": "elevenlabs",
      "preview_url": "https://storage.googleapis.com/eleven-public-prod/previews/Wu3B7.mp3",
      "elevenlabs_voice_id": "Wu3B7bOkdHbKnJTvbiFk",
      "labs_is_paid": false,
      "is_owner": false,
      "created_at": "2026-09-02T08:15:40Z"
    }
  ],
  "total": 2,
  "page": 0,
  "page_size": 50,
  "has_more": false
}

Общий каталог клонов

GET/v2/voices/cartesia/catalogТокен в заголовке Authorization

Клоны голосов ElevenLabs, доступные всем пользователям. Ими можно озвучивать без своих слотов клонов.

Query-параметры

languagestring

Фильтр по языку: код Cartesia (ru, de, uk). Пусто: любой язык

до 16 символов
paidboolean

Фильтр по исходному голосу ElevenLabs; без параметра все

  • trueКлоны платных голосов ElevenLabs
  • falseКлоны бесплатных голосов
pageinteger

Номер страницы с нуля

По умолчанию: 0. 0-10000
page_sizeinteger

Размер страницы

По умолчанию: 50. 1-50

Ответapplication/json

ПолеТипОписание
itemsarrayГолоса, поля ниже
totalintegerВсего голосов под фильтром
page, page_sizeintegerСтраница запроса
has_morebooleanЕсть следующая страница
items[].voice_idstringID для voice_id задачи с engine=cartesia
items[].name, tagline, descriptionstring | nullОписание голоса
items[].languagestring | nullЯзык голоса; у клонов ru или en
items[].accentstring | nullАкцент
items[].genderstring | nullПол, только у стандартных голосов
items[].sourcestringstandard библиотека Cartesia, elevenlabs общий каталог клонов, user свой клон
items[].preview_urlstring | nullСемпл для плеера без токена
items[].elevenlabs_voice_idstring | nullИсходный голос ElevenLabs у клона
items[].labs_is_paidboolean | nullИсходный голос ElevenLabs платный
items[].is_ownerbooleanЭто ваш клон
items[].created_atdatetime | nullКогда создан клон

Ошибки

СтатусКодКогда
401Нет заголовка Authorization или токен недействителен
402subscription_requiredНет подписки или символов
402subscription_expiredБезлимитная подписка закончилась
403engine_not_allowedТариф не разрешает движок cartesia
403user_blockedПользователь заблокирован

Примеры

Каталог на русском
curl -G "https://voicer.mat3u.com/v2/voices/cartesia/catalog" \
  --data-urlencode "language=ru" \
  --data-urlencode "page=0" \
  --data-urlencode "page_size=50" \
  -H "Authorization: Bearer $VOICER_TOKEN"
Ответ 200
{
  "items": [
    {
      "voice_id": "8d0a6f1e-3b52-4c9e-a7d4-52e1c09b7f36",
      "name": "Ярослав",
      "tagline": null,
      "description": "Спокойный глубокий голос для озвучки роликов",
      "language": "ru",
      "accent": null,
      "gender": null,
      "source": "elevenlabs",
      "preview_url": "https://storage.googleapis.com/eleven-public-prod/previews/Wu3B7.mp3",
      "elevenlabs_voice_id": "Wu3B7bOkdHbKnJTvbiFk",
      "labs_is_paid": false,
      "is_owner": false,
      "created_at": "2026-09-02T08:15:40Z"
    }
  ],
  "total": 1,
  "page": 0,
  "page_size": 50,
  "has_more": false
}

Мои клоны и квота

GET/v2/voices/cartesia/mineТокен в заголовке Authorization

Только свои клоны и сколько слотов клонов занято.

Query-параметры

languagestring

Фильтр по языку: код Cartesia (ru, de, uk). Пусто: любой язык

до 16 символов
qstring

Поиск по имени и ID

до 100 символов
pageinteger

Номер страницы с нуля

По умолчанию: 0. 0-10000
page_sizeinteger

Размер страницы

По умолчанию: 50. 1-50

Ответapplication/json

ПолеТипОписание
itemsarrayГолоса, поля ниже
totalintegerВсего голосов под фильтром
page, page_sizeintegerСтраница запроса
has_morebooleanЕсть следующая страница
clones_usedintegerСвоих клонов в любом статусе (идут в квоту)
clones_limitinteger | nullКвота тарифа: null без лимита, 0 запрещены
items[].voice_idstringID для voice_id задачи с engine=cartesia
items[].name, tagline, descriptionstring | nullОписание голоса
items[].languagestring | nullЯзык голоса; у клонов ru или en
items[].accentstring | nullАкцент
items[].genderstring | nullПол, только у стандартных голосов
items[].sourcestringstandard библиотека Cartesia, elevenlabs общий каталог клонов, user свой клон
items[].preview_urlstring | nullСемпл для плеера без токена
items[].elevenlabs_voice_idstring | nullИсходный голос ElevenLabs у клона
items[].labs_is_paidboolean | nullИсходный голос ElevenLabs платный
items[].is_ownerbooleanЭто ваш клон
items[].created_atdatetime | nullКогда создан клон

Ошибки

СтатусКодКогда
401Нет заголовка Authorization или токен недействителен
402subscription_requiredНет подписки или символов
402subscription_expiredБезлимитная подписка закончилась
403engine_not_allowedТариф не разрешает движок cartesia
403user_blockedПользователь заблокирован

Примеры

Мои клоны
curl "https://voicer.mat3u.com/v2/voices/cartesia/mine" \
  -H "Authorization: Bearer $VOICER_TOKEN"
Ответ 200
{
  "items": [
    {
      "voice_id": "c41f7b20-95de-4a1b-8e33-7a6d2f0c9b85",
      "name": "Мой голос",
      "tagline": null,
      "description": null,
      "language": "ru",
      "accent": null,
      "gender": null,
      "source": "user",
      "preview_url": null,
      "elevenlabs_voice_id": null,
      "labs_is_paid": null,
      "is_owner": true,
      "created_at": "2026-10-11T10:02:11Z"
    }
  ],
  "total": 1,
  "page": 0,
  "page_size": 50,
  "has_more": false,
  "clones_used": 1,
  "clones_limit": 5
}

Стандартные голоса Cartesia

GET/v2/voices/cartesia/standardТокен в заголовке Authorization

Библиотека готовых голосов Cartesia. Слоты клонов не нужны.

Query-параметры

languagestring

Фильтр по языку: код Cartesia (ru, de, uk). Пусто: любой язык

до 16 символов
genderstring

Фильтр по полу

  • masculineМужские
  • feminineЖенские
  • gender_neutralНейтральные
qstring

Поиск по имени и описанию

до 100 символов
pageinteger

Номер страницы с нуля

По умолчанию: 0. 0-10000
page_sizeinteger

Размер страницы

По умолчанию: 50. 1-50

Ответapplication/json

ПолеТипОписание
itemsarrayГолоса, поля ниже
totalintegerВсего голосов под фильтром
page, page_sizeintegerСтраница запроса
has_morebooleanЕсть следующая страница
items[].voice_idstringID для voice_id задачи с engine=cartesia
items[].name, tagline, descriptionstring | nullОписание голоса
items[].languagestring | nullЯзык голоса; у клонов ru или en
items[].accentstring | nullАкцент
items[].genderstring | nullПол, только у стандартных голосов
items[].sourcestringstandard библиотека Cartesia, elevenlabs общий каталог клонов, user свой клон
items[].preview_urlstring | nullСемпл для плеера без токена
items[].elevenlabs_voice_idstring | nullИсходный голос ElevenLabs у клона
items[].labs_is_paidboolean | nullИсходный голос ElevenLabs платный
items[].is_ownerbooleanЭто ваш клон
items[].created_atdatetime | nullКогда создан клон

Ошибки

СтатусКодКогда
401Нет заголовка Authorization или токен недействителен
402subscription_requiredНет подписки или символов
402subscription_expiredБезлимитная подписка закончилась
403engine_not_allowedТариф не разрешает движок cartesia
403user_blockedПользователь заблокирован

Примеры

Женские русские голоса
curl -G "https://voicer.mat3u.com/v2/voices/cartesia/standard" \
  --data-urlencode "language=ru" \
  --data-urlencode "gender=feminine" \
  -H "Authorization: Bearer $VOICER_TOKEN"
Ответ 200
{
  "items": [
    {
      "voice_id": "f786b574-daa5-4673-aa0c-cbe3e8534c02",
      "name": "Анна",
      "tagline": "Тёплый дикторский голос",
      "description": "Ровная подача для новостей и обучающих видео",
      "language": "ru",
      "accent": null,
      "gender": "feminine",
      "source": "standard",
      "preview_url": "https://voicer.mat3u.com/v2/voices/cartesia/standard/f786b574-daa5-4673-aa0c-cbe3e8534c02/preview",
      "elevenlabs_voice_id": null,
      "labs_is_paid": null,
      "is_owner": false,
      "created_at": null
    }
  ],
  "total": 1,
  "page": 0,
  "page_size": 50,
  "has_more": false
}

Карточка голоса Cartesia

GET/v2/voices/cartesia/{voice_id}Токен в заголовке Authorization

Свой клон, клон из общего каталога или стандартный голос по ID.

Параметры пути

voice_idstringобязательный

ID голоса

1-64

Ответapplication/json

ПолеТипОписание
voice_idstringID для voice_id задачи с engine=cartesia
name, tagline, descriptionstring | nullОписание голоса
languagestring | nullЯзык голоса; у клонов ru или en
accentstring | nullАкцент
genderstring | nullПол, только у стандартных голосов
sourcestringstandard библиотека Cartesia, elevenlabs общий каталог клонов, user свой клон
preview_urlstring | nullСемпл для плеера без токена
elevenlabs_voice_idstring | nullИсходный голос ElevenLabs у клона
labs_is_paidboolean | nullИсходный голос ElevenLabs платный
is_ownerbooleanЭто ваш клон
created_atdatetime | nullКогда создан клон

Ошибки

СтатусКодКогда
401Нет заголовка Authorization или токен недействителен
402subscription_requiredНет подписки или символов
402subscription_expiredБезлимитная подписка закончилась
403engine_not_allowedТариф не разрешает движок cartesia
403user_blockedПользователь заблокирован
404voice_not_foundГолоса нет или это чужой клон

Примеры

Клон из каталога
curl "https://voicer.mat3u.com/v2/voices/cartesia/8d0a6f1e-3b52-4c9e-a7d4-52e1c09b7f36" \
  -H "Authorization: Bearer $VOICER_TOKEN"
Ответ 200
{
  "voice_id": "8d0a6f1e-3b52-4c9e-a7d4-52e1c09b7f36",
  "name": "Ярослав",
  "tagline": null,
  "description": "Спокойный глубокий голос для озвучки роликов",
  "language": "ru",
  "accent": null,
  "gender": null,
  "source": "elevenlabs",
  "preview_url": "https://storage.googleapis.com/eleven-public-prod/previews/Wu3B7.mp3",
  "elevenlabs_voice_id": "Wu3B7bOkdHbKnJTvbiFk",
  "labs_is_paid": false,
  "is_owner": false,
  "created_at": "2026-09-02T08:15:40Z"
}

Семпл стандартного голоса

GET/v2/voices/cartesia/standard/{voice_id}/previewБез токена

MP3-семпл стандартного голоса Cartesia. Ссылку preview_url из каталога можно ставить в <audio> как есть: токен не нужен, ответ кэшируется на 7 дней и открыт для CORS.

Параметры пути

voice_idstringобязательный

ID стандартного голоса (UUID)

Ответaudio/mpeg

Ошибки

СтатусКодКогда
404preview_not_foundУ голоса нет семпла
502cartesia_unavailableCartesia не ответила или отказала
503no_account_availableНет рабочего аккаунта Cartesia, повторите позже

Примеры

Скачать семпл
curl "https://voicer.mat3u.com/v2/voices/cartesia/standard/f786b574-daa5-4673-aa0c-cbe3e8534c02/preview" \
  -o preview.mp3
Ответ 200
MP3 (audio/mpeg)

Клонирование голосов

Клон Cartesia создаётся двумя способами, и они по-разному расходуют квоту тарифа (max_cartesia_clones).

Свой клон и клон из ElevenLabs

Свой клипelevenlabs_voice_id
Слот клонаЗанимаетНе занимает
Кому виденТолько вамВсем, попадает в общий каталог
АудиоОбязательно, 10-60 сНеобязательно: берётся семпл ElevenLabs
ПовторКаждый раз новый клонВозвращается готовый (reused: true)
УдалениеDELETE освобождает слотНельзя (403 shared_clone)

Клонировать голос

POST/v2/voices/cartesia/cloneТокен в заголовке Authorization

Создаёт клон Cartesia из своего аудио или из голоса ElevenLabs. Запрос синхронный и может идти до нескольких минут: ставьте таймаут клиента от 300 секунд.

Поля формыmultipart/form-data

languagestringобязательный

Язык голоса. Славянские (ru, uk, be, pl, cs, bg, sr и др.) дают ru-клон, остальные en-клон

до 16 символов
clipfile

Аудио с речью. Обязателен без elevenlabs_voice_id; с ним необязателен (тогда берётся семпл голоса ElevenLabs)

10-60 секунд, до 16 МБ; flac, mp3, mpeg, mpga, oga, ogg, wav, webm
elevenlabs_voice_idstring

Голос ElevenLabs. С ним клон попадает в общий каталог и не тратит ваш слот

10-64 латинских букв и цифр
namestring

Имя клона. По умолчанию имя голоса ElevenLabs или clone-ru/clone-en

до 255 символов
modestring

Режим клонирования Cartesia

По умолчанию: "similarity".
  • similarityМаксимально похоже на исходник
  • stabilityСтабильнее звучание, меньше артефактов исходника
taglinestring

Короткая подпись

до 32 символов
descriptionstring

Описание. По умолчанию описание голоса ElevenLabs

до 1000 символов
accentstring

Акцент

до 64 символов

Ответapplication/json

ПолеТипОписание
voiceobjectКлон, поля как в карточке голоса
reusedbooleantrue: готовый клон этого голоса уже был в каталоге
clones_usedintegerСвоих клонов после операции
clones_limitinteger | nullКвота своих клонов, null без лимита

Ошибки

СтатусКодКогда
401Нет заголовка Authorization или токен недействителен
402subscription_requiredНет подписки или символов
402subscription_expiredБезлимитная подписка закончилась
403engine_not_allowedТариф не разрешает движок cartesia
403user_blockedПользователь заблокирован
403clone_limit_reachedЗаняты все слоты своих клонов
413clip_too_largeФайл больше 16 МБ
415unsupported_formatФормат файла не поддерживается
422clip_requiredНет ни clip, ни elevenlabs_voice_id
422invalid_durationДлина аудио не 10-60 секунд
422invalid_audioФайл не читается как аудио
422empty_clipПустой файл
422elevenlabs_voice_not_foundГолоса нет в ElevenLabs
422cartesia_rejectedCartesia отклонила клип
503elevenlabs_unavailableElevenLabs не ответил
502cartesia_unavailableCartesia не ответила или отказала
503no_account_availableНет рабочего аккаунта Cartesia, повторите позже

Примеры

Свой клон из файла (занимает слот)
curl -X POST "https://voicer.mat3u.com/v2/voices/cartesia/clone" \
  -H "Authorization: Bearer $VOICER_TOKEN" \
  -F "language=ru" \
  -F "name=Мой голос" \
  -F "clip=@voice.wav"
Ответ 200
{
  "voice": {
    "voice_id": "c41f7b20-95de-4a1b-8e33-7a6d2f0c9b85",
    "name": "Мой голос",
    "tagline": null,
    "description": null,
    "language": "ru",
    "accent": null,
    "gender": null,
    "source": "user",
    "preview_url": null,
    "elevenlabs_voice_id": null,
    "labs_is_paid": null,
    "is_owner": true,
    "created_at": "2026-10-11T10:02:11Z"
  },
  "reused": false,
  "clones_used": 2,
  "clones_limit": 5
}
Клон голоса ElevenLabs (слот не тратит)
curl -X POST "https://voicer.mat3u.com/v2/voices/cartesia/clone" \
  -H "Authorization: Bearer $VOICER_TOKEN" \
  -F "language=ru" \
  -F "elevenlabs_voice_id=Wu3B7bOkdHbKnJTvbiFk"
Ответ 200
{
  "voice": {
    "voice_id": "8d0a6f1e-3b52-4c9e-a7d4-52e1c09b7f36",
    "name": "Ярослав",
    "tagline": null,
    "description": "Спокойный глубокий голос для озвучки роликов",
    "language": "ru",
    "accent": null,
    "gender": null,
    "source": "elevenlabs",
    "preview_url": "https://storage.googleapis.com/eleven-public-prod/previews/Wu3B7.mp3",
    "elevenlabs_voice_id": "Wu3B7bOkdHbKnJTvbiFk",
    "labs_is_paid": false,
    "is_owner": false,
    "created_at": "2026-09-02T08:15:40Z"
  },
  "reused": true,
  "clones_used": 1,
  "clones_limit": 5
}

Повторный клон того же голоса ElevenLabs на том же языке не создаётся: сразу возвращается готовый клон с reused: true. Проверить заранее можно через /from-labs.

Проверить голос ElevenLabs перед клоном

GET/v2/voices/cartesia/from-labs/{voice_id}Токен в заголовке Authorization

Есть ли голос в ElevenLabs, есть ли уже его клон в общем каталоге и у вас. Ничего не создаёт.

Параметры пути

voice_idstringобязательный

ID голоса ElevenLabs

10-64 латинских букв и цифр

Query-параметры

languagestring

Язык клона: ru или en (как у /clone); пусто: клон на любом языке

до 16 символов

Ответapplication/json

ПолеТипОписание
elevenlabs_voice_idstringID голоса ElevenLabs
namestring | nullИмя
preview_urlstring | nullСемпл ElevenLabs
labs_is_paidboolean | nullГолос платный в ElevenLabs
clone_languagestring | nullКод языка клона или null
can_clonebooleanКлона в общем каталоге ещё нет
catalogobject | nullГотовый клон в общем каталоге
mineobject | nullВаш клон этого голоса

Ошибки

СтатусКодКогда
401Нет заголовка Authorization или токен недействителен
402subscription_requiredНет подписки или символов
402subscription_expiredБезлимитная подписка закончилась
403engine_not_allowedТариф не разрешает движок cartesia
403user_blockedПользователь заблокирован
404elevenlabs_voice_not_foundГолоса нет в ElevenLabs
503elevenlabs_unavailableElevenLabs не ответил

Примеры

Клон уже есть в каталоге
curl -G "https://voicer.mat3u.com/v2/voices/cartesia/from-labs/Wu3B7bOkdHbKnJTvbiFk" \
  --data-urlencode "language=ru" \
  -H "Authorization: Bearer $VOICER_TOKEN"
Ответ 200
{
  "elevenlabs_voice_id": "Wu3B7bOkdHbKnJTvbiFk",
  "name": "Ярослав",
  "preview_url": "https://storage.googleapis.com/eleven-public-prod/previews/Wu3B7.mp3",
  "labs_is_paid": false,
  "clone_language": "ru",
  "can_clone": false,
  "catalog": {
    "voice_id": "8d0a6f1e-3b52-4c9e-a7d4-52e1c09b7f36",
    "name": "Ярослав",
    "tagline": null,
    "description": "Спокойный глубокий голос для озвучки роликов",
    "language": "ru",
    "accent": null,
    "gender": null,
    "source": "elevenlabs",
    "preview_url": "https://storage.googleapis.com/eleven-public-prod/previews/Wu3B7.mp3",
    "elevenlabs_voice_id": "Wu3B7bOkdHbKnJTvbiFk",
    "labs_is_paid": false,
    "is_owner": false,
    "created_at": "2026-09-02T08:15:40Z"
  },
  "mine": null
}

Удалить свой клон

DELETE/v2/voices/cartesia/{voice_id}Токен в заголовке Authorization

Удаляет клон в Cartesia и освобождает слот. Клоны общего каталога удалить нельзя.

Параметры пути

voice_idstringобязательный

ID своего клона

1-64

Ответapplication/json

ПолеТипОписание
voice_idstringУдалённый клон

Ошибки

СтатусКодКогда
401Нет заголовка Authorization или токен недействителен
403shared_cloneЭто клон общего каталога
404voice_not_foundКлона нет или он чужой
502cartesia_unavailableCartesia не ответила или отказала
503no_account_availableНет рабочего аккаунта Cartesia, повторите позже

Примеры

Удалить
curl -X DELETE "https://voicer.mat3u.com/v2/voices/cartesia/c41f7b20-95de-4a1b-8e33-7a6d2f0c9b85" \
  -H "Authorization: Bearer $VOICER_TOKEN"
Ответ 200
{
  "voice_id": "c41f7b20-95de-4a1b-8e33-7a6d2f0c9b85"
}

Задачи озвучки

Задача принадлежит лицензии (токену), который её создал. Чужие задачи для API не существуют и дают 404. Незавершённые задачи текущего ключа: GET /v2/tasks.

Цензура и повтор

ElevenLabs иногда отказывается озвучивать отдельные фрагменты. Тогда задача заканчивается статусом censored: озвученные чанки сохранены, а заблокированные перечислены в blocked_chunks. Перепишите их текст и отправьте в /retry: переозвучатся только они.

Повтор бесплатен, если новый текст не длиннее исходного. Если длиннее, списывается только разница. Без доплаты повтор работает даже после окончания подписки. Данные для повтора хранятся вместе с задачей (30 дней).

Повтор на Python
task = s.get(f"{BASE}/v2/tasks/{task_id}", timeout=30).json()
if task["status"] == "censored":
    fixed = [
        {"index": c["index"], "text": rewrite(c["text"])}  # rewrite: ваша замена слов
        for c in task["blocked_chunks"]
    ]
    r = s.post(f"{BASE}/v2/tasks/{task_id}/retry", json={"corrected_chunks": fixed}, timeout=60)
    r.raise_for_status()
    # дальше снова опрашивайте статус до completed

Дубляж

С dub_languages задача озвучивает текст, потом переводит его на каждый язык и озвучивает перевод. По умолчанию тем же голосом (у Cartesia клоном на языке дорожки); в dub_voices можно задать другой voice_id на язык, чтобы не было акцента. Перевод подгоняется под длительность каждого чанка оригинала: если он выходит длиннее, модель сокращает формулировку, а не ускоряет речь. В конце чанки всех дорожек дополняются тишиной до самого длинного, поэтому файлы совпадают по длине и ложатся на одно видео.

Пример: оригинал голосом JBFqnCBsd6RMkjVDRZzb, английский pNInz6obpgDQGcFmaJgB, немецкий EXAVITQu4vr4xnSDxMaL. Язык без ключа в dub_voices остаётся голосом оригинала (у Cartesia клоном на языке дорожки).

Сначала озвучивается весь оригинал, потом языки по одному. Прогресс каждой дорожки виден в dubs основной задачи. Основная задача и дорожки становятся completed одновременно, когда длина выровнена.

У каждой дорожки свой task_id: /download, /subtitles и /v2/captions работают с ним как с обычной задачей. Для 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 текста.

Дубляж на Python: все файлы и субтитры
import time
from pathlib import Path

body = {
    "text": text,
    "voice_id": "JBFqnCBsd6RMkjVDRZzb",  # оригинал: George
    "model_id": "eleven_v3",
    "dub_languages": ["en", "de"],
    "dub_voices": {
        "en": "pNInz6obpgDQGcFmaJgB",  # английский: Adam, не голос оригинала
        "de": "EXAVITQu4vr4xnSDxMaL",  # немецкий: Sarah
    },
}
r = s.post(f"{BASE}/v2/tasks", json=body, timeout=60)
r.raise_for_status()
task = r.json()
tracks = {"original": task["task_id"]} | {d["language"]: d["task_id"] for d in task["dubs"]}

final = ("completed", "censored", "failed", "cancelled")
while s.get(f"{BASE}/v2/tasks/{task['task_id']}", timeout=30).json()["status"] not in final:
    time.sleep(5)

# аудио и метки всех дорожек хранятся час после последнего языка
for name, track_id in tracks.items():
    audio = s.get(f"{BASE}/v2/tasks/{track_id}/download", timeout=600)
    audio.raise_for_status()
    Path(f"{name}.mp3").write_bytes(audio.content)
    srt = s.get(f"{BASE}/v2/tasks/{track_id}/subtitles", params={"format": "srt"}, timeout=60)
    if srt.status_code == 200:  # у Cartesia меток нет: 409, тогда POST /v2/captions
        Path(f"{name}.srt").write_bytes(srt.content)

Создать задачу озвучки

POST/v2/tasksТокен в заголовке Authorization

Ставит текст в очередь и сразу списывает символы. Отвечает 202 с task_id; результат ждите через GET /v2/tasks/{task_id}.

Тело запросаapplication/json

textstringобязательный

Текст для озвучки. Длина в символах и есть стоимость задачи

1-1 000 000 символов и не больше max_chars_per_task тарифа
voice_idstringобязательный

Голос. Для original ID стандартного голоса ElevenLabs; для cartesia ID клона, стандартного голоса Cartesia или голоса ElevenLabs, у которого есть клон

1-50 символов
enginestring

Движок. Не указан: original, если тариф его разрешает, иначе cartesia

  • originalElevenLabs
  • cartesiaCartesia
model_idstring

Модель. Не указана: eleven_multilingual_v2 или sonic-3.6. Список в /v2/voices/models

до 50 символов
languagestring

Язык текста, только для cartesia: выбирает клон этого языка и язык синтеза. Не указан: язык голоса

до 16 символов, например ru, en, de
dub_languagesarray

Дубляж: языки, на которые переводится текст. Каждый язык озвучивается отдельной дорожкой; чанки всех дорожек дополняются тишиной до самого длинного, поэтому файлы совпадают с оригиналом по длине. Голос по умолчанию как у оригинала (Cartesia берёт клон на языке дорожки). Другой голос на язык задаётся в dub_voices. Стоимость: текст × (1 + 1.5 × число языков)

коды из каталога движка, например en, de, es; повторы отбрасываются
dub_voicesobject

Голос дорожки: объект {код языка: voice_id}. Например {"en": "pNInz6obpgDQGcFmaJgB", "de": "EXAVITQu4vr4xnSDxMaL"}: английский и немецкий своими голосами. Ключ должен быть из dub_languages. Нет ключа: Labs озвучивает тем же голосом, что оригинал, Cartesia берёт клон на языке дорожки

те же voice_id, что в задаче; ключ вне dub_languages даёт 400 unknown_dub_voice
voice_settingsobject

Настройки голоса ElevenLabs. Cartesia их игнорирует. Неуказанные поля берутся по умолчанию у ElevenLabs

stabilitynumber

Стабильность интонации

0-1
similarity_boostnumber

Похожесть на исходный голос

0-1
stylenumber

Выразительность стиля

0-1
use_speaker_boostboolean

Усиление сходства с диктором

speednumber

Скорость речи

0.7-1.2
split_typestring

Как резать текст на чанки

По умолчанию: "smart".
  • smartПо предложениям, склеенным до max_chunk_length; кавычки и прямая речь не разрываются
  • paragraphsКаждая непустая строка отдельным чанком; max_chunk_length не действует, строка длиннее 2500 символов даёт 400 invalid_split
  • max_lengthПо предложениям до max_chunk_length, без учёта кавычек
max_chunk_lengthinteger

Максимальная длина чанка. Для cartesia (кроме paragraphs) и для китайского, японского и корейского текста урезается до 500

По умолчанию: 1000. 500-2500
split_outputboolean

true: результат ZIP с отдельным MP3 на каждый чанк вместо одного MP3

По умолчанию: false.
auto_pauseobject

Тишина после каждого frequency-го чанка. После последнего чанка паузы нет

enabledboolean

Включить паузы

По умолчанию: false.
durationnumber

Длина паузы в секундах

По умолчанию: 0.5. 0.1-30
frequencyinteger

Пауза после каждого N-го чанка

По умолчанию: 1. 1-100

Ответapplication/json

ПолеТипОписание
task_idstringID задачи
statusstringВсегда pending
enginestringВыбранный движок
voice_idstringГолос, который получит провайдер (у Cartesia ID клона)
model_idstringВыбранная модель
chunks_countintegerНа сколько чанков разрезан текст
charactersintegerДлина текста
charged_charactersintegerСписано символов; 0 на безлимите
dubsarray | nullС dub_languages: [{language, task_id, status, progress_percent, voice_id}], у каждой дорожки свой task_id для статуса и скачивания

Ошибки

СтатусКодКогда
401Нет заголовка Authorization или токен недействителен
400empty_textВ тексте нет ничего, что можно озвучить
400text_too_longТекст длиннее max_chars_per_task тарифа
400too_many_chunksЧанков больше max_chunks_per_task тарифа
400invalid_splitНарезка невозможна (длинный абзац в paragraphs)
400voice_not_foundГолос не найден для этого движка
400voice_not_allowedГолос ElevenLabs вне списка стандартных
400invalid_modelМодель не поддерживается или снята
400unsupported_dub_languageЯзык дубляжа недоступен движку или модели (unsupported, available)
400dub_same_languageЯзык дубляжа совпадает с language текста
400unknown_dub_voiceВ dub_voices язык, которого нет в dub_languages
402subscription_requiredНет подписки или пакета символов
402subscription_expiredБезлимитная подписка закончилась
402insufficient_charactersНе хватает символов (required, available)
403user_blockedПользователь заблокирован
403engine_not_allowedДвижок закрыт тарифом
429too_many_active_tasksДостигнут max_parallel_tasks лицензии
503queue_unavailableОчередь недоступна, символы возвращены
503elevenlabs_unavailableElevenLabs недоступен для проверки голоса
503maintenanceТехнические работы, новые задачи не принимаются

Примеры

ElevenLabs, минимальный запрос
curl -X POST "https://voicer.mat3u.com/v2/tasks" \
  -H "Authorization: Bearer $VOICER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Привет! Это тест Voicer API.",
  "voice_id": "JBFqnCBsd6RMkjVDRZzb"
}'
Ответ 202
{
  "task_id": "6b1d7e42-0c3a-4f8e-9a51-d2c47e8b9f03",
  "status": "pending",
  "engine": "original",
  "voice_id": "JBFqnCBsd6RMkjVDRZzb",
  "model_id": "eleven_multilingual_v2",
  "chunks_count": 1,
  "characters": 28,
  "charged_characters": 28
}
ElevenLabs со всеми настройками
curl -X POST "https://voicer.mat3u.com/v2/tasks" \
  -H "Authorization: Bearer $VOICER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Глава первая.\nУтро началось с дождя.\nГлава вторая.",
  "voice_id": "EXAVITQu4vr4xnSDxMaL",
  "engine": "original",
  "model_id": "eleven_v3",
  "voice_settings": {
    "stability": 0.45,
    "similarity_boost": 0.8,
    "style": 0.2,
    "use_speaker_boost": true,
    "speed": 1.05
  },
  "split_type": "paragraphs",
  "split_output": false,
  "auto_pause": {
    "enabled": true,
    "duration": 1.2,
    "frequency": 1
  }
}'
Ответ 202
{
  "task_id": "6b1d7e42-0c3a-4f8e-9a51-d2c47e8b9f03",
  "status": "pending",
  "engine": "original",
  "voice_id": "EXAVITQu4vr4xnSDxMaL",
  "model_id": "eleven_v3",
  "chunks_count": 3,
  "characters": 50,
  "charged_characters": 50
}
Cartesia клоном, ZIP по чанкам
curl -X POST "https://voicer.mat3u.com/v2/tasks" \
  -H "Authorization: Bearer $VOICER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Добро пожаловать на курс. Сегодня разберём основы.",
  "voice_id": "8d0a6f1e-3b52-4c9e-a7d4-52e1c09b7f36",
  "engine": "cartesia",
  "model_id": "sonic-3.6",
  "language": "ru",
  "max_chunk_length": 500,
  "split_output": true
}'
Ответ 202
{
  "task_id": "6b1d7e42-0c3a-4f8e-9a51-d2c47e8b9f03",
  "status": "pending",
  "engine": "cartesia",
  "voice_id": "8d0a6f1e-3b52-4c9e-a7d4-52e1c09b7f36",
  "model_id": "sonic-3.6",
  "chunks_count": 1,
  "characters": 50,
  "charged_characters": 50
}
ElevenLabs с дубляжом: английский и немецкий другими голосами
curl -X POST "https://voicer.mat3u.com/v2/tasks" \
  -H "Authorization: Bearer $VOICER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Сегодня мы запускаем дубляж.",
  "voice_id": "JBFqnCBsd6RMkjVDRZzb",
  "model_id": "eleven_v3",
  "dub_languages": [
    "en",
    "de"
  ],
  "dub_voices": {
    "en": "pNInz6obpgDQGcFmaJgB",
    "de": "EXAVITQu4vr4xnSDxMaL"
  }
}'
Ответ 202
{
  "task_id": "6b1d7e42-0c3a-4f8e-9a51-d2c47e8b9f03",
  "status": "pending",
  "engine": "original",
  "voice_id": "JBFqnCBsd6RMkjVDRZzb",
  "model_id": "eleven_v3",
  "chunks_count": 1,
  "characters": 28,
  "charged_characters": 112,
  "dubs": [
    {
      "language": "en",
      "task_id": "a5c15c55-c861-4867-85ea-291789894745",
      "status": "pending",
      "progress_percent": 0.0,
      "voice_id": "pNInz6obpgDQGcFmaJgB"
    },
    {
      "language": "de",
      "task_id": "f91a2949-f4b8-49dc-9ec1-dbddd0828a82",
      "status": "pending",
      "progress_percent": 0.0,
      "voice_id": "EXAVITQu4vr4xnSDxMaL"
    }
  ]
}

Активные задачи ключа

GET/v2/tasksТокен в заголовке Authorization

Задачи, созданные этим API-ключом и ещё не завершённые: pending, processing, pending_confirmation. Другие ключи того же пользователя не видны. Пустой список, если активных нет.

Ответapplication/json

ПолеТипОписание
tasksarrayАктивные задачи ключа, от старых к новым. Поля как у GET /v2/tasks/{task_id}
tasks[].task_idstringID задачи
tasks[].statusstringpending, processing, pending_confirmation, completed, censored, failed, cancelled
tasks[].enginestring | nullДвижок задачи
tasks[].progress_percentnumberГотовность 0-100
tasks[].chunks_completed, chunks_totalintegerОзвучено чанков из общего числа
tasks[].split_outputbooleanРезультат будет ZIP
tasks[].created_at, started_at, completed_atdatetime | nullВремя этапов
tasks[].errorobject | null{type, message}; type: content_blocked, failover_confirmation_required и др.
tasks[].blocked_chunksarray | nullПри censored: [{index, text}] заблокированных чанков
tasks[].dubsarray | nullУ задачи с дубляжом: [{language, task_id, status, progress_percent, voice_id}] дорожек. Сначала озвучивается оригинал, потом языки по очереди; все файлы становятся completed вместе, когда длина дорожек выровнена
tasks[].dub_of, dub_languagestring | nullУ дорожки дубляжа: основная задача и язык

Ошибки

СтатусКодКогда
401Нет заголовка Authorization или токен недействителен

Примеры

Есть активные
curl "https://voicer.mat3u.com/v2/tasks" \
  -H "Authorization: Bearer $VOICER_TOKEN"
Ответ 200
{
  "tasks": [
    {
      "task_id": "6b1d7e42-0c3a-4f8e-9a51-d2c47e8b9f03",
      "status": "processing",
      "engine": "original",
      "progress_percent": 40.0,
      "chunks_completed": 2,
      "chunks_total": 5,
      "split_output": false,
      "created_at": "2026-10-11T16:20:03Z",
      "started_at": "2026-10-11T16:20:05Z",
      "completed_at": null,
      "error": null,
      "blocked_chunks": null
    }
  ]
}
Нет активных
curl "https://voicer.mat3u.com/v2/tasks" \
  -H "Authorization: Bearer $VOICER_TOKEN"
Ответ 200
{
  "tasks": []
}

Статус задачи

GET/v2/tasks/{task_id}Токен в заголовке Authorization

Статус, прогресс и ошибка своей задачи. Для censored в blocked_chunks лежат тексты фрагментов, которые нужно исправить.

Параметры пути

task_idstringобязательный

ID задачи

1-36

Ответapplication/json

ПолеТипОписание
task_idstringID задачи
statusstringpending, processing, pending_confirmation, completed, censored, failed, cancelled
enginestring | nullДвижок задачи
progress_percentnumberГотовность 0-100
chunks_completed, chunks_totalintegerОзвучено чанков из общего числа
split_outputbooleanРезультат будет ZIP
created_at, started_at, completed_atdatetime | nullВремя этапов
errorobject | null{type, message}; type: content_blocked, failover_confirmation_required и др.
blocked_chunksarray | nullПри censored: [{index, text}] заблокированных чанков
dubsarray | nullУ задачи с дубляжом: [{language, task_id, status, progress_percent, voice_id}] дорожек. Сначала озвучивается оригинал, потом языки по очереди; все файлы становятся completed вместе, когда длина дорожек выровнена
dub_of, dub_languagestring | nullУ дорожки дубляжа: основная задача и язык

Ошибки

СтатусКодКогда
401Нет заголовка Authorization или токен недействителен
404task_not_foundЗадачи нет или она чужая

Примеры

В работе
curl "https://voicer.mat3u.com/v2/tasks/6b1d7e42-0c3a-4f8e-9a51-d2c47e8b9f03" \
  -H "Authorization: Bearer $VOICER_TOKEN"
Ответ 200
{
  "task_id": "6b1d7e42-0c3a-4f8e-9a51-d2c47e8b9f03",
  "status": "processing",
  "engine": "original",
  "progress_percent": 40.0,
  "chunks_completed": 2,
  "chunks_total": 5,
  "split_output": false,
  "created_at": "2026-10-11T16:20:03Z",
  "started_at": "2026-10-11T16:20:05Z",
  "completed_at": null,
  "error": null,
  "blocked_chunks": null
}
Заблокировано цензурой
curl "https://voicer.mat3u.com/v2/tasks/6b1d7e42-0c3a-4f8e-9a51-d2c47e8b9f03" \
  -H "Authorization: Bearer $VOICER_TOKEN"
Ответ 200
{
  "task_id": "6b1d7e42-0c3a-4f8e-9a51-d2c47e8b9f03",
  "status": "censored",
  "engine": "original",
  "progress_percent": 80.0,
  "chunks_completed": 4,
  "chunks_total": 5,
  "split_output": false,
  "created_at": "2026-10-11T16:20:03Z",
  "started_at": "2026-10-11T16:20:05Z",
  "completed_at": "2026-10-11T16:21:12Z",
  "error": {
    "type": "content_blocked",
    "message": "1 чанк(ов) заблокировано цензурой ElevenLabs"
  },
  "blocked_chunks": [
    {
      "index": 3,
      "text": "Фрагмент, который не пропустил фильтр."
    }
  ]
}

Отменить задачу

POST/v2/tasks/{task_id}/cancelТокен в заголовке Authorization

Отменяет задачу в очереди и возвращает списанные символы. Задачу, которая уже озвучивается, можно отменить только на безлимитной подписке (символы за неё не списывались, возвращать нечего).

Параметры пути

task_idstringобязательный

ID задачи

1-36

Ответapplication/json

ПолеТипОписание
task_idstringID задачи
statusstringcancelled
previous_statusstringСтатус до отмены
refunded_charactersintegerВозвращено символов

Ошибки

СтатусКодКогда
401Нет заголовка Authorization или токен недействителен
404task_not_foundЗадачи нет или она чужая
409already_processingУже озвучивается, а подписка не безлимитная
409already_cancelledУже отменена
409not_cancellableВ этом статусе отменить нельзя (status)
409dub_track_not_cancellableДорожка дубляжа отменяется только вместе с основной задачей (dub_of)

Примеры

Отмена из очереди
curl -X POST "https://voicer.mat3u.com/v2/tasks/6b1d7e42-0c3a-4f8e-9a51-d2c47e8b9f03/cancel" \
  -H "Authorization: Bearer $VOICER_TOKEN"
Ответ 200
{
  "task_id": "6b1d7e42-0c3a-4f8e-9a51-d2c47e8b9f03",
  "status": "cancelled",
  "previous_status": "pending",
  "refunded_characters": 28
}

Повторить после цензуры

POST/v2/tasks/{task_id}/retryТокен в заголовке Authorization

Переозвучивает заблокированные фрагменты задачи censored с исправленным текстом. Остальные чанки не озвучиваются заново. Задача возвращается в pending.

Параметры пути

task_idstringобязательный

ID задачи

1-36

Тело запросаapplication/json

corrected_chunksarrayобязательный

Исправленный текст ровно для каждого index из blocked_chunks, не больше и не меньше

минимум 1 элемент
indexintegerобязательный

Индекс из blocked_chunks

textstringобязательный

Новый текст фрагмента

1-2500 символов, не только пробелы

Ответapplication/json

ПолеТипОписание
task_idstringID задачи
statusstringpending
retry_chunks_countintegerСколько фрагментов переозвучивается
charged_charactersintegerДоплата за символы сверх длины исходных фрагментов

Ошибки

СтатусКодКогда
401Нет заголовка Authorization или токен недействителен
400retry_chunks_mismatchИндексы не совпадают (missing, unexpected)
400duplicate_chunk_indexИндекс повторяется
400empty_textПустой текст фрагмента (indices)
402insufficient_charactersТекст длиннее, а символов на доплату нет
403user_blockedПользователь заблокирован
404task_not_foundЗадачи нет или она чужая
409not_censoredЗадача не в статусе censored
409retry_unavailableДанных для повтора нет, создайте новую задачу
503queue_unavailableОчередь недоступна; задача осталась censored

Примеры

Исправить часть диалога
curl -X POST "https://voicer.mat3u.com/v2/tasks/6b1d7e42-0c3a-4f8e-9a51-d2c47e8b9f03/retry" \
  -H "Authorization: Bearer $VOICER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "corrected_chunks": [
    {
      "index": 0,
      "text": "[EXAVITQu4vr4xnSDxMaL]: Ты уже слышал про диалоги?\n[CwhRBWXzGAHq8TQ4Fs17]: Слышал. Сейчас и проверим."
    }
  ]
}'
Ответ 202
{
  "task_id": "6b1d7e42-0c3a-4f8e-9a51-d2c47e8b9f03",
  "status": "pending",
  "retry_chunks_count": 1,
  "charged_characters": 0
}
Исправить один фрагмент
curl -X POST "https://voicer.mat3u.com/v2/tasks/6b1d7e42-0c3a-4f8e-9a51-d2c47e8b9f03/retry" \
  -H "Authorization: Bearer $VOICER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "corrected_chunks": [
    {
      "index": 3,
      "text": "Фрагмент, переписанный мягче."
    }
  ]
}'
Ответ 202
{
  "task_id": "6b1d7e42-0c3a-4f8e-9a51-d2c47e8b9f03",
  "status": "pending",
  "retry_chunks_count": 1,
  "charged_characters": 0
}

Диалоги

Диалог: это обычная задача озвучки из реплик разных голосов. Статус, скачивание и отмена идут через эндпоинты задач, а символы списываются так же, как за обычный текст той же длины.

Движки и голоса

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 разных голосов. Субтитров у диалогов нет: ответ провайдера без таймингов.

Дождаться результата
created = s.post(f"{BASE}/v2/dialogues", json=body, timeout=60).json()
task_id = created["task_id"]
while True:
    task = s.get(f"{BASE}/v2/tasks/{task_id}", timeout=30).json()
    if task["status"] in {"completed", "failed", "cancelled", "censored"}:
        break
    time.sleep(3)
file = s.get(f"{BASE}/v2/tasks/{task_id}/download", timeout=180)

Как писать текст

В text реплика начинается со строки [voice_id]: текст. voice_id это тот же ID голоса, что в обычной задаче. Строка без пометки в начале продолжает предыдущую реплику, так реплика занимает несколько строк. Пустые строки в начале текста пропускаются.

Текст диалога целиком
[EXAVITQu4vr4xnSDxMaL]: [excited] Have you heard about dialogues?
[CwhRBWXzGAHq8TQ4Fs17]: [laughs] I have.
Let's check how it sounds.

Создать диалог

POST/v2/dialoguesТокен в заголовке Authorization

Реплики нескольких голосов в одном файле. Символы списываются сразу за весь текст, ответ 202 с task_id. Статус, скачивание и отмена: как у задач: GET /v2/tasks/{task_id}, /download, /cancel.

Тело запросаapplication/json

textstring

Диалог одним текстом: каждая реплика с новой строки, голос в начале строки в квадратных скобках и с двоеточием. Реплика на несколько строк продолжается без пометки голоса. Передаётся либо text, либо inputs. Как выглядит такой текст: Как писать текст

до 1 000 000 символов
inputsarray

Реплики по порядку, если не передан text

1-2000 реплик
textstringобязательный

Текст реплики

1-10 000 символов
voice_idstringобязательный

Голос реплики

1-50 символов
enginestring

Движок

По умолчанию: "labs".
  • labsElevenLabs text-to-dialogue: часть диалога озвучивается одним запросом
  • cartesiaКаждая реплика отдельным запросом Cartesia TTS, затем склейка
model_idstring

Модель. Для labs не указана: eleven_v4; доступны ещё eleven_v4_turbo и eleven_v3. Для cartesia как у задач Cartesia, по умолчанию sonic-3.6

до 50 символов
language_codestring

Язык текста. Для cartesia выбирает клон голоса ElevenLabs этого языка и язык синтеза; не указан: определяется по тексту реплик. Для labs передаётся в ElevenLabs как есть, можно не указывать

2-8 символов, например ru, en, de
settingsobject

Настройки голоса ElevenLabs, только для labs. Cartesia их игнорирует

stabilitynumber

Стабильность интонации: 0 творчески, 0.5 естественно, 1 ровно

0-1
seedinteger

Повторяемость результата, только для labs. Cartesia его игнорирует

0-4 294 967 295
split_outputboolean

true: результат ZIP с MP3 по частям вместо одного MP3

По умолчанию: false.

Ответapplication/json

ПолеТипОписание
task_idstringID задачи
statusstringВсегда pending
enginestringВыбранный движок
model_idstringВыбранная модель
voicesarrayГолоса после проверки, в порядке появления (у Cartesia ID клонов)
language_codestringДля cartesia язык озвучки: из запроса или определённый по тексту; для labs значение из запроса, иначе null
lines_countintegerРеплик
parts_countintegerЗапросов к провайдеру (чанков задачи)
charactersintegerДлина всех реплик
charged_charactersintegerСписано символов; 0 на безлимите

Ошибки

СтатусКодКогда
401Нет заголовка Authorization или токен недействителен
400empty_textВ репликах нет ничего, что можно озвучить
400too_many_voicesВ диалоге больше 10 разных голосов
400too_many_chunksЧастей больше max_chunks_per_task тарифа
400voice_not_foundГолос не найден для этого движка
400invalid_modelМодель не поддерживается
402subscription_requiredНет подписки или пакета символов
402subscription_expiredБезлимитная подписка закончилась
402insufficient_charactersНе хватает символов
403dialogues_closedДиалоги в закрытом тесте, пользователь не в списке
403dialogues_disabledДиалоги отключены
403user_blockedПользователь заблокирован
403engine_not_allowedДвижок закрыт тарифом
429too_many_active_tasksДостигнут max_parallel_tasks лицензии
503queue_unavailableОчередь недоступна, символы возвращены
503elevenlabs_unavailableElevenLabs недоступен для проверки голоса
503maintenanceТехнические работы, новые задачи не принимаются

Примеры

Текст с голосами в строках
curl -X POST "https://voicer.mat3u.com/v2/dialogues" \
  -H "Authorization: Bearer $VOICER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "[EXAVITQu4vr4xnSDxMaL]: [excited] Ты уже слышал про диалоги?\n[CwhRBWXzGAHq8TQ4Fs17]: [laughs] Слышал. Сейчас и проверим."
}'
Ответ 202
{
  "task_id": "6b1d7e42-0c3a-4f8e-9a51-d2c47e8b9f03",
  "status": "pending",
  "engine": "labs",
  "model_id": "eleven_v4",
  "voices": [
    "EXAVITQu4vr4xnSDxMaL",
    "CwhRBWXzGAHq8TQ4Fs17"
  ],
  "language_code": null,
  "lines_count": 2,
  "parts_count": 1,
  "characters": 72,
  "charged_characters": 72
}
Labs, реплики по отдельности
curl -X POST "https://voicer.mat3u.com/v2/dialogues" \
  -H "Authorization: Bearer $VOICER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "inputs": [
    {
      "text": "[excited] Ты уже слышал про диалоги?",
      "voice_id": "EXAVITQu4vr4xnSDxMaL"
    },
    {
      "text": "[laughs] Слышал. Сейчас и проверим.",
      "voice_id": "CwhRBWXzGAHq8TQ4Fs17"
    }
  ]
}'
Ответ 202
{
  "task_id": "6b1d7e42-0c3a-4f8e-9a51-d2c47e8b9f03",
  "status": "pending",
  "engine": "labs",
  "model_id": "eleven_v4",
  "voices": [
    "EXAVITQu4vr4xnSDxMaL",
    "CwhRBWXzGAHq8TQ4Fs17"
  ],
  "language_code": null,
  "lines_count": 2,
  "parts_count": 1,
  "characters": 62,
  "charged_characters": 62
}
Cartesia: язык определяется по тексту
curl -X POST "https://voicer.mat3u.com/v2/dialogues" \
  -H "Authorization: Bearer $VOICER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "engine": "cartesia",
  "inputs": [
    {
      "text": "Слушай, ты видел вчерашний отчёт?",
      "voice_id": "EXAVITQu4vr4xnSDxMaL"
    },
    {
      "text": "Видел. Половина посчитана по старой методике.",
      "voice_id": "CwhRBWXzGAHq8TQ4Fs17"
    }
  ]
}'
Ответ 202
{
  "task_id": "6b1d7e42-0c3a-4f8e-9a51-d2c47e8b9f03",
  "status": "pending",
  "engine": "cartesia",
  "model_id": "sonic-3.6",
  "voices": [
    "3a775eba-b397-4f6a-ad71-7e84163c3781",
    "d3419c87-ace1-4529-a916-dc1b4537d979"
  ],
  "language_code": "ru",
  "lines_count": 2,
  "parts_count": 1,
  "characters": 75,
  "charged_characters": 75
}

Результат

Скачивать можно только задачу completed. Аудио хранится ограниченное время после завершения, затем удаляется и /download отвечает 410 result_expired. Скачивайте результат сразу, как задача готова.

Скачать результат

GET/v2/tasks/{task_id}/downloadТокен в заголовке Authorization

MP3 завершённой задачи или ZIP с MP3 по чанкам, если задача создана со split_output: true. Первое скачивание длинной задачи собирает файл из чанков и может занять до нескольких минут, следующие отдаются сразу.

Параметры пути

task_idstringобязательный

ID задачи

1-36

Ответaudio/mpeg | application/zip

ПолеТипОписание
Content-Dispositionheadervoice_<task_id>.mp3 или voice_<task_id>_chunks.zip
Content-LengthheaderРазмер файла

Ошибки

СтатусКодКогда
401Нет заголовка Authorization или токен недействителен
404task_not_foundЗадачи нет или она чужая
409task_not_completedЗадача ещё не completed (status)
409task_incompleteГотовы не все чанки (ready, total, missing)
410result_expiredАудио уже удалено по сроку хранения

Примеры

Сохранить MP3
curl "https://voicer.mat3u.com/v2/tasks/6b1d7e42-0c3a-4f8e-9a51-d2c47e8b9f03/download" \
  -H "Authorization: Bearer $VOICER_TOKEN" \
  -o voice.mp3
Ответ 200
MP3 (audio/mpeg)

Внутри ZIP файлы называются по номеру чанка с нулями: 0000.mp3, 0001.mp3 и т.д. Пауза auto_pause в ZIP-режиме лежит в конце соответствующего файла.

Скачать по подписанной ссылке

GET/v2/tasks/{task_id}/fileПодпись в ссылке, без токена

То же, что /download, но вместо токена подпись из /download-link. Обычно URL не собирают вручную, а берут целиком из url.

Параметры пути

task_idstringобязательный

ID задачи

1-36

Query-параметры

expintegerобязательный

Unix-время окончания ссылки

sigstringобязательный

HMAC-подпись

64 шестнадцатеричных символа

Ответaudio/mpeg | application/zip

Ошибки

СтатусКодКогда
401invalid_download_linkПодпись неверна или срок истёк
409task_not_completedЗадача ещё не completed (status)
409task_incompleteГотовы не все чанки (ready, total, missing)
410result_expiredАудио уже удалено по сроку хранения

Примеры

Скачать
curl -G "https://voicer.mat3u.com/v2/tasks/6b1d7e42-0c3a-4f8e-9a51-d2c47e8b9f03/file" \
  --data-urlencode "exp=1792327200" \
  --data-urlencode "sig=9f2c4e7a1b3d5f60718293a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4" \
  -o voice.mp3
Ответ 200
MP3 (audio/mpeg)

Субтитры

Есть два способа получить субтитры к озвучке. Они отличаются скоростью и движками, для которых работают.

Какой способ выбрать

Надёжная стратегия: сначала запросить /subtitles, а при 409 no_timestamps перейти на /v2/captions.

/v2/tasks/{task_id}/subtitles/v2/captions
ИсточникМетки ElevenLabs при озвучкеРаспознавание речи
ДвижкиТолько originalЛюбые, включая cartesia
СкоростьМгновенноСекунды или минуты
Форматыsrt, vtt, jsonsrt, vtt
Статус задачиcompleted или censoredГотовая озвучка

Субтитры из меток ElevenLabs

GET/v2/tasks/{task_id}/subtitlesТокен в заголовке Authorization

Мгновенные субтитры из временных меток, которые ElevenLabs возвращает вместе с аудио. Работают для задач engine=original в статусе completed или censored. Паузы auto_pause учтены.

Параметры пути

task_idstringобязательный

ID задачи

1-36

Query-параметры

formatstring

Формат файла

По умолчанию: "srt".
  • srtSubRip, application/x-subrip
  • vttWebVTT, text/vtt
  • jsonМетки по символам: characters, character_start_times_seconds, character_end_times_seconds

Ответapplication/x-subrip | text/vtt | application/json | application/zip

Ошибки

СтатусКодКогда
401Нет заголовка Authorization или токен недействителен
404task_not_foundЗадачи нет или она чужая
409task_not_readyОзвучка ещё не закончена
409no_timestampsУ задачи нет меток (обычно это Cartesia)

Примеры

SRT
curl -G "https://voicer.mat3u.com/v2/tasks/6b1d7e42-0c3a-4f8e-9a51-d2c47e8b9f03/subtitles" \
  --data-urlencode "format=srt" \
  -H "Authorization: Bearer $VOICER_TOKEN" \
  -o voice.srt
Ответ 200
1
00:00:00,000 --> 00:00:02,310
Привет! Это тест Voicer API.

При split_output: true приходит ZIP <task_id>_subtitles.zip с файлом на каждый чанк; таймкоды в каждом файле начинаются с нуля.

Метки хранятся час после завершения задачи, потом приходит 409 no_timestamps. Запрашивайте субтитры сразу после completed.

Для дубляжа запросите субтитры по task_id каждой дорожки из dubs: таймкоды совпадают с выровненным аудио дорожки.

Субтитры распознаванием речи

POST/v2/captionsТокен в заголовке Authorization

Субтитры готовой озвучки через распознавание речи. Подходит для любого движка, в том числе Cartesia. Символы не списываются. Запрос синхронный, длится от секунд до пары минут.

Тело запросаapplication/json

task_idstringобязательный

ID своей задачи

1-36
formatstring

Формат файла

По умолчанию: "srt".
  • srtSubRip
  • vttWebVTT
languagestring

Язык речи: ISO 639-1 (ru, en, uk, de...) или auto. Пусто или auto: определить по аудио среди ru, en, uk

до 16 символов

Ответapplication/x-subrip | text/vtt | application/zip

Ошибки

СтатусКодКогда
401Нет заголовка Authorization или токен недействителен
404task_not_foundЗадачи нет или она чужая
409task_not_readyОзвучка ещё не закончена
422invalid_languageКод языка не распознан
502transcription_failedНе удалось распознать речь
503transcription_timeoutРаспознавание заняло слишком много времени
503no_account_availableРаспознавание временно недоступно

Примеры

SRT на русском
curl -X POST "https://voicer.mat3u.com/v2/captions" \
  -H "Authorization: Bearer $VOICER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "task_id": "6b1d7e42-0c3a-4f8e-9a51-d2c47e8b9f03",
  "format": "srt",
  "language": "ru"
}' \
  -o voice.srt
Ответ 200
1
00:00:00,120 --> 00:00:02,280
Привет! Это тест Voicer API.

Для задачи с split_output: true приходит ZIP с файлом 0000.srt, 0001.srt на каждый чанк. Для задачи с auto_pause каждый чанк распознаётся отдельно и сдвигается на длительность предыдущих, поэтому таймкоды совпадают с паузами в MP3.

Субтитры для своего аудио

POST/v2/captions/uploadТокен в заголовке Authorization

Субтитры для любого аудиофайла без задачи озвучки. Имя результата берётся из имени файла.

Поля формыmultipart/form-data

filefileобязательный

Аудиофайл

formatstring

Формат файла

По умолчанию: "srt".
  • srtSubRip
  • vttWebVTT
languagestring

Язык речи: ISO 639-1 или auto; пусто: определить по аудио

Ответapplication/x-subrip | text/vtt

Ошибки

СтатусКодКогда
401Нет заголовка Authorization или токен недействителен
400empty_audioПустой файл
422invalid_languageКод языка не распознан
502transcription_failedНе удалось распознать речь
503transcription_timeoutРаспознавание заняло слишком много времени
503no_account_availableРаспознавание временно недоступно

Примеры

VTT для подкаста
curl -X POST "https://voicer.mat3u.com/v2/captions/upload" \
  -H "Authorization: Bearer $VOICER_TOKEN" \
  -F "format=vtt" \
  -F "language=auto" \
  -F "file=@podcast.mp3" \
  -o podcast.vtt
Ответ 200
WEBVTT

00:00.000 --> 00:03.420
Добрый вечер, это выпуск номер сорок два.

Музыка и эффекты

Генерация музыки и коротких звуков. Оба метода синхронные, без очереди задач и без списания символов. Нужна активная подписка.

Создать музыку

POST/v2/musicТокен в заголовке Authorization

Трек по текстовому промпту. Запрос синхронный и не списывает символы. Нужна активная подписка: безлимит в сроке или пакет с остатком. download_url живёт около суток.

Тело запросаapplication/json

promptstringобязательный

Описание трека: жанр, настроение, эпоха

1-2000 символов

Ответapplication/json

ПолеТипОписание
idstringID трека у провайдера
statusstringСтатус, например generating_music
progressnumberПрогресс от 0 до 1, если провайдер его прислал
promptstringПромпт, который ушёл в генерацию
titlestringНазвание трека
descriptionstringКороткое описание
genresstring[]Жанры
bpmintegerТемп
duration_msintegerДлина трека в миллисекундах
download_urlstringСсылка на файл, обычно MP4
failure_reasonstringПричина сбоя, если она есть
waveforminteger[]Амплитуды для отрисовки волны

Ошибки

СтатусКодКогда
401Нет заголовка Authorization или токен недействителен
403user_blockedПользователь заблокирован
402subscription_requiredНет активной подписки
402subscription_expiredСрок безлимитной подписки истёк
429too_many_generationsПревышен лимит потоков тарифа на этом ключе
503no_proxyГенерация временно недоступна
502generation_failedЗапрос не принят или ответ не разобран
503elevenlabs_unavailableElevenLabs не ответил, повторите позже

Примеры

Дабстеп
curl -X POST "https://voicer.mat3u.com/v2/music" \
  -H "Authorization: Bearer $VOICER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "dapstep 2012"
}'
Ответ 200
{
  "id": "b2WXbFqLJFRpGXFCxhil",
  "status": "generating_music",
  "progress": 1.0,
  "prompt": "dapstep 2012",
  "title": "Data Step",
  "description": "A dark electronic track.",
  "genres": [
    "electronic"
  ],
  "bpm": 140,
  "duration_ms": 30000,
  "download_url": "https://storage.googleapis.com/example/track.mp4",
  "failure_reason": null,
  "waveform": [
    871,
    -845
  ]
}

Пока status не финальный, файл по download_url может ещё дописываться. Повторите скачивание через несколько секунд.

Создать звуковой эффект

POST/v2/sound-effectsТокен в заголовке Authorization

Несколько вариантов эффекта по тексту. Запрос синхронный и не списывает символы. Нужна активная подписка. В audio_base64 лежит само аудио (Opus), не картинка волны.

Тело запросаapplication/json

textstringобязательный

Что должно звучать

1-500 символов
loopboolean

Зациклить фрагмент

По умолчанию: false.
output_formatstring

Формат аудио провайдера

По умолчанию: "opus_48000_128". 1-64 символа

Ответapplication/json

ПолеТипОписание
itemsobject[]Варианты эффекта
items[].idstringID варианта
items[].textstringТекст запроса
items[].content_typestringMIME, обычно audio/opus
items[].duration_secondsnumberДлина в секундах
items[].audio_base64stringАудио в base64
items[].subgroup_idstringОбщая группа вариантов одного запроса
items[].subgroup_positionintegerНомер варианта в группе

Ошибки

СтатусКодКогда
401Нет заголовка Authorization или токен недействителен
403user_blockedПользователь заблокирован
402subscription_requiredНет активной подписки
402subscription_expiredСрок безлимитной подписки истёк
429too_many_generationsПревышен лимит потоков тарифа на этом ключе
503no_proxyГенерация временно недоступна
502generation_failedЗапрос не принят или ответ не разобран
503elevenlabs_unavailableElevenLabs не ответил, повторите позже

Примеры

Звук мотора
curl -X POST "https://voicer.mat3u.com/v2/sound-effects" \
  -H "Authorization: Bearer $VOICER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "звук мотора",
  "loop": false,
  "output_format": "opus_48000_128"
}'
Ответ 200
{
  "items": [
    {
      "id": "2zjuIQWXhD2LY3KLArzI",
      "text": "звук мотора",
      "content_type": "audio/opus",
      "duration_seconds": 1.0,
      "audio_base64": "T2dnUw",
      "subgroup_id": "IXeCrNEYdt2fy8KmsRhN",
      "subgroup_position": 1
    }
  ]
}

Нюансы

Поведение, которое легко упустить при интеграции. Каждый нюанс также показан в конце своего раздела.

Повтор диалога правит текст, а голоса оставляет

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

Коды ошибок

Значение detail.code в ответе с ошибкой. Ветвите логику клиента по коду, а не по тексту message. Ответы 401 без кода и 422 валидации описаны в разделе Формат ошибок.

Неверный запрос

КодСтатусЗначениеЧто делать
empty_text400В тексте нет букв и цифрПроверить текст
text_too_long400Текст длиннее max_chars_per_taskРазбить на несколько задач
too_many_chunks400Чанков больше max_chunks_per_taskУвеличить max_chunk_length или разбить текст
invalid_split400Абзац длиннее 2500 символов в paragraphsРазбить абзац или взять smart
voice_not_found400, 404Голос не найден для движкаВзять ID из списков голосов
voice_not_allowed400Голос ElevenLabs не из списка стандартныхВзять стандартный голос или клон Cartesia
invalid_model400Модель не поддерживается или снятаВзять модель из /v2/voices/models
unsupported_dub_language400Язык дубляжа недоступен движку или моделиВзять язык из available
dub_same_language400Язык дубляжа совпадает с языком текстаУбрать этот язык
unknown_dub_voice400В dub_voices язык, которого нет в dub_languagesОставить только языки из dub_languages
too_many_voices400В диалоге больше 10 разных голосовСократить число голосов
retry_chunks_mismatch400Индексы не совпали с blocked_chunksПрислать ровно missing без unexpected
duplicate_chunk_index400Индекс повторяетсяУбрать дубли
empty_audio400Пустой файлПроверить файл

Доступ и оплата

КодСтатусЗначениеЧто делать
subscription_required402Нет подписки или пакета символовКупить пакет в боте
subscription_expired402Безлимит закончилсяПродлить подписку в боте
insufficient_characters402Не хватает символов (required, available)Пополнить баланс или сократить текст
user_blocked403Пользователь заблокированНаписать в поддержку
engine_not_allowed403Движок закрыт тарифомСменить engine или тариф
clone_limit_reached403Заняты все слоты своих клоновУдалить свой клон или клонировать по elevenlabs_voice_id
shared_clone403Клон общего каталогаУдалять нечего, слот он не занимает
dialogues_closed403Диалоги в закрытом тестеДождаться открытого запуска
dialogues_disabled403Диалоги отключеныПовторить позже
invalid_download_link401Подпись неверна или истеклаПолучить новую ссылку

Состояние задачи и ресурса

КодСтатусЗначениеЧто делать
task_not_found404Задачи нет или она чужаяПроверить task_id и токен
elevenlabs_voice_not_found404, 422Голоса нет в ElevenLabsПроверить ID через поиск
preview_not_found404У голоса нет семплаНе показывать плеер
task_not_completed409Задача ещё не completedДождаться статуса
task_incomplete409Готовы не все чанки (missing)Повторить через 10-60 секунд
task_not_ready409Озвучка не законченаДождаться статуса
no_timestamps409У задачи нет меток ElevenLabsИспользовать POST /v2/captions
already_processing409Задача уже озвучиваетсяДождаться результата
already_cancelled409Задача уже отмененаНичего
not_cancellable409Статус не позволяет отменитьНичего
dub_track_not_cancellable409Дорожка дубляжа отменяется с основной задачейОтменить задачу из dub_of
not_censored409Повтор только для censoredПроверить статус
retry_unavailable409Нет данных для повтораСоздать новую задачу
result_expired410Аудио удалено по сроку храненияОзвучить заново

Файлы и валидация

КодСтатусЗначениеЧто делать
clip_too_large413Клип больше 16 МБСжать или обрезать
unsupported_format415Формат клипа не поддерживаетсяКонвертировать в mp3 или wav
clip_required422Нет клипа и elevenlabs_voice_idПередать одно из двух
invalid_duration422Клип не 10-60 секундОбрезать или удлинить
invalid_audio422Файл не читается как аудиоПроверить файл
empty_clip422Пустой клипПроверить файл
cartesia_rejected422Cartesia не приняла клипВзять клип чище, без музыки
invalid_language422Код языка не распознанПередать ISO 639-1 или auto

Лимиты и внешние сервисы

КодСтатусЗначениеЧто делать
too_many_active_tasks429Достигнут max_parallel_tasksДождаться завершения задачи
too_many_generations429Достигнут лимит потоков тарифа на ключеДождаться завершения генерации
transcription_failed502Речь не распознанаПроверить аудио, указать language
cartesia_unavailable502Cartesia не ответилаПовторить через 10-60 секунд
transcription_timeout503Распознавание не уложилось по времениПовторить через 10-60 секунд
queue_unavailable503Очередь недоступна, символы возвращеныПовторить через 10-60 секунд
generation_failed502Генерация не принята или ответ битыйИзменить запрос
no_proxy503Нет канала до генерацииПовторить через 10-60 секунд
elevenlabs_unavailable503ElevenLabs не ответилПовторить через 10-60 секунд
no_account_available503Нет свободного аккаунта провайдераПовторить через 10-60 секунд
download_signing_disabled503Подписанные ссылки выключеныСкачивать через /download
maintenance503Технические работыПовторить позже, сообщение в message