Сервис Yandex SpeechKit TTS (Text-to-Speech) преобразует текст в речь через облачный API, и первое, что нужно проверить при интеграции, — наличие платёжного аккаунта в Yandex Cloud и корректный API-ключ или IAM-токен: без них любой запрос к tts.api.cloud.yandex.net вернёт ошибку авторизации ещё до начала синтеза. Сам синтез занимает доли секунды, но большинство проблем у разработчиков возникает не с генерацией звука, а с аутентификацией, форматами ответа и лимитами запросов.
В этом руководстве разберём, как устроен синтез речи в SpeechKit, какие голоса и форматы доступны, как правильно сформировать запрос и что делать, если API возвращает ошибки. Материал ориентирован на разработчиков, которые подключают озвучку к сайту, боту, IVR-системе или мобильному приложению.
Как работает синтез речи в SpeechKit
Принцип работы Text-to-Speech от Яндекса строится на нейросетевых моделях: текст проходит лингвистическую обработку (нормализация чисел, дат, аббревиатур), затем акустическая модель строит мел-спектрограмму, а вокодер превращает её в звуковую волну. На практике вам не нужно вникать в эти этапы — достаточно отправить текст и параметры, а в ответ получить готовый аудиофайл.
Сервис поддерживает два способа обращения: REST API для простых разовых запросов и gRPC API для потокового синтеза, когда аудио нужно получать частями по мере генерации. Для голосовых помощников и телефонии потоковый режим снижает задержку до первого звука, для озвучки статей достаточно обычного REST-запроса.
Доступны два режима разметки входного текста: обычный текст и SSML (Speech Synthesis Markup Language) — разметка, позволяющая управлять паузами, ударениями и произношением отдельных слов. Если нужно точно задать, как сервис прочитает фразу, используйте SSML.
Подготовка: ключи, каталог и права
Перед первым запросом необходимо выполнить настройку в консоли Yandex Cloud. Порядок действий не зависит от языка программирования, который вы планируете использовать.
- 🔑 Создайте сервисный аккаунт в консоли облака и назначьте ему роль, дающую доступ к SpeechKit.
- 🗝️ Выпустите API-ключ для сервисного аккаунта — это самый простой способ аутентификации для TTS.
- 📁 Запомните ID каталога (folder ID) — он обязательно передаётся в каждом запросе.
- 💳 Убедитесь, что к облаку привязан активный платёжный аккаунт, иначе запросы будут отклоняться.
API-ключ передаётся в заголовке Authorization: Api-Key <ключ>. Альтернатива — IAM-токен в заголовке Authorization: Bearer <токен>, но он имеет ограниченный срок жизни и требует периодического обновления, поэтому для серверных интеграций удобнее API-ключ.
⚠️ Внимание: никогда не встраивайте API-ключ в клиентский код мобильного приложения или JavaScript на странице — ключ станет доступен любому пользователю, а расходы за чужие запросы лягут на ваш платёжный аккаунт. Проксируйте запросы через свой бэкенд.
Формирование запроса к TTS API
Базовый запрос к REST API отправляется методом POST на адрес https://tts.api.cloud.yandex.net/speech/v1/tts:synthesize. Тело запроса передаётся в формате URL-encoded и содержит текст, параметры голоса и формат аудио.
curl -X POST \
-H "Authorization: Api-Key ВАШ_КЛЮЧ" \
-d "text=Привет, это тест синтеза речи" \
-d "lang=ru-RU" \
-d "voice=alena" \
-d "folderId=ВАШ_КАТАЛОГ" \
-d "format=mp3" \
"https://tts.api.cloud.yandex.net/speech/v1/tts:synthesize" \
--output result.mp3
Если всё настроено верно, в ответ придёт бинарное аудио, которое сохранится в файл result.mp3. Если вместо звука вы получили JSON с полем error_code — разбирайте код ошибки: чаще всего это 401 (проблема с ключом) или 400 (некорректный параметр).
☑️ Проверка перед первым запросом
Голоса, скорость и форматы аудио
SpeechKit предлагает несколько голосов для русского языка — например, alena и filipp относятся к премиальным нейросетевым голосам с более естественной интонацией. Точный актуальный список голосов стоит уточнять в официальной документации, так как Яндекс периодически добавляет новые и выводит старые из эксплуатации.
| Параметр | Назначение | Пример значения |
|---|---|---|
voice | Выбор голоса диктора | alena, filipp |
format | Формат выходного аудио | mp3, oggopus, lpcm |
speed | Скорость речи | 1.0 (нормальная) |
emotion | Эмоциональная окраска | good, neutral, evil |
sampleRateHertz | Частота дискретизации | 48000, 16000, 8000 |
Для телефонии и IVR обычно выбирают формат lpcm с частотой 8000 Гц — это соответствует стандартам телефонных каналов. Для сайтов и приложений удобнее mp3 или oggopus с более высоким качеством. Параметр emotion поддерживается не всеми голосами — проверяйте совместимость в документации конкретного голоса.
SSML-разметка: управление произношением
Когда стандартный синтез неверно ставит ударение или сливается в монотонную речь, на помощь приходит SSML. Текст с разметкой передаётся в параметре ssml вместо text и оборачивается в корневой тег <speak>.
<speak>
У меня всё <prosody pitch="high">отлично</prosody>!
<break time="500ms"/>
А у вас?
</speak>
Основные возможности разметки: паузы заданной длительности (<break>), изменение высоты и темпа фрагмента (<prosody>), фонетическая подстановка для сложных слов (<phoneme>). С помощью <phoneme> можно явно указать ударение, например для слова «замок» в значении «зАмок» против «замОк».
⚠️ Внимание: при использовании SSML весь текст должен быть валидным XML внутри тега<speak>. Неэкранированные символы&,<,>в исходном тексте приведут к ошибке парсинга — заменяйте их на XML-сущности.
Типичные ошибки и их решение
Разберём ситуации, с которыми разработчики сталкиваются чаще всего. Ошибка 401 Unauthorized почти всегда означает неверный или просроченный токен: проверьте, что ключ скопирован полностью и передаётся именно в заголовке Authorization, а не в теле запроса.
Ошибка 400 Bad Request указывает на проблему в параметрах: неподдерживаемое имя голоса, отсутствующий folderId или одновременную передачу text и ssml. Если текст длинный, учитывайте ограничение на максимальную длину одного запроса — большие тексты необходимо разбивать на части по предложениям и склеивать аудио на своей стороне.
- 🔇 Пустой или битый файл в ответе — проверьте, не записали ли вы в файл JSON с ошибкой вместо аудио.
- 🐢 Высокая задержка первого байта — переходите на gRPC-поток или сокращайте текст запроса.
- 🗣️ Неправильное ударение — используйте SSML-тег
<phoneme>с явным указанием фонем. - 📉 Превышение лимитов — добавьте очередь запросов и повторные попытки с экспоненциальной задержкой.
Как разбивать длинный текст на части
Делите текст по знакам препинания (точка, вопросительный и восклицательный знаки), сохраняя целостность предложений. Каждый фрагмент отправляйте отдельным запросом, а полученные аудиофайлы объединяйте последовательно — например, утилитой ffmpeg с параметром concat. Между фрагментами при необходимости вставляйте короткую тишину.
Стоимость и оптимизация расходов
Тарификация SpeechKit TTS построена по принципу оплаты за объём синтезированного текста — как правило, за миллион символов, причём премиальные голоса тарифицируются отдельно от стандартных. Точные цены зависят от текущего прайс-листа Yandex Cloud, поэтому сверяйте их на официальной странице тарифов перед планированием бюджета.
Главный способ экономии — кеширование результатов синтеза по хешу текста и параметров голоса: повторная озвучка одной и той же фразы не должна вызывать новый платный запрос. Для типового контента (приветствия, пункты меню, системные сообщения) кеш покрывает практически все обращения.
Дополнительно следите за длиной текстов: лишние пробелы, служебные символы и разметка тоже могут учитываться при подсчёте. Очищайте текст от HTML и невидимых символов перед отправкой.
Итоги и рекомендации
Подключение Yandex SpeechKit TTS сводится к трём шагам: настройка сервисного аккаунта с API-ключом, корректный POST-запрос с текстом и параметрами голоса, обработка аудио в ответе. Сложности начинаются на этапе масштабирования — потокового синтеза, кеширования и контроля расходов.
Начинайте с простого REST-запроса через curl, убедитесь в стабильной авторизации, и только потом переносите логику в код приложения. Для проектов с требованиями к естественности речи тестируйте премиальные голоса и SSML-разметку — разница с базовым синтезом заметна на слух.
Частые вопросы
Можно ли использовать SpeechKit TTS бесплатно?
Сервис тарифицируется по объёму синтезированного текста. Yandex Cloud периодически предоставляет стартовые гранты новым пользователям — их можно потратить на тестирование SpeechKit. Актуальные условия уточняйте в консоли облака.
Какой формат аудио выбрать для сайта?
Для веб-проектов оптимален mp3 — он воспроизводится всеми браузерами без дополнительных библиотек. Формат oggopus даёт лучшее качество при меньшем размере, но проверяйте поддержку в целевых браузерах.
Почему API возвращает ошибку 401 при верном ключе?
Частые причины: пробелы при копировании ключа, передача ключа в теле запроса вместо заголовка, удалённый или заблокированный сервисный аккаунт. Проверьте также, что запрос идёт по HTTPS на правильный адрес API.
Как озвучить длинную статью целиком?
Разбейте текст на фрагменты по предложениям, отправьте каждый отдельным запросом и склейте полученные аудиофайлы последовательно, например через ffmpeg. Прямая отправка большого текста одним запросом ограничена лимитами API.
Поддерживает ли TTS другие языки, кроме русского?
Да, SpeechKit поддерживает несколько языков — язык задаётся параметром lang, а набор доступных голосов различается для каждого языка. Актуальный перечень смотрите в официальной документации сервиса.