LightX2V is an advanced lightweight video generation inference framework engineered to deliver efficient, high-performance video synthesis solutions. This unified platform integrates multiple state-of-the-art video generation techniques, supporting diverse generation tasks including text-to-video (T2V) and image-to-video (I2V). X2V represents the transformation of different input modalities (X, such as text or images) into video output (V).
- November 21, 2025: 🚀 We support the HunyuanVideo-1.5 video generation model since Day 0. With the same number of GPUs, LightX2V can achieve a speed improvement of over 2 times and supports deployment on GPUs with lower memory (such as the 24GB RTX 4090). It also supports CFG/Ulysses parallelism, efficient offloading, TeaCache/MagCache technologies, and more. It also supports deployment on domestic chips such as Muxi and Cambricon. Quantized models and lightweight VAE models are now available: Hy1.5-Quantized-Models for quantized inference, and LightTAE for HunyuanVideo-1.5 for fast VAE decoding. We will soon update more models on our HuggingFace page, including step distillation, VAE distillation, and other related models. Refer to this for usage tutorials, or check out the examples directory for code examples.
For comprehensive usage instructions, please refer to our documentation: English Docs | 中文文档
pip install -v git+https://github.com/ModelTC/LightX2V.gitgit clone https://github.com/ModelTC/LightX2V.git
cd LightX2V
uv pip install -v . # pip install -v .For attention operators installation, please refer to our documentation: English Docs | 中文文档
# examples/hunyuan_video/hunyuan_t2v.py
from lightx2v import LightX2VPipeline
pipe = LightX2VPipeline(
model_path="/path/to/ckpts/hunyuanvideo-1.5/",
model_cls="hunyuan_video_1.5",
transformer_model_name="720p_t2v",
task="t2v",
)
pipe.create_generator(
attn_mode="sage_attn2",
infer_steps=50,
num_frames=121,
guidance_scale=6.0,
sample_shift=9.0,
aspect_ratio="16:9",
fps=24,
)
seed = 123
prompt = "Two anthropomorphic cats in comfy boxing gear and bright gloves fight intensely on a spotlighted stage."
negative_prompt = ""
save_result_path="/path/to/save_results/output.mp4"
pipe.generate(
seed=seed,
prompt=prompt,
negative_prompt=negative_prompt,
save_result_path=save_result_path,
)💡 More Examples: For more usage examples including quantization, offloading, caching, and other advanced configurations, please refer to the examples directory.
- ✅ Autoencoders 🔔 Follow our HuggingFace page for the latest model releases from our team.
💡 Refer to the Model Structure Documentation to quickly get started with LightX2V
We provide multiple frontend interface deployment options:
- 🎨 Gradio Interface: Clean and user-friendly web interface, perfect for quick experience and prototyping
- 🎯 ComfyUI Interface: Powerful node-based workflow interface, supporting complex video generation tasks
- 🚀 Windows One-Click Deployment: Convenient deployment solution designed for Windows users, featuring automatic environment configuration and intelligent parameter optimization
💡 Recommended Solutions:
- First-time Users: We recommend the Windows one-click deployment solution
- Advanced Users: We recommend the ComfyUI interface for more customization options
- Quick Experience: The Gradio interface provides the most intuitive operation experience
- 🔥 SOTA Inference Speed: Achieve ~20x acceleration via step distillation and system optimization (single GPU)
- ⚡️ Revolutionary 4-Step Distillation: Compress original 40-50 step inference to just 4 steps without CFG requirements
- 🛠️ Advanced Operator Support: Integrated with cutting-edge operators including Sage Attention, Flash Attention, Radial Attention, q8-kernel, sgl-kernel, vllm
- 💡 Breaking Hardware Barriers: Run 14B models for 480P/720P video generation with only 8GB VRAM + 16GB RAM
- 🔧 Intelligent Parameter Offloading: Advanced disk-CPU-GPU three-tier offloading architecture with phase/block-level granular management
- ⚙️ Comprehensive Quantization: Support for
w8a8-int8,w8a8-fp8,w4a4-nvfp4and other quantization strategies
- 📈 Smart Feature Caching: Intelligent caching mechanisms to eliminate redundant computations
- 🔄 Parallel Inference: Multi-GPU parallel processing for enhanced performance
- 📱 Flexible Deployment Options: Support for Gradio, service deployment, ComfyUI and other deployment methods
- 🎛️ Dynamic Resolution Inference: Adaptive resolution adjustment for optimal generation quality
- 🎞️ Video Frame Interpolation: RIFE-based frame interpolation for smooth frame rate enhancement
For detailed performance metrics and comparisons, please refer to our benchmark documentation.
Detailed Service Deployment Guide →
- Model Quantization - Comprehensive guide to quantization strategies
- Feature Caching - Intelligent caching mechanisms
- Attention Mechanisms - State-of-the-art attention operators
- Parameter Offloading - Three-tier storage architecture
- Parallel Inference - Multi-GPU acceleration strategies
- Changing Resolution Inference - U-shaped resolution strategy
- Step Distillation - 4-step inference technology
- Video Frame Interpolation - Base on the RIFE technology
- Low-Resource Deployment - Optimized 8GB VRAM solutions
- Low-Latency Deployment - Ultra-fast inference optimization
- Gradio Deployment - Web interface setup
- Service Deployment - Production API service deployment
- Lora Model Deployment - Flexible Lora deployment
We maintain code quality through automated pre-commit hooks to ensure consistent formatting across the project.
Tip
Setup Instructions:
- Install required dependencies:
pip install ruff pre-commit- Run before committing:
pre-commit run --all-filesWe appreciate your contributions to making LightX2V better!
We extend our gratitude to all the model repositories and research communities that inspired and contributed to the development of LightX2V. This framework builds upon the collective efforts of the open-source community.
If you find LightX2V useful in your research, please consider citing our work:
@misc{lightx2v,
author = {LightX2V Contributors},
title = {LightX2V: Light Video Generation Inference Framework},
year = {2025},
publisher = {GitHub},
journal = {GitHub repository},
howpublished = {\url{https://github.com/ModelTC/lightx2v}},
}For questions, suggestions, or support, please feel free to reach out through:
- 🐛 GitHub Issues - Bug reports and feature requests
- 💬 GitHub Discussions - Community discussions and Q&A