REST API для озвучки, потоковой генерации, каталога голосов, создания своего голоса и расшифровки.
POST-запрос возвращает готовый WAV-файл.
Примеры для cURL, Node.js и Python через обычный HTTP.
Отдельный endpoint для streaming-сценариев.
Один эндпоинт, параметр language: русский, английский, немецкий, французский, испанский, итальянский, португальский, китайский, японский и корейский.
Используйте библиотеку, сохранённые пользовательские голоса и варианты звучания.
Серверы в России, 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, но он судит по высоте и для диалога менее показателен. Движок синтезирует каждую фразу заново, и у части голосов звучание гуляет так, что собеседник слышит «разных людей». ⚠️Голоса с уехавшим тембром в выдачу не попадают вовсе — мы промерили весь русский каталог и убрали те, что для живого разговора не годятся. Ориентируйтесь на timbre_spread: он важнее герц, потому что голос с образцовой высотой может уплывать тембром. По умолчанию отдаётся 200 голосов — за остальными приходите с ?limit=500 или листайте через offset; общее число в поле total. Поле Поле sample_rate — частота ФАЙЛА для этой линии, полученная ЗАМЕРОМ (universal 24 000, дикторская 44 100); null означает «у линии замер не делали», а не «наверное, 24 000». ⚠️Точное значение каждого ответа всегда приходит в заголовке X-Sample-Rate — он читается из самого файла и главнее каталога; поток может отличаться от файла (у дикторской линии файл 44 100, поток 24 000). library различает линейки: "dictor" — дикторские голоса (ударения выверены, чтение детерминировано, свои ограничения — см. раздел «Дикторские голоса»), "universal" — обычные"mode": "expressive", но тогда звук придёт только в конце генерации/api/v1/voices/clone продолжает работать как алиас403, code: plan_required_music). Сейчас в режиме раннего доступа: возвращает 503 (code: music_api_not_ready, заголовок Retry-After) — движок песен под API ещё открывается. Кабинетная генерация песен («Споём») уже работает; напишите нам, чтобы попасть в ранний доступ по APIGET /api/v1/voices — фильтры: q (поиск по названию, стилю, описанию И по идентификатору голоса), language (ru, en, de…), gender (male/female), stability, use=agent, library (universal · dictor_espeech · dictor), limit (по умолч. 200, макс. 500), offset ИЛИ page (1-я страница = 1; при обоих главенствует offset). Ответ сам называет свою пагинацию: limit, offset, page (фактическая), has_more, total. Поле voice из ответа передавайте в POST /tts.
⚠️Русские голоса и линии (изменение от 13.09). Весь русский синтез переведён на дикторскую линию (library="dictor_espeech"): ударения выверены словарём, чтение ровное. Поэтому русские голоса прежней линии (library="universal") из каталога больше не отдаются, а синтез ими на русском отвечает отказом ru_dictor_only. Сколько голосов скрыто из вашей выдачи — в поле ru_old_line_hidden. Если вы спрашиваете конкретный голос по идентификатору (?q=ru_f5), ответ вернёт блок unavailable с причиной и именем замены: у каждого такого голоса есть двойник с тем же голосом на дикторской линии — kk_ + прежний идентификатор (ru_f5 → kk_ru_f5). Перечислить все дикторские: ?library=dictor_espeech. ⚠️Не-русские голоса прежней линии, ваши клоны и голоса с Маркетплейса не затронуты.
Свои голоса (приватные). Клон, который вы создали (в кабинете или через POST /voices/create), привязан к вашему аккаунту и в общий каталог GET /voices НЕ попадает — другие клиенты его не видят. Чтобы получить список своих голосов программно (и их voice-id для синтеза), вызывайте GET /api/v1/voices/mine со своим ключом — он вернёт только ВАШИ клоны и купленные голоса. Синтез своим голосом: передайте его voice в POST /tts с тем же ключом — озвучить его сможет только ваш аккаунт (чужой ключ получит 403). Публичный GET /voices при этом остаётся строго каталогом.
Два поля, которые стоит проверять перед синтезом.
license: commercial — голос можно использовать в проектах;
noncommercial — демонстрационный, синтез доступен, но файл не выдаётся.
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 для голоса, см. ниже). Тарифный лимит — на запрос в целом; плоский текст синтезируется одной генерацией движка с потолком 3000 символов — тексты длиннее передавайте массивом segments (каждый сегмент ≤3000). Если прислать плоский текст длиннее 3000, запрос вернёт 400 engine_rejected — символы не спишутся. Поддерживает маркер паузы ‖ — короткая пауза (~0,4 с) точно между словамиlibrary="dictor") эмоции/instruct не принимают — придёт 400 library_capabilityX-Effects-Failed: speed — запрос не падает, но результат будет не тем, что вы просили"fast" — первый звук приходит сразу (~0,8 с; замер 13.09.2026 снаружи через сайт, две пробы — 0,79 и 0,81 с, без разброса по нагрузке) независимо от длины текста (это и проверялось: 0,79 против 0,81 на разной длине), подача ровная; "expressive" — живая интонация, но звук отдаётся только в КОНЦЕ генерации, поэтому реплика в 480 знаков даёт около 10 секунд тишины. По умолчанию fast (с 27.08.2026; раньше умолчанием был expressive, и это ломало голосовых агентов: платформа не дожидалась ответа и рвала связь). Для живых разговоров и телефонии ничего указывать не нужно. Выразительность включается явно: "mode": "expressive", свой instruct или emotion — они сильнее режима. Принимаются также синонимы: "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? }] (до 40 элементов; тот же формат, что в /tts_stream) для пофразовой интонации; куски синтезируются и склеиваются в один файл, эффекты/фон/mp3 накладываются на целое. Интонация фрагмента задаётся через instruct (эмоция per-сегмент как отдельное поле не применяется). Пауза: пауза-сегмент {"{ silence: N }"} даёт точную тишину N мс (0–3000) в обоих эндпоинтах; сегмент с обоими полями 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 — можно синтезировать.Длинный текст режется на части ≤3000 знаков (или на главы) и синтезируется по кускам; паузы между абзацами — маркером ‖ или сегментами с silence.
Загрузите 20–60 с чистой речи с точной расшифровкой — получите voice-id, которым дальше синтезируете как обычным голосом. Согласие обязательно.
Аудио в base64 → текст с определением языка. ≈1 минута аудио = 1000 символов месячного лимита расшифровки тарифа.
Отдельная линейка для документов, инструкций и обучающих материалов: каждое ударение выверено словарём, чтение ровное и детерминированное — один и тот же текст всегда звучит одинаково (повтор с любым seed даёт ту же запись; «другого дубля» не существует, звучание меняется правкой текста и ударений). В каталоге GET /voices такие голоса помечены полем library: "dictor" — проверяйте его до синтеза.
‖ в тексте или сегментами с silence; скорость speed; ударение — ЗАГЛАВНОЙ гласной в слове (замОк)instruct, emotion, effect, eq, clean, background/bg_level, gain_db≠0, lead_silence_ms>0, saturation — любой из этих параметров вернёт 400 library_capability с объяснением, что именно убрать. Клонирование дикторских тембров не предусмотрено/api/v1/tts_stream дикторские голоса не поддерживает — придёт 400. Для real-time агентов используйте голоса library: "universal"400 library_capability — параметр не поддержан линейкой; 403 library_not_available — линейка выключена; успешный ответ несёт заголовок X-Library: dictorПринимает 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? }], до 40 элементов: text — фрагмент текста; instruct — интонация фрагмента по-английски (до 500 символов, как и у общего instruct); silence — пауза после фрагмента в мс (0–3000; сегмент можно прислать и без текста — только пауза). Символы списываются по сумме длин text всех сегментов.
"voice-data-consent,privacy" (данные голоса, 152-ФЗ); без неё — 400 (обязательно)Поле voice из ответа передавайте в POST /tts. Значение voice ниже — иллюстративный пример; реальный идентификатор приходит в ответе. Создание своего голоса ПО API требует доступа к API (тариф Про и выше) и учитывает лимит голосов тарифа.
code=audio_too_large); пустое/слишком короткое — 400 (code=no_audio)Списываются символы по тарифу (≈1 мин аудио = 1000 символов, минимальная тарификация — 3 секунды), учитывается месячный лимит минут расшифровки тарифа.
GET /api/v1/status (без ключа) — готовность движка для real-time. POST /api/v1/warmup (с ключом; символы НЕ списывает) прогревает движок перед серией звонков.
Через API голос по умолчанию говорит живой разговорной подачей, а тембр стабилен между репликами. Громкость в потоке отдаётся как её синтезировал движок — она ровная сама по себе; регулировать её можно полем gain_db. Ваши явные emotion/instruct/seed в запросе всегда в приоритете.
Текст диктору можно подсказывать прямо в строке — отдельных параметров для этого не нужно. Это особенно важно, когда реплики пишет языковая модель: букву ё она ставит непредсказуемо.
Заглавная гласная = подсказка. Напишите ударную гласную заглавной, и диктор прочитает по ней: жалюзИ, диспансЕр. Тем же способом выбирается буква Е или Ё: всЕ звучит как «все», всё — как «всё». Так чинится большинство ошибок ударения и произношения.
⚠️Редкие слова не поддаются даже так: у нас записан случай «обработала» — одиннадцать способов записи, ни один не сработал. Если попалось такое слово, перефразируйте его или напишите нам: мы разберём случай и добавим слово в общий словарь исправлений, после чего оно зазвучит верно у всех без правок с вашей стороны. Так, например, было исправлено «все» — теперь оно читается правильно само.
Профиль голоса — источник значений по умолчанию. Настройки, сохранённые у голоса в кабинете («Звучание голоса»: эквалайзер тембра, «Сделать чище», «Студийная полировка», манера чтения), применяются и к API-запросам — агент получает тот же звук, что вы слышите в студии, ничего дублировать в теле запроса не нужно. Параметр, переданный явно, перекрывает сохранённый. Если звук в интеграции отличается от ожидаемого, проверьте профиль голоса, а не только запрос.
Простая речь — в промт агента, не в TTS. Синтез читает текст как есть и слова не подменяет (юридические формулировки, названия и бренды не пострадают). Чтобы агент звучал по-человечески, добавьте в его системный промт правило вида:
Слова, которые движок читает неточно, лечит произносительная база — она общая для сайта и API и самообучается; отдельная просьба — в поддержку.
engine_busy с заголовком Retry-After: 5. Для агента это значит: не запускайте десятки параллельных синтезов на один ключ, ставьте свою очередь и уважайте Retry-After/tts отдаёт готовый файл целиком: короткая реплика (~50 знаков) — около 2 секунд, 480 знаков — около 12 секунд. /tts_stream с умолчанием (быстрый режим) начинает отдавать звук примерно через 0,6 секунды независимо от длины текста — подробности в следующем пункте. Если запросили "mode": "expressive", движок синтезирует фразу целиком и первый звук придёт только в конце: на 480 знаках это около 10 секунд молчания. Планируйте таймауты по режиму, который используете."mode": "expressive", но тогда звук придёт только в конце генерации: на 92 знаках первый звук через 2,6 секунды вместо 0,6, на 480 знаках — около 10 секунд. Умолчание одинаково в /tts_stream и /tts, поэтому характер речи совпадает, если часть реплик вы синтезируете файлом, а часть потоком/tts — 60 секунд на весь ответ; /tts_stream — 30 секунд на первый кадр и 120 секунд без данных подряд. Свой клиентский таймаут ставьте не меньше этих значений, иначе будете рвать живые генерацииX-Concurrency-Used — сколько генераций идёт в эту секунду, X-Concurrency-Limit — сколько слотов всего, X-Concurrency-Queued — сколько запросов ждут очереди, X-Voice-Mode — какой режим подачи применён. Стройте свою очередь по этим числам, а не по догадкам. ⚠️Исключение — ответ из кэша: повторный запрос с тем же текстом, голосом и настройками отдаётся мгновенно с заголовком X-Cache: HIT, и заголовков занятости в нём нет (генерации не было). Считайте их отсутствие признаком кэша, а не сбояGET /api/v1/status отдаёт ready, status (ok · degraded · maintenance · engine_down), причину в note и retry_after_seconds. Опрашивайте его перед стартом кампании и при первом 503 — так вы отличите техработы от разовой перегрузкиseed. Безопасно повторять после 429/503; после 4xx (кроме 429) повтор бессмыслен — исправьте запросformat/response_format: audio/wav, audio/mpeg; телефонные форматы — audio/PCMA;rate=8000 (alaw), audio/PCMU;rate=8000 (mulaw), audio/G722, audio/opus (в контейнере ogg), audio/L16;rate=24000 (сырой PCM 16 бит). Для /tts_stream — application/octet-stream. Без параметра формата приходит WAV 16 бит, моно; частота зависит от голоса — 24 000 или 44 100 Гц. Точное значение для каждого ответа приходит в заголовке X-Sample-Rate: берите его, а не зашитое число, иначе звук проиграется не на своей скорости. Нужна гарантированная частота — просите format=pcm_s16le_24k или телефонный профиль24000 или 44100. Читается из заголовка самого файла, поэтому не расходится с содержимым, и приходит одинаково на свежей генерации и на повторе из кэша. ⚠️Не зашивайте частоту в проигрыватель по документации — голоса разных линий звучат на разной, и ошибка слышна как ускоренная или замедленная речь. Нужна одна и та же всегда — просите 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). Ориентируйтесь на заголовок, а не на фиксированную паузуактивно/всего (например 3/4) — приходит на каждом успешном ответе. Если первая цифра стабильно у потолка, вы упираетесь в ёмкостьdictor) — приходит при синтезе дикторским голосомПоле 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_reading | 400 | Пометка не по правилу В слове должно быть ровно одно ударение, а само слово — не длиннее сорока четырёх знаков. | Оставьте одну пометку ударения на слово. |
bad_request | 400 | Неверный запрос В запросе не хватает обязательного поля или значение недопустимо. | Сверьтесь с описанием метода в документации API. |
email_typo | 400 | Опечатка в адресе почты Домен почты похож на известный с одной ошибкой — например «gmail.cim» вместо «gmail.com». На такой адрес письмо с кодом не придёт. | Проверьте адрес и повторите регистрацию. Подсказка с правильным написанием — в тексте ошибки. |
empty_text | 400 | Пустой текст В запросе нет текста для озвучки. | Введите текст и повторите. |
engine_rejected | 400 | Движок отклонил запрос Синтезатор не принял параметры: чаще всего не тот язык для выбранного голоса. | Проверьте язык и настройки голоса. Библиотечный голос читает на своём родном языке. |
extend_bad | 400 | Неверные параметры продления Продлить песню можно на 10–60 секунд, и продление не совмещается с перепевкой куска. | Выберите длительность хвоста от 10 до 60 секунд. |
extend_bad_variant | 400 | Вариант для продления не найден Указанный вариант песни не существует или песня ещё не готова. | Дождитесь готовности песни и выберите один из её вариантов. |
extend_no_parent | 400 | Нечего продлевать Продление дорисовывает хвост готовой песни — без неё запрос не имеет смысла. | Откройте готовую песню и нажмите «Продлить» у неё. |
library_capability | 400 | Возможность не поддерживается этой группой голосов У дикторских голосов нет эмоций, эффектов, фонов и потоковой отдачи — их сила в точных ударениях. | Уберите неподдерживаемые параметры или выберите голос из универсального каталога. |
name_required | 400 | Не указано имя голоса В запросе на создание голоса нет поля name. | Передайте name — под этим именем голос появится в вашей библиотеке. |
no_audio | 400 | Нет аудио В запросе на расшифровку не пришёл звук. | Приложите файл или base64-строку с записью. |
no_mark | 400 | Ударение не отмечено В пометке нет ни заглавной буквы, ни знака плюс — значит ударение не указано вовсе. | Отметьте ударный гласный: зАмок или з+амок. |
not_in_book | 400 | Текста нет в книге Этот отрывок не найден ни в одной главе книги, поэтому послушать его в голосе книги нельзя. | Выберите место прямо в тексте главы. |
not_same_word | 400 | Пометка меняет само слово Написание в пометке отличается от слова в тексте — так можно подменить текст, а не ударение. | Оставьте буквы слова как есть и отметьте только ударный гласный. |
ref_text_required | 400 | Нет расшифровки образца Не передан ref_text — текст, который звучит в образце. | Передайте ref_text ДОСЛОВНО так, как произнесено в записи: расхождение портит клон. |
repaint_bad_range | 400 | Неверные границы куска Кусок для перепевки должен быть не короче двух секунд и лежать в пределах песни. | Выделите на волне кусок подлиннее и внутри записи. |
repaint_bad_variant | 400 | Исходный вариант не найден Вариант песни, поверх которого просили перепеть, не найден или песня ещё не готова. | Дождитесь готовности песни и повторите с существующим вариантом. |
repaint_no_parent | 400 | Нечего перепевать Перепеть кусок можно только у уже готовой песни. | Откройте готовую песню и выберите кусок на её волне. |
ru_dictor_only | 400 | Русский текст — дикторским голосом Русскую речь мы озвучиваем дикторской линией: у неё выверенные ударения. Выбранный голос каталога на этой линии не существует, поэтому русский текст им не озвучить. | Выберите дикторский голос. Свой собственный голос, если он у вас есть, работает по-прежнему; на других языках выбранный голос тоже доступен. |
sample_too_short | 400 | Образец голоса слишком короткий Записи меньше 10 секунд не хватает, чтобы голос получился похожим. | Запишите 15–30 секунд спокойной речи в тихой комнате и загрузите заново. |
text_too_long | 400 | Текст длиннее предела Текст превышает максимальную длину одного запроса. | Длинные материалы озвучиваются в разделе «Аудиокниги»: там текст идёт частями в фоне. Больший объём за один раз открывает тариф выше. |
too_many_segments | 400 | Слишком много кусков Текст разбит на большее число фрагментов, чем допускает один запрос. | Уберите лишние паузы в разметке: каждая пауза начинает новый кусок, а их число ограничено. |
unsupported_emotion | 400 | Эмоция не распознана Значение emotion не из списка поддерживаемых. | Пришлите одно из перечисленных в ответе значений или уберите параметр — тогда голос звучит нейтрально. Символы не списаны. |
unsupported_eq | 400 | Эквалайзер не распознан Поле eq прислано, но его форма не подходит. | Ожидается {bands:[{hz,db},…]} либо {low,mid,high} в децибелах. Символы не списаны. |
unsupported_format | 400 | Неизвестный формат Запрошенный формат аудио не поддерживается. | Допустимые значения перечислены в поле supported ответа и в документации API. |
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 | Кончились символы На балансе не хватило символов, чтобы озвучить этот текст целиком. | Пополните баланс в разделе «Тариф и лимиты». |
no_credits | 402 | Нулевой баланс Символы на счету закончились. | Пополните баланс в разделе «Тариф и лимиты». |
preview_daily_limit | 402 | Суточный лимит прослушивания Бесплатные прослушивания на сегодня закончились. | Озвучьте через «Скачать файл» — это спишет символы с баланса, зато без суточного лимита. Или вернитесь завтра. |
preview_limit | 402 | Длинный текст для бесплатной пробы Бесплатно можно прослушать только начало текста. Этот длиннее лимита пробы. | Подтвердите платное прослушивание с баланса или нажмите «Скачать файл» — символы спишутся один раз, повторные скачивания бесплатны. |
consent_required | 403 | Нужно согласие на голос Создание голоса требует подтверждения, что вы вправе использовать эту запись. | Поставьте отметку о согласии в мастере создания голоса. |
demo_voice | 403 | Демонстрационный голос Этот голос можно слушать, но нельзя сохранить: у него нет прав на коммерческое использование. | Для скачивания выберите голос без метки «Демо». |
email_unverified | 403 | Почта не подтверждена Озвучка доступна после подтверждения почты. | Откройте раздел «Аккаунт» и введите код из письма. |
format_plan | 403 | Формат открыт на старшем тарифе Скачивание без потерь (FLAC) открыто с тарифа «Старт», мастер для монтажа (WAV) — с «Бизнеса». MP3 доступен на любом тарифе. | Скачайте MP3 или перейдите на тариф выше — «Тарифы» в кабинете. |
kind_not_ready | 403 | Раздел ещё в подготовке Эта функция помечена «Скоро»: качество ещё не прошло проверку. | Дождитесь открытия раздела — анонсируем в новостях. |
library_not_available | 403 | Группа голосов ещё не открыта Эти голоса ещё проходят проверку качества и не открыты для использования. | Дождитесь открытия группы — анонсируем в новостях. |
plan_quota | 403 | Исчерпан лимит тарифа Достигнут месячный лимит вашего плана. | Лимит обновится в начале следующего периода, либо перейдите на тариф выше. |
plan_required | 403 | Нужен другой тариф Эта возможность доступна на более высоком тарифе. | Посмотрите тарифы в кабинете — там указано, что входит в каждый. |
project_limit | 403 | Лимит проектов тарифа Достигнут предел числа проектов на вашем тарифе. | Удалите ненужные проекты или перейдите на старший тариф. |
voice_access | 403 | Голос не на вашем тарифе Голос существует, но на текущем плане недоступен. | Выберите другой голос или перейдите на тариф, где он открыт. |
voice_deleted | 403 | Голос удалён Этот голос удалён, синтезировать им больше нельзя (в проекте он мог остаться выбранным). | Выберите другой голос в списке. Если удалили случайно — создайте голос заново по тому же образцу. |
voice_denied | 403 | Голос без права выгрузки Выбран демонстрационный (исследовательский) голос — выгружать файлы им нельзя. | Выберите коммерческий голос из каталога. |
voice_failed | 403 | Голос не создался Обучение голоса завершилось ошибкой, поэтому синтез им недоступен. | повторить позже |
voice_limit | 403 | Лимит своих голосов На вашем тарифе закончились места под собственные голоса. | Удалите ненужный голос или перейдите на тариф с большим числом мест. |
voice_not_found | 403 | Голос не найден Такого голоса нет ни в каталоге, ни среди ваших и купленных. | Проверьте идентификатор голоса; полный список — /api/voices/library. |
voice_not_ready | 403 | Голос ещё готовится Ваш голос создан, но обучение ещё идёт — синтезировать им пока нельзя. | Подождите несколько минут. Удалять и создавать голос заново НЕ нужно. |
not_found | 404 | Объект не найден Запрошенной записи нет: удалена или адрес неверный. | Обновите страницу и проверьте, что объект существует. |
chapters_missing_audio | 409 | У части глав нет звука Книга помечена готовой, но у некоторых глав звук отсутствует — собрать один файл нельзя. | Откройте список глав, озвучьте те, что без звука, и соберите книгу снова. |
conflict | 409 | Занято обработкой Объект сейчас обрабатывается, поэтому изменить его нельзя. | Дождитесь окончания обработки и повторите. |
export_in_progress | 409 | Сохранение уже идёт Предыдущее сохранение или экспорт ещё не закончились. | Дождитесь окончания — повторный запуск не нужен. |
length_mismatch | 409 | Запись не совпала с текстом Сохраняемая озвучка не соответствует текущему тексту проекта. | Ничего делать не нужно: озвучим заново под изменённый текст. |
no_master | 409 | У песни нет оригинала Песня сделана до того, как мы начали хранить оригиналы. Развернуть сжатый файл обратно нельзя: звук остался бы тем же, а вес вырос бы в десять раз. | Скачайте MP3. Нужен оригинал — сделайте новую версию песни, у неё он будет. |
no_voice | 409 | Голос книги не выбран Для книги ещё не выбран голос, а слушать отрывок нужно именно её голосом. | Выберите голос книги на экране подготовки и повторите. |
not_dictor | 409 | Ударения работают не на этом голосе У выбранного голоса ударения расставляет модель, поэтому ваши пометки на нём не действуют. | Для книги с пометками ударений выберите голос, у которого в списке указано «Дикторский». |
not_done | 409 | Книга озвучена не целиком Собрать книгу в один файл можно, когда озвучены все главы. Часть глав ещё не готова. | Озвучьте оставшиеся главы — их видно по пометкам в списке — и соберите книгу снова. |
voice_change_revoice | 409 | Смена голоса = переозвучка Голос книги меняется только вместе с переозвучкой всех глав. | Подтвердите переозвучку книги, если готовы к списанию символов. |
voice_conflict | 409 | Такое имя голоса занято Голос с таким именем у вас уже есть. | Выберите другое имя. |
voice_not_available | 409 | Голос недоступен Этот голос вам сейчас недоступен: он удалён, не ваш или закрыт тарифом. | Выберите другой голос в списке. |
voice_not_available_yet | 409 | Голос ещё готовится Голос создан, но ещё не готов к синтезу — фабрика доводит его до рабочего состояния. | Подождите: на карточке голоса появится отметка готовности. Обычно это занимает несколько минут. |
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 | В файле нет текста Файл прочитан, но текста в нём не нашлось — например, это скан-картинки. | Загрузите текстовую версию: скан сначала нужно распознать. |
not_found_in_text | 422 | Слово в главе не найдено Этого слова в тексте главы нет — возможно, текст изменился после того, как вы открыли экран. | Обновите страницу и поставьте пометку заново на слово из текста. |
parse_failed | 422 | Файл не разобран Не удалось разобрать структуру файла. | Пересохраните файл в другом редакторе или загрузите в другом формате. |
concurrency_limit | 429 | Слишком много запросов сразу Одновременных озвучек больше, чем позволяет тариф. | Дождитесь окончания текущих или повторите через время из заголовка Retry-After. |
limit | 429 | Лимит работ «Споём» Достигнут предел одновременных или суточных работ с песнями (генерация и разделение считаются одним правилом). | Дождитесь завершения текущих работ или вернитесь завтра. |
rate_limited | 429 | Слишком часто Превышена частота запросов в минуту. Счёт ведётся НА АККАУНТ, а не на ключ: второй ключ частоту не удваивает. | Дождитесь секунд из заголовка Retry-After и повторите. Нужен запас — напишите нам. |
too_many_requeues | 429 | Слишком много повторов задачи Задачу расшифровки перезапускали слишком много раз подряд. | Загрузите файл заново. |
client_aborted | 499 | Клиент прервал сам Соединение закрыто со стороны клиента: закрыта вкладка, нажат стоп или пропала связь. | — |
empty_concat | 500 | Сборка книги дала пустой файл При склейке глав получился пустой файл — это наша ошибка, а не ваша. | повторить позже |
internal_error | 500 | Внутренняя ошибка Что-то пошло не так на нашей стороне. | повторить позже |
job_failed | 500 | Задача не создалась Не удалось поставить работу в очередь. | повторить позже |
save_failed | 500 | Голос не сохранён Голос синтезирован, но не записался в библиотеку. | повторить позже |
telephony_failed | 500 | Не собрался телефонный формат Звук синтезирован, но преобразование в телефонный формат не удалось. | повторить позже |
clone_failed | 502 | Не удалось создать голос Движок не смог построить голос по образцу. | повторить позже |
engine_empty | 502 | Пустой ответ движка Синтез завершился, но звук не пришёл. | повторить позже |
engine_error | 502 | Ошибка движка Движок вернул ошибку при обработке текста. | повторить позже |
full_failed | 502 | Файл не собрался Не удалось получить готовый файл книги. | повторить позже |
mp3_failed | 502 | Конвертация в MP3 не удалась Озвучка синтезирована, но перекодировать её в MP3 не получилось. Списанные символы возвращены. | повторить позже |
scan_failed | 502 | Разбор главы не удался Служба разбора текста не ответила или ответила непонятно, поэтому список спорных слов не собран. | повторить позже |
synth_failed | 502 | Озвучка отрывка не удалась Служба синтеза не смогла озвучить этот отрывок. | повторить позже |
transcribe_error | 502 | Ошибка распознавания Расшифровка не удалась на нашей стороне. | повторить позже |
asr_vram_low | 503 | Не хватило памяти на карте Распознаванию не хватило видеопамяти — её заняли озвучка и перевоплощение. | повторить позже |
billing_unavailable | 503 | Биллинг недоступен Не удалось проверить баланс. | повторить позже |
demo_unavailable | 503 | Демо недоступно Демонстрационная озвучка на главной временно не работает. | повторить позже |
engine_busy | 503 | Движок перегружен Сейчас слишком много одновременных озвучек. | повторить позже |
engine_off | 503 | Служба озвучки недоступна Служба синтеза сейчас не отвечает, поэтому разобрать главу и озвучить её не получилось. | повторить позже |
engine_unavailable | 503 | Движок недоступен Сервис синтеза временно не отвечает. | повторить позже |
kind_paused | 503 | Сервер песен отдыхает Машину генерации песен выключают, когда заказов нет, — это экономия, не поломка. | Загляните чуть позже: раздел проснётся автоматически, как только сервер включат. |
mp3_unavailable | 503 | MP3 временно недоступен Кодировщик MP3 на сервере сейчас недоступен; символы не списаны. | повторить позже |
orig_pin_failed | 503 | Исходник не зафиксирован Не удалось закрепить исходную запись перед обработкой. | повторить позже |
stress_unavailable | 503 | Слой ударений недоступен Служба, которая расставляет ударения для дикторских голосов, сейчас не отвечает. | повторить позже |
temporary_unavailable | 503 | Временно недоступно Сервис на короткое время недоступен. | повторить позже |
bad_json), пустой текст (empty_text), текст длиннее лимита тарифа (text_too_long), больше 40 сегментов (too_many_segments), плоский текст длиннее 3000 символов или неизвестный движку язык (engine_rejected). При создании голоса — не переданы обязательные поля: name_required, ref_text_required, audio_required, consent_requiredcode=plan_required) или нет доступа к голосу: voice_not_available — голос не найден либо чужой приватный; voice_not_available_yet — голос помечен «Скоро», синтез им пока отключён (см. поле badge в каталоге). Также: email_unverified — платные вызовы по ключу требуют подтверждённой почты аккаунта; voice_limit — достигнут лимит клонов тарифа; plan_quota — исчерпана квота расшифровки; library_not_available — линейка голоса выключенаvoice_conflict): голос с таким именем уже есть — при создании голоса укажите другое имяcode=audio_too_large)internal_error) — например при чтении каталога голосов. Повторите запрос; если повторяется — напишите в поддержкуengine_error, engine_empty, telephony_failed, transcribe_error, mp3_failed (символы за неотданный MP3 возвращаются)Тело ошибки — JSON { "error": "описание", "code": "машинный_код" }. Разбирайте code, а не текст: тексты мы переписываем, коды не меняем. Символы при неуспехе не списываются. Исключение — обрыв потока /tts_stream на середине: списываются только символы за фактически доставленное аудио, остаток возвращается.
Параметр effect — один пресет на запрос. Бесплатные доступны всем; премиум — на платных тарифах.
concurrency_limit с Retry-After: дождитесь завершения текущей генерации, а не шлите повтор сразу. Текущее состояние видно в заголовках любого успешного ответа (X-Concurrency-Used и X-Concurrency-Limit). Для голосовых агентов это главное ограничение: именно оно определяет, сколько разговоров вы ведёте одновременноВ кабинете → раздел «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 МБ base64), 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.
Обновите и повторите запрос. Если повторяется — это дефект на нашей стороне (не ваша настройка и не паузы): напишите в поддержку с примером и параметрами запроса, починим.