Diffusers documentation
LTX-2
LTX-2
LTX-2 es un modelo de base basado en DiT diseñado para generar video y audio sincronizados dentro de un solo modelo. Reúne los bloques de construcción fundamentales de la generación de video moderna, con pesos abiertos y un enfoque en la ejecución práctica y local.
Puedes encontrar todos los checkpoints originales de LTX-Video bajo la organización Lightricks.
El código original de LTX-2 se puede encontrar aquí.
Generación en dos etapas
Los valores predeterminados del __call__ compartido de LTX2Pipeline / LTX2ImageToVideoPipeline coinciden con la referencia de LTX-2.5 (num_inference_steps=30; num_frames es opcional cuando hay un duration_head, de lo contrario se usa 121). Los ejemplos de abajo usan esos valores predeterminados también para LTX-2.0/2.3.
Pipeline recomendado para lograr una generación de calidad de producción; este pipeline está compuesto por dos etapas:
- Etapa 1: Generar un video en la resolución objetivo mediante muestreo de difusión con guía libre de clasificador (CFG). Esta etapa produce una secuencia de video coherente con bajo ruido que respeta la condición de texto/imagen.
- Etapa 2: Aumentar la resolución de la salida de la Etapa 1 por un factor de 2 y refinar los detalles utilizando un modelo LoRA destilado para mejorar la fidelidad y la calidad visual. La Etapa 2 puede aplicar un CFG más ligero para preservar la estructura de la Etapa 1 mientras mejora la textura y la nitidez.
Uso de ejemplo del pipeline de texto a video en dos etapas
import torch
from diffusers import FlowMatchEulerDiscreteScheduler
from diffusers.pipelines.ltx2 import LTX2Pipeline, LTX2LatentUpsamplePipeline
from diffusers.models.latent_upscaler import LTX2LatentUpsamplerModel
from diffusers.pipelines.ltx2.utils import STAGE_2_DISTILLED_SIGMA_VALUES
from diffusers.utils import encode_video
device = "cuda:0"
width = 768
height = 512
pipe = LTX2Pipeline.from_pretrained(
"Lightricks/LTX-2", dtype=torch.bfloat16
)
pipe.enable_sequential_cpu_offload(device=device)
prompt = "A beautiful sunset over the ocean"
negative_prompt = "shaky, glitchy, low quality, worst quality, deformed, distorted, disfigured, motion smear, motion artifacts, fused fingers, bad anatomy, weird hand, ugly, transition, static."
# Stage 1 default (non-distilled) inference
frame_rate = 24.0
video_latent, audio_latent = pipe(
prompt=prompt,
negative_prompt=negative_prompt,
width=width,
height=height,
num_frames=121,
frame_rate=frame_rate,
num_inference_steps=30,
sigmas=None,
guidance_scale=3.0,
output_type="latent",
return_dict=False,
)
latent_upsampler = LTX2LatentUpsamplerModel.from_pretrained(
"Lightricks/LTX-2",
subfolder="latent_upsampler",
dtype=torch.bfloat16,
)
upsample_pipe = LTX2LatentUpsamplePipeline(vae=pipe.vae, latent_upsampler=latent_upsampler)
upsample_pipe.enable_model_cpu_offload(device=device)
upscaled_video_latent = upsample_pipe(
latents=video_latent,
output_type="latent",
return_dict=False,
)[0]
# Load Stage 2 distilled LoRA
pipe.load_lora_weights(
"Lightricks/LTX-2", adapter_name="stage_2_distilled", weight_name="ltx-2-19b-distilled-lora-384.safetensors"
)
pipe.set_adapters("stage_2_distilled", 1.0)
# VAE tiling is usually necessary to avoid OOM error when VAE decoding
pipe.vae.enable_tiling()
# Change scheduler to use Stage 2 distilled sigmas as is
new_scheduler = FlowMatchEulerDiscreteScheduler.from_config(
pipe.scheduler.config, use_dynamic_shifting=False, shift_terminal=None
)
pipe.scheduler = new_scheduler
# Stage 2 inference with distilled LoRA and sigmas
video, audio = pipe(
latents=upscaled_video_latent,
audio_latents=audio_latent,
prompt=prompt,
negative_prompt=negative_prompt,
num_inference_steps=3,
noise_scale=STAGE_2_DISTILLED_SIGMA_VALUES[0], # renoise with first sigma value https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-pipelines/src/ltx_pipelines/ti2vid_two_stages.py#L218
sigmas=STAGE_2_DISTILLED_SIGMA_VALUES,
guidance_scale=1.0,
output_type="np",
return_dict=False,
)
encode_video(
video[0],
fps=frame_rate,
audio=audio[0].float().cpu(),
audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
output_path="ltx2_lora_distilled_sample.mp4",
)Generación de puntos de control destilados
Pipeline de generación de dos etapas más rápido que utiliza un punto de control destilado.
import torch
from diffusers.pipelines.ltx2 import LTX2Pipeline, LTX2LatentUpsamplePipeline
from diffusers.models.latent_upscaler import LTX2LatentUpsamplerModel
from diffusers.pipelines.ltx2.utils import DISTILLED_SIGMA_VALUES, STAGE_2_DISTILLED_SIGMA_VALUES
from diffusers.utils import encode_video
device = "cuda" # or "mps", "xpu", "cpu"
width = 768
height = 512
random_seed = 42
generator = torch.Generator(device).manual_seed(random_seed)
model_path = "rootonchair/LTX-2-19b-distilled"
pipe = LTX2Pipeline.from_pretrained(
model_path, dtype=torch.bfloat16
)
pipe.enable_sequential_cpu_offload(device=device)
prompt = "A beautiful sunset over the ocean"
negative_prompt = "shaky, glitchy, low quality, worst quality, deformed, distorted, disfigured, motion smear, motion artifacts, fused fingers, bad anatomy, weird hand, ugly, transition, static."
frame_rate = 24.0
video_latent, audio_latent = pipe(
prompt=prompt,
negative_prompt=negative_prompt,
width=width,
height=height,
num_frames=121,
frame_rate=frame_rate,
num_inference_steps=8,
sigmas=DISTILLED_SIGMA_VALUES,
guidance_scale=1.0,
generator=generator,
output_type="latent",
return_dict=False,
)
latent_upsampler = LTX2LatentUpsamplerModel.from_pretrained(
model_path,
subfolder="latent_upsampler",
dtype=torch.bfloat16,
)
upsample_pipe = LTX2LatentUpsamplePipeline(vae=pipe.vae, latent_upsampler=latent_upsampler)
upsample_pipe.enable_model_cpu_offload(device=device)
upscaled_video_latent = upsample_pipe(
latents=video_latent,
output_type="latent",
return_dict=False,
)[0]
video, audio = pipe(
latents=upscaled_video_latent,
audio_latents=audio_latent,
prompt=prompt,
negative_prompt=negative_prompt,
num_inference_steps=3,
noise_scale=STAGE_2_DISTILLED_SIGMA_VALUES[0], # renoise with first sigma value https://github.com/Lightricks/LTX-2/blob/main/packages/ltx-pipelines/src/ltx_pipelines/distilled.py#L178
sigmas=STAGE_2_DISTILLED_SIGMA_VALUES,
generator=generator,
guidance_scale=1.0,
output_type="np",
return_dict=False,
)
encode_video(
video[0],
fps=frame_rate,
audio=audio[0].float().cpu(),
audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
output_path="ltx2_distilled_sample.mp4",
)Generación de Pipeline de Condición
Puede usar LTX2ConditionPipeline para especificar condiciones de imagen y/o vídeo en índices latentes arbitrarios. Por ejemplo, podemos especificar tanto una condición de primer fotograma como una de último fotograma para realizar la generación de primer-último-fotograma-a-vídeo (FLF2V):
import torch
from diffusers import LTX2ConditionPipeline, LTX2LatentUpsamplePipeline
from diffusers.models.latent_upscaler import LTX2LatentUpsamplerModel
from diffusers.pipelines.ltx2.pipeline_ltx2_condition import LTX2VideoCondition
from diffusers.pipelines.ltx2.utils import DISTILLED_SIGMA_VALUES, STAGE_2_DISTILLED_SIGMA_VALUES
from diffusers.utils import encode_video
from diffusers.utils import load_image
device = "cuda" # or "mps", "xpu", "cpu"
width = 768
height = 512
random_seed = 42
generator = torch.Generator(device).manual_seed(random_seed)
model_path = "rootonchair/LTX-2-19b-distilled"
pipe = LTX2ConditionPipeline.from_pretrained(model_path, dtype=torch.bfloat16)
pipe.enable_sequential_cpu_offload(device=device)
pipe.vae.enable_tiling()
prompt = (
"CG animation style, a small blue bird takes off from the ground, flapping its wings. The bird's feathers are "
"delicate, with a unique pattern on its chest. The background shows a blue sky with white clouds under bright "
"sunshine. The camera follows the bird upward, capturing its flight and the vastness of the sky from a close-up, "
"low-angle perspective."
)
first_image = load_image(
"https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/flf2v_input_first_frame.png",
)
last_image = load_image(
"https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/flf2v_input_last_frame.png",
)
first_cond = LTX2VideoCondition(frames=first_image, index=0, strength=1.0)
last_cond = LTX2VideoCondition(frames=last_image, index=-1, strength=1.0)
conditions = [first_cond, last_cond]
frame_rate = 24.0
video_latent, audio_latent = pipe(
conditions=conditions,
prompt=prompt,
width=width,
height=height,
num_frames=121,
frame_rate=frame_rate,
num_inference_steps=8,
sigmas=DISTILLED_SIGMA_VALUES,
guidance_scale=1.0,
generator=generator,
output_type="latent",
return_dict=False,
)
latent_upsampler = LTX2LatentUpsamplerModel.from_pretrained(
model_path,
subfolder="latent_upsampler",
dtype=torch.bfloat16,
)
upsample_pipe = LTX2LatentUpsamplePipeline(vae=pipe.vae, latent_upsampler=latent_upsampler)
upsample_pipe.enable_model_cpu_offload(device=device)
upscaled_video_latent = upsample_pipe(
latents=video_latent,
output_type="latent",
return_dict=False,
)[0]
video, audio = pipe(
latents=upscaled_video_latent,
audio_latents=audio_latent,
prompt=prompt,
width=width * 2,
height=height * 2,
num_inference_steps=3,
sigmas=STAGE_2_DISTILLED_SIGMA_VALUES,
generator=generator,
guidance_scale=1.0,
output_type="np",
return_dict=False,
)
encode_video(
video[0],
fps=frame_rate,
audio=audio[0].float().cpu(),
audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
output_path="ltx2_distilled_flf2v.mp4",
)Puedes usar tanto condiciones de imagen como de video:
import torch
from diffusers import LTX2ConditionPipeline
from diffusers.pipelines.ltx2.pipeline_ltx2_condition import LTX2VideoCondition
from diffusers.utils import encode_video
from diffusers.pipelines.ltx2.utils import DEFAULT_NEGATIVE_PROMPT
from diffusers.utils import load_image, load_video
device = "cuda" # or "mps", "xpu", "cpu"
width = 768
height = 512
random_seed = 42
generator = torch.Generator(device).manual_seed(random_seed)
model_path = "rootonchair/LTX-2-19b-distilled"
pipe = LTX2ConditionPipeline.from_pretrained(model_path, dtype=torch.bfloat16)
pipe.enable_sequential_cpu_offload(device=device)
pipe.vae.enable_tiling()
prompt = (
"The video depicts a long, straight highway stretching into the distance, flanked by metal guardrails. The road is "
"divided into multiple lanes, with a few vehicles visible in the far distance. The surrounding landscape features "
"dry, grassy fields on one side and rolling hills on the other. The sky is mostly clear with a few scattered "
"clouds, suggesting a bright, sunny day. And then the camera switch to a winding mountain road covered in snow, "
"with a single vehicle traveling along it. The road is flanked by steep, rocky cliffs and sparse vegetation. The "
"landscape is characterized by rugged terrain and a river visible in the distance. The scene captures the "
"solitude and beauty of a winter drive through a mountainous region."
)
cond_video = load_video(
"https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/cosmos/cosmos-video2world-input-vid.mp4"
)
cond_image = load_image(
"https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/cosmos/cosmos-video2world-input.jpg"
)
video_cond = LTX2VideoCondition(frames=cond_video, index=0, strength=1.0)
image_cond = LTX2VideoCondition(frames=cond_image, index=8, strength=1.0)
conditions = [video_cond, image_cond]
frame_rate = 24.0
video, audio = pipe(
conditions=conditions,
prompt=prompt,
negative_prompt=DEFAULT_NEGATIVE_PROMPT,
width=width,
height=height,
num_frames=121,
frame_rate=frame_rate,
num_inference_steps=30,
guidance_scale=3.0,
generator=generator,
output_type="np",
return_dict=False,
)
encode_video(
video[0],
fps=frame_rate,
audio=audio[0].float().cpu(),
audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
output_path="ltx2_cond_video.mp4",
)Dado que el condicionamiento se realiza mediante marcos latentes, los 8 marcos del espacio de datos correspondientes al marco latente especificado para una condición de imagen tenderán a ser estáticos.
Guía multimodal
Los pipelines de LTX-2.X admiten orientación multimodal. Está compuesta por tres términos, todos ellos que utilizan una regla de actualización de estilo CFG:
- Guía sin clasificador (CFG): CFG estándar donde la salida perturbada (“más débil”) se genera usando el prompt negativo.
- Guía espaciotemporal (STG): STG se aleja de una salida perturbada creada mediante el atajo de las operaciones de autoatención y, en su lugar, sustituye los valores de atención. La idea es que esto genera videos más nítidos y una mejor consistencia espaciotemporal.
- Guía de aislamiento de modalidades: se aleja de una salida perturbada creada al deshabilitar la atención cruzada entre modalidades (de audio a video y de video a audio). Esta guía es más específica para los modelos LTX-2.X, con la idea de que esto produce una mejor coherencia entre el audio y el video generados.
Estos se controlan mediante los argumentos guidance_scale, stg_scale y modality_scale y pueden configurarse por separado para video y audio. Además, para STG, es necesario especificar los índices de bloques del transformer donde se omite la autoatención mediante el argumento spatio_temporal_guidance_blocks. Los pipelines de LTX-2.X también admiten reescalado de guía para ayudar a reducir la sobreexposición, lo cual puede ser un problema cuando las escalas de guía se configuran con valores altos.
import torch
from diffusers import LTX2ImageToVideoPipeline
from diffusers.utils import encode_video
from diffusers.pipelines.ltx2.utils import DEFAULT_NEGATIVE_PROMPT
from diffusers.utils import load_image
device = "cuda" # or "mps", "xpu", "cpu"
width = 768
height = 512
random_seed = 42
frame_rate = 24.0
generator = torch.Generator(device).manual_seed(random_seed)
model_path = "diffusers/LTX-2.3-Diffusers"
pipe = LTX2ImageToVideoPipeline.from_pretrained(model_path, dtype=torch.bfloat16)
pipe.enable_sequential_cpu_offload(device=device)
pipe.vae.enable_tiling()
prompt = (
"An astronaut hatches from a fragile egg on the surface of the Moon, the shell cracking and peeling apart in "
"gentle low-gravity motion. Fine lunar dust lifts and drifts outward with each movement, floating in slow arcs "
"before settling back onto the ground. The astronaut pushes free in a deliberate, weightless motion, small "
"fragments of the egg tumbling and spinning through the air. In the background, the deep darkness of space subtly "
"shifts as stars glide with the camera's movement, emphasizing vast depth and scale. The camera performs a "
"smooth, cinematic slow push-in, with natural parallax between the foreground dust, the astronaut, and the "
"distant starfield. Ultra-realistic detail, physically accurate low-gravity motion, cinematic lighting, and a "
"breath-taking, movie-like shot."
)
image = load_image(
"https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg",
)
video, audio = pipe(
image=image,
prompt=prompt,
negative_prompt=DEFAULT_NEGATIVE_PROMPT,
width=width,
height=height,
num_frames=121,
frame_rate=frame_rate,
num_inference_steps=30,
guidance_scale=3.0, # Recommended LTX-2.3 guidance parameters
stg_scale=1.0, # Note that 0.0 (not 1.0) means that STG is disabled (all other guidance is disabled at 1.0)
modality_scale=3.0,
guidance_rescale=0.7,
audio_guidance_scale=7.0, # Note that a higher CFG guidance scale is recommended for audio
audio_stg_scale=1.0,
audio_modality_scale=3.0,
audio_guidance_rescale=0.7,
spatio_temporal_guidance_blocks=[28],
use_cross_timestep=True,
generator=generator,
output_type="np",
return_dict=False,
)
encode_video(
video[0],
fps=frame_rate,
audio=audio[0].float().cpu(),
audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
output_path="ltx2_3_i2v_stage_1.mp4",
)Mejora de prompts
Los modelos LTX-2.X son sensibles al estilo de indicación. Consulte la guía oficial de indicaciones para obtener recomendaciones sobre cómo escribir una buena indicación. El uso de la mejora de indicaciones, donde las indicaciones proporcionadas se mejoran mediante el codificador de texto de la canalización (por defecto, un modelo Gemma 3) dado un prompt de sistema, también puede mejorar la calidad de las muestras. El componente de canalización opcional processor debe estar presente para usar la mejora de indicaciones. Actívelo con enable_prompt_enhancement=True y un system_prompt (opcional, coincidente con las canalizaciones de referencia de Lightricks):
import torch
from transformers import Gemma3Processor
from diffusers import LTX2Pipeline
from diffusers.utils import encode_video
from diffusers.pipelines.ltx2.utils import DEFAULT_NEGATIVE_PROMPT, T2V_DEFAULT_SYSTEM_PROMPT
device = "cuda" # or "mps", "xpu", "cpu"
width = 768
height = 512
random_seed = 42
frame_rate = 24.0
generator = torch.Generator(device).manual_seed(random_seed)
model_path = "diffusers/LTX-2.3-Diffusers"
pipe = LTX2Pipeline.from_pretrained(model_path, dtype=torch.bfloat16)
pipe.enable_model_cpu_offload(device=device)
pipe.vae.enable_tiling()
if getattr(pipe, "processor", None) is None:
processor = Gemma3Processor.from_pretrained("google/gemma-3-12b-it-qat-q4_0-unquantized")
pipe.processor = processor
prompt = (
"An astronaut hatches from a fragile egg on the surface of the Moon, the shell cracking and peeling apart in "
"gentle low-gravity motion. Fine lunar dust lifts and drifts outward with each movement, floating in slow arcs "
"before settling back onto the ground. The astronaut pushes free in a deliberate, weightless motion, small "
"fragments of the egg tumbling and spinning through the air. In the background, the deep darkness of space subtly "
"shifts as stars glide with the camera's movement, emphasizing vast depth and scale. The camera performs a "
"smooth, cinematic slow push-in, with natural parallax between the foreground dust, the astronaut, and the "
"distant starfield. Ultra-realistic detail, physically accurate low-gravity motion, cinematic lighting, and a "
"breath-taking, movie-like shot."
)
video, audio = pipe(
prompt=prompt,
negative_prompt=DEFAULT_NEGATIVE_PROMPT,
width=width,
height=height,
num_frames=121,
frame_rate=frame_rate,
num_inference_steps=30,
guidance_scale=3.0,
stg_scale=1.0,
modality_scale=3.0,
guidance_rescale=0.7,
audio_guidance_scale=7.0,
audio_stg_scale=1.0,
audio_modality_scale=3.0,
audio_guidance_rescale=0.7,
spatio_temporal_guidance_blocks=[28],
use_cross_timestep=True,
enable_prompt_enhancement=True,
system_prompt=T2V_DEFAULT_SYSTEM_PROMPT,
generator=generator,
output_type="np",
return_dict=False,
)
encode_video(
video[0],
fps=frame_rate,
audio=audio[0].float().cpu(),
audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
output_path="ltx2_3_t2v_stage_1.mp4",
)LTX-2.5
LTX-2.5 reutiliza las mismas clases LTX2Pipeline/LTX2VideoTransformer3DModel/AutoencoderKLLTX2Video/etc. que LTX-2.3; no existe una clase de pipeline separada para él. La diferencia visible para el usuario es el codificador de texto: LTX-2.5 se empareja con un checkpoint de Gemma 4 (gemma4_unified) en lugar de Gemma 3. Esto se carga automáticamente cuando se llama a from_pretrained en un checkpoint de LTX-2.5 convertido (a través de las clases Auto* de transformers), por lo que no se necesita configuración adicional en el momento de la inferencia: basta con apuntar from_pretrained a un repositorio de LTX-2.5 en lugar de uno de LTX-2.3.
Lightricks/LTX-2.5-Diffusers incluye ambos transformers: el DiT destilado en transformer/, al que apunta model_index.json, y el DiT completo/SFT en transformer_full/, que debe cargarse explícitamente (ver Full / SFT transformer). El scheduler/ del repositorio está configurado para el checkpoint destilado (use_dynamic_shifting=False, shift_terminal=None) para que su programación de sigma se utilice exactamente como se indica. Todo lo que se necesita para la generación en dos etapas también se incluye allí: una subcarpeta latent_upsampler/ y el LoRA destilado de la etapa 2, ltx-2.5-22b-distilled-lora-450-bf16.safetensors, en la raíz del repositorio.
La inferencia destilada se rige por un programa de sigma explícito en lugar de un número de pasos, y se ejecuta sin guía (guidance_scale=1.0, por lo que negative_prompt no se utiliza). Si se pasa num_inference_steps en su lugar, se le proporciona al modelo un programa lineal genérico y se pierde calidad de forma silenciosa:
import torch
from diffusers import LTX2Pipeline
from diffusers.utils import encode_video
from diffusers.pipelines.ltx2.utils import DISTILLED_SIGMA_VALUES
device = "cuda" # or "mps", "xpu", "cpu"
width = 768
height = 512
random_seed = 42
frame_rate = 24.0
generator = torch.Generator(device).manual_seed(random_seed)
model_path = "Lightricks/LTX-2.5-Diffusers"
pipe = LTX2Pipeline.from_pretrained(model_path, dtype=torch.bfloat16)
pipe.enable_sequential_cpu_offload(device=device)
pipe.vae.enable_tiling()
prompt = "A cinematic shot of a red fox walking through a snowy forest at dawn, golden light filtering through pine trees."
video, audio = pipe(
prompt=prompt,
width=width,
height=height,
num_frames=121,
frame_rate=frame_rate,
sigmas=DISTILLED_SIGMA_VALUES,
guidance_scale=1.0,
audio_guidance_scale=1.0,
generator=generator,
output_type="np",
return_dict=False,
)
encode_video(
video[0],
fps=frame_rate,
audio=audio[0].float().cpu(),
audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
output_path="ltx2_5_t2v.mp4",
)Generación en dos etapas para LTX-2.5
LTX-2.5 admite ambas variantes de dos etapas, y DISTILLED_SIGMA_VALUES / STAGE_2_DISTILLED_SIGMA_VALUES son sus horarios de referencia:
- Punto de control destilado, ambas etapas — la receta de referencia para el
transformer/predeterminado, y la que se muestra a continuación. No se involucra ningún LoRA de la etapa 2, ya que el transformer ya está destilado; esto es Generación de punto de control destilado con los pesos de LTX-2.5. - Etapa 1 Full/SFT + etapa 2 LoRA destilado — Generación en dos etapas tal como se describe al inicio de esta página, utilizando
transformer_full/y el LoRA incluido. Consulte abajo para ver qué cambia.
La etapa 1 se ejecuta a la mitad de la resolución objetivo, el amplificador la duplica y la etapa 2 la refina a la resolución completa, tanto el video como el audio, ambos resembrados desde los latentes de la etapa 1 en noise_scale=STAGE_2_DISTILLED_SIGMA_VALUES[0]. La altura y el ancho deben ser divisibles entre 64, ya que la etapa 1 reduce cada eje a la mitad y aún debe alinearse con la cuadrícula espacial del VAE.
import torch
from diffusers.pipelines.ltx2 import LTX2Pipeline, LTX2LatentUpsamplePipeline
from diffusers.models.latent_upscaler import LTX2LatentUpsamplerModel
from diffusers.pipelines.ltx2.utils import DISTILLED_SIGMA_VALUES, STAGE_2_DISTILLED_SIGMA_VALUES
from diffusers.utils import encode_video
device = "cuda" # or "mps", "xpu", "cpu"
width = 1536
height = 1024
num_frames = 121
frame_rate = 24.0
model_path = "Lightricks/LTX-2.5-Diffusers"
# One generator for the whole call, threaded through both stages, so stage 2 continues the noise
# stream instead of repeating stage 1's draw.
generator = torch.Generator(device).manual_seed(42)
pipe = LTX2Pipeline.from_pretrained(model_path, dtype=torch.bfloat16)
pipe.enable_sequential_cpu_offload(device=device)
prompt = "A cinematic shot of a red fox walking through a snowy forest at dawn, golden light filtering through pine trees."
# Stage 1: half resolution, 8 distilled sigmas
video_latent, audio_latent = pipe(
prompt=prompt,
width=width // 2,
height=height // 2,
num_frames=num_frames,
frame_rate=frame_rate,
sigmas=DISTILLED_SIGMA_VALUES,
guidance_scale=1.0,
audio_guidance_scale=1.0,
generator=generator,
output_type="latent",
return_dict=False,
)
latent_upsampler = LTX2LatentUpsamplerModel.from_pretrained(
model_path,
subfolder="latent_upsampler",
dtype=torch.bfloat16,
)
upsample_pipe = LTX2LatentUpsamplePipeline(vae=pipe.vae, latent_upsampler=latent_upsampler)
upsample_pipe.enable_model_cpu_offload(device=device)
# `latents_normalized=False`: `output_type="latent"` already applied the latent statistics, and the
# upsampler is trained on denormalized latents. Stage 2 renormalizes them in `prepare_latents`.
upscaled_video_latent = upsample_pipe(
latents=video_latent,
latents_normalized=False,
output_type="latent",
return_dict=False,
)[0]
# Stage 2: full resolution, 3 sigmas, reseeded from stage 1. Pass `num_frames` explicitly here --
# omitting it would run the duration head a second time instead of using the stage 1 length.
pipe.vae.enable_tiling()
video, audio = pipe(
prompt=prompt,
latents=upscaled_video_latent,
audio_latents=audio_latent,
width=width,
height=height,
num_frames=num_frames,
frame_rate=frame_rate,
sigmas=STAGE_2_DISTILLED_SIGMA_VALUES,
noise_scale=STAGE_2_DISTILLED_SIGMA_VALUES[0], # renoise with the stage 2 entry sigma
guidance_scale=1.0,
audio_guidance_scale=1.0,
generator=generator,
output_type="np",
return_dict=False,
)
encode_video(
video[0],
fps=frame_rate,
audio=audio[0].float().cpu(),
audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
output_path="ltx2_5_t2v_two_stages.mp4",
)Cuando la longitud proviene de la cabecera de duración en lugar de un num_frames explícito, deja que la etapa 1 decida y recupere la longitud realizada a partir de sus latentes ([B, C, F, H, W]) antes de que se ejecute la etapa 2, en lugar de predecirla una segunda vez:
num_frames = (video_latent.shape[2] - 1) * pipe.vae_temporal_compression_ratio + 1Etapa 2 con el LoRA destilado
Para ejecutar Two-stages Generation en su lugar — DiT full/SFT para la etapa 1 y LoRA destilado para la etapa 2 —, construya el pipeline como en Full / SFT transformer y genere los latentes de la etapa 1 con esa pila de guía. A continuación, dos cosas difieren de LTX-2.0/2.3. El LoRA se encuentra en el propio repositorio de diffusers, en lugar de junto a los pesos originales, y la inversión del scheduler va en sentido contrario: LTX-2.5 incluye la configuración del scheduler distilled, por lo que la etapa 1 es la que activó el desplazamiento dinámico, y la etapa 2 lo vuelve a desactivar.
pipe.load_lora_weights(
"Lightricks/LTX-2.5-Diffusers",
adapter_name="stage_2_distilled",
weight_name="ltx-2.5-22b-distilled-lora-450-bf16.safetensors",
)
pipe.set_adapters("stage_2_distilled", 1.0)
pipe.vae.enable_tiling()
pipe.scheduler = FlowMatchEulerDiscreteScheduler.from_config(
pipe.scheduler.config, use_dynamic_shifting=False, shift_terminal=None
)El paso de upsample y la llamada de la etapa 2 no cambian respecto a la receta destilada anterior: mismo sigmas=STAGE_2_DISTILLED_SIGMA_VALUES, mismo noise_scale y guidance_scale=1.0, ya que la etapa 2 está ejecutando un modelo destilado de todos modos.
Decodificación convolucional y de difusión
LTX-2.5 incluye dos decodificadores de video sobre el mismo espacio latente, por lo que los latentes son intercambiables entre ellos:
vae/— el VAE convolucional (AutoencoderKLLTX2Video). Es el componente con el que las pipelines decodifican, por lo que todos los fragmentos anteriores ya lo utilizan, y es el único de los dos que admite mosaicos (pipe.vae.enable_tiling()), lo que normalmente permite que una resolución alta quepa en la memoria.diffusion_decoder/— LTX2VideoDiffusionDecoderModel. Es un modelo de difusión en sí mismo y no un componente de la pipeline, por lo que no se pasa comovae: ejecute la pipeline conoutput_type="latent"y pase los latentes a LTX2VideoDiffusionDecodePipeline.
La codificación siempre pasa por vae/, por lo que la condicional de imagen y vídeo no se ve afectada por la elección.
Dos cosas cambian al decodificar con el decodificador de difusión. output_type="latent" también omite el vocoder, por lo que el audio se devuelve como latentes y debe completarse manualmente, y el procesador NATTEN es prácticamente obligatorio en resoluciones de video:
import torch
from diffusers import LTX2Pipeline, LTX2VideoDiffusionDecodePipeline, LTX2VideoDiffusionDecoderModel
from diffusers.models.autoencoders.ltx2_diffusion_decoder import LTX2VideoVaeNeighborhoodNattenProcessor
from diffusers.pipelines.ltx2.utils import DISTILLED_SIGMA_VALUES
from diffusers.utils import encode_video
device = "cuda" # or "mps", "xpu", "cpu"
frame_rate = 24.0
generator = torch.Generator(device).manual_seed(42)
model_path = "Lightricks/LTX-2.5-Diffusers"
pipe = LTX2Pipeline.from_pretrained(model_path, dtype=torch.bfloat16)
pipe.enable_model_cpu_offload(device=device)
prompt = "A cinematic shot of a red fox walking through a snowy forest at dawn, golden light filtering through pine trees."
latents, audio_latents = pipe(
prompt=prompt,
width=960,
height=544,
num_frames=121,
frame_rate=frame_rate,
sigmas=DISTILLED_SIGMA_VALUES,
guidance_scale=1.0,
audio_guidance_scale=1.0,
generator=generator,
output_type="latent",
return_dict=False,
)
# `output_type="latent"` skips the vocoder, so finish the audio by hand. These latents are already
# denormalized, which is what `audio_vae.decode` expects.
mel = pipe.audio_vae.decode(audio_latents.to(pipe.audio_vae.dtype), return_dict=False)[0]
audio = pipe.vocoder(mel)
decoder = LTX2VideoDiffusionDecoderModel.from_pretrained(
model_path, subfolder="diffusion_decoder", dtype=torch.bfloat16
).to(device)
# The decoder runs on the `flex` backend by default, and uncompiled `flex_attention` materializes the
# full score matrix -- tens of GB at video resolutions. NATTEN's kernels are what the original
# implementation uses; they are fetched from the Hub by `kernels` (`pip install kernels`), not from a
# local NATTEN build. Switching the attention *backend* instead raises: only `flex` takes the BlockMask.
decoder.set_attn_processor(LTX2VideoVaeNeighborhoodNattenProcessor())
# Decode in overlapping tiles so peak memory scales with the tile size rather than the video size.
decoder.enable_tiling()
decode_pipe = LTX2VideoDiffusionDecodePipeline(diffusion_decoder=decoder, scheduler=pipe.scheduler)
# `denormalize=False`: `output_type="latent"` already applied the latent statistics, so applying them
# again would rescale every channel by its std a second time. The decoder draws the noise it denoises,
# so pass a generator to make decoding reproducible.
video = decode_pipe(
latents, generator=generator, output_type="np", denormalize=False, return_dict=False
)[0]
encode_video(
video[0],
fps=frame_rate,
audio=audio[0].float().cpu(),
audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
output_path="ltx2_5_t2v_diffusion_decode.mp4",
)Para combinar esto con generación en dos etapas, solicite a etapa 2 que devuelva output_type="latent" y decodifíquelo.
decoder.enable_tiling() es lo que mantiene la decodificación de alta resolución en memoria, de la misma manera que pipe.vae.enable_tiling() lo hace para el VAE convolucional. La parte dominante en memoria de la decodificación, que es la última etapa de remuestreo ascendente y la etapa de difusión, se ejecuta entonces en mosaicos superpuestos que se combinan nuevamente, de modo que la memoria pico está acotada por el tamaño del mosaico en lugar del tamaño del video. El mosaico solo se activa una vez que el latente supera un mosaico, y los tamaños de mosaico y superposición se pueden ajustar mediante los argumentos tile_sample_min_* / tile_sample_stride_* (los valores predeterminados coinciden con la implementación de referencia). Dado que la etapa de difusión elimina el ruido de cada mosaico por separado, una decodificación con mosaicos no reproduce exactamente el resultado sin mosaicos.
En una sola tarjeta, también conviene mover el pipeline fuera del camino antes de la decodificación (pipe.to("cpu") y torch.cuda.empty_cache(), después de capturar pipe.scheduler y la output_sampling_rate del vocoder), ya que el decodificador necesita su propio margen. Consulte LTX2VideoDiffusionDecoderModel para los backends de atención, los detalles de teselado y el resto del comportamiento del decodificador.
Transformador completo / SFT
transformer_full/ no se referencia en model_index.json, por lo que debe cargarse explícitamente. También requiere un scheduler diferente y una pila de guía real: el scheduler/ incluido está configurado para el checkpoint destilado, y los valores predeterminados de guía son genéricos de la era de LTX-2.0 que dejan una ejecución SFT de LTX-2.5 visiblemente subguiada sin generar ninguna advertencia. Las recomendaciones de Multimodal Guidance se aplican aquí sin cambios, incluida la STG en el bloque 28:
import torch
from diffusers import FlowMatchEulerDiscreteScheduler, LTX2Pipeline, LTX2VideoTransformer3DModel
from diffusers.pipelines.ltx2.utils import DEFAULT_NEGATIVE_PROMPT
device = "cuda" # or "mps", "xpu", "cpu"
model_path = "Lightricks/LTX-2.5-Diffusers"
# Passing `transformer=` keeps `from_pretrained` from fetching the distilled folder as well.
transformer = LTX2VideoTransformer3DModel.from_pretrained(
model_path, subfolder="transformer_full", dtype=torch.bfloat16
)
pipe = LTX2Pipeline.from_pretrained(model_path, transformer=transformer, dtype=torch.bfloat16)
pipe.enable_sequential_cpu_offload(device=device)
pipe.vae.enable_tiling()
# Re-enable dynamic shifting and the terminal shift, which the distilled configuration turns off.
pipe.scheduler = FlowMatchEulerDiscreteScheduler.from_config(
pipe.scheduler.config, use_dynamic_shifting=True, shift_terminal=0.1
)
video, audio = pipe(
prompt="A cinematic shot of a red fox walking through a snowy forest at dawn, golden light filtering through pine trees.",
negative_prompt=DEFAULT_NEGATIVE_PROMPT,
width=768,
height=512,
num_frames=121,
frame_rate=24.0,
num_inference_steps=30,
guidance_scale=3.0,
stg_scale=1.0,
modality_scale=3.0,
guidance_rescale=0.7,
audio_guidance_scale=7.0,
audio_stg_scale=1.0,
audio_modality_scale=3.0,
audio_guidance_rescale=0.7,
spatio_temporal_guidance_blocks=[28],
use_cross_timestep=True,
generator=torch.Generator(device).manual_seed(42),
output_type="np",
return_dict=False,
)Deja sigmas aquí: el DiT completo toma su programación del scheduler.
Mejora de prompts para LTX-2.5
Se recomienda encarecidamente el uso de mejora de prompt para LTX-2.5; pase enable_prompt_enhancement=True para activarlo (igual que en las pipelines de referencia de Lightricks). A diferencia de LTX-2.0/2.3, donde el mismo checkpoint del codificador de texto también actúa como mejorador (ver Mejora de prompt arriba), el codificador de texto afinado de LTX-2.5 no fue entrenado para la mejora. En su lugar, la mejora utiliza un checkpoint independiente y listo para usar de google/gemma-4-E2B-it. Cargue este en los componentes opcionales prompt_enhancer/processor de la pipeline y luego active la mejora: la pipeline usa por defecto LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT y la receta de Gemma 4 (do_sample=False, no_repeat_ngram_size=5, max_new_tokens=600). Pase un system_prompt= explícito para sobrescribirlo:
import torch
from transformers import AutoModelForImageTextToText, AutoProcessor
from diffusers import LTX2Pipeline
from diffusers.utils import encode_video
from diffusers.pipelines.ltx2.utils import DISTILLED_SIGMA_VALUES
device = "cuda" # or "mps", "xpu", "cpu"
width = 768
height = 512
random_seed = 42
frame_rate = 24.0
generator = torch.Generator(device).manual_seed(random_seed)
model_path = "Lightricks/LTX-2.5-Diffusers"
enhancer_model_id = "google/gemma-4-E2B-it"
pipe = LTX2Pipeline.from_pretrained(model_path, dtype=torch.bfloat16)
pipe.enable_model_cpu_offload(device=device)
pipe.vae.enable_tiling()
if getattr(pipe, "prompt_enhancer", None) is None:
pipe.prompt_enhancer = AutoModelForImageTextToText.from_pretrained(enhancer_model_id)
pipe.processor = AutoProcessor.from_pretrained(enhancer_model_id)
prompt = "A cinematic shot of a red fox walking through a snowy forest at dawn, golden light filtering through pine trees."
video, audio = pipe(
prompt=prompt,
width=width,
height=height,
num_frames=121,
frame_rate=frame_rate,
sigmas=DISTILLED_SIGMA_VALUES,
guidance_scale=1.0,
audio_guidance_scale=1.0,
enable_prompt_enhancement=True,
# No `system_prompt=` needed -- defaults to `LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT` when `prompt_enhancer` is set.
generator=generator,
output_type="np",
return_dict=False,
)
encode_video(
video[0],
fps=frame_rate,
audio=audio[0].float().cpu(),
audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
output_path="ltx2_5_t2v_enhanced.mp4",
)Lo mismo aplica para image-to-video con LTX2ImageToVideoPipeline: configura pipe.prompt_enhancer/pipe.processor de la misma manera y pasa enable_prompt_enhancement=True (usando LTX2_5_I2V_DEFAULT_SYSTEM_PROMPT, condicionando tanto en la imagen de referencia como en el prompt de texto) — de nuevo, no se necesita system_prompt= a menos que quieras sobrescribirlo.
Duración automática para LTX-2.5
Los checkpoints de LTX-2.5 incluyen un pequeño duration_head que predice cuánto tiempo debe durar el plano descrito, a partir de la misma salida del conector de texto en la que se condiciona el transformer. Cuando el pipeline cargado tiene uno, num_frames se predice automáticamente de forma predeterminada: omítelo y el modelo elegirá la duración.
video, audio = pipe(prompt=prompt, output_type="np", return_dict=False)Para establecer la longitud manualmente, pase num_frames de forma explícita. Un entero siempre tiene prioridad sobre la cabecera:
video, audio = pipe(prompt=prompt, num_frames=121, output_type="np", return_dict=False)Los pipelines cargados desde puntos de control de LTX-2.0 o LTX-2.3 no tienen una cabeza de duración y mantienen el valor predeterminado anterior de 121 fotogramas, por lo que esto no cambia nada para ellos.
Pase min_seconds / max_seconds para restringir la predicción. La predicción cruda se limita al rango y luego se convierte en fotogramas:
video, audio = pipe(
prompt=prompt,
min_seconds=2.0,
max_seconds=10.0,
frame_rate=frame_rate,
output_type="np",
return_dict=False,
)Las cantidades de fotogramas predichas se ajustan a la cuadrícula temporal causal del VAE (8k + 1), por lo que la duración realizada está cuantizada —aproximadamente 0,33 s por paso a 24 fps— y varía con frame_rate, ya que la cabecera predice segundos en lugar de fotogramas. min_seconds debe ser estrictamente menor que max_seconds. Estos límites se ignoran cuando num_frames se establece explícitamente.
Los límites más estrechos que un paso de la cuadrícula pueden no ser satisfactibles exactamente: a 24 fps, [1.0s, 1.02s] se convierte en [24, 24] fotogramas, y 24 no es 8k + 1. Se utiliza el punto de la cuadrícula más cercano y se registra una advertencia, por lo que la longitud devuelta puede caer justo fuera de límites tan estrictos.
Para inspeccionar una predicción sin generar un video, llama directamente a la cabeza. Todo lo que necesita es público:
prompt_embeds, prompt_attention_mask, _, _ = pipe.encode_prompt(prompt, do_classifier_free_guidance=False)
video_tokens, audio_tokens, _ = pipe.connectors(prompt_embeds, prompt_attention_mask)
num_frames = pipe.duration_head.predict_num_frames(
video_tokens,
audio_tokens,
frame_rate=24.0,
temporal_compression_ratio=pipe.vae_temporal_compression_ratio,
)
seconds = pipe.duration_head(video_tokens, audio_tokens).item() # raw, before clamping
print(f"predicted {seconds:.2f}s -> {num_frames} frames")Al convertir un checkpoint de 2.5, la cabeza se selecciona automáticamente con --full_pipeline, o por separado con --duration_head. Los checkpoints anteriores a 2.5 no tienen dichos pesos, y la conversión omite el componente en lugar de fallar.
Velocidad de movimiento para LTX-2.5
LTX-2 coloca cada token de video en un eje temporal en segundos, derivado por defecto de frame_rate, la tasa de reproducción. motion_speed (valor predeterminado 1.0) separa ambos: el eje temporal se condiciona en frame_rate / motion_speed, mientras que la duración del audio, el duration head y el video devuelto siguen frame_rate. Con frame_rate=24.0 y motion_speed=0.2, se indica al modelo que la acción fue capturada a 120 fps y el resultado se reproduce a 24 fps, lo que produce un cámara lenta de 5x.
El modelo base se entrena a velocidades de aproximadamente 24/25/30/60 fps, por lo que velocidades muy alejadas de 1.0 solo tienen sentido con un adaptador entrenado para ellas, como Lightricks/LTX-2.5-22b-LoRA-Slow-Motion-Control (con acceso restringido: primero debe aceptar su licencia en el Hub). Sin motion_speed, ese LoRA se carga como un LoRA normal y no proporciona ningún control de movimiento. La tarjeta del modelo sugiere velocidades de 1.0, 0.5, 0.2, 0.1, 0.05 y 0.025, con una intensidad de LoRA de 1.0. Omita las palabras relacionadas con la velocidad (“slow motion”, “high fps”) en el prompt y reutilice la misma descripción para todas las velocidades, ya que motion_speed por sí solo controla el efecto.
import torch
from diffusers import LTX2ImageToVideoPipeline
from diffusers.pipelines.ltx2.utils import DISTILLED_SIGMA_VALUES
from diffusers.utils import encode_video, load_image
device = "cuda" # or "mps", "xpu", "cpu"
width = 1920 # the LoRA's recommended resolution; the effect is much weaker at 768x512
height = 1088
frame_rate = 24.0 # playback rate, always 24 for this LoRA
model_path = "Lightricks/LTX-2.5-Diffusers"
pipe = LTX2ImageToVideoPipeline.from_pretrained(model_path, dtype=torch.bfloat16)
pipe.load_lora_weights(
"Lightricks/LTX-2.5-22b-LoRA-Slow-Motion-Control",
weight_name="ltx-2.5-22b-lora-slow-motion-control-1.0.safetensors",
adapter_name="slow_motion",
)
pipe.set_adapters("slow_motion", 1.0)
pipe.enable_sequential_cpu_offload(device=device)
pipe.vae.enable_tiling()
image = load_image(
"https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg"
)
# No speed wording: the same caption is reused at every speed.
prompt = (
"An astronaut hatches from a fragile egg on the surface of the Moon, the shell cracking apart and lunar dust "
"lifting into the air, while the camera pushes in."
)
for motion_speed in (1.0, 0.2):
video, audio = pipe(
image=image,
prompt=prompt,
width=width,
height=height,
num_frames=121,
frame_rate=frame_rate,
motion_speed=motion_speed, # 1.0 = real time, 0.2 = 5x slow motion
sigmas=DISTILLED_SIGMA_VALUES,
guidance_scale=1.0,
audio_guidance_scale=1.0,
generator=torch.Generator(device).manual_seed(42),
output_type="np",
return_dict=False,
)
encode_video(
video[0],
fps=frame_rate, # the file plays at the playback rate, not frame_rate / motion_speed
audio=audio[0].float().cpu(),
audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
output_path=f"ltx2_5_i2v_motion_speed_{motion_speed}.mp4",
)Ambos clips duran 121 fotogramas (aproximadamente 5 segundos a 24 fps) y solo cambia el ritmo del movimiento. En la generación en dos etapas, pase el mismo motion_speed a ambas etapas. La etapa 2 vuelve a desruidar el video y revertiría la cámara lenta si se ejecutara en el eje de tiempo real. El controlador de referencia hace lo mismo envolviendo el objeto de etapa que comparten ambas pasadas.
motion_speed también es una entrada de los bloques modulares de LTX-2 / LTX-2.5, y se pasa al pipeline modular de la misma manera.
LTX-2.5 Modular
LTX-2.5 también está disponible como pipeline modular. El conjunto de bloques predeterminado utiliza el decodificador de difusión y predice la duración del video cuando se omite num_frames. Aplica la guía de forma separada al video y al audio a través de los componentes guider y audio_guider. Consulte LTX2Guidance para conocer los parámetros de guía disponibles. De forma predeterminada, el pipeline modular descargará el mejorador y el procesador de prompts del repositorio google/gemma-4-E2B-it. A continuación se muestra un ejemplo modular de T2V:
import torch
from diffusers import ModularPipeline, ComponentsManager
from diffusers.models.autoencoders.ltx2_diffusion_decoder import LTX2VideoVaeNeighborhoodNattenProcessor
from diffusers.pipelines.ltx2.utils import DEFAULT_NEGATIVE_PROMPT
from diffusers.utils import encode_video
device = "cuda" # or "mps", "xpu", "cpu"
frame_rate = 24.0
random_seed = 42
generator = torch.Generator(device).manual_seed(random_seed)
model_path = "Lightricks/LTX-2.5-Diffusers"
cm = ComponentsManager()
pipe = ModularPipeline.from_pretrained(model_path, components_manager=cm)
pipe.load_components(dtype=torch.bfloat16)
# Set memory_reserve_margin higher to more aggressively offload component models
cm.enable_auto_cpu_offload(device=device, memory_reserve_margin="20GB")
# The NATTEN processor works if `kernels` is available (`pip install kernels`)
# Otherwise omit the below line to use the Flex Attention processor
pipe.diffusion_decoder.set_attn_processor(LTX2VideoVaeNeighborhoodNattenProcessor())
pipe.diffusion_decoder.enable_tiling()
prompt = (
"A cinematic shot of a red fox walking through a snowy forest at dawn, golden light filtering through pine trees."
)
output_state = pipe(
prompt=prompt,
negative_prompt=DEFAULT_NEGATIVE_PROMPT,
width=768,
height=512,
num_frames=None, # Set to an int (e.g. 121) to specify a fixed video length
frame_rate=frame_rate,
num_inference_steps=30,
use_cross_timestep=True,
enable_prompt_enhancement=True,
generator=generator,
output_type="np",
)
video = output_state.get("videos")
audio = output_state.get("audio")
encode_video(
video[0],
fps=frame_rate,
audio=audio[0].float().cpu(),
audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
output_path="ltx2_5_modular_t2v.mp4",
)El pipeline modular cambiará automáticamente los flujos de trabajo según las entradas proporcionadas. Por ejemplo, si se proporciona image, se utilizará un flujo de trabajo I2V:
import torch
from diffusers import ModularPipeline, ComponentsManager
from diffusers.models.autoencoders.ltx2_diffusion_decoder import LTX2VideoVaeNeighborhoodNattenProcessor
from diffusers.pipelines.ltx2.utils import DEFAULT_NEGATIVE_PROMPT
from diffusers.utils import encode_video, load_image
device = "cuda" # or "mps", "xpu", "cpu"
frame_rate = 24.0
random_seed = 42
generator = torch.Generator(device).manual_seed(random_seed)
model_path = "Lightricks/LTX-2.5-Diffusers"
cm = ComponentsManager()
pipe = ModularPipeline.from_pretrained(model_path, components_manager=cm)
pipe.load_components(dtype=torch.bfloat16)
cm.enable_auto_cpu_offload(device=device, memory_reserve_margin="20GB")
pipe.diffusion_decoder.set_attn_processor(LTX2VideoVaeNeighborhoodNattenProcessor())
pipe.diffusion_decoder.enable_tiling()
prompt = (
"An astronaut hatches from a fragile egg on the surface of the Moon, the shell cracking and peeling apart in "
"gentle low-gravity motion."
)
image_path = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg"
image = load_image(image_path)
output_state = pipe(
image=image,
prompt=prompt,
negative_prompt=DEFAULT_NEGATIVE_PROMPT,
width=768,
height=512,
num_frames=None, # Set to an int (e.g. 121) to specify a fixed video length
frame_rate=frame_rate,
num_inference_steps=30,
use_cross_timestep=True,
enable_prompt_enhancement=True,
generator=generator,
output_type="np",
)
video = output_state.get("videos")
audio = output_state.get("audio")
encode_video(
video[0],
fps=frame_rate,
audio=audio[0].float().cpu(),
audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
output_path="ltx2_5_modular_i2v.mp4",
)Puedes ver los flujos de trabajo admitidos en la documentación de cada blockset (p. ej., LTX2AutoBlocks, LTX25AutoBlocks).
Diffusion Fidelity Rendering (DFR) para LTX-2.5
LTX2DFRPipeline intercambia el tiempo real por la fidelidad del detalle. Cada __call__ es una pasada de desruido a height × width: genera video junto con ranuras de fotogramas clave adicionales de un solo píxel, o vuelve a desruidiar los latentes proporcionados sembrados desde esas ranuras. Los llamadores componen las etapas de la misma manera que en otros pipelines de dos etapas de LTX: este pipeline, LTX2LatentUpsamplePipeline, este pipeline de nuevo y luego LTX2DFRTemporalRefinePipeline para cada ronda temporal.
Un slot cuesta un marco latente completo de tokens para comprar un marco de píxeles, lo que relaja la compresión temporal efectiva en esa posición: el video circundante se condiciona en marcos genuinamente nuevos en lugar de interpolados. Las posiciones de los slots provienen de una cuadrícula de segmentos alineada con el borde temporal del VAE (24 o 32 marcos de píxeles, el que menos rellene la solicitud). El lienzo se rellena internamente hasta un número entero de segmentos; output_type="latent" devuelve esa cuadrícula rellena para que un slot en el relleno no se descarte. Recorta con trim_canvas antes de la decodificación del VAE.
Esto requiere un transformer cuya configuración establezca use_keyframes_abs_pos_embedding, que marca los latentes de marcos de un solo píxel con un embedding aprendido. Los checkpoints de LTX-2.5 lo incluyen; el pipeline lanza una excepción para cualquier versión anterior en lugar de gastar el presupuesto de tokens en tokens que no puede interpretar.
Presupuestar los tokens adicionales: cada slot añade el equivalente a un marco latente, por lo que la etapa 2 ejecuta una secuencia más larga que el paso destilado de dos etapas equivalente: +31% a 1024x1536 / 121 marcos (24576 -> 32256 tokens, 5 slots en una cuadrícula de segmentos de 24 marcos). La memoria de activación pico escala con esto, por lo que una resolución que apenas quepa con la receta destilada estándar puede requerir enable_sequential_cpu_offload, vae.enable_tiling() o un lienzo más pequeño bajo DFR.
La composición utiliza return_dict=True para keyframes y keyframe_positions (return_dict=False devuelve los mismos cuatro campos como una tupla).
La receta completa a continuación es la que conviene usar como punto de partida: imagen a video de 1088×1920, una ronda de refinamiento temporal x2 y el IC-LoRA de detallado espacial x2 en la etapa 2.
import torch
from diffusers import (
LTX2DFRPipeline,
LTX2DFRTemporalRefinePipeline,
LTX2LatentUpsamplePipeline,
LTXEulerAncestralRFScheduler,
)
from diffusers.models.latent_upscaler import LTX2LatentUpsamplerModel
from diffusers.pipelines.ltx2.utils import trim_canvas
from diffusers.pipelines.ltx2.pipeline_ltx2_condition import LTX2VideoCondition
from diffusers.pipelines.ltx2.utils import STAGE_2_DISTILLED_SIGMA_VALUES
from diffusers.utils import encode_video, load_image
pipe = LTX2DFRPipeline.from_pretrained("Lightricks/LTX-2.5-Diffusers", torch_dtype=torch.bfloat16)
latent_upsampler = LTX2LatentUpsamplerModel.from_pretrained(
"Lightricks/LTX-2.5-Diffusers", subfolder="latent_upsampler", torch_dtype=torch.bfloat16
)
# The x2 temporal upsampler is not in the published `model_index.json` — convert it with
# `--temporal_latent_upsampler`.
temporal_latent_upsampler = LTX2LatentUpsamplerModel.from_pretrained(
"path/to/converted/temporal_latent_upsampler", torch_dtype=torch.bfloat16
)
upsample_pipe = LTX2LatentUpsamplePipeline(vae=pipe.vae, latent_upsampler=latent_upsampler)
temporal_pipe = LTX2DFRTemporalRefinePipeline(
scheduler=LTXEulerAncestralRFScheduler(eta=0.5),
vae=pipe.vae,
audio_vae=pipe.audio_vae,
text_encoder=pipe.text_encoder,
tokenizer=pipe.tokenizer,
connectors=pipe.connectors,
transformer=pipe.transformer,
vocoder=pipe.vocoder,
temporal_latent_upsampler=temporal_latent_upsampler,
)
# All three pipelines share the same components, so place them together. Do not call
# `enable_model_cpu_offload()` on one of them: its hooks would own modules the other two also call,
# and `temporal_latent_upsampler` — held only by `temporal_pipe` — would never reach the device.
pipe.to("cuda")
upsample_pipe.to("cuda")
temporal_pipe.to("cuda")
image = load_image("https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/cat.png")
prompt = "A tabby cat stretching in a sunlit window, dust motes drifting in the light"
conditions = [LTX2VideoCondition(frames=image, index=0, strength=1.0)]
height, width = 1088, 1920
frame_rate = 24.0
generator = torch.Generator(device="cuda").manual_seed(0)
num_frames = 121
out = pipe(
prompt=prompt,
conditions=conditions,
height=height // 2,
width=width // 2,
num_frames=num_frames,
frame_rate=frame_rate,
generator=generator,
output_type="latent",
)
up_video = upsample_pipe(latents=out.frames, output_type="latent", return_dict=False)[0]
up_keyframes = upsample_pipe(latents=out.keyframes, output_type="latent", return_dict=False)[0]
# Load after stage 1 so the adapter is never disabled. `set_adapters` does not re-enable a
# transformer that already had `disable_adapters()` called on it.
pipe.load_lora_weights("Lightricks/LTX-2.5-22b-IC-LoRA-Pixel-Spatial-Upscaler", adapter_name="detailing")
pipe.set_adapters(["detailing"], adapter_weights=[0.5])
out2 = pipe(
prompt=prompt,
conditions=conditions,
latents=up_video,
audio_latents=out.audio,
keyframes_latents=up_keyframes,
keyframe_positions=out.keyframe_positions,
reference_latents=out.frames,
height=height,
width=width,
num_frames=num_frames,
frame_rate=frame_rate,
noise_scale=STAGE_2_DISTILLED_SIGMA_VALUES[0],
sigmas=STAGE_2_DISTILLED_SIGMA_VALUES,
generator=generator,
output_type="latent",
)
pipe.transformer.disable_adapters()
# `num_frames` here is the *padded* canvas the latents actually cover, which `resolve_canvas` may have
# grown past the 121 that were asked for. `condition_num_frames` stays the original request so a
# negative `condition.index` does not wrap onto the pad.
ratio = pipe.vae.temporal_compression_ratio
canvas_frames = (out2.frames.shape[2] - 1) * ratio + 1
out3 = temporal_pipe(
latents=out2.frames,
keyframes_latents=out2.keyframes,
keyframe_positions=out2.keyframe_positions,
audio_latents=out.audio,
prompt=prompt,
conditions=conditions,
height=height,
width=width,
num_frames=canvas_frames,
frame_rate=frame_rate,
source_seconds=canvas_frames / frame_rate,
condition_num_frames=num_frames,
generator=generator,
output_type="latent",
)
# Keep the padded canvas until decode so a slot on the pad is not dropped. `trim_canvas` counts *pixel*
# frames, and the round mapped `N -> 2 (N - 1) + 1`.
playback_fps = frame_rate * 2
requested_frames = (num_frames - 1) * 2 + 1
video_latents = trim_canvas(out3.frames, requested_frames, ratio)
timestep = None
if pipe.vae.config.timestep_conditioning:
timestep = torch.zeros(video_latents.shape[0], device=video_latents.device, dtype=pipe.vae.dtype)
video = pipe.vae.decode(video_latents.to(pipe.vae.dtype), timestep, return_dict=False)[0]
video = pipe.video_processor.postprocess_video(video, output_type="np")
# Audio is stage 1's. Cut it to the video's duration so a muxed container does not outlast the picture.
audio = pipe.vocoder(pipe.audio_vae.decode(out.audio.to(pipe.audio_vae.dtype), return_dict=False)[0])
audio_samples = round(requested_frames / playback_fps * pipe.vocoder.config.output_sampling_rate)
audio = audio[..., : min(audio.shape[-1], audio_samples)]
encode_video(
video[0],
fps=playback_fps,
audio=audio[0].float().cpu(),
audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
output_path="ltx2_5_dfr.mp4",
)height y width son de este paso, no de la salida final. La etapa 1 se ejecuta a la mitad del lienzo de 1080p (544×960); la etapa 2, a 1088×1920. Cada una debe ser divisible por la ratio de compresión espacial del VAE (32 en LTX-2.5 para un solo paso; 64 cuando la etapa 1 es la mitad de 1080p). Por eso 1080p es 1920×1088 y 4K es 3840×2176. Cada paso ejecuta un plan destilado fijo (sigmas), por lo que no hay num_inference_steps; los planes destilados se entrenan sin guía, por lo que tampoco hay negative_prompt ni guidance_scale. El audio incluido es el de la etapa 1: los pasos posteriores siguen ejecutando un flujo de audio para que la rama de vídeo tenga atención multimodal; la propia forma de onda no se refina después de la etapa 1.
Spatial detailing. Load the 2x spatial detailing IC-LoRA under a named adapter after stage 1 and activate it for stage 2 only (set_adapters(["detailing"], adapter_weights=[0.5])). Stage 2 then attends to the stage-1 half-resolution latent as reference_latents. Stage 1 and the temporal rounds run with the adapter off. If you load the LoRA before stage 1, transformer.disable_adapters() turns it off, and set_adapters does not turn it back on — call transformer.enable_adapters() before stage 2, or load the weights after stage 1 as in the recipe. reference_downscale_factor (default 2) scales the reference tokens’ spatial coordinates into the target’s coordinate space.
Refinamiento temporal. LTX2DFRTemporalRefinePipeline es una sola ronda: remuestreo temporal, teselado en las costuras de los fotogramas clave, desruido ancestral con LTXEulerAncestralRFScheduler (eta=0.5), costura eliminando la entrada del tesel posterior y fusión de la bolsa de fotogramas clave de arrastre. Construya ese programador usted mismo: la ronda se rechaza con cualquier otro, ya que un paso determinista se ejecutaría hasta el final y solo devolvería un lienzo más suave. Llame al pipeline una vez por ronda; itere para 2x / 4x, pasando round_index. Después de una ronda, keyframe_positions no puede volver a derivarse del num_frames original y debe pasarse tal cual. A cada tesel se le entrega la porción del audio de la etapa 1 congelada que cubre su propia ventana de reproducción. source_seconds es la duración de la etapa 1 y permanece fija entre rondas, por lo que las rondas posteriores deben pasarlo explícitamente en lugar de tomar el valor predeterminado.
El fps de condicionamiento es 60 siempre que la reproducción supere los 30, independientemente del multiplexado: el tiempo de RoPE es pixel_frame / fps, por lo que una base temporal de 120 fps reduciría a la mitad la extensión temporal de cada token en comparación con la distribución de entrenamiento, y 48 fps la estiraría. Ambos mienten al afirmar que son 60 y tratan los cuadros decodificados a la tasa de reproducción.
Una tercera etapa espacial. Compónla; no existe una cuarta canalización. Realiza el aumento de resolución espacial solo del video, reconstruye los fotogramas clave de carry en RGB (decode → Lanczos ×2 → encode mediante rebuild_epilogue_keyframes(); nunca aumentes la resolución latente de los fotogramas clave del epílogo), y luego:
from diffusers.pipelines.ltx2.dfr_layout import epilogue_tiles, pixel_to_latent_index
# One more doubling on top of the recipe above, so every stage below the output halves again:
# `epilogue_height` must be divisible by 128 (`4 * 32`), which is why 4K is 3840x2176.
epilogue_height, epilogue_width = height * 2, width * 2
refined_frames = (out3.frames.shape[2] - 1) * ratio + 1
up_video = upsample_pipe(latents=out3.frames, output_type="latent", return_dict=False)[0]
epilogue_keyframes = pipe.rebuild_epilogue_keyframes(
out3.keyframes,
decode_timestep=0.0,
decode_noise_scale=0.0,
seed=0,
device=up_video.device,
dtype=torch.float32,
)
# Temporal cuts land on the seams the *last* round stitched on -- the positions handed into it, doubled --
# not on every carry keyframe, since the slots that round invented sit mid-window.
tiles = epilogue_tiles(
latent_shape=(
(refined_frames - 1) // ratio + 1,
epilogue_height // pipe.vae.spatial_compression_ratio,
epilogue_width // pipe.vae.spatial_compression_ratio,
),
frame_tiles=2, # 2 ** number of temporal rounds
frame_seams=[pixel_to_latent_index(2 * p, ratio) for p in out2.keyframe_positions],
)
pipe.transformer.enable_adapters() # the epilogue is a detailing pass too
out4 = pipe(
prompt=prompt,
conditions=conditions,
latents=up_video,
audio_latents=out.audio,
generate_slots=False,
guidance_keyframe_latents=epilogue_keyframes,
guidance_keyframe_positions=out3.keyframe_positions,
reference_latents=out3.frames,
height=epilogue_height,
width=epilogue_width,
num_frames=refined_frames,
frame_rate=playback_fps,
noise_scale=STAGE_2_DISTILLED_SIGMA_VALUES[0],
sigmas=STAGE_2_DISTILLED_SIGMA_VALUES,
freeze_audio=True,
video_tiles=tiles,
generator=generator,
output_type="latent",
)
pipe.transformer.disable_adapters()Los dos ejes se unen de manera diferente. Ninguno de los dos lados de un borde espacial contiene una respuesta conocida, por lo que esas superposiciones se combinan con pesos trapezoidales. Los mosaicos temporales se cortan en las costuras de los fotogramas clave de la última ronda de refinamiento.
Decodificación con el decodificador de difusión. Para una fidelidad de detalle máxima, mantenga output_type="latent" y pase los latentes (ya denormalizados, posiblemente recortados con trim_canvas) a LTX2VideoDiffusionDecodePipeline.
from diffusers import LTX2VideoDiffusionDecodePipeline
from diffusers.models.autoencoders.ltx2_diffusion_decoder import LTX2VideoDiffusionDecoderModel
decoder = LTX2VideoDiffusionDecoderModel.from_pretrained(
"Lightricks/LTX-2.5-Diffusers", subfolder="diffusion_decoder", dtype=torch.bfloat16
)
decode_pipe = LTX2VideoDiffusionDecodePipeline(
diffusion_decoder=decoder, scheduler=pipe.scheduler, vae=pipe.vae
)
decode_pipe.enable_model_cpu_offload()
# `denormalize=False`: the `output_type="latent"` path already applied the latent statistics.
video = decode_pipe(latents=out3.frames, denormalize=False, output_type="np", return_dict=False)[0]LTX2Pipeline
clase diffusers.LTX2Pipeline
< source >( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLLTX2Videoaudio_vae: AutoencoderKLLTX2Audiotext_encoder: transformers.models.gemma3.modeling_gemma3.Gemma3ForConditionalGeneration | transformers.models.gemma4_unified.modeling_gemma4_unified.Gemma4UnifiedForConditionalGenerationtokenizer: GemmaTokenizerconnectors: LTX2TextConnectorstransformer: LTX2VideoTransformer3DModelvocoder: diffusers.pipelines.ltx2.vocoder.LTX2Vocoder | diffusers.pipelines.ltx2.vocoder.LTX2VocoderWithBWEprocessor: transformers.processing_utils.ProcessorMixin | None = Noneprompt_enhancer: transformers.models.gemma4.modeling_gemma4.Gemma4ForConditionalGeneration | None = Noneduration_head: diffusers.pipelines.ltx2.duration_head.LTX2DurationHead | None = None )
Parámetros
- transformer (LTXVideoTransformer3DModel) — Arquitectura de Transformer condicional para desruidar los latentes de video codificados.
- scheduler (FlowMatchEulerDiscreteScheduler) —
Un scheduler para usar en combinación con
transformerpara desruidar los latentes de imagen codificados. - vae (AutoencoderKLLTXVideo) — Modelo de Autoencoder Variacional (VAE) para codificar y decodificar imágenes hacia y desde representaciones latentes.
- text_encoder (
T5EncoderModel) — T5, concretamente la variante google/t5-v1_1-xxl. - tokenizer (
CLIPTokenizer) — Tokenizer de la clase CLIPTokenizer. - tokenizer (
T5TokenizerFast) — Segundo Tokenizer de la clase T5TokenizerFast. - connectors (
LTX2TextConnectors) — Pila de conectores de texto utilizada para adaptar los estados ocultos del codificador de texto para las ramas de video y audio.
Pipeline para la generación de texto a video.
Referencia: https://github.com/Lightricks/LTX-Video
__call__
< source >( prompt: str | list[str] = Nonenegative_prompt: str | list[str] | None = Noneheight: int = 512width: int = 768num_frames: int | None = Nonemin_seconds: float = 1.0max_seconds: float = 20.0frame_rate: float = 24.0motion_speed: float = 1.0num_inference_steps: int = 30sigmas: list[float] | None = Nonetimesteps: list = Noneguidance_scale: float = 3.0stg_scale: float = 1.0modality_scale: float = 3.0guidance_rescale: float = 0.7audio_guidance_scale: float | None = 7.0audio_stg_scale: float | None = 1.0audio_modality_scale: float | None = 3.0audio_guidance_rescale: float | None = 0.7spatio_temporal_guidance_blocks: list[int] | None = [28]noise_scale: float = 0.0num_videos_per_prompt: int = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneaudio_latents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Nonedecode_timestep: float | list[float] = 0.0decode_noise_scale: float | list[float] | None = Noneuse_cross_timestep: bool = Truesystem_prompt: str | None = Noneenable_prompt_enhancement: bool = Falseprompt_max_new_tokens: int | None = Noneprompt_enhancement_kwargs: dict[str, typing.Any] | None = Noneprompt_enhancement_seed: int = 10output_type: str = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list = ['latents']max_sequence_length: int = 1024 ) → ~pipelines.ltx.LTX2PipelineOutput or tuple
Parámetros
- prompt (
strolist[str], opcional) — El prompt o los prompts para guiar la generación de la imagen. Si no se define, hay que pasarprompt_embedsen su lugar. - negative_prompt (
strolist[str], opcional) — El prompt o los prompts que no deben guiar la generación de la imagen. Si no se define, hay que pasarnegative_prompt_embedsen su lugar. Se ignora cuando no se usa guía (guidance_scale < 1). - height (
int, opcional, valor predeterminado512) — La altura en píxeles de la imagen generada. Por defecto, se establece en 480 para obtener los mejores resultados. - width (
int, opcional, valor predeterminado768) — El ancho en píxeles de la imagen generada. Por defecto, se establece en 848 para obtener los mejores resultados. - num_frames (
int, opcional) — El número de fotogramas de vídeo a generar. Si no se especifica, el valor predeterminado es una duración predicha automáticamente cuando este pipeline tiene un componenteduration_head(puntos de control de LTX-2.5 y posteriores), y121en caso contrario. Pasa un entero para establecer la duración de forma explícita. Las cantidades predichas automáticamente se ajustan a la cuadrícula temporal causal del VAE, por lo que la duración realizada está cuantizada (aproximadamente 0,33 s a 24 fps). - min_seconds (
float, opcional, valor predeterminado1.0) — Límite inferior de la duración predicha automáticamente cuando se omitenum_framesy está presente unduration_head. Se ignora cuandonum_framesse establece explícitamente. - max_seconds (
float, opcional, valor predeterminado20.0) — Límite superior de la duración predicha automáticamente cuando se omitenum_framesy está presente unduration_head. Se ignora cuandonum_framesse establece explícitamente. Debe ser estrictamente mayor quemin_seconds. - frame_rate (
float, opcional, valor predeterminado24.0) — Los fotogramas por segundo (FPS) del video generado. - motion_speed (
float, opcional, valor predeterminado1.0) — Velocidad del movimiento en relación con el tiempo real. Los embeddings posicionales se condicionan enframe_rate / motion_speed, por lo que los valores inferiores a 1 ralentizan el movimiento, p. ej.0.2para el movimiento lento de 5x del LoRA Slow-Motion-Control.frame_ratesigue siendo la tasa de reproducción: la duración del audio y el número de frames predichos se ajustan a ella. - num_inference_steps (
int, opcional, valor predeterminado 30) — El número de pasos de desruido. Más pasos de desruido suelen conducir a una imagen de mayor calidad a costa de una inferencia más lenta. - sigmas (
List[float], opcional) — Sigmas personalizados para usar en el proceso de desruido con programadores que admiten un argumentosigmasen su métodoset_timesteps. Si no se define, se usará el comportamiento predeterminado cuando se pasenum_inference_steps. - timesteps (
list[int], opcional) — Pasos de tiempo personalizados para usar en el proceso de desruido con programadores que admiten un argumentotimestepsen su métodoset_timesteps. Si no se define, se usará el comportamiento predeterminado cuando se pasenum_inference_steps. Debe estar en orden descendente. - guidance_scale (
float, opcional, valor predeterminado4.0) — Escala de guía tal como se define en Classifier-Free Diffusion Guidance.guidance_scalese define comowde la ecuación 2 de Imagen Paper. La escala de guía se habilita al establecerguidance_scale > 1. Una escala de guía más alta fomenta la generación de imágenes estrechamente vinculadas al textoprompt, generalmente a costa de una menor calidad de imagen. Se utiliza para la modalidad de video (hay un valor separadoaudio_guidance_scalepara la modalidad de audio). - stg_scale (
float, opcional, valor predeterminado0.0) — Escala de guía de video para Spatio-Temporal Guidance (STG), propuesta en Spatiotemporal Skip Guidance for Enhanced Video Diffusion Sampling. STG utiliza una estimación similar a CFG donde se mueve la muestra alejándose de una muestra débil de una versión perturbada del modelo de desruido. Habilitar STG resultará en una pasada adicional del modelo de desruido; el valor predeterminado de0.0significa que STG está deshabilitado. - modality_scale (
float, opcional, valor predeterminado1.0) — Escala de guía de video para la guía de aislamiento de modalidades de LTX-2.X, donde se desplaza la muestra alejada de una muestra más débil generada por el modelo de desruido con la atención cruzada entre modalidades (de audio a video y de video a audio) deshabilitada, utilizando una estimación similar a CFG. Habilitar la guía de modalidades resultará en una paso de inferencia adicional del modelo de desruido; el valor predeterminado de1.0significa que la guía de modalidades está deshabilitada. - guidance_rescale (
float, opcional, valor predeterminado 0.0) — Factor de rescale de guía propuesto por Common Diffusion Noise Schedules and Sample Steps are Flawedguidance_scalese define comoφen la ecuación 16. de Common Diffusion Noise Schedules and Sample Steps are Flawed. El factor de rescale de guía debe corregir la sobreexposición al utilizar SNR terminal cero. Se usa para la modalidad de video. - audio_guidance_scale (
float, opcional por defectoNone) — Escala de guía de audio para CFG con respecto al prompt negativo. La regla de actualización de CFG es la misma para video y audio, pero pueden usar valores diferentes para la escala de guía. Los autores de LTX-2.X sugieren queaudio_guidance_scaledebe ser mayor en relación conguidance_scalede video (p. ej. para LTX-2.3 sugieren 3.0 para video y 7.0 para audio). Si esNone, por defecto toma el valor de videoguidance_scale. - audio_stg_scale (
float, opcional, valor predeterminadoNone) — Escala de guía de audio para STG. Al igual que con CFG, la regla de actualización de STG es la misma para video y audio. Para LTX-2.3, se sugiere un valor de 1.0 tanto para video como para audio. Si esNone, el valor predeterminado es el valor de videostg_scale. - audio_modality_scale (
float, opcional, valor predeterminadoNone) — Escala de guía de audio para la guía de aislamiento de modalidad de LTX-2.X. Al igual que con CFG, la regla de guía de modalidad es la misma para video y audio. Para LTX-2.3, se sugiere un valor de 3.0 tanto para video como para audio. Si esNone, el valor predeterminado es el valor de videomodality_scale. - audio_guidance_rescale (
float, opcional, valor predeterminadoNone) — Factor de reescalado de guía independiente para la modalidad de audio. Si esNone, toma el valor de videoguidance_rescale. - spatio_temporal_guidance_blocks (
list[int], opcional, valor predeterminadoNone) — Índices de bloques del transformer (con índice cero) en los que se aplica STG. Debe proporcionarse si se utiliza STG (stg_scaleoaudio_stg_scalees mayor que0). Se recomienda un valor de[29]para LTX-2.0 y[28]para LTX-2.3. - noise_scale (
float, opcional, valor predeterminado0.0) — El factor de interpolación entre el ruido aleatorio y los latentes desruidados en cada paso de tiempo. Aplica ruido a loslatentsy a losaudio_latentsantes de continuar con el desruido. - num_videos_per_prompt (
int, opcional, valor predeterminado 1) — El número de vídeos que se generarán por prompt. - generator (
torch.Generatorolist[torch.Generator], opcional) — Un generador o una lista de generadores de torch para hacer la generación determinista. - latents (
torch.Tensor, opcional) — Latentes ruidosos pregenerados, muestreados de una distribución gaussiana, que se usarán como entradas para la generación de video. Se pueden utilizar para ajustar la misma generación con diferentes prompts. Si no se proporcionan, se generará un tensor de latentes mediante muestreo usando elgeneratoraleatorio suministrado. - audio_latents (
torch.Tensor, opcional) — Latentes ruidosos pregenerados, muestreados de una distribución gaussiana, que se utilizarán como entradas para la generación de audio. Se pueden usar para ajustar la misma generación con diferentes prompts. Si no se proporciona, se generará un tensor de latentes mediante muestreo usando elgeneratoraleatorio suministrado. - prompt_embeds (
torch.Tensor, opcional) — Incrustaciones de texto pregeneradas. Se pueden usar para ajustar fácilmente las entradas de texto, p. ej. ponderación de prompts. Si no se proporcionan, las incrustaciones de texto se generarán a partir del argumento de entradaprompt. - prompt_attention_mask (
torch.Tensor, opcional) — Máscara de atención pregenerada para las incrustaciones de texto. - negative_prompt_embeds (
torch.FloatTensor, opcional) — Incrustaciones de texto negativo pregeneradas. Para PixArt-Sigma, este prompt negativo debe ser "". Si no se proporciona, negative_prompt_embeds se generará a partir del argumento de entradanegative_prompt. - negative_prompt_attention_mask (
torch.FloatTensor, opcional) — Máscara de atención pregenerada para los embeddings de texto negativos. - decode_timestep (
float, por defecto0.0) — El paso de tiempo en el que se decodifica el video generado. - decode_noise_scale (
float, por defectoNone) — El factor de interpolación entre el ruido aleatorio y los latentes desruidos en el paso de decodificación. - use_cross_timestep (
boolopcional, valor predeterminadoTrue) — Indica si se debe utilizar la sigma de la modalidad cruzada (el audio es la modalidad cruzada del video, y viceversa) al calcular los parámetros de modulación de la atención cruzada.Truees el comportamiento de LTX-2.3/2.5;Falsees el comportamiento heredado de LTX-2.0. - system_prompt (
str, opcional, valor predeterminadoNone) — Prompt de sistema opcional para usar en la mejora del prompt. El prompt de sistema será utilizado por el mejorador de prompts (un modelo de generación condicional de Gemma: el componente dedicadoprompt_enhancersi está configurado, o eltext_encoderprincipal en caso contrario) para generar un prompt mejorado a partir delpromptoriginal y condicionar la generación. Si no se proporciona y se ha configurado unprompt_enhancerdedicado (LTX-2.5), el valor predeterminado esLTX2_5_T2V_DEFAULT_SYSTEM_PROMPT(dediffusers.pipelines.ltx2.utils); consulteenable_prompt_enhancement. - enable_prompt_enhancement (
bool, opcional, valor predeterminadoFalse) — Si se debe ejecutar el mejoramiento del prompt. Es una opción de activación explícita, en línea con los pipelines de referencia de Lightricks. CuandoTrueysystem_promptse omite, LTX-2.5 usaLTX2_5_T2V_DEFAULT_SYSTEM_PROMPTsi se ha configurado unprompt_enhancerdedicado; LTX-2.0/2.3 requieren unsystem_promptexplícito. - prompt_max_new_tokens (
int, opcional, valor predeterminadoNone) — El número máximo de nuevos tokens que se generarán al realizar la mejora del prompt. Si no se proporciona, se utiliza 600 para unprompt_enhancerdedicado de Gemma 4 (LTX-2.5) o 512 para eltext_encoderde respaldo de Gemma 3 (LTX-2.0/2.3). - prompt_enhancement_kwargs (
dict[str, Any], opcional, valor predeterminadoNone) — Argumentos de palabra clave para la llamada.generatedel mejorador de prompts. Si no se proporcionan, siempre coinciden con el modelo que realiza la mejora:do_sample=False, no_repeat_ngram_size=5(codicioso) cuando se utiliza unprompt_enhancerdedicado (LTX-2.5), odo_sample=True, temperature=0.7para el respaldo detext_encoder(LTX-2.0/2.3). Consulte https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationMixin.generate para más detalles. - prompt_enhancement_seed (
int, opcional, valor predeterminado10) — Semilla aleatoria para cualquier operación aleatoria durante el mejoramiento del prompt. - output_type (
str, opcional, valor predeterminado"pil") — El formato de salida de la imagen generada. Elija entre PIL:PIL.Image.Imageonp.array. - return_dict (
bool, opcional, valor predeterminadoTrue) — Indica si se debe devolver un~pipelines.ltx.LTX2PipelineOutputen lugar de una tupla simple. - attention_kwargs (
dict, opcional) — Un diccionario de kwargs que, si se especifica, se pasa alAttentionProcessordefinido enself.processordentro de diffusers.models.attention_processor. - callback_on_step_end (
Callable, opcional) — Una función que se llama al final de cada paso de desruido durante la inferencia. La función se llama con los siguientes argumentos:callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict).callback_kwargsincluirá una lista de todos los tensores especificados porcallback_on_step_end_tensor_inputs. - callback_on_step_end_tensor_inputs (
List, opcional, valor predeterminado["latents"]) — La lista de entradas de tensor para la funcióncallback_on_step_end. Los tensores especificados en la lista se pasarán como argumentocallback_kwargs. Solo podrá incluir variables enumeradas en el atributo._callback_tensor_inputsde su clase de pipeline. - max_sequence_length (
int, opcional, valor predeterminado1024) — Longitud máxima de la secuencia para usar con elprompt.
Devuelve
~pipelines.ltx.LTX2PipelineOutput o tuple
Si return_dict es True, se devuelve ~pipelines.ltx.LTX2PipelineOutput; en caso contrario, se devuelve una tuple cuyo primer elemento es una lista con las imágenes generadas.
Función invocada al llamar a la pipeline para la generación.
Ejemplos:
>>> import torch
>>> from diffusers import LTX2Pipeline
>>> from diffusers.utils import encode_video
>>> pipe = LTX2Pipeline.from_pretrained("Lightricks/LTX-2", torch_dtype=torch.bfloat16)
>>> pipe.enable_model_cpu_offload()
>>> prompt = "A woman with long brown hair and light skin smiles at another woman with long blonde hair. The woman with brown hair wears a black jacket and has a small, barely noticeable mole on her right cheek. The camera angle is a close-up, focused on the woman with brown hair's face. The lighting is warm and natural, likely from the setting sun, casting a soft glow on the scene. The scene appears to be real-life footage"
>>> negative_prompt = "worst quality, inconsistent motion, blurry, jittery, distorted"
>>> frame_rate = 24.0
>>> video, audio = pipe(
... prompt=prompt,
... negative_prompt=negative_prompt,
... width=768,
... height=512,
... num_frames=121,
... frame_rate=frame_rate,
... num_inference_steps=30,
... guidance_scale=3.0,
... output_type="np",
... return_dict=False,
... )
>>> encode_video(
... video[0],
... fps=frame_rate,
... audio=audio[0].float().cpu(),
... audio_sample_rate=pipe.vocoder.config.output_sampling_rate, # should be 24000
... output_path="video.mp4",
... )encode_prompt
< source >( prompt: str | list[str]negative_prompt: str | list[str] | None = Nonedo_classifier_free_guidance: bool = Truenum_videos_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Nonemax_sequence_length: int = 1024scale_factor: int = 8device: typing.Optional[torch.device] = Nonedtype: typing.Optional[torch.dtype] = None )
Parámetros
- prompt (
strolist[str], opcional) — prompt a codificar - negative_prompt (
strolist[str], opcional) — El prompt o prompts que no deben guiar la generación de la imagen. Si no se define, se debe pasarnegative_prompt_embedsen su lugar. Se ignora cuando no se usa guía (es decir, se ignora siguidance_scalees menor que1). - do_classifier_free_guidance (
bool, opcional, valor predeterminadoTrue) — Si se debe usar classifier free guidance o no. - num_videos_per_prompt (
int, opcional, valor predeterminado 1) — Número de videos que deben generarse por prompt. Dispositivo torch en el que colocar las incrustaciones resultantes - prompt_embeds (
torch.Tensor, opcional) — Incrustaciones de texto pregeneradas. Se pueden usar para ajustar fácilmente las entradas de texto, p. ej. ponderación de prompts. Si no se proporcionan, las incrustaciones de texto se generarán a partir del argumento de entradaprompt. - negative_prompt_embeds (
torch.Tensor, opcional) — Incrustaciones de texto negativo pregeneradas. Se pueden usar para ajustar fácilmente las entradas de texto, p. ej. el ponderado del prompt. Si no se proporciona, negative_prompt_embeds se generará a partir del argumento de entradanegative_prompt. - device — (
torch.device, opcional): dispositivo de torch - dtype — (
torch.dtype, opcional): dtype de torch
Codifica el prompt en estados ocultos del codificador de texto.
enhance_prompt
< source >( prompt: strsystem_prompt: strmax_new_tokens: int | None = Noneseed: int = 10generator: typing.Optional[torch.Generator] = Nonegeneration_kwargs: dict[str, typing.Any] | None = Nonedevice: typing.Union[str, torch.device, NoneType] = Noneimage: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None )
Mejora el prompt proporcionado generando un nuevo prompt a partir de él y de un prompt de sistema, utilizando el mejorador de prompts (un modelo de generación condicional de Gemma). Cuando se proporciona image, el mejorador también se condiciona en ese fotograma de referencia (mejora de estilo I2V / fotograma clave). Utiliza el componente dedicado prompt_enhancer si está configurado (p. ej. LTX-2.5, cuyo codificador de texto no está entrenado para la mejora); de lo contrario, recurre al text_encoder principal (LTX-2.0/2.3, que también actúa como su propio mejorador).
Las plantillas de mensajes, los kwargs de decodificación, la limpieza de la respuesta y la preparación del lado largo de la imagen coinciden con ltx-core / ltx-pipelines (enhance_t2v / enhance_i2v / generate_enhanced_prompt).
LTX2ImageToVideoPipeline
clase diffusers.LTX2ImageToVideoPipeline
< source >( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLLTX2Videoaudio_vae: AutoencoderKLLTX2Audiotext_encoder: transformers.models.gemma3.modeling_gemma3.Gemma3ForConditionalGeneration | transformers.models.gemma4_unified.modeling_gemma4_unified.Gemma4UnifiedForConditionalGenerationtokenizer: GemmaTokenizerconnectors: LTX2TextConnectorstransformer: LTX2VideoTransformer3DModelvocoder: diffusers.pipelines.ltx2.vocoder.LTX2Vocoder | diffusers.pipelines.ltx2.vocoder.LTX2VocoderWithBWEprocessor: transformers.processing_utils.ProcessorMixin | None = Noneprompt_enhancer: transformers.models.gemma4.modeling_gemma4.Gemma4ForConditionalGeneration | None = Noneduration_head: diffusers.pipelines.ltx2.duration_head.LTX2DurationHead | None = None )
Pipeline para la generación de video a partir de imágenes.
Referencia: https://github.com/Lightricks/LTX-Video
TODO
__call__
< source >( image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = Noneprompt: str | list[str] = Nonenegative_prompt: str | list[str] | None = Noneheight: int = 512width: int = 768num_frames: int | None = Nonemin_seconds: float = 1.0max_seconds: float = 20.0frame_rate: float = 24.0motion_speed: float = 1.0num_inference_steps: int = 30sigmas: list[float] | None = Nonetimesteps: list[int] | None = Noneguidance_scale: float = 3.0stg_scale: float = 1.0modality_scale: float = 3.0guidance_rescale: float = 0.7audio_guidance_scale: float | None = 7.0audio_stg_scale: float | None = 1.0audio_modality_scale: float | None = 3.0audio_guidance_rescale: float | None = 0.7spatio_temporal_guidance_blocks: list[int] | None = [28]noise_scale: float = 0.0num_videos_per_prompt: int = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneaudio_latents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Nonedecode_timestep: float | list[float] = 0.0decode_noise_scale: float | list[float] | None = Noneuse_cross_timestep: bool = Truesystem_prompt: str | None = Noneenable_prompt_enhancement: bool = Falseprompt_max_new_tokens: int | None = Noneprompt_enhancement_kwargs: dict[str, typing.Any] | None = Noneprompt_enhancement_seed: int = 10image_crf: int | None = Noneoutput_type: str = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list = ['latents']max_sequence_length: int = 1024 ) → ~pipelines.ltx.LTX2PipelineOutput or tuple
Parámetros
- image (
PipelineImageInput) — La imagen de entrada para condicionar la generación. Debe ser una imagen, una lista de imágenes o untorch.Tensor. - prompt (
strolist[str], opcional) — El prompt o los prompts para guiar la generación de la imagen. Si no se define, hay que pasarprompt_embedsen su lugar. - negative_prompt (
strolist[str], opcional) — El prompt o los prompts que no deben guiar la generación de la imagen. Si no se define, hay que pasarnegative_prompt_embedsen su lugar. Se ignora cuando no se usa guía (guidance_scale < 1). - height (
int, opcional, valor predeterminado512) — La altura en píxeles de la imagen generada. Por defecto, se establece en 480 para obtener los mejores resultados. - width (
int, opcional, valor predeterminado768) — El ancho en píxeles de la imagen generada. Por defecto, se establece en 848 para obtener los mejores resultados. - num_frames (
int, opcional) — El número de fotogramas de vídeo a generar. Si no se especifica, el valor predeterminado es una duración predicha automáticamente cuando este pipeline tiene un componenteduration_head(puntos de control de LTX-2.5 y posteriores), y121en caso contrario. Pasa un entero para establecer la duración de forma explícita. Las cantidades predichas automáticamente se ajustan a la cuadrícula temporal causal del VAE, por lo que la duración realizada está cuantizada (aproximadamente 0,33 s a 24 fps). - min_seconds (
float, opcional, valor predeterminado1.0) — Límite inferior de la duración predicha automáticamente cuando se omitenum_framesy está presente unduration_head. Se ignora cuandonum_framesse establece explícitamente. - max_seconds (
float, opcional, valor predeterminado20.0) — Límite superior de la duración predicha automáticamente cuando se omitenum_framesy está presente unduration_head. Se ignora cuandonum_framesse establece explícitamente. Debe ser estrictamente mayor quemin_seconds. - frame_rate (
float, opcional, valor predeterminado24.0) — Los fotogramas por segundo (FPS) del video generado. - motion_speed (
float, opcional, valor predeterminado1.0) — Velocidad del movimiento en relación con el tiempo real. Los embeddings posicionales se condicionan enframe_rate / motion_speed, por lo que los valores inferiores a 1 ralentizan el movimiento, p. ej.0.2para el movimiento lento de 5x del LoRA Slow-Motion-Control.frame_ratesigue siendo la tasa de reproducción: la duración del audio y el número de frames predichos se ajustan a ella. - num_inference_steps (
int, opcional, valor predeterminado 30) — El número de pasos de desruido. Más pasos de desruido suelen conducir a una imagen de mayor calidad a costa de una inferencia más lenta. - sigmas (
List[float], opcional) — Sigmas personalizados para usar en el proceso de desruido con programadores que admiten un argumentosigmasen su métodoset_timesteps. Si no se define, se usará el comportamiento predeterminado cuando se pasenum_inference_steps. - timesteps (
List[int], opcional) — Pasos de tiempo personalizados para usar en el proceso de desruido con programadores que admiten un argumentotimestepsen su métodoset_timesteps. Si no se define, se usará el comportamiento predeterminado cuando se pasenum_inference_steps. Debe estar en orden descendente. - guidance_scale (
float, opcional, valor predeterminado4.0) — Escala de guía tal como se define en Classifier-Free Diffusion Guidance.guidance_scalese define comowde la ecuación 2 de Imagen Paper. La escala de guía se habilita al establecerguidance_scale > 1. Una escala de guía más alta fomenta la generación de imágenes estrechamente vinculadas al textoprompt, generalmente a costa de una menor calidad de imagen. Se utiliza para la modalidad de video (hay un valor separadoaudio_guidance_scalepara la modalidad de audio). - stg_scale (
float, opcional, valor predeterminado0.0) — Escala de guía de video para Spatio-Temporal Guidance (STG), propuesta en Spatiotemporal Skip Guidance for Enhanced Video Diffusion Sampling. STG utiliza una estimación similar a CFG donde se mueve la muestra alejándose de una muestra débil de una versión perturbada del modelo de desruido. Habilitar STG resultará en una pasada adicional del modelo de desruido; el valor predeterminado de0.0significa que STG está deshabilitado. - modality_scale (
float, opcional, valor predeterminado1.0) — Escala de guía de video para la guía de aislamiento de modalidades de LTX-2.X, donde se desplaza la muestra alejada de una muestra más débil generada por el modelo de desruido con la atención cruzada entre modalidades (de audio a video y de video a audio) deshabilitada, utilizando una estimación similar a CFG. Habilitar la guía de modalidades resultará en una paso de inferencia adicional del modelo de desruido; el valor predeterminado de1.0significa que la guía de modalidades está deshabilitada. - guidance_rescale (
float, opcional, valor predeterminado 0.0) — Factor de rescale de guía propuesto por Common Diffusion Noise Schedules and Sample Steps are Flawedguidance_scalese define comoφen la ecuación 16. de Common Diffusion Noise Schedules and Sample Steps are Flawed. El factor de rescale de guía debe corregir la sobreexposición al utilizar SNR terminal cero. Se usa para la modalidad de video. - audio_guidance_scale (
float, opcional por defectoNone) — Escala de guía de audio para CFG con respecto al prompt negativo. La regla de actualización de CFG es la misma para video y audio, pero pueden usar valores diferentes para la escala de guía. Los autores de LTX-2.X sugieren queaudio_guidance_scaledebe ser mayor en relación conguidance_scalede video (p. ej. para LTX-2.3 sugieren 3.0 para video y 7.0 para audio). Si esNone, por defecto toma el valor de videoguidance_scale. - audio_stg_scale (
float, opcional, valor predeterminadoNone) — Escala de guía de audio para STG. Al igual que con CFG, la regla de actualización de STG es la misma para video y audio. Para LTX-2.3, se sugiere un valor de 1.0 tanto para video como para audio. Si esNone, el valor predeterminado es el valor de videostg_scale. - audio_modality_scale (
float, opcional, valor predeterminadoNone) — Escala de guía de audio para la guía de aislamiento de modalidad de LTX-2.X. Al igual que con CFG, la regla de guía de modalidad es la misma para video y audio. Para LTX-2.3, se sugiere un valor de 3.0 tanto para video como para audio. Si esNone, el valor predeterminado es el valor de videomodality_scale. - audio_guidance_rescale (
float, opcional, valor predeterminadoNone) — Factor de reescalado de guía independiente para la modalidad de audio. Si esNone, toma el valor de videoguidance_rescale. - spatio_temporal_guidance_blocks (
list[int], opcional, valor predeterminadoNone) — Índices de bloques del transformer (con índice cero) en los que se aplica STG. Debe proporcionarse si se utiliza STG (stg_scaleoaudio_stg_scalees mayor que0). Se recomienda un valor de[29]para LTX-2.0 y[28]para LTX-2.3. - noise_scale (
float, opcional, valor predeterminado0.0) — El factor de interpolación entre el ruido aleatorio y los latentes desruidados en cada paso de tiempo. Aplica ruido a loslatentsy a losaudio_latentsantes de continuar con el desruido. - num_videos_per_prompt (
int, opcional, valor predeterminado 1) — El número de vídeos que se generarán por prompt. - generator (
torch.Generatorolist[torch.Generator], opcional) — Un generador o una lista de generadores de torch para hacer la generación determinista. - latents (
torch.Tensor, opcional) — Latentes ruidosos pregenerados, muestreados de una distribución gaussiana, que se usarán como entradas para la generación de video. Se pueden utilizar para ajustar la misma generación con diferentes prompts. Si no se proporcionan, se generará un tensor de latentes mediante muestreo usando elgeneratoraleatorio suministrado. - audio_latents (
torch.Tensor, opcional) — Latentes ruidosos pregenerados, muestreados de una distribución gaussiana, que se utilizarán como entradas para la generación de audio. Se pueden usar para ajustar la misma generación con diferentes prompts. Si no se proporciona, se generará un tensor de latentes mediante muestreo usando elgeneratoraleatorio suministrado. - prompt_embeds (
torch.Tensor, opcional) — Incrustaciones de texto pregeneradas. Se pueden usar para ajustar fácilmente las entradas de texto, p. ej. ponderación de prompts. Si no se proporcionan, las incrustaciones de texto se generarán a partir del argumento de entradaprompt. - prompt_attention_mask (
torch.Tensor, opcional) — Máscara de atención pregenerada para las incrustaciones de texto. - negative_prompt_embeds (
torch.FloatTensor, opcional) — Incrustaciones de texto negativo pregeneradas. Para PixArt-Sigma, este prompt negativo debe ser "". Si no se proporciona, negative_prompt_embeds se generará a partir del argumento de entradanegative_prompt. - negative_prompt_attention_mask (
torch.FloatTensor, opcional) — Máscara de atención pregenerada para los embeddings de texto negativos. - decode_timestep (
float, por defecto0.0) — El paso de tiempo en el que se decodifica el video generado. - decode_noise_scale (
float, por defectoNone) — El factor de interpolación entre el ruido aleatorio y los latentes desruidos en el paso de decodificación. - use_cross_timestep (
boolopcional, valor predeterminadoTrue) — Indica si se debe utilizar la sigma de la modalidad cruzada (el audio es la modalidad cruzada del video, y viceversa) al calcular los parámetros de modulación de la atención cruzada.Truees el comportamiento de LTX-2.3/2.5;Falsees el comportamiento heredado de LTX-2.0. - system_prompt (
str, opcional, valor predeterminadoNone) — Prompt de sistema opcional para usar en la mejora del prompt. El prompt de sistema será utilizado por el mejorador de prompts (un modelo de generación condicional de Gemma: el componente dedicadoprompt_enhancersi está configurado, o en su defecto eltext_encoderprincipal) para generar un prompt mejorado a partir delpromptoriginal y la primeraimagepara condicionar la generación. Si no se proporciona y se ha configurado unprompt_enhancerdedicado (LTX-2.5), el valor predeterminado esLTX2_5_I2V_DEFAULT_SYSTEM_PROMPT(dediffusers.pipelines.ltx2.utils) — consulteenable_prompt_enhancement. - enable_prompt_enhancement (
bool, opcional, valor predeterminadoFalse) — Si se debe ejecutar el mejoramiento del prompt. Es una opción de activación explícita, en línea con los pipelines de referencia de Lightricks. CuandoTrueysystem_promptse omite, LTX-2.5 usaLTX2_5_I2V_DEFAULT_SYSTEM_PROMPTsi se ha configurado unprompt_enhancerdedicado; LTX-2.0/2.3 requieren unsystem_promptexplícito. - prompt_max_new_tokens (
int, opcional, valor predeterminadoNone) — El número máximo de nuevos tokens que se generarán al realizar la mejora del prompt. Si no se proporciona, se utiliza 600 para unprompt_enhancerdedicado de Gemma 4 (LTX-2.5) o 512 para eltext_encoderde respaldo de Gemma 3 (LTX-2.0/2.3). - prompt_enhancement_kwargs (
dict[str, Any], opcional, valor predeterminadoNone) — Argumentos de palabra clave para la llamada.generatedel mejorador de prompts. Si no se proporcionan, siempre coinciden con el modelo que realiza la mejora:do_sample=False, no_repeat_ngram_size=3(codicioso) cuando se utiliza unprompt_enhancerdedicado (LTX-2.5), odo_sample=True, temperature=0.7para el respaldo detext_encoder(LTX-2.0/2.3). Consulte https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationMixin.generate para más detalles. - prompt_enhancement_seed (
int, opcional, valor predeterminado10) — Semilla aleatoria para cualquier operación aleatoria durante el mejoramiento del prompt. - image_crf (
int, opcional, valor predeterminadoNone) — CRF de H.264 utilizado para recomprimir laimagede condicionamiento antes de la codificación VAE, de modo que coincida con la compresión con la que se entrenó el modelo.Nonesignifica “usar el valor predeterminado del modelo” (33 hasta LTX-2.3, 18 para LTX-2.5). Pase0para omitir la recompresión. Requiere unaPIL.Image.Imagecuando se ejecuta la recompresión. - output_type (
str, opcional, valor predeterminado"pil") — El formato de salida de la imagen generada. Elija entre PIL:PIL.Image.Imageonp.array. - return_dict (
bool, opcional, valor predeterminadoTrue) — Indica si se debe devolver un~pipelines.ltx.LTX2PipelineOutputen lugar de una tupla simple. - attention_kwargs (
dict, opcional) — Un diccionario de kwargs que, si se especifica, se pasa alAttentionProcessordefinido enself.processordentro de diffusers.models.attention_processor. - callback_on_step_end (
Callable, opcional) — Una función que se llama al final de cada paso de desruido durante la inferencia. La función se llama con los siguientes argumentos:callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict).callback_kwargsincluirá una lista de todos los tensores especificados porcallback_on_step_end_tensor_inputs. - callback_on_step_end_tensor_inputs (
List, opcional) — La lista de entradas de tensor para la funcióncallback_on_step_end. Los tensores especificados en la lista se pasarán como argumentocallback_kwargs. Solo podrá incluir variables listadas en el atributo._callback_tensor_inputsde su clase de pipeline. - max_sequence_length (
int, opcional, valor predeterminado1024) — Longitud máxima de la secuencia para usar con elprompt.
Devuelve
~pipelines.ltx.LTX2PipelineOutput o tuple
Si return_dict es True, se devuelve ~pipelines.ltx.LTX2PipelineOutput; en caso contrario, se devuelve una tuple cuyo primer elemento es una lista con las imágenes generadas.
Función invocada al llamar a la pipeline para la generación.
Ejemplos:
>>> import torch
>>> from diffusers import LTX2ImageToVideoPipeline
>>> from diffusers.utils import encode_video
>>> from diffusers.utils import load_image
>>> pipe = LTX2ImageToVideoPipeline.from_pretrained("Lightricks/LTX-2", torch_dtype=torch.bfloat16)
>>> pipe.enable_model_cpu_offload()
>>> image = load_image(
... "https://huggingface.co/datasets/a-r-r-o-w/tiny-meme-dataset-captioned/resolve/main/images/8.png"
... )
>>> prompt = "A young girl stands calmly in the foreground, looking directly at the camera, as a house fire rages in the background."
>>> negative_prompt = "worst quality, inconsistent motion, blurry, jittery, distorted"
>>> frame_rate = 24.0
>>> video, audio = pipe(
... image=image,
... prompt=prompt,
... negative_prompt=negative_prompt,
... width=768,
... height=512,
... num_frames=121,
... frame_rate=frame_rate,
... num_inference_steps=30,
... guidance_scale=3.0,
... output_type="np",
... return_dict=False,
... )
>>> encode_video(
... video[0],
... fps=frame_rate,
... audio=audio[0].float().cpu(),
... audio_sample_rate=pipe.vocoder.config.output_sampling_rate, # should be 24000
... output_path="video.mp4",
... )encode_prompt
< source >( prompt: str | list[str]negative_prompt: str | list[str] | None = Nonedo_classifier_free_guidance: bool = Truenum_videos_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Nonemax_sequence_length: int = 1024scale_factor: int = 8device: typing.Optional[torch.device] = Nonedtype: typing.Optional[torch.dtype] = None )
Parámetros
- prompt (
strolist[str], opcional) — prompt a codificar - negative_prompt (
strolist[str], opcional) — El prompt o prompts que no deben guiar la generación de la imagen. Si no se define, se debe pasarnegative_prompt_embedsen su lugar. Se ignora cuando no se usa guía (es decir, se ignora siguidance_scalees menor que1). - do_classifier_free_guidance (
bool, opcional, valor predeterminadoTrue) — Si se debe usar classifier free guidance o no. - num_videos_per_prompt (
int, opcional, valor predeterminado 1) — Número de videos que deben generarse por prompt. Dispositivo torch en el que colocar las incrustaciones resultantes - prompt_embeds (
torch.Tensor, opcional) — Incrustaciones de texto pregeneradas. Se pueden usar para ajustar fácilmente las entradas de texto, p. ej. ponderación de prompts. Si no se proporcionan, las incrustaciones de texto se generarán a partir del argumento de entradaprompt. - negative_prompt_embeds (
torch.Tensor, opcional) — Incrustaciones de texto negativo pregeneradas. Se pueden usar para ajustar fácilmente las entradas de texto, p. ej. el ponderado del prompt. Si no se proporciona, negative_prompt_embeds se generará a partir del argumento de entradanegative_prompt. - device — (
torch.device, opcional): dispositivo de torch - dtype — (
torch.dtype, opcional): dtype de torch
Codifica el prompt en estados ocultos del codificador de texto.
enhance_prompt
< source >( prompt: strsystem_prompt: strmax_new_tokens: int | None = Noneseed: int = 10generator: typing.Optional[torch.Generator] = Nonegeneration_kwargs: dict[str, typing.Any] | None = Nonedevice: typing.Union[str, torch.device, NoneType] = Noneimage: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None )
Mejora el prompt proporcionado generando un nuevo prompt a partir de él y de un prompt de sistema, utilizando el mejorador de prompts (un modelo de generación condicional de Gemma). Cuando se proporciona image, el mejorador también se condiciona en ese fotograma de referencia (mejora de estilo I2V / fotograma clave). Utiliza el componente dedicado prompt_enhancer si está configurado (p. ej. LTX-2.5, cuyo codificador de texto no está entrenado para la mejora); de lo contrario, recurre al text_encoder principal (LTX-2.0/2.3, que también actúa como su propio mejorador).
Las plantillas de mensajes, los kwargs de decodificación, la limpieza de la respuesta y la preparación del lado largo de la imagen coinciden con ltx-core / ltx-pipelines (enhance_t2v / enhance_i2v / generate_enhanced_prompt).
LTX2ConditionPipeline
clase diffusers.LTX2ConditionPipeline
< source >( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLLTX2Videoaudio_vae: AutoencoderKLLTX2Audiotext_encoder: transformers.models.gemma3.modeling_gemma3.Gemma3ForConditionalGeneration | transformers.models.gemma4_unified.modeling_gemma4_unified.Gemma4UnifiedForConditionalGenerationtokenizer: GemmaTokenizerconnectors: LTX2TextConnectorstransformer: LTX2VideoTransformer3DModelvocoder: diffusers.pipelines.ltx2.vocoder.LTX2Vocoder | diffusers.pipelines.ltx2.vocoder.LTX2VocoderWithBWEaudio_scheduler: diffusers.schedulers.scheduling_flow_match_euler_discrete.FlowMatchEulerDiscreteScheduler | None = Noneprocessor: transformers.processing_utils.ProcessorMixin | None = Noneprompt_enhancer: transformers.models.gemma4.modeling_gemma4.Gemma4ForConditionalGeneration | None = Noneduration_head: diffusers.pipelines.ltx2.duration_head.LTX2DurationHead | None = None )
Pipeline para la generación de video que permite insertar condiciones de imagen en partes arbitrarias del video.
Referencia: https://github.com/Lightricks/LTX-Video
TODO
__call__
< source >( conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = Noneprompt: str | list[str] = Nonenegative_prompt: str | list[str] | None = Noneheight: int = 512width: int = 768num_frames: int | None = Nonemin_seconds: float = 1.0max_seconds: float = 20.0frame_rate: float = 24.0motion_speed: float = 1.0num_inference_steps: int = 30sigmas: list[float] | None = Nonetimesteps: list[float] | None = Noneguidance_scale: float = 3.0stg_scale: float = 1.0modality_scale: float = 3.0guidance_rescale: float = 0.7audio_guidance_scale: float | None = 7.0audio_stg_scale: float | None = 1.0audio_modality_scale: float | None = 3.0audio_guidance_rescale: float | None = 0.7spatio_temporal_guidance_blocks: list[int] | None = [28]noise_scale: float | None = Nonenum_videos_per_prompt: int | None = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneaudio_latents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Nonedecode_timestep: float | list[float] = 0.0decode_noise_scale: float | list[float] | None = Noneuse_cross_timestep: bool = Truesystem_prompt: str | None = Noneenable_prompt_enhancement: bool = Falseprompt_max_new_tokens: int | None = Noneprompt_enhancement_kwargs: dict[str, typing.Any] | None = Noneprompt_enhancement_seed: int = 10output_type: str = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list = ['latents']max_sequence_length: int = 1024 ) → ~pipelines.ltx.LTX2PipelineOutput or tuple
Parámetros
- conditions (
List[LTXVideoCondition], *optional*) — La lista de elementos de condicionamiento de fotogramas para la generación de video. - prompt (
stroList[str], opcional) — El prompt o los prompts para guiar la generación de la imagen. Si no se define, hay que pasarprompt_embedsen su lugar. - negative_prompt (
stroList[str], opcional) — El prompt o los prompts que no deben guiar la generación de la imagen. Si no se define, se debe pasarnegative_prompt_embedsen su lugar. Se ignora cuando no se usa guía (guidance_scale < 1). - height (
int, opcional, valor predeterminado512) — La altura en píxeles de la imagen generada. Por defecto, se establece en 480 para obtener los mejores resultados. - width (
int, opcional, valor predeterminado768) — El ancho en píxeles de la imagen generada. Por defecto, se establece en 848 para obtener los mejores resultados. - num_frames (
int, opcional) — El número de fotogramas de vídeo a generar. Si no se especifica, el valor predeterminado es una duración predicha automáticamente cuando este pipeline tiene un componenteduration_head(puntos de control de LTX-2.5 y posteriores), y121en caso contrario. Pasa un entero para establecer la duración de forma explícita. Las cantidades predichas automáticamente se ajustan a la cuadrícula temporal causal del VAE, por lo que la duración realizada está cuantizada (aproximadamente 0,33 s a 24 fps). - min_seconds (
float, opcional, valor predeterminado1.0) — Límite inferior de la duración predicha automáticamente cuando se omitenum_framesy está presente unduration_head. Se ignora cuandonum_framesse establece explícitamente. - max_seconds (
float, opcional, valor predeterminado20.0) — Límite superior de la duración predicha automáticamente cuando se omitenum_framesy está presente unduration_head. Se ignora cuandonum_framesse establece explícitamente. Debe ser estrictamente mayor quemin_seconds. - frame_rate (
float, opcional, valor predeterminado24.0) — Los fotogramas por segundo (FPS) del video generado. - motion_speed (
float, opcional, valor predeterminado1.0) — Velocidad del movimiento en relación con el tiempo real. Los embeddings posicionales se condicionan enframe_rate / motion_speed, por lo que los valores inferiores a 1 ralentizan el movimiento, p. ej.0.2para el movimiento lento de 5x del LoRA Slow-Motion-Control.frame_ratesigue siendo la tasa de reproducción: la duración del audio y el número de frames predichos se ajustan a ella. - num_inference_steps (
int, opcional, valor predeterminado 30) — El número de pasos de desruido. Más pasos de desruido suelen conducir a una imagen de mayor calidad a costa de una inferencia más lenta. - sigmas (
List[float], opcional) — Sigmas personalizados para usar en el proceso de desruido con programadores que admiten un argumentosigmasen su métodoset_timesteps. Si no se define, se usará el comportamiento predeterminado cuando se pasenum_inference_steps. - timesteps (
List[int], opcional) — Pasos de tiempo personalizados para usar en el proceso de desruido con programadores que admiten un argumentotimestepsen su métodoset_timesteps. Si no se define, se usará el comportamiento predeterminado cuando se pasenum_inference_steps. Debe estar en orden descendente. - guidance_scale (
float, opcional, valor predeterminado4.0) — Escala de guía tal como se define en Classifier-Free Diffusion Guidance.guidance_scalese define comowde la ecuación 2 de Imagen Paper. La escala de guía se habilita al establecerguidance_scale > 1. Una escala de guía más alta fomenta la generación de imágenes estrechamente vinculadas al textoprompt, generalmente a costa de una menor calidad de imagen. Se utiliza para la modalidad de video (hay un valor separadoaudio_guidance_scalepara la modalidad de audio). - stg_scale (
float, opcional, valor predeterminado0.0) — Escala de guía de video para Spatio-Temporal Guidance (STG), propuesta en Spatiotemporal Skip Guidance for Enhanced Video Diffusion Sampling. STG utiliza una estimación similar a CFG donde se mueve la muestra alejándose de una muestra débil de una versión perturbada del modelo de desruido. Habilitar STG resultará en una pasada adicional del modelo de desruido; el valor predeterminado de0.0significa que STG está deshabilitado. - modality_scale (
float, opcional, valor predeterminado1.0) — Escala de guía de video para la guía de aislamiento de modalidades de LTX-2.X, donde se desplaza la muestra alejada de una muestra más débil generada por el modelo de desruido con la atención cruzada entre modalidades (de audio a video y de video a audio) deshabilitada, utilizando una estimación similar a CFG. Habilitar la guía de modalidades resultará en una paso de inferencia adicional del modelo de desruido; el valor predeterminado de1.0significa que la guía de modalidades está deshabilitada. - guidance_rescale (
float, opcional, valor predeterminado 0.0) — Factor de rescale de guía propuesto por Common Diffusion Noise Schedules and Sample Steps are Flawedguidance_scalese define comoφen la ecuación 16. de Common Diffusion Noise Schedules and Sample Steps are Flawed. El factor de rescale de guía debe corregir la sobreexposición al utilizar SNR terminal cero. Se usa para la modalidad de video. - audio_guidance_scale (
float, opcional por defectoNone) — Escala de guía de audio para CFG con respecto al prompt negativo. La regla de actualización de CFG es la misma para video y audio, pero pueden usar valores diferentes para la escala de guía. Los autores de LTX-2.X sugieren queaudio_guidance_scaledebe ser mayor en relación conguidance_scalede video (p. ej. para LTX-2.3 sugieren 3.0 para video y 7.0 para audio). Si esNone, por defecto toma el valor de videoguidance_scale. - audio_stg_scale (
float, opcional, valor predeterminadoNone) — Escala de guía de audio para STG. Al igual que con CFG, la regla de actualización de STG es la misma para video y audio. Para LTX-2.3, se sugiere un valor de 1.0 tanto para video como para audio. Si esNone, el valor predeterminado es el valor de videostg_scale. - audio_modality_scale (
float, opcional, valor predeterminadoNone) — Escala de guía de audio para la guía de aislamiento de modalidad de LTX-2.X. Al igual que con CFG, la regla de guía de modalidad es la misma para video y audio. Para LTX-2.3, se sugiere un valor de 3.0 tanto para video como para audio. Si esNone, el valor predeterminado es el valor de videomodality_scale. - audio_guidance_rescale (
float, opcional, valor predeterminadoNone) — Factor de reescalado de guía independiente para la modalidad de audio. Si esNone, toma el valor de videoguidance_rescale. - spatio_temporal_guidance_blocks (
list[int], opcional, valor predeterminadoNone) — Índices de bloques del transformer (con índice cero) en los que se aplica STG. Debe proporcionarse si se utiliza STG (stg_scaleoaudio_stg_scalees mayor que0). Se recomienda un valor de[29]para LTX-2.0 y[28]para LTX-2.3. - noise_scale (
float, opcional, valor predeterminadoNone) — El factor de interpolación entre el ruido aleatorio y los latentes desruidados en cada paso de tiempo. Aplica ruido a loslatentsyaudio_latentsantes de continuar con el desruido. Si no se establece, se inferirá a partir de la programación de sigma. - num_videos_per_prompt (
int, opcional, valor predeterminado 1) — El número de vídeos que se generarán por prompt. - generator (
torch.GeneratoroList[torch.Generator], opcional) — Uno o una lista de generadores de torch para hacer la generación determinista. - latents (
torch.Tensor, opcional) — Latentes ruidosos pregenerados, muestreados de una distribución gaussiana, que se usarán como entradas para la generación de video. Se pueden utilizar para ajustar la misma generación con diferentes prompts. Si no se proporcionan, se generará un tensor de latentes mediante muestreo usando elgeneratoraleatorio suministrado. - audio_latents (
torch.Tensor, opcional) — Latentes ruidosos pregenerados, muestreados de una distribución gaussiana, que se utilizarán como entradas para la generación de audio. Se pueden usar para ajustar la misma generación con diferentes prompts. Si no se proporciona, se generará un tensor de latentes mediante muestreo usando elgeneratoraleatorio suministrado. - prompt_embeds (
torch.Tensor, opcional) — Incrustaciones de texto pregeneradas. Se pueden usar para ajustar fácilmente las entradas de texto, p. ej. ponderación de prompts. Si no se proporcionan, las incrustaciones de texto se generarán a partir del argumento de entradaprompt. - prompt_attention_mask (
torch.Tensor, opcional) — Máscara de atención pregenerada para las incrustaciones de texto. - negative_prompt_embeds (
torch.FloatTensor, opcional) — Incrustaciones de texto negativo pregeneradas. Para PixArt-Sigma, este prompt negativo debe ser "". Si no se proporciona, negative_prompt_embeds se generará a partir del argumento de entradanegative_prompt. - negative_prompt_attention_mask (
torch.FloatTensor, opcional) — Máscara de atención pregenerada para los embeddings de texto negativos. - decode_timestep (
float, por defecto0.0) — El paso de tiempo en el que se decodifica el video generado. - decode_noise_scale (
float, por defectoNone) — El factor de interpolación entre el ruido aleatorio y los latentes desruidos en el paso de decodificación. - use_cross_timestep (
boolopcional, valor predeterminadoTrue) — Indica si se debe utilizar la sigma de la modalidad cruzada (el audio es la modalidad cruzada del video, y viceversa) al calcular los parámetros de modulación de la atención cruzada.Truees el comportamiento de LTX-2.3/2.5;Falsees el comportamiento heredado de LTX-2.0. - system_prompt (
str, opcional, valor predeterminadoNone) — Prompt de sistema opcional para usar en la mejora del prompt. El prompt de sistema será utilizado por el mejorador de prompts (un modelo de generación condicional de Gemma: el componente dedicadoprompt_enhancersi está configurado, o eltext_encoderprincipal en caso contrario) para generar un prompt mejorado a partir delpromptoriginal (y una imagen de condicionamiento si está disponible) con el fin de condicionar la generación. Si no se proporciona y se ha configurado unprompt_enhancerdedicado (LTX-2.5), el valor predeterminado seráLTX2_5_I2V_DEFAULT_SYSTEM_PROMPTsi hay una imagen de condicionamiento disponible, oLTX2_5_T2V_DEFAULT_SYSTEM_PROMPTen caso contrario — consulteenable_prompt_enhancement. - enable_prompt_enhancement (
bool, opcional, valor predeterminadoFalse) — Si se debe ejecutar el mejoramiento del prompt. Es una opción de activación explícita, en línea con los pipelines de referencia de Lightricks. CuandoTrueysystem_promptse omite, LTX-2.5 eligeLTX2_5_I2V_DEFAULT_SYSTEM_PROMPT/LTX2_5_T2V_DEFAULT_SYSTEM_PROMPTsegún si hay una imagen de condicionamiento disponible. - prompt_max_new_tokens (
int, opcional, valor predeterminadoNone) — El número máximo de nuevos tokens que se generarán al realizar la mejora del prompt. Si no se proporciona, se utiliza 600 para unprompt_enhancerdedicado de Gemma 4 (LTX-2.5) o 512 para eltext_encoderde respaldo de Gemma 3 (LTX-2.0/2.3). - prompt_enhancement_kwargs (
dict[str, Any], opcional, valor predeterminadoNone) — Argumentos de palabra clave para la llamada.generatedel mejorador de prompts. Si no se proporcionan, siempre coinciden con el modelo que realiza la mejora:do_sample=False, no_repeat_ngram_size=5(codicioso) cuando se utiliza unprompt_enhancerdedicado (LTX-2.5), odo_sample=True, temperature=0.7para el respaldo detext_encoder(LTX-2.0/2.3). Consulte https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationMixin.generate para más detalles. - prompt_enhancement_seed (
int, opcional, valor predeterminado10) — Semilla aleatoria para cualquier operación aleatoria durante el mejoramiento del prompt. - output_type (
str, opcional, valor predeterminado"pil") — El formato de salida de la imagen generada. Elija entre PIL:PIL.Image.Imageonp.array. - return_dict (
bool, opcional, valor predeterminadoTrue) — Indica si se debe devolver un~pipelines.ltx.LTX2PipelineOutputen lugar de una tupla simple. - attention_kwargs (
dict, opcional) — Un diccionario de kwargs que, si se especifica, se pasa alAttentionProcessordefinido enself.processordentro de diffusers.models.attention_processor. - callback_on_step_end (
Callable, opcional) — Una función que se llama al final de cada paso de desruido durante la inferencia. La función se llama con los siguientes argumentos:callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict).callback_kwargsincluirá una lista de todos los tensores especificados porcallback_on_step_end_tensor_inputs. - callback_on_step_end_tensor_inputs (
List, opcional) — La lista de entradas de tensor para la funcióncallback_on_step_end. Los tensores especificados en la lista se pasarán como argumentocallback_kwargs. Solo podrá incluir variables listadas en el atributo._callback_tensor_inputsde su clase de pipeline. - max_sequence_length (
int, opcional, valor predeterminado1024) — Longitud máxima de la secuencia para usar con elprompt.
Devuelve
~pipelines.ltx.LTX2PipelineOutput o tuple
Si return_dict es True, se devuelve ~pipelines.ltx.LTX2PipelineOutput; en caso contrario, se devuelve una tuple cuyo primer elemento es una lista con las imágenes generadas.
Función invocada al llamar a la pipeline para la generación.
Ejemplos:
>>> import torch
>>> from diffusers import LTX2ConditionPipeline
>>> from diffusers.utils import encode_video
>>> from diffusers.pipelines.ltx2.pipeline_ltx2_condition import LTX2VideoCondition
>>> from diffusers.utils import load_image
>>> pipe = LTX2ConditionPipeline.from_pretrained("Lightricks/LTX-2", torch_dtype=torch.bfloat16)
>>> pipe.enable_model_cpu_offload()
>>> first_image = load_image(
... "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/flf2v_input_first_frame.png"
... )
>>> last_image = load_image(
... "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/flf2v_input_last_frame.png"
... )
>>> first_cond = LTX2VideoCondition(frames=first_image, index=0, strength=1.0)
>>> last_cond = LTX2VideoCondition(frames=last_image, index=-1, strength=1.0)
>>> conditions = [first_cond, last_cond]
>>> prompt = "CG animation style, a small blue bird takes off from the ground, flapping its wings."
>>> negative_prompt = "worst quality, inconsistent motion, blurry, jittery, distorted, static"
>>> frame_rate = 24.0
>>> video = pipe(
... conditions=conditions,
... prompt=prompt,
... negative_prompt=negative_prompt,
... width=768,
... height=512,
... num_frames=121,
... frame_rate=frame_rate,
... num_inference_steps=30,
... guidance_scale=3.0,
... output_type="np",
... return_dict=False,
... )
>>> video = (video * 255).round().astype("uint8")
>>> video = torch.from_numpy(video)
>>> encode_video(
... video[0],
... fps=frame_rate,
... audio=audio[0].float().cpu(),
... audio_sample_rate=pipe.vocoder.config.output_sampling_rate, # should be 24000
... output_path="video.mp4",
... )apply_first_frame_conditioning
< source >( latents: Tensorconditioning_mask: Tensorcondition_latents: listcondition_strengths: listcondition_indices: listlatent_height: intlatent_width: int ) → Tuple[torch.Tensor, torch.Tensor, torch.Tensor]
Parámetros
- latents (
torch.Tensor) — Latentes iniciales empaquetados (patchificados) de forma [batch_size, patch_seq_len, hidden_dim]. - conditioning_mask (
torch.Tensor) — Máscara de condicionamiento inicial empaquetada (patchificada) de forma [batch_size, patch_seq_len, 1] con valores en [0, 1], donde 0 significa que se utilizará por completo la salida del modelo de desruido y 1 significa que se utilizará por completo la condición.
Devuelve
Tuple[torch.Tensor, torch.Tensor, torch.Tensor]
Devuelve una 3-tupla de tensores donde:
- Los latentes de video empaquetados con las condiciones del primer cuadro aplicadas.
- La máscara de condicionamiento empaquetada con las intensidades del primer cuadro aplicadas.
- Los latentes de condicionamiento limpios en las posiciones del primer fotograma (ceros en el resto).
Aplicar el condicionamiento visual del primer cuadro sobrescribiendo los tokens en las posiciones del primer cuadro.
Solo se aplican aquí las condiciones con latent_idx == 0 (coincidiendo con VideoConditionByLatentIndex en la
implementación de referencia). Las condiciones en índices latentes distintos de cero se añaden como tokens de fotograma clave separados mediante prepare_keyframe_extras (coincidiendo con VideoConditionByKeyframeIndex) y se omiten aquí.
encode_prompt
< source >( prompt: str | list[str]negative_prompt: str | list[str] | None = Nonedo_classifier_free_guidance: bool = Truenum_videos_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Nonemax_sequence_length: int = 1024scale_factor: int = 8device: typing.Optional[torch.device] = Nonedtype: typing.Optional[torch.dtype] = None )
Parámetros
- prompt (
strolist[str], opcional) — prompt a codificar - negative_prompt (
strolist[str], opcional) — El prompt o prompts que no deben guiar la generación de la imagen. Si no se define, se debe pasarnegative_prompt_embedsen su lugar. Se ignora cuando no se usa guía (es decir, se ignora siguidance_scalees menor que1). - do_classifier_free_guidance (
bool, opcional, valor predeterminadoTrue) — Si se debe usar classifier free guidance o no. - num_videos_per_prompt (
int, opcional, valor predeterminado 1) — Número de videos que deben generarse por prompt. Dispositivo torch en el que colocar las incrustaciones resultantes - prompt_embeds (
torch.Tensor, opcional) — Incrustaciones de texto pregeneradas. Se pueden usar para ajustar fácilmente las entradas de texto, p. ej. ponderación de prompts. Si no se proporcionan, las incrustaciones de texto se generarán a partir del argumento de entradaprompt. - negative_prompt_embeds (
torch.Tensor, opcional) — Incrustaciones de texto negativo pregeneradas. Se pueden usar para ajustar fácilmente las entradas de texto, p. ej. el ponderado del prompt. Si no se proporciona, negative_prompt_embeds se generará a partir del argumento de entradanegative_prompt. - device — (
torch.device, opcional): dispositivo de torch - dtype — (
torch.dtype, opcional): dtype de torch
Codifica el prompt en estados ocultos del codificador de texto.
enhance_prompt
< source >( prompt: strsystem_prompt: strmax_new_tokens: int | None = Noneseed: int = 10generator: typing.Optional[torch.Generator] = Nonegeneration_kwargs: dict[str, typing.Any] | None = Nonedevice: typing.Union[str, torch.device, NoneType] = Noneimage: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None )
Mejora el prompt proporcionado generando un nuevo prompt a partir de él y de un prompt de sistema, utilizando el mejorador de prompts (un modelo de generación condicional de Gemma). Cuando se proporciona image, el mejorador también se condiciona en ese fotograma de referencia (mejora de estilo I2V / fotograma clave). Utiliza el componente dedicado prompt_enhancer si está configurado (p. ej. LTX-2.5, cuyo codificador de texto no está entrenado para la mejora); de lo contrario, recurre al text_encoder principal (LTX-2.0/2.3, que también actúa como su propio mejorador).
Las plantillas de mensajes, los kwargs de decodificación, la limpieza de la respuesta y la preparación del lado largo de la imagen coinciden con ltx-core / ltx-pipelines (enhance_t2v / enhance_i2v / generate_enhanced_prompt).
prepare_latents
< source >( conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = Nonebatch_size: int = 1num_channels_latents: int = 128height: int = 512width: int = 768num_frames: int = 121frame_rate: float = 24.0noise_scale: float = 1.0dtype: typing.Optional[torch.dtype] = Nonedevice: typing.Optional[torch.device] = Nonegenerator: typing.Optional[torch.Generator] = Nonelatents: typing.Optional[torch.Tensor] = None )
Prepara los latentes de video con ruido, aplicando las condiciones de cuadro.
Las condiciones de primer fotograma (latent_idx == 0) se aplican sobrescribiendo los tokens en las posiciones del primer fotograma
(semántica de VideoConditionByLatentIndex). Las condiciones de fotogramas no iniciales (latent_idx > 0) se concatenan a
la secuencia latente principal con conditioning_mask = strength por token (semántica de VideoConditionByKeyframeIndex) — la fórmula de timestep existente del bucle de desruido t * (1 - conditioning_mask) y la mezcla de posprocesado
denoised * (1 - conditioning_mask) + clean * conditioning_mask las gobiernan a lo largo de los pasos.
Devuelve una 4-tupla:
latents: latentes ruidosos empaquetados (tokens base + cualquier token de fotograma clave concatenado en la dimensión de la secuencia).conditioning_mask: máscara de condicionamiento empaquetada con valores en[0, 1]—1en las posiciones del primer fotograma,strengthen las posiciones de los fotogramas clave y0en el resto.clean_latents: valores de condición limpios en las posiciones condicionadas (ceros en las demás); misma forma quelatents.keyframe_coords: coordenadas posicionales[B, 3, num_keyframe_patches, 2]para añadir avideo_coords, oNonesi no hay condiciones de fotogramas distintos del primero.
preprocess_conditions
< source >( conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = Noneheight: int = 512width: int = 768num_frames: int = 121device: typing.Optional[torch.device] = None ) → Tuple[List[torch.Tensor], List[float], List[int], List[int]]
Parámetros
- conditions (
LTX2VideoConditionoList[LTX2VideoCondition], opcional, valor predeterminadoNone) — Una lista de instancias de condición de imagen/video. - height (
int, opcional, valor predeterminado512) — La altura deseada en píxeles. - width (
int, opcional, valor predeterminado768) — El ancho deseado en píxeles. - num_frames (
int, opcional, valor predeterminado121) — El número de fotogramas deseado en el video generado. - device (
torch.device, opcional, valor predeterminadoNone) — El dispositivo en el que se colocarán los tensores de imagen/vídeo preprocesados.
Devuelve
Tuple[List[torch.Tensor], List[float], List[int], List[int]]
Devuelve una 4-tupla de listas de longitud len(conditions) de la siguiente manera:
- La primera lista es una lista de tensores de video preprocesados de forma [batch_size=1, num_channels, num_frames, height, width].
- La segunda lista es una lista de intensidades de condicionamiento.
- La tercera lista es una lista de índices del espacio latente para cada condición.
- La cuarta lista es una lista de (recortados) recuentos de fotogramas en el espacio de píxeles por condición. Esto es necesario para la semántica de coordenadas de fotogramas clave (los fotogramas clave de un solo píxel tienen una extensión temporal limitada).
Preprocesa las imágenes/videos de condición en tensores de torch.
trim_conditioning_sequence
< source >( start_frame: intsequence_num_frames: inttarget_num_frames: int ) → int
Recorta una secuencia de condicionamiento al número de fotogramas permitido.
LTX2DFRPipeline
clase diffusers.LTX2DFRPipeline
< source >( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLLTX2Videoaudio_vae: AutoencoderKLLTX2Audiotext_encoder: transformers.models.gemma3.modeling_gemma3.Gemma3ForConditionalGeneration | transformers.models.gemma4_unified.modeling_gemma4_unified.Gemma4UnifiedForConditionalGenerationtokenizer: GemmaTokenizerconnectors: LTX2TextConnectorstransformer: LTX2VideoTransformer3DModelvocoder: diffusers.pipelines.ltx2.vocoder.LTX2Vocoder | diffusers.pipelines.ltx2.vocoder.LTX2VocoderWithBWEprocessor: transformers.processing_utils.ProcessorMixin | None = Noneprompt_enhancer: transformers.models.gemma4.modeling_gemma4.Gemma4ForConditionalGeneration | None = Noneduration_head: diffusers.pipelines.ltx2.duration_head.LTX2DurationHead | None = None )
Parámetros
- scheduler (FlowMatchEulerDiscreteScheduler) —
Un scheduler para usar en combinación con
transformerpara desruidar los latentes de video codificados. - vae (AutoencoderKLLTX2Video) — Modelo de Autoencoder Variacional (VAE) para codificar y decodificar videos a partir de y hacia representaciones latentes.
- audio_vae (AutoencoderKLLTX2Audio) — VAE de audio para codificar y decodificar espectrogramas de audio.
- text_encoder (
Gemma3ForConditionalGenerationoGemma4UnifiedForConditionalGeneration) — Modelo de codificador de texto. - tokenizer (
GemmaTokenizeroGemmaTokenizerFast) — Tokenizador para el codificador de texto. - connectors (
LTX2TextConnectors) — Pila de conectores de texto utilizada para adaptar los estados ocultos del codificador de texto para las ramas de video y audio. - transformer (LTX2VideoTransformer3DModel) — Arquitectura de Transformer condicional para desruidar los latentes de video codificados.
- vocoder (
LTX2VocoderoLTX2VocoderWithBWE) — Vocoder para convertir espectrogramas mel en formas de onda de audio. - processor (
ProcessorMixin, opcional) — Procesador utilizado para la mejora de prompts mediante plantillas de chat. - prompt_enhancer (
Gemma4ForConditionalGeneration, opcional) — Modelo dedicado para el mejoramiento de prompts (LTX-2.5). - duration_head (
LTX2DurationHead, opcional) — Predicenum_framesa partir de los embeddings del prompt cuando no se proporcionanum_frames.
Pipeline para una pasada de desruido de Diffusion Fidelity Rendering (DFR) con LTX-2.5.
Un paso genera video y ranuras adicionales de fotogramas clave de un solo píxel, o vuelve a desruidar los latentes proporcionados sembrados desde esas ranuras. Los llamadores componen etapas: esta pipeline a media resolución, LTX2LatentUpsamplePipeline espacialmente, esta pipeline de nuevo a resolución completa con las ranuras ampliadas y una referencia IC-LoRA, y luego LTX2DFRTemporalRefinePipeline para cada ronda de refinamiento temporal. Consulte la documentación de LTX-2 para la receta de 1080p.
Las posiciones de los slots provienen de una cuadrícula de segmentos alineada con el borde temporal del VAE (resolve_canvas). La cuadrícula se rellena hasta un número entero de segmentos; output_type="latent" devuelve esa cuadrícula rellena para que un slot en el relleno no se descarte. Recorte con trim_canvas antes de la decodificación del VAE.
Requiere un transformer cuya configuración establezca use_keyframes_abs_pos_embedding (LTX-2.5 y posteriores) cuando generate_slots=True.
Referencia: https://github.com/Lightricks/LTX-2
__call__
< source >( prompt: str | list[str] = Noneconditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = Noneheight: int = 704width: int = 1216num_frames: int | None = Noneframe_rate: float = 24.0min_seconds: float = 1.0max_seconds: float = 20.0latents: typing.Optional[torch.Tensor] = Noneaudio_latents: typing.Optional[torch.Tensor] = Nonekeyframes_latents: typing.Optional[torch.Tensor] = Nonekeyframe_positions: list[int] | None = Nonereference_latents: typing.Optional[torch.Tensor] = Nonereference_downscale_factor: int = 2guidance_keyframe_latents: typing.Optional[torch.Tensor] = Noneguidance_keyframe_positions: list[int] | None = Noneguidance_keyframe_strength: float = 1.0generate_slots: bool = Truesigmas: list = [1.0, 0.99375, 0.9875, 0.98125, 0.975, 0.909375, 0.725, 0.421875]noise_scale: float | None = Nonefreeze_audio: bool = Falsevideo_tiles: list[diffusers.pipelines.ltx2.dfr_layout.LTX2DFREpilogueTile] | None = Nonenum_videos_per_prompt: int | None = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonedecode_timestep: float | list[float] = 0.0decode_noise_scale: float | list[float] | None = Noneuse_cross_timestep: bool = Truesystem_prompt: str | None = Noneenable_prompt_enhancement: bool = Falseprompt_max_new_tokens: int | None = Noneprompt_enhancement_kwargs: dict[str, typing.Any] | None = Noneprompt_enhancement_seed: int = 10output_type: str = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list = ['latents']max_sequence_length: int = 1024 ) → LTX2DFRPipelineOutput or tuple
Parámetros
- prompt (
stroList[str], opcional) — El prompt o prompts para guiar la generación del video. Si no se define, es necesario pasarprompt_embeds. - conditions (
LTX2VideoConditionoList[LTX2VideoCondition], opcional) — Condiciones de imagen o video a nivel de fotograma.indexes un índice latente ennum_framesde esta pasada. - height (
int, opcional, valor predeterminado704) — La altura en píxeles de este paso, no la de la salida final compuesta. - width (
int, opcional, valor predeterminado1216) — El ancho en píxeles de este paso. - num_frames (
int, opcional) — Número de fotogramas de píxeles de este paso, antes del relleno interno del lienzo. Si no se proporciona, la duración se predice a partir del prompt medianteduration_head. Debe cumplir(num_frames - 1) % 8 == 0. - frame_rate (
float, opcional, valor predeterminado24.0) — fps de reproducción de este pase. El tiempo de RoPE se ajusta a 60 siempre que este valor supere 30. - min_seconds (
float, opcional, valor predeterminado1.0) — Límite inferior de la duración predicha automáticamente cuando se omitenum_frames. - max_seconds (
float, opcional, valor predeterminado20.0) — Límite superior de la duración predicha automáticamente cuando se omitenum_frames. - latents (
torch.Tensor, opcional) — Latentes de video en bruto de(batch_size, channels, frames, height, width)para re-denoise (etapa 2 / epílogo). - audio_latents (
torch.Tensor, opcional) — Latentes de audio sin empaquetar(batch_size, channels, length, mel_bins). La etapa 2 aún ejecuta una pasada de audio conjunta; la forma de onda enviada de una receta compuesta es la de la etapa 1, que el llamador conserva. - keyframes_latents (
torch.Tensor, opcional) — Iniciales de ranuras en bruto de(batch_size, channels, num_slots, height, width), utilizadas cuandogenerate_slots=True. - keyframe_positions (
list[int], opcional) — Índices de fotogramas en píxeles de los slots generados. El valor predeterminado esresolve_canvas(num_frames). - reference_latents (
torch.Tensor, opcional) — Video de referencia IC-LoRA sin procesar (típicamente los fotogramas de la etapa 1). - reference_downscale_factor (
int, opcional, valor predeterminado2) — Relación entre esta pasada y la resolución de referencia, utilizada para escalar las coordenadas de los tokens de referencia. - guidance_keyframe_latents (
torch.Tensor, opcional) — Keyframes de guía fijos en memoria(batch_size, channels, K, height, width)— la ruta de epílogo. No son ranuras generadas. - guidance_keyframe_positions (
list[int], opcional) — Índices de fotogramas en píxeles paraguidance_keyframe_latents. - guidance_keyframe_strength (
float, opcional, valor predeterminado1.0) — Fuerza de condicionamiento para los fotogramas clave de guía fijados. - generate_slots (
bool, opcional, valor predeterminadoTrue) — Añade tokens de slot de fotograma clave generados. El epílogo establece esto enFalsey fijaguidance_keyframe_latentsen su lugar. - sigmas (
list[float], opcional) — Programa de ruido para esta pasada, sin el terminal0.0. - noise_scale (
float, opcional) — Nivel de ruido desde el que comienzan los tokens no condicionados. El valor predeterminado essigmas[0]. - freeze_audio (
bool, opcional, valor predeterminadoFalse) — Mantiene el audio en sigma 0 (epílogo / al seguir una forma de onda de la etapa 1 congelada). - video_tiles (
list[LTX2DFREpilogueTile], opcional) — Mosaico de epílogo desdeepilogue_tiles(), de modo que una resolución demasiado grande para una sola pasada hacia adelante aún pueda procesar un lienzo único: cada paso ejecuta el transformador una vez por mosaico y combina las predicciones. Se resuelve en un plan de tokens contra las propias coordenadas RoPE de esta pasada, que es la razón por la que se pasa el diseño en lugar del plan: las coordenadas solo existen una vez que prepare_latents() se ha ejecutado. - num_videos_per_prompt (
int, opcional, valor predeterminado 1) — El número de vídeos que se generarán por prompt. - generator (
torch.Generatorolist[torch.Generator], opcional) — Generador(es) aleatorio(s) para la reproducibilidad. - prompt_embeds (
torch.Tensor, opcional) — Incrustaciones de texto pregeneradas. - prompt_attention_mask (
torch.Tensor, opcional) — Máscara de atención pregenerada para las incrustaciones de texto. - decode_timestep (
float, por defecto0.0) — El paso de tiempo en el que se decodifica el video generado. - decode_noise_scale (
float, por defectoNone) — Escala de ruido en el momento de la decodificación. - use_cross_timestep (
bool, opcional, valor predeterminadoTrue) — Si se debe usar sigma de multimodalidad cruzada para la modulación de atención cruzada.Truepara LTX-2.3+. - system_prompt (
str, opcional) — Prompt de sistema opcional para mejorar el prompt. Consulteenable_prompt_enhancement. - enable_prompt_enhancement (
bool, opcional, valor predeterminadoFalse) — Si se debe ejecutar el mejoramiento del prompt. - prompt_max_new_tokens (
int, opcional) — El número máximo de nuevos tokens que se generarán al realizar la mejora del prompt. - prompt_enhancement_kwargs (
dict[str, Any], opcional) — Argumentos de palabra clave para la llamada.generatedel mejorador de prompts. - prompt_enhancement_seed (
int, opcional, valor predeterminado10) — Semilla aleatoria para cualquier operación aleatoria durante el mejoramiento del prompt. - output_type (
str, opcional, valor predeterminado"pil") — Formato de salida. Elija"pil","np","pt"o"latent". La salida latente es el lienzo sin recortar. - return_dict (
bool, opcional, valor predeterminadoTrue) — Si se debe devolver un LTX2DFRPipelineOutput o una tupla simple(frames, audio, keyframes, keyframe_positions). - attention_kwargs (
dict, opcional) — Kwargs adicionales que se pasan al procesador de atención. - callback_on_step_end (
Callable, opcional) — Una función que se llama al final de cada paso de desruido. - callback_on_step_end_tensor_inputs (
List, opcional, valor predeterminado["latents"]) — Entradas de tensor para la función de callback. - max_sequence_length (
int, opcional, valor predeterminado1024) — Longitud máxima de la secuencia para el prompt de texto.
Devuelve
LTX2DFRPipelineOutput o tuple
Si return_dict es True, se devuelve LTX2DFRPipelineOutput; en caso contrario, se devuelve una tuple de (video, audio, keyframes, keyframe_positions).
Función invocada al llamar a la pipeline para la generación.
Un paso de desruido a height × width. Componga las etapas en el llamador: esta pipeline a media resolución, remuestreo espacial, esta pipeline de nuevo con latents / keyframes_latents / reference_latents, y luego LTX2DFRTemporalRefinePipeline para cada ronda temporal.
Ejemplos:
>>> import torch
>>> from diffusers import LTX2DFRPipeline
>>> from diffusers.utils import encode_video
>>> pipe = LTX2DFRPipeline.from_pretrained("Lightricks/LTX-2.5-Diffusers", torch_dtype=torch.bfloat16)
>>> pipe.enable_model_cpu_offload()
>>> frame_rate = 24.0
>>> video, audio, _, _ = pipe(
... prompt="A tabby cat stretching in a sunlit window, dust motes drifting in the light",
... height=704,
... width=1216,
... num_frames=121,
... frame_rate=frame_rate,
... output_type="np",
... return_dict=False,
... )
>>> encode_video(
... video[0],
... fps=frame_rate,
... audio=audio[0].float().cpu(),
... audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
... output_path="dfr_output.mp4",
... )denoise
< source >( latents: Tensorconditioning_mask: Tensorclean_latents: Tensorvideo_coords: Tensorkeyframes_mask: Tensorprompt_embeds: Tensoraudio_prompt_embeds: Tensorprompt_attention_mask: Tensorsigmas: listframe_rate: floataudio_latents: Tensorfreeze_audio: bool = Falsevideo_tile_plan: list | None = Nonegenerator: typing.Optional[torch.Generator] = Noneuse_cross_timestep: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Noneprogress_bar = Nonestep_offset: int = 0callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list[str] | None = None )
Parámetros
- sigmas (
list[float]) — Programa de ruido para esta pasada, sin el0.0terminal. - freeze_audio (
bool, opcional, valor predeterminadoFalse) — Mantieneaudio_latentslimpio (timestep/sigma 0, sin paso de Euler de audio) mientras se ejecuta la atención cruzada de audio a video. Se ignora cuandoaudio_latentsesNone. - video_tile_plan (
list, opcional) — Plan de tokens por mosaico devideo_tile_plan[~diffusers.pipelines.ltx2.dfr_layout.video_tile_plan]. Si se proporciona, cada paso ejecuta el transformador una vez por mosaico y combina las predicciones, de modo que el muestreador sigue avanzando un lienzo completo y los mosaicos coinciden en sus superposiciones en cada paso. - generator (
torch.Generator, opcional) — Se reenvía aLTXEulerAncestralRFScheduler.step(). Los mosaicos temporales pasan una semilla por mosaico para que los sorteos ancestrales no compartan un flujo ni consuman el estado que el ruido inicial del siguiente mosaico lee. El Euler destilado no lo lee. - step_offset (
int) — Índice del primer paso de esta pasada dentro de la programación completa del pipeline, utilizado paracallback_on_step_endy la barra de progreso compartida.
Ejecuta una pasada de desruido DFR sobre sigmas y devuelve (latents, audio_latents), ambos aún empaquetados.
El horario destilado se utiliza sin guía libre de clasificador, por lo que se realiza una sola llamada al transformer por paso.
Cada pasada ejecuta ambas ramas, porque la rama de video necesita la atención intermodal incluso donde el audio que
produce se descarta. freeze_audio=True mantiene la rama de audio en sigma 0 (sin paso de Euler) para que el video
pueda seguir haciendo atención cruzada con ella: los mosaicos de refinamiento temporal y el epílogo usan esto para seguir el habla de la etapa 1 sin que
cada mosaico redenoise una realización de audio diferente.
Tras la mezcla de condicionamiento x0, la velocidad es (latents - denoised) / sigma, por lo que un paso de RF x0 = x - σ v recupera el denoised mezclado. La etapa 1 / 2 / el epílogo mantienen FlowMatchEulerDiscreteScheduler y toman ese paso de Euler tal cual. El refinamiento temporal incorpora LTXEulerAncestralRFScheduler (eta=0.5); ese paso re-ruidifica cada token, por lo que la mezcla de condicionamiento se aplica de nuevo después, o los anclajes de costura con strength-0.95 se erosionan.
encode_conditions
< source >( conditions: list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | Noneheight: intwidth: intnum_frames: intdevice: typing.Optional[torch.device] = Nonedtype: typing.Optional[torch.dtype] = Nonegenerator: typing.Optional[torch.Generator] = None )
Preprocesar y codificar con VAE las condiciones de fotogramas, posicionadas por fotograma de píxeles.
Devuelve (pixel_frame_index, latent, strength, num_pixel_frames) por condición, listo para condition_latents de prepare_latents(). La codificación se mantiene separada de la colocación porque las rondas de refinamiento temporal escalan la posición de una condición por 2 ** round y la rebasean por cada mosaico, y no deberían recodificar la misma imagen estática una vez por cada mosaico para hacerlo.
El índice devuelto está en la propia cuadrícula de píxeles de num_frames; llevarlo a un lienzo refinado es responsabilidad del llamador.
encode_prompt
< source >( prompt: str | list[str]num_videos_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonemax_sequence_length: int = 1024device: typing.Optional[torch.device] = Nonedtype: typing.Optional[torch.dtype] = None )
Parámetros
- prompt (
strolist[str], opcional) — prompt a codificar - num_videos_per_prompt (
int, opcional, valor predeterminado 1) — Número de videos que deben generarse por prompt. - prompt_embeds (
torch.Tensor, opcional) — Incrustaciones de texto pregeneradas. Se pueden usar para ajustar fácilmente las entradas de texto, p. ej. ponderación de prompts. Si no se proporcionan, las incrustaciones de texto se generarán a partir del argumento de entradaprompt. - prompt_attention_mask (
torch.Tensor, opcional) — Máscara de atención pregenerada paraprompt_embeds. - device — (
torch.device, opcional): dispositivo de torch - dtype — (
torch.dtype, opcional): dtype de torch
Codifica el prompt en estados ocultos del codificador de texto.
DFR ejecuta el calendario de sigma destilado, que se entrena para usarse sin guía libre de clasificador, por lo que no hay una rama negativa aquí.
enhance_prompt
< source >( prompt: strsystem_prompt: strmax_new_tokens: int | None = Noneseed: int = 10generator: typing.Optional[torch.Generator] = Nonegeneration_kwargs: dict[str, typing.Any] | None = Nonedevice: typing.Union[str, torch.device, NoneType] = Noneimage: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None )
Mejora el prompt proporcionado generando un nuevo prompt a partir de él y de un prompt de sistema, utilizando el mejorador de prompts (un modelo de generación condicional de Gemma). Cuando se proporciona image, el mejorador también se condiciona en ese fotograma de referencia (mejora de estilo I2V / fotograma clave). Utiliza el componente dedicado prompt_enhancer si está configurado (p. ej. LTX-2.5, cuyo codificador de texto no está entrenado para la mejora); de lo contrario, recurre al text_encoder principal (LTX-2.0/2.3, que también actúa como su propio mejorador).
Las plantillas de mensajes, los kwargs de decodificación, la limpieza de la respuesta y la preparación del lado largo de la imagen coinciden con ltx-core / ltx-pipelines (enhance_t2v / enhance_i2v / generate_enhanced_prompt).
prepare_latents
< source >( conditions: list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = Nonecondition_latents: list[tuple[int, torch.Tensor, float, int]] | None = Nonekeyframe_latents: list[tuple[int, torch.Tensor, float]] | None = Noneslot_frame_indices: list[int] | None = Noneslot_initial_latents: typing.Optional[torch.Tensor] = Nonereference_latents: typing.Optional[torch.Tensor] = Nonereference_downscale_factor: int = 1batch_size: int = 1num_channels_latents: int = 128height: int = 512width: int = 768num_frames: int = 121frame_rate: float = 24.0noise_scale: float = 1.0dtype: typing.Optional[torch.dtype] = Nonedevice: typing.Optional[torch.device] = Nonegenerator: typing.Optional[torch.Generator] = Nonelatents: typing.Optional[torch.Tensor] = Nonelatents_normalized: bool = True ) → tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, slice | None]
Parámetros
- conditions (
list[LTX2VideoCondition], opcional) — Condiciones de imagen / video a nivel de fotograma, posicionadas por índice latente. - condition_latents (
list[tuple[int, torch.Tensor, float, int]], opcional) — Sustituto ya codificado deconditions, como(pixel_frame_index, latent, strength, num_pixel_frames). Índice de píxel en lugar de índice de latente, porque una ronda de refinamiento temporal escala la posición de una condición por2 ** roundy el resultado no suele caer en un límite de latente: solo un token de fotograma clave añadido puede situarse allí, y se coloca por píxel.pixel_frame_index == 0sigue significando «reemplazar el primer fotograma». - keyframe_latents (
list[tuple[int, torch.Tensor, float]], opcional) — Guía de fotogramas clave ya codificada como(pixel_frame_index, latent, strength), dondelatenttiene forma(batch_size, num_channels_latents, 1, latent_height, latent_width). Se utiliza en las rondas de refinamiento temporal para fijar los fotogramas clave de costura heredados de la ronda anterior. - slot_frame_indices (
list[int], opcional) — Posiciones de los fotogramas de píxeles de los slots de fotogramas clave generados. - slot_initial_latents (
torch.Tensor, opcional) —(batch_size, num_channels_latents, len(slot_frame_indices), latent_height, latent_width)contenido escrito en los tokens de slot antes de añadir ruido. - reference_latents (
torch.Tensor, opcional) —(batch_size, num_channels_latents, F, H, W)Latente de referencia de IC-LoRA. - reference_downscale_factor (
int, por defecto1) — Relación entre la resolución objetivo y la resolución de referencia. - latents (
torch.Tensor, opcional) —(batch_size, num_channels_latents, F, H, W)contenido inicial para los tokens base. Los latents de la pipeline pública son crudos (no normalizados); paselatents_normalized=Falseen ese límite. Los bucles de mosaico que ya están en el espacio normalizado por VAE dejan el valor predeterminado. - latents_normalized (
bool, por defectoTrue) — Indica silatents,slot_initial_latents,reference_latentsykeyframe_latentsya están normalizados por el VAE. Los bucles internos de mosaicos pasanTrue; cada__call__de la pipeline pasaFalse. - noise_scale (
float, por defecto1.0) — Nivel de ruido al que se inicializan los tokens no condicionados, es decir, la primera sigma del programa.
Devuelve
tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, slice | None]
(latents, conditioning_mask, clean_latents, video_coords, keyframes_mask, slot_token_slice).
slot_token_slice indexa los tokens de los slots de fotogramas clave generados en la secuencia empaquetada, o None cuando no se solicitaron slots.
Prepara los latentes de video empaquetados con ruido para una pasada de desruido DFR.
La secuencia empaquetada se organiza como [base | keyframes | slots | reference]:
- Los tokens base cubren la cuadrícula latente objetivo, inicializados desde
latentscuando se proporcionan. - Las condiciones de fotograma con
index == 0establecen el objetivo limpio en las posiciones del primer fotograma; las que tienenindex > 0y cada entrada dekeyframe_latentsse añaden como tokens de fotograma clave adicionales con una máscara de condicionamiento por token igual a su fuerza. slot_frame_indicesañade un valor de generado de tokens de fotogramas clave por posición, con una máscara de condicionamiento0(totalmente desruidado) y una extensión temporal de RoPE de exactamente un fotograma de píxeles. Estos son los espacios de fotogramas clave que otorgan a DFR sus fotogramas adicionales;slot_initial_latentsinicializa su contenido.reference_latentsañade el latente de media resolución de la etapa 1 como una referencia IC-LoRA completamente limpia, con las coordenadas espaciales escaladas porreference_downscale_factorpara que se mapeen en el espacio de coordenadas objetivo.
Los tokens de condicionamiento añadidos llevan su contenido en clean_latents y un marcador de posición cero en latents, mientras que
los espacios de fotogramas clave llevan su semilla en latents y ceros en clean_latents — los latents devueltos son la
mezcla con ruido de ambos (consulte el paso de ruido al final de este método).
preprocess_conditions
< source >( conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = Noneheight: int = 512width: int = 768num_frames: int = 121device: typing.Optional[torch.device] = None ) → Tuple[List[torch.Tensor], List[float], List[int], List[int]]
Parámetros
- conditions (
LTX2VideoConditionoList[LTX2VideoCondition], opcional, valor predeterminadoNone) — Una lista de instancias de condición de imagen/video. - height (
int, opcional, valor predeterminado512) — La altura deseada en píxeles. - width (
int, opcional, valor predeterminado768) — El ancho deseado en píxeles. - num_frames (
int, opcional, valor predeterminado121) — El número de fotogramas deseado en el video generado. - device (
torch.device, opcional, valor predeterminadoNone) — El dispositivo en el que se colocarán los tensores de imagen/vídeo preprocesados.
Devuelve
Tuple[List[torch.Tensor], List[float], List[int], List[int]]
Devuelve una 4-tupla de listas de longitud len(conditions) de la siguiente manera:
- La primera lista es una lista de tensores de video preprocesados de forma [batch_size=1, num_channels, num_frames, height, width].
- La segunda lista es una lista de intensidades de condicionamiento.
- La tercera lista es una lista de índices del espacio latente para cada condición.
- La cuarta lista es una lista de (recortados) recuentos de fotogramas en el espacio de píxeles por condición. Esto es necesario para la semántica de coordenadas de fotogramas clave (los fotogramas clave de un solo píxel tienen una extensión temporal limitada).
Preprocesa las imágenes/videos de condición en tensores de torch.
rebuild_epilogue_keyframes
< source >( keyframe_latents: Tensordecode_timestep: floatdecode_noise_scale: floatseed: intdevice: devicedtype: dtype ) → torch.Tensor
Parámetros
- keyframe_latents (
torch.Tensor) — Keyframes de transporte en bruto, con forma(batch_size, C, K, H, W), tal como los devolvió una pasada anterior. - seed (
int) — Semilla base; el planoise decodifica bajoseed + 4000 + i, por lo que los píxeles de un plano no dependen de cuántos planos se hayan decodificado antes que él.
Devuelve
torch.Tensor
Latentes (batch_size, C, K, 2H, 2W) sin procesar, listos para pasarse directamente de nuevo como
guidance_keyframe_latents.
Re-codifica los fotogramas clave de arrastre al doble de su resolución mediante RGB.
Estas son las imágenes que las rondas de refinamiento ya han definido, por lo que el epílogo las recibe en lugar de generarlas. Decodificar a píxeles, escalar x2 con Lanczos y codificar de nuevo preserva la imagen mientras la sitúa en la cuadrícula de salida, lo que permite al epícolo fijarla completamente limpia.
Cada plano se decodifica como su propio clip de un solo fotograma. La VAE es causal, por lo que una decodificación apilada permitiría que los planos vecinos se mezclen entre sí: son imágenes estáticas independientes, no una secuencia.
trim_conditioning_sequence
< source >( start_frame: intsequence_num_frames: inttarget_num_frames: int ) → int
Recorta una secuencia de condicionamiento al número de fotogramas permitido.
LTX2DFRTemporalRefinePipeline
clase diffusers.LTX2DFRTemporalRefinePipeline
< source >( scheduler: LTXEulerAncestralRFSchedulervae: AutoencoderKLLTX2Videoaudio_vae: AutoencoderKLLTX2Audiotext_encoder: transformers.models.gemma3.modeling_gemma3.Gemma3ForConditionalGeneration | transformers.models.gemma4_unified.modeling_gemma4_unified.Gemma4UnifiedForConditionalGenerationtokenizer: GemmaTokenizerconnectors: LTX2TextConnectorstransformer: LTX2VideoTransformer3DModelvocoder: diffusers.pipelines.ltx2.vocoder.LTX2Vocoder | diffusers.pipelines.ltx2.vocoder.LTX2VocoderWithBWEtemporal_latent_upsampler: LTX2LatentUpsamplerModel )
Parámetros
- scheduler (
LTXEulerAncestralRFScheduler) — Programador Euler ancestral en la parametrización de flujo rectificado. Constrúyalo coneta=0.5para coincidir con la receta temporal de DFR. - vae (AutoencoderKLLTX2Video) — Modelo de Autoencoder Variacional (VAE) para codificar y decodificar videos a partir de y hacia representaciones latentes.
- audio_vae (AutoencoderKLLTX2Audio) — VAE de audio para codificar y decodificar espectrogramas de audio.
- text_encoder (
Gemma3ForConditionalGenerationoGemma4UnifiedForConditionalGeneration) — Modelo de codificador de texto. - tokenizer (
GemmaTokenizeroGemmaTokenizerFast) — Tokenizador para el codificador de texto. - connectors (
LTX2TextConnectors) — Pila de conectores de texto utilizada para adaptar los estados ocultos del codificador de texto para las ramas de video y audio. - transformer (LTX2VideoTransformer3DModel) — Arquitectura de Transformer condicional para desruidar los latentes de video codificados.
- vocoder (
LTX2VocoderoLTX2VocoderWithBWE) — Vocoder para convertir espectrogramas mel en formas de onda de audio. - temporal_latent_upsampler (
LTX2LatentUpsamplerModel) — Upsampler temporal x2 de latentes aplicado al inicio de la ronda.
Una ronda de refinamiento temporal de DFR: interpolar el lienzo x2 en el tiempo, aplicar mosaico en las costuras de los fotogramas clave, desruidar de forma ancestral cada mosaico, unir descartando la entrada del mosaico posterior y fusionar la bolsa del fotograma clave de arrastre.
El programador es LTXEulerAncestralRFScheduler (con eta=0.5 por defecto). La etapa 1 / 2 / el epílogo espacial permanecen en FlowMatchEulerDiscreteScheduler a través de LTX2DFRPipeline. Llama a este pipeline una vez por ronda; el llamador hace un bucle para 2x / 4x.
Los latents / keyframes_latents / audio_latents entrantes son crudos (no normalizados), coincidiendo con LTX2Pipeline. keyframe_positions deben ser las posiciones devueltas por la pasada anterior; no pueden volver a derivarse del
num_frames original después de que se haya ejecutado una ronda.
__call__
< source >( prompt: str | list[str] = Nonelatents: Tensor = Nonekeyframes_latents: Tensor = Nonekeyframe_positions: list = Noneaudio_latents: Tensor = Noneconditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = Noneheight: int = 704width: int = 1216num_frames: int = 121frame_rate: float = 24.0source_seconds: float | None = Nonecondition_num_frames: int | None = Noneround_index: int = 1sigmas: list = [0.975, 0.909375, 0.725, 0.421875]noise_scale: float | None = Nonegenerator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonedecode_timestep: float | list[float] = 0.0decode_noise_scale: float | list[float] | None = Noneuse_cross_timestep: bool = Trueoutput_type: str = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list = ['latents']max_sequence_length: int = 1024 ) → LTX2DFRPipelineOutput or tuple
Parámetros
- prompt (
stroList[str], opcional) — El prompt o prompts para guiar la generación del video. Si no se define, es necesario pasarprompt_embeds. - latents (
torch.Tensor) — Latentes de video crudos del lienzo de entrada,(batch_size, channels, frames, height, width). - keyframes_latents (
torch.Tensor) — Keyframes de carry en bruto(batch_size, channels, K, height, width)de la pasada anterior. - keyframe_positions (
list[int]) — Índices de fotogramas en píxeles dekeyframes_latentsen el lienzo de entrada. - audio_latents (
torch.Tensor) — Audio de la etapa 1 congelado, desempaquetado y denormalizado. A cada tesela se le entrega la porción que cubre su ventana de reproducción; el audio devuelto es esta forma de onda, no una redenoise por tesela. - conditions (
LTX2VideoConditionoList[LTX2VideoCondition], opcional) — Condiciones a nivel de cuadro indexadas encondition_num_frames(la solicitud original). Cada ronda escala la posición de píxeles de una condición por2 ** round_index. - height (
int, opcional, valor predeterminado704) — Altura en píxeles de este paso (igual que la del video entrante). - width (
int, opcional, valor predeterminado1216) — Ancho en píxeles de este paso. - num_frames (
int, opcional, valor predeterminado121) — Número de fotogramas de píxeles del lienzo de entrada (sin recortar). - frame_rate (
float, opcional, valor predeterminado24.0) — fps de reproducción de la entrada. El redondeo lo duplica. - source_seconds (
float, opcional) — Duración del audio de la etapa 1 congelada. El valor predeterminado esnum_frames / frame_rate, que es correcto para la primera ronda; las rondas posteriores deben pasar la duración original de la etapa 1 para que los mosaicos no se desplacen. - condition_num_frames (
int, opcional) — El valor original denum_framesutilizado para codificar lasconditions. El valor predeterminado esnum_frames. Después del relleno o de una ronda previa, pase la solicitud original para queindex=-1no se envuelva al final relleno. - round_index (
int, opcional, valor predeterminado1) — Número de ronda basado en 1. Las semillas de ruido ancestral se asignan comoseed + 1000 * round_index + tile, y las condiciones se escalan por2 ** round_index. - sigmas (
list[float], opcional) — Programa destilado para los mosaicos de esta ronda, sin el0.0terminal. - noise_scale (
float, opcional) — Nivel de ruido desde el que comienzan los tokens no condicionados. El valor predeterminado essigmas[0]. - generator (
torch.Generatorolist[torch.Generator], opcional) — Generador(es) aleatorio(s) para la reproducibilidad. Los muestreos ancestrales utilizan una semilla independiente por tesela derivada deinitial_seed()de este generador. - prompt_embeds (
torch.Tensor, opcional) — Incrustaciones de texto pregeneradas. - prompt_attention_mask (
torch.Tensor, opcional) — Máscara de atención pregenerada para las incrustaciones de texto. - decode_timestep (
float, por defecto0.0) — El paso de tiempo en el que se decodifica el video generado. - decode_noise_scale (
float, por defectoNone) — Escala de ruido en el momento de la decodificación. - use_cross_timestep (
bool, opcional, valor predeterminadoTrue) — Si se debe usar sigma de multimodalidad cruzada para la modulación de atención cruzada.Truepara LTX-2.3+. - output_type (
str, opcional, valor predeterminado"pil") — Formato de salida. Elija"pil","np","pt"o"latent". La salida latente es el lienzo sin recortar. - return_dict (
bool, opcional, valor predeterminadoTrue) — Si se debe devolver un LTX2DFRPipelineOutput o una tupla simple(frames, audio, keyframes, keyframe_positions). - attention_kwargs (
dict, opcional) — Kwargs adicionales que se pasan al procesador de atención. - callback_on_step_end (
Callable, opcional) — Una función que se llama al final de cada paso de desruido, en todas las baldosas. - callback_on_step_end_tensor_inputs (
List, opcional, valor predeterminado["latents"]) — Entradas de tensor para la función de callback. - max_sequence_length (
int, opcional, valor predeterminado1024) — Longitud máxima de la secuencia para el prompt de texto.
Devuelve
LTX2DFRPipelineOutput o tuple
Si return_dict es True, se devuelve LTX2DFRPipelineOutput; en caso contrario, se devuelve una tuple de (video, audio, keyframes, keyframe_positions).
Ejecutar una ronda de refinamiento temporal.
Ejemplos:
>>> import torch
>>> from diffusers import LTX2DFRPipeline, LTX2DFRTemporalRefinePipeline, LTXEulerAncestralRFScheduler
>>> from diffusers.models.latent_upscaler import LTX2LatentUpsamplerModel
>>> pipe = LTX2DFRPipeline.from_pretrained("Lightricks/LTX-2.5-Diffusers", torch_dtype=torch.bfloat16)
>>> temporal_upsampler = LTX2LatentUpsamplerModel.from_pretrained(
... "path/to/converted/temporal_latent_upsampler", torch_dtype=torch.bfloat16
... )
>>> temporal_pipe = LTX2DFRTemporalRefinePipeline(
... scheduler=LTXEulerAncestralRFScheduler(eta=0.5),
... vae=pipe.vae,
... audio_vae=pipe.audio_vae,
... text_encoder=pipe.text_encoder,
... tokenizer=pipe.tokenizer,
... connectors=pipe.connectors,
... transformer=pipe.transformer,
... vocoder=pipe.vocoder,
... temporal_latent_upsampler=temporal_upsampler,
... )
>>> # `out` is a prior DFR pass at the same spatial size, `return_dict=True`.
>>> out = temporal_pipe(
... latents=out.frames,
... keyframes_latents=out.keyframes,
... keyframe_positions=out.keyframe_positions,
... audio_latents=out.audio,
... prompt="A tabby cat stretching in a sunlit window",
... height=1088,
... width=1920,
... num_frames=121,
... output_type="latent",
... )denoise
< source >( latents: Tensorconditioning_mask: Tensorclean_latents: Tensorvideo_coords: Tensorkeyframes_mask: Tensorprompt_embeds: Tensoraudio_prompt_embeds: Tensorprompt_attention_mask: Tensorsigmas: listframe_rate: floataudio_latents: Tensorfreeze_audio: bool = Falsevideo_tile_plan: list | None = Nonegenerator: typing.Optional[torch.Generator] = Noneuse_cross_timestep: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Noneprogress_bar = Nonestep_offset: int = 0callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list[str] | None = None )
Parámetros
- sigmas (
list[float]) — Programa de ruido para esta pasada, sin el0.0terminal. - freeze_audio (
bool, opcional, valor predeterminadoFalse) — Mantieneaudio_latentslimpio (timestep/sigma 0, sin paso de Euler de audio) mientras se ejecuta la atención cruzada de audio a video. Se ignora cuandoaudio_latentsesNone. - video_tile_plan (
list, opcional) — Plan de tokens por mosaico devideo_tile_plan[~diffusers.pipelines.ltx2.dfr_layout.video_tile_plan]. Si se proporciona, cada paso ejecuta el transformador una vez por mosaico y combina las predicciones, de modo que el muestreador sigue avanzando un lienzo completo y los mosaicos coinciden en sus superposiciones en cada paso. - generator (
torch.Generator, opcional) — Se reenvía aLTXEulerAncestralRFScheduler.step(). Los mosaicos temporales pasan una semilla por mosaico para que los sorteos ancestrales no compartan un flujo ni consuman el estado que el ruido inicial del siguiente mosaico lee. El Euler destilado no lo lee. - step_offset (
int) — Índice del primer paso de esta pasada dentro de la programación completa del pipeline, utilizado paracallback_on_step_endy la barra de progreso compartida.
Ejecuta una pasada de desruido DFR sobre sigmas y devuelve (latents, audio_latents), ambos aún empaquetados.
El horario destilado se utiliza sin guía libre de clasificador, por lo que se realiza una sola llamada al transformer por paso.
Cada pasada ejecuta ambas ramas, porque la rama de video necesita la atención intermodal incluso donde el audio que
produce se descarta. freeze_audio=True mantiene la rama de audio en sigma 0 (sin paso de Euler) para que el video
pueda seguir haciendo atención cruzada con ella: los mosaicos de refinamiento temporal y el epílogo usan esto para seguir el habla de la etapa 1 sin que
cada mosaico redenoise una realización de audio diferente.
Tras la mezcla de condicionamiento x0, la velocidad es (latents - denoised) / sigma, por lo que un paso de RF x0 = x - σ v recupera el denoised mezclado. La etapa 1 / 2 / el epílogo mantienen FlowMatchEulerDiscreteScheduler y toman ese paso de Euler tal cual. El refinamiento temporal incorpora LTXEulerAncestralRFScheduler (eta=0.5); ese paso re-ruidifica cada token, por lo que la mezcla de condicionamiento se aplica de nuevo después, o los anclajes de costura con strength-0.95 se erosionan.
encode_conditions
< source >( conditions: list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | Noneheight: intwidth: intnum_frames: intdevice: typing.Optional[torch.device] = Nonedtype: typing.Optional[torch.dtype] = Nonegenerator: typing.Optional[torch.Generator] = None )
Preprocesar y codificar con VAE las condiciones de fotogramas, posicionadas por fotograma de píxeles.
Devuelve (pixel_frame_index, latent, strength, num_pixel_frames) por condición, listo para condition_latents de prepare_latents(). La codificación se mantiene separada de la colocación porque las rondas de refinamiento temporal escalan la posición de una condición por 2 ** round y la rebasean por cada mosaico, y no deberían recodificar la misma imagen estática una vez por cada mosaico para hacerlo.
El índice devuelto está en la propia cuadrícula de píxeles de num_frames; llevarlo a un lienzo refinado es responsabilidad del llamador.
encode_prompt
< source >( prompt: str | list[str]num_videos_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonemax_sequence_length: int = 1024device: typing.Optional[torch.device] = Nonedtype: typing.Optional[torch.dtype] = None )
Parámetros
- prompt (
strolist[str], opcional) — prompt a codificar - num_videos_per_prompt (
int, opcional, valor predeterminado 1) — Número de videos que deben generarse por prompt. - prompt_embeds (
torch.Tensor, opcional) — Incrustaciones de texto pregeneradas. Se pueden usar para ajustar fácilmente las entradas de texto, p. ej. ponderación de prompts. Si no se proporcionan, las incrustaciones de texto se generarán a partir del argumento de entradaprompt. - prompt_attention_mask (
torch.Tensor, opcional) — Máscara de atención pregenerada paraprompt_embeds. - device — (
torch.device, opcional): dispositivo de torch - dtype — (
torch.dtype, opcional): dtype de torch
Codifica el prompt en estados ocultos del codificador de texto.
DFR ejecuta el calendario de sigma destilado, que se entrena para usarse sin guía libre de clasificador, por lo que no hay una rama negativa aquí.
prepare_latents
< source >( conditions: list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = Nonecondition_latents: list[tuple[int, torch.Tensor, float, int]] | None = Nonekeyframe_latents: list[tuple[int, torch.Tensor, float]] | None = Noneslot_frame_indices: list[int] | None = Noneslot_initial_latents: typing.Optional[torch.Tensor] = Nonereference_latents: typing.Optional[torch.Tensor] = Nonereference_downscale_factor: int = 1batch_size: int = 1num_channels_latents: int = 128height: int = 512width: int = 768num_frames: int = 121frame_rate: float = 24.0noise_scale: float = 1.0dtype: typing.Optional[torch.dtype] = Nonedevice: typing.Optional[torch.device] = Nonegenerator: typing.Optional[torch.Generator] = Nonelatents: typing.Optional[torch.Tensor] = Nonelatents_normalized: bool = True ) → tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, slice | None]
Parámetros
- conditions (
list[LTX2VideoCondition], opcional) — Condiciones de imagen / video a nivel de fotograma, posicionadas por índice latente. - condition_latents (
list[tuple[int, torch.Tensor, float, int]], opcional) — Sustituto ya codificado deconditions, como(pixel_frame_index, latent, strength, num_pixel_frames). Índice de píxel en lugar de índice de latente, porque una ronda de refinamiento temporal escala la posición de una condición por2 ** roundy el resultado no suele caer en un límite de latente: solo un token de fotograma clave añadido puede situarse allí, y se coloca por píxel.pixel_frame_index == 0sigue significando «reemplazar el primer fotograma». - keyframe_latents (
list[tuple[int, torch.Tensor, float]], opcional) — Guía de fotogramas clave ya codificada como(pixel_frame_index, latent, strength), dondelatenttiene forma(batch_size, num_channels_latents, 1, latent_height, latent_width). Se utiliza en las rondas de refinamiento temporal para fijar los fotogramas clave de costura heredados de la ronda anterior. - slot_frame_indices (
list[int], opcional) — Posiciones de los fotogramas de píxeles de los slots de fotogramas clave generados. - slot_initial_latents (
torch.Tensor, opcional) —(batch_size, num_channels_latents, len(slot_frame_indices), latent_height, latent_width)contenido escrito en los tokens de slot antes de añadir ruido. - reference_latents (
torch.Tensor, opcional) —(batch_size, num_channels_latents, F, H, W)Latente de referencia de IC-LoRA. - reference_downscale_factor (
int, por defecto1) — Relación entre la resolución objetivo y la resolución de referencia. - latents (
torch.Tensor, opcional) —(batch_size, num_channels_latents, F, H, W)contenido inicial para los tokens base. Los latents de la pipeline pública son crudos (no normalizados); paselatents_normalized=Falseen ese límite. Los bucles de mosaico que ya están en el espacio normalizado por VAE dejan el valor predeterminado. - latents_normalized (
bool, por defectoTrue) — Indica silatents,slot_initial_latents,reference_latentsykeyframe_latentsya están normalizados por el VAE. Los bucles internos de mosaicos pasanTrue; cada__call__de la pipeline pasaFalse. - noise_scale (
float, por defecto1.0) — Nivel de ruido al que se inicializan los tokens no condicionados, es decir, la primera sigma del programa.
Devuelve
tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, slice | None]
(latents, conditioning_mask, clean_latents, video_coords, keyframes_mask, slot_token_slice).
slot_token_slice indexa los tokens de los slots de fotogramas clave generados en la secuencia empaquetada, o None cuando no se solicitaron slots.
Prepara los latentes de video empaquetados con ruido para una pasada de desruido DFR.
La secuencia empaquetada se organiza como [base | keyframes | slots | reference]:
- Los tokens base cubren la cuadrícula latente objetivo, inicializados desde
latentscuando se proporcionan. - Las condiciones de fotograma con
index == 0establecen el objetivo limpio en las posiciones del primer fotograma; las que tienenindex > 0y cada entrada dekeyframe_latentsse añaden como tokens de fotograma clave adicionales con una máscara de condicionamiento por token igual a su fuerza. slot_frame_indicesañade un valor de generado de tokens de fotogramas clave por posición, con una máscara de condicionamiento0(totalmente desruidado) y una extensión temporal de RoPE de exactamente un fotograma de píxeles. Estos son los espacios de fotogramas clave que otorgan a DFR sus fotogramas adicionales;slot_initial_latentsinicializa su contenido.reference_latentsañade el latente de media resolución de la etapa 1 como una referencia IC-LoRA completamente limpia, con las coordenadas espaciales escaladas porreference_downscale_factorpara que se mapeen en el espacio de coordenadas objetivo.
Los tokens de condicionamiento añadidos llevan su contenido en clean_latents y un marcador de posición cero en latents, mientras que
los espacios de fotogramas clave llevan su semilla en latents y ceros en clean_latents — los latents devueltos son la
mezcla con ruido de ambos (consulte el paso de ruido al final de este método).
preprocess_conditions
< source >( conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = Noneheight: int = 512width: int = 768num_frames: int = 121device: typing.Optional[torch.device] = None ) → Tuple[List[torch.Tensor], List[float], List[int], List[int]]
Parámetros
- conditions (
LTX2VideoConditionoList[LTX2VideoCondition], opcional, valor predeterminadoNone) — Una lista de instancias de condición de imagen/video. - height (
int, opcional, valor predeterminado512) — La altura deseada en píxeles. - width (
int, opcional, valor predeterminado768) — El ancho deseado en píxeles. - num_frames (
int, opcional, valor predeterminado121) — El número de fotogramas deseado en el video generado. - device (
torch.device, opcional, valor predeterminadoNone) — El dispositivo en el que se colocarán los tensores de imagen/vídeo preprocesados.
Devuelve
Tuple[List[torch.Tensor], List[float], List[int], List[int]]
Devuelve una 4-tupla de listas de longitud len(conditions) de la siguiente manera:
- La primera lista es una lista de tensores de video preprocesados de forma [batch_size=1, num_channels, num_frames, height, width].
- La segunda lista es una lista de intensidades de condicionamiento.
- La tercera lista es una lista de índices del espacio latente para cada condición.
- La cuarta lista es una lista de (recortados) recuentos de fotogramas en el espacio de píxeles por condición. Esto es necesario para la semántica de coordenadas de fotogramas clave (los fotogramas clave de un solo píxel tienen una extensión temporal limitada).
Preprocesa las imágenes/videos de condición en tensores de torch.
trim_conditioning_sequence
< source >( start_frame: intsequence_num_frames: inttarget_num_frames: int ) → int
Recorta una secuencia de condicionamiento al número de fotogramas permitido.
Ejecuta upsampler en los latentes normalizados, realizando un recorrido de ida y vuelta a través del espacio latente crudo de la VAE, como espera.
LTX2DFRPipelineOutput
clase diffusers.LTX2DFRPipelineOutput
< source >( frames: Tensoraudio: Tensorkeyframes: typing.Optional[torch.Tensor] = Nonekeyframe_positions: list[int] | None = None )
Parámetros
- frames (
torch.Tensor,np.ndarrayo list[list[PIL.Image.Image]]) — Vídeo desruidoado. La salida latente es el lienzo sin recortar, con forma(batch_size, num_channels, latent_frames, latent_height, latent_width). - audio (
torch.Tensor,np.ndarray) — Latentes de audio o forma de onda correspondientes. - keyframes (
torch.Tensor, opcional) — Latentes de fotogramas clave generados o transportados, de forma(batch_size, num_channels, num_keyframes, latent_height, latent_width).Nonecuandooutput_type != "latent", o cuando la pasada no produjo ranuras (p. ej., un epílogo en mosaico). - keyframe_positions (
list[int], opcional) — Índice de cuadro en píxeles de cada keyframe en el lienzo de esta pasada;Nonesiempre quekeyframesseaNone. Después de una pasada temporal, estos no pueden volver a derivarse del valor original denum_framesy deben pasarse a la etapa siguiente.
Clase de salida para los pipelines de DFR.
LTX2LatentUpsamplePipeline
clase diffusers.LTX2LatentUpsamplePipeline
< source >( vae: AutoencoderKLLTX2Videolatent_upsampler: LTX2LatentUpsamplerModel )
__call__
< source >( video: list[typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]] | None = Noneheight: int = 512width: int = 768num_frames: int = 121spatial_patch_size: int = 1temporal_patch_size: int = 1latents: typing.Optional[torch.Tensor] = Nonelatents_normalized: bool = Falsedecode_timestep: float | list[float] = 0.0decode_noise_scale: float | list[float] | None = Noneadain_factor: float = 0.0tone_map_compression_ratio: float = 0.0generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Noneoutput_type: str | None = 'pil'return_dict: bool = True ) → ~pipelines.ltx.LTXPipelineOutput or tuple
Parámetros
- video (
list[PipelineImageInput], opcional) — El video que se va a aumentar de resolución (por ejemplo, la salida de la primera etapa de LTX 2.0). Si no se proporciona, se debe proporcionarlatents. - height (
int, opcional, valor predeterminado512) — La altura en píxeles del video de entrada (no del video generado, que tendrá una resolución mayor). - width (
int, opcional, valor predeterminado768) — El ancho en píxeles del video de entrada (no del video generado, que tendrá una resolución mayor). - num_frames (
int, opcional, valor predeterminado121) — El número de fotogramas en el video de entrada. - spatial_patch_size (
int, opcional, valor predeterminado1) — El tamaño de parche espacial de los latentes del video. Se utiliza cuando se proporcionalatentssi es necesario el desempaquetado. - temporal_patch_size (
int, opcional, valor predeterminado1) — El tamaño del parche temporal de los latentes del video. Se utiliza cuando se proporcionalatentssi es necesario el desempaquetado. - latents (
torch.Tensor, opcional) — Latentes de video pregenerados. Se puede proporcionar en lugar del argumentovideo. Puede ser una secuencia de parches de forma(batch_size, seq_len, hidden_dim)o un latente de video de forma(batch_size, latent_channels, latent_frames, latent_height, latent_width). - latents_normalized (
bool, opcional, valor predeterminadoFalse) — Si se proporcionanlatents, indica si loslatentsestán normalizados usando la media y la desviación estándar latente del VAE. SiTrue, loslatentsse desnormalizarán antes de ser proporcionados al amplificador latente. - decode_timestep (
float, por defecto0.0) — El paso de tiempo en el que se decodifica el video generado. - decode_noise_scale (
float, por defectoNone) — El factor de interpolación entre el ruido aleatorio y los latentes desruidos en el paso de decodificación. - adain_factor (
float, opcional, valor predeterminado0.0) — Factor de mezcla de Normalización de Instancia Adaptativa (AdaIN) entre los latentes ampliados y los originales. Debe estar en el rango [-10.0, 10.0]; si se proporciona 0.0 (el valor predeterminado), significa que no se realiza AdaIN. - tone_map_compression_ratio (
float, opcional, valor predeterminado0.0) — La intensidad de compresión para el mapeo de tonos, que reducirá el rango dinámico de los valores latentes. Esto es útil para regularizar latentes de alta varianza o para condicionar las salidas durante la generación. Debe estar en [0, 1], donde 0.0 (el valor predeterminado) significa que no se aplica el mapeo de tonos y 1.0 corresponde al efecto de compresión completo. - generator (
torch.Generatorolist[torch.Generator], opcional) — Un generador o una lista de generadores de torch para hacer la generación determinista. - output_type (
str, opcional, valor predeterminado"pil") — El formato de salida de la imagen generada. Elija entre PIL:PIL.Image.Imageonp.array. - return_dict (
bool, opcional, valor predeterminadoTrue) — Indica si se debe devolver un~pipelines.ltx.LTXPipelineOutputen lugar de una tupla simple.
Devuelve
~pipelines.ltx.LTXPipelineOutput o tuple
Si return_dict es True, se devuelve ~pipelines.ltx.LTXPipelineOutput; en caso contrario, se devuelve una tuple cuyo primer elemento es el video ampliado.
Función invocada al llamar a la pipeline para la generación.
Ejemplos:
>>> import torch
>>> from diffusers import LTX2ImageToVideoPipeline, LTX2LatentUpsamplePipeline
>>> from diffusers.utils import encode_video
>>> from diffusers.models.latent_upscaler import LTX2LatentUpsamplerModel
>>> from diffusers.utils import load_image
>>> pipe = LTX2ImageToVideoPipeline.from_pretrained("Lightricks/LTX-2", torch_dtype=torch.bfloat16)
>>> pipe.enable_model_cpu_offload()
>>> image = load_image(
... "https://huggingface.co/datasets/a-r-r-o-w/tiny-meme-dataset-captioned/resolve/main/images/8.png"
... )
>>> prompt = "A young girl stands calmly in the foreground, looking directly at the camera, as a house fire rages in the background."
>>> negative_prompt = "worst quality, inconsistent motion, blurry, jittery, distorted"
>>> frame_rate = 24.0
>>> video, audio = pipe(
... image=image,
... prompt=prompt,
... negative_prompt=negative_prompt,
... width=768,
... height=512,
... num_frames=121,
... frame_rate=frame_rate,
... num_inference_steps=40,
... guidance_scale=4.0,
... output_type="pil",
... return_dict=False,
... )
>>> latent_upsampler = LTX2LatentUpsamplerModel.from_pretrained(
... "Lightricks/LTX-2", subfolder="latent_upsampler", torch_dtype=torch.bfloat16
... )
>>> upsample_pipe = LTX2LatentUpsamplePipeline(vae=pipe.vae, latent_upsampler=latent_upsampler)
>>> upsample_pipe.vae.enable_tiling()
>>> upsample_pipe.to(device="cuda", dtype=torch.bfloat16)
>>> video = upsample_pipe(
... video=video,
... width=768,
... height=512,
... output_type="np",
... return_dict=False,
... )[0]
>>> encode_video(
... video[0],
... fps=frame_rate,
... audio=audio[0].float().cpu(),
... audio_sample_rate=pipe.vocoder.config.output_sampling_rate, # should be 24000
... output_path="video.mp4",
... )adain_filter_latent
< source >( latents: Tensorreference_latents: Tensorfactor: float = 1.0 ) → torch.Tensor
Parámetros
- latents (
torch.Tensor) — Latentes de entrada para normalizar - reference_latents (
torch.Tensor) — Los latentes de referencia que proporcionan las estadísticas de estilo. - factor (
float) — Factor de mezcla entre el latente original y el transformado. Rango: -10.0 a 10.0, Predeterminado: 1.0
Devuelve
torch.Tensor
El tensor latente transformado
Aplica la Normalización Adaptativa de Instancia (AdaIN) a un tensor latente en función de las estadísticas de un tensor latente de referencia.
Aplica una función de mapeo de tono no lineal a los valores latentes para reducir su rango dinámico de manera perceptualmente suave, utilizando una compresión basada en una sigmoide.
Esto es útil para regularizar latentes de alta varianza o para condicionar las salidas durante la generación, especialmente al controlar el comportamiento dinámico con un factor de compression.
LTX2VideoDiffusionDecodePipeline
clase diffusers.LTX2VideoDiffusionDecodePipeline
< source >( diffusion_decoder: LTX2VideoDiffusionDecoderModelschedulervae: AutoencoderKLLTX2Video = None )
Parámetros
- diffusion_decoder (LTX2VideoDiffusionDecoderModel) — El decodificador de video de difusión.
- scheduler (FlowMatchEulerDiscreteScheduler) — Programador que controla los pasos de desruido del decodificador.
- vae (AutoencoderKLLTX2Video, opcional) — Solo se consulta para las estadísticas latentes utilizadas para desnormalizar. Si se omite, el pipeline recurre a los valores predeterminados de LTX-2, por lo que un flujo de trabajo solo de decodificación no tiene que cargar un segundo autoencoder.
Decodifica los latentes de video de LTX-2 con el decodificador de difusión introducido en LTX-2.5.
A diferencia de un decodificador convolucional, este es en sí mismo un pequeño modelo de difusión: desruidifica píxeles condicionados en un volumen de contexto construido a partir de los latentes, por lo que necesita un programador y un generador. Combínalo con cualquier ejecución de la pipeline LTX-2 con output_type="latent", pasando denormalize=False ya que esa ruta ya aplicó las estadísticas de los latentes.
__call__
< source >( latents: Tensorgenerator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Noneoutput_type: str = 'pil'return_dict: bool = Truedenormalize: bool = True ) → LTX2VideoDecodeOutput or tuple
Parámetros
- latents (
torch.Tensor) — Latentes de forma(B, C, F, H, W). Tenga en cuenta que una ejecución de la pipeline LTX-2 conoutput_type="latent"devuelve latentes que ya están denormalizados, por lo que pasedenormalize=Falsepara esos. - generator (
torch.Generator, opcional) — El decodificador muestrea el ruido que desruidiza, por lo que debe pasar un generador para que la decodificación sea reproducible. - output_type (
str, opcional, valor predeterminado"pil") — El formato de salida del video decodificado. Elija entre"pil","np","pt"y"latent". - return_dict (
bool, opcional, valor predeterminadoTrue) — Si se debe devolver unLTX2VideoDecodeOutputen lugar de una tupla simple. - denormalize (
bool, opcional, valor predeterminadoTrue) — Si se aplican las estadísticas latentes antes de decodificar. EstablezcaFalsesi los latentes ya están denormalizados.
Devuelve
LTX2VideoDecodeOutput o tuple
LTX2DurationHead
clase diffusers.pipelines.ltx2.LTX2DurationHead
< source >( video_cross_attention_dim: int = 4096audio_cross_attention_dim: int = 2048pooler_hidden_dim: int = 256num_queries: int = 1num_pooler_heads: int = 4mlp_hidden_dim: int = 256 )
Parámetros
- video_cross_attention_dim (
int, por defecto4096) — Ancho de la salida del conector de video. - audio_cross_attention_dim (
int, por defecto2048) — Ancho de la salida del conector de audio. - pooler_hidden_dim (
int, por defecto256) — Dimensión oculta compartida en la que se proyectan ambas modalidades. - num_queries (
int, por defecto1) — Número de consultas de agrupación aprendibles. - num_pooler_heads (
int, por defecto4) — Cabezales de atención utilizados por el pooler. - mlp_hidden_dim (
int, por defecto256) — Ancho oculto del MLP de salida. Se nombra con el sufijo_dimpara evitar colisiones con el submódulomlp_hidden, que de otro modoConfigMixin.__getattr__ocultaría con este valor de configuración.
Predice la duración natural del plano implícita en una descripción, a partir de las salidas del conector de texto de LTX-2.
La cabeza es agnóstica de la modalidad: se pueden pasar la salida del conector de video, la del audio, o ambas. Las proyecciones de entrada específicas de cada modalidad mapean cada flujo a una dimensión compartida del pooler, los embeddings de modalidad aprendibles etiquetan los flujos para que el pooler pueda distinguirlos, y un MLP pequeño convierte el vector agrupado en una duración en logaritmo. El objetivo de regresión se entrena en segundos logarítmicos, por lo que forward realiza la exponenciación y los llamadores siempre obtienen segundos.
Incluido a partir de los puntos de control de LTX-2.5.
forward
< source >( video_tokens: typing.Optional[torch.Tensor] = Noneaudio_tokens: typing.Optional[torch.Tensor] = None ) → torch.Tensor of shape (batch_size,)
Parámetros
- video_tokens (
torch.Tensorde forma(batch_size, seq_len, video_cross_attention_dim), opcional) — Salida del conector de video. - audio_tokens (
torch.Tensorde forma(batch_size, seq_len, audio_cross_attention_dim), opcional) — Salida del conector de audio.
Devuelve
torch.Tensor de forma (batch_size,)
la duración predicha en segundos.
predict_num_frames
< source >( video_tokens: typing.Optional[torch.Tensor] = Noneaudio_tokens: typing.Optional[torch.Tensor] = Noneframe_rate: floattemporal_compression_ratio: intmin_seconds: float = 1.0max_seconds: float = 20.0 ) → int
Parámetros
- video_tokens (
torch.Tensor, opcional) — Salida del conector de video para un solo prompt. - audio_tokens (
torch.Tensor, opcional) — Salida del conector de audio para un solo prompt. - frame_rate (
float) — Fotogramas por segundo utilizados para convertir la duración predicha en un número de fotogramas. - temporal_compression_ratio (
int) — La relación de compresión temporal del VAE, que define la cuadrícula de fotogramas. - min_seconds (
float, por defecto1.0) — Límite inferior de la predicción. - max_seconds (
float, por defecto20.0) — Límite superior de la predicción.
Devuelve
int
un recuento de fotogramas que se encuentra en la cuadrícula temporal del VAE.
Predice un recuento de fotogramas a partir de tokens de conector, limitado a [min_seconds, max_seconds] y ajustado a la cuadrícula temporal causal del VAE (k * temporal_compression_ratio + 1).
El clamp se aplica antes del snapping: una cantidad de frames con clamp no está necesariamente alineada con la cuadrícula, por lo que aplicar el snapping primero daría un resultado diferente. Dado que el snapping redondea hacia abajo, puede caer por debajo del mínimo; cuando eso ocurre, el resultado se redondea hacia arriba al siguiente punto de la cuadrícula, de modo que la cantidad de frames se mantenga dentro de los límites.
Los límites estrechos pueden convertirse en una ventana de fotogramas que no contiene ningún punto de la cuadrícula: a 24 fps, [1.0s, 1.02s] se redondea a [24, 24], y 24 no es 8k + 1. Se utiliza el punto de la cuadrícula más cercano y se registra una advertencia, ya que
superar los límites en menos de un paso de la cuadrícula es preferible a negarse a generar. Por lo tanto, la cantidad devuelta siempre está en la
cuadrícula, pero en este caso puede quedar justo fuera de los límites solicitados.
LTX2PipelineOutput
clase diffusers.pipelines.ltx2.LTX2PipelineOutput
< source >( frames: Tensoraudio: Tensor )
Parámetros
- frames (
torch.Tensor,np.ndarrayo list[list[PIL.Image.Image]]) — Lista de salidas de video. Puede ser una lista anidada de longitudbatch_size,donde cada sublista contiene secuencias de imágenes PIL desruidas de longitudnum_frames.También puede ser un array de NumPy o un tensor de Torch de forma(batch_size, num_frames, channels, height, width). - audio (
torch.Tensor,np.ndarray) — TODO
Clase de salida para las tuberías de LTX.
LTX2ModularPipeline
clase diffusers.LTX2ModularPipeline
< source >( blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = Nonepretrained_model_name_or_path: str | os.PathLike | None = Nonecomponents_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = Nonecollection: str | None = Noneworkflow: str | None = Nonemodular_config_dict: dict[str, typing.Any] | None = Noneconfig_dict: dict[str, typing.Any] | None = None**kwargs )
Un ModularPipeline para LTX-2 (generación conjunta de video y audio).
LTX2AutoBlocks
Auto blocks para LTX-2 que admiten la generación de texto a video, imagen a video, condición a video y en contexto (IC-LoRA) (video y audio conjuntos).
Flujos de trabajo admitidos:
text2video: requierepromptimage2video: requiereimage,promptcondition: requiereconditions,promptin_context: requierereference_conditions,num_frames,prompt
Componentes:
prompt_enhancer (PreTrainedModel) processor (ProcessorMixin) text_encoder (PreTrainedModel) tokenizer
(PreTrainedTokenizerBase) connectors (LTX2TextConnectors) duration_head (LTX2DurationHead) vae
(AutoencoderKLLTX2Video) video_processor (VideoProcessor) transformer (LTX2VideoTransformer3DModel)
scheduler (FlowMatchEulerDiscreteScheduler) audio_vae (AutoencoderKLLTX2Audio) guider (LTX2Guidance)
audio_guider (LTX2Guidance) vocoder (LTX2Vocoder)
Entradas:
prompt (str, opcional):
El prompt o prompts para guiar la generación de imágenes.
conditions (list, opcional): LTX2VideoCondition (o lista de ellos) que coloca condiciones de imagen/video en los índices de fotogramas latentes del
video generado.
enable_prompt_enhancement (bool, opcional, predeterminado en False):
Si se debe ejecutar el mejorador de prompts. Opcional, coincidiendo con las pipelines de referencia de Lightricks.
system_prompt (str, opcional):
System prompt para el mejoramiento. Predeterminado a LTX2_5_I2V_DEFAULT_SYSTEM_PROMPT cuando está disponible un fotograma de condición PIL.Image.Image, de lo contrario LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT.
prompt_max_new_tokens (int, opcional):
Número máximo de tokens nuevos a generar durante el mejoramiento del prompt. Predeterminado a 600, el presupuesto del
mejorador Gemma-4 de LTX-2.5.
prompt_enhancement_kwargs (dict, opcional):
Argumentos de palabra clave para la llamada .generate del mejorador. Predeterminado a decodificación codiciosa.
prompt_enhancement_seed (int, opcional, predeterminado en 10):
Semilla aleatoria para el mejoramiento del prompt (inerte bajo la decodificación codiciosa de LTX-2.5).
generator (Generator, opcional):
Generador de Torch para generación determinista.
image (Image | list, opcional):
Imagen(es) de referencia para el desruido. Puede ser una sola imagen o una lista de imágenes.
negative_prompt (str, opcional):
El prompt o prompts que no deben guiar la generación de imágenes.
max_sequence_length (int, opcional, predeterminado en 1024):
Longitud máxima de secuencia para la codificación del prompt.
min_seconds (float, opcional, predeterminado en 1.0):
Límite inferior de la duración predicha automáticamente.
max_seconds (float, opcional, predeterminado en 20.0):
Límite superior de la duración predicha automáticamente. Debe ser estrictamente mayor que min_seconds.
frame_rate (float, opcional, predeterminado en 24.0):
Fotogramas por segundo del video generado.
height (int, opcional, predeterminado en 512):
La altura en píxeles de la imagen generada.
width (int, opcional, predeterminado en 704):
El ancho en píxeles de la imagen generada.
image_crf (int, opcional):
CRF de H.264 utilizado para recomprimir la image de condicionamiento antes de la codificación VAE, coincidiendo con la compresión
contra la que se entrenó el modelo. None (predeterminado) se resuelve desde la generación del codificador de texto (33 a través
de LTX-2.3, 18 para LTX-2.5). Pasa 0 para omitir la recompresión. Requiere un PIL.Image.Image cuando
se ejecuta la recompresión.
num_frames (int, opcional):
El número de fotogramas en el video generado. Omitir para predecir automáticamente mediante duration_head (ver LTX2AutoDurationStep).
reference_conditions (list, opcional): LTX2ReferenceCondition (o lista de ellos) cuyos videos se codifican en tokens latentes adicionales a los que atiende el
adaptador IC-LoRA.
reference_downscale_factor (int, opcional, predeterminado en 1):
Relación entre las resoluciones de destino y de referencia; 2 significa que la referencia se preprocesa a la mitad de la
resolución de destino. Las coordenadas espaciales se escalan por este factor para que los tokens de referencia caigan en el
espacio de coordenadas de destino. Debe coincidir con el factor con el que se entrenó el IC-LoRA.
conditioning_attention_strength (float, opcional, predeterminado en 1.0):
Escalar en [0, 1] que controla con qué fuerza los tokens ruidosos y los tokens de referencia atienden entre sí. 1.0
(predeterminado) deja la atención sin enmascarar.
conditioning_attention_mask (Tensor, opcional):
Máscara opcional en espacio de píxeles de forma (1, 1, F, H, W) con valores en [0, 1] que proporciona una fuerza de atención
variable espacialmente. Se reduce a la cuadrícula latente de la referencia y se multiplica por conditioning_attention_strength.
motion_speed (float, opcional, predeterminado en 1.0):
Velocidad del movimiento en relación con el tiempo real. Los embeddings posicionales se condicionan en frame_rate / motion_speed, por lo que los valores inferiores a 1 ralentizan el movimiento, p. ej. 0.2 para el movimiento lento 5x del LoRA Slow-Motion-Control. frame_rate permanece como la tasa de reproducción.
num_videos_per_prompt (int, opcional, predeterminado en 1):
El número de imágenes a generar por prompt.
condition_latents (list, opcional):
Latentes VAE normalizados por condición de forma [1, C, F, H, W].
condition_strengths (list, opcional):
Fuerzas de condicionamiento por condición.
condition_indices (list, opcional):
Índice de fotograma latente por condición en el que se aplica la condición.
condition_pixel_frames (list, opcional):
Conteo de fotogramas de píxeles recortados por condición, utilizado para acotar las coordenadas de fotogramas clave de un solo fotograma.
reference_latents (Tensor, opcional):
Tokens de referencia empaquetados de forma [1, total_reference_tokens, C], o None cuando no se proporcionaron condiciones de
referencia (LTX2AutoReferenceEncoderStep se omite).
reference_coords (Tensor, opcional):
Coordenadas RoPE para los tokens de referencia.
reference_token_counts (list, opcional):
Conteos de tokens por referencia, en el orden de reference_conditions.
latents (Tensor):
Latentes ruidosos pregenerados para la generación de imágenes.
noise_scale (float, opcional):
Nivel inicial de ruido para los tokens no condicionados. None (predeterminado) se resuelve a sigmas[0] cuando se proporcionan sigmas personalizados, de lo contrario 1.0.
sigmas (list, opcional):
Sigmas personalizados para el proceso de desruido.
reference_cross_mask (Tensor, opcional):
Fuerzas de atención ruidoso<->referencia por token de referencia de forma [1, num_ref_tokens].
num_inference_steps (int):
El número de pasos de desruido.
timesteps (Tensor):
Pasos de tiempo para el proceso de desruido.
audio_latents (Tensor):
Latentes de audio precodificados opcionales; se utiliza ruido aleatorio cuando no se proporcionan.
*denoiser_input_fields (None,opcional):
entradas condicionales del modelo para el desruidador: p. ej. prompt_embeds, negative_prompt_embeds, etc.
use_cross_timestep (bool,opcional, predeterminado en True):
Si se debe condicionar el transformer en un paso de tiempo cruzado separado por token (LTX-2.3+).
attention_kwargs (dict,opcional):
Kwargs adicionales para los procesadores de atención.
image_latents (Tensor,opcional):
Latentes de imagen de referencia codificados por VAE utilizados para el condicionamiento de imagen a video.
output_type (str,opcional, predeterminado en pil):
Formato de salida: ‘pil’, ‘np’, ‘pt’.
decode_timestep (None,opcional, predeterminado en 0.0):
El paso de tiempo en el que el VAE decodifica los latentes finales.
decode_noise_scale (None,opcional*):
Factor de interpolación de ruido aplicado a los latentes en el paso de tiempo de decodificación.
Salidas:
videos (list):
Los videos generados.
audio (Tensor):
La forma de onda de audio generada.
LTX25ModularPipeline
clase diffusers.LTX25ModularPipeline
< source >( blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = Nonepretrained_model_name_or_path: str | os.PathLike | None = Nonecomponents_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = Nonecollection: str | None = Noneworkflow: str | None = Nonemodular_config_dict: dict[str, typing.Any] | None = Noneconfig_dict: dict[str, typing.Any] | None = None**kwargs )
Un ModularPipeline para LTX-2.5 (generación conjunta de video y audio).
Idéntico a LTX2ModularPipeline, excepto que sus bloques predeterminados decodifican con el decodificador de video de difusión, que es el predeterminado nativo a partir de LTX-2.5. Un checkpoint se enruta aquí a través de modular_model_index.json.
LTX25AutoBlocks
Auto blocks para LTX-2.5 que admiten la generación de texto a video, imagen a video, condición a video y en contexto (IC-LoRA) (video + audio conjuntos). Idéntico a LTX2AutoBlocks excepto que el decodificador de video es LTX2DiffusionVaeDecoderStep, ya que el decodificador de difusión es el predeterminado nativo a partir de LTX-2.5. Para decodificar con el VAE convolucional en su lugar, reemplace el bloque de decodificación: blocks.sub_blocks["decode"] = LTX2AutoDecoderStep().
Flujos de trabajo admitidos:
text2video: requierepromptimage2video: requiereimage,promptcondition: requiereconditions,promptin_context: requierereference_conditions,num_frames,prompt
Componentes:
prompt_enhancer (PreTrainedModel) processor (ProcessorMixin) text_encoder (PreTrainedModel) tokenizer
(PreTrainedTokenizerBase) connectors (LTX2TextConnectors) duration_head (LTX2DurationHead) vae
(AutoencoderKLLTX2Video) video_processor (VideoProcessor) transformer (LTX2VideoTransformer3DModel)
scheduler (FlowMatchEulerDiscreteScheduler) audio_vae (AutoencoderKLLTX2Audio) guider (LTX2Guidance)
audio_guider (LTX2Guidance) diffusion_decoder (LTX2VideoDiffusionDecoderModel) vocoder (LTX2Vocoder)
Entradas:
prompt (str, opcional):
El prompt o prompts para guiar la generación de imágenes.
conditions (list, opcional): LTX2VideoCondition (o lista de ellos) que coloca condiciones de imagen/video en los índices de fotogramas latentes del
video generado.
enable_prompt_enhancement (bool, opcional, predeterminado en False):
Si se debe ejecutar el mejorador de prompts. Opcional, coincidiendo con las pipelines de referencia de Lightricks.
system_prompt (str, opcional):
System prompt para el mejoramiento. Predeterminado a LTX2_5_I2V_DEFAULT_SYSTEM_PROMPT cuando está disponible un fotograma de condición PIL.Image.Image, de lo contrario LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT.
prompt_max_new_tokens (int, opcional):
Número máximo de tokens nuevos a generar durante el mejoramiento del prompt. Predeterminado a 600, el presupuesto del
mejorador Gemma-4 de LTX-2.5.
prompt_enhancement_kwargs (dict, opcional):
Argumentos de palabra clave para la llamada .generate del mejorador. Predeterminado a decodificación codiciosa.
prompt_enhancement_seed (int, opcional, predeterminado en 10):
Semilla aleatoria para el mejoramiento del prompt (inerte bajo la decodificación codiciosa de LTX-2.5).
generator (Generator, opcional):
Generador de Torch para generación determinista.
image (Image | list, opcional):
Imagen(es) de referencia para el desruido. Puede ser una sola imagen o una lista de imágenes.
negative_prompt (str, opcional):
El prompt o prompts que no deben guiar la generación de imágenes.
max_sequence_length (int, opcional, predeterminado en 1024):
Longitud máxima de secuencia para la codificación del prompt.
min_seconds (float, opcional, predeterminado en 1.0):
Límite inferior de la duración predicha automáticamente.
max_seconds (float, opcional, predeterminado en 20.0):
Límite superior de la duración predicha automáticamente. Debe ser estrictamente mayor que min_seconds.
frame_rate (float, opcional, predeterminado en 24.0):
Fotogramas por segundo del video generado.
height (int, opcional, predeterminado en 512):
La altura en píxeles de la imagen generada.
width (int, opcional, predeterminado en 704):
El ancho en píxeles de la imagen generada.
image_crf (int, opcional):
CRF de H.264 utilizado para recomprimir la image de condicionamiento antes de la codificación VAE, coincidiendo con la compresión
contra la que se entrenó el modelo. None (predeterminado) se resuelve desde la generación del codificador de texto (33 a través
de LTX-2.3, 18 para LTX-2.5). Pasa 0 para omitir la recompresión. Requiere una PIL.Image.Image cuando
se ejecuta la recompresión.
num_frames (int, opcional):
El número de fotogramas en el video generado. Omitir para predecir automáticamente mediante duration_head (ver LTX2AutoDurationStep).
reference_conditions (list, opcional): LTX2ReferenceCondition (o lista de ellos) cuyos videos se codifican en tokens latentes adicionales a los que atiende el
adaptador IC-LoRA.
reference_downscale_factor (int, opcional, predeterminado en 1):
Relación entre las resoluciones objetivo y de referencia; 2 significa que la referencia se preprocesa a la mitad de la
resolución objetivo. Las coordenadas espaciales se escalan por este factor para que los tokens de referencia caigan en el
espacio de coordenadas objetivo. Debe coincidir con el factor con el que se entrenó el IC-LoRA.
conditioning_attention_strength (float, opcional, predeterminado en 1.0):
Escalar en [0, 1] que controla con qué fuerza los tokens ruidosos y los tokens de referencia atienden entre sí. 1.0
(predeterminado) deja la atención sin enmascarar.
conditioning_attention_mask (Tensor, opcional):
Máscara opcional en espacio de píxeles de forma (1, 1, F, H, W) con valores en [0, 1] que proporciona una fuerza de atención
variable espacialmente. Se submuestrea a la cuadrícula latente de la referencia y se multiplica por conditioning_attention_strength.
motion_speed (float, opcional, predeterminado en 1.0):
Velocidad del movimiento en relación con el tiempo real. Los embeddings posicionales se condicionan en frame_rate / motion_speed, por lo que los valores por debajo de 1 ralentizan el movimiento, p. ej. 0.2 para el movimiento lento 5x del LoRA Slow-Motion-Control. frame_rate permanece como la tasa de reproducción.
num_videos_per_prompt (int, opcional, predeterminado en 1):
El número de imágenes a generar por prompt.
condition_latents (list, opcional):
Latentes VAE normalizados por condición de forma [1, C, F, H, W].
condition_strengths (list, opcional):
Fuerzas de condicionamiento por condición.
condition_indices (list, opcional):
Índice de fotograma latente por condición en el que se aplica la condición.
condition_pixel_frames (list, opcional):
Conteo de fotogramas de píxeles recortados por condición, utilizado para acotar las coordenadas de fotogramas clave de un solo fotograma.
reference_latents (Tensor, opcional):
Tokens de referencia empaquetados de forma [1, total_reference_tokens, C], o None cuando no se proporcionaron condiciones de
referencia (LTX2AutoReferenceEncoderStep se omite).
reference_coords (Tensor, opcional):
Coordenadas RoPE para los tokens de referencia.
reference_token_counts (list, opcional):
Conteos de tokens por referencia, en el orden de reference_conditions.
latents (Tensor):
Latentes ruidosos pregenerados para la generación de imágenes.
noise_scale (float, opcional):
Nivel inicial de ruido para los tokens no condicionados. None (predeterminado) se resuelve a sigmas[0] cuando se proporcionan sigmas personalizados, de lo contrario 1.0.
sigmas (list, opcional):
Sigmas personalizados para el proceso de desruido.
reference_cross_mask (Tensor, opcional):
Fuerzas de atención ruidoso<->referencia por token de referencia de forma [1, num_ref_tokens].
num_inference_steps (int):
El número de pasos de desruido.
timesteps (Tensor):
Pasos de tiempo para el proceso de desruido.
audio_latents (Tensor):
Latentes de audio precodificados opcionales; se utiliza ruido aleatorio cuando no se proporcionan.
*denoiser_input_fields (None,opcional):
entradas condicionales del modelo para el desruidador: p. ej. prompt_embeds, negative_prompt_embeds, etc.
use_cross_timestep (bool,opcional, predeterminado en True):
Si se debe condicionar el transformer en un cross timestep separado por token (LTX-2.3+).
attention_kwargs (dict,opcional):
Kwargs adicionales para los procesadores de atención.
image_latents (Tensor,opcional):
Latentes de imagen de referencia codificados por VAE utilizados para el condicionamiento de imagen a video.
output_type (str,opcional*, predeterminado en pil):
Formato de salida: ‘pil’, ‘np’, ‘pt’.
Salidas:
videos (list):
Los videos generados.
audio (Tensor):
La forma de onda de audio generada.