Genius-bot · 11 минут чтения
Если на сайте есть документы и длинные страницы, api озвучки текста позволяет добавить аудиоверсию без ручной записи каждого материала. Для сценария доступности важна не только сама генерация речи: нужно решить, какие элементы страницы читать, где делать паузы и как дать пользователю возможность быстро перейти к нужному разделу. Раздел API для подключения и получения ключа находится здесь: API и ключ доступа.
В этой статье разберём практический вариант: берём текст документа или страницы, очищаем его от навигационного шума, разбиваем на логические части и отправляем их на озвучку. Отдельно проверим темп, паузы и структуру аудиоверсии, потому что дословное чтение HTML редко даёт удобный результат.
1) Кому и зачем нужна озвучка страницы
Озвучка для слабовидящих нужна прежде всего там, где человеку трудно постоянно воспринимать текст глазами: в длинных инструкциях, статьях, справочных материалах, формах и документах. Но аудио может быть полезно и пользователям, которым удобнее слушать материал во время другой деятельности. В обоих случаях задача сайта — не просто получить голосовой файл, а сохранить понятную структуру исходного материала.
Например, исходная страница может содержать заголовок, несколько разделов, списки, основной текст, подписи к изображениям, кнопки и футер. Если передать весь извлечённый текст в озвучку без обработки, пользователь услышит последовательность вроде «Главная. Каталог. Поиск. Войти. Заголовок статьи…» и только после этого доберётся до содержания. Для доступности сайта озвучка должна начинаться с полезной информации, а служебные элементы следует обрабатывать отдельно.
Удобная схема состоит из пяти этапов: получить содержимое, очистить его, определить структуру, сформировать аудио и дать пользователю управление воспроизведением. При этом API можно использовать не только для отдельных страниц. Тот же подход подходит для подготовки аудиоверсии документа, если текст документа сначала извлекается приложением.
На уровне приложения стоит хранить исходный текст и его структуру отдельно от готовых аудиофайлов. Тогда изменение одного абзаца не требует пересобирать всю страницу. Например, документ из 10 разделов можно обрабатывать по разделам, а пользователю показывать 10 отдельных дорожек или один объединённый файл с навигацией по временным меткам.
Для подключения используется базовый адрес https://genius-bot.ru/wp-json/genius/v1. Авторизация выполняется заголовком Authorization: Bearer <ключ>; ключ выдаётся после входа в разделе API и показывается один раз, поэтому его стоит сохранить в переменной окружения, а не помещать непосредственно в код клиентской части сайта.
2) Темп, паузы и громкость: что отличается от обычной озвучки
Обычная рекламная или презентационная озвучка может быть рассчитана на выразительность. Для доступности приоритет другой: пользователь должен без лишнего напряжения распознавать слова, понимать структуру текста и успевать осмысливать переходы между блоками. Поэтому слишком быстрый темп может оказаться проблемой даже при хорошем качестве синтеза речи.
Особенно важны паузы после заголовков и перед началом нового смыслового блока. Если текст содержит четыре раздела, их лучше отделить не только визуально, но и в аудио. Практически это означает, что перед озвучкой полезно преобразовать структуру страницы примерно так: «Раздел: Требования. Пауза. Далее — список требований…» вместо непрерывного чтения всех элементов.
Не стоит пытаться компенсировать плохую структуру исключительно увеличением громкости. Пользователь должен иметь возможность самостоятельно регулировать громкость средствами проигрывателя, а текст для синтеза следует готовить так, чтобы слова не сливались в длинную непрерывную последовательность.
Для списков полезно явно сообщать их структуру. Например, вместо «Пароль должен содержать… Длина… Символ…» можно использовать формулировку «Требования к паролю. Пункт первый… Пункт второй…». Это увеличивает длину аудио, но одновременно даёт слушателю информацию о том, где начинается и заканчивается каждый элемент.
Такая обработка особенно важна для длинных документов. Если каждый абзац передавать как отдельную независимую задачу, приложение сможет повторно озвучить только изменённый фрагмент. Если же весь документ всегда отправляется одним блоком, любое небольшое изменение приводит к повторной генерации всей аудиоверсии.
Для операции озвучки используется маршрут POST /generate. Перед запуском приложение может запросить список доступных операций через GET /services, а после запуска проверять состояние через GET /tasks/{id}. Если не хочется постоянно опрашивать API, можно передать параметр callback_url: после готовности задачи на этот адрес приходит POST.
curl -X POST "https://genius-bot.ru/wp-json/genius/v1/generate" \
-H "Authorization: Bearer $GENIUS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"service": "tts",
"text": "Раздел первый. Требования к документу. Далее перечислены основные пункты."
}'Конкретные обязательные поля запроса лучше получать из актуального ответа GET /services, поскольку именно этот маршрут предназначен для списка операций и цен. Сам принцип интеграции при этом остаётся одинаковым: авторизация, запуск операции, получение идентификатора задачи и получение результата.
3) Что пропускать: меню, подписи, служебные блоки
Главная ошибка при автоматической озвучке страницы — считать всё текстовое содержимое одинаково полезным. HTML может содержать название сайта, пункты меню, хлебные крошки, кнопки, рекламные блоки, подписи, уведомления, основной текст и технические сообщения. Если отправить всё подряд, аудиоверсия становится длиннее и сложнее для навигации.
Первое правило — отделить основной контент от интерфейса. Меню верхнего уровня не обязательно повторять в каждой статье: пользователь уже находится на странице и ему важнее услышать название материала и его содержание. Аналогично не стоит многократно читать один и тот же футер после каждого раздела.
С подписями к изображениям нужен контекстный подход. Если изображение содержит схему, график или другую информацию, полностью исключать подпись нельзя. Если это декоративная фотография, чтение служебного описания может только перегружать аудио.
Для кнопок и элементов управления лучше использовать их собственную доступную семантику, а не вставлять названия кнопок в основной аудиопоток. Если пользователь слушает статью, фраза «подписаться», повторяющаяся после каждого абзаца, не помогает понять содержание. Управление воспроизведением должно оставаться отдельным слоем интерфейса.
При подготовке текста удобно ввести явные категории: content, heading, list, caption, navigation и controls. В TTS отправляются только разрешённые категории, а заголовки и списки преобразуются в дополнительные речевые маркеры. Это проще поддерживать, чем набор исключений вроде «не читать этот div, кроме случая, когда…».
Для документа действует тот же принцип. Служебные сведения вроде номера страницы, повторяющегося колонтитула или технического идентификатора обычно не должны становиться частью основного аудиотекста. При этом заголовки разделов, предупреждения и важные примечания нужно сохранять, иначе слушатель потеряет часть структуры документа.
4) Навигация по разделам в аудиоверсии
Длинная аудиоверсия без навигации быстро превращается в линейную дорожку, которую трудно использовать. Пользователь должен понимать, где он находится, и иметь возможность перейти к нужному разделу без перемотки с начала. Поэтому структуру документа лучше переносить в интерфейс проигрывателя.
Самый простой вариант — создавать отдельную TTS-задачу для каждого крупного раздела. Например, документ содержит введение и пять разделов. Приложение создаёт шесть задач, сохраняет результат каждой и показывает список: «Введение», «Раздел 1», «Раздел 2» и так далее. При обновлении раздела пересобирается только его аудио.
Другой вариант — собрать один длинный файл после генерации отдельных фрагментов. Тогда в базе данных можно хранить соответствие между заголовком и диапазоном времени: «Раздел 3 — 08:42–12:15». Проигрыватель использует эти данные для перехода по оглавлению.
Для небольших материалов достаточно отдельного файла на каждый раздел. Для больших документов имеет смысл дополнительно хранить статус каждой задачи: queued, processing, completed или фактические значения, которые возвращает API. Важно ориентироваться на реальный ответ GET /tasks/{id}, а не зашивать предполагаемые статусы в клиент.
Python-клиент может выглядеть так:
import os
import requests
BASE_URL = "https://genius-bot.ru/wp-json/genius/v1"
API_KEY = os.environ["GENIUS_API_KEY"]
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"service": "tts",
"text": (
"Раздел два. Темп и паузы. "
"В этом разделе описаны требования к удобному прослушиванию."
)
}
response = requests.post(
f"{BASE_URL}/generate",
headers=headers,
json=payload,
timeout=60,
)
response.raise_for_status()
task = response.json()
print(task)После запуска приложение получает данные задачи из ответа и использует её идентификатор для дальнейшей проверки через GET /tasks/{id}. Если передан callback_url, отдельный обработчик вашего сайта может принять уведомление о готовности и сохранить ссылку на результат.
Для высокой нагрузки полезно учитывать ограничение частоты: не больше 60 запросов в минуту на один ключ. Это касается не только генерации, но и архитектуры проверки задач: частый опрос статуса каждой задачи может быстро создать лишние запросы. Webhook позволяет не держать постоянный цикл polling для уже запущенных операций.
5) Проверка: пройти путь целиком на слух
Готовую озвучку нельзя проверять только глазами по исходному тексту. Нужно пройти пользовательский сценарий от начала до конца: открыть страницу, запустить воспроизведение, перейти к следующему разделу, поставить паузу, вернуться назад и снова найти нужный фрагмент.
Первый тест — начало страницы. После запуска пользователь должен сразу понять, что именно он слушает. Если первые 20–30 секунд заняты названием компании, меню, рекламным блоком и повторяющимися кнопками, проблема находится не в TTS, а в подготовке исходного текста.
Второй тест — переход между разделами. Слушатель должен слышать границу между ними без необходимости смотреть на экран. Для этого достаточно короткой речевой маркировки вроде «Раздел третий. Навигация» и паузы перед первым абзацем.
Третий тест — возвращение к материалу после паузы. Если пользователь остановил воспроизведение и вернулся через несколько минут, интерфейс должен позволять продолжить прослушивание с понятного места. Для длинных документов сохранение позиции проигрывания часто полезнее, чем попытка сделать один гигантский аудиофайл.
Четвёртый тест — списки и таблицы. Нужно убедиться, что слушатель понимает, где начинается список, сколько в нём пунктов и где он заканчивается. Табличные данные нельзя бездумно превращать в последовательность значений: в аудио необходимо сохранить отношения между заголовком столбца и конкретным значением.
Пятый тест — ссылки и примечания. Если в тексте встречается длинный URL, его буквальное чтение может занять десятки секунд и не дать полезной информации. Для доступности лучше озвучивать понятное название ссылки, а сам адрес оставлять доступным в интерфейсе страницы.
Наконец, стоит проверить ситуацию с пустым или слишком коротким текстом. Приложение должно не отправлять заведомо неподходящий материал на генерацию, а показать понятное сообщение пользователю. Это снижает число лишних запусков и помогает контролировать расходы.
6) Сколько стоит озвучить сайт и документы
У операции озвучки текста цена составляет 18 ₽ за 1000 знаков. Это цена одного запуска TTS, а не абонентская плата. Оплата происходит за запуск, без абонплаты и без минимального платежа.
| Операция | Цена | Единица |
|---|---|---|
| Озвучка текста (tts) | 18 ₽ | 1000 знаков |
| Расшифровка записи (stt) | 10 ₽ | запуск |
| Звук из видео (ytaudio) | 0 ₽ | запуск |
| Звук по описанию (sfx) | 9 ₽ | запуск |
| Убрать шум (denoise) | 36 ₽ | запуск |
Для предварительной оценки можно считать количество символов после очистки страницы. Например, если после удаления меню, футера и других служебных блоков осталось 12 000 знаков, базовая оценка TTS составит 12 × 18 ₽ = 216 ₽ при условии, что расчёт соответствует единице тарификации в 1000 знаков. Для 100 000 знаков расчёт по той же ставке составит 1800 ₽.
При выпуске первого ключа на баланс начисляется 50 ₽ для пробы. Сам ключ получается в разделе API после входа и показывается один раз. Остаток можно проверять через GET /balance, а список операций и цен — через GET /services.
Если сайт озвучивает документы регулярно, имеет смысл кэшировать уже созданные результаты. Хэширование очищенного текста позволяет понять, изменился ли раздел после последней генерации. Если хэш тот же, повторный запуск не нужен, а существующую аудиоверсию можно показать пользователю снова.
Для сайта с несколькими тысячами страниц полезно добавить очередь собственных задач. Сначала приложение определяет изменившиеся документы, затем запускает TTS с учётом лимита 60 запросов в минуту на ключ и сохраняет идентификаторы задач. После завершения результаты можно принимать через callback_url вместо постоянного опроса.
В итоге api озвучки текста решает только часть задачи доступности. Качество результата определяется ещё и тем, насколько хорошо сайт отделяет содержание от интерфейса, сохраняет заголовки, объясняет списки и даёт пользователю навигацию. Если просто озвучить весь текстовый DOM, технически аудио появится, но пользоваться им может стать сложнее.
Частые вопросы
Можно ли озвучивать отдельные разделы документа?
Да. Практически это удобно организовать как отдельные TTS-задачи для крупных разделов. Тогда при изменении одного раздела не требуется заново обрабатывать весь документ.
Нужно ли озвучивать меню сайта?
Обычно меню не стоит включать в основной аудиотекст каждой страницы. Его лучше оставить элементом интерфейса и не заставлять пользователя каждый раз слушать повторяющийся набор пунктов.
Как получать результат после запуска?
После запуска операции приложение может проверять состояние по маршруту GET /tasks/{id}. Альтернативно можно передать callback_url, чтобы получить POST-уведомление после готовности задачи.
Есть ли ограничение на количество запросов?
Да. Для одного ключа установлено ограничение не более 60 запросов в минуту. Поэтому при массовой обработке документов следует учитывать частоту запуска задач и запросов статуса.
Можно ли сначала проверить доступные операции и цены?
Да. Для этого предусмотрен маршрут GET /services. Он возвращает список операций и цен, включая TTS, для которого стоимость указана за 1000 знаков.
Где получить ключ для API?
Ключ выдаётся после входа в разделе подключения API и показывается один раз. Для серверного приложения его разумно хранить в переменной окружения и не передавать в браузерный JavaScript.
