REST API для озвучки, потоковой генерации, каталога голосов, создания своего голоса и расшифровки.
POST-запрос возвращает готовый WAV-файл.
Примеры для cURL, Node.js и Python через обычный HTTP.
Отдельный endpoint для streaming-сценариев.
Один эндпоинт, параметр language: русский, английский, немецкий, французский, испанский, итальянский, португальский, китайский, японский и корейский.
Используйте библиотеку, свои голоса (клоны) и голоса, купленные в маркетплейсе (GET /voices/mine).
Серверы в России, 152-ФЗ.
sample_url) и портрет голоса (avatar_url). Обе ссылки абсолютные. Для голосовых агентов есть измеренные показатели: timbre_spread — насколько уезжает САМ ТЕМБР между репликами (ниже 0,44 — обычный разброс одного голоса; 0,44 и выше — расстояние, сопоставимое с расстоянием до другого человека), timbre_spread_worst — худший случай из замеров (порог 0,55), stability (stable · ok · drifting) и pitch_hz — средняя высота. Готовый вердикт — в поле recommended_for_agents: true у голосов, пригодных для живого разговора; ровно по нему работает фильтр ?use=agent, а на витрине стоит метка «Для агентов». Есть и фильтр ?stability=stable, но он судит по высоте и для диалога менее показателен. Движок синтезирует каждую фразу заново, и у части голосов звучание гуляет так, что собеседник слышит «разных людей». ⚠️Мы промерили весь каталог, но из общей выдачи голоса с уехавшим тембром не вырезаются (с 11.10.2026): для живого разговора берите фильтр ?use=agent — он отдаёт только проверенные. Ориентируйтесь на timbre_spread: он важнее герц, потому что голос с образцовой высотой может уплывать тембром. По умолчанию отдаётся 200 голосов — за остальными приходите с ?limit=500 или листайте через offset; общее число в поле total. Поле sample_rate — частота ФАЙЛА для линии этого голоса, полученная ЗАМЕРОМ; null означает «у линии замер не делали», а не «наверное, 24 000». ⚠️Точное значение каждого ответа всегда приходит в заголовке X-Sample-Rate — он читается из самого файла и главнее каталога, а поток может отличаться от файла. library — код линии, на которой работает голос. Значения не зашивайте: состав линий меняется, а какая обслуживает голос сейчас — видно в этом же поле ответа"mode": "expressive", свой instruct или emotion (с 18.10.2026 поле читается и в потоке), но тогда звук придёт только в конце генерации. Символы в потоке списываются по длине присланного текста целиком, включая маркеры пауз/api/v1/voices/clone продолжает работать как алиас{input, voice, response_format?, speed?, seed?} — тот же синтез, оплата и проверки, что у /api/v1/tts (см. Совместимость с OpenAI){"voices":[{"name","gender":"f|m","description","language"}]}; только опубликованные голоса витрины. Требует ключmoved_to_service, адрес сервиса — в поле service_url и заголовке LocationGET /api/v1/voices — фильтры: q (поиск по названию, стилю, описанию И по идентификатору голоса), language (ru, en, de…), gender (male/female), stability, use=agent, library (код линии; значения приходят в поле library у голосов — не зашивайте список, линии включают и выключают), limit (по умолч. 200, макс. 500), offset ИЛИ page (1-я страница = 1; при обоих главенствует offset). Ответ сам называет свою пагинацию: limit, offset, page (фактическая), has_more, total. Поле voice из ответа передавайте в POST /tts.
⚠️Линия голоса. Сейчас у всех голосов одна линия — поле library в ответе каталога равно "universal". Не зашивайте код линии в интеграцию: если в каталоге появится вторая линия, голоса неактивной русской линии из выдачи не отдаются, их число придёт в поле ru_old_line_hidden, а запрос голоса по идентификатору (?q=…) вернёт блок unavailable с reason — тем кодом, которым ответит синтез. Пока линия одна, этих полей в ответе нет.
Свои голоса (приватные). Клон, который вы создали (в кабинете или через POST /voices/create), привязан к вашему аккаунту и в общий каталог GET /voices НЕ попадает — другие клиенты его не видят. Чтобы получить список своих голосов программно (и их voice-id для синтеза), вызывайте GET /api/v1/voices/mine со своим ключом — он вернёт только ВАШИ клоны и купленные голоса. Синтез своим голосом: передайте его voice в POST /tts с тем же ключом — озвучить его сможет только ваш аккаунт (чужой ключ получит 403). Публичный GET /voices при этом остаётся строго каталогом.
Два поля, которые стоит проверять перед синтезом.
license: commercial — голос можно использовать в проектах;
noncommercial — демонстрационный (исследовательский) голос: в редакторе его можно слушать, но нельзя выгрузить; по API ограничение пока не применяется — используйте такие голоса только для проб, не для публикации.
badge: null — обычный голос; beta — работает, качество
языка дорабатывается; soon — синтез этим голосом временно отключён, запрос
вернёт ошибку voice_not_available_yet. Отфильтруйте такие голоса на своей
стороне, если строите список выбора для пользователя.
Голос, который вы создали (клон), приватный: он привязан к вашему аккаунту, в общий каталог GET /voices не попадает, и озвучить им может только ваш аккаунт по вашему ключу (чужой ключ → 403). Доступ к своим голосам — по ключу, в три шага:
GET /api/v1/voices/mine со своим ключом → список только ваших голосов (созданные вами клоны + купленные на маркетплейсе). Поле voice — это id для синтеза.POST /api/v1/tts с тем же ключом и voice = id вашего голоса → аудио вашим голосом. Язык берётся из самого голоса (запись клона), параметр language для своего голоса игнорируется.Новый голос, созданный позже, появляется в /voices/mine автоматически — переподключать ключ не нужно. Публичный GET /voices при этом остаётся строго каталогом (приватные голоса в него не подмешиваются).
Все эндпоинты требуют API-ключ: заголовок X-API-Key: <ключ> или Authorization: Bearer <ключ> (кроме GET /api/v1/voices и GET /api/v1/status — открыты). Ключ создаётся в кабинете → раздел «API»; API доступен с тарифа Про и выше (иначе 403). Синтез списывает символы с тарифа ключа — при нулевом балансе возвращается 402. Лимит частоты — по тарифу: Про — 120 запросов/мин, Бизнес — 300, Студия — 600 (фолбэк 60); превышение → 429, заголовок Retry-After.
speaker для голоса, см. ниже). Тарифный лимит — на запрос в целом. Длинный плоский текст сервис сам режет по предложениям на части (одна генерация движка — до [object Promise] символов) и склеивает в один файл; синхронно уходит до 5 частей, сверх этого запрос вернёт 400 text_too_long_for_sync без списания — тогда передавайте текст массивом segments или несколькими запросами. Если движок всё же отверг слишком длинную часть — text_too_long_for_line. Поддерживает маркер паузы: ‖N‖ — пауза N секунд (от 0,05 до 5, например ‖1.5‖; не больше 150 пауз на запрос), голый ‖ — 0,4 с. Метка звука или музыки ♪Скрип двери♪ — на этом месте прозвучит звук из каталога (/zvuki/katalog.json, поле imya; музыка — несколько секунд с затуханием); метка не читается вслух и не оплачивается, неизвестное имя убирается и даёт X-Effects-Failed: zvuk. В массиве segments звук — отдельный элемент {"zvuk": "Скрип двери"}. В одном запросе — не больше 20 звуков, иначе 400 too_many_sounds (символы не спишутся). Сколько символов списано за ответ — в заголовке X-Chars-Charged (метки, паузы и знаки ударения в счёт не входят). Поток /api/v1/tts_stream звуки не вставляет — метки в нём просто вырезаются/tts и /tts_stream (в потоке — с 18.10.2026). Эмоция включает живую подачу: синтез идёт целой фразой, и в потоке звук приходит в конце генерации (см. mode) — для живого разговора шлите реплику без эмоции. Незнакомое значение — 400 unsupported_emotion со списком допустимых, символы не списываются. Явный быстрый режим сильнее эмоции: при "mode": "fast" (или "instruct": "") подача остаётся быстрой, эмоция не применяется, и ответ несёт X-Effects-Failed: emotion. При segments эмоция достаётся сегментам без своего instruct; сегмент со своим instruct остаётся при нём.X-Effects-Failed: speed — запрос не падает, но результат будет не тем, что вы просили"fast" — первый звук приходит сразу (~0,8 с для короткой реплики; замер 13.09.2026 снаружи через сайт, две пробы — 0,79 и 0,81 с), подача ровная; на тексте длиннее ~60 знаков поток идёт кусками, и первый кусок приходит позже; "expressive" — живая интонация, но звук отдаётся только в КОНЦЕ генерации, поэтому реплика в 480 знаков даёт около 10 секунд тишины. По умолчанию fast (с 27.08.2026; раньше умолчанием был expressive, и это ломало голосовых агентов: платформа не дожидалась ответа и рвала связь). Для живых разговоров и телефонии ничего указывать не нужно. Выразительность включается явно: "mode": "expressive", свой instruct или emotion — любое из трёх переключает подачу в живую (ответ несёт X-Voice-Mode: expressive); исключение — явный "mode": "fast" или "instruct": "", они сильнее эмоции (см. emotion). До 18.10.2026 emotion в потоке не читался, а в /tts без mode гасился быстрым режимом — исправлено, пути ведут себя одинаково. Принимаются также синонимы: "slow" = expressive, "realtime" = fast/tts аудио приводится к ровному уровню (≈ −16 дБ), а gain_db сдвигает его. В потоковом /tts_stream звук идёт как синтезирован (он ровный сам по себе, разброс между репликами ~3 дБ), gain_db просто усиливает. ⚠️Замер 24.08: до +6 дБ чисто, при +12 дБ появляются искажения на пиках (0,2% сэмплов упираются в потолок) — для телефонии держите 0, при необходимости не выше +6seed не передан, по API подставляется фиксированное значение — одинаковый запрос даёт одинаковый звук по умолчанию. Нужна вариативность между репликами — передавайте разные seed явноX-Audio-Format (опц.)audio/G722), а opus всегда приходит в ogg-контейнере (audio/ogg, при raw — audio/opus)text — массив [{ text, instruct?, silence? }] (до 301 элементов — 150 пауз; тот же формат, что в /tts_stream) для пофразовой интонации; куски синтезируются и склеиваются в один файл, эффекты/фон/mp3 накладываются на целое. Интонация фрагмента задаётся через instruct (эмоция per-сегмент как отдельное поле не применяется). Пауза: пауза-сегмент { silence: N } даёт точную тишину N мс (0–5000) в обоих эндпоинтах; сегмент с обоими полями text и silence тоже работает — текст озвучивается, пауза ставится после него. Символы списываются по сумме длин text сегментов (опц.)Ответ — бинарный аудиофайл: audio/wav или audio/mpeg (если format=mp3). Передавайте либо text, либо segments.
Озвучка реплик бота с минимальной задержкой. Шаги: (1) один раз подобрать стабильный голос, (2) на каждую реплику — потоковый синтез.
GET /api/v1/voices?use=agent — вернёт голоса, проверенные для живого разговора (по ним ровный тембр между репликами). Возьмите voice первого подходящего пола и запомните.GET /api/v1/status перед стартом сессии: ready:true — можно синтезировать.Длинный текст можно отправить целиком — сервис сам режет его по предложениям (одна генерация движка ≤[object Promise] знаков, синхронно до 5 частей). Делите на главы сами, когда нужен контроль пауз и отдельные файлы; паузы между абзацами — маркером ‖ или сегментами с silence.
Загрузите 15–30 секунд чистой речи (короче 15 с — отказ sample_too_short) с точной расшифровкой — получите voice-id, которым дальше синтезируете как обычным голосом. Согласие обязательно.
Аудио в base64 → текст с определением языка. За каждую минуту аудио с баланса списывается 1000 символов; месячный лимит расшифровки считается в минутах по тарифу.
Принимает voice, text, language, instruct, speed, gain_db, eq, effect, seed ИЛИ массив segments (поэлементная интонация). Отдаёт чистый поток PCM (application/octet-stream, chunked; формат: 24 000 Гц, 16 бит, моно, little-endian) для немедленного воспроизведения. Пост-эффекты, применяемые к целому файлу (clean, background/bg_level, lead_silence_ms), и формат mp3 в стриме НЕ поддерживаются — для них используйте POST /api/v1/tts.
Формат segments — массив объектов [{ text, instruct?, silence? }], до 301 элементов (150 пауз): text — фрагмент текста; instruct — интонация фрагмента по-английски (до 500 символов, как и у общего instruct); silence — пауза после фрагмента в мс (0–5000; сегмент можно прислать и без текста — только пауза). Символы списываются по сумме длин text всех сегментов.
sample_too_short (обязательно)sample_text_mismatch с полями speech_seconds и ref_text_chars, голос не создаётся (≤2000 символов — длиннее молча обрезается, поэтому для длинного образца укладывайтесь в лимит, иначе транскрипт перестанет совпадать с аудио и качество клона упадёт)"voice-data-consent,privacy" (данные голоса, 152-ФЗ); без неё — 400 (обязательно)Поле voice из ответа передавайте в POST /tts. Значение voice ниже — иллюстративный пример; реальный идентификатор приходит в ответе. Создание своего голоса ПО API требует доступа к API (тариф Про и выше) и учитывает лимит голосов тарифа.
auto молча включают автоопределение; без параметра — автоопределение) (опц.)code=audio_too_large); пустое/слишком короткое — 400 (code=no_audio)Списываются символы по тарифу (≈1 мин аудио = 1000 символов, минимальная тарификация — 3 секунды), учитывается месячный лимит минут расшифровки тарифа.
Новый голос без записи: опишите его — модель создаст 3 варианта на одной фразе, около 3–4 минут. Попытка — 1 500 знаков с баланса; не получилось — знаки возвращаются. Одна попытка за раз, варианты хранятся 14 дней.
code=imya)GET /api/v1/voice-design → chips[] (до 20) — то же, что плашки на сайтеpol — не указан пол; 402 no_credits; 429 zanyato — предыдущая ещё идёт; 404 not_available — раздел ещё не открытОпрашивайте GET /api/v1/voice-design?id=… раз в 10–20 секунд. Когда status=done, скачайте варианты по audio_url (с тем же ключом) и сохраните понравившийся обычным созданием голоса: POST /api/v1/voices/create с файлом варианта в audio_b64 и sample_text в ref_text, согласие — в consent, как описано в создании голоса; правила тарифа для своих голосов действуют как всегда.
Если ваш код уже говорит с OpenAI-подобным API синтеза, поменяйте адрес и ключ. Ключ — тот же (X-API-Key или Authorization: Bearer). Поля переводятся в /api/v1/tts один в один, поэтому синтез, оплата, лимиты и ошибки — те же, что описаны выше.
text в /ttsvoice в GET /api/v1/voices или поле name в GET /api/v1/audio/voicesmp3 → MP3; без поля или wav → WAV; телефонные форматы — как в /ttsmodel игнорируетсяGET /api/v1/status (без ключа) — готовность движка для real-time. POST /api/v1/warmup (с ключом; символы НЕ списывает) прогревает движок перед серией звонков.
Через API по умолчанию действует быстрая ровная подача (fast), живая разговорная включается "mode": "expressive"; тембр стабилен между репликами. Громкость в потоке отдаётся как её синтезировал движок — она ровная сама по себе; регулировать её можно полем gain_db. Ваши явные emotion/instruct/seed в запросе всегда в приоритете.
Текст диктору можно подсказывать прямо в строке — отдельных параметров для этого не нужно. Это особенно важно, когда реплики пишет языковая модель: букву ё она ставит непредсказуемо.
Плюс перед гласной = подсказка. Поставьте плюс перед ударной гласной, и диктор прочитает по ней: жалюз+и, диспанс+ер. Букву Ё пишите буквой Ё: всё звучит как «всё», все — как «все». Так чинится большинство ошибок ударения и произношения.
⚠️Редкие слова не поддаются даже так: у нас записан случай «обработала» — одиннадцать способов записи, ни один не сработал. Если попалось такое слово, перефразируйте его или напишите нам: мы разберём случай и добавим слово в общий словарь исправлений, после чего оно зазвучит верно у всех без правок с вашей стороны. Так, например, было исправлено «все» — теперь оно читается правильно само.
Профиль голоса — источник значений по умолчанию. Настройки, сохранённые у голоса в кабинете («Звучание голоса»: эквалайзер тембра, «Сделать чище», «Студийная полировка», манера чтения), применяются и к API-запросам — агент получает тот же звук, что вы слышите в студии, ничего дублировать в теле запроса не нужно. Параметр, переданный явно, перекрывает сохранённый. Если звук в интеграции отличается от ожидаемого, проверьте профиль голоса, а не только запрос.
Простая речь — в промт агента, не в TTS. Синтез читает текст как есть и слова не подменяет (юридические формулировки, названия и бренды не пострадают). Чтобы агент звучал по-человечески, добавьте в его системный промт правило вида:
Слова, которые движок читает неточно, лечит произносительная база — она общая для сайта и API и самообучается; отдельная просьба — в поддержку.
engine_busy с заголовком Retry-After: 5 приходит сразу; не дождались — тот же ответ. Для агента это значит: не запускайте десятки параллельных синтезов на один ключ, ставьте свою очередь и уважайте Retry-After/tts отдаёт готовый файл целиком: короткая реплика (~50 знаков) — около 2 секунд, 480 знаков — около 12 секунд. /tts_stream с умолчанием (быстрый режим) начинает отдавать звук примерно через 0,8 секунды независимо от длины текста — подробности в следующем пункте. Если запросили "mode": "expressive", движок синтезирует фразу целиком и первый звук придёт только в конце: на 480 знаках это около 10 секунд молчания. Планируйте таймауты по режиму, который используете."mode": "expressive", но тогда звук придёт только в конце генерации: на 92 знаках первый звук через 2,6 секунды вместо 0,8, на 480 знаках — около 10 секунд. Умолчание одинаково в /tts_stream и /tts, поэтому характер речи совпадает, если часть реплик вы синтезируете файлом, а часть потоком/tts — 60 секунд на каждую часть длинного текста (частей до 5, то есть до 5 минут на весь ответ); /tts_stream — 30 секунд на первый кадр и 120 секунд без данных подряд. Свой клиентский таймаут ставьте не меньше этих значений, иначе будете рвать живые генерацииX-Concurrency-Used — сколько ВАШИХ генераций идёт прямо сейчас (счётчик аккаунта; в /tts считается после завершения текущего запроса, в потоке — вместе с ним), X-Concurrency-Limit — сколько параллельных генераций разрешает ваш тариф, X-Concurrency-Queued — сколько запросов ждут общей очереди сервиса, X-Engine-Busy — занят ли сам движок, X-Voice-Mode — какой режим подачи применён. Стройте свою очередь по этим числам, а не по догадкам. ⚠️Исключение — ответ из кэша: повторный запрос с тем же текстом, голосом и настройками отдаётся мгновенно с заголовком X-Cache: HIT, и заголовков занятости в нём нет (генерации не было). Считайте их отсутствие признаком кэша, а не сбояGET /api/v1/status отдаёт ready, status (ok · degraded · maintenance · engine_down), причину в note и retry_after_seconds. Опрашивайте его перед стартом кампании и при первом 503 — так вы отличите техработы от разовой перегрузкиseed. Память озвучки (повтор без изменений и правка только изменённых кусков без доплаты) работает в редакторе сайта; через API каждый синтез оплачивается. Безопасно повторять после 429/503; после 4xx (кроме 429) повтор бессмыслен — исправьте запросformat/response_format: audio/wav, audio/mpeg; телефонные форматы при container=raw — audio/PCMA;rate=8000 (alaw), audio/PCMU;rate=8000 (mulaw), audio/G722, audio/opus (в контейнере ogg), audio/L16;rate=24000 (сырой PCM 16 бит); по умолчанию контейнер wav, и тогда приходит audio/wav. Для /tts_stream — application/octet-stream. Без параметра формата приходит WAV 16 бит, моно; частота сейчас 24 000 Гц у всех голосов. Точное значение для ответа /tts приходит в заголовке X-Sample-Rate (у потока /tts_stream этого заголовка нет — частота потока 24 000 Гц): берите его, а не зашитое число, иначе звук проиграется не на своей скорости. Нужна гарантированная частота — просите response_format=pcm_s16le_24k или телефонный профиль24000). Читается из заголовка самого файла, поэтому не расходится с содержимым, и приходит одинаково на свежей генерации и на повторе из кэша. Заголовок есть только у /tts; поток /tts_stream идёт на 24 000 Гц. ⚠️Не зашивайте частоту в проигрыватель по документации — читайте заголовок: у другой линии голосов она может быть иной, и ошибка слышна как ускоренная или замедленная речь. Нужна одна и та же всегда — просите response_format=pcm_s16le_24k/tts_stream — секундомер по этапам: prep=174ms; engine=74ms; total=248ms. prep — наша подготовка (разбор текста, проверка доступа, биллинг), engine — время движка до первых данных, total — вместе. Помогает понять, где расходуется время, не гадая. В ответе /tts этого заголовка нет: там отдаётся готовый файл, и разбивать нечего. ⚠️Это НЕ время до речи: первые байты потока могут быть тишинойunstable_for_agents; pitch_spread_hz=54; timbre_spread=0.45; better=ru_n26,ru_f7,ru_n39. В better — замены того же пола с измеренными показателями. Синтез при этом выполняется штатно, заголовок ничего не блокируетg711_alaw_8k и т.д.). Приходит только при явном response_format. ⚠️Если формат указан неверно, ответ будет 400 unsupported_format со списком допустимых значений в поле supported — раньше неизвестное значение молча игнорировалось, и приходил звук в другом форматеspeed (вышел за 0,5–2,0 и приведён к границе), loudness (нормализация громкости пропущена), instruct (инструкция длиннее 500 знаков — взята не целиком), seed (значение негодное, поэтому повтор не будет тем же), bg_level (громкость фона вне 0.05–0.8 либо прислана без годного background — фона не будет вовсе). Заголовок есть только при расхождении; запрос при этом не падает и символы списываются полностью, поэтому проверяйте его, если результат отличается от ожидаемого. Работает одинаково на /api/v1/tts и /api/v1/tts_streamengine_busy, temporary_unavailable), 30 с, если движок недоступен (engine_unavailable) или не собрался MP3 (mp3_unavailable); при 429 concurrency_limit — 2 с. Ориентируйтесь на заголовок, а не на фиксированную паузуактивно/всего (например 3/4) — приходит на каждом ответе со свежей генерацией (в ответе из кэша, X-Cache: HIT, его нет). Если первая цифра стабильно у потолка, вы упираетесь в ёмкостьПоле code в теле ошибки — машиночитаемая ПРИЧИНА. Ориентируйтесь на него, а не на HTTP-код: один и тот же 403 возвращается в нескольких разных случаях. Полный перечень — в таблице ниже, она собирается из того же справочника, по которому сервис отвечает, поэтому не может отстать от кода.
| code | HTTP | Что значит | Что делать |
|---|---|---|---|
acute | 400 | Ударение знаком акута не годится В пометке стоит знак акута над буквой (за́мок). Такую пометку служба чтения не понимает. | Отметьте ударную гласную знаком плюс перед ней (з+амок). |
audio_required | 400 | Нет образца голоса В запросе нет аудио-образца (audio_b64). | Приложите образец записи в base64: чистая речь, без музыки и шума. |
bad_audio | 400 | Запись не распознана Присланная запись не читается как аудио. | Повторите синтез и сохранение — файл, судя по всему, повреждён. |
bad_json | 400 | Битый запрос Тело запроса не разобралось как JSON. | Проверьте синтаксис и заголовок Content-Type: application/json. |
bad_request | 400 | Неверный запрос В запросе не хватает обязательного поля или значение недопустимо. | Сверьтесь с описанием метода в документации API. |
consent_required | 400 | Нужно согласие на голос Создание голоса требует подтверждения, что вы вправе использовать эту запись. | Поставьте отметку о согласии в мастере создания голоса. |
email_typo | 400 | Опечатка в адресе почты Домен почты похож на известный с одной ошибкой — например «gmail.cim» вместо «gmail.com». На такой адрес письмо с кодом не придёт. | Проверьте адрес и повторите регистрацию. Подсказка с правильным написанием — в тексте ошибки. |
empty_text | 400 | Пустой текст В запросе нет текста для озвучки. | Введите текст и повторите. |
engine_rejected | 400 | Движок отклонил запрос Синтезатор не принял параметры: чаще всего не тот язык для выбранного голоса. | Проверьте язык и настройки голоса. Библиотечный голос читает на своём родном языке. |
library_capability | 400 | Возможность не поддерживается этой группой голосов У линии, на которой работает этот голос, нет запрошенной возможности — например эмоций, эффектов, фонов или потоковой отдачи. | Уберите неподдерживаемые параметры или выберите голос из универсального каталога. |
name_required | 400 | Не указано имя голоса В запросе на создание голоса нет поля name. | Передайте name — под этим именем голос появится в вашей библиотеке. |
no_audio | 400 | Нет аудио В запросе на расшифровку не пришёл звук. | Приложите файл или base64-строку с записью. |
ref_text_required | 400 | Нет расшифровки образца Не передан ref_text — текст, который звучит в образце. | Передайте ref_text ДОСЛОВНО так, как произнесено в записи: расхождение портит клон. |
ru_dictor_line_off | 400 | Линия голоса не исполняет русский Русский текст озвучивает основная линия, а выбранный каталожный голос принадлежит другой русской линии, которая сейчас не исполняет русский. | Выберите русский голос из каталога (поле library у голосов показывает активную линию). Если у голоса есть двойник на активной линии, отказ называет его по имени. Свой собственный голос работает по-прежнему. |
ru_dictor_only | 400 | Русский исполняет другая линия Русский текст сейчас озвучивает не основная линия, и выбранный голос основной линии на ней не воспроизводится. | Выберите русский голос активной линии из каталога. На других языках выбранный голос доступен; свой собственный голос работает по-прежнему. |
sample_text_mismatch | 400 | Текст не совпадает с записью Текст образца в разы не сходится с длиной речи в записи — голос из такой пары говорит неразборчиво, поэтому он не создан. | Загрузите запись обычной речи без повторов, музыки и чужих голосов или впишите в текст всё, что сказано в записи, слово в слово. Замер — в полях speech_seconds и ref_text_chars ответа. |
sample_too_short | 400 | Образец слишком короткий Запись образца короче минимума — из такой похожий голос не получится. | Перезапишите образец длиннее: измеренная длительность — в поле sample_seconds ответа, нужный минимум — в min_seconds. Спокойная речь с паузами между фразами. |
text_too_long | 400 | Текст длиннее предела Текст превышает максимальную длину одного запроса. | Разделите текст на части. На платных тарифах длинный текст в редакторе экспортируется в фоне частями; целую книгу удобнее озвучивать в отдельном сервисе «Книги» (golosar-kniga.tech). Больший объём за один раз открывает тариф выше. |
text_too_long_for_line | 400 | Слишком длинная часть для движка Движок отверг одну из частей текста как слишком длинную для одной генерации. | Разбейте текст на сегменты покороче (массив segments) или добавьте точки, по которым сервис режет текст. |
text_too_long_for_sync | 400 | Объём только фоном Текст слишком велик для синхронного ответа: частей больше, чем держится соединение (поля parts, max_parts, got). | В кабинете — озвучьте фоном через «Скачать»; в API — разбейте текст на части (асинхронных задач в API нет). |
too_many_segments | 400 | Слишком много кусков Текст разбит на большее число фрагментов, чем допускает один запрос. | Уберите лишние паузы в разметке: каждая пауза начинает новый кусок, а их число ограничено. |
too_many_sounds | 400 | Слишком много звуков В тексте больше меток звуков (♪), чем допускает один запрос. | Уберите часть меток звуков или разбейте текст на несколько запросов. |
trial_same_text | 400 | Текст пробы совпадает с образцом Пробный голос нельзя слушать тем же текстом, что читали при записи: так не слышно, похож ли голос. | Напишите другой текст. |
unsupported_effect | 400 | Неизвестный эффект Запрошенный звуковой эффект (effect) не поддерживается. | Возьмите значение из поля allowed в ответе или уберите effect. |
unsupported_emotion | 400 | Эмоция не распознана Значение emotion не из списка поддерживаемых. | Пришлите одно из перечисленных в ответе значений или уберите параметр — тогда голос звучит нейтрально. Символы не списаны. |
unsupported_eq | 400 | Эквалайзер не распознан Поле eq прислано, но его форма не подходит. | Ожидается {bands:[{hz,db},…]} либо {low,mid,high} в децибелах. Символы не списаны. |
unsupported_format | 400 | Неизвестный формат Запрошенный формат аудио не поддерживается. | Допустимые значения перечислены в поле supported ответа и в документации API. |
voice_not_in_demo | 400 | Голоса нет в демо В демо-озвучке на витрине доступен только короткий список голосов, этот в него не входит. | Выберите голос из списка демо или войдите в кабинет — там доступны все голоса. |
api_key_invalid | 401 | Ключ API недействителен Ключ не существует или был отозван. | Проверьте, что копировали ключ целиком, или выпустите новый в разделе «API». |
api_key_required | 401 | Не передан ключ API Запрос пришёл без ключа доступа. | Передайте ключ заголовком X-API-Key или Authorization: Bearer. Ключ — в разделе «API» кабинета. |
auth_invalid | 401 | Неверный ключ API Ключ не найден или отозван. | Проверьте заголовок X-API-Key. Ключ можно перевыпустить в разделе «API». |
auth_required | 401 | Нужен вход Сессия истекла или вы не вошли в аккаунт. | Войдите заново — черновик в редакторе сохраняется. |
insufficient_balance | 402 | Кончились символы На балансе не хватило символов, чтобы озвучить этот текст целиком. | Пополните баланс в разделе «Тариф и лимиты». |
insufficient_balance_kuski | 402 | Не хватило символов На балансе не хватило символов на новые части озвучки (уже озвученные берутся из памяти и не оплачиваются). Символы не списаны. | Пополните баланс в разделе «Тариф и лимиты». |
no_credits | 402 | Нулевой баланс Символы на счету закончились. | Пополните баланс в разделе «Тариф и лимиты». |
demo_voice | 403 | Демонстрационный голос Этот голос можно слушать, но нельзя сохранить: у него нет прав на коммерческое использование. | Для скачивания выберите голос без метки «Демо». |
email_unverified | 403 | Почта не подтверждена Озвучка доступна после подтверждения почты. | Откройте раздел «Аккаунт» и введите код из письма. |
plan_quota | 403 | Исчерпан лимит тарифа Достигнут месячный лимит вашего плана. | Лимит обновится в начале следующего периода, либо перейдите на тариф выше. |
plan_required | 403 | Нужен другой тариф Эта возможность доступна на более высоком тарифе. | Посмотрите тарифы в кабинете — там указано, что входит в каждый. |
project_limit | 403 | Лимит проектов тарифа Достигнут предел числа проектов на вашем тарифе. | Удалите ненужные проекты или перейдите на старший тариф. |
trial_exists | 403 | Пробный голос уже есть На бесплатном тарифе пробный голос может быть только один, и он у вас уже создан. | Послушайте его или удалите, затем создавайте новый. На платном тарифе ограничения нет. |
trial_spent | 403 | Пробные прослушки закончились У пробного голоса ограниченное число прослушек, они израсходованы. | Оформите платный тариф — голос станет рабочим сам, без пересоздания. |
voice_access | 403 | Голос не на вашем тарифе Голос существует, но на текущем плане недоступен. | Выберите другой голос или перейдите на тариф, где он открыт. |
voice_deleted | 403 | Голос удалён Этот голос удалён, синтезировать им больше нельзя (в проекте он мог остаться выбранным). | Выберите другой голос в списке. Если удалили случайно — создайте голос заново по тому же образцу. |
voice_denied | 403 | Голос без права выгрузки Выбран демонстрационный (исследовательский) голос — выгружать файлы им нельзя. | Выберите коммерческий голос из каталога. |
voice_failed | 403 | Голос не создался Обучение голоса завершилось ошибкой, поэтому синтез им недоступен. | повторить позже |
voice_limit | 403 | Лимит своих голосов На вашем тарифе закончились места под собственные голоса. | Удалите ненужный голос или перейдите на тариф с большим числом мест. |
voice_not_available | 403 | Голос недоступен Этот голос вам сейчас недоступен: он удалён, не ваш или закрыт тарифом. | Выберите другой голос в списке. |
voice_not_available_yet | 403 | Язык голоса ещё не открыт Голос из языка с меткой «Скоро»: синтез для этого языка пока не включён. | Выберите голос другого языка; языки с меткой «Скоро» откроются позже. |
voice_not_found | 403 | Голос не найден Такого голоса нет ни в каталоге, ни среди ваших и купленных. | Проверьте идентификатор голоса; полный список — /api/voices/library. |
voice_not_ready | 403 | Голос ещё готовится Ваш голос создан, но обучение ещё идёт — синтезировать им пока нельзя. | Подождите несколько минут. Удалять и создавать голос заново НЕ нужно. |
voice_trial | 403 | Пробный голос Этот голос создан на бесплатном плане как проба: его можно послушать, но нельзя озвучивать им тексты. | Перейдите на тариф «Старт» или выше — пробный голос станет рабочим. |
not_found | 404 | Объект не найден Запрошенной записи нет: удалена или адрес неверный. | Обновите страницу и проверьте, что объект существует. |
export_in_progress | 409 | Сохранение уже идёт Предыдущее сохранение или экспорт ещё не закончились. | Дождитесь окончания — повторный запуск не нужен. |
length_mismatch | 409 | Запись не совпала с текстом Сохраняемая озвучка не соответствует текущему тексту проекта. | Ничего делать не нужно: озвучим заново под изменённый текст. |
voice_conflict | 409 | Такое имя голоса занято Голос с таким именем у вас уже есть. | Выберите другое имя. |
tracks_gone | 410 | Дорожек проекта больше нет Отдельные дорожки голоса и фона этого перевоплощения больше не хранятся; готовый файл цел, но пересвести баланс нечем. | Перевоплотите запись заново. |
voice_line_retired | 410 | Линия этого голоса снята Голос принадлежит линии, которой больше нет: озвучить им или перезаписать его образец нельзя. | Создайте голос заново на действующей линии — запись займёт пару минут. |
length_required | 411 | Нет длины запроса Не передан или испорчен заголовок Content-Length. | Проверьте HTTP-клиент: длина тела обязательна. |
audio_too_large | 413 | Аудио слишком большое Размер записи больше допустимого для одного запроса. | Разрежьте запись на части или сожмите её (моно, меньший битрейт). |
body_too_large | 413 | Слишком большой запрос Тело запроса превышает допустимый размер. | Уменьшите объём: короче текст или меньше файл. |
too_big | 413 | Файл слишком большой Загружаемый файл больше допустимого размера. | Разбейте книгу на части или уберите тяжёлые вложения. |
too_large | 413 | Запись собираем на сервере Готовая озвучка слишком велика, чтобы собрать её в браузере. | Ничего делать не нужно: файл соберётся на сервере. |
unsupported | 415 | Формат файла не поддержан Такой формат книги или документа мы не читаем. | Сохраните файл в поддерживаемом формате (список — в документации) и загрузите снова. |
no_text | 422 | В файле нет текста Файл прочитан, но текста в нём не нашлось — например, это скан-картинки. | Загрузите текстовую версию: скан сначала нужно распознать. |
concurrency_limit | 429 | Слишком много запросов сразу Одновременных озвучек больше, чем позволяет тариф. | Дождитесь окончания текущих или повторите через время из заголовка Retry-After. |
rate_limited | 429 | Слишком часто Превышена частота запросов в минуту. Счёт ведётся НА АККАУНТ, а не на ключ: второй ключ частоту не удваивает. | Дождитесь секунд из заголовка Retry-After и повторите. Нужен запас — напишите нам. |
too_many_requeues | 429 | Слишком много повторов задачи Задачу расшифровки перезапускали слишком много раз подряд. | Загрузите файл заново. |
client_aborted | 499 | Клиент прервал сам Соединение закрыто со стороны клиента: закрыта вкладка, нажат стоп или пропала связь. | — |
internal_error | 500 | Внутренняя ошибка Что-то пошло не так на нашей стороне. | повторить позже |
save_failed | 500 | Голос не сохранён Голос синтезирован, но не записался в библиотеку. | повторить позже |
clone_failed | 502 | Не удалось создать голос Движок не смог построить голос по образцу. | повторить позже |
engine_empty | 502 | Пустой ответ движка Синтез завершился, но звук не пришёл. | повторить позже |
engine_error | 502 | Ошибка движка Движок вернул ошибку при обработке текста. | повторить позже |
factory_bad_answer | 502 | Фабрика голосов ответила непонятно Ответ службы не разобрался: либо версии разошлись, либо ответ пришёл не в том виде. | повторить позже |
mp3_failed | 502 | Конвертация в MP3 не удалась Озвучка синтезирована, но перекодировать её в MP3 не получилось. Списанные символы возвращены. | повторить позже |
scan_failed | 502 | Разбор главы не удался Служба разбора текста не ответила или ответила непонятно, поэтому список спорных слов не собран. | повторить позже |
synth_failed | 502 | Озвучка отрывка не удалась Служба синтеза не смогла озвучить этот отрывок. | повторить позже |
telephony_failed | 502 | Не собрался телефонный формат Звук синтезирован, но преобразование в телефонный формат не удалось. | повторить позже |
transcribe_error | 502 | Ошибка распознавания Расшифровка не удалась на нашей стороне. | повторить позже |
asr_vram_low | 503 | Не хватило памяти на карте Распознаванию не хватило видеопамяти — её заняли озвучка и перевоплощение. | повторить позже |
billing_unavailable | 503 | Биллинг недоступен Не удалось проверить баланс. | повторить позже |
catalog_unavailable | 503 | Каталог голосов недоступен Список голосов временно не читается — сбой на нашей стороне. | повторить позже |
demo_unavailable | 503 | Демо недоступно Демонстрационная озвучка на главной временно не работает. | повторить позже |
engine_busy | 503 | Движок перегружен Сейчас слишком много одновременных озвучек. | повторить позже |
engine_off | 503 | Служба озвучки недоступна Служба синтеза сейчас не отвечает, поэтому разобрать главу и озвучить её не получилось. | повторить позже |
engine_unavailable | 503 | Движок недоступен Сервис синтеза временно не отвечает. | повторить позже |
factory_down | 503 | Фабрика голосов недоступна Адрес службы известен, но она не отвечает: скорее всего не запущена на машине движка. | повторить позже |
factory_off | 503 | Фабрика голосов не подключена В реестре серверов не указан порт службы «Фабрика голосов», поэтому обращаться некуда. | повторить позже |
factory_timeout | 503 | Фабрика голосов не ответила вовремя Служба не ответила за отведённое время. Начатая задача могла остаться выполняться. | повторить позже |
mp3_unavailable | 503 | MP3 временно недоступен Кодировщик MP3 на сервере сейчас недоступен; символы не списаны. | повторить позже |
orig_pin_failed | 503 | Исходник не зафиксирован Не удалось закрепить исходную запись перед обработкой. | повторить позже |
temporary_unavailable | 503 | Временно недоступно Сервис на короткое время недоступен. | повторить позже |
bad_json), пустой текст (empty_text), текст длиннее лимита тарифа (text_too_long), больше 301 сегментов (too_many_segments), больше 5 частей для синхронного ответа (text_too_long_for_sync), движок отверг слишком длинную часть (text_too_long_for_line) или неизвестный движку язык (engine_rejected). При создании голоса — не переданы обязательные поля: name_required, ref_text_required, audio_required, consent_required; образец короче минимума — sample_too_short (в ответе sample_seconds и min_seconds)code=plan_required) или нет доступа к голосу: voice_not_found — голос неизвестен или чужой приватный; voice_not_available — не передано поле voice, голос скрыт или не опубликован; voice_trial — пробный клон бесплатного плана, озвучивать им нельзя до тарифа; voice_not_ready, voice_failed, voice_deleted — свой голос ещё готовится, не собрался или удалён; voice_not_available_yet — голос помечен «Скоро», синтез им пока отключён (см. поле badge в каталоге). Также: email_unverified — платные вызовы по ключу требуют подтверждённой почты аккаунта; voice_limit — достигнут лимит клонов тарифа; plan_quota — исчерпана квота расшифровкиvoice_conflict): такое имя занято голосом другого аккаунта — укажите другое имя. Свой голос с тем же именем конфликта не даёт: он перезаписывается новым образцомbody_too_large); расшифровка — аудио > ~30 МБ (base64, code=audio_too_large)internal_error) — например при чтении каталога голосов. Повторите запрос; если повторяется — напишите в поддержкуengine_error, engine_empty, telephony_failed, mp3_failed (символы за неотданный MP3 возвращаются). transcribe_error и clone_failed приходят с тем статусом, который вернул движок (например 503) — смотрите на код, а не на числоТело ошибки — JSON { "error": "описание", "code": "машинный_код" }. Разбирайте code, а не текст: тексты мы переписываем, коды не меняем. Символы при неуспехе не списываются. Исключение — обрыв потока /tts_stream на середине: списываются только символы за фактически доставленное аудио, остаток возвращается.
Параметр effect — один пресет на запрос. Бесплатные доступны всем; премиум — на платных тарифах.
concurrency_limit с Retry-After: дождитесь завершения текущей генерации, а не шлите повтор сразу. Текущее состояние видно в заголовках любого успешного ответа (X-Concurrency-Used и X-Concurrency-Limit). Для голосовых агентов это главное ограничение: именно оно определяет, сколько разговоров вы ведёте одновременноtext_too_long_for_sync). В /tts_stream суммарная длина сегментов — тоже по тарифу ключа, жёсткого числа нетВ кабинете → раздел «API» создайте ключ (формат sk-live-…) — он показывается один раз, сохраните сразу. Публичный API доступен с тарифа Про и выше; на младших вернётся 403 plan_required.
Заголовком — принимаются оба варианта: X-API-Key: sk-live-… или Authorization: Bearer sk-live-…. Тело запроса — JSON.
/tts — синхронный, отдаёт готовый файл (WAV/MP3 или телефонный формат). /tts_stream — низколатентный поток сырого PCM по мере синтеза, для голосовых ассистентов; без mp3, телефонии и пост-обработки целого файла (чистка/фон). Пресет-эффект, громкость и эквалайзер в потоке работают.
Сырой PCM: 16 бит, 24000 Гц, моно, без WAV-заголовка (Content-Type: application/octet-stream). Проиграть: ffplay -f s16le -ar 24000 -ac 1 -i - или aplay -f S16_LE -r 24000 -c 1; либо дописать WAV-заголовок и сохранить как .wav.
По умолчанию WAV; format:"mp3" → MP3. Для телефонии — response_format: g711_alaw_8k, g711_ulaw_8k, g722_16k, opus, pcm_s16le_24k (фактический формат приходит в заголовке X-Audio-Format).
401 — проблема с ключом; 402 insufficient_balance — не хватает символов; 403 — нет прав (тариф/email/голос); 429 rate_limited — превышен лимит (см. заголовок Retry-After); 400 — ошибка в запросе; 503 — движок занят/недоступен; 502 — сбой синтеза (символы возвращаются). Причина — в поле code ответа.
Только временные: 429 — по Retry-After; 503/502 — с экспоненциальной паузой, 2–4 попытки. Не ретраить 400/401/402/403/413/409 — это про сам запрос, доступ или баланс.
POST /api/v1/voices/create (алиас /api/v1/voices/clone): поля name, audio_b64 (образец, до 10 МБ самого файла), ref_text (расшифровка образца слово-в-слово), consent (строка с токенами voice-data-consent и privacy). Голос приватный, привязан к вашему аккаунту.
POST /api/v1/transcribe: audio_b64 и опционально language (только полное имя языка — например «Russian», не «ru»). Вернёт {text, language}. Стоимость — по длительности аудио.
Передавайте фиксированный seed (целое) вместе с теми же текстом/голосом/параметрами — озвучка воспроизводится идентично.
Нет. Синтез и расшифровка синхронные — результат приходит в том же запросе. Асинхронной постановки задач с колбэком нет.
Используйте /api/v1/tts_stream (звук по мере синтеза), заранее прогрейте движок POST /api/v1/warmup (без списания) и проверяйте готовность GET /api/v1/status.
Обновите и повторите запрос. Если повторяется — это дефект на нашей стороне (не ваша настройка и не паузы): напишите в поддержку с примером и параметрами запроса, починим.