Интеграция API синтеза речи: полное руководство для разработчиков

Коротко: TTS API DubVoice.ai работает по REST, авторизация по ключу sk_, есть вебхуки. POST с текстом и voice_id на /api/v1/tts, затем GET /api/v1/tts/{task_id} за audio_url и srt_url. Стартовые кредиты входят в каждый аккаунт.

Нужно добавить синтез речи в своё приложение? Это руководство закрывает всё, что нужно для интеграции TTS API DubVoice.ai — от авторизации до практик для продакшена.

Зачем брать готовый API

Собрать синтез речи с нуля — это огромные датасеты, дорогая GPU-инфраструктура и глубокая ML-экспертиза. Готовый API даёт:

• Голоса, готовые к продакшену — 17 800+ естественных голосов из коробки
• Много языков — 50+ языков через один интерфейс
• Масштаб — тысячи запросов без забот об инфраструктуре
• Постоянное улучшение — качество голосов растёт без вашего участия

Быстрый старт

Авторизация

Каждый запрос требует API-ключ. Получите его в панели DubVoice.ai: Настройки → API-ключи.

Базовый запрос

curl -X POST https://dubvoice.ai/api/v1/tts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, welcome to our application!",
    "voice_id": "voice_rachel",
    "language": "en"
  }'

Ответ

API возвращает аудиофайл (по умолчанию MP3) вместе с метаданными: числом символов и временем обработки.

Схемы интеграции

Схема 1. Генерация по запросу

Аудио создаётся в момент запроса пользователя. Подходит для интерактивных приложений, чат-ботов и функций доступности.

Схема 2. Предварительная генерация

Аудио создаётся и кэшируется заранее для известного контента. Подходит для платформ обучения, голосовых меню и статики.

Схема 3. Потоковая передача

Для приложений реального времени, где важна задержка. Аудио отдаётся кусками по мере генерации.

Практики

• Кэшируйте агрессивно — если один и тот же текст запрашивают повторно, отдавайте из кэша
• Обрабатывайте лимиты — экспоненциальная задержка на ответ 429
• Проверяйте вход — длину и содержимое текста перед отправкой
• Следите за расходом — считайте символы, чтобы не удивляться счёту
• Используйте вебхуки — для длинных текстов берите асинхронную генерацию с колбэком

Обработка ошибок

Всегда закрывайте ошибки явно:

• 400 — некорректный запрос (проверьте длину текста, voice_id, язык)
• 401 — неверный или истёкший API-ключ
• 429 — превышен лимит запросов (нужна задержка)
• 500 — ошибка сервера (повтор с экспоненциальной задержкой)

Стоимость через API

Запросы через API списывают кредиты с того же баланса и по той же цене, что и веб-интерфейс. Один кредит равен одному символу. Пакеты — от 250 тыс. кредитов ($4,99) до 40 млн ($110).

Типичные сценарии

• Мобильные приложения — озвучка в читалках, новостях, навигации
• Веб-приложения — доступность, аудиоконтент, уведомления
• Устройства — объявления в умном доме, встроенные голосовые ответы
• Игры — реплики персонажей, голос рассказчика, динамические истории
• SaaS-платформы — аудиоверсии отчётов, дашбордов и оповещений

Синхронно или асинхронно — решите до того, как писать код

Это решение задаёт форму всей интеграции, и его легко принять неправильно, просто пойдя по умолчанию.

Короткий текст возвращается достаточно быстро, чтобы ждать его прямо в запросе. Приветствие, уведомление, название товара — секунда-другая, и блокирующий вызов проще альтернативы. Длинный текст — нет. Статья на 15 000 символов может занять минуты, а серверлес-функция, которая её ждёт, будет убита платформой задолго до готовности аудио.

Сценарий отказа стоит назвать прямо: ваша функция отваливается по таймауту, пользователь видит ошибку, а задача на сервере при этом успешно завершается. Кредиты списаны, результат потерян.

Поэтому выше нескольких тысяч символов — отправляйте и опрашивайте. Сразу заберите идентификатор задачи, верните его в браузер и дайте браузеру опрашивать тонкий статусный маршрут. Запрос на отправку остаётся меньше секунды, сколько бы ни длился рендер.

Как обрабатывать сбои, не платя дважды

Два правила закрывают большую часть проблем.

Считайте лимит запросов ожиданием, а не ошибкой. Ответ 429 несёт заголовок Retry-After, который говорит, сколько ждать. Уважайте его, а не повторяйте немедленно: повтор в лимит только продлевает лимит. Отступайте экспоненциально с небольшим разбросом, чтобы параллельные воркеры не повторяли синхронно.

Сделайте повторы идемпотентными. Если ваш раннер упал после отправки, но до записи идентификатора задачи, наивное решение — отправить заново, и вот вы заплатили дважды за одно аудио. Пишите идентификатор в базу раньше всего остального и проверяйте его наличие перед отправкой.

Что хранить и как долго

Храните идентификатор задачи, хеш текста, идентификатор голоса и итоговый URL аудио. Хеш текста позволяет вообще пропустить рендер, когда тот же сценарий приходит снова, — а это случается часто: одно и то же описание товара запрашивают многократно.

Не считайте URL поставщика постоянным хранилищем. Скачайте файл и положите туда, что контролируете вы, по своему расписанию. URL, который выдали не вы, может истечь, и узнаете вы об этом из тикета про неработающий плеер.

Обзор того, что ещё доступно по тому же ключу, — в материале [всё, что умеет платформа](/blog/everything-you-can-do-with-dubvoice-ai).

С чего начать

• Зарегистрируйтесь на dubvoice.ai и получите API-ключ
• Проверьте простым запросом через cURL
• Встройте в приложение на своём языке программирования
• Протестируйте разные голоса и языки
• Выкатывайте и следите за расходом

Полный справочник эндпоинтов, каталог голосов и коды языков — в документации на dubvoice.ai/api-docs.