LTX-Video-FastAPI (Docker Deployment)

🚀High-Performance Multi-GPU / Multi-Process LTX-Video Image-to-Video & Text-to-Video Inference FastAPI Service

Core Repo: Lightricks/LTX-Video

🆕 Features

• Image-to-Video: Upload an image + text prompt to generate video
• Text-to-Video: Use only text prompt to generate video (NEW!)
• Multi-GPU Support: Automatic GPU allocation and load balancing
• High Concurrency: Async processing with queue management
• Docker Ready: Production-ready containerized deployment

git submodule add https://github.com/Lightricks/LTX-Video.git  
python inference.py --prompt "PROMPT" --conditioning_media_paths IMAGE_PATH --conditioning_start_frames 0 --height HEIGHT --width WIDTH --num_frames NUM_FRAMES --seed SEED --pipeline_config configs/ltxv-13b-0.9.8-distilled.yaml

Prerequisites

Before you begin, ensure you have the following installed on your host machine:

• Docker & Docker Compose
• NVIDIA Drivers (CUDA 12.4+)
• NVIDIA Container Toolkit (Crucial for GPU access in Docker)

  # Verify GPU visibility in Docker
  docker run --rm -it --gpus all nvidia/cuda:12.4.1-cudnn-runtime-ubuntu22.04
  nvidia-smi

Download Pretrained Models

hf download Lightricks/LTX-Video

Installation

git clone https://github.com/fjyu95/LTX-Video-FastAPI.git  
cd LTX-Video-FastAPI  
git checkout deploy/docker 

Configuration

Create the environment configuration file.

cp .env-template .env  
vim .env  
# 密钥生成
echo "SERVER_API_KEY=$(head -c 32 /dev/urandom | base64 | tr -d '/+=')" >> .env

🐳 Build docker image

sudo chown -R 1000:1000 generated_videos/  
chmod -R 777 /data/huggingface/

docker pull nvidia/cuda:12.4.1-cudnn-runtime-ubuntu22.04  
docker-compose build  # 更新代码/dockerfile后重新build，速度非常快

Run Service in detached mode

docker-compose up -d
docker-compose up -d --build (Build & Run)

Test & Update Service

docker container prune -f   
docker-compose -f docker-compose.test.yml down  
docker-compose -f docker-compose.test.yml build  
docker-compose -f docker-compose.test.yml up
docker-compose -f docker-compose.test.yml up -d --build
# p.s. 只更新了.env不用重新build

📊 Check Service Status

docker-compose ps  
docker-compose logs -f --tail=100  

🧪 API Usage Examples

Health Check

curl http://localhost:8001/health  

Image-to-Video (Original)

curl -X 'POST' \
  'http://116.169.116.28:40001/generate' \
  -H 'accept: application/json' \
  -H 'X-API-Key: SERVER_API_KEY' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@i2v_input.JPG;type=image/jpeg' \
  -F 'prompt=Summer beach vacation style, a white cat wearing sunglasses sits on a surfboard' \
  -F 'negative_prompt=worst quality, inconsistent motion, blurry, jittery, distorted' \
  -F 'width=1280' \
  -F 'height=720' \
  -F 'seed=42'

Text-to-Video (NEW!)

curl -X 'POST' \
  'http://localhost:8001/generate' \
  -H 'accept: application/json' \
  -H 'X-API-Key: SERVER_API_KEY' \
  -H 'Content-Type: multipart/form-data' \
  -F 'prompt=A majestic eagle soaring through mountain peaks at sunset' \
  -F 'negative_prompt=worst quality, inconsistent motion, blurry, jittery, distorted' \
  -F 'width=1280' \
  -F 'height=720' \
  -F 'seed=42'

Note: When no image file is provided, the service automatically uses Text-to-Video mode with a default prompt if none is specified.

📈 Performance & Benchmarks

Supported Resolutions

• 720p (1280×720): Recommended for production use
• 1080p (1920×1080): Higher quality, longer processing time
• Custom: Up to 2048×2048, subject to GPU memory limits

Concurrency Guidelines

• Single GPU: 1-2 concurrent requests for stability
• Short Bursts: Up to 4-6 concurrent requests (5-second window)
• Queue Timeout: 600 seconds (configurable via TIMEOUT env var)

🔧 Configuration Options

Key environment variables in .env:

PORT=8001                    # Service port
SERVER_API_KEY=your-key      # API authentication
CUDA_VISIBLE_DEVICES=0,1     # GPU selection
MANUAL_WORKERS=2             # Worker process count
TIMEOUT=300                  # Request timeout (seconds)