README.md

---
base_model:
- tencent/HunyuanVideo-1.5
library_name: diffusers
license: apache-2.0
pipeline_tag: text-to-video
tags:
- diffusion-single-file
- comfyui
- distillation
- video
- video-generation
---

# 🎬 Hy1.5-Distill-Models

<img src="https://raw.githubusercontent.com/ModelTC/LightX2V/main/assets/img_lightx2v.png" width="75%" />

---

🤗 [HuggingFace](https://huggingface.co/lightx2v/Hy1.5-Distill-Models) | [GitHub](https://github.com/ModelTC/LightX2V) | [Paper](https://huggingface.co/papers/2605.30116) | [License](https://opensource.org/licenses/Apache-2.0)

---

This repository contains 4-step distilled models for HunyuanVideo-1.5, developed using the technique described in the paper **[SGMD: Score Gradient Matching Distillation for Few-Step Video Diffusion Distillation](https://huggingface.co/papers/2605.30116)**. 

These models are optimized for use with the [LightX2V](https://github.com/ModelTC/LightX2V) framework, enabling **ultra-fast 4-step inference** without Classifier-Free Guidance (CFG), significantly reducing generation time while maintaining high-quality video output.

## 📋 Model List

### 4-Step Distilled Models

* **`hy1.5_t2v_480p_lightx2v_4step.safetensors`** - 480p Text-to-Video 4-step distilled model (16.7 GB)
* **`hy1.5_t2v_480p_scaled_fp8_e4m3_lightx2v_4step.safetensors`** - 480p Text-to-Video 4-step distilled model with FP8 quantization (8.85 GB)

## 🚀 Quick Start

### Installation

First, install LightX2V:

```bash
pip install -v git+https://github.com/ModelTC/LightX2V.git
```

### Download Models

Download the distilled models from this repository:

```bash
# Using git-lfs
git lfs install
git clone https://huggingface.co/lightx2v/Hy1.5-Distill-Models

# Or download individual files using huggingface-hub
pip install huggingface-hub
python -c "from huggingface_hub import hf_hub_download; hf_hub_download(repo_id='lightx2v/Hy1.5-Distill-Models', filename='hy1.5_t2v_480p_lightx2v_4step.safetensors', local_dir='./models')"
```

## 💻 Usage in LightX2V

### 4-Step Distilled Model (Base Version)

```python
from lightx2v import LightX2VPipeline

# Initialize pipeline for HunyuanVideo-1.5
pipe = LightX2VPipeline(
    model_path="/path/to/hunyuanvideo-1.5/",  # Original model path
    model_cls="hunyuan_video_1.5",
    transformer_model_name="480p_t2v",
    task="t2v",
    # 4-step distilled model ckpt
    dit_original_ckpt="/path/to/hy1.5_t2v_480p_lightx2v_4step.safetensors"
)

# Enable offloading to significantly reduce VRAM usage
pipe.enable_offload(
    cpu_offload=True,
    offload_granularity="block",
    text_encoder_offload=True,
    image_encoder_offload=False,
    vae_offload=False,
)

# Create generator with specified parameters
# Note: 4-step distillation requires infer_steps=4, guidance_scale=1, and denoising_step_list
pipe.create_generator(
    attn_mode="sage_attn2",
    infer_steps=4,  # 4-step inference
    num_frames=81,
    guidance_scale=1,  # No CFG needed for distilled models
    sample_shift=9.0,
    aspect_ratio="16:9",
    fps=16,
    denoising_step_list=[1000, 750, 500, 250]  # Required for 4-step distillation
)

# Generate video
pipe.generate(
    seed=123,
    prompt="A close-up shot captures a scene on a polished, light-colored granite kitchen counter, illuminated by soft natural light from an unseen window. The scene is in a realistic style.",
    negative_prompt="",
    save_result_path="output.mp4",
)
```

## ⚙️ Key Features

* **🚀 Ultra-Fast Inference**: SGMD technology compresses the original inference process into just **4 steps**, providing a ~25x speedup compared to standard 50-step inference.
* **💡 No CFG Required**: Distilled models are trained to work without Classifier-Free Guidance (`guidance_scale=1`), eliminating the overhead of dual-forward passes.
* **💾 Memory Efficiency**: Available in **FP8 quantized** versions for up to 50% memory reduction on consumer GPUs.

## 🔗 Related Resources

* [LightX2V GitHub Repository](https://github.com/ModelTC/LightX2V)
* [SGMD Paper](https://huggingface.co/papers/2605.30116)
* [Step Distillation Documentation](https://lightx2v-en.readthedocs.io/en/latest/method_tutorials/step_distill.html)

## 🤝 Citation

If you use these distilled models or the SGMD method in your research, please cite:

```bibtex
@article{sgmd2026,
  title={SGMD: Score Gradient Matching Distillation for Few-Step Video Diffusion Distillation},
  author={LightX2V Contributors},
  journal={arXiv preprint arXiv:2605.30116},
  year={2026}
}

@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}},
}
```

## 📄 License

This model is released under the Apache 2.0 License, consistent with the original HunyuanVideo-1.5 model.