Voice Video Generator

Локальная платформа для генерации видео с говорящим лицом.

Требования

• Python 3.8+
• Внешние веса модели SadTalker (скачать отдельно)

Установите зависимости:

pip install -r requirements.txt

Запуск

python app.py

По умолчанию ожидается, что скрипт SadTalker находится в каталоге SadTalker в корне проекта. При необходимости измените переменную окружения SADTALKER_ROOT.

Voice Video Generator Backend

Приложение объединяет генерацию речи и анимацию лица. Для обработки запросов используется FastAPI, а задачи выполняются асинхронно через Celery c брокером Redis. Дополнительно включена конвертация голоса через so-vits-svc и постобработка видео при помощи Wav2Lip для более точной синхронизации губ.

Установка

pip install -r requirements.txt

Эта команда установит все необходимые модули, включая зависимости проектов SadTalker и TTS.

Не забудьте установить и запустить Redis локально или указать адрес работающего сервера. Адрес брокера Celery задаётся переменными окружения CELERY_BROKER_URL и CELERY_BACKEND_URL.

Для загрузки результатов в S3 установите переменную S3_BUCKET и настройте политику жизненного цикла бакета на удаление файлов через 1 день.

Для работы so-vits-svc и Wav2Lip потребуются дополнительные переменные окружения:

• SOVITS_MODEL и SOVITS_CONFIG – пути к файлам модели и конфигурации.
• SOVITS_SPK – имя целевого спикера.
• WAV2LIP_CHECKPOINT – путь к чекпойнту модели Wav2Lip.

Для защиты эндпоинтов можно задать переменную API_SECRET_KEY. Клиент должен передавать это значение в заголовке X-API-Key.

После клонирования репозитория скопируйте файл .env.example в .env и заполните реальные значения переменных.

Запуск API и Celery

Запустите воркер Celery:

celery -A backend.tasks worker --loglevel=info

Запустите сервер FastAPI:

uvicorn backend.api:app --reload

После запуска сервера откройте http://localhost:8000/docs, чтобы увидеть интерактивную документацию Swagger.

Эндпоинты API

Доступные маршруты описаны в Swagger UI по адресу /docs.

POST /generate

• Параметры запроса
  • image – файл изображения лица
  • text – текст для озвучивания
  • language – код языка (ru, en, es, de, fr)
  • speaker_audio – пример голоса (необязательно)
  • заголовок X-API-Key, если задан API_SECRET_KEY
• Ответ: {"task_id": "UUID"}

GET /result/{task_id}

• Параметры запроса
  • task_id – идентификатор задачи
  • заголовок X-API-Key, если задан API_SECRET_KEY
• Ответ:
  • при завершении задачи – {"status": "completed", "video_path": "<url>"}
  • иначе – {"status": "<state>"}

Использование

Отправьте POST запрос на /generate с форм-данными:

• image – изображение лица
• text – текст для озвучивания
• language – код языка (ru, en, es, de, fr)
• speaker_audio – опциональный пример голоса

Если задан API_SECRET_KEY, передавайте его в заголовке X-API-Key для обоих запросов.

В ответе будет task_id. Статус и путь до готового видео можно получить по /result/{task_id}.

Запуск через Docker

В репозитории есть Dockerfile и docker-compose.yml. Для запуска достаточно CPU – специальные CUDA-образы не используются, однако при наличии GPU генерация пройдёт быстрее. Контейнеры не создают постоянных томов, поэтому все результаты хранятся внутри и удаляются после остановки.

Для первой сборки потребуется интернет: скрипты SadTalker автоматически скачают модели. Этот шаг занимает несколько минут (обычно 5–10).

Запустите сервисы, при необходимости указав переменные окружения:

API_SECRET_KEY=<ключ> \
S3_ACCESS_KEY_ID=<id> \
S3_SECRET_ACCESS_KEY=<секрет> \
S3_REGION=<регион> \
S3_ENDPOINT=<endpoint> \
S3_BUCKET=<имя_бакета> \
S3_URL_BUCKET=<публичный_url> \
docker compose up --build

По умолчанию будут подняты контейнеры FastAPI, Celery и Redis. Для хранения загруженных весов в каталоге models и результатов в assets используются тома, проброшенные в контейнеры api и worker. Для защиты запросов можно передать переменную API_SECRET_KEY, а для загрузки файлов в облако – S3_BUCKET.

• API_SECRET_KEY — защищает эндпоинты FastAPI. Клиент должен передавать значение в заголовке X-API-Key.
• S3_ACCESS_KEY_ID и S3_SECRET_ACCESS_KEY — учетные данные для доступа к S3.
• S3_REGION — регион S3.
• S3_ENDPOINT — URL эндпоинта S3 (например, https://storage.yandexcloud.kz).
• S3_BUCKET — имя бакета S3 для загрузки готовых видео. Если переменная не задана, файлы останутся в контейнере.
• S3_URL_BUCKET — базовый публичный URL бакета для формирования ссылок на загруженные файлы.

По умолчанию будут подняты контейнеры FastAPI, Celery и Redis. Дополнительно запускаются отдельные сервисы tts-service, vc-service, sadtalker-service и wav2lip-service, которые выполняют соответствующие этапы генерации.

Запуск тестов

Для запуска тестов после установки зависимостей выполните:

pytest

Лицензия

Проект распространяется под лицензией MIT. Смотрите файл LICENSE.