LTX-2
LTX-2 is the first DiT-based audio-video foundation model that contains all core capabilities of modern video generation in one model: synchronized audio and video, high fidelity, multiple performance modes, production-ready outputs, API access, and open access.
🚀 Quick Start
Clone the repo
git clone https://github.com/Lightricks/LTX-2.git
cd LTX-2
Install the dependencies. The natten extra is the fastest backend for the diffusion video VAE below, and is Linux + CUDA only -- on Windows and macOS it is skipped automatically and decoding falls back to a Triton or eager implementation, so the same command works everywhere (see neighborhood attention backends)
uv sync --extra natten
Download the models or use the Hugging Face CLI
hf auth login
hf download Lightricks/LTX-2.5 \
diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors \
text_encoders/gemma4-12b-with-proj-ltx-2.5-bf16.safetensors \
vae/ltx-2.5-video-vae-bf16.safetensors \
vae/ltx-2.5-audio-vae-bf16.safetensors \
latent_upscale_models/ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0.safetensors \
--local-dir models/ltx-2.5
That is roughly 66 GiB. The CLI keeps the repository's folder layout under --local-dir, which is why the paths below include diffusion_models/, vae/ and so on.
If you get a 401/403, accept the model terms on Hugging Face and log in with a Read token (fine-grained tokens need the "read gated repos" scope enabled).
Generate
uv run python -m ltx_pipelines.distilled \
--transformer-path models/ltx-2.5/diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors \
--text-encoder-path models/ltx-2.5/text_encoders/gemma4-12b-with-proj-ltx-2.5-bf16.safetensors \
--video-vae-path models/ltx-2.5/vae/ltx-2.5-video-vae-bf16.safetensors \
--audio-vae-path models/ltx-2.5/vae/ltx-2.5-audio-vae-bf16.safetensors \
--spatial-upsampler-path models/ltx-2.5/latent_upscale_models/ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0.safetensors \
--num-frames 121 \
--seed 42 \
--output-path output.mp4 \
--prompt "A medium close-up shot features a Caucasian man with a beard, wearing a green and white baseball cap without any letters on the front, and a light blue shirt over a white t-shirt. He is positioned in the center of the frame, looking intently directly at the camera, his eyes focused on camera. His facial expression is one of deep concentration, with his brow slightly raised. As he looks straight at the camera, a quick sniff sound is heard, and then he speaks with a deep male voice and a satisfied tone, saying, 'I think it's so good.' The camera remains static throughout, maintaining a shallow depth of field, which keeps the man in sharp focus while the background is softly blurred, showing a beige wall behind him. After a brief pause, another short, audible sniff is heard. The man then continues to speak, his voice maintaining the same quality, as he states, 'So good. So good.' He elaborates further, emphasizing his point with a final statement, 'This got to be, it's got to be the best tool I've ever seen.'"
In cases of GPU memory constraints, consider --quantization fp8-cast --offload {cpu, disk}. See additional flags.
This is DistilledPipeline: the fast starting point. For production quality (slower, more VRAM), run DFR below. For other capabilities, see Models and Pipelines.
DFR (production quality)
DFR (Diffusion Fidelity Rendering) is the production-quality text/image-to-video path. It uses the same distilled transformer as the command above, plus a detailing IC-LoRA — extra generated keyframes and a spatial detailing pass. Expect longer runtime and more VRAM, not a different prompting style. Do not pass the full (dev) transformer.
Reuse the text encoder, VAEs, spatial upscaler, and distilled transformer from the first download; add the detailing IC-LoRA (separate repository):
hf download Lightricks/LTX-2.5-22b-IC-LoRA-Pixel-Spatial-Upscaler \
ltx-2.5-22b-ic-lora-pixel-spatial-upscaler-x2-1.0.safetensors \
--local-dir models/ltx-2.5/loras
uv run python -m ltx_pipelines.dfr_pipeline \
--transformer-path models/ltx-2.5/diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors \
--text-encoder-path models/ltx-2.5/text_encoders/gemma4-12b-with-proj-ltx-2.5-bf16.safetensors \
--video-vae-path models/ltx-2.5/vae/ltx-2.5-video-vae-bf16.safetensors \
--audio-vae-path models/ltx-2.5/vae/ltx-2.5-audio-vae-bf16.safetensors \
--detailing-lora models/ltx-2.5/loras/ltx-2.5-22b-ic-lora-pixel-spatial-upscaler-x2-1.0.safetensors \
--spatial-upsampler-path models/ltx-2.5/latent_upscale_models/ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0.safetensors \
--num-frames 121 \
--seed 42 \
--output-path output_dfr.mp4 \
--prompt "A medium close-up shot features a Caucasian man with a beard, wearing a green and white baseball cap without any letters on the front, and a light blue shirt over a white t-shirt. He is positioned in the center of the frame, looking intently directly at the camera, his eyes focused on camera. His facial expression is one of deep concentration, with his brow slightly raised. As he looks straight at the camera, a quick sniff sound is heard, and then he speaks with a deep male voice and a satisfied tone, saying, 'I think it's so good.' The camera remains static throughout, maintaining a shallow depth of field, which keeps the man in sharp focus while the background is softly blurred, showing a beige wall behind him. After a brief pause, another short, audible sniff is heard. The man then continues to speak, his voice maintaining the same quality, as he states, 'So good. So good.' He elaborates further, emphasizing his point with a final statement, 'This got to be, it's got to be the best tool I've ever seen.'"
Defaults are 1024×1536 at 24 fps (--temporal-upscalings 0). UHD 4K is --width 3840 --height 2176 (not 2160). --temporal-upscalings 1 or 2 needs the temporal upscaler. Size, fps, and memory notes: Running DFR.
Full Model List
LTX-2.5 is the recommended model, and what the Quick Start uses. Its weights are published as one file per component, so you download only the parts your pipeline needs.
Download from the LTX-2.5 HuggingFace repository:
Transformer (choose and download one of the following)
Text Encoder - Gemma 4 12B, fine-tuned for LTX, with the text projection bundled in; required by every pipeline. It is bundled with the model, so no separate Gemma download is needed. Google's stock Gemma 4 release is not a substitute: loading checks the encoder's version against the one the checkpoint was trained with (gemma4-12b-ltx-v1)
Video VAE (choose and download one of the following)
Audio VAE - required by the pipelines that generate or decode audio
Spatial Upscaler - required by the two-stage pipeline implementations in this repository
Temporal Upscaler - required by DFRPipeline when running temporal refine rounds (--temporal-upscalings)
Distilled LoRA - required by the two-stage pipeline implementations that run the full model in stage 1 (TI2Vid two-stage / HQ, Keyframe, A2Vid; not DistilledPipeline, DFRPipeline, ICLoraPipeline, or DubItPipeline)
Detailing IC-LoRA - required by DFRPipeline's refinement stage (--detailing-lora). It lives in its own repository, LTX-2.5-22b-IC-LoRA-Pixel-Spatial-Upscaler
Duration Head - optional; lets you omit --num-frames and have the clip length predicted from the prompt
Legacy: LTX-2.3
Every pipeline in this repository also runs on LTX-2.3. Its checkpoints are single files bundling
the transformer, VAEs and text projection, with the Gemma 3 text encoder downloaded separately.
Files are not interchangeable between the two models, and a LoRA only works with the model it was
trained on.
See LTX-2.3 models for the full list.
Available Pipelines
- DistilledPipeline - Fastest text/image-to-video (starting point)
- DFRPipeline - Production-quality text/image-to-video (slower, more VRAM): same distilled transformer, generated keyframes, spatial detailing, optional 2x/4x fps. How to run: DFR in Quick Start and Running DFR
- TI2VidTwoStagesPipeline - Guided two-stage text/image-to-video with CFG/STG and 2x upsampling
- TI2VidTwoStagesHQPipeline - Same guided two-stage flow with the res_2s sampler (fewer steps)
- TI2VidOneStagePipeline - Single-stage generation for quick prototyping
- ICLoraPipeline - Video-to-video and image-to-video transformations (uses distilled model.)
- KeyframeInterpolationPipeline - Interpolate between keyframe images
- A2VidPipelineTwoStage - Audio-to-video generation conditioned on an input audio file
- RetakePipeline - Regenerate a specific time region of an existing video
- HDRICLoraPipeline - Video-to-video with HDR IC-LoRA output (linear float via LogC3 inverse decode, suitable for EXR export and tonemapping)
- DubItPipeline - Dub-It: rephrasing while matching speaker identity and lip movements (distilled model, single IC-LoRA, two stages).
- Native HDR / EXR — standard pipelines accept EXR stills and EXR-frame folders with
--hdr {SRGB_LINEAR,ACESCG,ACESCCT} and write half EXR frames plus a BT.2020/HLG master. See HDR Support.
⚡ Optimization Tips
- Use DistilledPipeline for speed - Fastest inference with only 8 predefined sigmas (8 steps stage 1, 4 steps stage 2). For production quality, use DFR instead.
- Enable FP8 quantization - Enables lower memory footprint:
--quantization fp8-cast (CLI) or quantization=QuantizationPolicy.fp8_cast() (Python). Fp8-cast should be used with bf16 checkpoints, it shall downcast them on the fly. On Hopper+ GPUs with native FP8 support, use --quantization fp8-scaled-mm for FP8 scaled matrix multiplication. Fp8-scaled-mm should be used with fp8 checkpoints.
- Install attention optimizations - On datacenter Blackwell GPUs (B200), install FlashAttention 4 manually:
uv pip install 'flash-attn-4==4.0.0b9' (this specific revision is the one we have verified against torch 2.9.1+cu128; newer betas have known issues on consumer Blackwell). On Hopper GPUs, install the FlashAttention 3 wheel. On other CUDA GPUs, PyTorch SDPA is used automatically. An installed backend is selected automatically at runtime; forcing a specific one is a Python-API option (AttentionFunction.FLASH_ATTENTION_3/FLASH_ATTENTION_4), not a CLI flag.
- Use gradient estimation - Reduce inference steps from 40 to 20-30 while maintaining quality (see pipeline documentation)
- Skip memory cleanup - If you have sufficient VRAM, disable automatic memory cleanup between stages for faster processing
- Choose single-stage pipeline - Use
TI2VidOneStagePipeline for faster generation when high resolution isn't required
✍️ Prompting for LTX-2
When writing prompts, focus on detailed, chronological descriptions of actions and scenes. Include specific movements, appearances, camera angles, and environmental details - all in a single flowing paragraph. Start directly with the action, and keep descriptions literal and precise. Think like a cinematographer describing a shot list. Keep within 200 words. For best results, build your prompts using this structure:
- Start with main action in a single sentence
- Add specific details about movements and gestures
- Describe character/object appearances precisely
- Include background and environment details
- Specify camera angles and movements
- Describe lighting and colors
- Note any changes or sudden events
For additional guidance on writing a prompt please refer to https://ltx.io/blog/prompting-guide-for-ltx-2
Automatic Prompt Enhancement
LTX-2 pipelines support automatic prompt enhancement via an enhance_prompt parameter.
🔌 ComfyUI Integration
To use our model with ComfyUI, please follow the instructions at https://github.com/Lightricks/ComfyUI-LTXVideo/.
📦 Packages
This repository is organized as a monorepo with three main packages:
- ltx-core - Core model implementation, inference stack, and utilities
- ltx-pipelines - High-level pipeline implementations for text-to-video, image-to-video, and other generation modes
- ltx-trainer - Training and fine-tuning tools for LoRA, full fine-tuning, and IC-LoRA
Each package has its own README and documentation. See the Documentation section below.
📚 Documentation
Each package includes compre
这是 Lightricks 官方的 LTX-2 Python 包，LTX-2 是他们的音视频基础模型：一个基于 DiT 的模型，可以从文字或图片生成带同步音频的视频，并提供多种画质/速度模式。