Diffusers documentation
LTX-2
LTX-2
LTX-2 — это базовая модель на основе DiT, предназначенная для генерации синхронизированного видео и аудио в рамках одной модели. Она объединяет ключевые компоненты современных систем генерации видео, предоставляя открытые веса и акцентируя внимание на практическом локальном выполнении.
Все исходные контрольные точки LTX-Video можно найти в организации Lightricks.
Исходный код LTX-2 можно найти здесь.
Генерация в два этапа
Значения по умолчанию для общего LTX2Pipeline / LTX2ImageToVideoPipeline __call__ соответствуют эталонным для LTX-2.5 (num_inference_steps=30; num_frames является необязательным, если присутствует duration_head, в противном случае используется значение по умолчанию 121). В примерах ниже эти значения по умолчанию также используются для LTX-2.0/2.3.
Рекомендуемый конвейер для достижения производственного качества генерации; он состоит из двух этапов:
- Этап 1: сгенерировать видео в целевом разрешении с помощью диффузионного сэмплирования с использованием classifier-free guidance (CFG). На этом этапе формируется последовательность кадров с низким уровнем шума, согласованная с текстовым/изображением-условием.
- Этап 2: Увеличение разрешения вывода этапа 1 в 2 раза и уточнение деталей с использованием дистиллированной модели LoRA для повышения точности и визуального качества. На этапе 2 может применяться более слабый CFG, чтобы сохранить структуру, полученную на этапе 1, одновременно улучшая текстуру и резкость.
Пример использования двухэтапного конвейера text-to-video
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",
)Генерация дистиллированной контрольной точки
Самый быстрый двухэтапный конвейер генерации с использованием дистиллированной контрольной точки.
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",
)Условная генерация конвейера
С помощью LTX2ConditionPipeline можно задать условия по изображению и/или видео для произвольных латентных индексов. Например, можно указать условия для первого и последнего кадров, чтобы выполнить генерацию видео по первым и последним кадрам (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",
)Вы можете использовать как условия на основе изображений, так и на основе видео:
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",
)Поскольку обусловливание выполняется через латентные кадры, 8 кадров в пространстве данных, соответствующих указанному латентному кадру для условия изображения, будут иметь тенденцию к статичности.
Мультимодальное управление
Пайплайны LTX-2.X поддерживают мультимодальное управление. Оно состоит из трёх слагаемых, каждое из которых использует правило обновления в стиле CFG:
- Classifier-Free Guidance (CFG): стандартный CFG, где возмущённый («более слабый») вывод генерируется с использованием негативного промпта.
- Пространственно-временное управление (STG): STG отходит от использования возмущённого вывода, полученного путём сокращения операций само-внимания, и вместо этого подставляет значения внимания. Идея состоит в том, что это приводит к более чётким видео и лучшей пространственно-временной согласованности.
- Руководство по изоляции модальности: отходит от возмущённого вывода, создаваемого путём отключения кросс-внимания между модальностями (аудио-в-видео и видео-в-аудио). Это руководство более специфично для моделей LTX-2.X, с идеей о том, что это обеспечивает лучшую согласованность между сгенерированным аудио и видео.
Эти параметры управляются аргументами guidance_scale, stg_scale и modality_scale и могут быть заданы отдельно для видео и аудио. Кроме того, для STG необходимо указать индексы блоков трансформера, в которых пропускается само-внимание, с помощью аргумента spatio_temporal_guidance_blocks. Пайплайны LTX-2.X также поддерживают масштабирование гайданса, что помогает снизить переэкспозицию, которая может возникать при высоких значениях масштабов гайданса.
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",
)Улучшение промпта
Модели LTX-2.X чувствительны к стилю промптов. См. официальное руководство по промптам с рекомендациями по написанию качественных промптов. Использование улучшения промптов, при котором предоставленные промпты улучшаются с помощью текстового энкодера пайплайна (по умолчанию модель Gemma 3) на основе системного промпта, также может повысить качество сгенерированных образцов. Для использования улучшения промптов обязателен опциональный компонент пайплайна processor. Включите его с помощью enable_prompt_enhancement=True и system_prompt (по желанию, в соответствии с эталонными пайплайнами Lightricks):
import torch
from transformers import Gemma3Processor
from diffusers import LTX2Pipeline
from diffusers.utils import encode_video
from diffusers.pipelines.ltx2.utils import DEFAULT_NEGATIVE_PROMPT, T2V_DEFAULT_SYSTEM_PROMPT
device = "cuda" # or "mps", "xpu", "cpu"
width = 768
height = 512
random_seed = 42
frame_rate = 24.0
generator = torch.Generator(device).manual_seed(random_seed)
model_path = "diffusers/LTX-2.3-Diffusers"
pipe = LTX2Pipeline.from_pretrained(model_path, dtype=torch.bfloat16)
pipe.enable_model_cpu_offload(device=device)
pipe.vae.enable_tiling()
if getattr(pipe, "processor", None) is None:
processor = Gemma3Processor.from_pretrained("google/gemma-3-12b-it-qat-q4_0-unquantized")
pipe.processor = processor
prompt = (
"An astronaut hatches from a fragile egg on the surface of the Moon, the shell cracking and peeling apart in "
"gentle low-gravity motion. Fine lunar dust lifts and drifts outward with each movement, floating in slow arcs "
"before settling back onto the ground. The astronaut pushes free in a deliberate, weightless motion, small "
"fragments of the egg tumbling and spinning through the air. In the background, the deep darkness of space subtly "
"shifts as stars glide with the camera's movement, emphasizing vast depth and scale. The camera performs a "
"smooth, cinematic slow push-in, with natural parallax between the foreground dust, the astronaut, and the "
"distant starfield. Ultra-realistic detail, physically accurate low-gravity motion, cinematic lighting, and a "
"breath-taking, movie-like shot."
)
video, audio = pipe(
prompt=prompt,
negative_prompt=DEFAULT_NEGATIVE_PROMPT,
width=width,
height=height,
num_frames=121,
frame_rate=frame_rate,
num_inference_steps=30,
guidance_scale=3.0,
stg_scale=1.0,
modality_scale=3.0,
guidance_rescale=0.7,
audio_guidance_scale=7.0,
audio_stg_scale=1.0,
audio_modality_scale=3.0,
audio_guidance_rescale=0.7,
spatio_temporal_guidance_blocks=[28],
use_cross_timestep=True,
enable_prompt_enhancement=True,
system_prompt=T2V_DEFAULT_SYSTEM_PROMPT,
generator=generator,
output_type="np",
return_dict=False,
)
encode_video(
video[0],
fps=frame_rate,
audio=audio[0].float().cpu(),
audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
output_path="ltx2_3_t2v_stage_1.mp4",
)LTX-2.5
LTX-2.5 использует те же классы LTX2Pipeline/LTX2VideoTransformer3DModel/AutoencoderKLLTX2Video/и т. д., что и LTX-2.3 — отдельного класса пайплайна для него нет. Разница, видимая пользователем, заключается в текстовом энкодере: LTX-2.5 работает с чекпоинтом Gemma 4 (gemma4_unified), а не Gemma 3. Он загружается автоматически при вызове from_pretrained для сконвертированного чекпоинта LTX-2.5 (через классы Auto* из transformers), поэтому дополнительная настройка на этапе инференса не требуется — достаточно указать в from_pretrained репозиторий LTX-2.5 вместо LTX-2.3.
Lightricks/LTX-2.5-Diffusers содержит оба трансформера: дистиллированный DiT в transformer/, на который указывает model_index.json, и полный/SFT DiT в transformer_full/, который необходимо загружать явно (см. Полный / SFT трансформер). Папка scheduler/ в репозитории настроена для дистиллированной контрольной точки (use_dynamic_shifting=False, shift_terminal=None), чтобы её сигма-расписание использовалось в точности в том виде, в котором задано. Всё, что требуется для двухстадийной генерации, также поставляется в репозитории: подпапка latent_upsampler/ и дистиллированный LoRA для второй стадии, ltx-2.5-22b-distilled-lora-450-bf16.safetensors, в корне репозитория.
Дистиллированный вывод управляется явным расписанием сигмы, а не количеством шагов, и выполняется без направляющего сигнала (guidance_scale=1.0, поэтому negative_prompt не используется). Передача num_inference_steps вместо этого даст модели общее линейное расписание и незаметно снизит качество:
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",
)Двухэтапная генерация для LTX-2.5
LTX-2.5 поддерживает оба двухстадийных варианта, а DISTILLED_SIGMA_VALUES / STAGE_2_DISTILLED_SIGMA_VALUES являются его эталонными расписаниями:
- Дистиллированная контрольная точка, оба этапа — эталонный рецепт для стандартного
transformer/, показанный ниже. LoRA второго этапа не используется, поскольку трансформер уже дистиллирован; это Генерация дистиллированной контрольной точки с весами LTX-2.5. - Полный SFT, этап 1 + дистиллированный LoRA, этап 2 — Двухэтапная генерация, описанная в начале этой страницы, с использованием
transformer_full/и поставляемого LoRA. Подробности о изменениях — ниже.
Этап 1 выполняется в половинном от целевого разрешении, апсемплер удваивает его, а этап 2 уточняет изображение в полном разрешении — видео и аудио, оба с новым посевом из латентов этапа 1 при noise_scale=STAGE_2_DISTILLED_SIGMA_VALUES[0]. Высота и ширина должны делиться на 64, поскольку этап 1 уменьшает каждую ось вдвое и всё равно должен попасть на пространственную сетку 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",
)Если длина определяется duration head, а не явным параметром num_frames, пусть этап 1 принимает решение и восстанавливает фактическую длину из своих латентов ([B, C, F, H, W]) до запуска этапа 2, вместо того чтобы предсказывать её повторно:
num_frames = (video_latent.shape[2] - 1) * pipe.vae_temporal_compression_ratio + 1Этап 2 с дистиллированным LoRA
Чтобы вместо этого запустить Two-stages Generation — полный/SFT DiT для первого этапа, дистиллированный LoRA для второго — соберите пайплайн так, как описано в разделе Full / SFT transformer, и сгенерируйте латенты первого этапа с использованием этого стека guidance. Затем два момента отличаются от LTX-2.0/2.3. LoRA находится в самом репозитории diffusers, а не рядом с исходными весами, а переключение планировщика происходит в обратную сторону: в LTX-2.5 поставляется конфигурация планировщика distilled, поэтому именно на первом этапе включается динамический сдвиг, а на втором он снова отключается.
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
)Шаг апсемплинга и вызов этапа 2 остаются без изменений по сравнению с приведённым выше дистиллированным рецептом: те же sigmas=STAGE_2_DISTILLED_SIGMA_VALUES, тот же noise_scale и guidance_scale=1.0, поскольку на этапе 2 в любом случае выполняется дистиллированная модель.
Свёрточное и диффузионное декодирование
LTX-2.5 включает в себя два видеодекодера, работающих в одном и том же латентном пространстве, поэтому латенты взаимозаменяемы между ними:
vae/— свёрточный VAE (AutoencoderKLLTX2Video). Именно с его помощью пайплайны выполняют декодирование, поэтому все приведённые выше фрагменты кода уже используют его. Это единственный из двух, который поддерживает тайлинг (pipe.vae.enable_tiling()), что обычно позволяет уместить изображение высокого разрешения в память.diffusion_decoder/— LTX2VideoDiffusionDecoderModel. Это самостоятельная диффузионная модель, а не компонент пайплайна, поэтому она не передаётся какvae: запустите пайплайн сoutput_type="latent"и передайте латенты в LTX2VideoDiffusionDecodePipeline.
Кодирование всегда выполняется через vae/, поэтому выбор не влияет на условное кодирование изображений и видео.
При декодировании с помощью диффузионного декодера меняется две вещи. output_type="latent" также пропускает вокодер, поэтому аудио возвращается в виде латентов и требует ручной доработки, а процессор NATTEN фактически обязателен при видео-разрешениях:
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",
)Чтобы объединить это с двухэтапной генерацией, запросите у второго этапа output_type="latent" и декодируйте результат.
decoder.enable_tiling() позволяет удерживать декодирование высокого разрешения в памяти, аналогично тому, как pipe.vae.enable_tiling() делает это для свёрточного VAE. Памятёмкая часть декодирования — последний этап апсемплинга и этап диффузии — выполняется на перекрывающихся тайлах, которые затем смешиваются обратно, поэтому пиковое потребление памяти ограничивается размером тайла, а не размером видео. Тайлинг включается только тогда, когда латентное представление превышает один тайл, а размеры тайла и перекрытия можно настроить через аргументы tile_sample_min_* / tile_sample_stride_* (значения по умолчанию совпадают с эталонной реализацией). Поскольку на этапе диффузии шум удаляется для каждого тайла отдельно, результат декодирования с тайлингом не совпадает точно с результатом без тайлинга.
На одной карте также стоит освободить память перед декодированием (pipe.to("cpu") и torch.cuda.empty_cache(), после сохранения pipe.scheduler и output_sampling_rate вокодера), так как декодеру требуется собственное свободное пространство. Подробности об attention-бэкендах, тайлинге и остальном поведении декодера см. в LTX2VideoDiffusionDecoderModel.
Полный / SFT-трансформер
transformer_full/ не указан в model_index.json, поэтому его нужно загружать явно. Кроме того, для него требуется другой планировщик и полноценный механизм guidance: поставляемый scheduler/ настроен для дистиллированной контрольной точки, а значения по умолчанию для guidance — это общие настройки эпохи LTX-2.0, из-за которых прогон SFT для LTX-2.5 явно недоконтролируется, при этом никаких ошибок не возникает. Рекомендации из раздела Multimodal Guidance применимы здесь без изменений, включая STG на блоке 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,
)Перетащите sigmas сюда — полный DiT получает расписание из планировщика.
Улучшение промптов для LTX-2.5
Использование улучшения промптов настоятельно рекомендуется для LTX-2.5; передайте enable_prompt_enhancement=True, чтобы включить эту функцию (как в эталонных пайплайнах Lightricks). В отличие от LTX-2.0/2.3, где один и тот же чекпоинт текстового энкодера выполняет роль и энкодера, и улучшателя (см. Улучшение промптов выше), дообученный текстовый энкодер LTX-2.5 не обучался для улучшения. Вместо этого для улучшения используется отдельный готовый чекпоинт google/gemma-4-E2B-it. Загрузите его в необязательные компоненты пайплайна prompt_enhancer/processor, а затем включите улучшение — по умолчанию пайплайн использует LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT и рецепт Gemma 4 (do_sample=False, no_repeat_ngram_size=5, max_new_tokens=600). Передайте явное значение system_prompt=, чтобы переопределить:
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",
)То же самое относится к генерации видео по изображению с помощью LTX2ImageToVideoPipeline: установите pipe.prompt_enhancer/pipe.processor аналогичным образом и передайте enable_prompt_enhancement=True (используя LTX2_5_I2V_DEFAULT_SYSTEM_PROMPT, с условием на исходное изображение и текстовый промпт) — снова, system_prompt= не требуется, если вы не хотите переопределить его.
Автоматическая длительность для LTX-2.5
Чекпоинты LTX-2.5 поставляются с небольшим duration_head, который предсказывает длительность описанного кадра на основе того же вывода текстового коннектора, на который опирается трансформер. Если загруженный пайплайн содержит этот модуль, num_frames по умолчанию предсказывается автоматически — просто опустите этот параметр, и модель сама выберет длину:
video, audio = pipe(prompt=prompt, output_type="np", return_dict=False)Чтобы задать длину самостоятельно, явно передайте num_frames. Целое число всегда имеет приоритет над заголовком:
video, audio = pipe(prompt=prompt, num_frames=121, output_type="np", return_dict=False)Пайплайны, загруженные из чекпоинтов LTX-2.0 или LTX-2.3, не имеют duration head и сохраняют предыдущее значение по умолчанию в 121 кадр, поэтому для них это ничего не меняет.
Передайте min_seconds / max_seconds, чтобы ограничить предсказание. Сырое предсказание ограничивается указанным диапазоном, а затем преобразуется в кадры:
video, audio = pipe(
prompt=prompt,
min_seconds=2.0,
max_seconds=10.0,
frame_rate=frame_rate,
output_type="np",
return_dict=False,
)Предсказанное количество кадров округляется до каузальной временной сетки VAE (8k + 1), поэтому фактическая длительность квантуется — примерно 0,33 с на шаг при 24 кадрах/с — и смещается в зависимости от frame_rate, поскольку модель предсказывает секунды, а не кадры. min_seconds должно быть строго меньше max_seconds. Эти ограничения игнорируются, если num_frames задано явно.
Границы, уже одного шага сетки, могут не удовлетворяться точно: при 24 кадрах в секунду [1.0s, 1.02s] преобразуется в [24, 24] кадров, а 24 не является 8k + 1. Используется ближайшая точка сетки, и в журнал выводится предупреждение, поэтому возвращаемая длина может оказаться чуть за пределами таких строгих границ.
Чтобы проверить предсказание без генерации видео, вызовите head напрямую. Всё, что ему нужно, является публичным:
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")Конвертация контрольной точки версии 2.5 автоматически подхватывает head с помощью --full_pipeline или отдельно с помощью --duration_head. В контрольных точках, созданных до версии 2.5, таких весов нет, поэтому при конвертации этот компонент просто пропускается, а не вызывает ошибку.
Скорость движения для LTX-2.5
LTX-2 размещает каждый видеотокен на временной оси в секундах, которая по умолчанию выводится из frame_rate — скорости воспроизведения. Параметр motion_speed (по умолчанию 1.0) разделяет эти величины: временная ось обусловлена значением frame_rate / motion_speed, тогда как длина аудио, duration head и возвращаемое видео по-прежнему следуют frame_rate. При frame_rate=24.0 и motion_speed=0.2 модели сообщается, что действие было записано со скоростью 120 кадров/с, а результат воспроизводится со скоростью 24 кадра/с, что даёт замедление в 5 раз.
Базовая модель обучена на скоростях около 24/25/30/60 fps, поэтому значения, сильно отличающиеся от 1.0, имеют смысл только в сочетании с адаптером, обученным для них, например Lightricks/LTX-2.5-22b-LoRA-Slow-Motion-Control (с ограниченным доступом: сначала примите её лицензию на Hub). Без motion_speed этот LoRA загружается как обычный LoRA и не обеспечивает никакого управления движением. В карточке модели рекомендуются скорости 1.0, 0.5, 0.2, 0.1, 0.05 и 0.025 при силе LoRA 1.0. Не включайте в промпт слова, описывающие скорость («slow motion», «high fps»), и используйте один и тот же описательный текст для всех скоростей, поскольку именно motion_speed определяет эффект.
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",
)Оба клипа длятся 121 кадр (около 5 секунд при 24 кадрах в секунду), при этом меняется только темп движения. При двухэтапной генерации передавайте одно и то же значение motion_speed на оба этапа. Этап 2 повторно выполняет удаление шума из видео, и если бы он работал в реальном времени, это отменило бы замедленное воспроизведение. Справочный драйвер делает то же самое, оборачивая объект этапа, которым пользуются оба прохода.
motion_speed также является входным параметром модульных блоков LTX-2 / LTX-2.5 и передаётся в модульный пайплайн аналогичным образом.
LTX-2.5 Модульный
LTX-2.5 также доступен в виде модульного конвейера. Набор блоков по умолчанию использует диффузионный декодер и предсказывает длительность видео, если num_frames не указан. Он применяет гайданс отдельно к видео и аудио через компоненты guider и audio_guider. См. LTX2Guidance для списка доступных параметров гайданса. По умолчанию модульный конвейер скачивает промпт-усилитель и процессор из репозитория google/gemma-4-E2B-it. Ниже приведен пример модульного 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",
)Модульный конвейер будет автоматически переключать рабочие процессы в зависимости от переданных входных данных. Например, если передан image, будет использован рабочий процесс I2V:
import torch
from diffusers import ModularPipeline, ComponentsManager
from diffusers.models.autoencoders.ltx2_diffusion_decoder import LTX2VideoVaeNeighborhoodNattenProcessor
from diffusers.pipelines.ltx2.utils import DEFAULT_NEGATIVE_PROMPT
from diffusers.utils import encode_video, load_image
device = "cuda" # or "mps", "xpu", "cpu"
frame_rate = 24.0
random_seed = 42
generator = torch.Generator(device).manual_seed(random_seed)
model_path = "Lightricks/LTX-2.5-Diffusers"
cm = ComponentsManager()
pipe = ModularPipeline.from_pretrained(model_path, components_manager=cm)
pipe.load_components(dtype=torch.bfloat16)
cm.enable_auto_cpu_offload(device=device, memory_reserve_margin="20GB")
pipe.diffusion_decoder.set_attn_processor(LTX2VideoVaeNeighborhoodNattenProcessor())
pipe.diffusion_decoder.enable_tiling()
prompt = (
"An astronaut hatches from a fragile egg on the surface of the Moon, the shell cracking and peeling apart in "
"gentle low-gravity motion."
)
image_path = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg"
image = load_image(image_path)
output_state = pipe(
image=image,
prompt=prompt,
negative_prompt=DEFAULT_NEGATIVE_PROMPT,
width=768,
height=512,
num_frames=None, # Set to an int (e.g. 121) to specify a fixed video length
frame_rate=frame_rate,
num_inference_steps=30,
use_cross_timestep=True,
enable_prompt_enhancement=True,
generator=generator,
output_type="np",
)
video = output_state.get("videos")
audio = output_state.get("audio")
encode_video(
video[0],
fps=frame_rate,
audio=audio[0].float().cpu(),
audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
output_path="ltx2_5_modular_i2v.mp4",
)Поддерживаемые рабочие процессы можно найти в документации для каждого набора блоков (например, LTX2AutoBlocks, LTX25AutoBlocks).
Diffusion Fidelity Rendering (DFR) для LTX-2.5
LTX2DFRPipeline жертвует временем выполнения ради детализации. Каждый вызов __call__ — это один проход денойзинга с разрешением height × width: он генерирует видео и дополнительные слоты для ключевых кадров размером в один пиксель, либо повторно денойзит переданные латенты, инициализированные из этих слотов. Вызывающий код комбинирует этапы так же, как в других двухэтапных пайплайнах LTX: этот пайплайн, затем LTX2LatentUpsamplePipeline, снова этот пайплайн, а для каждого временного раунда — LTX2DFRTemporalRefinePipeline.
Слот обходится в полный латентный кадр токенов ради одного пиксельного кадра, что ослабляет эффективное временное сжатие в этой позиции — поэтому окружающее видео обуславливается действительно новыми кадрами, а не интерполированными. Позиции слотов определяются по сегментной сетке, выровненной по временной границе VAE (24 или 32 пиксельных кадра, в зависимости от того, какой вариант требует меньше дополнения). Холст внутренним образом дополняется до целого числа сегментов; output_type="latent" возвращает эту дополненную сетку, чтобы слот на дополнении не был удалён. Обрежьте с помощью trim_canvas перед декодированием VAE.
Для этого требуется трансформер, в конфигурации которого задан параметр use_keyframes_abs_pos_embedding, отмечающий латенты одиночных пиксельных кадров с помощью обучаемого эмбеддинга. Чекпоинты LTX-2.5 поставляются с этим параметром; пайплайн вызывает исключение для более старых версий, чтобы не тратить бюджет токенов на токены, которые он не может интерпретировать.
Бюджет на дополнительные токены: каждый слот добавляет объём, соответствующий одному латентному кадру, поэтому второй этап обрабатывает более длинную последовательность, чем эквивалентный двухэтапный дистиллированный проход — на 31% больше при разрешении 1024x1536 и 121 кадре (24576 -> 32256 токенов, 5 слотов на сетке сегментов из 24 кадров). Пиковая память активаций масштабируется пропорционально этому, поэтому разрешение, которое едва помещается в память при обычном дистиллированном рецепте, может потребовать enable_sequential_cpu_offload, vae.enable_tiling() или уменьшения холста в режиме DFR.
Composition использует return_dict=True для keyframes и keyframe_positions (return_dict=False возвращает те же четыре поля в виде кортежа).
Полный рецепт, приведённый ниже, — это тот, с которого стоит начинать: преобразование изображения в видео с разрешением 1088×1920, один раунд временного уточнения x2 и пространственный детализирующий IC-LoRA x2 на этапе 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 и width соответствуют данному проходу, а не итоговому выводу. Первый этап выполняется на холсте с разрешением, вдвое меньшим, чем 1080p (544×960); второй этап — на 1088×1920. Каждое значение должно делиться на пространственный коэффициент сжатия VAE (32 для LTX-2.5 при одном проходе; 64, если первый этап составляет половину от 1080p). Именно поэтому разрешение 1080p равно 1920×1088, а 4K — 3840×2176. Каждый проход использует фиксированный дистиллированный график (sigmas), поэтому параметра num_inference_steps нет; дистиллированные графики обучаются без гайданса, поэтому отсутствуют также negative_prompt и guidance_scale. Встроенный звук соответствует первому этапу — последующие проходы всё равно запускают аудиопоток, чтобы ветвь видео имела кросс-модальное внимание; сама форма волны после первого этапа не уточняется.
Пространственная детализация. Загрузите IC-LoRA для 2x пространственной детализации как именованный адаптер после этапа 1 и активируйте его только для этапа 2 (set_adapters(["detailing"], adapter_weights=[0.5])). На этапе 2 модель обращается к латентному представлению с половинным разрешением этапа 1 как к reference_latents. Этап 1 и временные раунды выполняются с выключенным адаптером. Если вы загрузите LoRA до этапа 1, transformer.disable_adapters() отключит его, а set_adapters не включит его обратно — вызовите transformer.enable_adapters() перед этапом 2 или загрузите веса после этапа 1, как в рецепте. reference_downscale_factor (по умолчанию 2) масштабирует пространственные координаты токенов-ссылок в пространство координат целевого изображения.
Повременное уточнение. LTX2DFRTemporalRefinePipeline представляет собой один раунд: временное увеличение разрешения, разбиение на тайлы по швам ключевых кадров, предковое шумоподавление с помощью LTXEulerAncestralRFScheduler (eta=0.5), склейка путём отбрасывания начального участка более позднего тайла и объединение пакета ключевых кадров. Этот планировщик нужно создавать самостоятельно — раунд будет отклонён при использовании любого другого, поскольку детерминированный шаг дойдёт до конца и вернёт лишь более мягкий холст. Вызывайте пайплайн один раз на раунд; для 2x / 4x используйте цикл, передавая round_index. После раунда keyframe_positions нельзя повторно вывести из исходного num_frames, поэтому их необходимо передавать явно. Каждый тайл получает срез замороженного аудио первого этапа, покрывающий собственное окно воспроизведения. source_seconds — это длительность первого этапа, она остаётся неизменной между раундами, поэтому в последующих раундах её нужно передавать явно, а не полагаться на значение по умолчанию.
Условие fps равно 60, если воспроизведение выше 30, независимо от мультиплексирования: время RoPE вычисляется как pixel_frame / fps, поэтому временная база 120 fps вдвое сократит временной диапазон каждого токена по сравнению с обученным распределением, а 48 fps — увеличит. Оба утверждают, что они 60, и обрабатывают декодированные кадры на скорости воспроизведения.
Третий пространственный этап. Соберите его; четвёртого пайплайна нет. Пространственно увеличьте только видео, пересоздайте ключевые кадры carry в RGB (decode → Lanczos ×2 → encode через rebuild_epilogue_keyframes(); никогда не увеличивайте ключевые кадры epilogue в латентном пространстве), затем:
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()Две оси сшиваются по-разному. Ни одна из сторон пространственной границы не содержит известного ответа, поэтому эти перекрытия смешиваются с трапециевидными весами. Временные тайлы разрезаются по швам ключевых кадров последнего раунда уточнения.
Декодирование с помощью диффузионного декодера. Для максимальной детализации оставайтесь на output_type="latent" и передавайте (уже денормализованные, возможно, обрезанные с помощью trim_canvas) латенты в 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
класс 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 )
Параметры
- transformer (LTXVideoTransformer3DModel) — Условная архитектура Transformer для удаления шума из закодированных латентов видео.
- scheduler (FlowMatchEulerDiscreteScheduler) —
планировщик, используемый в связке с
transformerдля удаления шума из закодированных латентов изображения. - vae (AutoencoderKLLTXVideo) — Модель вариационного автоэнкодера (VAE) для кодирования изображений в латентные представления и декодирования из них.
- text_encoder (
T5EncoderModel) — T5, а именно вариант google/t5-v1_1-xxl. - tokenizer (
CLIPTokenizer) — токенизатор класса CLIPTokenizer. - tokenizer (
T5TokenizerFast) — Второй токенизатор класса T5TokenizerFast. - connectors (
LTX2TextConnectors) — Стек текстовых коннекторов, используемый для адаптации скрытых состояний текстового энкодера для видео- и аудиоветвей.
Пайплайн для генерации видео по тексту.
Ссылка: 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[int] = 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[str] = ['latents']max_sequence_length: int = 1024 ) → ~pipelines.ltx.LTX2PipelineOutput or tuple
Параметры
- prompt (
strилиlist[str], необязательный) — Промпт или промпты для управления генерацией изображения. Если не задан, необходимо передатьprompt_embedsвместо него. - negative_prompt (
strorlist[str], необязательный) — Промпт или промпты, которые не должны направлять генерацию изображения. Если не задан, необходимо передатьnegative_prompt_embeds. Игнорируется, если не используется направляющее поле (guidance_scale < 1). - height (
int, необязательный, по умолчанию512) — Высота генерируемого изображения в пикселях. По умолчанию установлено значение 480 для достижения наилучших результатов. - width (
int, необязательный, по умолчанию768) — Ширина генерируемого изображения в пикселях. Для получения наилучших результатов по умолчанию установлено значение 848. - num_frames (
int, необязательный) — Количество кадров видео для генерации. Если значение не указано, по умолчанию используется автоматически предсказанная длительность, если в этом конвейере есть компонентduration_head(чекпоинты LTX-2.5 и новее), иначе —121. Передайте целое число, чтобы явно задать длину. Автоматически предсказанные значения округляются до каузальной временной сетки VAE, поэтому фактическая длительность квантуется (примерно 0,33 с при 24 кадрах/с). - min_seconds (
float, необязательный, по умолчанию1.0) — Нижняя граница для автоматически предсказанной длительности, еслиnum_framesне указан и присутствуетduration_head. Игнорируется, еслиnum_framesзадан явно. - max_seconds (
float, необязательный, по умолчанию20.0) — Верхняя граница для автоматически предсказанной длительности, еслиnum_framesне указан и присутствуетduration_head. Игнорируется, еслиnum_framesзадан явно. Должно быть строго большеmin_seconds. - frame_rate (
float, необязательный, по умолчанию24.0) — Количество кадров в секунду (FPS) в сгенерированном видео. - motion_speed (
float, необязательный, по умолчанию1.0) — Скорость движения относительно реального времени. Позиционные эмбеддинги зависят отframe_rate / motion_speed, поэтому значения меньше 1 замедляют движение, например0.2для 5-кратного замедления в Slow-Motion-Control LoRA.frame_rateостается скоростью воспроизведения: длительность аудио и предсказанное количество кадров определяются именно им. - num_inference_steps (
int, необязательный, по умолчанию 30) — Количество шагов денойзинга. Как правило, большее число шагов денойзинга приводит к изображению более высокого качества, но за счёт более медленного вывода. - sigmas (
List[float], необязательный) — Пользовательские сигмы для процесса удаления шума в планировщиках, поддерживающих аргументsigmasв их методеset_timesteps. Если не задано, будет использовано поведение по умолчанию при передачеnum_inference_steps. - timesteps (
list[int], необязательный) — Пользовательские шаги для процесса удаления шума в планировщиках, поддерживающих аргументtimestepsв методеset_timesteps. Если не задан, будет использоваться поведение по умолчанию при передачеnum_inference_steps. Значения должны быть в порядке убывания. - guidance_scale (
float, необязательный, по умолчанию4.0) — Масштаб руководства, определенный в Classifier-Free Diffusion Guidance.guidance_scaleопределяется какwиз уравнения 2 статьи Imagen Paper. Масштаб руководства включается при установкеguidance_scale > 1. Более высокое значение масштаба руководства способствует генерации изображений, тесно связанных с текстовымprompt, обычно за счет снижения качества изображения. Используется для модальности видео (для модальности аудио есть отдельное значениеaudio_guidance_scale). - stg_scale (
float, необязательный, по умолчанию0.0) — Масштаб руководства для видео в методе Spatio-Temporal Guidance (STG), предложенном в статье Spatiotemporal Skip Guidance for Enhanced Video Diffusion Sampling. STG использует оценку, аналогичную CFG, при которой образец смещается от слабого образца, полученного из возмущенной версии модели денойзинга. Включение STG приводит к дополнительному проходу через модель денойзинга; значение по умолчанию0.0означает, что STG отключен. - modality_scale (
float, необязательный, по умолчанию1.0) — Масштаб руководства для видео в режиме изоляции модальности LTX-2.X, при котором образец смещается от более слабого образца, сгенерированного моделью денуазинга с отключенным кросс-вниманием между модальностями (аудио-в-видео и видео-в-аудио), с использованием оценки, аналогичной CFG. Включение руководства по модальности приводит к дополнительному прямому проходу модели денуазинга; значение по умолчанию1.0означает, что руководство по модальности отключено. - guidance_rescale (
float, optional, defaults to 0.0) — Guidance rescale factor proposed by Common Diffusion Noise Schedules and Sample Steps are Flawedguidance_scaleis defined asφin equation 16. of Common Diffusion Noise Schedules and Sample Steps are Flawed. Guidance rescale factor should fix overexposure when using zero terminal SNR. Used for the video modality. - audio_guidance_scale (
float, необязательный, по умолчаниюNone) — Масштаб аудио-гайданса для CFG относительно негативного промпта. Правило обновления CFG одинаково для видео и аудио, но для масштаба гайданса можно использовать разные значения. Авторы LTX-2.X рекомендуют делатьaudio_guidance_scaleвыше по сравнению с видеоguidance_scale(например, для LTX-2.3 они предлагают 3.0 для видео и 7.0 для аудио). ЕслиNone, по умолчанию используется значение для видеоguidance_scale. - audio_stg_scale (
float, необязательный, по умолчаниюNone) — Масштаб аудио-гидинга для STG. Как и в случае с CFG, правило обновления STG в остальном одинаково для видео и аудио. Для LTX-2.3 рекомендуется значение 1.0 как для видео, так и для аудио. ЕслиNone, по умолчанию используется значение для видеоstg_scale. - audio_modality_scale (
float, необязательный, по умолчаниюNone) — Масштаб аудио-гидинга для изоляции модальности в LTX-2.X. Как и в случае с CFG, правило модального гидинга в остальном одинаково для видео и аудио. Для LTX-2.3 рекомендуется значение 3.0 как для видео, так и для аудио. ЕслиNone, по умолчанию используется значение видеоmodality_scale. - audio_guidance_rescale (
float, необязательный, по умолчаниюNone) — Отдельный коэффициент rescale для модальности аудио. ЕслиNone, по умолчанию используется значение видеоguidance_rescale. - spatio_temporal_guidance_blocks (
list[int], необязательный, по умолчаниюNone) — Индексы блоков трансформера (начиная с нуля), на которых применяется STG. Обязательный параметр при использовании STG (еслиstg_scaleилиaudio_stg_scaleбольше0). Для LTX-2.0 рекомендуется значение[29], а для LTX-2.3 —[28]. - noise_scale (
float, необязательный, по умолчанию0.0) — Коэффициент интерполяции между случайным шумом и денойзанными латентами на каждом шаге. Применяет шум кlatentsиaudio_latentsперед продолжением денойзинга. - num_videos_per_prompt (
int, необязательный, по умолчанию 1) — Количество видео, генерируемых для каждого промпта. - generator (
torch.Generatorилиlist[torch.Generator], необязательный) — Один или список генераторов torch для обеспечения детерминированности генерации. - latents (
torch.Tensor, необязательный) — Предварительно сгенерированные зашумлённые латенты, выбранные из гауссова распределения, которые используются в качестве входных данных для генерации видео. Позволяет корректировать один и тот же процесс генерации с помощью различных промптов. Если не заданы, тензор латентов будет сгенерирован путём выборки с использованием переданного случайногоgenerator. - audio_latents (
torch.Tensor, необязательный) — Предварительно сгенерированные зашумлённые латенты, выбранные из гауссова распределения, которые используются в качестве входных данных для генерации аудио. Можно использовать, чтобы корректировать одну и ту же генерацию с разными промптами. Если не указано, тензор латентов будет сгенерирован путём выборки с использованием переданного случайногоgenerator. - prompt_embeds (
torch.Tensor, необязательный) — Предварительно сгенерированные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, например, для взвешивания промпта. Если не передано, текстовые эмбеддинги будут сгенерированы из входного аргументаprompt. - prompt_attention_mask (
torch.Tensor, необязательный) — Предварительно сгенерированная маска внимания для текстовых эмбеддингов. - negative_prompt_embeds (
torch.FloatTensor, необязательный) — Предварительно сгенерированные эмбеддинги отрицательного текста. Для PixArt-Sigma этот отрицательный промпт должен быть "". Если не предоставлен, negative_prompt_embeds будет сгенерирован из аргументаnegative_prompt. - negative_prompt_attention_mask (
torch.FloatTensor, необязательный) — Предварительно сгенерированная маска внимания для отрицательных текстовых эмбеддингов. - decode_timestep (
float, по умолчанию0.0) — Шаг времени, на котором декодируется сгенерированное видео. - decode_noise_scale (
float, по умолчаниюNone) — Коэффициент интерполяции между случайным шумом и денойзанными латентами на шаге декодирования. - use_cross_timestep (
boolнеобязательный, по умолчаниюTrue) — Определяет, следует ли использовать сигму кросс-модальности (аудио является кросс-модальностью для видео и наоборот) при вычислении параметров модуляции кросс-внимания.Trueсоответствует поведению LTX-2.3/2.5;False— устаревшему поведению LTX-2.0. - system_prompt (
str, необязательный, по умолчаниюNone) — Необязательная системная подсказка для улучшения промпта. Системная подсказка используется улучшителем промпта (модель условной генерации Gemma — выделенный компонентprompt_enhancer, если он настроен, в противном случае основнойtext_encoder) для генерации улучшенного промпта из исходногоpromptдля управления генерацией. Если значение не указано, а выделенныйprompt_enhancerнастроен (LTX-2.5), по умолчанию используетсяLTX2_5_T2V_DEFAULT_SYSTEM_PROMPT(изdiffusers.pipelines.ltx2.utils) — см.enable_prompt_enhancement. - enable_prompt_enhancement (
bool, необязательный, по умолчаниюFalse) — Определяет, следует ли выполнять улучшение промпта. Функция включается явно, в соответствии с эталонными конвейерами Lightricks. ЕслиTrueиsystem_promptне указан, LTX-2.5 используетLTX2_5_T2V_DEFAULT_SYSTEM_PROMPT, если настроен специальныйprompt_enhancer; для LTX-2.0/2.3 требуется явное указаниеsystem_prompt. - prompt_max_new_tokens (
int, необязательный, по умолчаниюNone) — Максимальное количество новых токенов для генерации при улучшении промпта. Если значение не указано, используется 600 для выделенногоprompt_enhancerGemma 4 (LTX-2.5) или 512 для резервногоtext_encoderGemma 3 (LTX-2.0/2.3). - prompt_enhancement_kwargs (
dict[str, Any], необязательный, по умолчаниюNone) — Параметры для вызова.generateв модуле улучшения промпта. Если не указаны, всегда соответствуют модели, выполняющей улучшение:do_sample=False, no_repeat_ngram_size=5(жадный выбор) при использовании отдельногоprompt_enhancer(LTX-2.5) илиdo_sample=True, temperature=0.7для резервногоtext_encoder(LTX-2.0/2.3). Подробнее см. https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationMixin.generate. - prompt_enhancement_seed (
int, необязательный, по умолчанию10) — Случайный сид для любых операций с генерацией случайных чисел при улучшении промпта. - output_type (
str, необязательный, по умолчанию"pil") — Формат вывода сгенерированного изображения. Выберите один из вариантов: PIL:PIL.Image.Imageилиnp.array. - return_dict (
bool, необязательный, по умолчаниюTrue) — Определяет, следует ли возвращать~pipelines.ltx.LTX2PipelineOutputвместо обычного кортежа. - attention_kwargs (
dict, необязательный) — Словарь kwargs, который при указании передается вAttentionProcessor, определенный вself.processorв diffusers.models.attention_processor. - callback_on_step_end (
Callable, необязательный) — Функция, вызываемая в конце каждого шага денойзинга во время инференса. Функция вызывается со следующими аргументами:callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict).callback_kwargsбудет содержать список всех тензоров, как указано вcallback_on_step_end_tensor_inputs. - callback_on_step_end_tensor_inputs (
List, необязательный, по умолчанию["latents"]) — Список тензорных входных данных для функцииcallback_on_step_end. Тензоры, указанные в списке, будут переданы в качестве аргументаcallback_kwargs. Вы сможете включать только переменные, перечисленные в атрибуте._callback_tensor_inputsвашего класса пайплайна. - max_sequence_length (
int, необязательный, по умолчанию1024) — Максимальная длина последовательности, используемая сprompt.
Возвращает
~pipelines.ltx.LTX2PipelineOutput или tuple
Если return_dict равно True, возвращается ~pipelines.ltx.LTX2PipelineOutput, иначе возвращается tuple, где первый элемент — это список с сгенерированными изображениями.
Функция, вызываемая при обращении к конвейеру для генерации.
Примеры:
>>> 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 )
Параметры
- prompt (
strилиlist[str], необязательный) — промпт для кодирования - negative_prompt (
strorlist[str], необязательный) — Промпт или промпты, которые не должны направлять генерацию изображения. Если не задан, необходимо передатьnegative_prompt_embeds. Игнорируется, если не используется направляющее поле (то есть игнорируется, еслиguidance_scaleменьше1). - do_classifier_free_guidance (
bool, необязательный, по умолчаниюTrue) — Использовать ли classifier free guidance. - num_videos_per_prompt (
int, необязательный, по умолчанию 1) — Количество видео, которое должно быть сгенерировано для каждого промпта. Устройство torch, на котором должны размещаться результирующие эмбеддинги - prompt_embeds (
torch.Tensor, необязательный) — Предварительно сгенерированные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, например, для взвешивания промпта. Если не передано, текстовые эмбеддинги будут сгенерированы из входного аргументаprompt. - negative_prompt_embeds (
torch.Tensor, необязательный) — Предварительно сгенерированные отрицательные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, например для взвешивания промпта. Если не передано, negative_prompt_embeds будет сгенерировано из входного аргументаnegative_prompt. - device — (
torch.device, необязательный): устройство torch - dtype — (
torch.dtype, необязательный): torch dtype
Кодирует промпт в скрытые состояния текстового энкодера.
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 )
Улучшает переданный prompt, генерируя новый промпт с помощью модуля улучшения промптов (модель условной генерации Gemma) на основе исходного промпта и системного промпта. Если передан image, модуль улучшения также использует этот кадр в качестве опорного (улучшение в стиле I2V / ключевых кадров). Использует выделенный компонент prompt_enhancer, если он настроен (например, LTX-2.5, текстовый энкодер которого не обучен для улучшения), в противном случае использует основной text_encoder (LTX-2.0/2.3, который выполняет роль собственного модуля улучшения).
Шаблоны сообщений, аргументы декодирования, очистка ответа и подготовка длинной стороны изображения соответствуют ltx-core / ltx-pipelines (enhance_t2v / enhance_i2v / generate_enhanced_prompt).
LTX2ImageToVideoPipeline
класс 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 )
Пайплайн для генерации видео по изображению.
Ссылка: 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[str] = ['latents']max_sequence_length: int = 1024 ) → ~pipelines.ltx.LTX2PipelineOutput or tuple
Параметры
- image (
PipelineImageInput) — Входное изображение, на основе которого выполняется генерация. Должно быть изображением, списком изображений илиtorch.Tensor. - prompt (
strилиlist[str], необязательный) — Промпт или промпты для управления генерацией изображения. Если не задан, необходимо передатьprompt_embedsвместо него. - negative_prompt (
strorlist[str], необязательный) — Промпт или промпты, которые не должны направлять генерацию изображения. Если не задан, необходимо передатьnegative_prompt_embeds. Игнорируется, если не используется направляющее поле (guidance_scale < 1). - height (
int, необязательный, по умолчанию512) — Высота генерируемого изображения в пикселях. По умолчанию установлено значение 480 для достижения наилучших результатов. - width (
int, необязательный, по умолчанию768) — Ширина генерируемого изображения в пикселях. Для получения наилучших результатов по умолчанию установлено значение 848. - num_frames (
int, необязательный) — Количество кадров видео для генерации. Если значение не указано, по умолчанию используется автоматически предсказанная длительность, если в этом конвейере есть компонентduration_head(чекпоинты LTX-2.5 и новее), иначе —121. Передайте целое число, чтобы явно задать длину. Автоматически предсказанные значения округляются до каузальной временной сетки VAE, поэтому фактическая длительность квантуется (примерно 0,33 с при 24 кадрах/с). - min_seconds (
float, необязательный, по умолчанию1.0) — Нижняя граница для автоматически предсказанной длительности, еслиnum_framesне указан и присутствуетduration_head. Игнорируется, еслиnum_framesзадан явно. - max_seconds (
float, необязательный, по умолчанию20.0) — Верхняя граница для автоматически предсказанной длительности, еслиnum_framesне указан и присутствуетduration_head. Игнорируется, еслиnum_framesзадан явно. Должно быть строго большеmin_seconds. - frame_rate (
float, необязательный, по умолчанию24.0) — Количество кадров в секунду (FPS) в сгенерированном видео. - motion_speed (
float, необязательный, по умолчанию1.0) — Скорость движения относительно реального времени. Позиционные эмбеддинги зависят отframe_rate / motion_speed, поэтому значения меньше 1 замедляют движение, например0.2для 5-кратного замедления в Slow-Motion-Control LoRA.frame_rateостается скоростью воспроизведения: длительность аудио и предсказанное количество кадров определяются именно им. - num_inference_steps (
int, необязательный, по умолчанию 30) — Количество шагов денойзинга. Как правило, большее число шагов денойзинга приводит к изображению более высокого качества, но за счёт более медленного вывода. - sigmas (
List[float], необязательный) — Пользовательские сигмы для процесса удаления шума в планировщиках, поддерживающих аргументsigmasв их методеset_timesteps. Если не задано, будет использовано поведение по умолчанию при передачеnum_inference_steps. - timesteps (
List[int], необязательный) — Пользовательские шаги для процесса удаления шума с планировщиками, которые поддерживают аргументtimestepsв их методеset_timesteps. Если не задано, будет использоваться поведение по умолчанию при передачеnum_inference_steps. Должны быть в порядке убывания. - guidance_scale (
float, необязательный, по умолчанию4.0) — Масштаб руководства, определенный в Classifier-Free Diffusion Guidance.guidance_scaleопределяется какwиз уравнения 2 статьи Imagen Paper. Масштаб руководства включается при установкеguidance_scale > 1. Более высокое значение масштаба руководства способствует генерации изображений, тесно связанных с текстовымprompt, обычно за счет снижения качества изображения. Используется для модальности видео (для модальности аудио есть отдельное значениеaudio_guidance_scale). - stg_scale (
float, необязательный, по умолчанию0.0) — Масштаб руководства для видео в методе Spatio-Temporal Guidance (STG), предложенном в статье Spatiotemporal Skip Guidance for Enhanced Video Diffusion Sampling. STG использует оценку, аналогичную CFG, при которой образец смещается от слабого образца, полученного из возмущенной версии модели денойзинга. Включение STG приводит к дополнительному проходу через модель денойзинга; значение по умолчанию0.0означает, что STG отключен. - modality_scale (
float, необязательный, по умолчанию1.0) — Масштаб руководства для видео в режиме изоляции модальности LTX-2.X, при котором образец смещается от более слабого образца, сгенерированного моделью денуазинга с отключенным кросс-вниманием между модальностями (аудио-в-видео и видео-в-аудио), с использованием оценки, аналогичной CFG. Включение руководства по модальности приводит к дополнительному прямому проходу модели денуазинга; значение по умолчанию1.0означает, что руководство по модальности отключено. - guidance_rescale (
float, optional, defaults to 0.0) — Guidance rescale factor proposed by Common Diffusion Noise Schedules and Sample Steps are Flawedguidance_scaleis defined asφin equation 16. of Common Diffusion Noise Schedules and Sample Steps are Flawed. Guidance rescale factor should fix overexposure when using zero terminal SNR. Used for the video modality. - audio_guidance_scale (
float, необязательный, по умолчаниюNone) — Масштаб аудио-гайданса для CFG относительно негативного промпта. Правило обновления CFG одинаково для видео и аудио, но для масштаба гайданса можно использовать разные значения. Авторы LTX-2.X рекомендуют делатьaudio_guidance_scaleвыше по сравнению с видеоguidance_scale(например, для LTX-2.3 они предлагают 3.0 для видео и 7.0 для аудио). ЕслиNone, по умолчанию используется значение для видеоguidance_scale. - audio_stg_scale (
float, необязательный, по умолчаниюNone) — Масштаб аудио-гидинга для STG. Как и в случае с CFG, правило обновления STG в остальном одинаково для видео и аудио. Для LTX-2.3 рекомендуется значение 1.0 как для видео, так и для аудио. ЕслиNone, по умолчанию используется значение для видеоstg_scale. - audio_modality_scale (
float, необязательный, по умолчаниюNone) — Масштаб аудио-гидинга для изоляции модальности в LTX-2.X. Как и в случае с CFG, правило модального гидинга в остальном одинаково для видео и аудио. Для LTX-2.3 рекомендуется значение 3.0 как для видео, так и для аудио. ЕслиNone, по умолчанию используется значение видеоmodality_scale. - audio_guidance_rescale (
float, необязательный, по умолчаниюNone) — Отдельный коэффициент rescale для модальности аудио. ЕслиNone, по умолчанию используется значение видеоguidance_rescale. - spatio_temporal_guidance_blocks (
list[int], необязательный, по умолчаниюNone) — Индексы блоков трансформера (начиная с нуля), на которых применяется STG. Обязательный параметр при использовании STG (еслиstg_scaleилиaudio_stg_scaleбольше0). Для LTX-2.0 рекомендуется значение[29], а для LTX-2.3 —[28]. - noise_scale (
float, необязательный, по умолчанию0.0) — Коэффициент интерполяции между случайным шумом и денойзанными латентами на каждом шаге. Применяет шум кlatentsиaudio_latentsперед продолжением денойзинга. - num_videos_per_prompt (
int, необязательный, по умолчанию 1) — Количество видео, генерируемых для каждого промпта. - generator (
torch.Generatorилиlist[torch.Generator], необязательный) — Один или список генераторов torch для обеспечения детерминированности генерации. - latents (
torch.Tensor, необязательный) — Предварительно сгенерированные зашумлённые латенты, выбранные из гауссова распределения, которые используются в качестве входных данных для генерации видео. Позволяет корректировать один и тот же процесс генерации с помощью различных промптов. Если не заданы, тензор латентов будет сгенерирован путём выборки с использованием переданного случайногоgenerator. - audio_latents (
torch.Tensor, необязательный) — Предварительно сгенерированные зашумлённые латенты, выбранные из гауссова распределения, которые используются в качестве входных данных для генерации аудио. Можно использовать, чтобы корректировать одну и ту же генерацию с разными промптами. Если не указано, тензор латентов будет сгенерирован путём выборки с использованием переданного случайногоgenerator. - prompt_embeds (
torch.Tensor, необязательный) — Предварительно сгенерированные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, например, для взвешивания промпта. Если не передано, текстовые эмбеддинги будут сгенерированы из входного аргументаprompt. - prompt_attention_mask (
torch.Tensor, необязательный) — Предварительно сгенерированная маска внимания для текстовых эмбеддингов. - negative_prompt_embeds (
torch.FloatTensor, необязательный) — Предварительно сгенерированные эмбеддинги отрицательного текста. Для PixArt-Sigma этот отрицательный промпт должен быть "". Если не предоставлен, negative_prompt_embeds будет сгенерирован из аргументаnegative_prompt. - negative_prompt_attention_mask (
torch.FloatTensor, необязательный) — Предварительно сгенерированная маска внимания для отрицательных текстовых эмбеддингов. - decode_timestep (
float, по умолчанию0.0) — Шаг времени, на котором декодируется сгенерированное видео. - decode_noise_scale (
float, по умолчаниюNone) — Коэффициент интерполяции между случайным шумом и денойзанными латентами на шаге декодирования. - use_cross_timestep (
boolнеобязательный, по умолчаниюTrue) — Определяет, следует ли использовать сигму кросс-модальности (аудио является кросс-модальностью для видео и наоборот) при вычислении параметров модуляции кросс-внимания.Trueсоответствует поведению LTX-2.3/2.5;False— устаревшему поведению LTX-2.0. - system_prompt (
str, необязательный, по умолчаниюNone) — Необязательная системная подсказка для улучшения промпта. Системная подсказка используется улучшителем промпта (модель условной генерации Gemma — выделенный компонентprompt_enhancer, если он настроен, в противном случае основнойtext_encoder) для генерации улучшенного промпта на основе исходногоpromptи первогоimageдля условия генерации. Если значение не указано, а выделенныйprompt_enhancerнастроен (LTX-2.5), по умолчанию используетсяLTX2_5_I2V_DEFAULT_SYSTEM_PROMPT(изdiffusers.pipelines.ltx2.utils) — см.enable_prompt_enhancement. - enable_prompt_enhancement (
bool, необязательный, по умолчаниюFalse) — Определяет, следует ли выполнять улучшение промпта. Функция включается явно, в соответствии с эталонными конвейерами Lightricks. ЕслиTrueиsystem_promptне указан, LTX-2.5 используетLTX2_5_I2V_DEFAULT_SYSTEM_PROMPT, если настроен специальныйprompt_enhancer; для LTX-2.0/2.3 требуется явное указаниеsystem_prompt. - prompt_max_new_tokens (
int, необязательный, по умолчаниюNone) — Максимальное количество новых токенов для генерации при улучшении промпта. Если значение не указано, используется 600 для выделенногоprompt_enhancerGemma 4 (LTX-2.5) или 512 для резервногоtext_encoderGemma 3 (LTX-2.0/2.3). - prompt_enhancement_kwargs (
dict[str, Any], необязательный, по умолчаниюNone) — Параметры для вызова.generateв модуле улучшения промпта. Если не указаны, всегда соответствуют модели, выполняющей улучшение:do_sample=False, no_repeat_ngram_size=3(жадный поиск) при использовании отдельногоprompt_enhancer(LTX-2.5) илиdo_sample=True, temperature=0.7для резервногоtext_encoder(LTX-2.0/2.3). Подробнее см. https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationMixin.generate. - prompt_enhancement_seed (
int, необязательный, по умолчанию10) — Случайный сид для любых операций с генерацией случайных чисел при улучшении промпта. - image_crf (
int, необязательный, по умолчаниюNone) — CRF для H.264, используемый для пережатия исходногоimageперед кодированием VAE, чтобы соответствовать сжатию, с которым обучалась модель.Noneозначает «использовать значение по умолчанию для модели» (33 для LTX-2.3, 18 для LTX-2.5). Передайте0, чтобы пропустить пережатие. ТребуетсяPIL.Image.Image, если выполняется пережатие. - output_type (
str, необязательный, по умолчанию"pil") — Формат вывода сгенерированного изображения. Выберите один из вариантов: PIL:PIL.Image.Imageилиnp.array. - return_dict (
bool, необязательный, по умолчаниюTrue) — Определяет, следует ли возвращать~pipelines.ltx.LTX2PipelineOutputвместо обычного кортежа. - attention_kwargs (
dict, необязательный) — Словарь kwargs, который при указании передается вAttentionProcessor, определенный вself.processorв diffusers.models.attention_processor. - callback_on_step_end (
Callable, необязательный) — Функция, вызываемая в конце каждого шага денойзинга во время инференса. Функция вызывается со следующими аргументами:callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict).callback_kwargsбудет содержать список всех тензоров, как указано вcallback_on_step_end_tensor_inputs. - callback_on_step_end_tensor_inputs (
List, необязательный) — Список тензорных входных данных для функцииcallback_on_step_end. Тензоры, указанные в списке, будут переданы в качестве аргументаcallback_kwargs. Вы сможете включать только переменные, перечисленные в атрибуте._callback_tensor_inputsвашего класса конвейера. - max_sequence_length (
int, необязательный, по умолчанию1024) — Максимальная длина последовательности, используемая сprompt.
Возвращает
~pipelines.ltx.LTX2PipelineOutput или tuple
Если return_dict равно True, возвращается ~pipelines.ltx.LTX2PipelineOutput, иначе возвращается tuple, где первый элемент — это список с сгенерированными изображениями.
Функция, вызываемая при обращении к конвейеру для генерации.
Примеры:
>>> 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 )
Параметры
- prompt (
strилиlist[str], необязательный) — промпт для кодирования - negative_prompt (
strorlist[str], необязательный) — Промпт или промпты, которые не должны направлять генерацию изображения. Если не задан, необходимо передатьnegative_prompt_embeds. Игнорируется, если не используется направляющее поле (то есть игнорируется, еслиguidance_scaleменьше1). - do_classifier_free_guidance (
bool, необязательный, по умолчаниюTrue) — Использовать ли classifier free guidance. - num_videos_per_prompt (
int, необязательный, по умолчанию 1) — Количество видео, которое должно быть сгенерировано для каждого промпта. Устройство torch, на котором должны размещаться результирующие эмбеддинги - prompt_embeds (
torch.Tensor, необязательный) — Предварительно сгенерированные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, например, для взвешивания промпта. Если не передано, текстовые эмбеддинги будут сгенерированы из входного аргументаprompt. - negative_prompt_embeds (
torch.Tensor, необязательный) — Предварительно сгенерированные отрицательные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, например для взвешивания промпта. Если не передано, negative_prompt_embeds будет сгенерировано из входного аргументаnegative_prompt. - device — (
torch.device, необязательный): устройство torch - dtype — (
torch.dtype, необязательный): torch dtype
Кодирует промпт в скрытые состояния текстового энкодера.
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 )
Улучшает переданный prompt, генерируя новый промпт с помощью модуля улучшения промптов (модель условной генерации Gemma) на основе исходного промпта и системного промпта. Если передан image, модуль улучшения также использует этот кадр в качестве опорного (улучшение в стиле I2V / ключевых кадров). Использует выделенный компонент prompt_enhancer, если он настроен (например, LTX-2.5, текстовый энкодер которого не обучен для улучшения), в противном случае использует основной text_encoder (LTX-2.0/2.3, который выполняет роль собственного модуля улучшения).
Шаблоны сообщений, аргументы декодирования, очистка ответа и подготовка длинной стороны изображения соответствуют ltx-core / ltx-pipelines (enhance_t2v / enhance_i2v / generate_enhanced_prompt).
LTX2ConditionPipeline
класс 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 для генерации видео, позволяющий вставлять условия на основе изображений в произвольные части видео.
Ссылка: 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[str] = ['latents']max_sequence_length: int = 1024 ) → ~pipelines.ltx.LTX2PipelineOutput or tuple
Параметры
- conditions (
List[LTXVideoCondition], *optional*) — Список элементов для условного формирования кадров при генерации видео. - prompt (
strилиList[str], необязательный) — Промпт или промпты для управления генерацией изображения. Если не задан, необходимо передатьprompt_embedsвместо него. - negative_prompt (
strилиList[str], необязательный) — Промпт или промпты, которые не должны направлять генерацию изображения. Если не задан, необходимо передатьnegative_prompt_embeds. Игнорируется, если не используется направляющее поле (guidance_scale < 1). - height (
int, необязательный, по умолчанию512) — Высота генерируемого изображения в пикселях. По умолчанию установлено значение 480 для достижения наилучших результатов. - width (
int, необязательный, по умолчанию768) — Ширина генерируемого изображения в пикселях. Для получения наилучших результатов по умолчанию установлено значение 848. - num_frames (
int, необязательный) — Количество кадров видео для генерации. Если значение не указано, по умолчанию используется автоматически предсказанная длительность, если в этом конвейере есть компонентduration_head(чекпоинты LTX-2.5 и новее), иначе —121. Передайте целое число, чтобы явно задать длину. Автоматически предсказанные значения округляются до каузальной временной сетки VAE, поэтому фактическая длительность квантуется (примерно 0,33 с при 24 кадрах/с). - min_seconds (
float, необязательный, по умолчанию1.0) — Нижняя граница для автоматически предсказанной длительности, еслиnum_framesне указан и присутствуетduration_head. Игнорируется, еслиnum_framesзадан явно. - max_seconds (
float, необязательный, по умолчанию20.0) — Верхняя граница для автоматически предсказанной длительности, еслиnum_framesне указан и присутствуетduration_head. Игнорируется, еслиnum_framesзадан явно. Должно быть строго большеmin_seconds. - frame_rate (
float, необязательный, по умолчанию24.0) — Количество кадров в секунду (FPS) в сгенерированном видео. - motion_speed (
float, необязательный, по умолчанию1.0) — Скорость движения относительно реального времени. Позиционные эмбеддинги зависят отframe_rate / motion_speed, поэтому значения меньше 1 замедляют движение, например0.2для 5-кратного замедления в Slow-Motion-Control LoRA.frame_rateостается скоростью воспроизведения: длительность аудио и предсказанное количество кадров определяются именно им. - num_inference_steps (
int, необязательный, по умолчанию 30) — Количество шагов денойзинга. Как правило, большее число шагов денойзинга приводит к изображению более высокого качества, но за счёт более медленного вывода. - sigmas (
List[float], необязательный) — Пользовательские сигмы для процесса удаления шума в планировщиках, поддерживающих аргументsigmasв их методеset_timesteps. Если не задано, будет использовано поведение по умолчанию при передачеnum_inference_steps. - timesteps (
List[int], необязательный) — Пользовательские шаги для процесса удаления шума с планировщиками, которые поддерживают аргументtimestepsв их методеset_timesteps. Если не задано, будет использоваться поведение по умолчанию при передачеnum_inference_steps. Должны быть в порядке убывания. - guidance_scale (
float, необязательный, по умолчанию4.0) — Масштаб руководства, определенный в Classifier-Free Diffusion Guidance.guidance_scaleопределяется какwиз уравнения 2 статьи Imagen Paper. Масштаб руководства включается при установкеguidance_scale > 1. Более высокое значение масштаба руководства способствует генерации изображений, тесно связанных с текстовымprompt, обычно за счет снижения качества изображения. Используется для модальности видео (для модальности аудио есть отдельное значениеaudio_guidance_scale). - stg_scale (
float, необязательный, по умолчанию0.0) — Масштаб руководства для видео в методе Spatio-Temporal Guidance (STG), предложенном в статье Spatiotemporal Skip Guidance for Enhanced Video Diffusion Sampling. STG использует оценку, аналогичную CFG, при которой образец смещается от слабого образца, полученного из возмущенной версии модели денойзинга. Включение STG приводит к дополнительному проходу через модель денойзинга; значение по умолчанию0.0означает, что STG отключен. - modality_scale (
float, необязательный, по умолчанию1.0) — Масштаб руководства для видео в режиме изоляции модальности LTX-2.X, при котором образец смещается от более слабого образца, сгенерированного моделью денуазинга с отключенным кросс-вниманием между модальностями (аудио-в-видео и видео-в-аудио), с использованием оценки, аналогичной CFG. Включение руководства по модальности приводит к дополнительному прямому проходу модели денуазинга; значение по умолчанию1.0означает, что руководство по модальности отключено. - guidance_rescale (
float, optional, defaults to 0.0) — Guidance rescale factor proposed by Common Diffusion Noise Schedules and Sample Steps are Flawedguidance_scaleis defined asφin equation 16. of Common Diffusion Noise Schedules and Sample Steps are Flawed. Guidance rescale factor should fix overexposure when using zero terminal SNR. Used for the video modality. - audio_guidance_scale (
float, необязательный, по умолчаниюNone) — Масштаб аудио-гайданса для CFG относительно негативного промпта. Правило обновления CFG одинаково для видео и аудио, но для масштаба гайданса можно использовать разные значения. Авторы LTX-2.X рекомендуют делатьaudio_guidance_scaleвыше по сравнению с видеоguidance_scale(например, для LTX-2.3 они предлагают 3.0 для видео и 7.0 для аудио). ЕслиNone, по умолчанию используется значение для видеоguidance_scale. - audio_stg_scale (
float, необязательный, по умолчаниюNone) — Масштаб аудио-гидинга для STG. Как и в случае с CFG, правило обновления STG в остальном одинаково для видео и аудио. Для LTX-2.3 рекомендуется значение 1.0 как для видео, так и для аудио. ЕслиNone, по умолчанию используется значение для видеоstg_scale. - audio_modality_scale (
float, необязательный, по умолчаниюNone) — Масштаб аудио-гидинга для изоляции модальности в LTX-2.X. Как и в случае с CFG, правило модального гидинга в остальном одинаково для видео и аудио. Для LTX-2.3 рекомендуется значение 3.0 как для видео, так и для аудио. ЕслиNone, по умолчанию используется значение видеоmodality_scale. - audio_guidance_rescale (
float, необязательный, по умолчаниюNone) — Отдельный коэффициент rescale для модальности аудио. ЕслиNone, по умолчанию используется значение видеоguidance_rescale. - spatio_temporal_guidance_blocks (
list[int], необязательный, по умолчаниюNone) — Индексы блоков трансформера (начиная с нуля), на которых применяется STG. Обязательный параметр при использовании STG (еслиstg_scaleилиaudio_stg_scaleбольше0). Для LTX-2.0 рекомендуется значение[29], а для LTX-2.3 —[28]. - noise_scale (
float, необязательный, по умолчаниюNone) — Коэффициент интерполяции между случайным шумом и денойзанными латентами на каждом шаге. Применяет шум кlatentsиaudio_latentsперед продолжением денойзинга. Если не задан, вычисляется из расписания сигм. - num_videos_per_prompt (
int, необязательный, по умолчанию 1) — Количество видео, генерируемых для каждого промпта. - generator (
torch.GeneratorилиList[torch.Generator], необязательный) — Один или список генераторов torch для обеспечения детерминированности генерации. - latents (
torch.Tensor, необязательный) — Предварительно сгенерированные зашумлённые латенты, выбранные из гауссова распределения, которые используются в качестве входных данных для генерации видео. Позволяет корректировать один и тот же процесс генерации с помощью различных промптов. Если не заданы, тензор латентов будет сгенерирован путём выборки с использованием переданного случайногоgenerator. - audio_latents (
torch.Tensor, необязательный) — Предварительно сгенерированные зашумлённые латенты, выбранные из гауссова распределения, которые используются в качестве входных данных для генерации аудио. Можно использовать, чтобы корректировать одну и ту же генерацию с разными промптами. Если не указано, тензор латентов будет сгенерирован путём выборки с использованием переданного случайногоgenerator. - prompt_embeds (
torch.Tensor, необязательный) — Предварительно сгенерированные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, например, для взвешивания промпта. Если не передано, текстовые эмбеддинги будут сгенерированы из входного аргументаprompt. - prompt_attention_mask (
torch.Tensor, необязательный) — Предварительно сгенерированная маска внимания для текстовых эмбеддингов. - negative_prompt_embeds (
torch.FloatTensor, необязательный) — Предварительно сгенерированные эмбеддинги отрицательного текста. Для PixArt-Sigma этот отрицательный промпт должен быть "". Если не предоставлен, negative_prompt_embeds будет сгенерирован из аргументаnegative_prompt. - negative_prompt_attention_mask (
torch.FloatTensor, необязательный) — Предварительно сгенерированная маска внимания для отрицательных текстовых эмбеддингов. - decode_timestep (
float, по умолчанию0.0) — Шаг времени, на котором декодируется сгенерированное видео. - decode_noise_scale (
float, по умолчаниюNone) — Коэффициент интерполяции между случайным шумом и денойзанными латентами на шаге декодирования. - use_cross_timestep (
boolнеобязательный, по умолчаниюTrue) — Определяет, следует ли использовать сигму кросс-модальности (аудио является кросс-модальностью для видео и наоборот) при вычислении параметров модуляции кросс-внимания.Trueсоответствует поведению LTX-2.3/2.5;False— устаревшему поведению LTX-2.0. - system_prompt (
str, необязательный, по умолчаниюNone) — Необязательная системная подсказка для улучшения промпта. Системная подсказка используется улучшителем промпта (модель условной генерации Gemma — выделенный компонентprompt_enhancer, если он настроен, в противном случае основнойtext_encoder) для генерации улучшенного промпта на основе исходногоprompt(и условного изображения, если оно доступно) для управления генерацией. Если значение не указано, а выделенныйprompt_enhancerнастроен (LTX-2.5), по умолчанию используетсяLTX2_5_I2V_DEFAULT_SYSTEM_PROMPT, если доступно условное изображение, в противном случаеLTX2_5_T2V_DEFAULT_SYSTEM_PROMPT— см.enable_prompt_enhancement. - enable_prompt_enhancement (
bool, необязательный, по умолчаниюFalse) — Определяет, следует ли выполнять улучшение промпта. Функция включается явно, в соответствии с эталонными конвейерами Lightricks. ЕслиTrueиsystem_promptне указан, LTX-2.5 выбираетLTX2_5_I2V_DEFAULT_SYSTEM_PROMPT/LTX2_5_T2V_DEFAULT_SYSTEM_PROMPTв зависимости от наличия изображения для условного формирования. - prompt_max_new_tokens (
int, необязательный, по умолчаниюNone) — Максимальное количество новых токенов для генерации при улучшении промпта. Если значение не указано, используется 600 для выделенногоprompt_enhancerGemma 4 (LTX-2.5) или 512 для резервногоtext_encoderGemma 3 (LTX-2.0/2.3). - prompt_enhancement_kwargs (
dict[str, Any], необязательный, по умолчаниюNone) — Параметры для вызова.generateв модуле улучшения промпта. Если не указаны, всегда соответствуют модели, выполняющей улучшение:do_sample=False, no_repeat_ngram_size=5(жадный выбор) при использовании отдельногоprompt_enhancer(LTX-2.5) илиdo_sample=True, temperature=0.7для резервногоtext_encoder(LTX-2.0/2.3). Подробнее см. https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationMixin.generate. - prompt_enhancement_seed (
int, необязательный, по умолчанию10) — Случайный сид для любых операций с генерацией случайных чисел при улучшении промпта. - output_type (
str, необязательный, по умолчанию"pil") — Формат вывода сгенерированного изображения. Выберите один из вариантов: PIL:PIL.Image.Imageилиnp.array. - return_dict (
bool, необязательный, по умолчаниюTrue) — Определяет, следует ли возвращать~pipelines.ltx.LTX2PipelineOutputвместо обычного кортежа. - attention_kwargs (
dict, необязательный) — Словарь kwargs, который при указании передается вAttentionProcessor, определенный вself.processorв diffusers.models.attention_processor. - callback_on_step_end (
Callable, необязательный) — Функция, вызываемая в конце каждого шага денойзинга во время инференса. Функция вызывается со следующими аргументами:callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict).callback_kwargsбудет содержать список всех тензоров, как указано вcallback_on_step_end_tensor_inputs. - callback_on_step_end_tensor_inputs (
List, необязательный) — Список тензорных входных данных для функцииcallback_on_step_end. Тензоры, указанные в списке, будут переданы в качестве аргументаcallback_kwargs. Вы сможете включать только переменные, перечисленные в атрибуте._callback_tensor_inputsвашего класса конвейера. - max_sequence_length (
int, необязательный, по умолчанию1024) — Максимальная длина последовательности, используемая сprompt.
Возвращает
~pipelines.ltx.LTX2PipelineOutput или tuple
Если return_dict равно True, возвращается ~pipelines.ltx.LTX2PipelineOutput, иначе возвращается tuple, где первый элемент — это список с сгенерированными изображениями.
Функция, вызываемая при обращении к конвейеру для генерации.
Примеры:
>>> 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: list[torch.Tensor]condition_strengths: list[float]condition_indices: list[int]latent_height: intlatent_width: int ) → Tuple[torch.Tensor, torch.Tensor, torch.Tensor]
Параметры
- latents (
torch.Tensor) — Начальные упакованные (патчифицированные) латенты формы [batch_size, patch_seq_len, hidden_dim]. - conditioning_mask (
torch.Tensor) — Начальная упакованная (патчифицированная) маска условий формы [batch_size, patch_seq_len, 1] со значениями в диапазоне [0, 1], где 0 означает, что выход модели денуазинга будет использован полностью, а 1 — что условие будет использовано полностью.
Возвращает
Tuple[torch.Tensor, torch.Tensor, torch.Tensor]
Возвращает кортеж из трёх тензоров, где:
- Сжатые латенты видео с применёнными условиями для первого кадра.
- Маска упакованных условий с применёнными значениями силы для первого кадра.
- Чистые условные латенты в позициях первого кадра (в остальных местах — нули).
Примените визуальное условие по первому кадру, перезаписав токены на позициях первого кадра.
Здесь применяются только условия с latent_idx == 0 (в соответствии с VideoConditionByLatentIndex в эталонной реализации). Условия с ненулевыми индексами латентов добавляются как отдельные токены ключевых кадров через prepare_keyframe_extras (в соответствии с VideoConditionByKeyframeIndex) и пропускаются здесь.
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 )
Параметры
- prompt (
strилиlist[str], необязательный) — промпт для кодирования - negative_prompt (
strorlist[str], необязательный) — Промпт или промпты, которые не должны направлять генерацию изображения. Если не задан, необходимо передатьnegative_prompt_embeds. Игнорируется, если не используется направляющее поле (то есть игнорируется, еслиguidance_scaleменьше1). - do_classifier_free_guidance (
bool, необязательный, по умолчаниюTrue) — Использовать ли classifier free guidance. - num_videos_per_prompt (
int, необязательный, по умолчанию 1) — Количество видео, которое должно быть сгенерировано для каждого промпта. Устройство torch, на котором должны размещаться результирующие эмбеддинги - prompt_embeds (
torch.Tensor, необязательный) — Предварительно сгенерированные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, например, для взвешивания промпта. Если не передано, текстовые эмбеддинги будут сгенерированы из входного аргументаprompt. - negative_prompt_embeds (
torch.Tensor, необязательный) — Предварительно сгенерированные отрицательные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, например для взвешивания промпта. Если не передано, negative_prompt_embeds будет сгенерировано из входного аргументаnegative_prompt. - device — (
torch.device, необязательный): устройство torch - dtype — (
torch.dtype, необязательный): torch dtype
Кодирует промпт в скрытые состояния текстового энкодера.
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 )
Улучшает переданный prompt, генерируя новый промпт с помощью модуля улучшения промптов (модель условной генерации Gemma) на основе исходного промпта и системного промпта. Если передан image, модуль улучшения также использует этот кадр в качестве опорного (улучшение в стиле I2V / ключевых кадров). Использует выделенный компонент prompt_enhancer, если он настроен (например, LTX-2.5, текстовый энкодер которого не обучен для улучшения), в противном случае использует основной text_encoder (LTX-2.0/2.3, который выполняет роль собственного модуля улучшения).
Шаблоны сообщений, аргументы декодирования, очистка ответа и подготовка длинной стороны изображения соответствуют 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 )
Подготовьте зашумлённые латенты видео, применив условия по кадрам.
Условия первого кадра (latent_idx == 0) применяются путём перезаписи токенов на позициях первого кадра
(семантика VideoConditionByLatentIndex). Условия, не относящиеся к первому кадру (latent_idx > 0), конкатенируются с
основной латентной последовательностью с использованием conditioning_mask = strength для каждого токена (семантика VideoConditionByKeyframeIndex) — далее их по шагам управляют существующая формула временного шага цикла денойзинга t * (1 - conditioning_mask) и постобработка
смешивания denoised * (1 - conditioning_mask) + clean * conditioning_mask.
Возвращает 4-кортеж:
latents: упакованные зашумлённые латенты (базовые токены + любые токены ключевых кадров, добавленные в размерность последовательности).conditioning_mask: упакованная маска условий со значениями в диапазоне[0, 1]—1в позициях первого кадра,strengthв позициях ключевых кадров,0в остальных.clean_latents: значения чистого условия в позициях с условием (ноль в остальных местах); та же форма, что и уlatents.keyframe_coords:[B, 3, num_keyframe_patches, 2]координаты позиций, которые добавляются кvideo_coords, илиNone, если нет условий, отличных от первого кадра.
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]]
Параметры
- conditions (
LTX2VideoConditionилиList[LTX2VideoCondition], необязательный, по умолчаниюNone) — Список экземпляров условий изображения/видео. - height (
int, необязательный, по умолчанию512) — Требуемая высота в пикселях. - width (
int, необязательный, по умолчанию768) — Требуемая ширина в пикселях. - num_frames (
int, необязательный, по умолчанию121) — Требуемое количество кадров в генерируемом видео. - device (
torch.device, необязательный, по умолчаниюNone) — Устройство, на котором размещаются тензоры предобработанного изображения/видео.
Возвращает
Tuple[List[torch.Tensor], List[float], List[int], List[int]]
Возвращает 4-кортеж списков длины len(conditions) в следующем виде:
- Первый список — это список предобработанных тензоров видео с формой [batch_size=1, num_channels, num_frames, height, width].
- Второй список — это список сил обусловливания.
- Третий список — это список индексов пространства латентов для каждого условия.
- Четвёртый список — это список (обрезанных) количеств кадров в пиксельном пространстве для каждого условия. Это необходимо для семантики координат ключевых кадров (ключевые кадры с одним пиксельным кадром имеют ограниченное временное расширение).
Предварительно обрабатывает изображения/видео условий в тензоры torch.
trim_conditioning_sequence
< source >( start_frame: intsequence_num_frames: inttarget_num_frames: int ) → int
Обрежьте последовательность условий до допустимого количества кадров.
LTX2DFRPipeline
класс 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 )
Параметры
- scheduler (FlowMatchEulerDiscreteScheduler) —
планировщик, используемый в связке с
transformerдля удаления шума из закодированных латентов видео. - vae (AutoencoderKLLTX2Video) — Модель вариационного автоэнкодера (VAE) для кодирования и декодирования видео в латентные представления и обратно.
- audio_vae (AutoencoderKLLTX2Audio) — аудио-VAE для кодирования и декодирования аудиоспектрограмм.
- text_encoder (
Gemma3ForConditionalGenerationилиGemma4UnifiedForConditionalGeneration) — Модель текстового кодировщика. - tokenizer (
GemmaTokenizerилиGemmaTokenizerFast) — токенизатор для текстового энкодера. - connectors (
LTX2TextConnectors) — Стек текстовых коннекторов, используемый для адаптации скрытых состояний текстового энкодера для видео- и аудиоветвей. - transformer (LTX2VideoTransformer3DModel) — Условная архитектура Transformer для удаления шума из закодированных латентов видео.
- vocoder (
LTX2VocoderилиLTX2VocoderWithBWE) — Vocoder для преобразования мел-спектрограмм в аудиосигналы. - processor (
ProcessorMixin, необязательный) — Процессор, используемый для улучшения промптов и шаблонизации чата. - prompt_enhancer (
Gemma4ForConditionalGeneration, необязательный) — Специализированная модель для улучшения промптов (LTX-2.5). - duration_head (
LTX2DurationHead, необязательный) — Предсказываетnum_framesиз эмбеддингов промпта, еслиnum_framesне передан.
Пайплайн для одного прохода шумоподавления Diffusion Fidelity Rendering (DFR) с LTX-2.5.
Один проход генерирует видео и дополнительные слоты для ключевых кадров с одним пикселем, либо повторно выполняет денойзинг переданных латентов, инициализированных из этих слотов. Вызывающая сторона комбинирует этапы: данный пайплайн с половинным разрешением, LTX2LatentUpsamplePipeline для пространственного апскейлинга, затем снова данный пайплайн с полным разрешением, используя апскейленные слоты и эталон IC-LoRA, после чего LTX2DFRTemporalRefinePipeline для каждого раунда временной детализации. См. документацию LTX-2 для рецепта 1080p.
Позиции слотов определяются сегментной сеткой, выровненной по временной границе VAE (resolve_canvas). Канвас дополняется до целого числа сегментов; output_type="latent" возвращает эту дополненную сетку, чтобы слот на дополнении не был отброшен. Перед декодированием VAE обрежьте канвас с помощью trim_canvas.
Требуется трансформер, в конфигурации которого задан use_keyframes_abs_pos_embedding (LTX-2.5 и новее), при generate_slots=True.
Ссылка: 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[float] = [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[str] = ['latents']max_sequence_length: int = 1024 ) → LTX2DFRPipelineOutput or tuple
Параметры
- prompt (
strилиList[str], необязательный) — Промпт или промпты для управления генерацией видео. Если не задан, необходимо передатьprompt_embeds. - conditions (
LTX2VideoConditionилиList[LTX2VideoCondition], необязательный) — Условия на уровне кадров в виде изображений или видео.index— это латентный индекс дляnum_framesтекущего прохода. - height (
int, необязательный, по умолчанию704) — Высота в пикселях данного прохода, а не итогового составленного результата. - width (
int, необязательный, по умолчанию1216) — Ширина этого прохода в пикселях. - num_frames (
int, необязательный) — Количество кадров в пикселях для этого прохода, до внутреннего выравнивания холста. Если не указано, длительность предсказывается из запроса с помощьюduration_head. Должно удовлетворять условию(num_frames - 1) % 8 == 0. - frame_rate (
float, необязательный, по умолчанию24.0) — Частота кадров (fps) воспроизведения для этого прохода. Если значение превышает 30, время RoPE округляется до 60. - min_seconds (
float, необязательный, по умолчанию1.0) — Нижняя граница автоматически предсказанной длительности, еслиnum_framesне указан. - max_seconds (
float, необязательный, по умолчанию20.0) — Верхняя граница автоматически предсказанной длительности, еслиnum_framesне указан. - latents (
torch.Tensor, необязательный) — Сырые видео-латенты размера(batch_size, channels, frames, height, width)для повторного удаления шума (этап 2 / эпилог). - audio_latents (
torch.Tensor, необязательный) — Сырые распакованные аудио-латенты формы(batch_size, channels, length, mel_bins). На этапе 2 по-прежнему выполняется совместный проход по аудио; при этом передаваемая волновая форма составленного рецепта соответствует этапу 1, и именно её сохраняет вызывающая сторона. - keyframes_latents (
torch.Tensor, необязательный) — Сырые начальные значения слотов формы(batch_size, channels, num_slots, height, width), используются приgenerate_slots=True. - keyframe_positions (
list[int], необязательный) — Индексы кадров в пикселях для сгенерированных слотов. По умолчаниюresolve_canvas(num_frames). - reference_latents (
torch.Tensor, необязательный) — Сырое видео-ссылка IC-LoRA (обычно кадры из этапа 1). - reference_downscale_factor (
int, необязательный, по умолчанию2) — Коэффициент между этим проходом и эталонным разрешением, используется для масштабирования координат эталонных токенов. - guidance_keyframe_latents (
torch.Tensor, необязательный) — Сырые закреплённые ключевые кадры guidance(batch_size, channels, K, height, width)— путь эпилога. Не сгенерированные слоты. - guidance_keyframe_positions (
list[int], необязательный) — Индексы кадров в пикселях дляguidance_keyframe_latents. - guidance_keyframe_strength (
float, необязательный, по умолчанию1.0) — Сила обусловливания для зафиксированных ключевых кадров управления. - generate_slots (
bool, необязательный, по умолчаниюTrue) — Добавляет сгенерированные токены ключевых кадров-слотов. В эпилоге это значение устанавливается вFalse, а вместо этого фиксируютсяguidance_keyframe_latents. - sigmas (
list[float], необязательный) — Шумовое расписание для этого прохода, без конечного0.0. - noise_scale (
float, необязательный) — Уровень шума, с которого начинаются токены без условий. По умолчаниюsigmas[0]. - freeze_audio (
bool, необязательный, по умолчаниюFalse) — Закрепить аудио на сигме 0 (эпилог / при следовании за замороженной волновой формой первого этапа). - video_tiles (
list[LTX2DFREpilogueTile], необязательный) — Плиточная обработка эпилога изepilogue_tiles(), благодаря чему разрешение, слишком большое для одного прохода, всё равно позволяет обрабатывать единое полотно: на каждом шаге трансформатор выполняется один раз на каждую плитку, а предсказания смешиваются. Преобразуется в план токенов относительно собственных координат RoPE данного прохода, именно поэтому передаётся раскладка, а не план — координаты существуют только после выполнения prepare_latents(). - num_videos_per_prompt (
int, необязательный, по умолчанию 1) — Количество видео, генерируемых для каждого промпта. - generator (
torch.Generatorилиlist[torch.Generator], необязательный) — Генератор(ы) случайных чисел для воспроизводимости. - prompt_embeds (
torch.Tensor, необязательный) — Предварительно сгенерированные текстовые эмбеддинги. - prompt_attention_mask (
torch.Tensor, необязательный) — Предварительно сгенерированная маска внимания для текстовых эмбеддингов. - decode_timestep (
float, по умолчанию0.0) — Шаг времени, на котором декодируется сгенерированное видео. - decode_noise_scale (
float, по умолчаниюNone) — Масштаб шума при декодировании. - use_cross_timestep (
bool, необязательный, по умолчаниюTrue) — Использовать ли сигму кросс-модальности для модуляции кросс-внимания.Trueдля LTX-2.3+. - system_prompt (
str, необязательный) — Необязательный системный промпт для улучшения промпта. См.enable_prompt_enhancement. - enable_prompt_enhancement (
bool, необязательный, по умолчаниюFalse) — Указывает, следует ли выполнять улучшение промпта. - prompt_max_new_tokens (
int, необязательный) — Максимальное количество новых токенов для генерации при выполнении улучшения промпта. - prompt_enhancement_kwargs (
dict[str, Any], необязательный) — Параметры с ключами для вызова.generateмодуля улучшения промпта. - prompt_enhancement_seed (
int, необязательный, по умолчанию10) — Случайный сид для любых операций с генерацией случайных чисел при улучшении промпта. - output_type (
str, необязательный, по умолчанию"pil") — Формат вывода. Выберите"pil","np","pt"или"latent". Вывод в латентном пространстве представляет собой необрезанный холст. - return_dict (
bool, необязательный, по умолчаниюTrue) — Определяет, возвращать ли LTX2DFRPipelineOutput или обычный кортеж(frames, audio, keyframes, keyframe_positions). - attention_kwargs (
dict, необязательный) — Дополнительные аргументы, передаваемые в процессор внимания. - callback_on_step_end (
Callable, необязательный) — Функция, вызываемая в конце каждого шага денойзинга. - callback_on_step_end_tensor_inputs (
List, необязательный, по умолчанию["latents"]) — Тензорные входные данные для функции обратного вызова. - max_sequence_length (
int, необязательный, по умолчанию1024) — Максимальная длина последовательности для текстового запроса.
Возвращает
LTX2DFRPipelineOutput или tuple
Если return_dict равно True, возвращается LTX2DFRPipelineOutput, иначе возвращается tuple вида (video, audio, keyframes, keyframe_positions).
Функция, вызываемая при обращении к конвейеру для генерации.
Один проход шумоподавления при размере height × width. Собирайте этапы в вызывающем коде: этот пайплайн в половинном разрешении, пространственное увеличение, снова этот пайплайн с latents / keyframes_latents / reference_latents, затем LTX2DFRTemporalRefinePipeline для каждого временного раунда.
Примеры:
>>> 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: list[float]frame_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 )
Параметры
- sigmas (
list[float]) — Шумовое расписание для этого прохода, без конечного значения0.0. - freeze_audio (
bool, optional, defaults toFalse) — Holdaudio_latentsclean (timestep/sigma 0, no audio Euler step) while still running audio-to-video cross-attention. Ignored whenaudio_latentsisNone. - video_tile_plan (
list, необязательный) — План токенов для каждой плитки изvideo_tile_plan[~diffusers.pipelines.ltx2.dfr_layout.video_tile_plan]. Если указан, на каждом шаге трансформатор выполняется один раз для каждой плитки, а предсказания смешиваются, поэтому сэмплер по-прежнему делает шаг по одному полному холсту, и плитки согласуются в своих пересечениях на каждом шаге. - generator (
torch.Generator, optional) — Передаётся вLTXEulerAncestralRFScheduler.step(). Временные тайлы передают отдельный seed для каждого тайла, чтобы анцестральные выборки не использовали общий поток и не затрагивали состояние, которое читает начальное шумовое воздействие следующего тайла. Distilled Euler не обращается к этому параметру. - step_offset (
int) — Индекс первого шага данного прохода в общем расписании конвейера, используется дляcallback_on_step_endи общей строки прогресса.
Выполните один проход шумоподавления DFR по sigmas и верните (latents, audio_latents), оба по-прежнему упакованные.
Дистиллированный расписание используется без classifier-free guidance, поэтому на каждом шаге выполняется один вызов трансформера.
Каждый проход запускает оба потока, поскольку ветви видео требуются кросс-модальные внимание даже там, где создаваемый ею звук отбрасывается. freeze_audio=True удерживает звуковой поток на сигме 0 (без шага Эйлера), чтобы видео всё ещё могло обращаться к нему через кросс-внимание — временные refine-плитки и эпилог используют это, чтобы следовать речи первого этапа, не перепрогоняя для каждой плитки отдельную реализацию звука.
После смешивания условия x0 скорость равна (latents - denoised) / sigma, поэтому шаг RF x0 = x - σ v восстанавливает смешанный denoised. Этапы 1 / 2 / эпилог используют FlowMatchEulerDiscreteScheduler и выполняют этот шаг Эйлера без изменений. Temporal refine подменяет его на LTXEulerAncestralRFScheduler (eta=0.5); этот шаг добавляет шум каждому токену, поэтому после него необходимо снова применить смешивание условия, иначе якоря шва со strength 0.95 будут разрушаться.
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 )
Предобработка и кодирование условий кадров с помощью VAE, позиционированных по пиксельным кадрам.
Возвращает (pixel_frame_index, latent, strength, num_pixel_frames) для каждого условия, готовое для condition_latents в prepare_latents(). Кодирование отделено от размещения, поскольку раунды временного уточнения масштабируют позицию условия на 2 ** round и пересчитывают её для каждой плитки, и не должны повторно кодировать один и тот же статичный кадр для каждой плитки.
Возвращаемый индекс относится к собственной пиксельной сетке num_frames; перенос его на уточненный холст — задача вызывающего кода.
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 )
Параметры
- prompt (
strилиlist[str], необязательный) — промпт для кодирования - num_videos_per_prompt (
int, необязательный, по умолчанию 1) — Количество видео, которое должно быть сгенерировано для каждого промпта. - prompt_embeds (
torch.Tensor, необязательный) — Предварительно сгенерированные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, например, для взвешивания промпта. Если не передано, текстовые эмбеддинги будут сгенерированы из входного аргументаprompt. - prompt_attention_mask (
torch.Tensor, необязательный) — Предварительно сгенерированная маска внимания дляprompt_embeds. - device — (
torch.device, необязательный): устройство torch - dtype — (
torch.dtype, необязательный): torch dtype
Кодирует промпт в скрытые состояния текстового энкодера.
DFR использует дистиллированное расписание сигмы, которое обучено для работы без классификаторного свободного руководства, поэтому здесь нет отрицательной ветви.
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 )
Улучшает переданный prompt, генерируя новый промпт с помощью модуля улучшения промптов (модель условной генерации Gemma) на основе исходного промпта и системного промпта. Если передан image, модуль улучшения также использует этот кадр в качестве опорного (улучшение в стиле I2V / ключевых кадров). Использует выделенный компонент prompt_enhancer, если он настроен (например, LTX-2.5, текстовый энкодер которого не обучен для улучшения), в противном случае использует основной text_encoder (LTX-2.0/2.3, который выполняет роль собственного модуля улучшения).
Шаблоны сообщений, аргументы декодирования, очистка ответа и подготовка длинной стороны изображения соответствуют 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]
Параметры
- conditions (
list[LTX2VideoCondition], необязательный) — Условия на уровне кадров (изображения/видео), позиционируемые по индексу латента. - condition_latents (
list[tuple[int, torch.Tensor, float, int]], необязательный) — Уже закодированная замена дляconditionsв виде(pixel_frame_index, latent, strength, num_pixel_frames). Используется индекс пикселя, а не латента, потому что раунд временного уточнения масштабирует позицию условия множителем2 ** round, и результат, как правило, не совпадает с границей латента — только добавленный ключевой кадр может находиться в этой позиции, и он размещается по пикселю.pixel_frame_index == 0по-прежнему означает «заменить первый кадр». - keyframe_latents (
list[tuple[int, torch.Tensor, float]], необязательный) — Уже закодированные ключевые кадры в виде(pixel_frame_index, latent, strength), гдеlatentимеет форму(batch_size, num_channels_latents, 1, latent_height, latent_width). Используется в раундах временной детализации для фиксации ключевых кадров на стыках, переданных из предыдущего раунда. - slot_frame_indices (
list[int], необязательный) — Позиции кадров в пикселях для сгенерированных ключевых слотов. - slot_initial_latents (
torch.Tensor, необязательный) — содержимое формы(batch_size, num_channels_latents, len(slot_frame_indices), latent_height, latent_width), записываемое в токены слота до добавления шума. - reference_latents (
torch.Tensor, необязательный) —(batch_size, num_channels_latents, F, H, W)Скрытое представление (latent) для IC-LoRA. - reference_downscale_factor (
int, по умолчанию1) — Коэффициент между целевым и эталонным разрешением. - latents (
torch.Tensor, необязательный) —(batch_size, num_channels_latents, F, H, W)начальное содержимое для базовых токенов. Публичные пайплайны передают сырые (денормализованные) латенты; на этой границе передавайтеlatents_normalized=False. Циклы по тайлам, которые уже находятся в пространстве нормализации VAE, оставляют значение по умолчанию. - latents_normalized (
bool, по умолчаниюTrue) — Указывает, являются лиlatents,slot_initial_latents,reference_latentsиkeyframe_latentsуже нормализованными с помощью VAE. Внутренние циклы по тайлам передаютTrue; каждый вызов__call__пайплайна передаётFalse. - noise_scale (
float, по умолчанию1.0) — Уровень шума, с которым инициализируются токены без условий, то есть первое значение сигмы в расписании.
Возвращает
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 индексирует токены слотов сгенерированных ключевых кадров в упакованной последовательности, либо None, если слоты не запрашивались.
Подготовьте зашумленные упакованные латенты видео для одного прохода шумоподавления DFR.
Упакованная последовательность размещается в формате [base | keyframes | slots | reference]:
- Базовые токены покрывают целевую латентную сетку, инициализируясь из
latents, если они предоставлены. - Условия кадров с
index == 0задают чистую цель на позициях первого кадра; те, у которыхindex > 0, и все элементыkeyframe_latentsдобавляются как дополнительные токены ключевых кадров с маской условного сигнала на каждый токен, равной их силе. slot_frame_indicesдобавляет по одному набору токенов ключевых кадров, сгенерированных для одного латентного кадра, на каждую позицию, с маской условия0(полностью денойзится) и временным диапазоном RoPE, равным ровно одному пиксельному кадру. Это слоты ключевых кадров, которые обеспечивают DFR дополнительные кадры;slot_initial_latentsзадаёт их начальное содержимое.reference_latentsдобавляет латентное представление полурезолюции первого этапа в качестве полностью чистого эталона IC-LoRA, при этом пространственные координаты масштабируются коэффициентомreference_downscale_factor, чтобы соответствовать целевому пространству координат.
Токены добавляемого условия несут своё содержимое в clean_latents и нулевой плейсхолдер в latents, тогда как слоты ключевых кадров несут своё зерно в latents и нули в clean_latents — возвращаемые latents представляют собой зашумлённую смесь обоих (см. шаг добавления шума в конце этого метода).
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]]
Параметры
- conditions (
LTX2VideoConditionилиList[LTX2VideoCondition], необязательный, по умолчаниюNone) — Список экземпляров условий изображения/видео. - height (
int, необязательный, по умолчанию512) — Требуемая высота в пикселях. - width (
int, необязательный, по умолчанию768) — Требуемая ширина в пикселях. - num_frames (
int, необязательный, по умолчанию121) — Требуемое количество кадров в генерируемом видео. - device (
torch.device, необязательный, по умолчаниюNone) — Устройство, на котором размещаются тензоры предобработанного изображения/видео.
Возвращает
Tuple[List[torch.Tensor], List[float], List[int], List[int]]
Возвращает 4-кортеж списков длины len(conditions) в следующем виде:
- Первый список — это список предобработанных тензоров видео с формой [batch_size=1, num_channels, num_frames, height, width].
- Второй список — это список сил обусловливания.
- Третий список — это список индексов пространства латентов для каждого условия.
- Четвёртый список — это список (обрезанных) количеств кадров в пиксельном пространстве для каждого условия. Это необходимо для семантики координат ключевых кадров (ключевые кадры с одним пиксельным кадром имеют ограниченное временное расширение).
Предварительно обрабатывает изображения/видео условий в тензоры torch.
rebuild_epilogue_keyframes
< source >( keyframe_latents: Tensordecode_timestep: floatdecode_noise_scale: floatseed: intdevice: devicedtype: dtype ) → torch.Tensor
Параметры
- keyframe_latents (
torch.Tensor) — Сырые(batch_size, C, K, H, W)ключевые кадры, в том виде, в каком их вернул предыдущий проход. - seed (
int) — Базовый seed; плоскостьiдекодируется поseed + 4000 + i, поэтому пиксели плоскости не зависят от того, сколько плоскостей было декодировано до неё.
Возвращает
torch.Tensor
Сырые латенты (batch_size, C, K, 2H, 2W), готовые к передаче обратно в качестве
guidance_keyframe_latents.
Перекодировать ключевые кадры с переносом с удвоенным разрешением через RGB.
Это кадры, которые раунды уточнения уже обработали, поэтому эпилог получает их, а не генерирует. Декодирование в пиксели, масштабирование в 2 раза с помощью Lanczos и повторное кодирование сохраняют кадр, выстраивая его на выходной сетке, что позволяет эпилогу зафиксировать его полностью чистым.
Каждая плоскость декодируется как отдельный однокадровый клип. VAE является каузальным, поэтому при стековом декодировании соседние плоскости «проникали» бы друг в друга — это независимые статичные кадры, а не последовательность.
trim_conditioning_sequence
< source >( start_frame: intsequence_num_frames: inttarget_num_frames: int ) → int
Обрежьте последовательность условий до допустимого количества кадров.
LTX2DFRTemporalRefinePipeline
класс 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 )
Параметры
- scheduler (
LTXEulerAncestralRFScheduler) — Анцестральный планировщик Euler в параметризации rectified-flow. Создайте сeta=0.5, чтобы соответствовать временному рецепту DFR. - vae (AutoencoderKLLTX2Video) — Модель вариационного автоэнкодера (VAE) для кодирования и декодирования видео в латентные представления и обратно.
- audio_vae (AutoencoderKLLTX2Audio) — аудио-VAE для кодирования и декодирования аудиоспектрограмм.
- text_encoder (
Gemma3ForConditionalGenerationилиGemma4UnifiedForConditionalGeneration) — Модель текстового кодировщика. - tokenizer (
GemmaTokenizerилиGemmaTokenizerFast) — токенизатор для текстового энкодера. - connectors (
LTX2TextConnectors) — Стек текстовых коннекторов, используемый для адаптации скрытых состояний текстового энкодера для видео- и аудиоветвей. - transformer (LTX2VideoTransformer3DModel) — Условная архитектура Transformer для удаления шума из закодированных латентов видео.
- vocoder (
LTX2VocoderилиLTX2VocoderWithBWE) — Vocoder для преобразования мел-спектрограмм в аудиосигналы. - temporal_latent_upsampler (
LTX2LatentUpsamplerModel) — временной x2 latent-апсэмплер, применяемый в начале раунда.
Один раунд уточнения временного DFR: интерполяция холста x2 во времени, тайлинг на швах ключевых кадров, денойзинг каждого тайла с использованием предкового шума, склейка путём отбрасывания лид-ин части более позднего тайла и объединение меша ключевых кадров переноса.
Планировщик — LTXEulerAncestralRFScheduler (по умолчанию eta=0.5). Этапы 1 / 2 / пространственный эпилог остаются на FlowMatchEulerDiscreteScheduler через LTX2DFRPipeline. Вызывайте этот пайплайн один раз за раунд; вызывающая сторона выполняет цикл для 2x / 4x.
Входящие latents / keyframes_latents / audio_latents являются сырыми (ненормализованными), что соответствует LTX2Pipeline. keyframe_positions должны быть позициями, возвращёнными на предыдущем проходе — их невозможно повторно вывести из исходного num_frames после выполнения раунда.
__call__
< source >( prompt: str | list[str] = Nonelatents: Tensor = Nonekeyframes_latents: Tensor = Nonekeyframe_positions: list[int] = 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[float] = [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[str] = ['latents']max_sequence_length: int = 1024 ) → LTX2DFRPipelineOutput or tuple
Параметры
- prompt (
strилиList[str], необязательный) — Промпт или промпты для управления генерацией видео. Если не задан, необходимо передатьprompt_embeds. - latents (
torch.Tensor) — Сырые латенты видео для входного холста,(batch_size, channels, frames, height, width). - keyframes_latents (
torch.Tensor) — Сырые ключевые кадры переноса(batch_size, channels, K, height, width)из предыдущего прохода. - keyframe_positions (
list[int]) — Индексы пиксельных кадровkeyframes_latentsна входном холсте. - audio_latents (
torch.Tensor) — Замороженный аудио-поток первой стадии, распакованный и денормализованный. Каждой плитке передаётся срез, покрывающий её окно воспроизведения; возвращаемый аудио-поток представляет собой именно эту форму волны, а не результат повторного шумоподавления для каждой плитки. - conditions (
LTX2VideoConditionилиList[LTX2VideoCondition], необязательный) — Условия на уровне кадров, индексируемые поcondition_num_frames(исходный запрос). На каждом раунде пиксельная позиция условия масштабируется на2 ** round_index. - height (
int, необязательный, по умолчанию704) — Высота в пикселях для этого прохода (такая же, как у входящего видео). - width (
int, необязательный, по умолчанию1216) — Ширина в пикселях для этого прохода. - num_frames (
int, необязательный, по умолчанию121) — Количество пиксельных кадров на входном холсте (без обрезки). - frame_rate (
float, необязательный, по умолчанию24.0) — Частота кадров (fps) при воспроизведении входных данных. Округление удваивает её. - source_seconds (
float, необязательный) — Длительность замороженного аудио первого этапа. По умолчанию равноnum_frames / frame_rate, что верно для первого раунда; в последующих раундах необходимо передавать исходную длительность первого этапа, чтобы плитки не смещались. - condition_num_frames (
int, необязательный) — Исходное значениеnum_frames, использованное для кодированияconditions. По умолчанию равноnum_frames. После дополнения или предыдущего раунда передавайте исходный запрос, чтобыindex=-1не переходил в дополненный хвост. - round_index (
int, необязательный, по умолчанию1) — номер раунда, начиная с 1. Плитки формируют исходный шум какseed + 1000 * round_index + tile, а условия масштабируются множителем2 ** round_index. - sigmas (
list[float], необязательный) — Сжатый график для тайлов текущего раунда, без конечного0.0. - noise_scale (
float, необязательный) — Уровень шума, с которого начинаются токены без условий. По умолчаниюsigmas[0]. - generator (
torch.Generatorилиlist[torch.Generator], необязательный) — Генератор(ы) случайных чисел для воспроизводимости. Выборки по методу предков используют отдельный сид для каждой плитки, производный отinitial_seed()этого генератора. - prompt_embeds (
torch.Tensor, необязательный) — Предварительно сгенерированные текстовые эмбеддинги. - prompt_attention_mask (
torch.Tensor, необязательный) — Предварительно сгенерированная маска внимания для текстовых эмбеддингов. - decode_timestep (
float, по умолчанию0.0) — Шаг времени, на котором декодируется сгенерированное видео. - decode_noise_scale (
float, по умолчаниюNone) — Масштаб шума при декодировании. - use_cross_timestep (
bool, необязательный, по умолчаниюTrue) — Использовать ли сигму кросс-модальности для модуляции кросс-внимания.Trueдля LTX-2.3+. - output_type (
str, необязательный, по умолчанию"pil") — Формат вывода. Выберите"pil","np","pt"или"latent". Вывод в латентном пространстве представляет собой необрезанный холст. - return_dict (
bool, необязательный, по умолчаниюTrue) — Определяет, возвращать ли LTX2DFRPipelineOutput или обычный кортеж(frames, audio, keyframes, keyframe_positions). - attention_kwargs (
dict, необязательный) — Дополнительные аргументы, передаваемые в процессор внимания. - callback_on_step_end (
Callable, необязательный) — Функция, вызываемая в конце каждого шага денойзинга для каждой плитки. - callback_on_step_end_tensor_inputs (
List, необязательный, по умолчанию["latents"]) — Тензорные входные данные для функции обратного вызова. - max_sequence_length (
int, необязательный, по умолчанию1024) — Максимальная длина последовательности для текстового запроса.
Возвращает
LTX2DFRPipelineOutput или tuple
Если return_dict равно True, возвращается LTX2DFRPipelineOutput, иначе возвращается tuple вида (video, audio, keyframes, keyframe_positions).
Выполнить один раунд временной детализации.
Примеры:
>>> 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: list[float]frame_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 )
Параметры
- sigmas (
list[float]) — Шумовое расписание для этого прохода, без конечного значения0.0. - freeze_audio (
bool, optional, defaults toFalse) — Holdaudio_latentsclean (timestep/sigma 0, no audio Euler step) while still running audio-to-video cross-attention. Ignored whenaudio_latentsisNone. - video_tile_plan (
list, необязательный) — План токенов для каждой плитки изvideo_tile_plan[~diffusers.pipelines.ltx2.dfr_layout.video_tile_plan]. Если указан, на каждом шаге трансформатор выполняется один раз для каждой плитки, а предсказания смешиваются, поэтому сэмплер по-прежнему делает шаг по одному полному холсту, и плитки согласуются в своих пересечениях на каждом шаге. - generator (
torch.Generator, optional) — Передаётся вLTXEulerAncestralRFScheduler.step(). Временные тайлы передают отдельный seed для каждого тайла, чтобы анцестральные выборки не использовали общий поток и не затрагивали состояние, которое читает начальное шумовое воздействие следующего тайла. Distilled Euler не обращается к этому параметру. - step_offset (
int) — Индекс первого шага данного прохода в общем расписании конвейера, используется дляcallback_on_step_endи общей строки прогресса.
Выполните один проход шумоподавления DFR по sigmas и верните (latents, audio_latents), оба по-прежнему упакованные.
Дистиллированный расписание используется без classifier-free guidance, поэтому на каждом шаге выполняется один вызов трансформера.
Каждый проход запускает оба потока, поскольку ветви видео требуются кросс-модальные внимание даже там, где создаваемый ею звук отбрасывается. freeze_audio=True удерживает звуковой поток на сигме 0 (без шага Эйлера), чтобы видео всё ещё могло обращаться к нему через кросс-внимание — временные refine-плитки и эпилог используют это, чтобы следовать речи первого этапа, не перепрогоняя для каждой плитки отдельную реализацию звука.
После смешивания условия x0 скорость равна (latents - denoised) / sigma, поэтому шаг RF x0 = x - σ v восстанавливает смешанный denoised. Этапы 1 / 2 / эпилог используют FlowMatchEulerDiscreteScheduler и выполняют этот шаг Эйлера без изменений. Temporal refine подменяет его на LTXEulerAncestralRFScheduler (eta=0.5); этот шаг добавляет шум каждому токену, поэтому после него необходимо снова применить смешивание условия, иначе якоря шва со strength 0.95 будут разрушаться.
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 )
Предобработка и кодирование условий кадров с помощью VAE, позиционированных по пиксельным кадрам.
Возвращает (pixel_frame_index, latent, strength, num_pixel_frames) для каждого условия, готовое для condition_latents в prepare_latents(). Кодирование отделено от размещения, поскольку раунды временного уточнения масштабируют позицию условия на 2 ** round и пересчитывают её для каждой плитки, и не должны повторно кодировать один и тот же статичный кадр для каждой плитки.
Возвращаемый индекс относится к собственной пиксельной сетке num_frames; перенос его на уточненный холст — задача вызывающего кода.
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 )
Параметры
- prompt (
strилиlist[str], необязательный) — промпт для кодирования - num_videos_per_prompt (
int, необязательный, по умолчанию 1) — Количество видео, которое должно быть сгенерировано для каждого промпта. - prompt_embeds (
torch.Tensor, необязательный) — Предварительно сгенерированные текстовые эмбеддинги. Можно использовать для простой настройки текстовых входных данных, например, для взвешивания промпта. Если не передано, текстовые эмбеддинги будут сгенерированы из входного аргументаprompt. - prompt_attention_mask (
torch.Tensor, необязательный) — Предварительно сгенерированная маска внимания дляprompt_embeds. - device — (
torch.device, необязательный): устройство torch - dtype — (
torch.dtype, необязательный): torch dtype
Кодирует промпт в скрытые состояния текстового энкодера.
DFR использует дистиллированное расписание сигмы, которое обучено для работы без классификаторного свободного руководства, поэтому здесь нет отрицательной ветви.
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]
Параметры
- conditions (
list[LTX2VideoCondition], необязательный) — Условия на уровне кадров (изображения/видео), позиционируемые по индексу латента. - condition_latents (
list[tuple[int, torch.Tensor, float, int]], необязательный) — Уже закодированная замена дляconditionsв виде(pixel_frame_index, latent, strength, num_pixel_frames). Используется индекс пикселя, а не латента, потому что раунд временного уточнения масштабирует позицию условия множителем2 ** round, и результат, как правило, не совпадает с границей латента — только добавленный ключевой кадр может находиться в этой позиции, и он размещается по пикселю.pixel_frame_index == 0по-прежнему означает «заменить первый кадр». - keyframe_latents (
list[tuple[int, torch.Tensor, float]], необязательный) — Уже закодированные ключевые кадры в виде(pixel_frame_index, latent, strength), гдеlatentимеет форму(batch_size, num_channels_latents, 1, latent_height, latent_width). Используется в раундах временной детализации для фиксации ключевых кадров на стыках, переданных из предыдущего раунда. - slot_frame_indices (
list[int], необязательный) — Позиции кадров в пикселях для сгенерированных ключевых слотов. - slot_initial_latents (
torch.Tensor, необязательный) — содержимое формы(batch_size, num_channels_latents, len(slot_frame_indices), latent_height, latent_width), записываемое в токены слота до добавления шума. - reference_latents (
torch.Tensor, необязательный) —(batch_size, num_channels_latents, F, H, W)Скрытое представление (latent) для IC-LoRA. - reference_downscale_factor (
int, по умолчанию1) — Коэффициент между целевым и эталонным разрешением. - latents (
torch.Tensor, необязательный) —(batch_size, num_channels_latents, F, H, W)начальное содержимое для базовых токенов. Публичные пайплайны передают сырые (денормализованные) латенты; на этой границе передавайтеlatents_normalized=False. Циклы по тайлам, которые уже находятся в пространстве нормализации VAE, оставляют значение по умолчанию. - latents_normalized (
bool, по умолчаниюTrue) — Указывает, являются лиlatents,slot_initial_latents,reference_latentsиkeyframe_latentsуже нормализованными с помощью VAE. Внутренние циклы по тайлам передаютTrue; каждый вызов__call__пайплайна передаётFalse. - noise_scale (
float, по умолчанию1.0) — Уровень шума, с которым инициализируются токены без условий, то есть первое значение сигмы в расписании.
Возвращает
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 индексирует токены слотов сгенерированных ключевых кадров в упакованной последовательности, либо None, если слоты не запрашивались.
Подготовьте зашумленные упакованные латенты видео для одного прохода шумоподавления DFR.
Упакованная последовательность размещается в формате [base | keyframes | slots | reference]:
- Базовые токены покрывают целевую латентную сетку, инициализируясь из
latents, если они предоставлены. - Условия кадров с
index == 0задают чистую цель на позициях первого кадра; те, у которыхindex > 0, и все элементыkeyframe_latentsдобавляются как дополнительные токены ключевых кадров с маской условного сигнала на каждый токен, равной их силе. slot_frame_indicesдобавляет по одному набору токенов ключевых кадров, сгенерированных для одного латентного кадра, на каждую позицию, с маской условия0(полностью денойзится) и временным диапазоном RoPE, равным ровно одному пиксельному кадру. Это слоты ключевых кадров, которые обеспечивают DFR дополнительные кадры;slot_initial_latentsзадаёт их начальное содержимое.reference_latentsдобавляет латентное представление полурезолюции первого этапа в качестве полностью чистого эталона IC-LoRA, при этом пространственные координаты масштабируются коэффициентомreference_downscale_factor, чтобы соответствовать целевому пространству координат.
Токены добавляемого условия несут своё содержимое в clean_latents и нулевой плейсхолдер в latents, тогда как слоты ключевых кадров несут своё зерно в latents и нули в clean_latents — возвращаемые latents представляют собой зашумлённую смесь обоих (см. шаг добавления шума в конце этого метода).
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]]
Параметры
- conditions (
LTX2VideoConditionилиList[LTX2VideoCondition], необязательный, по умолчаниюNone) — Список экземпляров условий изображения/видео. - height (
int, необязательный, по умолчанию512) — Требуемая высота в пикселях. - width (
int, необязательный, по умолчанию768) — Требуемая ширина в пикселях. - num_frames (
int, необязательный, по умолчанию121) — Требуемое количество кадров в генерируемом видео. - device (
torch.device, необязательный, по умолчаниюNone) — Устройство, на котором размещаются тензоры предобработанного изображения/видео.
Возвращает
Tuple[List[torch.Tensor], List[float], List[int], List[int]]
Возвращает 4-кортеж списков длины len(conditions) в следующем виде:
- Первый список — это список предобработанных тензоров видео с формой [batch_size=1, num_channels, num_frames, height, width].
- Второй список — это список сил обусловливания.
- Третий список — это список индексов пространства латентов для каждого условия.
- Четвёртый список — это список (обрезанных) количеств кадров в пиксельном пространстве для каждого условия. Это необходимо для семантики координат ключевых кадров (ключевые кадры с одним пиксельным кадром имеют ограниченное временное расширение).
Предварительно обрабатывает изображения/видео условий в тензоры torch.
trim_conditioning_sequence
< source >( start_frame: intsequence_num_frames: inttarget_num_frames: int ) → int
Обрежьте последовательность условий до допустимого количества кадров.
Запустите upsampler на нормализованных латентах, выполнив обратное преобразование в исходное латентное пространство VAE, как того требует модель.
LTX2DFRPipelineOutput
класс diffusers.LTX2DFRPipelineOutput
< source >( frames: Tensoraudio: Tensorkeyframes: typing.Optional[torch.Tensor] = Nonekeyframe_positions: list[int] | None = None )
Параметры
- frames (
torch.Tensor,np.ndarrayили list[list[PIL.Image.Image]]) — Видео после шумоподавления. Латентный вывод представляет собой необрезанный холст, форма(batch_size, num_channels, latent_frames, latent_height, latent_width). - audio (
torch.Tensor,np.ndarray) — Сопроводительные аудио-латенты или волновая форма. - keyframes (
torch.Tensor, необязательный) — Сгенерированные или переданные ключевые кадры в латентном пространстве формы(batch_size, num_channels, num_keyframes, latent_height, latent_width).None, еслиoutput_type != "latent", или если проход не создал слоты (например, в случае тайловой эпилоги). - keyframe_positions (
list[int], необязательный) — Индекс пиксельного кадра каждого ключевого кадра на холсте данного прохода;None, еслиkeyframesравноNone. После временного раунда их невозможно повторно вывести из исходногоnum_frames, и их необходимо передать на следующий этап.
Класс вывода для конвейеров DFR.
LTX2LatentUpsamplePipeline
класс 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
Параметры
- video (
list[PipelineImageInput], необязательный) — Видео, подлежащее апскейлингу (например, вывод первого этапа LTX 2.0). Если не указано, следует передатьlatents. - height (
int, необязательный, по умолчанию512) — Высота входного видео в пикселях (не сгенерированного видео, которое будет иметь более высокое разрешение). - width (
int, необязательный, по умолчанию768) — Ширина входного видео в пикселях (не сгенерированного видео, которое будет иметь более высокое разрешение). - num_frames (
int, необязательный, по умолчанию121) — Количество кадров во входном видео. - spatial_patch_size (
int, необязательный, по умолчанию1) — Пространственный размер патча для латентов видео. Используется, если переданыlatentsи требуется распаковка. - temporal_patch_size (
int, необязательный, по умолчанию1) — Размер временного патча для латентов видео. Используется, если переданыlatentsи требуется распаковка. - latents (
torch.Tensor, необязательный) — Предварительно сгенерированные латенты видео. Этот параметр можно передать вместо аргументаvideo. Может представлять собой последовательность патчей формы(batch_size, seq_len, hidden_dim)или латентное представление видео формы(batch_size, latent_channels, latent_frames, latent_height, latent_width). - latents_normalized (
bool, необязательный, по умолчаниюFalse) — Если переданыlatents, указывает, нормализованы лиlatentsс использованием среднего значения и стандартного отклонения латентного пространства VAE. ЕслиTrue,latentsбудут денормализованы перед передачей в латентный апсемплер. - decode_timestep (
float, по умолчанию0.0) — Шаг времени, на котором декодируется сгенерированное видео. - decode_noise_scale (
float, по умолчаниюNone) — Коэффициент интерполяции между случайным шумом и денойзанными латентами на шаге декодирования. - adain_factor (
float, необязательный, по умолчанию0.0) — Коэффициент смешивания адаптивной нормализации экземпляра (AdaIN) между увеличенными и исходными латентами. Должен находиться в диапазоне [-10.0, 10.0]; значение 0.0 (по умолчанию) означает, что AdaIN не выполняется. - tone_map_compression_ratio (
float, необязательный, по умолчанию0.0) — Сила сжатия при тонмаппинге, которая уменьшает динамический диапазон значений латентов. Это полезно для регуляризации латентов с высокой дисперсией или для управления выходными данными во время генерации. Должно находиться в диапазоне [0, 1], где 0.0 (значение по умолчанию) означает, что тонмаппинг не применяется, а 1.0 соответствует полному эффекту сжатия. - generator (
torch.Generatorилиlist[torch.Generator], необязательный) — Один или список генераторов torch для обеспечения детерминированности генерации. - output_type (
str, необязательный, по умолчанию"pil") — Формат вывода сгенерированного изображения. Выберите один из вариантов: PIL:PIL.Image.Imageилиnp.array. - return_dict (
bool, необязательный, по умолчаниюTrue) — Определяет, следует ли возвращать~pipelines.ltx.LTXPipelineOutputвместо обычного кортежа.
Возвращает
~pipelines.ltx.LTXPipelineOutput или tuple
Если return_dict равно True, возвращается ~pipelines.ltx.LTXPipelineOutput, иначе возвращается tuple, где первый элемент — это видео с увеличенным разрешением.
Функция, вызываемая при обращении к конвейеру для генерации.
Примеры:
>>> 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
Параметры
- latents (
torch.Tensor) — Входные латенты для нормализации - reference_latents (
torch.Tensor) — Справочные латенты, задающие стилистические статистики. - factor (
float) — Коэффициент смешения исходного и преобразованного латентного представления. Диапазон: от -10.0 до 10.0, значение по умолчанию: 1.0
Возвращает
torch.Tensor
Трансформированный латентный тензор
Применяет адаптивную нормализацию экземпляров (AdaIN) к тензору латентных представлений на основе статистики из опорного тензора латентных представлений.
tone_map_latents
< source >( latents: Tensorcompression: float )
Применяет нелинейную функцию тонального отображения к латентным значениям, чтобы сжать их динамический диапазон с помощью сигмоидного сжатия, обеспечивая воспринимаемую плавность.
Это полезно для регуляризации латентов с высокой дисперсией или для управления выходными данными во время генерации, особенно при контроле динамического поведения с помощью коэффициента compression.
LTX2VideoDiffusionDecodePipeline
класс diffusers.LTX2VideoDiffusionDecodePipeline
< source >( diffusion_decoder: LTX2VideoDiffusionDecoderModelschedulervae: AutoencoderKLLTX2Video = None )
Параметры
- diffusion_decoder (LTX2VideoDiffusionDecoderModel) — Диффузионный видео-декодер.
- scheduler (FlowMatchEulerDiscreteScheduler) — планировщик, управляющий шагами денойзинга декодера.
- vae (AutoencoderKLLTX2Video, optional) — Используется только для получения латентных статистик, применяемых при денормализации. Если параметр не указан, конвейер переключается на значения по умолчанию для LTX-2, поэтому в сценарии, где выполняется только декодирование, не требуется загружать второй автоэнкодер.
Декодирование латентов видео LTX-2 с помощью диффузионного декодера, представленного в LTX-2.5.
В отличие от свёрточного декодера, этот сам является небольшой диффузионной моделью: он снимает шум с пикселей, используя в качестве условия контекстный объём, построенный из латентов, поэтому ему необходимы планировщик и генератор. Используйте его в паре с любым пайплайном LTX-2, запущенным с output_type="latent", передавая denormalize=False, так как на этом пути статистика латентов уже была применена.
__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
Параметры
- latents (
torch.Tensor) — Латенты формы(B, C, F, H, W). Обратите внимание, что запуск конвейера LTX-2 с параметромoutput_type="latent"возвращает латенты, которые уже денормализованы, поэтому для них передавайтеdenormalize=False. - generator (
torch.Generator, необязательный) — Декодер генерирует шум, который затем очищает, поэтому передайте генератор, чтобы сделать декодирование воспроизводимым. - output_type (
str, необязательный, по умолчанию"pil") — Формат вывода декодированного видео. Выберите один из вариантов:"pil","np","pt"или"latent". - return_dict (
bool, необязательный, по умолчаниюTrue) — Определяет, следует ли возвращать объектLTX2VideoDecodeOutputвместо обычного кортежа. - denormalize (
bool, необязательный, по умолчаниюTrue) — Следует ли применять статистику латентов перед декодированием. УстановитеFalse, если латенты уже денормализованы.
Возвращает
LTX2VideoDecodeOutput или tuple
LTX2DurationHead
класс 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 )
Параметры
- video_cross_attention_dim (
int, по умолчанию4096) — Ширина выходного слоя видеоконнектора. - audio_cross_attention_dim (
int, по умолчанию2048) — Ширина вывода аудио-коннектора. - pooler_hidden_dim (
int, по умолчанию256) — Общее скрытое измерение, в которое проецируются обе модальности. - num_queries (
int, по умолчанию1) — Количество обучаемых запросов для пулинга. - num_pooler_heads (
int, по умолчанию4) — Головки внимания, используемые пулером. - mlp_hidden_dim (
int, по умолчанию256) — Ширина скрытого слоя выходного MLP. Имя содержит суффикс_dim, чтобы избежать конфликта с подмодулемmlp_hidden, который в противном случае был бы затенён этим значением конфигурации черезConfigMixin.__getattr__.
Предсказывает естественную длительность кадра, подразумеваемую подписью, на основе выходов текстового коннектора LTX-2.
Head не зависит от модальности: передавайте выход коннектора видео, аудио или оба. Специфичные для модальности проекции входных данных отображают каждый поток в общее пространство пулера, обучаемые эмбеддинги модальности помечают потоки, чтобы пулер мог их различать, а небольшой MLP преобразует пулированный вектор в лог-длительность. Целевая переменная регрессии обучается в лог-секундах, поэтому forward выполняет экспоненту, и вызывающий код всегда получает значение в секундах.
Доступно начиная с контрольных точек LTX-2.5.
forward
< source >( video_tokens: typing.Optional[torch.Tensor] = Noneaudio_tokens: typing.Optional[torch.Tensor] = None ) → torch.Tensor of shape (batch_size,)
Параметры
- video_tokens (
torch.Tensorформы(batch_size, seq_len, video_cross_attention_dim), необязательный) — Выход видеоконнектора. - audio_tokens (
torch.Tensorформы(batch_size, seq_len, audio_cross_attention_dim), необязательный) — Выход аудио-коннектора.
Возвращает
torch.Tensor формы (batch_size,)
предсказанная длительность в секундах.
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
Параметры
- video_tokens (
torch.Tensor, необязательный) — Выход видеоконнектора для одного запроса. - audio_tokens (
torch.Tensor, необязательный) — Выход аудио-коннектора для одного запроса. - frame_rate (
float) — Количество кадров в секунду, используемое для преобразования прогнозируемой длительности в число кадров. - temporal_compression_ratio (
int) — Временное сжатие VAE, определяющее сетку кадров. - min_seconds (
float, по умолчанию1.0) — Нижняя граница предсказания. - max_seconds (
float, по умолчанию20.0) — Верхняя граница для предсказания.
Возвращает
int
количество кадров, соответствующее временной сетке VAE.
Предсказывает количество кадров по токенам коннектора, ограничивает значение диапазоном [min_seconds, max_seconds] и выравнивает по причинной временной сетке VAE (k * temporal_compression_ratio + 1).
Ограничение (clamp) применяется до привязки: количество кадров после ограничения не обязательно совпадает с сеткой, поэтому предварительная привязка дала бы иной результат. Поскольку привязка округляет вниз, результат может оказаться ниже минимального значения; в этом случае он округляется вверх до следующей точки сетки, чтобы количество кадров оставалось в пределах допустимых значений.
Узкие границы могут привести к окну кадров, не содержащему ни одной точки сетки: при 24 кадрах в секунде [1.0s, 1.02s] округляется до [24, 24], а 24 не является 8k + 1. В этом случае используется ближайшая точка сетки и записывается предупреждение, поскольку превышение менее чем на один шаг сетки предпочтительнее отказа от генерации. Поэтому возвращаемое количество кадров всегда соответствует сетке, но в данной ситуации может оказаться чуть за пределами запрошенных границ.
LTX2PipelineOutput
класс diffusers.pipelines.ltx2.LTX2PipelineOutput
< source >( frames: Tensoraudio: Tensor )
Параметры
- frames (
torch.Tensor,np.ndarrayили list[list[PIL.Image.Image]]) — Список видеовыходов. Может представлять собой вложенный список длиныbatch_size,где каждый подсписок содержит последовательности денойзированных изображений PIL длиныnum_frames.Также может быть массивом NumPy или тензором Torch с формой(batch_size, num_frames, channels, height, width). - audio (
torch.Tensor,np.ndarray) — TODO
Класс вывода для конвейеров LTX.
LTX2ModularPipeline
класс 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 )
Модульный ModularPipeline для LTX-2 (совместная генерация видео и аудио).
LTX2AutoBlocks
Auto-блоки для LTX-2, поддерживающие генерацию видео из текста, видео из изображения, видео по условию и в контексте (IC-LoRA) (совместная генерация видео и аудио).
Поддерживаемые рабочие процессы:
text2video: требуетсяpromptimage2video: требуетсяimage,promptcondition: требуетconditions,promptin_context: требуетreference_conditions,num_frames,prompt
Компоненты:
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)
Входные данные:
prompt (str, необязательный):
Промпт или промпты для управления генерацией изображения.
conditions (list, необязательный): LTX2VideoCondition (или список таких объектов), задающий условия изображения/видео для латентных кадров сгенерированного видео.
enable_prompt_enhancement (bool, необязательный, по умолчанию False):
Запускать ли улучшитель промпта. Опционально, в соответствии с эталонными пайплайнами Lightricks.
system_prompt (str, необязательный):
Системный промпт для улучшения. По умолчанию LTX2_5_I2V_DEFAULT_SYSTEM_PROMPT, если доступно условие кадра PIL.Image.Image, иначе LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT.
prompt_max_new_tokens (int, необязательный):
Максимальное количество новых токенов для генерации при улучшении промпта. По умолчанию 600, бюджет улучшителя LTX-2.5 Gemma-4.
prompt_enhancement_kwargs (dict, необязательный):
Именованные аргументы для вызова .generate улучшителя. По умолчанию используется жадное декодирование.
prompt_enhancement_seed (int, необязательный, по умолчанию 10):
Случайный сид для улучшения промпта (не влияет при жадном декодировании LTX-2.5).
generator (Generator, необязательный):
Генератор Torch для детерминированной генерации.
image (Image | list, необязательный):
Референсное изображение(я) для денойзинга. Может быть одним изображением или списком изображений.
negative_prompt (str, необязательный):
Промпт или промпты, которые не должны направлять генерацию изображения.
max_sequence_length (int, необязательный, по умолчанию 1024):
Максимальная длина последовательности для кодирования промпта.
min_seconds (float, необязательный, по умолчанию 1.0):
Нижняя граница для автоматически предсказанной длительности.
max_seconds (float, необязательный, по умолчанию 20.0):
Верхняя граница для автоматически предсказанной длительности. Должно быть строго больше min_seconds.
frame_rate (float, необязательный, по умолчанию 24.0):
Количество кадров в секунду сгенерированного видео.
height (int, необязательный, по умолчанию 512):
Высота сгенерированного изображения в пикселях.
width (int, необязательный, по умолчанию 704):
Ширина сгенерированного изображения в пикселях.
image_crf (int, необязательный):
CRF H.264, используемый для перекодирования условного image перед кодированием VAE, чтобы соответствовать сжатию, на котором обучалась модель. None (по умолчанию) определяется из генерации текстового кодировщика (33 для LTX-2.3 и ниже, 18 для LTX-2.5). Передайте 0, чтобы пропустить перекодирование. Требует PIL.Image.Image, если выполняется перекодирование.
num_frames (int, необязательный):
Количество кадров в сгенерированном видео. Если не указано, длительность предсказывается автоматически через duration_head (см. LTX2AutoDurationStep).
reference_conditions (list, необязательный): LTX2ReferenceCondition (или список таких объектов), видео которых кодируются в дополнительные латентные токены, на которые обращает внимание адаптер IC-LoRA.
reference_downscale_factor (int, необязательный, по умолчанию 1):
Соотношение между целевым и референсным разрешениями; 2 означает, что референс предобрабатывается с половинным целевым разрешением. Пространственные координаты масштабируются этим коэффициентом, чтобы референсные токены попадали в целевое координатное пространство. Должно соответствовать коэффициенту, с которым обучался IC-LoRA.
conditioning_attention_strength (float, необязательный, по умолчанию 1.0):
Скаляр в диапазоне [0, 1], управляющий силой внимания между шумовыми и референсными токенами. 1.0 (по умолчанию) оставляет внимание без маски.
conditioning_attention_mask (Tensor, необязательный):
Необязательная маска в пиксельном пространстве формы (1, 1, F, H, W) со значениями в [0, 1], задающая пространственно изменяющуюся силу внимания. Уменьшается до латентной сетки референса и умножается на conditioning_attention_strength.
motion_speed (float, необязательный, по умолчанию 1.0):
Скорость движения относительно реального времени. Позиционные эмбеддинги обусловлены frame_rate / motion_speed, поэтому значения меньше 1 замедляют движение, например 0.2 для 5-кратного замедления LoRA Slow-Motion-Control. frame_rate остается частотой воспроизведения.
num_videos_per_prompt (int, необязательный, по умолчанию 1):
Количество изображений для генерации на один промпт.
condition_latents (list, необязательный):
Нормализованные латенты VAE для каждого условия формы [1, C, F, H, W].
condition_strengths (list, необязательный):
Силы обусловливания для каждого условия.
condition_indices (list, необязательный):
Индекс латентного кадра для каждого условия, на котором применяется условие.
condition_pixel_frames (list, необязательный):
Количество обрезанных пиксельных кадров для каждого условия, используемое для ограничения координат одиночных ключевых кадров.
reference_latents (Tensor, необязательный):
Упакованные референсные токены формы [1, total_reference_tokens, C] или None, если референсные условия не были предоставлены (LTX2AutoReferenceEncoderStep пропускается).
reference_coords (Tensor, необязательный):
Координаты RoPE для референсных токенов.
reference_token_counts (list, необязательный):
Количество токенов для каждого референса, в порядке reference_conditions.
latents (Tensor):
Предварительно сгенерированные шумовые латенты для генерации изображения.
noise_scale (float, необязательный):
Начальный уровень шума для необусловленных токенов. None (по умолчанию) разрешается в sigmas[0], если предоставлены пользовательские sigmas, иначе 1.0.
sigmas (list, необязательный):
Пользовательские сигмы для процесса денойзинга.
reference_cross_mask (Tensor, необязательный):
Силы внимания шумовые<->референсные для каждого референсного токена формы [1, num_ref_tokens].
num_inference_steps (int):
Количество шагов денойзинга.
timesteps (Tensor):
Шаги времени для процесса денойзинга.
audio_latents (Tensor):
Необязательные предварительно закодированные аудио-латенты; если не предоставлены, используется случайный шум.
*denoiser_input_fields (None,необязательный):
условные входные данные модели для денойзера: например, prompt_embeds, negative_prompt_embeds и т.д.
use_cross_timestep (bool,необязательный, по умолчанию True):
Обусловливать ли трансформер отдельным кросс-шагом времени для каждого токена (LTX-2.3+).
attention_kwargs (dict,необязательный):
Дополнительные именованные аргументы для процессоров внимания.
image_latents (Tensor,необязательный):
Латенты референсного изображения, закодированные VAE, используемые для обусловливания image-to-video.
output_type (str,необязательный, по умолчанию pil):
Формат вывода: ‘pil’, ‘np’, ‘pt’.
decode_timestep (None,необязательный, по умолчанию 0.0):
Шаг времени, на котором VAE декодирует финальные латенты.
decode_noise_scale (None,необязательный*):
Коэффициент интерполяции шума, применяемый к латентам на шаге декодирования.
Выводы:
videos (list):
Сгенерированные видео.
audio (Tensor):
Сгенерированная звуковая волна.
LTX25ModularPipeline
класс 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 )
Модульный ModularPipeline для LTX-2.5 (совместная генерация видео и аудио).
Идентичен LTX2ModularPipeline, за исключением того, что его блоки по умолчанию декодируют с помощью диффузионного видео-декодера, который является нативным значением по умолчанию начиная с LTX-2.5. Чекпоинт направляется сюда через modular_model_index.json.
LTX25AutoBlocks
Auto-блоки для LTX-2.5, поддерживающие генерацию видео по тексту, по изображению, по условию и в контексте (IC-LoRA) (совместное видео + аудио). Идентичны LTX2AutoBlocks, за исключением того, что видео-декодер — это LTX2DiffusionVaeDecoderStep, поскольку диффузионный декодер является нативным значением по умолчанию начиная с LTX-2.5. Чтобы декодировать с помощью свёрточного VAE, замените блок декодирования: blocks.sub_blocks["decode"] = LTX2AutoDecoderStep().
Поддерживаемые рабочие процессы:
text2video: требуетсяpromptimage2video: требуетсяimage,promptcondition: требуетconditions,promptin_context: требуетreference_conditions,num_frames,prompt
Компоненты:
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)
Входные данные:
prompt (str, необязательный):
Промпт или промпты для управления генерацией изображения.
conditions (list, необязательный): LTX2VideoCondition (или список таких объектов) для размещения условий изображения/видео на индексах латентных кадров сгенерированного видео.
enable_prompt_enhancement (bool, необязательный, по умолчанию False):
Запускать ли улучшитель промпта. Опционально, в соответствии с эталонными пайплайнами Lightricks.
system_prompt (str, необязательный):
Системный промпт для улучшения. По умолчанию LTX2_5_I2V_DEFAULT_SYSTEM_PROMPT, если доступен кадр условия PIL.Image.Image, иначе LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT.
prompt_max_new_tokens (int, необязательный):
Максимальное количество новых токенов для генерации при улучшении промпта. По умолчанию 600, бюджет улучшителя LTX-2.5 Gemma-4.
prompt_enhancement_kwargs (dict, необязательный):
Именованные аргументы для вызова .generate улучшителя. По умолчанию используется жадное декодирование.
prompt_enhancement_seed (int, необязательный, по умолчанию 10):
Случайный сид для улучшения промпта (не действует при жадном декодировании LTX-2.5).
generator (Generator, необязательный):
Генератор Torch для детерминированной генерации.
image (Image | list, необязательный):
Референсное изображение(я) для денойзинга. Может быть одним изображением или списком изображений.
negative_prompt (str, необязательный):
Промпт или промпты, которые не должны направлять генерацию изображения.
max_sequence_length (int, необязательный, по умолчанию 1024):
Максимальная длина последовательности для кодирования промпта.
min_seconds (float, необязательный, по умолчанию 1.0):
Нижняя граница автоматически предсказанной длительности.
max_seconds (float, необязательный, по умолчанию 20.0):
Верхняя граница автоматически предсказанной длительности. Должно быть строго больше min_seconds.
frame_rate (float, необязательный, по умолчанию 24.0):
Количество кадров в секунду сгенерированного видео.
height (int, необязательный, по умолчанию 512):
Высота сгенерированного изображения в пикселях.
width (int, необязательный, по умолчанию 704):
Ширина сгенерированного изображения в пикселях.
image_crf (int, необязательный):
CRF H.264, используемый для перекодирования условия image перед кодированием VAE, в соответствии со сжатием, на котором обучалась модель. None (по умолчанию) определяется из генерации текстового кодировщика (33 для LTX-2.3 и ниже, 18 для LTX-2.5). Передайте 0, чтобы пропустить перекодирование. Требует PIL.Image.Image, если выполняется перекодирование.
num_frames (int, необязательный):
Количество кадров в сгенерированном видео. Пропустите, чтобы автоматически предсказать через duration_head (см. LTX2AutoDurationStep).
reference_conditions (list, необязательный): LTX2ReferenceCondition (или список таких объектов), видео которых кодируются в дополнительные латентные токены, на которые обращает внимание адаптер IC-LoRA.
reference_downscale_factor (int, необязательный, по умолчанию 1):
Соотношение между целевым и референсным разрешениями; 2 означает, что референс предобрабатывается с половиной целевого разрешения. Пространственные координаты масштабируются этим коэффициентом, чтобы референсные токены попали в целевое координатное пространство. Должно соответствовать коэффициенту, с которым обучался IC-LoRA.
conditioning_attention_strength (float, необязательный, по умолчанию 1.0):
Скаляр в [0, 1], управляющий силой, с которой шумовые токены и референсные токены обращают внимание друг на друга. 1.0 (по умолчанию) оставляет внимание без маски.
conditioning_attention_mask (Tensor, необязательный):
Необязательная маска в пиксельном пространстве формы (1, 1, F, H, W) со значениями в [0, 1], задающая пространственно изменяющуюся силу внимания. Уменьшается до латентной сетки референса и умножается на conditioning_attention_strength.
motion_speed (float, необязательный, по умолчанию 1.0):
Скорость движения относительно реального времени. Позиционные эмбеддинги обусловлены frame_rate / motion_speed, поэтому значения меньше 1 замедляют движение, например 0.2 для 5-кратного замедления LoRA Slow-Motion-Control. frame_rate остается скоростью воспроизведения.
num_videos_per_prompt (int, необязательный, по умолчанию 1):
Количество изображений для генерации на один промпт.
condition_latents (list, необязательный):
Нормализованные латенты VAE для каждого условия формы [1, C, F, H, W].
condition_strengths (list, необязательный):
Силы обусловливания для каждого условия.
condition_indices (list, необязательный):
Индекс латентного кадра для каждого условия, на котором применяется условие.
condition_pixel_frames (list, необязательный):
Обрезанное количество пиксельных кадров для каждого условия, используемое для ограничения координат одиночных ключевых кадров.
reference_latents (Tensor, необязательный):
Упакованные референсные токены формы [1, total_reference_tokens, C] или None, если референсные условия не были предоставлены (LTX2AutoReferenceEncoderStep пропускается).
reference_coords (Tensor, необязательный):
Координаты RoPE для референсных токенов.
reference_token_counts (list, необязательный):
Количество токенов для каждого референса, в порядке reference_conditions.
latents (Tensor):
Предварительно сгенерированные шумовые латенты для генерации изображения.
noise_scale (float, необязательный):
Начальный уровень шума для необусловленных токенов. None (по умолчанию) разрешается в sigmas[0], если предоставлены пользовательские sigmas, иначе 1.0.
sigmas (list, необязательный):
Пользовательские сигмы для процесса денойзинга.
reference_cross_mask (Tensor, необязательный):
Силы внимания шумовые<->референсные для каждого референсного токена формы [1, num_ref_tokens].
num_inference_steps (int):
Количество шагов денойзинга.
timesteps (Tensor):
Шаги времени для процесса денойзинга.
audio_latents (Tensor):
Необязательные предварительно закодированные латенты аудио; если не предоставлены, используется случайный шум.
*denoiser_input_fields (None,необязательный):
условные входные данные модели для денойзера: например, prompt_embeds, negative_prompt_embeds и т.д.
use_cross_timestep (bool,необязательный, по умолчанию True):
Обусловливать ли трансформер отдельным кросс-шагом времени для каждого токена (LTX-2.3+).
attention_kwargs (dict,необязательный):
Дополнительные именованные аргументы для процессоров внимания.
image_latents (Tensor,необязательный):
Латенты референсного изображения, закодированные VAE, используемые для обусловливания image-to-video.
output_type (str,необязательный*, по умолчанию pil):
Формат вывода: ‘pil’, ‘np’, ‘pt’.
Выводы:
videos (list):
Сгенерированные видео.
audio (Tensor):
Сгенерированная звуковая волна.