Сервис Yandex Text to Speech реализован в составе облачной платформы Yandex Cloud как часть API SpeechKit, и для его использования требуется создать сервисный аккаунт, получить API-ключ или IAM-токен и отправить текст на эндпоинт синтеза речи. Без действующего ключа и подключённого биллинга запрос вернёт ошибку авторизации — это самая частая причина, с которой сталкиваются новые пользователи при первой попытке озвучить текст.
В этой статье разберём, как устроен синтез речи от Яндекса, какие голоса и языки доступны, как управлять произношением через SSML-разметку, какие лимиты действуют и как исправить типичные ошибки при интеграции. Материал подойдёт разработчикам, владельцам голосовых ботов и всем, кто хочет озвучивать тексты программно.
Что такое Yandex SpeechKit Text to Speech
Функция преобразования текста в речь (Text-to-Speech, TTS) в SpeechKit принимает текстовую строку и возвращает аудиофайл в выбранном формате. Сервис работает по модели «запрос — ответ»: вы отправляете HTTP-запрос с текстом и параметрами голоса, а в ответ получаете бинарные аудиоданные.
Синтез поддерживает несколько языков, включая русский, английский и ряд других. Точный актуальный список языков и голосов стоит проверять в официальной документации Yandex Cloud, так как он периодически расширяется, а отдельные голоса могут выводиться из эксплуатации.
- 🎙️ Несколько голосов — мужские и женские, с разной эмоциональной окраской для части голосов.
- 🌍 Мультиязычность — синтез на русском, английском и других поддерживаемых языках.
- 🔧 SSML-разметка — управление паузами, ударениями и произношением отдельных слов.
- 📦 Форматы аудио — получение результата в сжатых и несжатых форматах, например OGG Opus или LPCM.
- ⚡ Streaming API — потоковый синтез для приложений реального времени через gRPC.
Подготовка: аккаунт, ключ и первый запрос
Перед первым вызовом API нужно выполнить несколько обязательных шагов в консоли Yandex Cloud. Без них любой запрос будет отклонён с ошибкой аутентификации.
Порядок действий выглядит так: создайте облако и каталог, привяжите платёжный аккаунт (даже для тестирования в рамках гранта), затем создайте сервисный аккаунт с ролью, допускающей использование SpeechKit, и выпустите для него API-ключ. Храните ключ в переменных окружения, а не в коде приложения.
☑️ Подготовка к работе с Yandex TTS
Пример запроса через curl выглядит примерно так (актуальный URL и параметры сверяйте с документацией — они могут меняться):
curl -X POST \
-H "Authorization: Api-Key ${API_KEY}" \
-d "text=Привет, это тест синтеза речи" \
-d "lang=ru-RU" \
-d "format=oggopus" \
"https://tts.api.cloud.yandex.net/speech/v1/tts:synthesize" \
--output result.ogg
В ответ при успехе приходит бинарное аудио, которое сохраняется в файл. Если вместо аудио вернулся JSON с описанием ошибки — читайте код и сообщение, обычно там прямо указана причина отказа.
Выбор голоса и языка
Голос задаётся параметром voice, язык — параметром lang. Важно, чтобы голос соответствовал выбранному языку: попытка озвучить русский текст голосом, предназначенным для другого языка, даст либо ошибку, либо некорректное произношение.
Для части голосов доступен параметр эмоциональной окраски (emotion), например нейтральная, доброжелательная или строгая подача. Поддержка эмоций зависит от конкретного голоса — проверяйте это в справочнике голосов в документации.
⚠️ Внимание: состав голосов и их параметры периодически меняются. Не зашивайте имя голоса в код «навсегда» без проверки — вынесите его в конфигурацию, чтобы при выводе голоса из эксплуатации заменить значение в одном месте.
Управление произношением через SSML
Обычный «плоский» текст синтезатор читает с интонациями по умолчанию, что не всегда подходит: аббревиатуры произносятся неправильно, паузы отсутствуют, ударения ставятся неверно. Для тонкой настройки используется SSML (Speech Synthesis Markup Language) — XML-подобная разметка внутри текста запроса.
Чтобы сервис воспринял разметку, текст нужно передать в параметре ssml вместо text, обернув содержимое в корневой тег <speak>.
- ⏸️
<break>— вставка паузы заданной длительности между фразами. - 🔤
<phoneme>— фонетическое произношение для сложных слов и имён. - 📢
<prosody>— изменение темпа и высоты речи для фрагмента. - ⏭️
<sub>— подмена произношения: например, читать «г.» как «город».
⚠️ Внимание: ошибка в XML-структуре SSML (незакрытый тег, лишний символ) приведёт к отказу всего запроса. Валидируйте разметку перед отправкой, особенно если она собирается динамически из пользовательских данных.
Лимиты, форматы и тарификация
Сервис ограничивает максимальную длину текста в одном запросе. Если нужно озвучить длинный материал — статью или главу книги — текст разбивают на фрагменты по предложениям и синтезируют по частям, после чего склеивают аудио. Разбивайте по границам предложений, а не посередине фразы, чтобы не было резких обрывов интонации.
Оплата начисляется за количество символов, отправленных на синтез. Точные тарифы и квоты зависят от текущих условий Yandex Cloud — сверяйтесь с разделом ценообразования в консоли, так как цены пересматриваются.
| Параметр | Что задаёт | Типичные значения |
|---|---|---|
text / ssml | Исходный текст или разметка | Строка ограниченной длины |
lang | Язык синтеза | ru-RU, en-US и др. |
voice | Голос диктора | Имя из справочника голосов |
format | Формат аудио | oggopus, lpcm |
sampleRateHertz | Частота дискретизации | Например, 8000–48000 |
Для телефонии обычно выбирают низкую частоту дискретизации и линейный PCM — это совместимо с большинством АТС. Для озвучки контента на сайте удобнее OGG Opus: файлы заметно меньше при сопоставимом качестве.
Типичные ошибки и их решение
Большинство проблем при работе с API сводится к нескольким повторяющимся сценариям. Ниже — диагностика по симптомам.
Ошибка 401 / Unauthorized. Проверьте, что ключ передаётся в заголовке Authorization в правильном формате, что он не отозван и что сервисный аккаунт имеет роль, разрешающую вызовы SpeechKit. IAM-токен имеет ограниченный срок жизни — если он протух, запросите новый.
Ошибка 400 / Bad Request. Обычно это невалидные параметры: неподдерживаемое имя голоса, несовместимая комбинация формата и частоты дискретизации, битый SSML. Сверьте каждое значение со справочником параметров.
Ошибка 429 / превышение квоты. Слишком частые запросы. Добавьте в код повторные попытки с экспоненциальной задержкой (backoff) и при необходимости запросите повышение квот через поддержку.
Плохое качество произношения. Это не ошибка API, а ограничение синтеза: лечится SSML-разметкой, сменой голоса или подменой написания проблемных слов через тег <sub>.
Как организовать повторные попытки при ошибках
Реализуйте цикл с задержкой: при ответе 429 или 5xx ждите 1 секунду, затем 2, затем 4 и так далее, не более 4–5 попыток. Ошибки 4xx (кроме 429) повторять бессмысленно — исправляйте сам запрос. Логируйте тело ответа при каждой неудаче: там почти всегда есть текстовое описание причины.
⚠️ Внимание: не отправляйте в запросах персональные данные пользователей без необходимости и правовых оснований. Текст, переданный на синтез, обрабатывается на стороне облака — учитывайте это при проектировании системы и ознакомьтесь с условиями обработки данных в Yandex Cloud.
Где применяется синтез речи от Яндекса
Технология используется в голосовом помощнике Алиса, а внешним разработчикам доступна через тот же стек SpeechKit. Типовые сценарии: озвучка ответов чат-ботов, голосовые меню в телефонии, аудиоверсии статей, уведомления в мобильных приложениях и доступность интерфейсов для людей с нарушениями зрения.
Если вам нужна разовая озвучка текста без программирования, API может быть избыточным — посмотрите готовые инструменты и демо-страницы, где текст озвучивается прямо в браузере. Для интеграции в продукт, напротив, потребуется полноценная работа с API и обработкой ошибок.
Часто задаваемые вопросы
Можно ли использовать Yandex Text to Speech бесплатно?
Сервис тарифицируется по количеству символов, однако новым пользователям Yandex Cloud обычно предоставляется стартовый грант, которого хватает на тестирование. Актуальные условия и размер гранта проверяйте в консоли управления.
Какой формат аудио выбрать для сайта?
Для веба чаще всего подходит OGG Opus — он даёт хорошее качество при небольшом размере файла. Если нужна совместимость с телефонией, выбирайте LPCM с низкой частотой дискретизации.
Почему синтезатор неправильно произносит слово?
Это ограничение автоматического синтеза: редкие слова, аббревиатуры и имена могут читаться с ошибками. Исправьте произношение через SSML — теги <sub> или <phoneme>, либо напишите слово так, как оно должно звучать.
Есть ли ограничение на длину текста в одном запросе?
Да, максимальная длина одного запроса ограничена. Длинные тексты разбивайте на фрагменты по границам предложений и синтезируйте по частям, затем склеивайте аудио. Точный лимит уточняйте в документации — он может меняться.
Чем IAM-токен отличается от API-ключа?
API-ключ не имеет срока действия и проще в использовании, а IAM-токен нужно периодически обновлять, но он даёт более гибкое управление доступом. Для серверных приложений подходят оба варианта — выбор зависит от вашей политики безопасности.