Diffusers documentation
LTX-2
LTX-2
LTX-2 é um modelo de base baseado em DiT projetado para gerar vídeo e áudio sincronizados em um único modelo. Ele reúne os blocos de construção fundamentais da geração de vídeo moderna, com pesos abertos e foco em execução local prática.
Você pode encontrar todos os checkpoints originais do LTX-Video sob a organização Lightricks.
O código-fonte original do LTX-2 pode ser encontrado aqui.
Geração em duas etapas
Os padrões do __call__ compartilhado de LTX2Pipeline / LTX2ImageToVideoPipeline correspondem à referência LTX-2.5 (num_inference_steps=30; num_frames é opcional quando um duration_head está presente, caso contrário, o valor padrão é 121). Os exemplos abaixo também usam esses padrões para LTX-2.0/2.3.
Pipeline recomendado para alcançar geração de qualidade de produção, este pipeline é composto por duas etapas:
- Etapa 1: Gerar um vídeo na resolução de destino usando amostragem por difusão com orientação sem classificador (CFG). Esta etapa produz uma sequência de vídeo coerente com baixo ruído que respeita a condicionamento de texto/imagem.
- Etapa 2: Amplie a saída da Etapa 1 por um fator de 2 e refine os detalhes usando um modelo LoRA destilado para melhorar a fidelidade e a qualidade visual. A Etapa 2 pode aplicar um CFG mais leve para preservar a estrutura da Etapa 1, ao mesmo tempo em que aprimora a textura e a nitidez.
Uso de exemplo do pipeline de texto para vídeo em duas 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",
)Geração de checkpoint destilado
Pipeline de geração em duas etapas mais rápido usando um checkpoint 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",
)Condição Pipeline Geração
Você pode usar LTX2ConditionPipeline para especificar condições de imagem e/ou vídeo em índices latentes arbitrários. Por exemplo, podemos especificar tanto uma condição de primeiro quadro quanto uma de último quadro para realizar a geração first-last-frame-to-video (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",
)Você pode usar condições de imagem e vídeo:
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",
)Como o condicionamento é feito por meio de quadros latentes, os 8 quadros do espaço de dados correspondentes ao quadro latente especificado para uma condição de imagem tendem a ser estáticos.
Orientação Multimodal
Os pipelines LTX-2.X suportam orientação multimodal. Ele é composto por três termos, todos usando uma regra de atualização no estilo CFG:
- Classifier-Free Guidance (CFG): CFG padrão, em que a saída perturbada (“mais fraca”) é gerada usando o prompt negativo.
- Spatio-Temporal Guidance (STG): STG abandona a saída perturbada criada por meio de atalhos nas operações de autoatenção e, em vez disso, substitui os valores de atenção. A ideia é que isso resulte em vídeos mais nítidos e com melhor consistência espaço-temporal.
- Orientação de Isolamento de Modalidade: afasta-se de uma saída perturbada criada ao desabilitar a atenção cruzada entre modalidades (áudio-para-vídeo e vídeo-para-áudio). Essa orientação é mais específica para os modelos LTX-2.X, com a ideia de que isso produz uma melhor consistência entre o áudio e o vídeo gerados.
Esses são controlados pelos argumentos guidance_scale, stg_scale e modality_scale e podem ser definidos separadamente para vídeo e áudio. Além disso, para o STG, é necessário especificar os índices dos blocos do transformer nos quais a autoatenção é ignorada por meio do argumento spatio_temporal_guidance_blocks. Os pipelines LTX-2.X também suportam reescalonamento de orientação para ajudar a reduzir a superexposição, o que pode ser um problema quando as escalas de orientação são definidas com 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",
)Melhoria de Prompt
Os modelos LTX-2.X são sensíveis ao estilo de prompt. Consulte o guia oficial de prompts para recomendações sobre como escrever um bom prompt. O uso de aprimoramento de prompt, em que os prompts fornecidos são aprimorados usando o codificador de texto do pipeline (por padrão, um modelo Gemma 3) dado um prompt de sistema, também pode melhorar a qualidade das amostras. O componente de pipeline opcional processor precisa estar presente para usar o aprimoramento de prompt. Ative-o com enable_prompt_enhancement=True e um system_prompt (opt-in, correspondente aos pipelines de referência da 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
O LTX-2.5 reutiliza as mesmas classes LTX2Pipeline/LTX2VideoTransformer3DModel/AutoencoderKLLTX2Video/etc. do LTX-2.3 — não há uma classe de pipeline separada para ele. A diferença visível ao usuário é o codificador de texto: o LTX-2.5 é emparelhado com um checkpoint Gemma 4 (gemma4_unified) em vez do Gemma 3. Isso é carregado automaticamente quando você chama from_pretrained em um checkpoint LTX-2.5 convertido (via as classes Auto* do transformers), portanto, nenhum setup extra é necessário no momento da inferência — basta apontar o from_pretrained para um repositório LTX-2.5 em vez de um LTX-2.3.
Lightricks/LTX-2.5-Diffusers inclui os dois transformers: o DiT destilado em transformer/, para o qual model_index.json aponta, e o DiT completo/SFT em transformer_full/, que precisa ser carregado explicitamente (veja Full / SFT transformer). O scheduler/ do repositório é configurado para o checkpoint destilado (use_dynamic_shifting=False, shift_terminal=None) para que seu agendamento de sigma seja usado exatamente como fornecido. Tudo o que a two-stage generation precisa também é incluído lá: uma subpasta latent_upsampler/ e o LoRA destilado do estágio 2, ltx-2.5-22b-distilled-lora-450-bf16.safetensors, na raiz do repositório.
A inferência destilada é dirigida por um agendamento explícito de sigma, em vez de uma contagem de etapas, e é executada sem orientação (guidance_scale=1.0, portanto negative_prompt não é utilizado). Passar num_inference_steps em vez disso forneceria ao modelo um agendamento linear genérico e causaria uma perda silenciosa de qualidade:
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",
)Geração em duas etapas para LTX-2.5
O LTX-2.5 suporta ambas as variantes de dois estágios, e DISTILLED_SIGMA_VALUES / STAGE_2_DISTILLED_SIGMA_VALUES são seus agendamentos de referência:
- Checkpoint destilado, ambos os estágios — a receita de referência para o
transformer/padrão, e a mostrada abaixo. Não há LoRA do estágio 2 envolvido, pois o transformer já está destilado; este é o Geração de checkpoint destilado com os pesos do LTX-2.5. - Etapa 1 Full/SFT + etapa 2 LoRA destilado — Geração em duas etapas conforme descrito no topo desta página, usando
transformer_full/e o LoRA incluído. Veja abaixo o que muda.
A etapa 1 é executada na metade da resolução alvo, o upsampler a dobra e a etapa 2 refina na resolução completa — vídeo e áudio, ambos resemeados a partir dos latentes da etapa 1 em noise_scale=STAGE_2_DISTILLED_SIGMA_VALUES[0]. Altura e largura devem ser divisíveis por 64, pois a etapa 1 reduz cada eixo pela metade e ainda precisa se alinhar à grade espacial do 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",
)Quando o comprimento vem do duration head em vez de um num_frames explícito, deixe que a etapa 1 decida e recupere o comprimento realizado a partir de seus latentes ([B, C, F, H, W]) antes da execução da etapa 2, em vez de prever uma segunda vez:
num_frames = (video_latent.shape[2] - 1) * pipe.vae_temporal_compression_ratio + 1Etapa 2 com o LoRA destilado
Para executar Two-stages Generation em vez disso — DiT full/SFT para o estágio 1, LoRA destilado para o estágio 2 — monte o pipeline conforme descrito em Full / SFT transformer e gere os latents do estágio 1 com essa pilha de orientação. Duas coisas diferem em relação ao LTX-2.0/2.3. O LoRA fica no próprio repositório do diffusers, em vez de estar junto com os pesos originais, e a inversão do scheduler ocorre no sentido oposto: o LTX-2.5 fornece a configuração do scheduler distilled, de modo que o estágio 1 é o que ativou o dynamic shifting, e o estágio 2 o desativa novamente.
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
)A etapa de upsample e a chamada da etapa 2 permanecem inalteradas em relação à receita destilada acima: mesmo sigmas=STAGE_2_DISTILLED_SIGMA_VALUES, mesmo noise_scale e guidance_scale=1.0, já que a etapa 2 executa um modelo destilado de qualquer forma.
Decodificação convolucional e de difusão
O LTX-2.5 inclui dois decodificadores de vídeo sobre o mesmo espaço latente, portanto os latentes são intercambiáveis entre eles:
vae/— o VAE convolucional (AutoencoderKLLTX2Video). É com ele que os pipelines fazem a decodificação, portanto todos os trechos acima já o utilizam, e é o único dos dois que faz tiling (pipe.vae.enable_tiling()), o que geralmente permite que uma resolução alta caiba na memória.diffusion_decoder/— LTX2VideoDiffusionDecoderModel. Trata-se de um modelo de difusão em si, e não de um componente de pipeline, portanto não é passado comovae: execute o pipeline comoutput_type="latent"e passe os latentes para LTX2VideoDiffusionDecodePipeline.
A codificação sempre passa por vae/, portanto, a condicionamento de imagem e vídeo não é afetado pela escolha.
Duas coisas mudam quando você decodifica com o decodificador de difusão. output_type="latent" também pula o vocoder, então o áudio volta como latentes e precisa ser finalizado manualmente, e o processador NATTEN é efetivamente obrigatório em resoluções de vídeo:
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 isso com geração em duas etapas, solicite ao estágio 2 output_type="latent" e decodifique-o.
decoder.enable_tiling() é o que mantém a decodificação em alta resolução na memória, da mesma forma que pipe.vae.enable_tiling() faz para o VAE convolucional. A parte da decodificação que mais consome memória — o último estágio de upsampling e o estágio de difusão — é executada em tiles sobrepostos que são mesclados novamente, de modo que a memória de pico é limitada pelo tamanho do tile em vez do tamanho do vídeo. O tiling só entra em ação quando o latente excede um tile, e os tamanhos do tile e da sobreposição podem ser ajustados por meio dos argumentos tile_sample_min_* / tile_sample_stride_* (os valores padrão correspondem à implementação de referência). Como o estágio de difusão remove o ruído de cada tile separadamente, uma decodificação com tiles não reproduz exatamente o resultado da decodificação sem tiles.
Em um único cartão, também vale a pena mover o pipeline para fora do caminho antes da decodificação (pipe.to("cpu") e torch.cuda.empty_cache(), após capturar pipe.scheduler e o output_sampling_rate do vocoder), pois o decodificador precisa de sua própria folga. Consulte LTX2VideoDiffusionDecoderModel para os backends de atenção, os detalhes de tiling e o restante do comportamento do decodificador.
Transformador completo / SFT
transformer_full/ não é referenciado por model_index.json, portanto carregue-o explicitamente. Ele também requer um scheduler diferente e uma pilha de guidance real: o scheduler/ incluído é configurado para o checkpoint destilado, e os padrões de guidance são genéricos da era LTX-2.0 que deixam uma execução SFT do LTX-2.5 visivelmente subguiada sem emitir nenhum aviso. As recomendações de Multimodal Guidance se aplicam aqui sem alterações, incluindo STG no bloco 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,
)Insira sigmas aqui — o DiT completo obtém seu agendamento do scheduler.
Melhoria de Prompt para LTX-2.5
O uso de aprimoramento de prompt é fortemente recomendado para o LTX-2.5; passe enable_prompt_enhancement=True para ativá-lo (da mesma forma que nos pipelines de referência da Lightricks). Diferentemente do LTX-2.0/2.3, em que o mesmo checkpoint do text encoder também atua como aprimorador (veja Aprimoramento de Prompt acima), o text encoder fine-tuned do LTX-2.5 não foi treinado para aprimoramento. Em vez disso, o aprimoramento utiliza um checkpoint separado, pronto para uso, google/gemma-4-E2B-it. Carregue-o nos componentes opcionais prompt_enhancer/processor do pipeline e, em seguida, ative o aprimoramento — o pipeline usa por padrão LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT e a receita do Gemma 4 (do_sample=False, no_repeat_ngram_size=5, max_new_tokens=600). Passe um system_prompt= explícito para substituir:
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",
)O mesmo se aplica ao image-to-video com LTX2ImageToVideoPipeline: defina pipe.prompt_enhancer/pipe.processor da mesma forma e passe enable_prompt_enhancement=True (usando LTX2_5_I2V_DEFAULT_SYSTEM_PROMPT, condicionando tanto na imagem de referência quanto no prompt de texto) — novamente, não é necessário system_prompt=, a menos que você queira sobrescrevê-lo.
Duração automática para LTX-2.5
Os checkpoints do LTX-2.5 incluem um pequeno duration_head que prevê a duração do tiro descrito, a partir da mesma saída do conector de texto em que o transformer é condicionado. Quando o pipeline carregado possui um, num_frames é previsto automaticamente por padrão — omita-o e o modelo escolherá a duração:
video, audio = pipe(prompt=prompt, output_type="np", return_dict=False)Para definir o comprimento manualmente, passe num_frames explicitamente. Um inteiro sempre tem prioridade sobre o cabeçalho:
video, audio = pipe(prompt=prompt, num_frames=121, output_type="np", return_dict=False)Pipelines carregados de checkpoints LTX-2.0 ou LTX-2.3 não possuem duration head e mantêm o padrão anterior de 121 frames, portanto isso não altera nada para eles.
Passe min_seconds / max_seconds para restringir a previsão. A previsão bruta é limitada ao intervalo e, em seguida, convertida em quadros:
video, audio = pipe(
prompt=prompt,
min_seconds=2.0,
max_seconds=10.0,
frame_rate=frame_rate,
output_type="np",
return_dict=False,
)As contagens de quadros previstas são ajustadas à grade temporal causal do VAE (8k + 1), de modo que a duração realizada é quantizada — cerca de 0,33 s por passo a 24 fps — e varia com frame_rate, pois a cabeça prevê segundos em vez de quadros. min_seconds deve ser estritamente menor que max_seconds. Esses limites são ignorados quando num_frames é definido explicitamente.
Limites mais estreitos que um passo de grade podem não ser satisfatórios exatamente: a 24 fps, [1.0s, 1.02s] é convertido para [24, 24] quadros, e 24 não é 8k + 1. O ponto de grade mais próximo é usado e um aviso é registrado, de modo que o comprimento retornado pode ficar ligeiramente fora de limites tão apertados.
Para inspecionar uma previsão sem gerar um vídeo, chame a head diretamente. Tudo o que ela precisa é 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")A conversão de um checkpoint 2.5 seleciona automaticamente o head com --full_pipeline, ou isoladamente com --duration_head. Checkpoints anteriores à versão 2.5 não possuem esses pesos, e a conversão ignora o componente em vez de falhar.
Velocidade de movimento para LTX-2.5
O LTX-2 posiciona cada token de vídeo em um eixo temporal em segundos, derivado por padrão de frame_rate, a taxa de reprodução. motion_speed (padrão 1.0) separa os dois: o eixo temporal é condicionado em frame_rate / motion_speed, enquanto a duração do áudio, o duration head e o vídeo retornado ainda seguem frame_rate. Com frame_rate=24.0 e motion_speed=0.2, o modelo é informado de que a ação foi capturada a 120 fps e o resultado é reproduzido a 24 fps, o que resulta em câmera lenta de 5x.
O modelo base é treinado em torno de 24/25/30/60 fps, portanto, velocidades muito diferentes de 1.0 só fazem sentido com um adaptador treinado para elas, como Lightricks/LTX-2.5-22b-LoRA-Slow-Motion-Control (com restrição: aceite sua licença no Hub primeiro). Sem motion_speed, esse LoRA é carregado como um LoRA comum e não fornece nenhum controle de movimento. O cartão do modelo sugere velocidades de 1.0, 0.5, 0.2, 0.1, 0.05 e 0.025, com intensidade de LoRA 1.0. Deixe as palavras de velocidade (“slow motion”, “high fps”) de fora do prompt e reutilize a mesma legenda entre as velocidades, pois apenas motion_speed controla o efeito.
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 os clipes têm 121 quadros (cerca de 5 segundos a 24 fps) e apenas o ritmo do movimento muda. Na geração em duas etapas, passe o mesmo motion_speed para ambas as etapas. A etapa 2 re-remove o ruído do vídeo e desfaria o câmera lenta se fosse executada no eixo do tempo real. O driver de referência faz o mesmo ao encapsular o objeto da etapa compartilhado por ambas as passagens.
motion_speed também é uma entrada dos blocos modulares do LTX-2 / LTX-2.5 e é passada para o pipeline modular da mesma forma.
LTX-2.5 Modular
O LTX-2.5 também está disponível como um pipeline modular. O conjunto de blocos padrão usa o decodificador de difusão e prevê a duração do vídeo quando num_frames é omitido. Ele aplica o guia separadamente para vídeo e áudio por meio dos componentes guider e audio_guider. Consulte LTX2Guidance para os parâmetros de guia disponíveis. Por padrão, o pipeline modular baixará o aprimorador e o processador de prompt do repositório google/gemma-4-E2B-it. Abaixo está um exemplo 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",
)O pipeline modular alterna automaticamente os fluxos de trabalho com base nas entradas fornecidas. Por exemplo, se image for fornecida, um fluxo de trabalho I2V será utilizado:
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",
)Você pode ver os fluxos de trabalho suportados na documentação de cada blockset (por exemplo, LTX2AutoBlocks, LTX25AutoBlocks).
Diffusion Fidelity Rendering (DFR) para LTX-2.5
LTX2DFRPipeline troca o tempo real por fidelidade de detalhes. Cada __call__ é uma passada de desruido em height × width: ele gera o vídeo mais slots de keyframe adicionais de quadro único, ou reprocessa latentes fornecidos semeados a partir desses slots. Os chamadores compõem as etapas da mesma forma que outros pipelines de duas etapas do LTX — este pipeline, LTX2LatentUpsamplePipeline, este pipeline novamente, e então LTX2DFRTemporalRefinePipeline para cada rodada temporal.
Um slot custa um frame latente completo de tokens para adquirir um frame de pixels, o que relaxa a compressão temporal efetiva naquela posição — assim, o vídeo ao redor é condicionado em frames genuinamente novos em vez de interpolados. As posições dos slots vêm de uma grade de segmentos alinhada à borda temporal do VAE (24 ou 32 frames de pixels, o que resultar em menos padding para a solicitação). O canvas é preenchido internamente até um número inteiro de segmentos; output_type="latent" retorna essa grade preenchida para que um slot no padding não seja descartado. Use trim_canvas antes da decodificação pelo VAE.
Isso requer um transformer cuja configuração defina use_keyframes_abs_pos_embedding, que marca latentes de quadros de um único pixel com um embedding aprendido. Os checkpoints do LTX-2.5 o incluem; o pipeline gera um erro para qualquer versão anterior, em vez de gastar o orçamento de tokens em tokens que não consegue interpretar.
Orçamento para os tokens extras: cada slot adiciona o equivalente a um frame latente, portanto a etapa 2 executa uma sequência mais longa do que a passagem destilada de duas etapas equivalente — +31% em 1024x1536 / 121 frames (24576 -> 32256 tokens, 5 slots em uma grade de segmentos de 24 frames). A memória de ativação de pico escala com isso, então uma resolução que cabe apenas na receita destilada padrão pode precisar de enable_sequential_cpu_offload, vae.enable_tiling() ou um canvas menor sob DFR.
A composição usa return_dict=True para keyframes e keyframe_positions (return_dict=False retorna os mesmos quatro campos como uma tupla).
A receita completa abaixo é a que vale a pena usar como ponto de partida: imagem-para-vídeo de 1088×1920, uma rodada de refinamento temporal x2 e o IC-LoRA de detalhamento espacial x2 no estágio 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 e width são desta passagem, não da saída final. O estágio 1 é executado em metade do canvas 1080p (544×960); o estágio 2, em 1088×1920. Cada um deve ser divisível pela razão de compressão espacial do VAE (32 no LTX-2.5 para uma única passagem; 64 quando o estágio 1 é metade do 1080p). É por isso que o 1080p é 1920×1088 e o 4K é 3840×2176. Cada passagem executa um agendamento destilado fixo (sigmas), portanto não há num_inference_steps; os agendamentos destilados são treinados sem orientação, portanto também não há negative_prompt ou guidance_scale. O áudio incluído é o do estágio 1 — as passagens posteriores ainda executam um fluxo de áudio para que o ramo de vídeo tenha atenção intermodal; a própria forma de onda não é refinada após o estágio 1.
Detalhamento espacial. Carregue o IC-LoRA de detalhamento espacial 2x em um adaptador nomeado após a etapa 1 e ative-o apenas para a etapa 2 (set_adapters(["detailing"], adapter_weights=[0.5])). A etapa 2 então presta atenção ao latente de meia resolução da etapa 1 como reference_latents. A etapa 1 e as rodadas temporais são executadas com o adaptador desativado. Se você carregar o LoRA antes da etapa 1, transformer.disable_adapters() o desativa, e set_adapters não o reativa — chame transformer.enable_adapters() antes da etapa 2, ou carregue os pesos após a etapa 1, conforme a receita. reference_downscale_factor (padrão 2) escala as coordenadas espaciais dos tokens de referência para o espaço de coordenadas do alvo.
Refinamento temporal. LTX2DFRTemporalRefinePipeline é uma rodada: faz upsample temporal, aplica tiles nas emendas dos keyframes, realiza ancestral-denoise com LTXEulerAncestralRFScheduler (eta=0.5), costura descartando a lead-in do tile posterior e mescla a bag do keyframe de continuação. Construa esse scheduler você mesmo — a rodada é recusada com qualquer outro, pois um passo determinístico executaria até o fim e retornaria apenas um canvas mais suave. Chame o pipeline uma vez por rodada; faça um loop para 2x / 4x, passando round_index. Após uma rodada, keyframe_positions não pode ser re-derivado do num_frames original e deve ser passado adiante. Cada tile recebe o slice do áudio congelado da etapa 1 que cobre sua própria janela de reprodução. source_seconds é a duração da etapa 1 e permanece fixa entre as rodadas, portanto as rodadas posteriores devem passá-lo explicitamente em vez de usar o valor padrão.
A fps de condicionamento é 60 sempre que a reprodução estiver acima de 30, independentemente do muxing: o tempo de RoPE é pixel_frame / fps, portanto, uma base de tempo de 120 fps reduziria pela metade a extensão temporal de cada token em relação à distribuição treinada, e 48 fps a estenderia. Ambos mentem dizendo que são 60 e tratam os frames decodificados na taxa de reprodução.
Um terceiro estágio espacial. Componha-o; não há um quarto pipeline. Faça o upsample espacial do apenas do vídeo, reconstrua os keyframes de carry em RGB (decode → Lanczos ×2 → encode via rebuild_epilogue_keyframes(); nunca faça upsample latente dos keyframes de epílogo), e então:
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()Os dois eixos são costurados de maneira diferente. Nenhum lado de uma fronteira espacial possui uma resposta conhecida, portanto, essas sobreposições são mescladas com pesos trapezoidais. Os tiles temporais são cortados nas emendas dos quadros-chave da última rodada de refinamento.
Decodificação com o decodificador de difusão. Para máxima fidelidade de detalhes, mantenha output_type="latent" e passe os latentes (já desnornalizados, possivelmente trim_canvas‘d) para 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
classe 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) — Arquitetura de Transformer condicional para desruidar os latentes de vídeo codificados.
- scheduler (FlowMatchEulerDiscreteScheduler) —
Um scheduler a ser usado em combinação com
transformerpara desruidar os latentes da imagem codificada. - vae (AutoencoderKLLTXVideo) — Modelo de Autoencoder Variacional (VAE) para codificar e decodificar imagens a partir de e para representações latentes.
- text_encoder (
T5EncoderModel) — T5, especificamente a variante google/t5-v1_1-xxl. - tokenizer (
CLIPTokenizer) — Tokenizer da classe CLIPTokenizer. - tokenizer (
T5TokenizerFast) — Segundo Tokenizer da classe T5TokenizerFast. - connectors (
LTX2TextConnectors) — Pilha de conectores de texto usada para adaptar os estados ocultos do codificador de texto para os ramos de vídeo e áudio.
Pipeline para geração de texto para vídeo.
Referência: 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 (
stroulist[str], opcional) — O prompt ou os prompts para orientar a geração da imagem. Se não for definido, é necessário passarprompt_embedsem vez disso. - negative_prompt (
stroulist[str], opcional) — O prompt ou os prompts que não devem orientar a geração da imagem. Se não for definido, é necessário passarnegative_prompt_embedsem vez disso. Ignorado quando não está usando orientação (guidance_scale < 1). - height (
int, opcional, padrão512) — A altura em pixels da imagem gerada. Por padrão, é definida como 480 para obter os melhores resultados. - width (
int, opcional, padrão768) — A largura em pixels da imagem gerada. Por padrão, é definida como 848 para obter os melhores resultados. - num_frames (
int, opcional) — O número de quadros de vídeo a serem gerados. Se não for fornecido, o valor padrão é uma duração prevista automaticamente quando este pipeline possui um componenteduration_head(checkpoints LTX-2.5 e posteriores) e121caso contrário. Passe um inteiro para definir o comprimento explicitamente. As contagens previstas automaticamente são ajustadas à grade temporal causal do VAE, de modo que a duração realizada é quantizada (aproximadamente 0,33s a 24 fps). - min_seconds (
float, opcional, padrão1.0) — Limite inferior da duração prevista automaticamente quandonum_framesé omitido e umduration_headestá presente. Ignorado quandonum_framesé definido explicitamente. - max_seconds (
float, opcional, padrão20.0) — Limite superior para a duração prevista automaticamente quandonum_framesé omitido e umduration_headestá presente. Ignorado quandonum_framesé definido explicitamente. Deve ser estritamente maior quemin_seconds. - frame_rate (
float, opcional, padrão24.0) — Os quadros por segundo (FPS) do vídeo gerado. - motion_speed (
float, opcional, padrão1.0) — Velocidade do movimento em relação ao tempo real. Os embeddings posicionais são condicionados emframe_rate / motion_speed, portanto, valores abaixo de 1 reduzem a velocidade do movimento, por exemplo,0.2para o slow motion de 5x do LoRA Slow-Motion-Control.frame_ratepermanece como a taxa de reprodução: a duração do áudio e o número previsto de quadros seguem essa taxa. - num_inference_steps (
int, opcional, padrão 30) — O número de etapas de desruidamento. Mais etapas de desruidamento geralmente resultam em uma imagem de maior qualidade, à custa de uma inferência mais lenta. - sigmas (
List[float], opcional) — Sigmas personalizados para usar no processo de desruidamento com agendadores que suportam um argumentosigmasem seu métodoset_timesteps. Se não definido, o comportamento padrão quandonum_inference_stepsé passado será usado. - timesteps (
list[int], opcional) — Timesteps personalizados para usar no processo de remoção de ruído com agendadores que suportam um argumentotimestepsem seu métodoset_timesteps. Se não definido, o comportamento padrão quandonum_inference_stepsé passado será usado. Deve estar em ordem decrescente. - guidance_scale (
float, opcional, padrão4.0) — Escala de orientação definida em Classifier-Free Diffusion Guidance.guidance_scaleé definido comowda equação 2 do Imagen Paper. A escala de orientação é ativada ao definirguidance_scale > 1. Uma escala de orientação maior incentiva a geração de imagens que estão intimamente ligadas aopromptde texto, geralmente em detrimento de uma menor qualidade de imagem. Usado para a modalidade de vídeo (há um valor separadoaudio_guidance_scalepara a modalidade de áudio). - stg_scale (
float, opcional, padrão0.0) — Escala de orientação de vídeo para Spatio-Temporal Guidance (STG), proposta em Spatiotemporal Skip Guidance for Enhanced Video Diffusion Sampling. O STG usa uma estimativa semelhante à CFG, na qual afastamos a amostra de uma amostra fraca de uma versão perturbada do modelo de desruido. Ativar o STG resultará em uma passagem adicional do modelo de desruido; o valor padrão de0.0significa que o STG está desativado. - modality_scale (
float, opcional, padrão1.0) — Escala de orientação de vídeo para o isolamento de modalidade do LTX-2.X, onde movemos a amostra para longe de uma amostra mais fraca gerada pelo modelo de desruidamento com a atenção cruzada entre modalidades (áudio-para-vídeo e vídeo-para-áudio) desativada, usando uma estimativa semelhante à CFG. Ativar a orientação de modalidade resultará em uma passada adicional do modelo de desruidamento; o valor padrão de1.0significa que a orientação de modalidade está desativada. - guidance_rescale (
float, opcional, padrão 0.0) — Fator de rescalonamento de orientação proposto por Common Diffusion Noise Schedules and Sample Steps are Flawedguidance_scaleé definido comoφna equação 16. de Common Diffusion Noise Schedules and Sample Steps are Flawed. O fator de rescalonamento de orientação deve corrigir a sobreexposição ao usar SNR terminal zero. Usado para a modalidade de vídeo. - audio_guidance_scale (
float, opcional padrãoNone) — Escala de orientação de áudio para CFG em relação ao prompt negativo. A regra de atualização do CFG é a mesma para vídeo e áudio, mas eles podem usar valores diferentes para a escala de orientação. Os autores do LTX-2.X sugerem que oaudio_guidance_scaledeve ser maior em relação aoguidance_scalede vídeo (por exemplo, para o LTX-2.3, eles sugerem 3.0 para vídeo e 7.0 para áudio). SeNone, o padrão é o valor de vídeoguidance_scale. - audio_stg_scale (
float, opcional, padrãoNone) — Escala de orientação de áudio para STG. Assim como no CFG, a regra de atualização do STG é a mesma para vídeo e áudio. Para o LTX-2.3, sugere-se o valor 1.0 para ambos, vídeo e áudio. SeNone, usa o valor de vídeostg_scalecomo padrão. - audio_modality_scale (
float, opcional, padrãoNone) — Escala de orientação de áudio para o isolamento de modalidade do LTX-2.X. Assim como no CFG, a regra de orientação de modalidade é a mesma para vídeo e áudio. Para o LTX-2.3, sugere-se o valor 3.0 para ambos, vídeo e áudio. SeNone, usa o valor de vídeomodality_scalecomo padrão. - audio_guidance_rescale (
float, opcional, padrãoNone) — Fator de rescale de guidance separado para a modalidade de áudio. SeNone, usa o valor de vídeoguidance_rescalecomo padrão. - spatio_temporal_guidance_blocks (
list[int], opcional, padrãoNone) — Os índices de blocos do transformer, com índice inicial zero, nos quais aplicar o STG. Deve ser fornecido se o STG for usado (stg_scaleouaudio_stg_scalefor maior que0). O valor[29]é recomendado para o LTX-2.0 e[28]é recomendado para o LTX-2.3. - noise_scale (
float, opcional, padrão0.0) — O fator de interpolação entre ruído aleatório e latentes desruídos em cada passo de tempo. Aplica ruído aoslatentseaudio_latentsantes de continuar o desruído. - num_videos_per_prompt (
int, opcional, padrão 1) — O número de vídeos a serem gerados por prompt. - generator (
torch.Generatoroulist[torch.Generator], opcional) — Um ou uma lista de geradores do torch para tornar a geração determinística. - latents (
torch.Tensor, opcional) — Latentes ruidosos pré-gerados, amostrados de uma distribuição gaussiana, a serem usados como entradas para a geração de vídeo. Pode ser usado para ajustar a mesma geração com diferentes prompts. Se não for fornecido, um tensor de latentes será gerado por amostragem usando ogeneratoraleatório fornecido. - audio_latents (
torch.Tensor, opcional) — Latentes ruidosos pré-gerados, amostrados de uma distribuição gaussiana, a serem usados como entradas para a geração de áudio. Pode ser usado para ajustar a mesma geração com diferentes prompts. Se não for fornecido, um tensor de latentes será gerado por amostragem usando ogeneratoraleatório fornecido. - prompt_embeds (
torch.Tensor, opcional) — Incorporações de texto pré-geradas. Podem ser usadas para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompts. Se não forem fornecidas, as incorporações de texto serão geradas a partir do argumento de entradaprompt. - prompt_attention_mask (
torch.Tensor, opcional) — Máscara de atenção pré-gerada para embeddings de texto. - negative_prompt_embeds (
torch.FloatTensor, opcional) — Incorporações de texto negativo pré-geradas. Para o PixArt-Sigma, este prompt negativo deve ser "". Se não for fornecido, negative_prompt_embeds será gerado a partir do argumento de entradanegative_prompt. - negative_prompt_attention_mask (
torch.FloatTensor, opcional) — Máscara de atenção pré-gerada para embeddings de texto negativos. - decode_timestep (
float, padrão0.0) — O timestep em que o vídeo gerado é decodificado. - decode_noise_scale (
float, padrãoNone) — O fator de interpolação entre o ruído aleatório e os latentes desruídos no passo de decodificação. - use_cross_timestep (
boolopcional, padrãoTrue) — Se deve usar o sigma da modalidade cruzada (áudio é a modalidade cruzada de vídeo, e vice-versa) ao calcular os parâmetros de modulação da atenção cruzada.Trueé o comportamento do LTX-2.3/2.5;Falseé o comportamento legado do LTX-2.0. - system_prompt (
str, opcional, padrãoNone) — Prompt de sistema opcional para uso no aprimoramento do prompt. O prompt de sistema será utilizado pelo aprimorador de prompts (um modelo de geração condicional Gemma — o componente dedicadoprompt_enhancer, se configurado, caso contrário o principaltext_encoder) para gerar um prompt aprimorado a partir do prompt originalpromptpara condicionar a geração. Se não fornecido e umprompt_enhancerdedicado estiver configurado (LTX-2.5), o padrão éLTX2_5_T2V_DEFAULT_SYSTEM_PROMPT(dediffusers.pipelines.ltx2.utils) — vejaenable_prompt_enhancement. - enable_prompt_enhancement (
bool, opcional, padrãoFalse) — Se deve executar o aprimoramento de prompt. Opcional, alinhado aos pipelines de referência da Lightricks. QuandoTrueesystem_prompté omitido, o LTX-2.5 usaLTX2_5_T2V_DEFAULT_SYSTEM_PROMPTse umprompt_enhancerdedicado estiver configurado; o LTX-2.0/2.3 exige umsystem_promptexplícito. - prompt_max_new_tokens (
int, opcional, padrãoNone) — O número máximo de novos tokens a serem gerados ao realizar o aprimoramento do prompt. Se não for fornecido, usa 600 para umprompt_enhancerdedicado do Gemma 4 (LTX-2.5) ou 512 para o fallback dotext_encoderdo Gemma 3 (LTX-2.0/2.3). - prompt_enhancement_kwargs (
dict[str, Any], opcional, padrãoNone) — Argumentos de palavra-chave para a chamada.generatedo aprimorador de prompt. Se não fornecidos, sempre correspondem ao modelo que está realizando o aprimoramento:do_sample=False, no_repeat_ngram_size=5(ganancioso) ao usar umprompt_enhancerdedicado (LTX-2.5), oudo_sample=True, temperature=0.7para o fallback dotext_encoder(LTX-2.0/2.3). Veja https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationMixin.generate para mais detalhes. - prompt_enhancement_seed (
int, opcional, padrão10) — Semente aleatória para qualquer operação aleatória durante o aprimoramento do prompt. - output_type (
str, opcional, padrão"pil") — O formato de saída da imagem gerada. Escolha entre PIL:PIL.Image.Imageounp.array. - return_dict (
bool, opcional, padrãoTrue) — Se deve ou não retornar um~pipelines.ltx.LTX2PipelineOutputem vez de uma tupla simples. - attention_kwargs (
dict, opcional) — Um dicionário de kwargs que, se especificado, é passado aoAttentionProcessorconforme definido emself.processorem diffusers.models.attention_processor. - callback_on_step_end (
Callable, opcional) — Uma função que é chamada no final de cada etapa de desruidamento durante a inferência. A função é chamada com os seguintes argumentos:callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict).callback_kwargsincluirá uma lista de todos os tensores, conforme especificado porcallback_on_step_end_tensor_inputs. - callback_on_step_end_tensor_inputs (
List, opcional, padrão["latents"]) — A lista de entradas de tensor para a funçãocallback_on_step_end. Os tensores especificados na lista serão passados como argumentocallback_kwargs. Você só poderá incluir variáveis listadas no atributo._callback_tensor_inputsda sua classe de pipeline. - max_sequence_length (
int, opcional, padrão1024) — Comprimento máximo da sequência a ser usado com oprompt.
Retorna
~pipelines.ltx.LTX2PipelineOutput ou tuple
Se return_dict for True, ~pipelines.ltx.LTX2PipelineOutput é retornado; caso contrário, uma tuple é retornada, onde o primeiro elemento é uma lista com as imagens geradas.
Função invocada ao chamar o pipeline para geração.
Exemplos:
>>> 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 (
stroulist[str], opcional) — prompt a ser codificado - negative_prompt (
stroulist[str], opcional) — O prompt ou os prompts que não devem orientar a geração da imagem. Se não for definido, é necessário passarnegative_prompt_embedsem vez disso. Ignorado quando não se usa orientação (ou seja, ignorado seguidance_scalefor menor que1). - do_classifier_free_guidance (
bool, opcional, padrãoTrue) — Se deve ou não usar classifier free guidance. - num_videos_per_prompt (
int, opcional, padrão 1) — Número de vídeos que devem ser gerados por prompt. Dispositivo torch para colocar os embeddings resultantes - prompt_embeds (
torch.Tensor, opcional) — Incorporações de texto pré-geradas. Podem ser usadas para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompts. Se não forem fornecidas, as incorporações de texto serão geradas a partir do argumento de entradaprompt. - negative_prompt_embeds (
torch.Tensor, opcional) — Incorporações de texto negativas pré-geradas. Pode ser usado para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompts. Se não for fornecido, negative_prompt_embeds será gerado a partir do argumento de entradanegative_prompt. - device — (
torch.device, opcional): dispositivo torch - dtype — (
torch.dtype, opcional): dtype do torch
Codifica o prompt em estados ocultos do 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 )
Melhora o prompt fornecido gerando um novo prompt a partir dele e de um prompt de sistema, utilizando o aprimorador de prompts (um modelo de geração condicional Gemma). Quando image é fornecido, o aprimorador também é condicionado nesse quadro de referência (aprimoramento no estilo I2V / keyframe). Usa o componente dedicado prompt_enhancer se um estiver configurado (por exemplo, LTX-2.5, cujo codificador de texto não foi treinado para aprimoramento); caso contrário, recorre ao text_encoder principal (LTX-2.0/2.3, que também atua como seu próprio aprimorador).
Os modelos de mensagem, os kwargs de decodificação, a limpeza da resposta e a preparação do lado longo da imagem correspondem a ltx-core / ltx-pipelines (enhance_t2v / enhance_i2v / generate_enhanced_prompt).
LTX2ImageToVideoPipeline
classe 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 geração de vídeo a partir de imagem.
Referência: 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) — A imagem de entrada para condicionar a geração. Deve ser uma imagem, uma lista de imagens ou umtorch.Tensor. - prompt (
stroulist[str], opcional) — O prompt ou os prompts para orientar a geração da imagem. Se não for definido, é necessário passarprompt_embedsem vez disso. - negative_prompt (
stroulist[str], opcional) — O prompt ou os prompts que não devem orientar a geração da imagem. Se não for definido, é necessário passarnegative_prompt_embedsem vez disso. Ignorado quando não está usando orientação (guidance_scale < 1). - height (
int, opcional, padrão512) — A altura em pixels da imagem gerada. Por padrão, é definida como 480 para obter os melhores resultados. - width (
int, opcional, padrão768) — A largura em pixels da imagem gerada. Por padrão, é definida como 848 para obter os melhores resultados. - num_frames (
int, opcional) — O número de quadros de vídeo a serem gerados. Se não for fornecido, o valor padrão é uma duração prevista automaticamente quando este pipeline possui um componenteduration_head(checkpoints LTX-2.5 e posteriores) e121caso contrário. Passe um inteiro para definir o comprimento explicitamente. As contagens previstas automaticamente são ajustadas à grade temporal causal do VAE, de modo que a duração realizada é quantizada (aproximadamente 0,33s a 24 fps). - min_seconds (
float, opcional, padrão1.0) — Limite inferior da duração prevista automaticamente quandonum_framesé omitido e umduration_headestá presente. Ignorado quandonum_framesé definido explicitamente. - max_seconds (
float, opcional, padrão20.0) — Limite superior para a duração prevista automaticamente quandonum_framesé omitido e umduration_headestá presente. Ignorado quandonum_framesé definido explicitamente. Deve ser estritamente maior quemin_seconds. - frame_rate (
float, opcional, padrão24.0) — Os quadros por segundo (FPS) do vídeo gerado. - motion_speed (
float, opcional, padrão1.0) — Velocidade do movimento em relação ao tempo real. Os embeddings posicionais são condicionados emframe_rate / motion_speed, portanto, valores abaixo de 1 reduzem a velocidade do movimento, por exemplo,0.2para o slow motion de 5x do LoRA Slow-Motion-Control.frame_ratepermanece como a taxa de reprodução: a duração do áudio e o número previsto de quadros seguem essa taxa. - num_inference_steps (
int, opcional, padrão 30) — O número de etapas de desruidamento. Mais etapas de desruidamento geralmente resultam em uma imagem de maior qualidade, à custa de uma inferência mais lenta. - sigmas (
List[float], opcional) — Sigmas personalizados para usar no processo de desruidamento com agendadores que suportam um argumentosigmasem seu métodoset_timesteps. Se não definido, o comportamento padrão quandonum_inference_stepsé passado será usado. - timesteps (
List[int], opcional) — Timesteps personalizados para usar no processo de remoção de ruído com agendadores que suportam um argumentotimestepsem seu métodoset_timesteps. Se não definido, o comportamento padrão quandonum_inference_stepsé passado será usado. Deve estar em ordem decrescente. - guidance_scale (
float, opcional, padrão4.0) — Escala de orientação definida em Classifier-Free Diffusion Guidance.guidance_scaleé definido comowda equação 2 do Imagen Paper. A escala de orientação é ativada ao definirguidance_scale > 1. Uma escala de orientação maior incentiva a geração de imagens que estão intimamente ligadas aopromptde texto, geralmente em detrimento de uma menor qualidade de imagem. Usado para a modalidade de vídeo (há um valor separadoaudio_guidance_scalepara a modalidade de áudio). - stg_scale (
float, opcional, padrão0.0) — Escala de orientação de vídeo para Spatio-Temporal Guidance (STG), proposta em Spatiotemporal Skip Guidance for Enhanced Video Diffusion Sampling. O STG usa uma estimativa semelhante à CFG, na qual afastamos a amostra de uma amostra fraca de uma versão perturbada do modelo de desruido. Ativar o STG resultará em uma passagem adicional do modelo de desruido; o valor padrão de0.0significa que o STG está desativado. - modality_scale (
float, opcional, padrão1.0) — Escala de orientação de vídeo para o isolamento de modalidade do LTX-2.X, onde movemos a amostra para longe de uma amostra mais fraca gerada pelo modelo de desruidamento com a atenção cruzada entre modalidades (áudio-para-vídeo e vídeo-para-áudio) desativada, usando uma estimativa semelhante à CFG. Ativar a orientação de modalidade resultará em uma passada adicional do modelo de desruidamento; o valor padrão de1.0significa que a orientação de modalidade está desativada. - guidance_rescale (
float, opcional, padrão 0.0) — Fator de rescalonamento de orientação proposto por Common Diffusion Noise Schedules and Sample Steps are Flawedguidance_scaleé definido comoφna equação 16. de Common Diffusion Noise Schedules and Sample Steps are Flawed. O fator de rescalonamento de orientação deve corrigir a sobreexposição ao usar SNR terminal zero. Usado para a modalidade de vídeo. - audio_guidance_scale (
float, opcional padrãoNone) — Escala de orientação de áudio para CFG em relação ao prompt negativo. A regra de atualização do CFG é a mesma para vídeo e áudio, mas eles podem usar valores diferentes para a escala de orientação. Os autores do LTX-2.X sugerem que oaudio_guidance_scaledeve ser maior em relação aoguidance_scalede vídeo (por exemplo, para o LTX-2.3, eles sugerem 3.0 para vídeo e 7.0 para áudio). SeNone, o padrão é o valor de vídeoguidance_scale. - audio_stg_scale (
float, opcional, padrãoNone) — Escala de orientação de áudio para STG. Assim como no CFG, a regra de atualização do STG é a mesma para vídeo e áudio. Para o LTX-2.3, sugere-se o valor 1.0 para ambos, vídeo e áudio. SeNone, usa o valor de vídeostg_scalecomo padrão. - audio_modality_scale (
float, opcional, padrãoNone) — Escala de orientação de áudio para o isolamento de modalidade do LTX-2.X. Assim como no CFG, a regra de orientação de modalidade é a mesma para vídeo e áudio. Para o LTX-2.3, sugere-se o valor 3.0 para ambos, vídeo e áudio. SeNone, usa o valor de vídeomodality_scalecomo padrão. - audio_guidance_rescale (
float, opcional, padrãoNone) — Fator de rescale de guidance separado para a modalidade de áudio. SeNone, usa o valor de vídeoguidance_rescalecomo padrão. - spatio_temporal_guidance_blocks (
list[int], opcional, padrãoNone) — Os índices de blocos do transformer, com índice inicial zero, nos quais aplicar o STG. Deve ser fornecido se o STG for usado (stg_scaleouaudio_stg_scalefor maior que0). O valor[29]é recomendado para o LTX-2.0 e[28]é recomendado para o LTX-2.3. - noise_scale (
float, opcional, padrão0.0) — O fator de interpolação entre ruído aleatório e latentes desruídos em cada passo de tempo. Aplica ruído aoslatentseaudio_latentsantes de continuar o desruído. - num_videos_per_prompt (
int, opcional, padrão 1) — O número de vídeos a serem gerados por prompt. - generator (
torch.Generatoroulist[torch.Generator], opcional) — Um ou uma lista de geradores do torch para tornar a geração determinística. - latents (
torch.Tensor, opcional) — Latentes ruidosos pré-gerados, amostrados de uma distribuição gaussiana, a serem usados como entradas para a geração de vídeo. Pode ser usado para ajustar a mesma geração com diferentes prompts. Se não for fornecido, um tensor de latentes será gerado por amostragem usando ogeneratoraleatório fornecido. - audio_latents (
torch.Tensor, opcional) — Latentes ruidosos pré-gerados, amostrados de uma distribuição gaussiana, a serem usados como entradas para a geração de áudio. Pode ser usado para ajustar a mesma geração com diferentes prompts. Se não for fornecido, um tensor de latentes será gerado por amostragem usando ogeneratoraleatório fornecido. - prompt_embeds (
torch.Tensor, opcional) — Incorporações de texto pré-geradas. Podem ser usadas para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompts. Se não forem fornecidas, as incorporações de texto serão geradas a partir do argumento de entradaprompt. - prompt_attention_mask (
torch.Tensor, opcional) — Máscara de atenção pré-gerada para embeddings de texto. - negative_prompt_embeds (
torch.FloatTensor, opcional) — Incorporações de texto negativo pré-geradas. Para o PixArt-Sigma, este prompt negativo deve ser "". Se não for fornecido, negative_prompt_embeds será gerado a partir do argumento de entradanegative_prompt. - negative_prompt_attention_mask (
torch.FloatTensor, opcional) — Máscara de atenção pré-gerada para embeddings de texto negativos. - decode_timestep (
float, padrão0.0) — O timestep em que o vídeo gerado é decodificado. - decode_noise_scale (
float, padrãoNone) — O fator de interpolação entre o ruído aleatório e os latentes desruídos no passo de decodificação. - use_cross_timestep (
boolopcional, padrãoTrue) — Se deve usar o sigma da modalidade cruzada (áudio é a modalidade cruzada de vídeo, e vice-versa) ao calcular os parâmetros de modulação da atenção cruzada.Trueé o comportamento do LTX-2.3/2.5;Falseé o comportamento legado do LTX-2.0. - system_prompt (
str, opcional, padrãoNone) — Prompt de sistema opcional para uso no aprimoramento do prompt. O prompt de sistema será utilizado pelo aprimorador de prompts (um modelo de geração condicional Gemma — o componente dedicadoprompt_enhancer, se configurado, caso contrário o principaltext_encoder) para gerar um prompt aprimorado a partir dopromptoriginal e da primeiraimagepara condicionar a geração. Se não fornecido e umprompt_enhancerdedicado estiver configurado (LTX-2.5), o padrão éLTX2_5_I2V_DEFAULT_SYSTEM_PROMPT(dediffusers.pipelines.ltx2.utils) — vejaenable_prompt_enhancement. - enable_prompt_enhancement (
bool, opcional, padrãoFalse) — Se deve executar o aprimoramento de prompt. Opcional, alinhado aos pipelines de referência da Lightricks. QuandoTrueesystem_prompté omitido, o LTX-2.5 usaLTX2_5_I2V_DEFAULT_SYSTEM_PROMPTse umprompt_enhancerdedicado estiver configurado; o LTX-2.0/2.3 exige umsystem_promptexplícito. - prompt_max_new_tokens (
int, opcional, padrãoNone) — O número máximo de novos tokens a serem gerados ao realizar o aprimoramento do prompt. Se não for fornecido, usa 600 para umprompt_enhancerdedicado do Gemma 4 (LTX-2.5) ou 512 para o fallback dotext_encoderdo Gemma 3 (LTX-2.0/2.3). - prompt_enhancement_kwargs (
dict[str, Any], opcional, padrãoNone) — Argumentos de palavra-chave para a chamada.generatedo aprimorador de prompt. Se não fornecidos, sempre correspondem ao modelo que está realizando o aprimoramento:do_sample=False, no_repeat_ngram_size=3(ganancioso) ao usar umprompt_enhancerdedicado (LTX-2.5), oudo_sample=True, temperature=0.7para o fallback dotext_encoder(LTX-2.0/2.3). Veja https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationMixin.generate para mais detalhes. - prompt_enhancement_seed (
int, opcional, padrão10) — Semente aleatória para qualquer operação aleatória durante o aprimoramento do prompt. - image_crf (
int, opcional, padrãoNone) — CRF do H.264 usado para recomprimir aimagede condicionamento antes da codificação pelo VAE, correspondendo à compressão com a qual o modelo foi treinado.Nonesignifica “usar o padrão do modelo” (33 até o LTX-2.3, 18 para o LTX-2.5). Passe0para pular a recompressão. Exige umPIL.Image.Imagequando a recompressão é executada. - output_type (
str, opcional, padrão"pil") — O formato de saída da imagem gerada. Escolha entre PIL:PIL.Image.Imageounp.array. - return_dict (
bool, opcional, padrãoTrue) — Se deve ou não retornar um~pipelines.ltx.LTX2PipelineOutputem vez de uma tupla simples. - attention_kwargs (
dict, opcional) — Um dicionário de kwargs que, se especificado, é passado aoAttentionProcessorconforme definido emself.processorem diffusers.models.attention_processor. - callback_on_step_end (
Callable, opcional) — Uma função que é chamada no final de cada etapa de desruidamento durante a inferência. A função é chamada com os seguintes argumentos:callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict).callback_kwargsincluirá uma lista de todos os tensores, conforme especificado porcallback_on_step_end_tensor_inputs. - callback_on_step_end_tensor_inputs (
List, opcional) — A lista de entradas de tensor para a funçãocallback_on_step_end. Os tensores especificados na lista serão passados como argumentocallback_kwargs. Você só poderá incluir variáveis listadas no atributo._callback_tensor_inputsda sua classe de pipeline. - max_sequence_length (
int, opcional, padrão1024) — Comprimento máximo da sequência a ser usado com oprompt.
Retorna
~pipelines.ltx.LTX2PipelineOutput ou tuple
Se return_dict for True, ~pipelines.ltx.LTX2PipelineOutput é retornado; caso contrário, uma tuple é retornada, onde o primeiro elemento é uma lista com as imagens geradas.
Função invocada ao chamar o pipeline para geração.
Exemplos:
>>> 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 (
stroulist[str], opcional) — prompt a ser codificado - negative_prompt (
stroulist[str], opcional) — O prompt ou os prompts que não devem orientar a geração da imagem. Se não for definido, é necessário passarnegative_prompt_embedsem vez disso. Ignorado quando não se usa orientação (ou seja, ignorado seguidance_scalefor menor que1). - do_classifier_free_guidance (
bool, opcional, padrãoTrue) — Se deve ou não usar classifier free guidance. - num_videos_per_prompt (
int, opcional, padrão 1) — Número de vídeos que devem ser gerados por prompt. Dispositivo torch para colocar os embeddings resultantes - prompt_embeds (
torch.Tensor, opcional) — Incorporações de texto pré-geradas. Podem ser usadas para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompts. Se não forem fornecidas, as incorporações de texto serão geradas a partir do argumento de entradaprompt. - negative_prompt_embeds (
torch.Tensor, opcional) — Incorporações de texto negativas pré-geradas. Pode ser usado para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompts. Se não for fornecido, negative_prompt_embeds será gerado a partir do argumento de entradanegative_prompt. - device — (
torch.device, opcional): dispositivo torch - dtype — (
torch.dtype, opcional): dtype do torch
Codifica o prompt em estados ocultos do 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 )
Melhora o prompt fornecido gerando um novo prompt a partir dele e de um prompt de sistema, utilizando o aprimorador de prompts (um modelo de geração condicional Gemma). Quando image é fornecido, o aprimorador também é condicionado nesse quadro de referência (aprimoramento no estilo I2V / keyframe). Usa o componente dedicado prompt_enhancer se um estiver configurado (por exemplo, LTX-2.5, cujo codificador de texto não foi treinado para aprimoramento); caso contrário, recorre ao text_encoder principal (LTX-2.0/2.3, que também atua como seu próprio aprimorador).
Os modelos de mensagem, os kwargs de decodificação, a limpeza da resposta e a preparação do lado longo da imagem correspondem a ltx-core / ltx-pipelines (enhance_t2v / enhance_i2v / generate_enhanced_prompt).
LTX2ConditionPipeline
classe 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 geração de vídeo que permite inserir condições de imagem em partes arbitrárias do vídeo.
Referência: 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*) — A lista de itens de condicionamento de quadros para a geração de vídeo. - prompt (
strouList[str], opcional) — O prompt ou os prompts para orientar a geração da imagem. Se não for definido, é necessário passarprompt_embedsem vez disso. - negative_prompt (
strouList[str], opcional) — O prompt ou os prompts que não devem orientar a geração da imagem. Se não for definido, é necessário passarnegative_prompt_embedsem vez disso. Ignorado quando não está usando orientação (guidance_scale < 1). - height (
int, opcional, padrão512) — A altura em pixels da imagem gerada. Por padrão, é definida como 480 para obter os melhores resultados. - width (
int, opcional, padrão768) — A largura em pixels da imagem gerada. Por padrão, é definida como 848 para obter os melhores resultados. - num_frames (
int, opcional) — O número de quadros de vídeo a serem gerados. Se não for fornecido, o valor padrão é uma duração prevista automaticamente quando este pipeline possui um componenteduration_head(checkpoints LTX-2.5 e posteriores) e121caso contrário. Passe um inteiro para definir o comprimento explicitamente. As contagens previstas automaticamente são ajustadas à grade temporal causal do VAE, de modo que a duração realizada é quantizada (aproximadamente 0,33s a 24 fps). - min_seconds (
float, opcional, padrão1.0) — Limite inferior da duração prevista automaticamente quandonum_framesé omitido e umduration_headestá presente. Ignorado quandonum_framesé definido explicitamente. - max_seconds (
float, opcional, padrão20.0) — Limite superior para a duração prevista automaticamente quandonum_framesé omitido e umduration_headestá presente. Ignorado quandonum_framesé definido explicitamente. Deve ser estritamente maior quemin_seconds. - frame_rate (
float, opcional, padrão24.0) — Os quadros por segundo (FPS) do vídeo gerado. - motion_speed (
float, opcional, padrão1.0) — Velocidade do movimento em relação ao tempo real. Os embeddings posicionais são condicionados emframe_rate / motion_speed, portanto, valores abaixo de 1 reduzem a velocidade do movimento, por exemplo,0.2para o slow motion de 5x do LoRA Slow-Motion-Control.frame_ratepermanece como a taxa de reprodução: a duração do áudio e o número previsto de quadros seguem essa taxa. - num_inference_steps (
int, opcional, padrão 30) — O número de etapas de desruidamento. Mais etapas de desruidamento geralmente resultam em uma imagem de maior qualidade, à custa de uma inferência mais lenta. - sigmas (
List[float], opcional) — Sigmas personalizados para usar no processo de desruidamento com agendadores que suportam um argumentosigmasem seu métodoset_timesteps. Se não definido, o comportamento padrão quandonum_inference_stepsé passado será usado. - timesteps (
List[int], opcional) — Timesteps personalizados para usar no processo de remoção de ruído com agendadores que suportam um argumentotimestepsem seu métodoset_timesteps. Se não definido, o comportamento padrão quandonum_inference_stepsé passado será usado. Deve estar em ordem decrescente. - guidance_scale (
float, opcional, padrão4.0) — Escala de orientação definida em Classifier-Free Diffusion Guidance.guidance_scaleé definido comowda equação 2 do Imagen Paper. A escala de orientação é ativada ao definirguidance_scale > 1. Uma escala de orientação maior incentiva a geração de imagens que estão intimamente ligadas aopromptde texto, geralmente em detrimento de uma menor qualidade de imagem. Usado para a modalidade de vídeo (há um valor separadoaudio_guidance_scalepara a modalidade de áudio). - stg_scale (
float, opcional, padrão0.0) — Escala de orientação de vídeo para Spatio-Temporal Guidance (STG), proposta em Spatiotemporal Skip Guidance for Enhanced Video Diffusion Sampling. O STG usa uma estimativa semelhante à CFG, na qual afastamos a amostra de uma amostra fraca de uma versão perturbada do modelo de desruido. Ativar o STG resultará em uma passagem adicional do modelo de desruido; o valor padrão de0.0significa que o STG está desativado. - modality_scale (
float, opcional, padrão1.0) — Escala de orientação de vídeo para o isolamento de modalidade do LTX-2.X, onde movemos a amostra para longe de uma amostra mais fraca gerada pelo modelo de desruidamento com a atenção cruzada entre modalidades (áudio-para-vídeo e vídeo-para-áudio) desativada, usando uma estimativa semelhante à CFG. Ativar a orientação de modalidade resultará em uma passada adicional do modelo de desruidamento; o valor padrão de1.0significa que a orientação de modalidade está desativada. - guidance_rescale (
float, opcional, padrão 0.0) — Fator de rescalonamento de orientação proposto por Common Diffusion Noise Schedules and Sample Steps are Flawedguidance_scaleé definido comoφna equação 16. de Common Diffusion Noise Schedules and Sample Steps are Flawed. O fator de rescalonamento de orientação deve corrigir a sobreexposição ao usar SNR terminal zero. Usado para a modalidade de vídeo. - audio_guidance_scale (
float, opcional padrãoNone) — Escala de orientação de áudio para CFG em relação ao prompt negativo. A regra de atualização do CFG é a mesma para vídeo e áudio, mas eles podem usar valores diferentes para a escala de orientação. Os autores do LTX-2.X sugerem que oaudio_guidance_scaledeve ser maior em relação aoguidance_scalede vídeo (por exemplo, para o LTX-2.3, eles sugerem 3.0 para vídeo e 7.0 para áudio). SeNone, o padrão é o valor de vídeoguidance_scale. - audio_stg_scale (
float, opcional, padrãoNone) — Escala de orientação de áudio para STG. Assim como no CFG, a regra de atualização do STG é a mesma para vídeo e áudio. Para o LTX-2.3, sugere-se o valor 1.0 para ambos, vídeo e áudio. SeNone, usa o valor de vídeostg_scalecomo padrão. - audio_modality_scale (
float, opcional, padrãoNone) — Escala de orientação de áudio para o isolamento de modalidade do LTX-2.X. Assim como no CFG, a regra de orientação de modalidade é a mesma para vídeo e áudio. Para o LTX-2.3, sugere-se o valor 3.0 para ambos, vídeo e áudio. SeNone, usa o valor de vídeomodality_scalecomo padrão. - audio_guidance_rescale (
float, opcional, padrãoNone) — Fator de rescale de guidance separado para a modalidade de áudio. SeNone, usa o valor de vídeoguidance_rescalecomo padrão. - spatio_temporal_guidance_blocks (
list[int], opcional, padrãoNone) — Os índices de blocos do transformer, com índice inicial zero, nos quais aplicar o STG. Deve ser fornecido se o STG for usado (stg_scaleouaudio_stg_scalefor maior que0). O valor[29]é recomendado para o LTX-2.0 e[28]é recomendado para o LTX-2.3. - noise_scale (
float, opcional, padrãoNone) — O fator de interpolação entre ruído aleatório e latentes desruídos em cada passo de tempo. Aplica ruído aoslatentseaudio_latentsantes de continuar o desruído. Se não definido, será inferido a partir da agenda de sigma. - num_videos_per_prompt (
int, opcional, padrão 1) — O número de vídeos a serem gerados por prompt. - generator (
torch.GeneratorouList[torch.Generator], opcional) — Um ou uma lista de geradores do torch para tornar a geração determinística. - latents (
torch.Tensor, opcional) — Latentes ruidosos pré-gerados, amostrados de uma distribuição gaussiana, a serem usados como entradas para a geração de vídeo. Pode ser usado para ajustar a mesma geração com diferentes prompts. Se não for fornecido, um tensor de latentes será gerado por amostragem usando ogeneratoraleatório fornecido. - audio_latents (
torch.Tensor, opcional) — Latentes ruidosos pré-gerados, amostrados de uma distribuição gaussiana, a serem usados como entradas para a geração de áudio. Pode ser usado para ajustar a mesma geração com diferentes prompts. Se não for fornecido, um tensor de latentes será gerado por amostragem usando ogeneratoraleatório fornecido. - prompt_embeds (
torch.Tensor, opcional) — Incorporações de texto pré-geradas. Podem ser usadas para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompts. Se não forem fornecidas, as incorporações de texto serão geradas a partir do argumento de entradaprompt. - prompt_attention_mask (
torch.Tensor, opcional) — Máscara de atenção pré-gerada para embeddings de texto. - negative_prompt_embeds (
torch.FloatTensor, opcional) — Incorporações de texto negativo pré-geradas. Para o PixArt-Sigma, este prompt negativo deve ser "". Se não for fornecido, negative_prompt_embeds será gerado a partir do argumento de entradanegative_prompt. - negative_prompt_attention_mask (
torch.FloatTensor, opcional) — Máscara de atenção pré-gerada para embeddings de texto negativos. - decode_timestep (
float, padrão0.0) — O timestep em que o vídeo gerado é decodificado. - decode_noise_scale (
float, padrãoNone) — O fator de interpolação entre o ruído aleatório e os latentes desruídos no passo de decodificação. - use_cross_timestep (
boolopcional, padrãoTrue) — Se deve usar o sigma da modalidade cruzada (áudio é a modalidade cruzada de vídeo, e vice-versa) ao calcular os parâmetros de modulação da atenção cruzada.Trueé o comportamento do LTX-2.3/2.5;Falseé o comportamento legado do LTX-2.0. - system_prompt (
str, opcional, padrãoNone) — Prompt de sistema opcional para uso no aprimoramento do prompt. O prompt de sistema será utilizado pelo aprimorador de prompts (um modelo de geração condicional Gemma — o componente dedicadoprompt_enhancer, se configurado, caso contrário o principaltext_encoder) para gerar um prompt aprimorado a partir do prompt originalprompt(e uma imagem de condicionamento, quando disponível) para condicionar a geração. Se não fornecido e umprompt_enhancerdedicado estiver configurado (LTX-2.5), o padrão seráLTX2_5_I2V_DEFAULT_SYSTEM_PROMPTquando uma imagem de condicionamento estiver disponível, caso contrárioLTX2_5_T2V_DEFAULT_SYSTEM_PROMPT— vejaenable_prompt_enhancement. - enable_prompt_enhancement (
bool, opcional, padrãoFalse) — Se deve executar o aprimoramento de prompt. Opcional, alinhado aos pipelines de referência da Lightricks. QuandoTrueesystem_prompté omitido, o LTX-2.5 selecionaLTX2_5_I2V_DEFAULT_SYSTEM_PROMPT/LTX2_5_T2V_DEFAULT_SYSTEM_PROMPTcom base na disponibilidade de uma imagem de condicionamento. - prompt_max_new_tokens (
int, opcional, padrãoNone) — O número máximo de novos tokens a serem gerados ao realizar o aprimoramento do prompt. Se não for fornecido, usa 600 para umprompt_enhancerdedicado do Gemma 4 (LTX-2.5) ou 512 para o fallback dotext_encoderdo Gemma 3 (LTX-2.0/2.3). - prompt_enhancement_kwargs (
dict[str, Any], opcional, padrãoNone) — Argumentos de palavra-chave para a chamada.generatedo aprimorador de prompt. Se não fornecidos, sempre correspondem ao modelo que está realizando o aprimoramento:do_sample=False, no_repeat_ngram_size=5(ganancioso) ao usar umprompt_enhancerdedicado (LTX-2.5), oudo_sample=True, temperature=0.7para o fallback dotext_encoder(LTX-2.0/2.3). Veja https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationMixin.generate para mais detalhes. - prompt_enhancement_seed (
int, opcional, padrão10) — Semente aleatória para qualquer operação aleatória durante o aprimoramento do prompt. - output_type (
str, opcional, padrão"pil") — O formato de saída da imagem gerada. Escolha entre PIL:PIL.Image.Imageounp.array. - return_dict (
bool, opcional, padrãoTrue) — Se deve ou não retornar um~pipelines.ltx.LTX2PipelineOutputem vez de uma tupla simples. - attention_kwargs (
dict, opcional) — Um dicionário de kwargs que, se especificado, é passado aoAttentionProcessorconforme definido emself.processorem diffusers.models.attention_processor. - callback_on_step_end (
Callable, opcional) — Uma função que é chamada no final de cada etapa de desruidamento durante a inferência. A função é chamada com os seguintes argumentos:callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict).callback_kwargsincluirá uma lista de todos os tensores, conforme especificado porcallback_on_step_end_tensor_inputs. - callback_on_step_end_tensor_inputs (
List, opcional) — A lista de entradas de tensor para a funçãocallback_on_step_end. Os tensores especificados na lista serão passados como argumentocallback_kwargs. Você só poderá incluir variáveis listadas no atributo._callback_tensor_inputsda sua classe de pipeline. - max_sequence_length (
int, opcional, padrão1024) — Comprimento máximo da sequência a ser usado com oprompt.
Retorna
~pipelines.ltx.LTX2PipelineOutput ou tuple
Se return_dict for True, ~pipelines.ltx.LTX2PipelineOutput é retornado; caso contrário, uma tuple é retornada, onde o primeiro elemento é uma lista com as imagens geradas.
Função invocada ao chamar o pipeline para geração.
Exemplos:
>>> 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 empacotados (patchificados) iniciais, com forma [batch_size, patch_seq_len, hidden_dim]. - conditioning_mask (
torch.Tensor) — Máscara de condicionamento inicial empacotada (patchificada) com forma [batch_size, patch_seq_len, 1] e valores em [0, 1], em que 0 significa que a saída do modelo de desruidamento será totalmente utilizada e 1 significa que o condicionamento será totalmente utilizado.
Retorna
Tuple[torch.Tensor, torch.Tensor, torch.Tensor]
Retorna uma 3-tupla de tensores onde:
- Os latentes de vídeo empacotados com as condições do primeiro quadro aplicadas.
- A máscara de condicionamento empacotada com as intensidades do primeiro quadro aplicadas.
- Os latentes de condicionamento limpos nas posições do primeiro quadro (zeros em outros lugares).
Aplique a condicionamento visual do primeiro quadro sobrescrevendo os tokens nas posições do primeiro quadro.
Somente as condições com latent_idx == 0 são aplicadas aqui (correspondendo a VideoConditionByLatentIndex na
implementação de referência). Condições em índices latentes não nulos são adicionadas como tokens de keyframe separados via prepare_keyframe_extras (correspondendo a VideoConditionByKeyframeIndex) e são ignoradas aqui.
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 (
stroulist[str], opcional) — prompt a ser codificado - negative_prompt (
stroulist[str], opcional) — O prompt ou os prompts que não devem orientar a geração da imagem. Se não for definido, é necessário passarnegative_prompt_embedsem vez disso. Ignorado quando não se usa orientação (ou seja, ignorado seguidance_scalefor menor que1). - do_classifier_free_guidance (
bool, opcional, padrãoTrue) — Se deve ou não usar classifier free guidance. - num_videos_per_prompt (
int, opcional, padrão 1) — Número de vídeos que devem ser gerados por prompt. Dispositivo torch para colocar os embeddings resultantes - prompt_embeds (
torch.Tensor, opcional) — Incorporações de texto pré-geradas. Podem ser usadas para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompts. Se não forem fornecidas, as incorporações de texto serão geradas a partir do argumento de entradaprompt. - negative_prompt_embeds (
torch.Tensor, opcional) — Incorporações de texto negativas pré-geradas. Pode ser usado para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompts. Se não for fornecido, negative_prompt_embeds será gerado a partir do argumento de entradanegative_prompt. - device — (
torch.device, opcional): dispositivo torch - dtype — (
torch.dtype, opcional): dtype do torch
Codifica o prompt em estados ocultos do 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 )
Melhora o prompt fornecido gerando um novo prompt a partir dele e de um prompt de sistema, utilizando o aprimorador de prompts (um modelo de geração condicional Gemma). Quando image é fornecido, o aprimorador também é condicionado nesse quadro de referência (aprimoramento no estilo I2V / keyframe). Usa o componente dedicado prompt_enhancer se um estiver configurado (por exemplo, LTX-2.5, cujo codificador de texto não foi treinado para aprimoramento); caso contrário, recorre ao text_encoder principal (LTX-2.0/2.3, que também atua como seu próprio aprimorador).
Os modelos de mensagem, os kwargs de decodificação, a limpeza da resposta e a preparação do lado longo da imagem correspondem a 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 )
Prepare os latentes de vídeo com ruído, aplicando as condições de quadro.
As condições do primeiro quadro (latent_idx == 0) são aplicadas sobrescrevendo os tokens nas posições do primeiro quadro
(semântica de VideoConditionByLatentIndex). As condições de quadros que não são o primeiro (latent_idx > 0) são concatenadas à
sequência latente principal com conditioning_mask = strength por token (semântica de VideoConditionByKeyframeIndex) — a fórmula de timestep existente do loop de desruidamento t * (1 - conditioning_mask) e a mistura de pós-processamento
denoised * (1 - conditioning_mask) + clean * conditioning_mask então as conduzem ao longo das etapas.
Retorna uma 4-tupla:
latents: latentes ruidosos empacotados (tokens de base + quaisquer tokens de keyframe concatenados na dimensão da sequência).conditioning_mask: máscara de condicionamento compactada com valores em[0, 1]—1nas posições do primeiro quadro,strengthnas posições dos quadros-chave e0em todos os outros.clean_latents: valores de condição limpos nas posições condicionadas (zeros em outros lugares); mesmo formato quelatents.keyframe_coords: coordenadas posicionais[B, 3, num_keyframe_patches, 2]para anexar avideo_coords, ouNonese não houver condições de quadros que não sejam o primeiro.
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 (
LTX2VideoConditionouList[LTX2VideoCondition], opcional, padrãoNone) — Uma lista de instâncias de condição de imagem/vídeo. - height (
int, opcional, padrão512) — A altura desejada em pixels. - width (
int, opcional, padrão768) — A largura desejada em pixels. - num_frames (
int, opcional, padrão121) — O número desejado de quadros no vídeo gerado. - device (
torch.device, opcional, padrãoNone) — O dispositivo em que os tensores de imagem/vídeo pré-processados devem ser colocados.
Retorna
Tuple[List[torch.Tensor], List[float], List[int], List[int]]
Retorna uma 4-tupla de listas de comprimento len(conditions) da seguinte forma:
- A primeira lista é uma lista de tensores de vídeo pré-processados com forma [batch_size=1, num_channels, num_frames, height, width].
- A segunda lista é uma lista de intensidades de condicionamento.
- A terceira lista é uma lista de índices do espaço latente para cada condição.
- A quarta lista é uma lista de contagens de quadros (recortados) no espaço de pixels por condição. Isso é necessário para a semântica de coordenadas de quadros-chave (quadros-chave de um único quadro de pixel têm uma extensão temporal limitada).
Pré-processa as imagens/vídeos de condição para tensores do torch.
trim_conditioning_sequence
< source >( start_frame: intsequence_num_frames: inttarget_num_frames: int ) → int
Reduza uma sequência de condicionamento para o número permitido de quadros.
LTX2DFRPipeline
classe 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) —
Um scheduler a ser usado em combinação com
transformerpara desruidar os latentes de vídeo codificados. - vae (AutoencoderKLLTX2Video) — Modelo de Autoencoder Variacional (VAE) para codificar e decodificar vídeos a partir de e para representações latentes.
- audio_vae (AutoencoderKLLTX2Audio) — VAE de áudio para codificar e decodificar espectrogramas de áudio.
- text_encoder (
Gemma3ForConditionalGenerationouGemma4UnifiedForConditionalGeneration) — Modelo de codificador de texto. - tokenizer (
GemmaTokenizerouGemmaTokenizerFast) — Tokenizer para o codificador de texto. - connectors (
LTX2TextConnectors) — Pilha de conectores de texto usada para adaptar os estados ocultos do codificador de texto para os ramos de vídeo e áudio. - transformer (LTX2VideoTransformer3DModel) — Arquitetura de Transformer condicional para desruidar os latentes de vídeo codificados.
- vocoder (
LTX2VocoderouLTX2VocoderWithBWE) — Vocoder para converter espectrogramas mel em formas de onda de áudio. - processor (
ProcessorMixin, opcional) — Processador usado para o aprimoramento de prompts e chat templating. - prompt_enhancer (
Gemma4ForConditionalGeneration, opcional) — Modelo dedicado para aprimoramento de prompt (LTX-2.5). - duration_head (
LTX2DurationHead, opcional) — Prevênum_framesa partir dos embeddings do prompt quandonum_framesnão é fornecido.
Pipeline para uma passagem de desruído de Diffusion Fidelity Rendering (DFR) com LTX-2.5.
A pass gera vídeo e slots de keyframe de quadro único extra, ou re-denoise latentes fornecidos semeados a partir desses slots. Os chamadores compõem os estágios: este pipeline em meia resolução, LTX2LatentUpsamplePipeline espacialmente, este pipeline novamente em resolução completa com os slots upsampled e uma referência IC-LoRA, e então LTX2DFRTemporalRefinePipeline para cada rodada de refinamento temporal. Consulte a documentação do LTX-2 para a receita de 1080p.
As posições dos slots vêm de uma grade de segmentos alinhada à borda temporal do VAE (resolve_canvas). A grade é
preenchida até um número inteiro de segmentos; output_type="latent" retorna essa grade preenchida para que um slot no preenchimento não seja
descartado. Use trim_canvas antes da decodificação pelo VAE.
Exige um transformer cuja configuração defina use_keyframes_abs_pos_embedding (LTX-2.5 e versões posteriores) quando generate_slots=True.
Referência: 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 (
strouList[str], opcional) — O prompt ou prompts para orientar a geração do vídeo. Se não definido, é necessário passarprompt_embeds. - conditions (
LTX2VideoConditionouList[LTX2VideoCondition], opcional) — Condições de imagem ou vídeo em nível de quadro.indexé um índice latent nonum_framesdesta passagem. - height (
int, opcional, padrão704) — A altura em pixels de esta passagem, não a saída final composta. - width (
int, opcional, padrão1216) — A largura em pixels desta passagem. - num_frames (
int, opcional) — Número de quadros em pixels desta passagem, antes do preenchimento interno do canvas. Se não for fornecido, a duração é prevista a partir do prompt peloduration_head. Deve satisfazer(num_frames - 1) % 8 == 0. - frame_rate (
float, opcional, padrão24.0) — FPS de reprodução desta passagem. O tempo do RoPE é arredondado para 60 sempre que este valor for superior a 30. - min_seconds (
float, opcional, padrão1.0) — Limite inferior da duração prevista automaticamente quandonum_framesé omitido. - max_seconds (
float, opcional, padrão20.0) — Limite superior para a duração prevista automaticamente quandonum_framesé omitido. - latents (
torch.Tensor, opcional) — Latentes de vídeo brutos(batch_size, channels, frames, height, width)para re-remover ruído (etapa 2 / epílogo). - audio_latents (
torch.Tensor, opcional) — Latentes de áudio brutos e descompactados(batch_size, channels, length, mel_bins). A etapa 2 ainda executa uma passagem de áudio conjunta; a forma de onda enviada de uma receita composta é a da etapa 1, que o chamador mantém. - keyframes_latents (
torch.Tensor, opcional) — Iniciais de slot brutas(batch_size, channels, num_slots, height, width), usadas quandogenerate_slots=True. - keyframe_positions (
list[int], opcional) — Índices de quadros em pixels dos slots gerados. O padrão éresolve_canvas(num_frames). - reference_latents (
torch.Tensor, opcional) — Vídeo de referência bruto do IC-LoRA (geralmente os quadros da etapa 1). - reference_downscale_factor (
int, opcional, padrão2) — Proporção entre esta passagem e a resolução de referência, usada para escalar as coordenadas dos tokens de referência. - guidance_keyframe_latents (
torch.Tensor, opcional) — Keyframes de orientação bruto fixados(batch_size, channels, K, height, width)— o caminho do epílogo. Não são slots gerados. - guidance_keyframe_positions (
list[int], opcional) — Índices de quadros em pixels paraguidance_keyframe_latents. - guidance_keyframe_strength (
float, opcional, padrão1.0) — Força de condicionamento para keyframes de orientação fixos. - generate_slots (
bool, opcional, padrãoTrue) — Acrescenta tokens de slot de keyframe gerados. O epílogo define isso comoFalsee fixaguidance_keyframe_latentsem vez disso. - sigmas (
list[float], opcional) — Agenda de ruído para esta passagem, sem o terminal0.0. - noise_scale (
float, opcional) — Nível de ruído em que os tokens não condicionados começam. O padrão ésigmas[0]. - freeze_audio (
bool, opcional, padrãoFalse) — Mantém o áudio em sigma 0 (epílogo / ao seguir uma forma de onda da etapa 1 congelada). - video_tiles (
list[LTX2DFREpilogueTile], opcional) — Tiling de epílogo deepilogue_tiles(), para que uma resolução grande demais para uma única passagem de forward ainda possa avançar um único canvas: cada passo executa o transformer uma vez por tile e combina as previsões. Isso é resolvido em um plano de tokens em relação às próprias coordenadas RoPE desta passagem, o que é o motivo pelo qual o layout é passado em vez do plano — as coordenadas só existem depois que prepare_latents() foi executado. - num_videos_per_prompt (
int, opcional, padrão 1) — O número de vídeos a serem gerados por prompt. - generator (
torch.Generatoroulist[torch.Generator], opcional) — Gerador(es) aleatório(s) para reprodutibilidade. - prompt_embeds (
torch.Tensor, opcional) — Incorporações de texto pré-geradas. - prompt_attention_mask (
torch.Tensor, opcional) — Máscara de atenção pré-gerada para embeddings de texto. - decode_timestep (
float, padrão0.0) — O timestep em que o vídeo gerado é decodificado. - decode_noise_scale (
float, padrãoNone) — Escala de ruído no momento da decodificação. - use_cross_timestep (
bool, opcional, padrãoTrue) — Se deve usar sigma de cross-modality para modulação de cross attention.Truepara LTX-2.3+. - system_prompt (
str, opcional) — Prompt de sistema opcional para aprimoramento do prompt. Consulteenable_prompt_enhancement. - enable_prompt_enhancement (
bool, opcional, padrãoFalse) — Se deve executar o aprimoramento de prompt. - prompt_max_new_tokens (
int, opcional) — O número máximo de novos tokens a serem gerados ao realizar o aprimoramento do prompt. - prompt_enhancement_kwargs (
dict[str, Any], opcional) — Argumentos de palavra-chave para a chamada.generatedo aprimorador de prompt. - prompt_enhancement_seed (
int, opcional, padrão10) — Semente aleatória para qualquer operação aleatória durante o aprimoramento do prompt. - output_type (
str, opcional, padrão"pil") — Formato de saída. Escolha"pil","np","pt"ou"latent". A saída latente é o canvas sem recorte. - return_dict (
bool, opcional, padrãoTrue) — Se deve retornar um LTX2DFRPipelineOutput ou uma tupla simples(frames, audio, keyframes, keyframe_positions). - attention_kwargs (
dict, opcional) — Kwargs adicionais passados para o processador de atenção. - callback_on_step_end (
Callable, opcional) — Uma função chamada no final de cada etapa de desruidamento. - callback_on_step_end_tensor_inputs (
List, opcional, padrão["latents"]) — Entradas de tensor para a função de callback. - max_sequence_length (
int, opcional, padrão1024) — Comprimento máximo da sequência para o prompt de texto.
Retorna
LTX2DFRPipelineOutput ou tuple
Se return_dict for True, LTX2DFRPipelineOutput é retornado; caso contrário, uma tuple de (video, audio, keyframes, keyframe_positions) é retornada.
Função invocada ao chamar o pipeline para geração.
Uma passada de desruidamento em height × width. Componha os estágios no chamador: este pipeline em meia resolução, upsample espacial, este pipeline novamente com latents / keyframes_latents / reference_latents, e então LTX2DFRTemporalRefinePipeline para cada rodada temporal.
Exemplos:
>>> 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]) — Agenda de ruído para esta passagem, sem o terminal0.0. - freeze_audio (
bool, opcional, padrãoFalse) — Mantémaudio_latentslimpo (timestep/sigma 0, sem etapa Euler de áudio) enquanto ainda executa a atenção cruzada de áudio para vídeo. Ignorado quandoaudio_latentséNone. - video_tile_plan (
list, opcional) — Plano de tokens por tile obtido devideo_tile_plan[~diffusers.pipelines.ltx2.dfr_layout.video_tile_plan]. Quando fornecido, cada etapa executa o transformer uma vez por tile e mescla as previsões, de modo que o sampler ainda avança um único canvas completo e os tiles concordam em suas sobreposições a cada etapa. - generator (
torch.Generator, opcional) — Encaminhado paraLTXEulerAncestralRFScheduler.step(). Os tiles temporais passam uma semente por tile para que as extrações ancestrais não compartilhem um fluxo nem consumam o estado que o ruído inicial do próximo tile lê. O Euler destilado não o lê. - step_offset (
int) — Índice do primeiro passo desta passagem dentro do agendamento completo do pipeline, usado paracallback_on_step_ende a barra de progresso compartilhada.
Execute uma passagem de remoção de ruído DFR sobre sigmas e retorne (latents, audio_latents), ambos ainda empacotados.
O agendamento destilado é usado sem orientação livre de classificador, portanto, isso representa uma única chamada de transformador por etapa.
Cada passagem executa ambos os fluxos, porque o ramo de vídeo precisa da atenção intermodal, mesmo onde o áudio que
ele produz é descartado. freeze_audio=True mantém o fluxo de áudio em sigma 0 (sem etapa de Euler) para que o vídeo ainda
possa fazer atenção cruzada a ele — os tiles de refinamento temporal e o epílogo usam isso para seguir a fala da etapa 1 sem
que cada tile re-remova o ruído de uma realização de áudio diferente.
Após a mistura de condicionamento x0, a velocidade é (latents - denoised) / sigma, de modo que um passo de RF x0 = x - σ v recupera o denoised misturado. As etapas 1 / 2 / o epílogo mantêm o FlowMatchEulerDiscreteScheduler e executam esse passo de Euler como está. O refinamento temporal substitui por LTXEulerAncestralRFScheduler (eta=0.5); esse passo re-ruidifica cada token, portanto a mistura de condicionamento é aplicada novamente em seguida, ou as âncoras de emenda com força 0,95 se desgastam.
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 )
Pré-processa e codifica as condições de quadro com VAE, posicionadas por quadro de pixels.
Retorna (pixel_frame_index, latent, strength, num_pixel_frames) por condição, pronto para condition_latents de prepare_latents(). A codificação é mantida separada da colocação, pois as rodadas de refinamento temporal escalam a posição de uma condição por 2 ** round e a rebaseiam por tile, e não devem recodificar a mesma imagem estática uma vez por tile para isso.
O índice retornado está na grade de pixels própria de num_frames; transferi-lo para um canvas refinado é responsabilidade do chamador.
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 (
stroulist[str], opcional) — prompt a ser codificado - num_videos_per_prompt (
int, opcional, padrão 1) — Número de vídeos que devem ser gerados por prompt. - prompt_embeds (
torch.Tensor, opcional) — Incorporações de texto pré-geradas. Podem ser usadas para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompts. Se não forem fornecidas, as incorporações de texto serão geradas a partir do argumento de entradaprompt. - prompt_attention_mask (
torch.Tensor, opcional) — Máscara de atenção pré-gerada paraprompt_embeds. - device — (
torch.device, opcional): dispositivo torch - dtype — (
torch.dtype, opcional): dtype do torch
Codifica o prompt em estados ocultos do codificador de texto.
O DFR executa o agendamento de sigma destilado, que é treinado para ser usado sem classifier-free guidance, portanto não há um ramo negativo aqui.
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 )
Melhora o prompt fornecido gerando um novo prompt a partir dele e de um prompt de sistema, utilizando o aprimorador de prompts (um modelo de geração condicional Gemma). Quando image é fornecido, o aprimorador também é condicionado nesse quadro de referência (aprimoramento no estilo I2V / keyframe). Usa o componente dedicado prompt_enhancer se um estiver configurado (por exemplo, LTX-2.5, cujo codificador de texto não foi treinado para aprimoramento); caso contrário, recorre ao text_encoder principal (LTX-2.0/2.3, que também atua como seu próprio aprimorador).
Os modelos de mensagem, os kwargs de decodificação, a limpeza da resposta e a preparação do lado longo da imagem correspondem a 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) — Condições de imagem/vídeo por quadro, posicionadas pelo índice latente. - condition_latents (
list[tuple[int, torch.Tensor, float, int]], opcional) — Substituto já codificado paraconditions, na forma(pixel_frame_index, latent, strength, num_pixel_frames). Índice de pixel em vez de índice de latente, porque uma rodada de refinamento temporal escala a posição de uma condição por2 ** rounde o resultado não necessariamente cai em uma fronteira de latente — apenas um token de keyframe anexado pode ficar ali, e ele é posicionado por pixel.pixel_frame_index == 0ainda significa “substituir o primeiro quadro”. - keyframe_latents (
list[tuple[int, torch.Tensor, float]], opcional) — Orientação de keyframes já codificada como(pixel_frame_index, latent, strength), ondelatenttem a forma(batch_size, num_channels_latents, 1, latent_height, latent_width). Usada pelas rodadas de refinamento temporal para fixar os keyframes de emenda trazidos da rodada anterior. - slot_frame_indices (
list[int], opcional) — Posições dos quadros de pixels dos slots de quadros-chave gerados. - slot_initial_latents (
torch.Tensor, opcional) —(batch_size, num_channels_latents, len(slot_frame_indices), latent_height, latent_width)conteúdo gravado nos tokens de slot antes da adição de ruído. - reference_latents (
torch.Tensor, opcional) —(batch_size, num_channels_latents, F, H, W)Latente de referência do IC-LoRA. - reference_downscale_factor (
int, padrão1) — Proporção entre a resolução de destino e a resolução de referência. - latents (
torch.Tensor, opcional) —(batch_size, num_channels_latents, F, H, W)conteúdo inicial para os tokens de base. Os latents do pipeline público são brutos (não normalizados); passelatents_normalized=Falsenessa fronteira. Laços de tiles que já estão no espaço normalizado pelo VAE mantêm o valor padrão. - latents_normalized (
bool, padrãoTrue) — Indica selatents,slot_initial_latents,reference_latentsekeyframe_latentsjá estão normalizados pelo VAE. Os loops internos de tiles passamTrue; cada pipeline__call__passaFalse. - noise_scale (
float, padrão1.0) — Nível de ruído em que os tokens não condicionados são inicializados, ou seja, o primeiro sigma do agendamento.
Retorna
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 os tokens de slot de keyframe gerados na sequência empacotada, ou None quando nenhum
slot foi solicitado.
Prepare os latentes de vídeo empacotados com ruído para uma passagem de desruidamento DFR.
A sequência empacotada é organizada como [base | keyframes | slots | reference]:
- Os tokens de base cobrem a grade latente alvo, sendo semeados a partir de
latentsquando fornecidos. - As condições de quadro com
index == 0definem o alvo limpo nas posições do primeiro quadro; aquelas comindex > 0e todas as entradas dekeyframe_latentssão adicionadas como tokens de quadro-chave extras com uma máscara de condicionamento por token igual à sua intensidade. slot_frame_indicesadiciona um conjunto de tokens de keyframe gerados por posição, correspondente a um frame latente, com máscara de condicionamento0(totalmente desruidado) e uma extensão temporal de RoPE de exatamente um frame de pixels. Esses são os slots de keyframe que conferem os frames extras ao DFR;slot_initial_latentsdefine o conteúdo inicial deles.reference_latentsadiciona o latente de meia resolução da etapa 1 como uma referência IC-LoRA totalmente limpa, com as coordenadas espaciais escaladas porreference_downscale_factorpara que sejam mapeadas no espaço de coordenadas do alvo.
Os tokens de condicionamento anexados carregam seu conteúdo em clean_latents e um placeholder zero em latents, enquanto
os slots de keyframe carregam sua semente em latents e zeros em clean_latents — os latents retornados são a
mistura com ruído dos dois (veja a etapa de noising no final deste 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 (
LTX2VideoConditionouList[LTX2VideoCondition], opcional, padrãoNone) — Uma lista de instâncias de condição de imagem/vídeo. - height (
int, opcional, padrão512) — A altura desejada em pixels. - width (
int, opcional, padrão768) — A largura desejada em pixels. - num_frames (
int, opcional, padrão121) — O número desejado de quadros no vídeo gerado. - device (
torch.device, opcional, padrãoNone) — O dispositivo em que os tensores de imagem/vídeo pré-processados devem ser colocados.
Retorna
Tuple[List[torch.Tensor], List[float], List[int], List[int]]
Retorna uma 4-tupla de listas de comprimento len(conditions) da seguinte forma:
- A primeira lista é uma lista de tensores de vídeo pré-processados com forma [batch_size=1, num_channels, num_frames, height, width].
- A segunda lista é uma lista de intensidades de condicionamento.
- A terceira lista é uma lista de índices do espaço latente para cada condição.
- A quarta lista é uma lista de contagens de quadros (recortados) no espaço de pixels por condição. Isso é necessário para a semântica de coordenadas de quadros-chave (quadros-chave de um único quadro de pixel têm uma extensão temporal limitada).
Pré-processa as imagens/vídeos de condição para tensores do 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 brutos, com formato(batch_size, C, K, H, W), conforme retornados por uma passagem anterior. - seed (
int) — Semente base; o planoié decodificado sobseed + 4000 + i, de modo que os pixels de um plano não dependem de quantos planos foram decodificados antes dele.
Retorna
torch.Tensor
Latentes brutos (batch_size, C, K, 2H, 2W), prontos para serem passados diretamente de volta como
guidance_keyframe_latents.
Re-codifique os keyframes de carry com o dobro da resolução por meio de RGB.
Estas são as quadros que as rodadas de refinamento já definiram, portanto o epílogo os recebe em vez de ser solicitado a gerá-los. Decodificar para pixels, esticar x2 com Lanczos e codificar novamente preserva o quadro enquanto o posiciona na grade de saída, o que permite que o epíloco o fixe completamente limpo.
Cada plano é decodificado como um clipe de um único quadro. O VAE é causal, portanto, uma decodificação empilhada permitiria que planos vizinhos se misturassem entre si — eles são imagens estáticas independentes, não uma sequência.
trim_conditioning_sequence
< source >( start_frame: intsequence_num_frames: inttarget_num_frames: int ) → int
Reduza uma sequência de condicionamento para o número permitido de quadros.
LTX2DFRTemporalRefinePipeline
classe 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) — Agendador Euler ancestral na parametrização de fluxo retificado. Construa cometa=0.5para corresponder à receita temporal do DFR. - vae (AutoencoderKLLTX2Video) — Modelo de Autoencoder Variacional (VAE) para codificar e decodificar vídeos a partir de e para representações latentes.
- audio_vae (AutoencoderKLLTX2Audio) — VAE de áudio para codificar e decodificar espectrogramas de áudio.
- text_encoder (
Gemma3ForConditionalGenerationouGemma4UnifiedForConditionalGeneration) — Modelo de codificador de texto. - tokenizer (
GemmaTokenizerouGemmaTokenizerFast) — Tokenizer para o codificador de texto. - connectors (
LTX2TextConnectors) — Pilha de conectores de texto usada para adaptar os estados ocultos do codificador de texto para os ramos de vídeo e áudio. - transformer (LTX2VideoTransformer3DModel) — Arquitetura de Transformer condicional para desruidar os latentes de vídeo codificados.
- vocoder (
LTX2VocoderouLTX2VocoderWithBWE) — Vocoder para converter espectrogramas mel em formas de onda de áudio. - temporal_latent_upsampler (
LTX2LatentUpsamplerModel) — Upsampler latente temporal x2 aplicado no início da rodada.
Uma rodada de refinamento do DFR temporal: interpole o canvas x2 no tempo, faça o tileamento nas emendas dos keyframes, remova o ruído ancestral de cada tile, costure descartando a introdução do tile posterior e mescle a bolsa do keyframe de continuação.
O agendador é LTXEulerAncestralRFScheduler (com eta=0.5 por padrão). O estágio 1 / 2 / o epílogo espacial permanecem no FlowMatchEulerDiscreteScheduler via LTX2DFRPipeline. Chame este pipeline uma vez por rodada; o chamador faz o loop para 2x / 4x.
Os latents / keyframes_latents / audio_latents de entrada são brutos (não normalizados), correspondendo ao LTX2Pipeline. keyframe_positions deve ser as posições retornadas pela passagem anterior — elas não podem ser rederivadas do
num_frames original após a execução de uma rodada.
__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 (
strouList[str], opcional) — O prompt ou prompts para orientar a geração do vídeo. Se não definido, é necessário passarprompt_embeds. - latents (
torch.Tensor) — Latentes brutos de vídeo do input canvas,(batch_size, channels, frames, height, width). - keyframes_latents (
torch.Tensor) — Keyframes de transporte brutos(batch_size, channels, K, height, width)da passada anterior. - keyframe_positions (
list[int]) — Índices de quadros em pixels doskeyframes_latentsno canvas de entrada. - audio_latents (
torch.Tensor) — Áudio da etapa 1 congelado, descompactado e desnornormalizado. Cada tile recebe o slice que cobre sua janela de reprodução; o áudio retornado é esta forma de onda, não um re-desruido por tile. - conditions (
LTX2VideoConditionouList[LTX2VideoCondition], opcional) — Condições de nível de quadro indexadas emcondition_num_frames(a solicitação original). Cada rodada escala a posição de pixels de uma condição por2 ** round_index. - height (
int, opcional, padrão704) — Altura em pixels desta passagem (igual à do vídeo de entrada). - width (
int, opcional, padrão1216) — Largura em pixels desta passagem. - num_frames (
int, opcional, padrão121) — Número de quadros de pixels do input (sem corte). - frame_rate (
float, opcional, padrão24.0) — FPS de reprodução da entrada. O arredondamento o dobra. - source_seconds (
float, opcional) — Duração do áudio da etapa 1 congelada. O valor padrão énum_frames / frame_rate, o que está correto para a primeira rodada; nas rodadas subsequentes, é necessário passar a duração original da etapa 1 para que os tiles não se desloquem. - condition_num_frames (
int, optional) — Original generationnum_framesused to encodeconditions. Defaults tonum_frames. After padding or a prior round, pass the original request soindex=-1does not wrap to the padded tail. - round_index (
int, opcional, padrão1) — Número da rodada, começando em 1. Os tiles semeiam o ruído ancestral comoseed + 1000 * round_index + tile, e as condições são escaladas por2 ** round_index. - sigmas (
list[float], opcional) — Agenda destilada para os tiles desta rodada, sem o terminal0.0. - noise_scale (
float, opcional) — Nível de ruído em que os tokens não condicionados começam. O padrão ésigmas[0]. - generator (
torch.Generatoroulist[torch.Generator], opcional) — Gerador(es) aleatório(s) para reprodutibilidade. As extrações ancestrais usam uma semente separada por tile derivada doinitial_seed()deste gerador. - prompt_embeds (
torch.Tensor, opcional) — Incorporações de texto pré-geradas. - prompt_attention_mask (
torch.Tensor, opcional) — Máscara de atenção pré-gerada para embeddings de texto. - decode_timestep (
float, padrão0.0) — O timestep em que o vídeo gerado é decodificado. - decode_noise_scale (
float, padrãoNone) — Escala de ruído no momento da decodificação. - use_cross_timestep (
bool, opcional, padrãoTrue) — Se deve usar sigma de cross-modality para modulação de cross attention.Truepara LTX-2.3+. - output_type (
str, opcional, padrão"pil") — Formato de saída. Escolha"pil","np","pt"ou"latent". A saída latente é o canvas sem recorte. - return_dict (
bool, opcional, padrãoTrue) — Se deve retornar um LTX2DFRPipelineOutput ou uma tupla simples(frames, audio, keyframes, keyframe_positions). - attention_kwargs (
dict, opcional) — Kwargs adicionais passados para o processador de atenção. - callback_on_step_end (
Callable, opcional) — Uma função chamada no final de cada etapa de desruidamento, em todas as tiles. - callback_on_step_end_tensor_inputs (
List, opcional, padrão["latents"]) — Entradas de tensor para a função de callback. - max_sequence_length (
int, opcional, padrão1024) — Comprimento máximo da sequência para o prompt de texto.
Retorna
LTX2DFRPipelineOutput ou tuple
Se return_dict for True, LTX2DFRPipelineOutput é retornado; caso contrário, uma tuple de (video, audio, keyframes, keyframe_positions) é retornada.
Execute uma rodada de refinamento temporal.
Exemplos:
>>> 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]) — Agenda de ruído para esta passagem, sem o terminal0.0. - freeze_audio (
bool, opcional, padrãoFalse) — Mantémaudio_latentslimpo (timestep/sigma 0, sem etapa Euler de áudio) enquanto ainda executa a atenção cruzada de áudio para vídeo. Ignorado quandoaudio_latentséNone. - video_tile_plan (
list, opcional) — Plano de tokens por tile obtido devideo_tile_plan[~diffusers.pipelines.ltx2.dfr_layout.video_tile_plan]. Quando fornecido, cada etapa executa o transformer uma vez por tile e mescla as previsões, de modo que o sampler ainda avança um único canvas completo e os tiles concordam em suas sobreposições a cada etapa. - generator (
torch.Generator, opcional) — Encaminhado paraLTXEulerAncestralRFScheduler.step(). Os tiles temporais passam uma semente por tile para que as extrações ancestrais não compartilhem um fluxo nem consumam o estado que o ruído inicial do próximo tile lê. O Euler destilado não o lê. - step_offset (
int) — Índice do primeiro passo desta passagem dentro do agendamento completo do pipeline, usado paracallback_on_step_ende a barra de progresso compartilhada.
Execute uma passagem de remoção de ruído DFR sobre sigmas e retorne (latents, audio_latents), ambos ainda empacotados.
O agendamento destilado é usado sem orientação livre de classificador, portanto, isso representa uma única chamada de transformador por etapa.
Cada passagem executa ambos os fluxos, porque o ramo de vídeo precisa da atenção intermodal, mesmo onde o áudio que
ele produz é descartado. freeze_audio=True mantém o fluxo de áudio em sigma 0 (sem etapa de Euler) para que o vídeo ainda
possa fazer atenção cruzada a ele — os tiles de refinamento temporal e o epílogo usam isso para seguir a fala da etapa 1 sem
que cada tile re-remova o ruído de uma realização de áudio diferente.
Após a mistura de condicionamento x0, a velocidade é (latents - denoised) / sigma, de modo que um passo de RF x0 = x - σ v recupera o denoised misturado. As etapas 1 / 2 / o epílogo mantêm o FlowMatchEulerDiscreteScheduler e executam esse passo de Euler como está. O refinamento temporal substitui por LTXEulerAncestralRFScheduler (eta=0.5); esse passo re-ruidifica cada token, portanto a mistura de condicionamento é aplicada novamente em seguida, ou as âncoras de emenda com força 0,95 se desgastam.
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 )
Pré-processa e codifica as condições de quadro com VAE, posicionadas por quadro de pixels.
Retorna (pixel_frame_index, latent, strength, num_pixel_frames) por condição, pronto para condition_latents de prepare_latents(). A codificação é mantida separada da colocação, pois as rodadas de refinamento temporal escalam a posição de uma condição por 2 ** round e a rebaseiam por tile, e não devem recodificar a mesma imagem estática uma vez por tile para isso.
O índice retornado está na grade de pixels própria de num_frames; transferi-lo para um canvas refinado é responsabilidade do chamador.
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 (
stroulist[str], opcional) — prompt a ser codificado - num_videos_per_prompt (
int, opcional, padrão 1) — Número de vídeos que devem ser gerados por prompt. - prompt_embeds (
torch.Tensor, opcional) — Incorporações de texto pré-geradas. Podem ser usadas para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompts. Se não forem fornecidas, as incorporações de texto serão geradas a partir do argumento de entradaprompt. - prompt_attention_mask (
torch.Tensor, opcional) — Máscara de atenção pré-gerada paraprompt_embeds. - device — (
torch.device, opcional): dispositivo torch - dtype — (
torch.dtype, opcional): dtype do torch
Codifica o prompt em estados ocultos do codificador de texto.
O DFR executa o agendamento de sigma destilado, que é treinado para ser usado sem classifier-free guidance, portanto não há um ramo negativo aqui.
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) — Condições de imagem/vídeo por quadro, posicionadas pelo índice latente. - condition_latents (
list[tuple[int, torch.Tensor, float, int]], opcional) — Substituto já codificado paraconditions, na forma(pixel_frame_index, latent, strength, num_pixel_frames). Índice de pixel em vez de índice de latente, porque uma rodada de refinamento temporal escala a posição de uma condição por2 ** rounde o resultado não necessariamente cai em uma fronteira de latente — apenas um token de keyframe anexado pode ficar ali, e ele é posicionado por pixel.pixel_frame_index == 0ainda significa “substituir o primeiro quadro”. - keyframe_latents (
list[tuple[int, torch.Tensor, float]], opcional) — Orientação de keyframes já codificada como(pixel_frame_index, latent, strength), ondelatenttem a forma(batch_size, num_channels_latents, 1, latent_height, latent_width). Usada pelas rodadas de refinamento temporal para fixar os keyframes de emenda trazidos da rodada anterior. - slot_frame_indices (
list[int], opcional) — Posições dos quadros de pixels dos slots de quadros-chave gerados. - slot_initial_latents (
torch.Tensor, opcional) —(batch_size, num_channels_latents, len(slot_frame_indices), latent_height, latent_width)conteúdo gravado nos tokens de slot antes da adição de ruído. - reference_latents (
torch.Tensor, opcional) —(batch_size, num_channels_latents, F, H, W)Latente de referência do IC-LoRA. - reference_downscale_factor (
int, padrão1) — Proporção entre a resolução de destino e a resolução de referência. - latents (
torch.Tensor, opcional) —(batch_size, num_channels_latents, F, H, W)conteúdo inicial para os tokens de base. Os latents do pipeline público são brutos (não normalizados); passelatents_normalized=Falsenessa fronteira. Laços de tiles que já estão no espaço normalizado pelo VAE mantêm o valor padrão. - latents_normalized (
bool, padrãoTrue) — Indica selatents,slot_initial_latents,reference_latentsekeyframe_latentsjá estão normalizados pelo VAE. Os loops internos de tiles passamTrue; cada pipeline__call__passaFalse. - noise_scale (
float, padrão1.0) — Nível de ruído em que os tokens não condicionados são inicializados, ou seja, o primeiro sigma do agendamento.
Retorna
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 os tokens de slot de keyframe gerados na sequência empacotada, ou None quando nenhum
slot foi solicitado.
Prepare os latentes de vídeo empacotados com ruído para uma passagem de desruidamento DFR.
A sequência empacotada é organizada como [base | keyframes | slots | reference]:
- Os tokens de base cobrem a grade latente alvo, sendo semeados a partir de
latentsquando fornecidos. - As condições de quadro com
index == 0definem o alvo limpo nas posições do primeiro quadro; aquelas comindex > 0e todas as entradas dekeyframe_latentssão adicionadas como tokens de quadro-chave extras com uma máscara de condicionamento por token igual à sua intensidade. slot_frame_indicesadiciona um conjunto de tokens de keyframe gerados por posição, correspondente a um frame latente, com máscara de condicionamento0(totalmente desruidado) e uma extensão temporal de RoPE de exatamente um frame de pixels. Esses são os slots de keyframe que conferem os frames extras ao DFR;slot_initial_latentsdefine o conteúdo inicial deles.reference_latentsadiciona o latente de meia resolução da etapa 1 como uma referência IC-LoRA totalmente limpa, com as coordenadas espaciais escaladas porreference_downscale_factorpara que sejam mapeadas no espaço de coordenadas do alvo.
Os tokens de condicionamento anexados carregam seu conteúdo em clean_latents e um placeholder zero em latents, enquanto
os slots de keyframe carregam sua semente em latents e zeros em clean_latents — os latents retornados são a
mistura com ruído dos dois (veja a etapa de noising no final deste 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 (
LTX2VideoConditionouList[LTX2VideoCondition], opcional, padrãoNone) — Uma lista de instâncias de condição de imagem/vídeo. - height (
int, opcional, padrão512) — A altura desejada em pixels. - width (
int, opcional, padrão768) — A largura desejada em pixels. - num_frames (
int, opcional, padrão121) — O número desejado de quadros no vídeo gerado. - device (
torch.device, opcional, padrãoNone) — O dispositivo em que os tensores de imagem/vídeo pré-processados devem ser colocados.
Retorna
Tuple[List[torch.Tensor], List[float], List[int], List[int]]
Retorna uma 4-tupla de listas de comprimento len(conditions) da seguinte forma:
- A primeira lista é uma lista de tensores de vídeo pré-processados com forma [batch_size=1, num_channels, num_frames, height, width].
- A segunda lista é uma lista de intensidades de condicionamento.
- A terceira lista é uma lista de índices do espaço latente para cada condição.
- A quarta lista é uma lista de contagens de quadros (recortados) no espaço de pixels por condição. Isso é necessário para a semântica de coordenadas de quadros-chave (quadros-chave de um único quadro de pixel têm uma extensão temporal limitada).
Pré-processa as imagens/vídeos de condição para tensores do torch.
trim_conditioning_sequence
< source >( start_frame: intsequence_num_frames: inttarget_num_frames: int ) → int
Reduza uma sequência de condicionamento para o número permitido de quadros.
Execute upsampler nos latentes normalizados, fazendo um round-trip pelo espaço latente bruto da VAE, como esperado.
LTX2DFRPipelineOutput
classe diffusers.LTX2DFRPipelineOutput
< source >( frames: Tensoraudio: Tensorkeyframes: typing.Optional[torch.Tensor] = Nonekeyframe_positions: list[int] | None = None )
Parâmetros
- frames (
torch.Tensor,np.ndarrayou list[list[PIL.Image.Image]]) — Vídeo denoisado. A saída latente é o canvas sem recorte, com forma(batch_size, num_channels, latent_frames, latent_height, latent_width). - audio (
torch.Tensor,np.ndarray) — Latentes de áudio ou forma de onda correspondentes. - keyframes (
torch.Tensor, optional) — Generated or carried keyframe latents of shape(batch_size, num_channels, num_keyframes, latent_height, latent_width).Nonewhenoutput_type != "latent", or when the pass did not produce slots (e.g. a tiled epilogue). - keyframe_positions (
list[int], opcional) — Índice do quadro em pixels de cada keyframe no canvas desta passada;Nonesempre quekeyframesforNone. Após uma rodada temporal, esses valores não podem ser rederivados donum_framesoriginal e devem ser passados para o próximo estágio.
Classe de saída para pipelines DFR.
LTX2LatentUpsamplePipeline
classe 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) — O vídeo a ser ampliado (como a saída da primeira etapa do LTX 2.0). Se não for fornecido,latentsdeve ser fornecido. - height (
int, opcional, padrão512) — A altura em pixels do vídeo de entrada (não do vídeo gerado, que terá uma resolução maior). - width (
int, opcional, padrão768) — A largura em pixels do vídeo de entrada (não do vídeo gerado, que terá uma resolução maior). - num_frames (
int, opcional, padrão121) — O número de quadros no vídeo de entrada. - spatial_patch_size (
int, opcional, padrão1) — O tamanho do patch espacial dos latentes do vídeo. Usado quandolatentsé fornecido, caso seja necessário descompactar. - temporal_patch_size (
int, opcional, padrão1) — O tamanho do patch temporal dos latentes do vídeo. Usado quandolatentsé fornecido, caso seja necessário descompactar. - latents (
torch.Tensor, opcional) — Latentes de vídeo pré-gerados. Isso pode ser fornecido no lugar do argumentovideo. Pode ser uma sequência de patches com forma(batch_size, seq_len, hidden_dim)ou um latente de vídeo com forma(batch_size, latent_channels, latent_frames, latent_height, latent_width). - latents_normalized (
bool, opcional, padrãoFalse) — Selatentsforem fornecidos, se oslatentssão normalizados usando a média e o desvio padrão latente do VAE. SeTrue, oslatentsserão desnormalizados antes de serem fornecidos ao amplificador latente. - decode_timestep (
float, padrão0.0) — O timestep em que o vídeo gerado é decodificado. - decode_noise_scale (
float, padrãoNone) — O fator de interpolação entre o ruído aleatório e os latentes desruídos no passo de decodificação. - adain_factor (
float, opcional, padrão0.0) — Fator de mistura da Normalização Adaptativa de Instância (AdaIN) entre os latentes interpolados e os originais. Deve estar em [-10.0, 10.0]; fornecer 0.0 (o padrão) significa que a AdaIN não é executada. - tone_map_compression_ratio (
float, opcional, padrão0.0) — A intensidade de compressão para o tone mapping, que reduzirá a faixa dinâmica dos valores latentes. Isso é útil para regularizar latentes de alta variância ou para condicionar as saídas durante a geração. Deve estar em [0, 1], onde 0.0 (o padrão) significa que o tone mapping não é aplicado e 1.0 corresponde ao efeito de compressão total. - generator (
torch.Generatoroulist[torch.Generator], opcional) — Um ou uma lista de geradores do torch para tornar a geração determinística. - output_type (
str, opcional, padrão"pil") — O formato de saída da imagem gerada. Escolha entre PIL:PIL.Image.Imageounp.array. - return_dict (
bool, opcional, padrãoTrue) — Se deve ou não retornar um~pipelines.ltx.LTXPipelineOutputem vez de uma tupla simples.
Retorna
~pipelines.ltx.LTXPipelineOutput ou tuple
Se return_dict for True, ~pipelines.ltx.LTXPipelineOutput é retornado; caso contrário, uma tuple é retornada, onde o primeiro elemento é o vídeo ampliado.
Função invocada ao chamar o pipeline para geração.
Exemplos:
>>> 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) — Os latentes de referência que fornecem as estatísticas de estilo. - factor (
float) — Fator de mistura entre o latente original e o latente transformado. Intervalo: -10.0 a 10.0, Padrão: 1.0
Retorna
torch.Tensor
O tensor latente transformado
Aplica a Normalização Adaptativa de Instância (AdaIN) a um tensor latente com base nas estatísticas de um tensor latente de referência.
tone_map_latents
< source >( latents: Tensorcompression: float )
Aplica uma função de mapeamento de tom não linear aos valores latentes para reduzir sua faixa dinâmica de forma perceptualmente suave, usando uma compressão baseada em sigmoide.
Isso é útil para regularizar latentes de alta variância ou para condicionar as saídas durante a geração, especialmente ao controlar o comportamento dinâmico com um fator de compression.
LTX2VideoDiffusionDecodePipeline
classe diffusers.LTX2VideoDiffusionDecodePipeline
< source >( diffusion_decoder: LTX2VideoDiffusionDecoderModelschedulervae: AutoencoderKLLTX2Video = None )
Parâmetros
- diffusion_decoder (LTX2VideoDiffusionDecoderModel) — O decodificador de vídeo de difusão.
- scheduler (FlowMatchEulerDiscreteScheduler) — Agendador que controla as etapas de remoção de ruído do decodificador.
- vae (AutoencoderKLLTX2Video, opcional) — Consultado apenas para as estatísticas latentes usadas na desnornalização. Quando omitido, o pipeline recorre aos padrões do LTX-2, de modo que um fluxo de trabalho somente de decodificação não precisa carregar um segundo autoencoder.
Decodifique os latentes de vídeo do LTX-2 com o decodificador de difusão introduzido no LTX-2.5.
Diferente de um decodificador convolucional, este é em si um pequeno modelo de difusão: ele remove o ruído dos pixels condicionado a um volume de contexto construído a partir dos latentes, portanto, requer um agendador e um gerador. Combine-o com qualquer execução de pipeline LTX-2 com output_type="latent", passando denormalize=False, pois esse caminho já aplicou as estatísticas dos 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) — Latents de forma(B, C, F, H, W). Observe que uma execução do pipeline LTX-2 comoutput_type="latent"retorna latents que já estão denormalizados, portanto, passedenormalize=Falsepara esses. - generator (
torch.Generator, opcional) — O decodificador amostra o ruído que ele desrujiza, portanto, passe um gerador para tornar a decodificação reproduzível. - output_type (
str, opcional, padrão"pil") — O formato de saída do vídeo decodificado. Escolha entre"pil","np","pt"e"latent". - return_dict (
bool, opcional, padrãoTrue) — Se deve retornar umLTX2VideoDecodeOutputem vez de uma tupla simples. - denormalize (
bool, opcional, padrãoTrue) — Se as estatísticas latentes devem ser aplicadas antes da decodificação. Defina comoFalsese os latentes já estiverem denormalizados.
Retorna
LTX2VideoDecodeOutput ou tuple
LTX2DurationHead
classe 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, padrão4096) — Largura da saída do conector de vídeo. - audio_cross_attention_dim (
int, padrão2048) — Largura da saída do conector de áudio. - pooler_hidden_dim (
int, padrão256) — Dimensão oculta compartilhada na qual ambas as modalidades são projetadas. - num_queries (
int, padrão1) — Número de consultas de pooling aprendíveis. - num_pooler_heads (
int, padrão4) — Cabeças de atenção usadas pelo pooler. - mlp_hidden_dim (
int, padrão256) — Largura oculta do MLP de saída. Nomeado com o sufixo_dimpara evitar colisão com o submódulomlp_hidden, que oConfigMixin.__getattr__ofuscaria caso contrário com este valor de configuração.
Prevê a duração natural do tiro implícita por uma legenda, a partir das saídas do conector de texto do LTX-2.
A cabeça é agnóstica em relação à modalidade: passe a saída do conector de vídeo, a de áudio, ou ambas. As projeções de entrada específicas de cada modalidade mapeiam cada fluxo para uma dimensão compartilhada do pooler, os embeddings de modalidade aprendíveis rotulam os fluxos para que o pooler possa diferenciá-los, e um pequeno MLP converte o vetor agregado em uma duração logarítmica. O alvo de regressão é treinado em segundos logarítmicos, portanto forward aplica a exponenciação e os chamadores sempre recebem o valor em segundos.
Disponível a partir dos checkpoints do 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) — Saída do conector de vídeo. - audio_tokens (
torch.Tensorde forma(batch_size, seq_len, audio_cross_attention_dim), opcional) — Saída do conector de áudio.
Retorna
torch.Tensor de forma (batch_size,)
a duração prevista em 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) — Saída do conector de vídeo para um único prompt. - audio_tokens (
torch.Tensor, opcional) — Saída do conector de áudio para um único prompt. - frame_rate (
float) — Quadros por segundo usados para converter a duração prevista em um número de quadros. - temporal_compression_ratio (
int) — A razão de compressão temporal do VAE, que define a grade de quadros. - min_seconds (
float, padrão1.0) — Limite inferior da previsão. - max_seconds (
float, padrão20.0) — Limite superior da previsão.
Retorna
int
uma contagem de quadros que se encaixa na grade temporal do VAE.
Prevê uma contagem de quadros a partir de tokens de conector, limitada a [min_seconds, max_seconds] e ajustada à grade temporal causal da VAE (k * temporal_compression_ratio + 1).
O clamp é aplicado antes do snapping: uma contagem de frames com clamp não é necessariamente alinhada à grade, portanto, aplicar o snapping primeiro daria um resultado diferente. Como o snapping arredonda para baixo, ele pode ficar abaixo do mínimo; quando isso acontece, o resultado é arredondado para cima até o próximo ponto da grade, de modo que a contagem de frames permaneça dentro dos limites.
Limites estreitos podem converter em uma janela de quadro que não contém nenhum ponto da grade — a 24 fps, [1.0s, 1.02s] é arredondado para [24, 24], e 24 não é 8k + 1. O ponto da grade mais próximo é usado e um aviso é registrado, pois ultrapassar em menos de um passo da grade é melhor do que recusar a geração. A contagem retornada é, portanto, sempre na grade, mas pode ficar ligeiramente fora dos limites solicitados neste caso.
LTX2PipelineOutput
classe diffusers.pipelines.ltx2.LTX2PipelineOutput
< source >( frames: Tensoraudio: Tensor )
Parâmetros
- frames (
torch.Tensor,np.ndarrayou list[list[PIL.Image.Image]]) — Lista de saídas de vídeo - Pode ser uma lista aninhada de comprimentobatch_size,com cada sublista contendo sequências de imagens PIL desruidas de comprimentonum_frames.Também pode ser um array NumPy ou tensor Torch de forma(batch_size, num_frames, channels, height, width). - audio (
torch.Tensor,np.ndarray) — TODO
Classe de saída para pipelines LTX.
LTX2ModularPipeline
classe 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 )
Uma ModularPipeline para LTX-2 (geração conjunta de vídeo + áudio).
LTX2AutoBlocks
Auto blocks para LTX-2 com suporte a text-to-video, image-to-video, condition-to-video e in-context (IC-LoRA) geração (vídeo + áudio conjuntos).
Fluxos de trabalho suportados:
text2video: requerpromptimage2video: requerimage,promptcondition: requerconditions,promptin_context: requerreference_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):
O prompt ou prompts para orientar a geração de imagem.
conditions (list, opcional): LTX2VideoCondition (ou lista deles) que posiciona condições de imagem/vídeo nos índices de frames latentes do
vídeo gerado.
enable_prompt_enhancement (bool, opcional, padrão False):
Se deve executar o aprimorador de prompt. Opcional, alinhado aos pipelines de referência da Lightricks.
system_prompt (str, opcional):
System prompt para o aprimoramento. Padrão é LTX2_5_I2V_DEFAULT_SYSTEM_PROMPT quando um frame de condição PIL.Image.Image está disponível, caso contrário LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT.
prompt_max_new_tokens (int, opcional):
Número máximo de novos tokens a serem gerados durante o aprimoramento do prompt. Padrão é 600, o orçamento do
aprimorador Gemma-4 do LTX-2.5.
prompt_enhancement_kwargs (dict, opcional):
Argumentos por palavra-chave para a chamada .generate do aprimorador. Padrão é decodificação gulosa.
prompt_enhancement_seed (int, opcional, padrão 10):
Semente aleatória para o aprimoramento do prompt (inerte sob a decodificação gulosa do LTX-2.5).
generator (Generator, opcional):
Gerador do Torch para geração determinística.
image (Image | list, opcional):
Imagem(ns) de referência para o desruido. Pode ser uma única imagem ou uma lista de imagens.
negative_prompt (str, opcional):
O prompt ou prompts que não devem orientar a geração de imagem.
max_sequence_length (int, opcional, padrão 1024):
Comprimento máximo da sequência para a codificação do prompt.
min_seconds (float, opcional, padrão 1.0):
Limite inferior para a duração prevista automaticamente.
max_seconds (float, opcional, padrão 20.0):
Limite superior para a duração prevista automaticamente. Deve ser estritamente maior que min_seconds.
frame_rate (float, opcional, padrão 24.0):
Frames por segundo do vídeo gerado.
height (int, opcional, padrão 512):
A altura em pixels da imagem gerada.
width (int, opcional, padrão 704):
A largura em pixels da imagem gerada.
image_crf (int, opcional):
CRF H.264 usado para recomprimir a image de condicionamento antes da codificação VAE, correspondendo à compressão
com a qual o modelo foi treinado. None (padrão) é resolvido a partir da geração do text-encoder (33 até
LTX-2.3, 18 para LTX-2.5). Passe 0 para pular a recompressão. Requer um PIL.Image.Image quando
a recompressão é executada.
num_frames (int, opcional):
O número de frames no vídeo gerado. Omita para prever automaticamente via duration_head (veja LTX2AutoDurationStep).
reference_conditions (list, opcional): LTX2ReferenceCondition (ou lista deles) cujos vídeos são codificados em tokens latentes extras para os quais o adaptador IC-LoRA
presta atenção.
reference_downscale_factor (int, opcional, padrão 1):
Razão entre as resoluções de destino e de referência; 2 significa que a referência é pré-processada na metade da
resolução de destino. As coordenadas espaciais são escaladas por este fator para que os tokens de referência caiam no
espaço de coordenadas de destino. Deve corresponder ao fator com o qual o IC-LoRA foi treinado.
conditioning_attention_strength (float, opcional, padrão 1.0):
Escalar em [0, 1] que controla a intensidade com que os tokens ruidosos e os tokens de referência prestam atenção uns aos outros. 1.0
(padrão) deixa a atenção sem máscara.
conditioning_attention_mask (Tensor, opcional):
Máscara opcional em espaço de pixels de forma (1, 1, F, H, W) com valores em [0, 1] que fornece intensidade de
atenção variável espacialmente. Subamostrada para a grade latente da referência e multiplicada por conditioning_attention_strength.
motion_speed (float, opcional, padrão 1.0):
Velocidade do movimento em relação ao tempo real. Os embeddings posicionais são condicionados em frame_rate / motion_speed, portanto valores abaixo de 1 desaceleram o movimento, por exemplo, 0.2 para o slow motion 5x do LoRA Slow-Motion-Control. frame_rate permanece como a taxa de reprodução.
num_videos_per_prompt (int, opcional, padrão 1):
O número de imagens a gerar por prompt.
condition_latents (list, opcional):
Latentes VAE normalizados por condição de forma [1, C, F, H, W].
condition_strengths (list, opcional):
Intensidades de condicionamento por condição.
condition_indices (list, opcional):
Índice de frame latente por condição no qual a condição é aplicada.
condition_pixel_frames (list, opcional):
Contagem de frames de pixels recortados por condição, usada para limitar as coordenadas de keyframes de frame único.
reference_latents (Tensor, opcional):
Tokens de referência empacotados de forma [1, total_reference_tokens, C], ou None quando nenhuma condição de referência
foi fornecida (LTX2AutoReferenceEncoderStep é ignorado).
reference_coords (Tensor, opcional):
Coordenadas RoPE para os tokens de referência.
reference_token_counts (list, opcional):
Contagens de tokens por referência, na ordem de reference_conditions.
latents (Tensor):
Latentes ruidosos pré-gerados para a geração de imagem.
noise_scale (float, opcional):
Nível inicial de ruído para os tokens não condicionados. None (padrão) é resolvido para sigmas[0] quando sigmas personalizados são fornecidos, caso contrário 1.0.
sigmas (list, opcional):
Sigmas personalizados para o processo de desruido.
reference_cross_mask (Tensor, opcional):
Intensidades de atenção ruidoso<->referência por token de referência de forma [1, num_ref_tokens].
num_inference_steps (int):
O número de passos de desruido.
timesteps (Tensor):
Passos de tempo para o processo de desruido.
audio_latents (Tensor):
Latentes de áudio pré-codificados opcionais; ruído aleatório é usado quando não fornecidos.
*denoiser_input_fields (None,opcional):
entradas condicionais do modelo para o desruidador: por exemplo, prompt_embeds, negative_prompt_embeds, etc.
use_cross_timestep (bool,opcional, padrão True):
Se deve condicionar o transformer em um cross timestep separado por token (LTX-2.3+).
attention_kwargs (dict,opcional):
Kwargs adicionais para os processadores de atenção.
image_latents (Tensor,opcional):
Latentes de imagem de referência codificados por VAE usados para condicionamento de imagem-para-vídeo.
output_type (str,opcional, padrão pil):
Formato de saída: ‘pil’, ‘np’, ‘pt’.
decode_timestep (None,opcional, padrão 0.0):
O passo de tempo no qual o VAE decodifica os latentes finais.
decode_noise_scale (None,opcional*):
Fator de interpolação de ruído aplicado aos latentes no passo de tempo de decodificação.
Saídas:
vídeos (list):
Os vídeos gerados.
áudio (Tensor):
A forma de onda de áudio gerada.
LTX25ModularPipeline
classe 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 )
Uma ModularPipeline para LTX-2.5 (geração conjunta de vídeo + áudio).
Idêntico ao LTX2ModularPipeline, exceto que seus blocos padrão decodificam com o decodificador de vídeo de difusão, que é o padrão nativo a partir do LTX-2.5. Um checkpoint é roteado para aqui por meio de modular_model_index.json.
LTX25AutoBlocks
Auto blocks para LTX-2.5 com suporte a text-to-video, image-to-video, condition-to-video e geração in-context (IC-LoRA) (vídeo + áudio conjuntos). Idêntico a LTX2AutoBlocks, exceto que o decodificador de vídeo é LTX2DiffusionVaeDecoderStep, já que o decodificador de difusão é o padrão nativo a partir do LTX-2.5. Para decodificar com o VAE convolucional em vez disso, substitua o bloco de decodificação: blocks.sub_blocks["decode"] = LTX2AutoDecoderStep().
Fluxos de trabalho suportados:
text2video: requerpromptimage2video: requerimage,promptcondition: requerconditions,promptin_context: requerreference_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):
O prompt ou prompts para orientar a geração de imagem.
conditions (list, opcional): LTX2VideoCondition (ou lista deles) que posiciona condições de imagem/vídeo nos índices de frames latentes do
vídeo gerado.
enable_prompt_enhancement (bool, opcional, padrão False):
Se deve executar o aprimorador de prompt. Opcional, alinhado aos pipelines de referência da Lightricks.
system_prompt (str, opcional):
System prompt para o aprimoramento. Padrão é LTX2_5_I2V_DEFAULT_SYSTEM_PROMPT quando um frame de condição PIL.Image.Image está disponível, caso contrário LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT.
prompt_max_new_tokens (int, opcional):
Número máximo de novos tokens a serem gerados durante o aprimoramento do prompt. Padrão é 600, o orçamento do
aprimorador Gemma-4 do LTX-2.5.
prompt_enhancement_kwargs (dict, opcional):
Argumentos por palavra-chave para a chamada .generate do aprimorador. Padrão é decodificação gulosa.
prompt_enhancement_seed (int, opcional, padrão 10):
Semente aleatória para o aprimoramento do prompt (inerte sob a decodificação gulosa do LTX-2.5).
generator (Generator, opcional):
Gerador do Torch para geração determinística.
image (Image | list, opcional):
Imagem(ns) de referência para o desruido. Pode ser uma única imagem ou uma lista de imagens.
negative_prompt (str, opcional):
O prompt ou prompts que não devem orientar a geração de imagem.
max_sequence_length (int, opcional, padrão 1024):
Comprimento máximo da sequência para a codificação do prompt.
min_seconds (float, opcional, padrão 1.0):
Limite inferior para a duração prevista automaticamente.
max_seconds (float, opcional, padrão 20.0):
Limite superior para a duração prevista automaticamente. Deve ser estritamente maior que min_seconds.
frame_rate (float, opcional, padrão 24.0):
Frames por segundo do vídeo gerado.
height (int, opcional, padrão 512):
A altura em pixels da imagem gerada.
width (int, opcional, padrão 704):
A largura em pixels da imagem gerada.
image_crf (int, opcional):
CRF H.264 usado para recomprimir a imagem de condição image antes da codificação VAE, correspondendo à compressão com a qual
o modelo foi treinado. None (padrão) é resolvido a partir da geração do text-encoder (33 até
LTX-2.3, 18 para LTX-2.5). Passe 0 para pular a recompressão. Requer um PIL.Image.Image quando
a recompressão é executada.
num_frames (int, opcional):
O número de frames no vídeo gerado. Omita para prever automaticamente via duration_head (veja LTX2AutoDurationStep).
reference_conditions (list, opcional): LTX2ReferenceCondition (ou lista deles) cujos vídeos são codificados em tokens latentes extras para os quais o adaptador IC-LoRA
presta atenção.
reference_downscale_factor (int, opcional, padrão 1):
Razão entre as resoluções de destino e de referência; 2 significa que a referência é pré-processada na metade da
resolução de destino. As coordenadas espaciais são escaladas por este fator para que os tokens de referência caiam no
espaço de coordenadas de destino. Deve corresponder ao fator com o qual o IC-LoRA foi treinado.
conditioning_attention_strength (float, opcional, padrão 1.0):
Escalar em [0, 1] que controla a intensidade com que os tokens ruidosos e os tokens de referência prestam atenção uns aos outros. 1.0
(padrão) deixa a atenção sem máscara.
conditioning_attention_mask (Tensor, opcional):
Máscara opcional em espaço de pixels de forma (1, 1, F, H, W) com valores em [0, 1] que fornece intensidade de
atenção variável espacialmente. Reduzida à grade latente da referência e multiplicada por conditioning_attention_strength.
motion_speed (float, opcional, padrão 1.0):
Velocidade do movimento em relação ao tempo real. Os embeddings posicionais são condicionados em frame_rate / motion_speed, portanto valores abaixo de 1 desaceleram o movimento, por exemplo, 0.2 para o slow motion 5x do LoRA Slow-Motion-Control. frame_rate permanece como a taxa de reprodução.
num_videos_per_prompt (int, opcional, padrão 1):
O número de imagens a serem geradas por prompt.
condition_latents (list, opcional):
Latentes VAE normalizados por condição de forma [1, C, F, H, W].
condition_strengths (list, opcional):
Intensidades de condicionamento por condição.
condition_indices (list, opcional):
Índice do frame latente por condição no qual a condição é aplicada.
condition_pixel_frames (list, opcional):
Contagem de frames de pixels recortados por condição, usada para limitar as coordenadas de keyframes de frame único.
reference_latents (Tensor, opcional):
Tokens de referência empacotados de forma [1, total_reference_tokens, C], ou None quando nenhuma condição de referência
foi fornecida (LTX2AutoReferenceEncoderStep é ignorado).
reference_coords (Tensor, opcional):
Coordenadas RoPE para os tokens de referência.
reference_token_counts (list, opcional):
Contagens de tokens por referência, na ordem de reference_conditions.
latents (Tensor):
Latentes ruidosos pré-gerados para a geração de imagem.
noise_scale (float, opcional):
Nível inicial de ruído para os tokens não condicionados. None (padrão) é resolvido para sigmas[0] quando sigmas personalizados são fornecidos, caso contrário 1.0.
sigmas (list, opcional):
Sigmas personalizados para o processo de desruido.
reference_cross_mask (Tensor, opcional):
Intensidades de atenção ruidoso<->referência por token de referência de forma [1, num_ref_tokens].
num_inference_steps (int):
O número de etapas de desruido.
timesteps (Tensor):
Timesteps para o processo de desruido.
audio_latents (Tensor):
Latentes de áudio pré-codificados opcionais; ruído aleatório é usado quando não fornecidos.
*denoiser_input_fields (None,opcional):
entradas condicionais do modelo para o desruidador: por exemplo, prompt_embeds, negative_prompt_embeds, etc.
use_cross_timestep (bool,opcional, padrão True):
Se deve condicionar o transformer em um cross timestep separado por token (LTX-2.3+).
attention_kwargs (dict,opcional):
Kwargs adicionais para os processadores de atenção.
image_latents (Tensor,opcional):
Latentes de imagem de referência codificados por VAE usados para o condicionamento de imagem-para-vídeo.
output_type (str,opcional*, padrão pil):
Formato de saída: ‘pil’, ‘np’, ‘pt’.
Saídas:
vídeos (list):
Os vídeos gerados.
áudio (Tensor):
A forma de onda de áudio gerada.