README.md
26.4 KB · 414 lines · markdown Raw
1 ---
2 language:
3 - en
4 - de
5 - es
6 - fr
7 - ja
8 - ko
9 - zh
10 - it
11 - pt
12 license: other
13 license_name: ltx-2-community-license-agreement
14 license_link: https://github.com/Lightricks/LTX-2/blob/main/LICENSE.md
15 pipeline_tag: image-to-video
16 arxiv: 2601.03233
17 tags:
18 - image-to-video
19 - text-to-video
20 - video-to-video
21 - image-text-to-video
22 - audio-to-video
23 - text-to-audio
24 - video-to-audio
25 - audio-to-audio
26 - text-to-audio-video
27 - image-to-audio-video
28 - image-text-to-audio-video
29 - ltx-video
30 - lightricks
31 - comfyui
32 - ltx-2.5
33 - diffusion-single-file
34 pinned: true
35 demo: https://app.ltx.studio/ltx-2-playground/i2v
36 extra_gated_description: >-
37 By clicking "Agree and Access" you acknowledge the [Privacy
38 Policy](https://static.lightricks.com/legal/Privacy%20Policy%20-%20LTX%20Platform.pdf)
39 and consent to receive offers and updates including targeted and personalized
40 advertisements. You can unsubscribe at any time.
41 extra_gated_button_content: Agree and Access
42 ---
43
44 <!-- LTX-2.5 model card — license-first redesign. YAML frontmatter above kept intact. -->
45
46 <div class="lg:-mr-20 xl:-mr-24 2xl:-mr-36" style="border-radius:14px;overflow:hidden;">
47 <div style="position:relative;line-height:0;font-size:0;height:300px;">
48 <img src="https://huggingface.co/Lightricks/LTX-2.5/resolve/main/hf-hero-web.webp" alt="LTX-2.5 — Video, Audio &amp; World Simulation" style="display:block;width:100%;height:100%;object-fit:cover;margin:0;vertical-align:top;" />
49 <video autoplay muted loop playsinline style="position:absolute;inset:0;width:100%;height:100%;object-fit:cover;">
50 <source src="https://videos.ltx.io/LTX-2/ltx-research/hf-hero-web.mp4" type="video/mp4" />
51 <source src="https://videos.ltx.io/LTX-2/ltx-research/hf-hero-web.webm" type="video/webm" />
52 </video>
53 </div>
54 <!-- light hero footer -->
55 <div class="dark:hidden" style="background-color:#eef1f5;padding:2rem 1.5rem 2.4rem;text-align:center;isolation:isolate;">
56 <h1 style="color:#0a0a0a;margin:0 0 0.5rem;font-size:2rem;font-weight:700;letter-spacing:-0.01em;border:none;padding:0;">LTX-2.5 — Video, Audio &amp; World Simulation</h1>
57 <p style="color:#555;margin:0 0 1.25rem;font-size:1.05rem;">Full control and customization — self-host on your infrastructure.</p>
58 <div style="display:flex;flex-wrap:wrap;justify-content:center;gap:0.5rem;">
59 <a href="https://ltx.io" class="bg-white hover:bg-gray-200 transition-colors duration-150" style="color:#1c1c1c;border:1px solid #d0d3d8;border-radius:8px;padding:0.5rem 1.1rem;font-size:0.85rem;font-weight:600;text-decoration:none;">Homepage</a>
60 <a href="https://docs.ltx.io" class="bg-white hover:bg-gray-200 transition-colors duration-150" style="color:#1c1c1c;border:1px solid #d0d3d8;border-radius:8px;padding:0.5rem 1.1rem;font-size:0.85rem;font-weight:600;text-decoration:none;">Docs</a>
61 <a href="https://github.com/Lightricks/LTX-2" class="bg-white hover:bg-gray-200 transition-colors duration-150" style="color:#1c1c1c;border:1px solid #d0d3d8;border-radius:8px;padding:0.5rem 1.1rem;font-size:0.85rem;font-weight:600;text-decoration:none;">GitHub</a>
62 <a href="https://huggingface.co/papers/2601.03233" class="bg-white hover:bg-gray-200 transition-colors duration-150" style="color:#1c1c1c;border:1px solid #d0d3d8;border-radius:8px;padding:0.5rem 1.1rem;font-size:0.85rem;font-weight:600;text-decoration:none;">Research</a>
63 <a href="https://console.ltx.io/playground/" class="bg-white hover:bg-gray-200 transition-colors duration-150" style="color:#1c1c1c;border:1px solid #d0d3d8;border-radius:8px;padding:0.5rem 1.1rem;font-size:0.85rem;font-weight:600;text-decoration:none;">API Playground</a>
64 <a href="https://discord.gg/ltxplatform" class="bg-white hover:bg-gray-200 transition-colors duration-150" style="color:#1c1c1c;border:1px solid #d0d3d8;border-radius:8px;padding:0.5rem 1.1rem;font-size:0.85rem;font-weight:600;text-decoration:none;">Discord</a>
65 </div>
66 <div style="margin-top:1.5rem;">
67 <a href="https://github.com/Lightricks/LTX-2/blob/main/LICENSE.md" class="bg-green-500 hover:brightness-110 transition-all duration-150" style="display:inline-block;color:#fff;border-radius:8px;padding:0.65rem 1.6rem;font-size:0.9rem;font-weight:700;text-decoration:none;">LTX License</a>
68 </div>
69 </div>
70 <!-- dark hero footer -->
71 <div class="hidden dark:block" style="background-color:#0a0a0a;padding:2rem 1.5rem 2.4rem;text-align:center;isolation:isolate;">
72 <h1 style="color:#fff;margin:0 0 0.5rem;font-size:2rem;font-weight:700;letter-spacing:-0.01em;border:none;padding:0;">LTX-2.5 — Video, Audio &amp; World Simulation</h1>
73 <p style="color:#c9c9c9;margin:0 0 1.25rem;font-size:1.05rem;">Full control and customization — self-host on your infrastructure.</p>
74 <div style="display:flex;flex-wrap:wrap;justify-content:center;gap:0.5rem;">
75 <a href="https://ltx.io" class="bg-gray-800 hover:bg-gray-700 transition-colors duration-150" style="color:#fff;border:1px solid #2e2e2e;border-radius:8px;padding:0.5rem 1.1rem;font-size:0.85rem;font-weight:600;text-decoration:none;">Homepage</a>
76 <a href="https://docs.ltx.io" class="bg-gray-800 hover:bg-gray-700 transition-colors duration-150" style="color:#fff;border:1px solid #2e2e2e;border-radius:8px;padding:0.5rem 1.1rem;font-size:0.85rem;font-weight:600;text-decoration:none;">Docs</a>
77 <a href="https://github.com/Lightricks/LTX-2" class="bg-gray-800 hover:bg-gray-700 transition-colors duration-150" style="color:#fff;border:1px solid #2e2e2e;border-radius:8px;padding:0.5rem 1.1rem;font-size:0.85rem;font-weight:600;text-decoration:none;">GitHub</a>
78 <a href="https://huggingface.co/papers/2601.03233" class="bg-gray-800 hover:bg-gray-700 transition-colors duration-150" style="color:#fff;border:1px solid #2e2e2e;border-radius:8px;padding:0.5rem 1.1rem;font-size:0.85rem;font-weight:600;text-decoration:none;">Research</a>
79 <a href="https://console.ltx.io/playground/" class="bg-gray-800 hover:bg-gray-700 transition-colors duration-150" style="color:#fff;border:1px solid #2e2e2e;border-radius:8px;padding:0.5rem 1.1rem;font-size:0.85rem;font-weight:600;text-decoration:none;">API Playground</a>
80 <a href="https://discord.gg/ltxplatform" class="bg-gray-800 hover:bg-gray-700 transition-colors duration-150" style="color:#fff;border:1px solid #2e2e2e;border-radius:8px;padding:0.5rem 1.1rem;font-size:0.85rem;font-weight:600;text-decoration:none;">Discord</a>
81 </div>
82 <div style="margin-top:1.5rem;">
83 <a href="https://github.com/Lightricks/LTX-2/blob/main/LICENSE.md" class="bg-green-500 hover:brightness-110 transition-all duration-150" style="display:inline-block;color:#fff;border-radius:8px;padding:0.65rem 1.6rem;font-size:0.9rem;font-weight:700;text-decoration:none;">LTX License</a>
84 </div>
85 </div>
86 </div>
87
88 <!-- LIGHT tier cards -->
89 <div class="dark:hidden lg:-mr-20 xl:-mr-24 2xl:-mr-36">
90 <div style="display:grid;grid-template-columns:1fr 1fr;gap:1rem;margin-top:1rem;">
91 <div style="background:#ecf8f2;border:1px solid #d6e9de;border-radius:6px;padding:1.5rem 1.6rem;">
92 <div style="width:44px;height:44px;border-radius:6px;background:#dceee4;display:flex;align-items:center;justify-content:center;margin:0 0 0.8rem;color:#1c1c1c;"><svg xmlns="http://www.w3.org/2000/svg" width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M16 20V4a2 2 0 0 0-2-2h-4a2 2 0 0 0-2 2v16"/><rect width="20" height="14" x="2" y="6" rx="2"/></svg></div>
93 <div style="font-size:1.3rem;font-weight:700;color:#0a0a0a;margin:0 0 0.6rem;line-height:1.35;">Under $10M annual revenue</div>
94 <p style="color:#333;font-size:1.05rem;margin:1.1rem 0;">Commercial and production use at no cost under the LTX-2.x Community License. Transfer of fine-tunes may require a paid license, in accordance with the LTX-2.x Community License.</p>
95 <a href="https://docs.ltx.io/open-source-model/getting-started/overview" class="bg-gray-900 hover:bg-gray-700 transition-colors duration-150" style="display:inline-block;color:#fff;border:1px solid #0a0a0a;border-radius:9999px;padding:0.5rem 1.1rem;font-size:0.85rem;font-weight:600;text-decoration:none;">Read the Documentation</a>
96 </div>
97 <div style="background:#f3eff9;border:1px solid #e0d8f0;border-radius:6px;padding:1.5rem 1.6rem;">
98 <div style="width:44px;height:44px;border-radius:6px;background:#e6deef;display:flex;align-items:center;justify-content:center;margin:0 0 0.8rem;color:#1c1c1c;"><svg xmlns="http://www.w3.org/2000/svg" width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M3 21h18"/><path d="M5 21V5a2 2 0 0 1 2-2h6a2 2 0 0 1 2 2v16"/><path d="M15 21V9a1 1 0 0 1 1-1h3a2 2 0 0 1 2 2v11"/><path d="M9 7h2"/><path d="M9 11h2"/><path d="M9 15h2"/></svg></div>
99 <div style="font-size:1.3rem;font-weight:700;color:#0a0a0a;margin:0 0 0.6rem;line-height:1.35;">Over $10M annual revenue</div>
100 <p style="color:#333;font-size:1.05rem;margin:1.1rem 0;">Paid Commercial Use Agreement for LTX-2.x with full weights, engineering support, LoRAs, and flexible deployment options. To learn about all licensing options, talk to an expert.</p>
101 <a href="https://ltx.io/forms/ltx-contact-sales?kpi=licensing" class="bg-gray-900 hover:bg-gray-700 transition-colors duration-150" style="display:inline-block;color:#fff;border:1px solid #0a0a0a;border-radius:9999px;padding:0.5rem 1.1rem;font-size:0.85rem;font-weight:600;text-decoration:none;">Talk to a Commercial Licensing Expert</a>
102 </div>
103 </div>
104 </div>
105
106 <!-- DARK tier cards -->
107 <div class="hidden dark:block lg:-mr-20 xl:-mr-24 2xl:-mr-36">
108 <div style="display:grid;grid-template-columns:1fr 1fr;gap:1rem;margin-top:1rem;">
109 <div style="background:#1a2622;border:1px solid #2a3a32;border-radius:6px;padding:1.5rem 1.6rem;">
110 <div style="width:44px;height:44px;border-radius:6px;background:#22332c;display:flex;align-items:center;justify-content:center;margin:0 0 0.8rem;color:#fff;"><svg xmlns="http://www.w3.org/2000/svg" width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M16 20V4a2 2 0 0 0-2-2h-4a2 2 0 0 0-2 2v16"/><rect width="20" height="14" x="2" y="6" rx="2"/></svg></div>
111 <div style="font-size:1.3rem;font-weight:700;color:#fff;margin:0 0 0.6rem;line-height:1.35;">Under $10M annual revenue</div>
112 <p style="color:#c9ced6;font-size:1.05rem;margin:1.1rem 0;">Commercial and production use at no cost under the LTX-2.x Community License. Transfer of fine-tunes may require a paid license, in accordance with the LTX-2.x Community License.</p>
113 <a href="https://docs.ltx.io/open-source-model/getting-started/overview" class="bg-gray-50 hover:bg-gray-300 transition-colors duration-150" style="display:inline-block;color:#1c1c1c;border:1px solid #f8fafc;border-radius:9999px;padding:0.5rem 1.1rem;font-size:0.85rem;font-weight:600;text-decoration:none;">Read the Documentation</a>
114 </div>
115 <div style="background:#221a2e;border:1px solid #322a42;border-radius:6px;padding:1.5rem 1.6rem;">
116 <div style="width:44px;height:44px;border-radius:6px;background:#2a2238;display:flex;align-items:center;justify-content:center;margin:0 0 0.8rem;color:#fff;"><svg xmlns="http://www.w3.org/2000/svg" width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M3 21h18"/><path d="M5 21V5a2 2 0 0 1 2-2h6a2 2 0 0 1 2 2v16"/><path d="M15 21V9a1 1 0 0 1 1-1h3a2 2 0 0 1 2 2v11"/><path d="M9 7h2"/><path d="M9 11h2"/><path d="M9 15h2"/></svg></div>
117 <div style="font-size:1.3rem;font-weight:700;color:#fff;margin:0 0 0.6rem;line-height:1.35;">Over $10M annual revenue</div>
118 <p style="color:#c9ced6;font-size:1.05rem;margin:1.1rem 0;">Paid Commercial Use Agreement for LTX-2.x with full weights, engineering support, LoRAs, and flexible deployment options. To learn about all licensing options, talk to an expert.</p>
119 <a href="https://ltx.io/forms/ltx-contact-sales?kpi=licensing" class="bg-gray-50 hover:bg-gray-300 transition-colors duration-150" style="display:inline-block;color:#1c1c1c;border:1px solid #f8fafc;border-radius:9999px;padding:0.5rem 1.1rem;font-size:0.85rem;font-weight:600;text-decoration:none;">Talk to a Commercial Licensing Expert</a>
120 </div>
121 </div>
122 </div>
123
124 ---
125
126 **LTX-2.5** is an open world model with open weights, built for local execution and fine-tuning. Its established use is generating synchronized, high-fidelity video and audio from text, image, and video inputs; applicability to emerging domains such as robotics and physical AI is developing.
127
128 **Full control and customization** — self-host on your own infrastructure. No per-generation billing, no per-seat lock-in, no forced API dependency. Revenue is measured across the whole entity, including subsidiaries and affiliates under common control. The full, binding terms live in [`LICENSE`](https://github.com/Lightricks/LTX-2/blob/main/LICENSE.md).
129
130
131 ## What's new in LTX-2.5
132
133 - **Native multishot generation** — generate connected scenes in a single pass: multiple shots that hold character identity, environment, lighting, voice, and visual style across cuts (previous versions produced a single continuous shot).
134 - **Diffusion fidelity rendering** — Instead of locking every scene to one compression rate, our model dynamically allocates compute by scene complexity and budget, rendering flawless detail where it matters, efficient everywhere else.
135 - **New diffusion video decoder** — replaces the VAE reconstruction stage; sharper faces, textures, and on-screen text, better motion, and fewer artifacts in demanding scenes.
136 - **Custom Gemma 4 12B text encoder** — holds complex prompts together (multiple characters, camera moves, lighting, actions) instead of dropping details across a longer sequence.
137 - **Prompt enhancer** — expands a short prompt into richer cinematic instructions at minimal extra compute.
138 - **Duration predictor (optional)** — an opt-in node predicts a clip's length from the prompt and sets the frame count for you, instead of relying on a fixed-duration parameter.
139 - **Substantially improved distilled model** — retains much more of the full model's visual quality, prompt adherence, and motion consistency in a smaller, faster checkpoint.
140
141 ---
142
143 # Model family & checkpoints
144
145 LTX-2.5 ships as a **split, Comfy-aligned pack** (one `.safetensors` per component) rather than a single monolith. Point each CLI flag / loader at the file below.
146
147 ## Transformers (DiT)
148
149 | File | Notes |
150 |------|-------|
151 | [`diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors`](https://huggingface.co/Lightricks/LTX-2.5/blob/main/diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors) | Distilled DiT (bf16). Fixed 8-step schedule, CFG=1. |
152 | [`diffusion_models/ltx-2.5-22b-dev-transformer-bf16.safetensors`](https://huggingface.co/Lightricks/LTX-2.5/blob/main/diffusion_models/ltx-2.5-22b-dev-transformer-bf16.safetensors) | Full / trainable DiT (bf16). |
153 | [`diffusion_models/ltx-2.5-22b-distilled-transformer-comfy-int8-convrot.safetensors`](https://huggingface.co/Lightricks/LTX-2.5/blob/main/diffusion_models/ltx-2.5-22b-distilled-transformer-comfy-int8-convrot.safetensors) | Distilled DiT (Comfy int8 + convrot). **ComfyUI only** — not for `ltx-pipelines` / PyTorch. |
154 | [`diffusion_models/ltx-2.5-22b-dev-transformer-comfy-int8-convrot.safetensors`](https://huggingface.co/Lightricks/LTX-2.5/blob/main/diffusion_models/ltx-2.5-22b-dev-transformer-comfy-int8-convrot.safetensors) | Full DiT (Comfy int8 + convrot). **ComfyUI only** — not for `ltx-pipelines` / PyTorch. |
155 | [`diffusion_models/ltx-2.5-22b-distilled-transformer-nvfp4.safetensors`](https://huggingface.co/Lightricks/LTX-2.5/blob/main/diffusion_models/ltx-2.5-22b-distilled-transformer-nvfp4.safetensors) | Distilled DiT (NVFP4). ComfyUI, or `ltx-pipelines` with `--quantization nvfp4-prequant` (Blackwell / `ltx-kernels`). |
156
157 ## Other components
158
159 | File | Notes |
160 |------|-------|
161 | [`text_encoders/gemma4-12b-with-proj-ltx-2.5-bf16.safetensors`](https://huggingface.co/Lightricks/LTX-2.5/blob/main/text_encoders/gemma4-12b-with-proj-ltx-2.5-bf16.safetensors) | Gemma4 TE + projections (bf16) |
162 | [`text_encoders/gemma4-12b-with-proj-ltx-2.5-comfy-int8-convrot.safetensors`](https://huggingface.co/Lightricks/LTX-2.5/blob/main/text_encoders/gemma4-12b-with-proj-ltx-2.5-comfy-int8-convrot.safetensors) | Same TE, Comfy int8 — **ComfyUI only** |
163 | [`vae/ltx-2.5-video-vae-bf16.safetensors`](https://huggingface.co/Lightricks/LTX-2.5/blob/main/vae/ltx-2.5-video-vae-bf16.safetensors) | DiffVAE — higher quality, heavier |
164 | [`vae/ltx-2.5-video-vae-conv-bf16.safetensors`](https://huggingface.co/Lightricks/LTX-2.5/blob/main/vae/ltx-2.5-video-vae-conv-bf16.safetensors) | Conv VAE — faster, lighter |
165 | [`vae/ltx-2.5-audio-vae-bf16.safetensors`](https://huggingface.co/Lightricks/LTX-2.5/blob/main/vae/ltx-2.5-audio-vae-bf16.safetensors) | Audio VAE + vocoder |
166 | [`loras/ltx-2.5-22b-distilled-lora-450-bf16.safetensors`](https://huggingface.co/Lightricks/LTX-2.5/blob/main/loras/ltx-2.5-22b-distilled-lora-450-bf16.safetensors) | Distilled LoRA (dev-transformer workflows) |
167 | [`model_patches/ltx-2.5-duration-head-bf16.safetensors`](https://huggingface.co/Lightricks/LTX-2.5/blob/main/model_patches/ltx-2.5-duration-head-bf16.safetensors) | Auto duration when `--num-frames` omitted |
168 | [`latent_upscale_models/ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0.safetensors`](https://huggingface.co/Lightricks/LTX-2.5/blob/main/latent_upscale_models/ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0.safetensors) | x2 spatial upscaler required for multi-stage pipeline |
169 | [`latent_upscale_models/ltx-2.5-latent-temporal-upscaler-x2-bf16-1.0.safetensors`](https://huggingface.co/Lightricks/LTX-2.5/blob/main/latent_upscale_models/ltx-2.5-latent-temporal-upscaler-x2-bf16-1.0.safetensors) | x2 temporal upscaler |
170
171 ---
172
173 # Usage
174
175 ### Online demo
176
177 Try LTX-2.5 in the [API Playground](https://console.ltx.video/playground/) without installing anything locally.
178
179 ### Option A — Python (`ltx-pipelines`)
180
181 Weights on this repo are **split** (Comfy-aligned): one safetensors file per component. The [LTX-2](https://github.com/Lightricks/LTX-2) `ltx-pipelines` package loads them via `--transformer-path`, `--text-encoder-path`, etc.
182
183 #### Install
184
185 ```bash
186 git clone https://github.com/Lightricks/LTX-2.git
187 cd LTX-2
188 uv sync
189 source .venv/bin/activate
190 ```
191
192 Python >= 3.12, CUDA >= 12.7, PyTorch ~= 2.7 recommended. See the [repo README](https://github.com/Lightricks/LTX-2) for attention backends and optional extras.
193
194 #### Download weights
195
196 ```bash
197 hf auth login
198
199 # LTX-2.5 distilled split pack
200 hf download Lightricks/LTX-2.5 \
201 diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors \
202 text_encoders/gemma4-12b-with-proj-ltx-2.5-bf16.safetensors \
203 vae/ltx-2.5-video-vae-bf16.safetensors \
204 vae/ltx-2.5-audio-vae-bf16.safetensors \
205 model_patches/ltx-2.5-duration-head-bf16.safetensors \
206 --local-dir models/ltx-2.5
207
208 # Spatial upscaler (still hosted on LTX-2.3; required by the distilled pipeline)
209 hf download Lightricks/LTX-2.3 \
210 ltx-2.3-spatial-upscaler-x2-1.1.safetensors \
211 --local-dir models/ltx-2.3
212 ```
213
214 #### Distilled text-to-video
215
216 ```bash
217 uv run python -m ltx_pipelines.distilled \
218 --transformer-path models/ltx-2.5/diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors \
219 --text-encoder-path models/ltx-2.5/text_encoders/gemma4-12b-with-proj-ltx-2.5-bf16.safetensors \
220 --video-vae-path models/ltx-2.5/vae/ltx-2.5-video-vae-bf16.safetensors \
221 --audio-vae-path models/ltx-2.5/vae/ltx-2.5-audio-vae-bf16.safetensors \
222 --duration-head-path models/ltx-2.5/model_patches/ltx-2.5-duration-head-bf16.safetensors \
223 --spatial-upsampler-path models/ltx-2.3/ltx-2.3-spatial-upscaler-x2-1.1.safetensors \
224 --prompt "A golden retriever running through a sunny meadow, cinematic lighting" \
225 --seed 42 \
226 --output-path output_distilled.mp4
227 ```
228
229 Omit `--num-frames` to let the duration head pick a length from the prompt (LTX-2.5+). Or set e.g. `--num-frames 121` (must satisfy `frames % 8 == 1`). Width/height must be divisible by 32.
230
231 #### Image-to-video
232
233 Add one or more `--image PATH FRAME_IDX STRENGTH` flags (frame 0 = first frame conditioning):
234
235 ```bash
236 uv run python -m ltx_pipelines.distilled \
237 --transformer-path models/ltx-2.5/diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors \
238 --text-encoder-path models/ltx-2.5/text_encoders/gemma4-12b-with-proj-ltx-2.5-bf16.safetensors \
239 --video-vae-path models/ltx-2.5/vae/ltx-2.5-video-vae-bf16.safetensors \
240 --audio-vae-path models/ltx-2.5/vae/ltx-2.5-audio-vae-bf16.safetensors \
241 --duration-head-path models/ltx-2.5/model_patches/ltx-2.5-duration-head-bf16.safetensors \
242 --spatial-upsampler-path models/ltx-2.3/ltx-2.3-spatial-upscaler-x2-1.1.safetensors \
243 --image path/to/first_frame.jpg 0 1.0 \
244 --prompt "The camera slowly dollies out as wind moves through the grass" \
245 --seed 42 \
246 --output-path output_i2v.mp4
247 ```
248
249 #### Low-VRAM tips
250
251 ```bash
252 # Downcast bf16 transformer on the fly + CPU offload
253 ...existing flags... \
254 --quantization fp8-cast \
255 --offload cpu
256 ```
257
258 Use the **bf16** checkpoints with `ltx-pipelines`. The `*-comfy-int8-convrot.safetensors` files are ComfyUI-only and are not loaded by this PyTorch path.
259
260 #### Python API (same split paths)
261
262 ```python
263 from ltx_pipelines.distilled import DistilledPipeline
264 from ltx_pipelines.utils.model_paths import ModelPaths
265
266 model_paths = ModelPaths.from_split(
267 transformer_path="models/ltx-2.5/diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors",
268 text_encoder_path="models/ltx-2.5/text_encoders/gemma4-12b-with-proj-ltx-2.5-bf16.safetensors",
269 video_vae_path="models/ltx-2.5/vae/ltx-2.5-video-vae-bf16.safetensors",
270 audio_vae_path="models/ltx-2.5/vae/ltx-2.5-audio-vae-bf16.safetensors",
271 duration_head_path="models/ltx-2.5/model_patches/ltx-2.5-duration-head-bf16.safetensors",
272 )
273
274 pipe = DistilledPipeline(
275 model_paths=model_paths,
276 spatial_upsampler_path="models/ltx-2.3/ltx-2.3-spatial-upscaler-x2-1.1.safetensors",
277 )
278 # See packages/ltx-pipelines for __call__ args (prompt, seed, num_frames, images, ...).
279 ```
280
281 ```bash
282 uv run python -m ltx_pipelines.distilled --help
283 ```
284
285 Full docs: [ltx-pipelines installation](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-pipelines/docs/installation.md).
286
287 ### Option B — ComfyUI
288
289 Official LTX-2.5 workflow templates ship in ComfyUI. Full instructions: [ComfyUI integration](https://docs.ltx.video/open-source-model/integration-tools/comfy-ui).
290
291 ### Option C — Diffusers
292
293 A Diffusers-compatible pack lives at [`Lightricks/LTX-2.5-Diffusers`](https://huggingface.co/Lightricks/LTX-2.5-Diffusers) — same model, Diffusers-friendly packaging.
294
295 #### Install
296
297 LTX-2.5 support is not in a `diffusers` release yet, so install from main:
298
299 ```bash
300 pip install git+https://github.com/huggingface/diffusers
301 ```
302
303 #### Image-to-video, two stages
304
305 ```python
306 import torch
307 from diffusers import LTX2ImageToVideoPipeline, LTX2LatentUpsamplePipeline
308 from diffusers.pipelines.ltx2.latent_upsampler import LTX2LatentUpsamplerModel
309 from diffusers.pipelines.ltx2.utils import (
310 DEFAULT_NEGATIVE_PROMPT,
311 DISTILLED_SIGMA_VALUES,
312 STAGE_2_DISTILLED_SIGMA_VALUES,
313 )
314 from diffusers.utils import encode_video, load_image
315
316 MODEL_ID = "Lightricks/LTX-2.5-Diffusers"
317 # Stage 1 resolution; stage 2 runs at 2x this.
318 HEIGHT, WIDTH, NUM_FRAMES, FRAME_RATE = 544, 960, 121, 24.0
319
320 pipe = LTX2ImageToVideoPipeline.from_pretrained(MODEL_ID, dtype=torch.bfloat16)
321 pipe.enable_model_cpu_offload()
322 pipe.vae.enable_tiling() # stage 2 decodes at 2x
323
324 latent_upsampler = LTX2LatentUpsamplerModel.from_pretrained(
325 MODEL_ID, subfolder="latent_upsampler", dtype=torch.bfloat16
326 ).to("cuda")
327 upsample_pipe = LTX2LatentUpsamplePipeline(vae=pipe.vae, latent_upsampler=latent_upsampler)
328
329 generator = torch.Generator("cuda").manual_seed(42)
330 shared = dict(
331 image=load_image("path/to/first_frame.jpg"),
332 prompt="The camera slowly dollies out as wind moves through the grass",
333 negative_prompt=DEFAULT_NEGATIVE_PROMPT,
334 frame_rate=FRAME_RATE,
335 guidance_scale=1.0,
336 audio_guidance_scale=1.0,
337 stg_scale=0.0,
338 audio_stg_scale=0.0,
339 modality_scale=1.0,
340 audio_modality_scale=1.0,
341 generator=generator,
342 return_dict=False,
343 )
344
345 stage_1_latents, audio_latents = pipe(
346 height=HEIGHT, width=WIDTH, num_frames=NUM_FRAMES,
347 sigmas=DISTILLED_SIGMA_VALUES, output_type="latent", **shared,
348 )
349
350 upsampled_latents = upsample_pipe(
351 latents=stage_1_latents, output_type="latent", return_dict=False
352 )[0]
353
354 # Stage 2 takes its size from the upsampled latents, so pass no height/width.
355 video, audio = pipe(
356 num_frames=NUM_FRAMES,
357 sigmas=STAGE_2_DISTILLED_SIGMA_VALUES,
358 latents=upsampled_latents,
359 audio_latents=audio_latents,
360 noise_scale=STAGE_2_DISTILLED_SIGMA_VALUES[0],
361 output_type="np",
362 **shared,
363 )
364
365 encode_video(
366 video[0],
367 fps=int(FRAME_RATE),
368 output_path="output_i2v_two_stage.mp4",
369 audio=audio[0].float().cpu(),
370 audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
371 )
372 ```
373
374 ---
375
376 ### Constraints
377
378 - Frame count: `num_frames % 8 == 1` (1, 9, 17, …, 121, …)
379 - Width and height divisible by 32
380
381 ### Prompting
382
383 Well-structured, detailed prompts materially improve results. For multishot prompting and a full guide, see [How to prompt LTX-2](https://docs.ltx.video/open-source-model/usage-guides/prompting-guide).
384
385 ---
386
387 # Training & fine-tuning
388
389 The **dev** transformer is fully trainable. Reproduce published LoRAs and IC-LoRAs with the [LTX-2 Trainer](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-trainer/README.md).
390
391 Based on our testing, the large majority of LoRAs and IC-LoRAs trained on LTX-2.3 run on LTX-2.5 without changes. A small number of exceptions exist — validate your adapters before production use.
392
393 ---
394
395 # Limitations
396
397 - This model is not intended or able to provide factual information.
398 - As a statistical model, this checkpoint may amplify existing societal biases.
399 - Prompt following is heavily influenced by prompting style.
400 - The model may fail to generate videos that match the prompt perfectly.
401 - The model may generate content that is inappropriate or offensive.
402
403 ---
404
405 ## Citation
406
407 ```bibtex
408 @article{hacohen2025ltx2,
409 title={LTX-2: Efficient Joint Audio-Visual Foundation Model},
410 author={HaCohen, Yoav and Brazowski, Benny and Chiprut, Nisan and Bitterman, Yaki and Kvochko, Andrew and Berkowitz, Avishai and Shalem, Daniel and Lifschitz, Daphna and Moshe, Dudu and Porat, Eitan and Richardson, Eitan and Guy Shiran and Itay Chachy and Jonathan Chetboun and Michael Finkelson and Michael Kupchick and Nir Zabari and Nitzan Guetta and Noa Kotler and Ofir Bibi and Ori Gordon and Poriya Panet and Roi Benita and Shahar Armon and Victor Kulikov and Yaron Inger and Yonatan Shiftan and Zeev Melumian and Zeev Farbman},
411 journal={arXiv preprint arXiv:2601.03233},
412 year={2026}
413 }
414 ```