РУКОВОДСТВО

Свой API для озвучки текста в Docker

API синтеза речи на собственном сервере превращает текст в аудио для любой программы, которая умеет отправлять HTTP-запрос: сайта, бота, игрового бэкенда или скрипта на любом языке. Текст не покидает вашу машину, а платить за символы не нужно.

В этом руководстве показано, как запустить движок SuperClonica на основе открытой модели Supertonic 3 как HTTP-сервер в Docker: старт на процессоре или видеокарте NVIDIA, запросы со встроенными и своими голосами и подготовка к реальной работе. Образ и движок наши, поэтому мы прямо говорим, где речь о нашем продукте.

Голоса для вашего API Другие способы установки движка

Зачем запускать синтез речи у себя

С облачными API озвучки легко начать, но каждый запрос отправляет текст провайдеру и оплачивается посимвольно. Свой API меняет это на сервер, которым вы управляете сами.

  • Приватность: тексты и аудио остаются на вашем железе — это важно для внутренних документов, сообщений и данных пользователей.
  • Стоимость: после покупки железа речь бесплатна, длинные тексты и большие объёмы не увеличивают счёт.
  • Любой клиент: один HTTP-эндпоинт одинаково обслуживает Python, JavaScript, Go, PHP, C# или shell-скрипт.
  • Офлайн: после загрузки модели серверу не нужен интернет.

Запуск сервера

На любом процессоре: docker run -d --name tts -p 8000:8000 -v superclonica-models:/models superclonica/superclonica:cpu. На видеокарте NVIDIA установите NVIDIA Container Toolkit и запустите docker run -d --name tts --gpus all -p 8000:8000 -v superclonica-models:/models superclonica/superclonica:cuda; CUDA и cuDNN уже в образе, от хоста нужен только драйвер.

При первом запуске модель Supertonic 3 (около 385 МБ) скачивается в том superclonica-models, следующие запуски используют её повторно. Сервер готов, когда GET http://localhost:8000/health отвечает статусом, версией и используемым устройством. В образе есть собственная проверка здоровья, поэтому docker ps показывает, когда контейнер готов.

Отправка запроса

POST /synthesize принимает JSON и возвращает моно-WAV 16 бит: curl -X POST http://localhost:8000/synthesize -H "Content-Type: application/json" -d '{"text": "Привет с моего сервера!", "voice": "F1", "lang": "ru"}' -o hello.wav. Заголовки X-Sample-Rate и X-Duration-Seconds описывают аудио.

Поля запроса: text, voice, lang, seed и normalize. voice — один из десяти встроенных голосов, от M1 до M5 и от F1 до F5, или свой голос; lang — язык текста, один из 31 языка модели (китайского среди них нет). Фиксированный seed даёт то же аудио для того же текста, а normalize выравнивает громкость. GET /voices перечисляет встроенные голоса и языки, а /docs показывает интерактивную документацию API.

Свои голоса

Голос Supertonic 3 — это JSON-файл размером около 0,3 МБ. Бесплатные голоса с примерами звучания лежат в репозитории superclonica/supertonic-voices на GitHub, а в каталоге SuperClonica их больше 170, у каждого есть бесплатное онлайн-демо.

Голос передаётся в запросе самим JSON-объектом в поле voice, поэтому сервер не хранит файлы голосов. Объект большой, так что собирайте запрос в файле и отправляйте через curl -d @request.json или из кода: загрузите голос через json.load в Python или JSON.parse в JavaScript и отправьте вместе с текстом. Тело запроса может весить до 2 МБ.

Настройки

Сервер берёт настройки из переменных окружения — через -e в docker run или в файле Compose.

  • SUPERCLONICA_API_KEY: если задан, /synthesize и /voices требуют заголовок Authorization: Bearer и ключ.
  • SUPERCLONICA_LANES: копии модели, от 1 до 8 (по умолчанию 1); каждая озвучивает один запрос за раз и требует своей памяти.
  • SUPERCLONICA_DEVICE: auto, cuda или cpu (по умолчанию auto — видеокарта, если она есть).
  • SUPERCLONICA_THREADS: потоки процессора (по умолчанию по одному на физическое ядро).
  • SUPERCLONICA_MAX_TEXT: самый длинный текст в символах (по умолчанию 5000).

Перед запуском в продакшен

Несколько привычек делают свой API озвучки быстрым и безопасным.

  • Сохраняйте том /models, чтобы после перезапуска модель не скачивалась заново, и запускайте контейнер с --restart unless-stopped.
  • Не открывайте порт 8000 в интернет как есть: задайте API-ключ и поставьте сервер за обратный прокси с HTTPS или держите его в частной сети.
  • Делите длинные тексты на абзацы на своей стороне, если нужен прогресс или потоковая выдача; движок и так озвучивает длинный текст естественными кусками до 160 символов.
  • Кэшируйте аудио для повторяющихся текстов, например фраз интерфейса: тот же текст, голос и seed всегда дают тот же файл.
  • Измеряйте на своём железе: в наших тестах короткая фраза заняла 0,12 с на RTX 5070 Ti и 0,43 с на четырёх потоках Ryzen 7 5800X.

Лицензии

Движок SuperClonica и образ выпущены под Apache License 2.0. Модель Supertonic 3 распространяется под OpenRAIL-M — бесплатной лицензией со списком запрещённых применений вместо запрета на коммерческое использование: не используйте речь, чтобы выдавать себя за другого человека без согласия, обманывать или травить, и указывайте, что аудио сгенерировано, там, где это важно.