> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs-dev.ltx.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-dev.ltx.io/_mcp/server. # PyTorch API > Integrate LTX-2.5 from Python with native ltx-pipelines or Diffusers, including split model files and generation examples. For developers who want direct Python integration or custom workflows beyond ComfyUI, LTX offers two paths: the native `ltx-pipelines` package (full control, all features) and the HuggingFace Diffusers integration (familiar API, quick start). ## Repository Structure The [LTX-2 codebase](https://github.com/Lightricks/LTX-2) is a monorepo with three packages: | Package | Purpose | | ----------------- | ----------------------------------------------------------------------------------------------------- | | **ltx-core** | Model architecture, schedulers, guiders, noisers, and patchifiers | | **ltx-pipelines** | High-level inference pipelines for text-to-video, image-to-video, and IC-LoRA workflows | | **ltx-trainer** | LoRA, IC-LoRA, and full fine-tuning (see [Trainer docs](/open-source-model/ltx-trainer/ltx-training)) | ## Requirements * Python >= 3.12 * CUDA >= 12.7 * PyTorch \~= 2.7 See [System Requirements](/open-source-model/getting-started/system-requirements) for full hardware specifications. ## Installation ```bash # Clone the repository git clone https://github.com/Lightricks/LTX-2.git cd LTX-2 # Set up the environment uv sync source .venv/bin/activate ``` ## Download Models LTX-2.5 ships as a **split pack** — one `.safetensors` file per component (transformer, text encoder, video/audio VAEs, duration head). The distilled text-to-video pipeline needs the files below. Download them with the Hugging Face CLI (click **Agree and Access** on the [model page](https://huggingface.co/Lightricks/LTX-2.5) on first download): ```bash hf auth login # LTX-2.5 distilled split pack 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 \ model_patches/ltx-2.5-duration-head-bf16.safetensors \ latent_upscale_models/ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0.safetensors \ --local-dir models/ltx-2.5 ``` Use the **bf16** files with `ltx-pipelines`. The `*-comfy-int8_convrot` variants are **ComfyUI-only** and are not loaded by the PyTorch path. For the full checkpoint list (dev transformer, conv VAE, distilled LoRA, upscalers), see the [LTX-2.5 model card](https://huggingface.co/Lightricks/LTX-2.5). --- ## Option 1: Native Pipelines (ltx-pipelines) The `ltx-pipelines` package provides the most complete feature set, including two-stage generation, IC-LoRA, and fine-grained guidance control. ### Available Pipelines | Pipeline | Use case | | ------------------------------- | ------------------------------------------------------------------------------------------------------- | | `TI2VidTwoStagesPipeline` | Text/image-to-video with two-stage upscaling. Recommended for production. | | `TI2VidTwoStagesHQPipeline` | Same two-stage flow with the res\_2s second-order sampler — fewer steps, highest quality. | | `TI2VidOneStagePipeline` | Single-stage text/image-to-video for quick prototyping (no upscaling). | | `DistilledPipeline` | Fast two-stage generation on the distilled checkpoint. Best for speed and batch runs. | | `ICLoraPipeline` | Video-to-video with IC-LoRA adapters (control, restoration, creative transforms). Distilled model. | | `DubItPipeline` | Dub-It — re-voice or rephrase speech with matched lips and preserved speaker identity. Distilled model. | | `HDRICLoraPipeline` | Video-to-video with HDR output (linear-float EXR for color grading). Distilled model. | | `A2VidPipelineTwoStage` | Audio-to-video conditioned on an input audio track. | | `T2AOneStagePipeline` | Text-to-audio — audio-only output (no video branch) from a text prompt. | | `RetakePipeline` | Regenerate a specific time region of an existing video without starting over. | | `KeyframeInterpolationPipeline` | Interpolate between keyframe images for smooth transitions. | All pipelines also run from the command line (`python -m ltx_pipelines. --help`). For the full module list, shared CLI flags, and a per-pipeline reference, see [Installation & Usage](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-pipelines/docs/installation.md) and [Available Pipelines](https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-pipelines/docs/pipelines.md) on GitHub. ### Text-to-Video Example This runs the distilled pipeline from the command line — the same interface as the [Pipeline Quick Start](/open-source-model/getting-started/quick-start#pipeline-quick-start). Each split component is passed with its own path flag: ```bash 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 \ --duration-head-path models/ltx-2.5/model_patches/ltx-2.5-duration-head-bf16.safetensors \ --spatial-upsampler-path models/ltx-2.5/latent_upscale_models/ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0.safetensors \ --prompt "A golden retriever running through a sunlit meadow, cinematic lighting. Sound of panting, rustling grass, distant birdsong." \ --seed 42 \ --output-path output.mp4 ``` You can drive the same pipeline from Python, passing the split paths through `ModelPaths`: ```python from ltx_pipelines.distilled import DistilledPipeline from ltx_pipelines.utils.model_paths import ModelPaths model_paths = ModelPaths.from_split( 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", duration_head_path="models/ltx-2.5/model_patches/ltx-2.5-duration-head-bf16.safetensors", ) pipe = DistilledPipeline( model_paths=model_paths, spatial_upsampler_path="models/ltx-2.5/latent_upscale_models/ltx-2.5-latent-spatial-upscaler-x2-bf16-1.0.safetensors", ) # See packages/ltx-pipelines for the __call__ arguments (prompt, seed, num_frames, images, …). ``` Add `--help` to any pipeline module to see its full option list, including the guidance parameters below. > **Note** > > **Dimension constraints:** Width and height must be divisible by 32. Frame > count must follow the pattern `8n + 1` (valid values: 1, 9, 17, 25, …, 97, > 105, 113, 121, etc.). Omit `--num-frames` to let the duration head pick a > length from the prompt (LTX-2.5+), or set it explicitly, e.g. `--num-frames 121`. ### Guidance Parameters The native pipelines expose `MultiModalGuiderParams` for fine-grained control over generation: | Parameter | Range | Description | | ---------------- | ----------- | ----------------------------------------------------------------------------------------- | | `cfg_scale` | 2.0–5.0 | Classifier-Free Guidance. Higher values increase prompt adherence. Set to 1.0 to disable. | | `stg_scale` | 0.5–1.5 | Spatio-Temporal Guidance for temporal coherence. Set to 0.0 to disable. | | `stg_blocks` | e.g. `[28]` | Transformer blocks to perturb for STG. Set to `[]` to disable. | | `rescale_scale` | \~0.7 | Rescales guided prediction to prevent over-saturation. | | `modality_scale` | 1.0–3.0 | Audio-visual sync strength. Set > 1.0 when generating with audio. | ### Memory Optimization For consumer GPUs, reduce VRAM by running the transformer in FP8 and offloading weights to CPU — add these flags to any pipeline command: ```bash uv run python -m ltx_pipelines.distilled \ ...model + prompt flags... \ --quantization fp8-cast \ --offload cpu ``` * `--quantization fp8-cast` downcasts the bf16 transformer on the fly and works on any FP8-capable GPU. Use the **bf16** checkpoints for this — the `*-comfy-int8_convrot` files are ComfyUI-only. * `--quantization fp8-scaled-mm` is the alternative for a native-FP8 checkpoint on Hopper+ GPUs. * `--offload cpu` streams weights from system RAM per layer; `--offload disk` reads them from disk on demand (lowest memory, slower). **Additional tip:** set `PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True` to improve memory allocation. --- ## Option 2: HuggingFace Diffusers LTX-2.5 is published as a Diffusers-compatible pack in a separate repo, [`Lightricks/LTX-2.5-Diffusers`](https://huggingface.co/Lightricks/LTX-2.5-Diffusers) — the same model in Diffusers-friendly packaging. Load it with `from_pretrained` against that repo id: ```python import torch from diffusers import LTX2Pipeline pipeline = LTX2Pipeline.from_pretrained( "Lightricks/LTX-2.5-Diffusers", torch_dtype=torch.bfloat16, ) pipeline.to("cuda") result = pipeline( prompt="A golden retriever running through a sunlit meadow, " "wildflowers swaying in a gentle breeze.", width=768, height=512, ) ``` > **Note** > > The Diffusers integration provides a simpler interface but may not expose all > features available in the native `ltx-pipelines` package (e.g., IC-LoRA, > advanced guidance parameters). For full feature access, use the native > pipelines. For the exact pipeline class and current examples, see the [`Lightricks/LTX-2.5-Diffusers`](https://huggingface.co/Lightricks/LTX-2.5-Diffusers) model card. --- ## Generation Parameters Reference ### Resolution Standard aspect ratios: | Resolution | Aspect Ratio | Notes | | ---------- | ------------- | --------------------------- | | 768×512 | 3:2 landscape | Good default for wide shots | | 512×768 | 2:3 portrait | Vertical/mobile content | | 704×512 | 4:3 standard | Classic frame | | 512×704 | 3:4 vertical | | | 640×640 | 1:1 square | Social media | Higher resolutions are supported (up to 4K) but require significantly more VRAM. Start with lower resolutions for testing. ### Frame Count & Duration | Frames | Duration (24fps) | Duration (25fps) | | ------ | ---------------- | ---------------- | | 65 | \~2.7s | \~2.6s | | 97 | \~4.0s | \~3.9s | | 121 | \~5.0s | \~4.8s | | 161 | \~6.7s | \~6.4s | | 257 | \~10.7s | \~10.3s | ### Sampling | Parameter | Distilled Model | Full Model | | ----------- | --------------- | ---------- | | Steps | 4–8 | 20–50 | | CFG Scale | 1.0 | 2.0–5.0 | | Recommended | 3.0–3.5 | 3.0–3.5 |