PyTorch API

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 is a monorepo with three packages:

Requirements

• Python >= 3.12
• CUDA >= 12.7
• PyTorch ~= 2.7

See System Requirements for full hardware specifications.

Installation

# 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 on first download):

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.

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

All pipelines also run from the command line (python -m ltx_pipelines.<module> --help). For the full module list, shared CLI flags, and a per-pipeline reference, see Installation & Usage and Available Pipelines on GitHub.

Text-to-Video Example

This runs the distilled pipeline from the command line — the same interface as the Pipeline Quick Start. Each split component is passed with its own path flag:

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:

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.

Guidance Parameters

The native pipelines expose MultiModalGuiderParams for fine-grained control over generation:

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:

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 — the same model in Diffusers-friendly packaging. Load it with from_pretrained against that repo id:

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,
)

For the exact pipeline class and current examples, see the Lightricks/LTX-2.5-Diffusers model card.

Generation Parameters Reference

Resolution

Standard aspect ratios:

Higher resolutions are supported (up to 4K) but require significantly more VRAM. Start with lower resolutions for testing.

Frame Count & Duration

Sampling