HunyuanVideo-1.5

HunyuanVideo-1.5 is a lightweight video generation model open-sourced by the Tencent Hunyuan team, focused on achieving high-quality video generation with only 8.3B parameters, capable of running on consumer-grade GPUs, and aimed at lowering the barrier to using video generation.

I. Main Uses This model is a unified video generation framework that supports text-to-video (T2V) and image-to-video (I2V), covering multiple durations and resolutions. It is aimed at developers and creators, providing the code and tools needed to implement video generation.

II. Core Capabilities

1. Lightweight high-performance architecture: It uses an 8.3B-parameter Diffusion Transformer (DiT) combined with a 3D causal VAE, with a spatial compression ratio of 16x and a temporal compression ratio of 4x. The innovative SSTA (Selective and Sliding Tile Attention) mechanism can prune redundant spatiotemporal kv blocks, reducing the computational overhead of long video sequences. It is claimed that 10-second 720p video synthesis achieves about 1.87x end-to-end speedup compared with FlashAttention-3.
2. Video super-resolution enhancement: Through an efficient few-step super-resolution network, the output is upscaled to 1080p, enhancing clarity and correcting distortion.
3. End-to-end training optimization: It adopts a multi-stage progressive training strategy, combined with the Muon optimizer to accelerate convergence, overall improving motion coherence, aesthetic quality, and human preference alignment.
4. Text understanding: It enhances bilingual understanding capability through glyph-aware text encoding.

III. Version Update Highlights

• December 23, 2025: Support for fp8 gemm inference.
• December 5, 2025: Released the 480p I2V step distillation model, supporting 8 or 12 step generation (recommended), reducing end-to-end generation time on RTX 4090 by 75%, and generating video within 75 seconds on a single card; the distilled model quality is comparable to the original model. To enable it, add the --enable_step_distill parameter in generate.py; you can also try 4 steps (faster but with slightly reduced quality). On the same day, the training code (train.py) and LoRA fine-tuning scripts were open-sourced. The training pipeline supports distributed training, FSDP, context parallelism, gradient checkpointing, etc., and uses the Muon optimizer.
• Diffusers support: It is now available on Hugging Face Diffusers.
• November 27, 2025 Day: Support for cached inference (deepcache, teacache, taylorcache).
• November 24, 2025: Support for deepcache inference.
• November 20, 2025: Released inference code and model weights.

IV. Usage

1. Hardware requirements: NVIDIA GPU with CUDA support; minimum VRAM of 14 GB when model offloading is enabled; when VRAM is sufficient, offloading can be disabled to improve speed.
2. Software requirements: Linux system, Python 3.10 or higher, and the CUDA version must match the PyTorch installation.
3. Installation steps: Clone the repository and install the basic dependencies; optionally install Flash Attention to accelerate inference and reduce VRAM usage; sparse attention requires installing flex-block-attn (git clone https://github.com/Tencent-Hunyuan/flex-block-attn.git，cd flex-block-attn, git submodule update --init --recursive, python3 setup.py install); enabling SageAttention requires cloning https://github.com/cooper1637/SageAttention.git and install it. Note that enabling SageAttention will automatically disable Flex-Block-Attention; to enable fp8 gemm, you need pip install sgl-kernel==0.3.18.
4. Download the pretrained model: see checkpoints-download.md for details.
5. Inference: run generate.py. You can use IMAGE_PATH=none for text-to-video or provide an image path for image-to-video; you can use --nproc_per_node to specify the number of GPUs (e.g., --nproc_per_node=8 uses 8 GPUs).
6. Prompt enhancement: enabled by default (--rewrite defaults to true). You can set --rewrite false or --rewrite 0 to disable it. It is recommended to use Gemini or a model deployed via vLLM. The codebase currently only supports models compatible with the vLLM API. For T2V, Qwen3-235B-A22B-Thinking-2507 is recommended; configure T2V_REWRITE_BASE_URL and T2V_REWRITE_MODEL_NAME. For I2V, Qwen3-VL-235B-A22B-Instruct is recommended; configure I2V_REWRITE_BASE_URL and I2V_REWRITE_MODEL_NAME. When no vLLM endpoint is configured, the pipeline does not perform remote rewriting.
7. Diffusers usage: It can be easily invoked through the Diffusers library. It is recommended to install kernels (pip install kernels) to obtain prebuilt attention kernels.
8. Training and fine-tuning: train.py provides a complete training pipeline. You need to replace create_dummy_dataloader() with your own implementation. The dataset's getitem method should return a single sample; required fields include "pixel_values" (torch.Tensor, [C, F, H, W] for video or [C, H, W] for images, with pixel values in the range [-1, 1], and the video temporal dimension F must be 4n+1, such as 1, 5, 9, 13, 17, etc.), "text" (string, text prompt), "data_type" (string).

V. Applicable scenarios and limitations Applicable scenarios: Developers and creators performing video generation, research, secondary development, and fine-tuning on consumer-grade GPUs, including text-to-video, image-to-video, and use through community integrations such as ComfyUI, Diffusers, and LightX2V. Limitations: A Linux system and an NVIDIA CUDA GPU are required; the minimum VRAM is 14 GB (with offloading enabled). The distilled model and sparse attention model were still in a "coming soon" status at the time the documentation was published, so keep an eye on Hugging Face Model Card updates. The cfg distilled model must use 50 steps to generate correct results. Some community integrations are maintained by the community, and their quality and compatibility are not described in the materials. Pricing and fee information is not currently provided.