#
# Apache License, Version 2.0("라이선스")에 따라 라이선스가 부여됩니다.
# 이 파일은 라이선스에 따라만 사용할 수 있습니다.
# 라이선스 사본은 다음에서 가져올 수 있습니다
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# 적용 가능한 법률에 의해 요구되거나 서면으로 합의되지 않는 한, 소프트웨어
# 라이선스에 따라 배포되는 본 소프트웨어는 "있는 그대로"
# 명시적이든 묵시적이든 어떠한 종류의 보증이나 조건도 없이 제공됩니다.
# 권한을 관리하는 특정 언어에 대한 라이선스를 참조하세요
# 라이선스 하의 제한 사항. -->

# LTX-2

  

[LTX-2](https://hf.co/papers/2601.03233)는 DiT 기반의 파운데이션 모델로, 단일 모델 내에서 동기화된 비디오와 오디오를 생성하도록 설계되었습니다. 최신 비디오 생성의 핵심 구성 요소를 통합했으며, 오픈 웨이트를 제공하며 실용적인 로컬 실행에 초점을 맞추고 있습니다.

모든 원본 LTX-Video 체크포인트는 [Lightricks](https://huggingface.co/Lightricks) 조직에서 찾을 수 있습니다.

LTX-2의 원본 코드베이스는 [여기](https://github.com/Lightricks/LTX-2)에서 찾을 수 있습니다.

## 2단계 생성

공유되는 `LTX2Pipeline` / `LTX2ImageToVideoPipeline`의 `__call__` 기본값은 LTX-2.5 레퍼런스와 일치합니다(`num_inference_steps=30`; `duration_head`가 존재하는 경우 `num_frames`는 선택 사항이며, 그렇지 않으면 `121`로 대체됩니다). 아래 예제는 LTX-2.0/2.3에도 동일한 기본값을 사용합니다.

프로덕션 품질의 생성을 달성하기 위한 권장 파이프라인입니다. 이 파이프라인은 두 단계로 구성됩니다:

- Stage 1: classifier-free guidance(CFG)를 사용한 diffusion sampling으로 목표 해상도의 비디오를 생성합니다. 이 단계에서는 텍스트/이미지 조건을 준수하는 일관된 저노이즈 비디오 시퀀스를 생성합니다.
- Stage 2: Stage 1의 출력을 2배로 업샘플링하고, 디스틸된 LoRA 모델을 사용하여 세부 사항을 정제하여 충실도와 시각적 품질을 향상시킵니다. Stage 2에서는 Stage 1의 구조를 유지하면서 텍스처와 선명도를 강화하기 위해 더 가벼운 CFG를 적용할 수 있습니다.

text-to-video 2단계 파이프라인의 사용 예시

```py
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",
)
```

## 디스틸드 체크포인트 생성
디스틸된 체크포인트를 사용하는 가장 빠른 2단계 생성 파이프라인.

```py
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`를 사용하여 임의의 latent 인덱스에서 이미지 및/또는 비디오 조건을 지정할 수 있습니다. 예를 들어, 첫 번째 프레임과 마지막 프레임 조건을 모두 지정하여 first-last-frame-to-video(FLF2V) 생성을 수행할 수 있습니다:

```py
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",
)
```

이미지와 비디오 조건을 모두 사용할 수 있습니다:

```py
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",
)
```

조건부가 잠재 프레임(latent frames)을 통해 수행되므로, 이미지 조건에 대해 지정된 잠재 프레임에 해당하는 8개의 데이터 공간 프레임은 정적인 경향이 있습니다.

## 멀티모달 가이드

LTX-2.X 파이프라인은 멀티모달 가이던스를 지원합니다. 세 가지 항으로 구성되며, 모두 CFG 스타일의 업데이트 규칙을 사용합니다:

1. Classifier-Free Guidance (CFG): 교란된("더 약한") 출력을 negative prompt를 사용하여 생성하는 표준 [CFG](https://huggingface.co/papers/2207.12598)
2. Spatio-Temporal Guidance (STG): [STG](https://huggingface.co/papers/2411.18664)는 self-attention 연산을 단축하여 생성된 교란된 출력에서 벗어나, 대신 attention 값을 대입합니다. 이를 통해 더 선명한 비디오와 더 나은 시공간적 일관성을 만드는 것이 핵심 아이디어입니다.
3. Modality Isolation Guidance: 크로스 모달리티(오디오-비디오 및 비디오-오디오) 크로스 어텐션을 비활성화하여 생성된 교란된 출력에서 벗어나도록 합니다. 이 가이던스는 [LTX-2.X](https://huggingface.co/papers/2601.03233) 모델에 더 구체적으로 적용되며, 이를 통해 생성된 오디오와 비디오 간의 일관성이 향상된다는 아이디어에 기반합니다.

이 값들은 `guidance_scale`, `stg_scale`, `modality_scale` 인자로 제어되며, 비디오와 오디오에 대해 각각 별도로 설정할 수 있습니다. 또한 STG의 경우, self-attention이 건너뛰어지는 transformer 블록 인덱스를 `spatio_temporal_guidance_blocks` 인자를 통해 지정해야 합니다. LTX-2.X 파이프라인은 guidance scale이 높은 값으로 설정될 때 발생할 수 있는 과노출 문제를 완화하기 위해 [guidance rescaling](https://huggingface.co/papers/2305.08891)도 지원합니다.

```py
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 모델은 프롬프트 작성 스타일에 민감합니다. 좋은 프롬프트 작성법에 대한 권장 사항은 [공식 프롬프트 가이드](https://ltx.io/model/model-blog/prompting-guide-for-ltx-2)를 참고하세요. 시스템 프롬프트를 제공하여 파이프라인의 텍스트 인코더(기본적으로 [Gemma 3](https://huggingface.co/google/gemma-3-12b-it-qat-q4_0-unquantized) 모델)를 사용해 제공된 프롬프트를 강화하는 프롬프트 강화(Prompt Enhancement)를 사용하면 샘플 품질을 향상시킬 수도 있습니다. 프롬프트 강화를 사용하려면 선택적 `processor` 파이프라인 구성 요소가 존재해야 합니다. `enable_prompt_enhancement=True`와 `system_prompt`를 설정하여 활성화합니다(선택 사항, Lightricks 레퍼런스 파이프라인과 일치):

```py
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는 LTX-2.3과 동일한 `LTX2Pipeline`/`LTX2VideoTransformer3DModel`/`AutoencoderKLLTX2Video` 등의 클래스를 재사용하며, 이를 위한 별도의 파이프라인 클래스는 없습니다. 사용자가 인지할 수 있는 차이는 텍스트 인코더입니다. LTX-2.5는 Gemma 3 대신 Gemma 4(`gemma4_unified`) 체크포인트와 함께 사용됩니다. 변환된 LTX-2.5 체크포인트에 대해 `from_pretrained`를 호출하면(`transformers`의 `Auto*` 클래스를 통해) 자동으로 로드되므로 추론 시점에 추가 설정이 필요하지 않습니다. LTX-2.3 저장소 대신 LTX-2.5 저장소를 `from_pretrained`에 지정하기만 하면 됩니다.

[`Lightricks/LTX-2.5-Diffusers`](https://huggingface.co/Lightricks/LTX-2.5-Diffusers)에는 두 가지 transformer가 함께 제공됩니다. `model_index.json`가 가리키는 `transformer/`에 있는 **distilled** DiT와, 명시적으로 로드해야 하는 `transformer_full/`에 있는 full/SFT DiT입니다(자세한 내용은 [Full / SFT transformer](#full--sft-transformer) 섹션을 참고하세요). 저장소의 `scheduler/`는 distilled checkpoint에 맞게 구성되어 있으며(`use_dynamic_shifting=False`, `shift_terminal=None`), 제공된 그대로 sigma schedule이 사용되도록 설정되어 있습니다. [two-stage generation](#two-stage-generation-for-ltx-25)에 필요한 모든 것도 함께 제공됩니다: `latent_upsampler/` 하위 폴더와 저장소 루트에 있는 stage 2 distilled LoRA인 `ltx-2.5-22b-distilled-lora-450-bf16.safetensors`입니다.

Distilled inference는 단계 수가 아닌 명시적인 sigma 스케줄에 의해 구동되며, 무가이드로 실행됩니다(`guidance_scale=1.0`이므로 `negative_prompt`는 사용되지 않음). 대신 `num_inference_steps`를 전달하면 모델에 범용 선형 스케줄이 부여되어 품질이 조용히 저하됩니다:

```py
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의 2단계 생성

LTX-2.5는 두 단계 변형을 모두 지원하며, `DISTILLED_SIGMA_VALUES` / `STAGE_2_DISTILLED_SIGMA_VALUES`는 해당 참조 스케줄입니다:

- **양단계 모두에 대한 증류된 체크포인트** — 기본 `transformer/`의 레퍼런스 레시피이며, 아래에 표시된 것입니다. 트랜스포머가 이미 증류되었으므로 2단계 LoRA는 포함되지 않으며, 이는 LTX-2.5 가중치를 사용한 [증류된 체크포인트 생성](#distilled-checkpoint-generation)입니다.
- **Full/SFT stage 1 + distilled LoRA stage 2** — 이 페이지 상단에 설명된 [Two-stages Generation](#two-stages-generation)을 `transformer_full/`와 함께 제공되는 LoRA를 사용하여 수행합니다. 변경되는 내용은 [아래](#stage-2-with-the-distilled-lora)를 참조하세요.

Stage 1은 목표 해상도의 절반에서 실행되고, upsampler가 이를 두 배로 늘리며, stage 2는 전체 해상도에서 정밀도를 높입니다 — 비디오 *및* 오디오 모두 stage 1의 latents에서 `noise_scale=STAGE_2_DISTILLED_SIGMA_VALUES[0]`로 재시드됩니다. Stage 1이 각 축을 절반으로 줄인 후에도 VAE의 공간 그리드에 정확히 맞춰야 하므로, 높이와 너비는 64로 나누어떨어져야 합니다.

```py
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",
)
```

길이가 명시적인 `num_frames`가 아니라 [duration head](#automatic-duration-for-ltx-25)에서来的时候, stage 2가 실행되기 전에 stage 1이 결정하고 그 latents(`[B, C, F, H, W]`)에서 실제 길이를 복원하도록 하세요. 두 번째로 예측하는 대신:

```py
num_frames = (video_latent.shape[2] - 1) * pipe.vae_temporal_compression_ratio + 1
```

#### 증류된 LoRA를 사용한 Stage 2

대신 [Two-stages Generation](#two-stages-generation)를 실행하려면 — 1단계에는 full/SFT DiT, 2단계에는 distilled LoRA를 사용 — [Full / SFT transformer](#full--sft-transformer)와 동일한 방식으로 파이프라인을 구성하고 해당 guidance stack으로 1단계 latents를 생성합니다. 이후 LTX-2.0/2.3과 두 가지가 다릅니다. LoRA는 원래 가중치와 함께 있는 것이 아니라 diffusers 저장소 자체에 위치하며, 스케줄러의 방향이 반대입니다. LTX-2.5는 *distilled* 스케줄러 구성을 제공하므로, 1단계에서 dynamic shifting이 켜지고 2단계에서 다시 꺼집니다.

```py
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
)
```

업샘플링 단계와 stage 2 호출 자체는 위의 distilled 레시피와 동일합니다: `sigmas=STAGE_2_DISTILLED_SIGMA_VALUES`, `noise_scale`, `guidance_scale=1.0`가 모두 같으며, stage 2는 어쨌든 distilled 모델을 실행하기 때문입니다.

### 합성곱 및 확산 디코딩

LTX-2.5는 동일한 잠재 공간(latent space)을 공유하는 두 개의 비디오 디코더를 제공하므로, 잠재 변수(latents)는 두 디코더 간에 상호 교환 가능합니다:

- `vae/` — 합성곱 VAE([AutoencoderKLLTX2Video](/docs/diffusers/main/ko/api/models/autoencoderkl_ltx_2#diffusers.AutoencoderKLLTX2Video)). 파이프라인이 디코딩하는 데 사용하는 모델로, 위 스니펫 모두 이미 이를 사용하고 있습니다. 두 모델 중 타일링(`pipe.vae.enable_tiling()`)을 지원하는 유일한 모델이며, 이는 일반적으로 고해상도를 처리할 수 있게 해 주는 기능입니다.
- `diffusion_decoder/` — [LTX2VideoDiffusionDecoderModel](/docs/diffusers/main/ko/api/models/ltx2_diffusion_decoder#diffusers.LTX2VideoDiffusionDecoderModel). 이는 파이프라인 구성 요소가 아닌 자체적인 diffusion 모델이므로 `vae`로 전달되지 않습니다. `output_type="latent"`로 파이프라인을 실행한 후, latents를 [LTX2VideoDiffusionDecodePipeline](/docs/diffusers/main/ko/api/pipelines/ltx2#diffusers.LTX2VideoDiffusionDecodePipeline)에 전달하세요.

인코딩은 항상 `vae/`를 통해 이루어지므로 이미지 및 비디오 조건화는 선택에 영향을 받지 않습니다.

diffusion decoder로 디코딩할 때 두 가지가 달라집니다. `output_type="latent"`는 vocoder도 건너뛰므로 오디오가 latents로 반환되며 수동으로 마무리해야 하고, NATTEN 프로세서가 비디오 해상도에서 사실상 필수입니다:

```py
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",
)
```

이것을 [2단계 생성](#two-stage-generation-for-ltx-25)과 결합하려면, *2단계*에서 `output_type="latent"`를 요청하고 이를 디코딩하세요.

`decoder.enable_tiling()`은 고해상도 디코딩을 메모리에 유지하는 역할을 하며, 이는 `pipe.vae.enable_tiling()`이 합성곱 VAE에서 수행하는 방식과 동일합니다. 디코딩에서 메모리 사용량이 가장 큰 부분인 마지막 업샘플링 단계와 디퓨전 단계는 오버랩되는 타일 위에서 실행된 후 다시 블렌딩되어 결합되므로, 피크 메모리는 비디오 크기가 아닌 타일 크기로 제한됩니다. Tiling은 latent가 하나의 타일을 초과할 때만 활성화되며, 타일 및 오버랩 크기는 `tile_sample_min_*` / `tile_sample_stride_*` 인수를 통해 조정할 수 있습니다(기본값은 참조 구현과 일치합니다). 디퓨전 단계가 각 타일을 개별적으로 디노이즈하기 때문에, 타일링된 디코딩은 타일링되지 않은 결과와 정확히 동일하지 않습니다.

단일 카드에서는 디코딩 전에 파이프라인을 다른 곳으로 이동하는 것도 가치가 있습니다(`pipe.scheduler`와 보코더의 `output_sampling_rate`를 캡처한 후 `pipe.to("cpu")` 및 `torch.cuda.empty_cache()`를 호출). 디코더는 자체적인 여유 공간이 필요하기 때문입니다. 어텐션 백엔드, 타일링 세부 사항 및 디코더의 나머지 동작에 대해서는 [LTX2VideoDiffusionDecoderModel](/docs/diffusers/main/ko/api/models/ltx2_diffusion_decoder#diffusers.LTX2VideoDiffusionDecoderModel)을 참조하세요.

### Full / SFT transformer

`transformer_full/`은 `model_index.json`에 참조되지 않으므로 명시적으로 로드해야 합니다. 또한 다른 스케줄러와 실제 가이던스 스택이 필요합니다. 포함된 `scheduler/`는 증류된 체크포인트용으로 설정되어 있으며, 가이던스 기본값은 LTX-2.0 시대의 범용 설정으로, 아무런 오류를 발생시키지 않으면서도 LTX-2.5 SFT 실행이 눈에 띄게 가이던스가 부족하게 됩니다. [Multimodal Guidance](#multimodal-guidance) 권장 사항은 여기에도 그대로 적용되며, `28` 블록에 대한 STG를 포함합니다:

```py
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에서는 동일한 텍스트 인코더 체크포인트가 강화기로도 사용되었지만(위 [프롬프트 강화](#prompt-enhancement) 참조), 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=`를 명시적으로 전달하여 오버라이드할 수 있습니다:

```py
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 체크포인트에는 transformer가 조건으로 사용하는 동일한 텍스트 커넥터 출력으로부터 설명된 샷의 길이를 예측하는 작은 `duration_head`가 포함되어 있습니다. 로드된 파이프라인에 이 헤드가 있는 경우, 기본적으로 **`num_frames`가 자동 예측됩니다**. 이 값을 생략하면 모델이 길이를 선택합니다:

```py
video, audio = pipe(prompt=prompt, output_type="np", return_dict=False)
```

길이를 직접 설정하려면 `num_frames`를 명시적으로 전달하세요. 정수는 항상 헤드보다 우선합니다:

```py
video, audio = pipe(prompt=prompt, num_frames=121, output_type="np", return_dict=False)
```

LTX-2.0 또는 LTX-2.3 체크포인트에서 로드된 Pipelines에는 duration head가 없으며 이전 기본값인 121프레임을 유지하므로, 해당 모델에는 변경 사항이 없습니다.

`min_seconds` / `max_seconds`를 전달하여 예측을 제한합니다. 원시 예측 값은 해당 범위로 클램프된 후 프레임으로 변환됩니다:

```py
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`)에 맞춰 정렬되므로, 실제 지속 시간은 양자화됩니다. 24 fps 기준 단계당 약 0.33초이며, 헤드가 프레임이 아닌 초를 예측하기 때문에 `frame_rate`에 따라 달라집니다. `min_seconds`는 `max_seconds`보다 엄격히 작아야 합니다. `num_frames`이 명시적으로 설정된 경우 이 범위는 무시됩니다.

그리드 스텝보다 좁은 범위는 정확히 만족되지 않을 수 있습니다. 24 fps에서 `[1.0s, 1.02s]`은 `[24, 24]` 프레임으로 변환되며, 24는 `8k + 1`이 아닙니다. 가장 가까운 그리드 점이 사용되고 경고가 기록되므로, 반환된 길이가 이러한 좁은 범위를 약간 벗어날 수 있습니다.

비디오를 생성하지 않고 예측을 검사하려면 헤드를 직접 호출하세요. 필요한 모든 것이 공개되어 있습니다:

```py
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 체크포인트를 변환하면 `--full_pipeline`를 사용하면 헤드가 자동으로 선택되거나, `--duration_head`를 단독으로 사용하여 선택할 수 있습니다. 2.5 이전의 체크포인트에는 이러한 가중치가 없으며, 변환 시 해당 구성 요소를 건너뛰고 실패하지 않습니다.

### LTX-2.5의 모션 속도

LTX-2는 모든 비디오 토큰을 초 단위의 시간 축에 배치하며, 이 축은 기본적으로 재생 속도인 `frame_rate`에서 유도됩니다. `motion_speed`(기본값 `1.0`)은 이 두 가지를 분리합니다. 시간 축은 `frame_rate / motion_speed`에 조건부 설정되는 반면, 오디오 길이, [duration head](#automatic-duration-for-ltx-25) 및 반환되는 비디오는 여전히 `frame_rate`를 따릅니다. `frame_rate=24.0`이고 `motion_speed=0.2`인 경우, 모델에는 동작이 120 fps로 촬영되었고 결과가 24 fps로 재생된다고 전달되어 5배 슬로 모션이 생성됩니다.

기본 모델은 대략 24/25/30/60 fps로 학습되므로, `1.0`에서 크게 벗어난 속도는 해당 속도로 학습된 어댑터, 예: [`Lightricks/LTX-2.5-22b-LoRA-Slow-Motion-Control`](https://huggingface.co/Lightricks/LTX-2.5-22b-LoRA-Slow-Motion-Control) (게이트: 먼저 Hub에서 라이선스를 수락해야 함)와 함께 사용할 때만 의미가 있습니다. `motion_speed`가 없으면 해당 LoRA는 일반 LoRA로 로드되어 모션 제어 기능이 전혀 제공되지 않습니다. 모델 카드에서는 LoRA 강도 `1.0`에서 `1.0`, `0.5`, `0.2`, `0.1`, `0.05`, `0.025`의 속도를 권장합니다. 프롬프트에서 속도 관련 단어("slow motion", "high fps")를 제외하고, `motion_speed`만으로 효과가 제어되므로 모든 속도에서 동일한 캡션을 재사용하세요.

```py
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프레임(24fps 기준 약 5초) 길이이며, 움직임의 속도만 달라집니다. [2단계 생성](#two-stage-generation-for-ltx-25)에서는 **두 단계** 모두에 동일한 `motion_speed`를 전달해야 합니다. 2단계는 비디오를 다시 디노이즈하며, 실시간 축에서 실행되면 슬로 모션 효과가 사라집니다. [참조 드라이버](https://huggingface.co/Lightricks/LTX-2.5-22b-LoRA-Slow-Motion-Control/blob/main/distilled_speed_demo.py)는 두 패스가 공유하는 단계 객체를 래핑하여 동일한 동작을 수행합니다.

`motion_speed`는 LTX-2 / LTX-2.5 모듈 블록의 입력이기도 하며, 모듈형 파이프라인에도 동일한 방식으로 전달됩니다.

### LTX-2.5 모듈형

LTX-2.5는 모듈형 파이프라인으로도 사용할 수 있습니다. 기본 블록셋은 diffusion decoder를 사용하며, `num_frames`가 생략된 경우 비디오 길이를 예측합니다. `guider`와 `audio_guider` 구성 요소를 통해 비디오와 오디오에 각각 guidance를 적용합니다. 사용 가능한 guidance 매개변수는 [LTX2Guidance](/docs/diffusers/main/ko/api/modular_diffusers/guiders#diffusers.LTX2Guidance)를 참고하세요. 기본적으로 모듈형 파이프라인은 [google/gemma-4-E2B-it](https://huggingface.co/google/gemma-4-E2B-it) 저장소에서 prompt enhancer와 processor를 다운로드합니다. 아래는 T2V 모듈형 예시입니다:

```py
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 워크플로가 사용됩니다:

```py
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](/docs/diffusers/main/ko/api/pipelines/ltx2#diffusers.LTX2AutoBlocks), [LTX25AutoBlocks](/docs/diffusers/main/ko/api/pipelines/ltx2#diffusers.LTX25AutoBlocks))에서 지원되는 워크플로를 확인할 수 있습니다.

### LTX-2.5용 Diffusion Fidelity Rendering(DFR)

`LTX2DFRPipeline`는 실제 실행 시간을 디테일 충실도로 교환합니다. 각 `__call__`은 `height` × `width` 해상도로 **단일 디노이즈 패스**를 수행합니다. 이 패스는 비디오와 추가 단일 픽셀 프레임 **키프레임 슬롯**을 생성하거나, 해당 슬롯에서 시드된 제공된 레이턴트를 다시 디노이즈합니다. 호출자는 다른 LTX 2단계 파이프라인과 동일한 방식으로 단계를 구성합니다. 즉, 이 파이프라인, [LTX2LatentUpsamplePipeline](/docs/diffusers/main/ko/api/pipelines/ltx2#diffusers.LTX2LatentUpsamplePipeline), 다시 이 파이프라인, 그리고 각 시간 라운드마다 [LTX2DFRTemporalRefinePipeline](/docs/diffusers/main/ko/api/pipelines/ltx2#diffusers.LTX2DFRTemporalRefinePipeline)을 호출합니다.

슬롯은 픽셀 프레임 하나를 얻기 위해 토큰의 완전한 잠재 프레임 하나를 소모하며, 이는 해당 위치의 유효한 시간 압축을 완화합니다. 따라서 주변 비디오는 보간된 프레임이 아닌 실제로 새로운 프레임에 조건부화됩니다. 슬롯 위치는 VAE의 시간 경계(요청을 덜 패딩하는 24 또는 32 픽셀 프레임 중 하나)에 정렬된 세그먼트 그리드에서 가져옵니다. 캔버스는 내부적으로 세그먼트의 정수 배로 패딩되며, `output_type="latent"`는 패딩된 그리드를 반환하여 패딩에 있는 슬롯이 제거되지 않도록 합니다. VAE 디코딩 전에 `trim_canvas`로 트리밍하세요.

`use_keyframes_abs_pos_embedding`를 설정하는 config를 가진 transformer가 필요합니다. 이 설정은 단일 픽셀 프레임의 latents를 학습된 embedding으로 표시합니다. LTX-2.5 체크포인트에는 해당 설정이 포함되어 있으며, 파이프라인은 해석할 수 없는 토큰에 토큰 예산을 소모하기보다 더 오래된 버전에서 예외를 발생시킵니다.

추가 토큰에 대한 예산을 계획하세요: 각 슬롯은 하나의 잠재 프레임 분량만큼을 추가하므로, 2단계는 동등한 2단계 증류 패스보다 더 긴 시퀀스를 실행합니다 — 1024x1536 / 121 프레임에서 +31% (24576 -> 32256 토큰, 24프레임 세그먼트 그리드에서 5개 슬롯). 피크 활성화 메모리는 이에 따라 확장되므로, 일반 증류 레시피에 간신히 맞는 해상도의 경우 DFR 환경에서 `enable_sequential_cpu_offload`, `vae.enable_tiling()`, 또는 더 작은 캔버스가 필요할 수 있습니다.

Composition은 `keyframes`와 `keyframe_positions`에 대해 `return_dict=True`를 사용합니다(`return_dict=False`는 동일한 네 필드를 튜플로 반환합니다).

아래의 전체 레시피는 시작점으로 적합합니다: 1088×1920 이미지-투-비디오, x2 시간적 리파인 라운드 1회, 그리고 2단계에서 x2 공간적 디테일링 IC-LoRA.

```py
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`는 최종 출력이 아니라 **해당 패스**의 값입니다. 1단계는 1080p 캔버스의 절반 크기인 544×960에서, 2단계는 1088×1920에서 실행됩니다. 각 패스의 크기는 VAE의 공간 압축 비율(단일 패스인 경우 LTX-2.5에서 32, 1단계가 1080p의 절반인 경우 64)로 나누어떨어져야 합니다. 이것이 1080p가 **1920×1088**이고 4K가 **3840×2176**인 이유입니다. 각 패스는 고정된 증류 스케줄(`sigmas`)을 실행하므로 `num_inference_steps`가 없습니다. 증류 스케줄은 가이던스 없이 학습되었기 때문에 `negative_prompt`나 `guidance_scale`도 없습니다. 포함된 오디오는 1단계의 것입니다. 이후 패스에서도 비디오 브랜치가 크로스 모달 어텐션을 수행할 수 있도록 오디오 스트림이 실행되지만, 웨이브폼 자체는 1단계 이후에 정제되지 않습니다.

**공간 디테일링.** 2x 공간 디테일링 IC-LoRA를 **1단계 이후**에 이름이 지정된 어댑터로 로드하고, 2단계에서만 활성화합니다(`set_adapters(["detailing"], adapter_weights=[0.5])`). 그러면 2단계는 1단계의 반해상도 latent를 `reference_latents`로 참조합니다. 1단계와 시간적 라운드는 어댑터가 꺼진 상태로 실행됩니다. 1단계 전에 LoRA를 로드한 경우, `transformer.disable_adapters()`로 이를 끄고, `set_adapters`는 이를 **다시** 켜지 않습니다 — 2단계 전에 `transformer.enable_adapters()`를 호출하거나, 레시피와 같이 1단계 후에 가중치를 로드하세요. `reference_downscale_factor`(기본값 `2`)는 참조 토큰의 공간 좌표를 대상의 좌표 공간으로 스케일링합니다.

**시간적 정제.** [LTX2DFRTemporalRefinePipeline](/docs/diffusers/main/ko/api/pipelines/ltx2#diffusers.LTX2DFRTemporalRefinePipeline)는 한 라운드를 수행합니다. 시간적 업샘플링, 키프레임 이음새에서의 타일링, `LTXEulerAncestralRFScheduler`(`eta=0.5`)를 사용한 선조 노이즈 제거, 후속 타일의 리드인을 제거하여 스티칭, 그리고 캐리 키프레임 백을 병합하는 과정입니다. 해당 스케줄러는 직접 구성해야 합니다. 결정적 단계는 완주하여 더 부드러운 캔버스만 반환하기 때문에, 다른 스케줄러를 사용하면 라운드가 거부됩니다. 라운드당 파이프라인을 한 번씩 호출하고, 2배 / 4배를 위해 `round_index`를 전달하며 루프를 실행합니다. 라운드 이후에는 `keyframe_positions`를 원래의 `num_frames`에서 다시 유도할 수 없으므로, 반드시 그대로 전달해야 합니다. 각 타일에는 해당 재생 윈도우를 덮는 동결된 1단계 오디오의 슬라이스가 전달됩니다. `source_seconds`는 *1단계*의 길이이며 라운드 간에 고정되므로, 후속 라운드에서는 기본값을 사용하는 대신 명시적으로 전달해야 합니다.

muxing과 무관하게, 재생이 30을 초과하는 경우 Conditioning fps는 항상 60입니다. RoPE 시간은 `pixel_frame / fps`이므로, 120 fps 시간 기준은 학습된 분포에 비해 모든 토큰의 시간 범위를 절반으로 줄이고, 48 fps는 이를 늘립니다. 두 경우 모두 60이라고 거짓말하고 재생 속도로 디코딩된 프레임을 취급합니다.

**세 번째 공간 단계.** 이를 구성합니다. 네 번째 파이프라인은 없습니다. **비디오만** 공간적으로 업샘플링하고, RGB에서 carry keyframes를 재구성합니다(`decode` → Lanczos ×2 → [rebuild_epilogue_keyframes()](/docs/diffusers/main/ko/api/pipelines/ltx2#diffusers.LTX2DFRPipeline.rebuild_epilogue_keyframes)를 통해 `encode`; epilogue keyframes는 절대 latent-upsample하지 않음), 그리고 다음을 수행합니다:

```py
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()
```

두 축은 서로 다른 방식으로 봉합됩니다. 공간 경계의 어느 쪽에도 알려진 답이 없으므로, 해당 겹침 부분은 사다리꼴 가중치를 사용하여 혼합됩니다. 시간 타일은 마지막 refine 라운드의 keyframe 봉합선을 기준으로 잘립니다.

**Diffusion decoder를 사용한 디코딩.** 최대 수준의 디테일 충실도를 위해 `output_type="latent"`를 유지하고, (이미 정규화 해제되고, 필요 시 `trim_canvas`가 적용된) latents를 [LTX2VideoDiffusionDecodePipeline](/docs/diffusers/main/ko/api/pipelines/ltx2#diffusers.LTX2VideoDiffusionDecodePipeline)에 전달하세요.

```py
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]]

#### diffusers.LTX2Pipeline[[diffusers.LTX2Pipeline]]

```python
diffusers.LTX2Pipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKLLTX2Video, audio_vae: AutoencoderKLLTX2Audio, text_encoder: transformers.models.gemma3.modeling_gemma3.Gemma3ForConditionalGeneration | transformers.models.gemma4_unified.modeling_gemma4_unified.Gemma4UnifiedForConditionalGeneration, tokenizer: GemmaTokenizer, connectors: LTX2TextConnectors, transformer: LTX2VideoTransformer3DModel, vocoder: diffusers.pipelines.ltx2.vocoder.LTX2Vocoder | diffusers.pipelines.ltx2.vocoder.LTX2VocoderWithBWE, processor: transformers.processing_utils.ProcessorMixin | None = None, prompt_enhancer: transformers.models.gemma4.modeling_gemma4.Gemma4ForConditionalGeneration | None = None, duration_head: diffusers.pipelines.ltx2.duration_head.LTX2DurationHead | None = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2.py#L209)

**매개변수:**

transformer ([LTXVideoTransformer3DModel](/docs/diffusers/main/ko/api/models/ltx_video_transformer3d#diffusers.LTXVideoTransformer3DModel)) : 인코딩된 비디오 잠재 변수를 디노이즈하기 위한 조건부 Transformer 아키텍처.

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/ko/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : `transformer`와 함께 사용하여 인코딩된 이미지 라텐트를 디노이즈하는 데 사용되는 스케줄러입니다.

vae ([AutoencoderKLLTXVideo](/docs/diffusers/main/ko/api/models/autoencoderkl_ltx_video#diffusers.AutoencoderKLLTXVideo)) : 잠재 표현으로 이미지를 인코딩 및 디코딩하는 Variational Auto-Encoder (VAE) 모델.

text_encoder (`T5EncoderModel`) : [T5](https://huggingface.co/docs/transformers/en/model_doc/t5#transformers.T5EncoderModel), 구체적으로 [google/t5-v1_1-xxl](https://huggingface.co/google/t5-v1_1-xxl) 변형입니다.

tokenizer (`CLIPTokenizer`) : [CLIPTokenizer](https://huggingface.co/docs/transformers/en/model_doc/clip#transformers.CLIPTokenizer) 클래스의 토크나이저.

tokenizer (`T5TokenizerFast`) : [T5TokenizerFast](https://huggingface.co/docs/transformers/en/model_doc/t5#transformers.T5TokenizerFast) 클래스의 두 번째 Tokenizer.

connectors (`LTX2TextConnectors`) : 비디오 및 오디오 브랜치를 위해 텍스트 인코더의 히든 상태를 적응시키기 위해 사용되는 텍스트 커넥터 스택입니다.

텍스트-투-비디오 생성을 위한 Pipeline입니다.

Reference: https://github.com/Lightricks/LTX-Video

#### __호출__[[diffusers.LTX2Pipeline.__call__]]

```python
__call__(prompt: str | list[str] = None, negative_prompt: str | list[str] | None = None, height: int = 512, width: int = 768, num_frames: int | None = None, min_seconds: float = 1.0, max_seconds: float = 20.0, frame_rate: float = 24.0, motion_speed: float = 1.0, num_inference_steps: int = 30, sigmas: list[float] | None = None, timesteps: list = None, guidance_scale: float = 3.0, stg_scale: float = 1.0, modality_scale: float = 3.0, guidance_rescale: float = 0.7, audio_guidance_scale: float | None = 7.0, audio_stg_scale: float | None = 1.0, audio_modality_scale: float | None = 3.0, audio_guidance_rescale: float | None = 0.7, spatio_temporal_guidance_blocks: list[int] | None = [28], noise_scale: float = 0.0, num_videos_per_prompt: int = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, audio_latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, decode_timestep: float | list[float] = 0.0, decode_noise_scale: float | list[float] | None = None, use_cross_timestep: bool = True, system_prompt: str | None = None, enable_prompt_enhancement: bool = False, prompt_max_new_tokens: int | None = None, prompt_enhancement_kwargs: dict[str, typing.Any] | None = None, prompt_enhancement_seed: int = 10, output_type: str = 'pil', return_dict: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list = ['latents'], max_sequence_length: int = 1024)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2.py#L929)

**매개변수:**

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의 인과적 시간 그리드에 맞춰 정렬되므로, 실제 길이는 양자화됩니다(24 fps 기준 약 0.33초).

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보다 작은 값은 동작을 늦춥니다. 예를 들어 Slow-Motion-Control LoRA의 5배 슬로 모션에는 `0.2`를 사용합니다. `frame_rate`는 재생 속도로 유지되며, 오디오 길이와 예측된 프레임 수는 이에 따라 결정됩니다.

num_inference_steps (`int`, *선택 사항*, 기본값 30) : 디노이징 단계의 수입니다. 디노이징 단계가 많을수록 일반적으로 추론 속도가 느려지는 대신 더 높은 품질의 이미지를 생성합니다.

sigmas (`List[float]`, *선택 사항*) : `set_timesteps` 메서드에서 `sigmas` 인자를 지원하는 스케줄러의 노이즈 제거 과정에 사용할 커스텀 시그마입니다. 정의되지 않은 경우, `num_inference_steps`가 전달될 때의 기본 동작이 사용됩니다.

timesteps (`list[int]`, *선택 사항*) : `set_timesteps` 메서드에 `timesteps` 인수를 지원하는 스케줄러의 노이즈 제거 과정에 사용할 커스텀 타임스텝입니다. 정의되지 않은 경우, `num_inference_steps`가 전달될 때의 기본 동작이 사용됩니다. 내림차순으로 정렬되어 있어야 합니다.

guidance_scale (`float`, *선택 사항*, 기본값 `4.0`) : [Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598)에서 정의한 가이던스 스케일입니다. `guidance_scale`은 [Imagen Paper](https://huggingface.co/papers/2205.11487)의 2번 식의 `w`로 정의됩니다. `guidance_scale > 1`로 설정하면 가이던스 스케일이 활성화됩니다. 가이던스 스케일이 높을수록 `prompt` 텍스트와 밀접하게 연결된 이미지를 생성하도록 장려하지만, 일반적으로 이미지 품질이 낮아지는 대가를 치릅니다. 비디오 모달리티에 사용됩니다(오디오 모달리티에는 별도의 값 `audio_guidance_scale`이 있습니다).

stg_scale (`float`, *선택 사항*, 기본값 `0.0`) : [Spatiotemporal Skip Guidance for Enhanced Video Diffusion Sampling](https://arxiv.org/abs/2411.18664)에서 제안된 Spatio-Temporal Guidance(STG)를 위한 비디오 guidance scale입니다. STG는 CFG와 유사한 추정 방식을 사용하여, denoising 모델의 perturbed 버전에서 생성된 weak sample에서 샘플을 멀어지도록 이동시킵니다. STG를 활성화하면 denoising 모델의 forward pass가 추가로 수행되며, 기본값 `0.0`은 STG가 비활성화되어 있음을 의미합니다.

modality_scale (`float`, *선택 사항*, 기본값 `1.0`) : LTX-2.X 모달리티 격리 가이던스를 위한 비디오 가이던스 스케일입니다. 크로스 모달리티(오디오-비디오 및 비디오-오디오) 크로스 어텐션을 비활성화한 상태에서 디노이징 모델이 생성한 더 약한 샘플로부터 샘플을 이동시키는 CFG 유사 추정 방식을 사용합니다. 모달리티 가이던스를 활성화하면 디노이징 모델의 추가 포워드 패스가 발생합니다. 기본값 `1.0`은 모달리티 가이던스가 비활성화되어 있음을 의미합니다.

guidance_rescale (`float`, *선택 사항*, 기본값 0.0) : [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://huggingface.co/papers/2305.08891)에서 제안한 Guidance rescale factor입니다. `guidance_scale`은 [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://huggingface.co/papers/2305.08891)의 16번 식에서 `φ`로 정의됩니다. Guidance rescale factor는 zero terminal SNR을 사용할 때 과노출을 수정하는 데 사용됩니다. 비디오 모달리티에 사용됩니다.

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`) : 오디오 모달리티에 대한 별도의 guidance rescale factor입니다. `None`인 경우, 비디오 값인 `guidance_rescale`를 기본값으로 사용합니다.

spatio_temporal_guidance_blocks (`list[int]`, *선택 사항*, 기본값 `None`) : STG를 적용할 제로 인덱스 transformer 블록 인덱스입니다. STG를 사용하는 경우(`stg_scale` 또는 `audio_stg_scale`이 `0`보다 큰 경우) 반드시 제공해야 합니다. LTX-2.0에는 `[29]`를, LTX-2.3에는 `[28]`를 권장합니다.

noise_scale (`float`, *선택 사항*, 기본값 `0.0`) : 각 timestep에서 랜덤 노이즈와 디노이즈된 latents 사이의 보간 계수입니다. 디노이징을 계속하기 전에 `latents`와 `audio_latents`에 노이즈를 적용합니다.

num_videos_per_prompt (`int`, *선택 사항*, 기본값 1) : 프롬프트당 생성할 비디오의 수입니다.

generator (`torch.Generator` 또는 `list[torch.Generator]`, *선택 사항*) : 생성을 결정적으로 만들기 위한 [torch generator](https://pytorch.org/docs/stable/generated/torch.Generator.html) 하나 또는 목록.

latents (`torch.Tensor`, *선택 사항*) : 비디오 생성의 입력으로 사용할 가우시안 분포에서 샘플링된 사전 생성된 노이즈된 latents입니다. 동일한 생성을 다른 프롬프트로 조정하는 데 사용할 수 있습니다. 제공되지 않으면, 제공된 랜덤 `generator`를 사용하여 샘플링하여 latents 텐서가 생성됩니다.

audio_latents (`torch.Tensor`, *선택 사항*) : 가우시안 분포에서 샘플링하여 생성된 노이즈가 포함된 사전 생성된 latents로, 오디오 생성의 입력으로 사용됩니다. 동일한 생성을 다른 프롬프트로 조정하는 데 사용할 수 있습니다. 제공되지 않으면, 제공된 랜덤 `generator`를 사용하여 샘플링하여 latents 텐서가 생성됩니다.

prompt_embeds (`torch.Tensor`, *선택 사항*) : 미리 생성된 텍스트 임베딩입니다. *예를 들어* 프롬프트 가중치와 같은 텍스트 입력을 쉽게 조정하는 데 사용할 수 있습니다. 제공되지 않으면 `prompt` 입력 인자에서 텍스트 임베딩이 생성됩니다.

prompt_attention_mask (`torch.Tensor`, *선택 사항*) : 텍스트 임베딩을 위한 사전 생성된 어텐션 마스크입니다.

negative_prompt_embeds (`torch.FloatTensor`, *선택*) : 미리 생성된 부정 텍스트 임베딩입니다. PixArt-Sigma의 경우 이 negative prompt는 ""여야 합니다. 제공되지 않으면 `negative_prompt` 입력 인수에서 negative_prompt_embeds가 생성됩니다.

negative_prompt_attention_mask (`torch.FloatTensor`, *선택 사항*) : 부정 텍스트 임베딩에 사용할 사전 생성된 어텐션 마스크입니다.

decode_timestep (`float`, 기본값 `0.0`) : 생성된 비디오가 디코딩되는 타임스텝입니다.

decode_noise_scale (`float`, 기본값 `None`) : 디코딩 타임스텝에서 랜덤 노이즈와 디노이즈된 레이턴트 사이의 보간 계수입니다.

use_cross_timestep (`bool` *optional*, 기본값 `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`가 생략된 경우, 전용 `prompt_enhancer`가 구성된 경우 LTX-2.5는 `LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT`를 사용합니다. LTX-2.0/2.3은 명시적인 `system_prompt`가 필요합니다.

prompt_max_new_tokens (`int`, *선택 사항*, 기본값 `None`) : 프롬프트 강화 수행 시 생성할 새 토큰의 최대 수입니다. 지정되지 않으면 전용 Gemma 4 `prompt_enhancer`(LTX-2.5)의 경우 600, Gemma 3 `text_encoder` 폴백(LTX-2.0/2.3)의 경우 512를 사용합니다.

prompt_enhancement_kwargs (`dict[str, Any]`, *선택 사항*, 기본값 `None`) : 프롬프트 강화기의 `.generate` 호출에 사용할 키워드 인자입니다. 지정하지 않으면 강화 작업을 수행하는 모델에 따라 항상 다음과 같이 설정됩니다. 전용 `prompt_enhancer`(LTX-2.5)를 사용하는 경우 `do_sample=False, no_repeat_ngram_size=5`(그리디), `text_encoder` 폴백(LTX-2.0/2.3)을 사용하는 경우 `do_sample=True, temperature=0.7`입니다. 자세한 내용은 https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationMixin.generate 를 참조하세요.

prompt_enhancement_seed (`int`, *선택 사항*, 기본값 `10`) : 프롬프트 강화 과정 중 랜덤 연산에 사용되는 랜덤 시드입니다.

output_type (`str`, *선택 사항*, 기본값 `"pil"`) : 이미지 생성의 출력 형식입니다. [PIL](https://pillow.readthedocs.io/en/stable/): `PIL.Image.Image` 또는 `np.array` 중 하나를 선택합니다.

return_dict (`bool`, *선택 사항*, 기본값 `True`) : 일반 튜플 대신 `~pipelines.ltx.LTX2PipelineOutput`를 반환할지 여부.

attention_kwargs (`dict`, *선택 사항*) : 지정된 경우 [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py)의 `self.processor` 아래에서 정의된 `AttentionProcessor`로 전달되는 kwargs 사전입니다.

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`이 반환됩니다.

생성을 위해 파이프라인을 호출할 때 호출되는 함수.

예:
```py
>>> 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[[diffusers.LTX2Pipeline.encode_prompt]]

```python
encode_prompt(prompt: str | list[str], negative_prompt: str | list[str] | None = None, do_classifier_free_guidance: bool = True, num_videos_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, max_sequence_length: int = 1024, scale_factor: int = 8, device: typing.Optional[torch.device] = None, dtype: typing.Optional[torch.dtype] = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2.py#L367)

**매개변수:**

prompt (`str` 또는 `list[str]`, *선택 사항*) : 인코딩할 프롬프트

negative_prompt (`str` 또는 `list[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` 입력 인수에서 negative_prompt_embeds가 생성됩니다.

device : (`torch.device`, *선택 사항*): torch device

dtype : (`torch.dtype`, *선택 사항*): torch dtype

프롬프트를 텍스트 인코더의 히든 상태로 인코딩합니다.

#### enhance_prompt[[diffusers.LTX2Pipeline.enhance_prompt]]

```python
enhance_prompt(prompt: str, system_prompt: str, max_new_tokens: int | None = None, seed: int = 10, generator: typing.Optional[torch.Generator] = None, generation_kwargs: dict[str, typing.Any] | None = None, device: typing.Union[str, torch.device, NoneType] = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2.py#L574)

`prompt`를 입력받아 프롬프트 강화기(Gemma 조건 생성 모델)와 시스템 프롬프트를 활용하여 새로운 프롬프트를 생성합니다. `image`가 제공되면, 강화기는 해당 참조 프레임에도 조건을 부여하여 강화합니다(I2V/키프레임 스타일 강화). `prompt_enhancer` 구성 요소가 설정되어 있으면(예: 강화용으로 학습되지 않은 텍스트 인코더를 사용하는 LTX-2.5) 이를 사용하고, 그렇지 않으면 자체 강화기로 기능하는 메인 `text_encoder`(LTX-2.0/2.3)로 대체합니다.

메시지 템플릿, 디코딩 kwargs, 응답 정제, 이미지 긴 변 준비는 `ltx-core` / `ltx-pipelines`의 `enhance_t2v` / `enhance_i2v` / `generate_enhanced_prompt`와 일치합니다.

## LTX2ImageToVideoPipeline[[diffusers.LTX2ImageToVideoPipeline]]

#### diffusers.LTX2ImageToVideoPipeline[[diffusers.LTX2ImageToVideoPipeline]]

```python
diffusers.LTX2ImageToVideoPipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKLLTX2Video, audio_vae: AutoencoderKLLTX2Audio, text_encoder: transformers.models.gemma3.modeling_gemma3.Gemma3ForConditionalGeneration | transformers.models.gemma4_unified.modeling_gemma4_unified.Gemma4UnifiedForConditionalGeneration, tokenizer: GemmaTokenizer, connectors: LTX2TextConnectors, transformer: LTX2VideoTransformer3DModel, vocoder: diffusers.pipelines.ltx2.vocoder.LTX2Vocoder | diffusers.pipelines.ltx2.vocoder.LTX2VocoderWithBWE, processor: transformers.processing_utils.ProcessorMixin | None = None, prompt_enhancer: transformers.models.gemma4.modeling_gemma4.Gemma4ForConditionalGeneration | None = None, duration_head: diffusers.pipelines.ltx2.duration_head.LTX2DurationHead | None = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_image2video.py#L229)

이미지에서 비디오를 생성하는 Pipeline입니다.

Reference: https://github.com/Lightricks/LTX-Video

TODO

#### __호출__[[diffusers.LTX2ImageToVideoPipeline.__call__]]

```python
__call__(image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, prompt: str | list[str] = None, negative_prompt: str | list[str] | None = None, height: int = 512, width: int = 768, num_frames: int | None = None, min_seconds: float = 1.0, max_seconds: float = 20.0, frame_rate: float = 24.0, motion_speed: float = 1.0, num_inference_steps: int = 30, sigmas: list[float] | None = None, timesteps: list[int] | None = None, guidance_scale: float = 3.0, stg_scale: float = 1.0, modality_scale: float = 3.0, guidance_rescale: float = 0.7, audio_guidance_scale: float | None = 7.0, audio_stg_scale: float | None = 1.0, audio_modality_scale: float | None = 3.0, audio_guidance_rescale: float | None = 0.7, spatio_temporal_guidance_blocks: list[int] | None = [28], noise_scale: float = 0.0, num_videos_per_prompt: int = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, audio_latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, decode_timestep: float | list[float] = 0.0, decode_noise_scale: float | list[float] | None = None, use_cross_timestep: bool = True, system_prompt: str | None = None, enable_prompt_enhancement: bool = False, prompt_max_new_tokens: int | None = None, prompt_enhancement_kwargs: dict[str, typing.Any] | None = None, prompt_enhancement_seed: int = 10, image_crf: int | None = None, output_type: str = 'pil', return_dict: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list = ['latents'], max_sequence_length: int = 1024)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_image2video.py#L983)

**매개변수:**

image (`PipelineImageInput`) : 생성을 조건화할 입력 이미지. 이미지, 이미지 목록 또는 `torch.Tensor`여야 합니다.

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의 인과적 시간 그리드에 맞춰 정렬되므로, 실제 길이는 양자화됩니다(24 fps 기준 약 0.33초).

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보다 작은 값은 동작을 늦춥니다. 예를 들어 Slow-Motion-Control LoRA의 5배 슬로 모션에는 `0.2`를 사용합니다. `frame_rate`는 재생 속도로 유지되며, 오디오 길이와 예측된 프레임 수는 이에 따라 결정됩니다.

num_inference_steps (`int`, *선택 사항*, 기본값 30) : 디노이징 단계의 수입니다. 디노이징 단계가 많을수록 일반적으로 추론 속도가 느려지는 대신 더 높은 품질의 이미지를 생성합니다.

sigmas (`List[float]`, *선택 사항*) : `set_timesteps` 메서드에서 `sigmas` 인자를 지원하는 스케줄러의 노이즈 제거 과정에 사용할 커스텀 시그마입니다. 정의되지 않은 경우, `num_inference_steps`가 전달될 때의 기본 동작이 사용됩니다.

timesteps (`List[int]`, *선택 사항*) : `set_timesteps` 메서드에 `timesteps` 인수를 지원하는 스케줄러의 노이즈 제거 과정에 사용할 커스텀 타임스텝입니다. 정의되지 않은 경우, `num_inference_steps`가 전달될 때의 기본 동작이 사용됩니다. 내림차순으로 정렬되어 있어야 합니다.

guidance_scale (`float`, *선택 사항*, 기본값 `4.0`) : [Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598)에서 정의한 가이던스 스케일입니다. `guidance_scale`은 [Imagen Paper](https://huggingface.co/papers/2205.11487)의 2번 식의 `w`로 정의됩니다. `guidance_scale > 1`로 설정하면 가이던스 스케일이 활성화됩니다. 가이던스 스케일이 높을수록 `prompt` 텍스트와 밀접하게 연결된 이미지를 생성하도록 장려하지만, 일반적으로 이미지 품질이 낮아지는 대가를 치릅니다. 비디오 모달리티에 사용됩니다(오디오 모달리티에는 별도의 값 `audio_guidance_scale`이 있습니다).

stg_scale (`float`, *선택 사항*, 기본값 `0.0`) : [Spatiotemporal Skip Guidance for Enhanced Video Diffusion Sampling](https://arxiv.org/abs/2411.18664)에서 제안된 Spatio-Temporal Guidance(STG)를 위한 비디오 guidance scale입니다. STG는 CFG와 유사한 추정 방식을 사용하여, denoising 모델의 perturbed 버전에서 생성된 weak sample에서 샘플을 멀어지도록 이동시킵니다. STG를 활성화하면 denoising 모델의 forward pass가 추가로 수행되며, 기본값 `0.0`은 STG가 비활성화되어 있음을 의미합니다.

modality_scale (`float`, *선택 사항*, 기본값 `1.0`) : LTX-2.X 모달리티 격리 가이던스를 위한 비디오 가이던스 스케일입니다. 크로스 모달리티(오디오-비디오 및 비디오-오디오) 크로스 어텐션을 비활성화한 상태에서 디노이징 모델이 생성한 더 약한 샘플로부터 샘플을 이동시키는 CFG 유사 추정 방식을 사용합니다. 모달리티 가이던스를 활성화하면 디노이징 모델의 추가 포워드 패스가 발생합니다. 기본값 `1.0`은 모달리티 가이던스가 비활성화되어 있음을 의미합니다.

guidance_rescale (`float`, *선택 사항*, 기본값 0.0) : [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://huggingface.co/papers/2305.08891)에서 제안한 Guidance rescale factor입니다. `guidance_scale`은 [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://huggingface.co/papers/2305.08891)의 16번 식에서 `φ`로 정의됩니다. Guidance rescale factor는 zero terminal SNR을 사용할 때 과노출을 수정하는 데 사용됩니다. 비디오 모달리티에 사용됩니다.

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`) : 오디오 모달리티에 대한 별도의 guidance rescale factor입니다. `None`인 경우, 비디오 값인 `guidance_rescale`를 기본값으로 사용합니다.

spatio_temporal_guidance_blocks (`list[int]`, *선택 사항*, 기본값 `None`) : STG를 적용할 제로 인덱스 transformer 블록 인덱스입니다. STG를 사용하는 경우(`stg_scale` 또는 `audio_stg_scale`이 `0`보다 큰 경우) 반드시 제공해야 합니다. LTX-2.0에는 `[29]`를, LTX-2.3에는 `[28]`를 권장합니다.

noise_scale (`float`, *선택 사항*, 기본값 `0.0`) : 각 timestep에서 랜덤 노이즈와 디노이즈된 latents 사이의 보간 계수입니다. 디노이징을 계속하기 전에 `latents`와 `audio_latents`에 노이즈를 적용합니다.

num_videos_per_prompt (`int`, *선택 사항*, 기본값 1) : 프롬프트당 생성할 비디오의 수입니다.

generator (`torch.Generator` 또는 `list[torch.Generator]`, *선택 사항*) : 생성을 결정적으로 만들기 위한 [torch generator](https://pytorch.org/docs/stable/generated/torch.Generator.html) 하나 또는 목록.

latents (`torch.Tensor`, *선택 사항*) : 비디오 생성의 입력으로 사용할 가우시안 분포에서 샘플링된 사전 생성된 노이즈된 latents입니다. 동일한 생성을 다른 프롬프트로 조정하는 데 사용할 수 있습니다. 제공되지 않으면, 제공된 랜덤 `generator`를 사용하여 샘플링하여 latents 텐서가 생성됩니다.

audio_latents (`torch.Tensor`, *선택 사항*) : 가우시안 분포에서 샘플링하여 생성된 노이즈가 포함된 사전 생성된 latents로, 오디오 생성의 입력으로 사용됩니다. 동일한 생성을 다른 프롬프트로 조정하는 데 사용할 수 있습니다. 제공되지 않으면, 제공된 랜덤 `generator`를 사용하여 샘플링하여 latents 텐서가 생성됩니다.

prompt_embeds (`torch.Tensor`, *선택 사항*) : 미리 생성된 텍스트 임베딩입니다. *예를 들어* 프롬프트 가중치와 같은 텍스트 입력을 쉽게 조정하는 데 사용할 수 있습니다. 제공되지 않으면 `prompt` 입력 인자에서 텍스트 임베딩이 생성됩니다.

prompt_attention_mask (`torch.Tensor`, *선택 사항*) : 텍스트 임베딩을 위한 사전 생성된 어텐션 마스크입니다.

negative_prompt_embeds (`torch.FloatTensor`, *선택*) : 미리 생성된 부정 텍스트 임베딩입니다. PixArt-Sigma의 경우 이 negative prompt는 ""여야 합니다. 제공되지 않으면 `negative_prompt` 입력 인수에서 negative_prompt_embeds가 생성됩니다.

negative_prompt_attention_mask (`torch.FloatTensor`, *선택 사항*) : 부정 텍스트 임베딩에 사용할 사전 생성된 어텐션 마스크입니다.

decode_timestep (`float`, 기본값 `0.0`) : 생성된 비디오가 디코딩되는 타임스텝입니다.

decode_noise_scale (`float`, 기본값 `None`) : 디코딩 타임스텝에서 랜덤 노이즈와 디노이즈된 레이턴트 사이의 보간 계수입니다.

use_cross_timestep (`bool` *optional*, 기본값 `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`가 생략된 경우, 전용 `prompt_enhancer`가 구성된 경우 LTX-2.5는 `LTX2_5_I2V_DEFAULT_SYSTEM_PROMPT`를 사용합니다. LTX-2.0/2.3은 명시적인 `system_prompt`가 필요합니다.

prompt_max_new_tokens (`int`, *선택 사항*, 기본값 `None`) : 프롬프트 강화 수행 시 생성할 새 토큰의 최대 수입니다. 지정되지 않으면 전용 Gemma 4 `prompt_enhancer`(LTX-2.5)의 경우 600, Gemma 3 `text_encoder` 폴백(LTX-2.0/2.3)의 경우 512를 사용합니다.

prompt_enhancement_kwargs (`dict[str, Any]`, *선택 사항*, 기본값 `None`) : 프롬프트 강화기의 `.generate` 호출에 사용할 키워드 인자입니다. 지정하지 않으면 강화 작업을 수행하는 모델에 따라 항상 다음과 같이 설정됩니다. 전용 `prompt_enhancer`(LTX-2.5)를 사용하는 경우 `do_sample=False, no_repeat_ngram_size=3`(그리디), `text_encoder` 폴백(LTX-2.0/2.3)을 사용하는 경우 `do_sample=True, temperature=0.7`입니다. 자세한 내용은 https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationMixin.generate 를 참조하세요.

prompt_enhancement_seed (`int`, *선택 사항*, 기본값 `10`) : 프롬프트 강화 과정 중 랜덤 연산에 사용되는 랜덤 시드입니다.

image_crf (`int`, *선택 사항*, 기본값 `None`) : VAE 인코딩 전에 조건부 `image`를 재압축할 때 사용되는 H.264 CRF 값입니다. 모델이 학습된 압축 수준과 일치하도록 설정합니다. `None`은 "모델 기본값 사용"을 의미하며(LTX-2.3까지는 33, LTX-2.5는 18) `0`을 전달하면 재압축을 건너뜁니다. 재압축이 실행될 때는 `PIL.Image.Image`가 필요합니다.

output_type (`str`, *선택 사항*, 기본값 `"pil"`) : 이미지 생성의 출력 형식입니다. [PIL](https://pillow.readthedocs.io/en/stable/): `PIL.Image.Image` 또는 `np.array` 중 하나를 선택합니다.

return_dict (`bool`, *선택 사항*, 기본값 `True`) : 일반 튜플 대신 `~pipelines.ltx.LTX2PipelineOutput`를 반환할지 여부.

attention_kwargs (`dict`, *선택 사항*) : 지정된 경우 [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py)의 `self.processor` 아래에서 정의된 `AttentionProcessor`로 전달되는 kwargs 사전입니다.

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`이 반환됩니다.

생성을 위해 파이프라인을 호출할 때 호출되는 함수.

예:
```py
>>> 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[[diffusers.LTX2ImageToVideoPipeline.encode_prompt]]

```python
encode_prompt(prompt: str | list[str], negative_prompt: str | list[str] | None = None, do_classifier_free_guidance: bool = True, num_videos_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, max_sequence_length: int = 1024, scale_factor: int = 8, device: typing.Optional[torch.device] = None, dtype: typing.Optional[torch.dtype] = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_image2video.py#L372)

**매개변수:**

prompt (`str` 또는 `list[str]`, *선택 사항*) : 인코딩할 프롬프트

negative_prompt (`str` 또는 `list[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` 입력 인수에서 negative_prompt_embeds가 생성됩니다.

device : (`torch.device`, *선택 사항*): torch device

dtype : (`torch.dtype`, *선택 사항*): torch dtype

프롬프트를 텍스트 인코더의 히든 상태로 인코딩합니다.

#### enhance_prompt[[diffusers.LTX2ImageToVideoPipeline.enhance_prompt]]

```python
enhance_prompt(prompt: str, system_prompt: str, max_new_tokens: int | None = None, seed: int = 10, generator: typing.Optional[torch.Generator] = None, generation_kwargs: dict[str, typing.Any] | None = None, device: typing.Union[str, torch.device, NoneType] = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_image2video.py#L580)

`prompt`를 입력받아 프롬프트 강화기(Gemma 조건 생성 모델)와 시스템 프롬프트를 활용하여 새로운 프롬프트를 생성합니다. `image`가 제공되면, 강화기는 해당 참조 프레임에도 조건을 부여하여 강화합니다(I2V/키프레임 스타일 강화). `prompt_enhancer` 구성 요소가 설정되어 있으면(예: 강화용으로 학습되지 않은 텍스트 인코더를 사용하는 LTX-2.5) 이를 사용하고, 그렇지 않으면 자체 강화기로 기능하는 메인 `text_encoder`(LTX-2.0/2.3)로 대체합니다.

메시지 템플릿, 디코딩 kwargs, 응답 정제, 이미지 긴 변 준비는 `ltx-core` / `ltx-pipelines`의 `enhance_t2v` / `enhance_i2v` / `generate_enhanced_prompt`와 일치합니다.

## LTX2ConditionPipeline[[diffusers.LTX2ConditionPipeline]]

#### diffusers.LTX2ConditionPipeline[[diffusers.LTX2ConditionPipeline]]

```python
diffusers.LTX2ConditionPipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKLLTX2Video, audio_vae: AutoencoderKLLTX2Audio, text_encoder: transformers.models.gemma3.modeling_gemma3.Gemma3ForConditionalGeneration | transformers.models.gemma4_unified.modeling_gemma4_unified.Gemma4UnifiedForConditionalGeneration, tokenizer: GemmaTokenizer, connectors: LTX2TextConnectors, transformer: LTX2VideoTransformer3DModel, vocoder: diffusers.pipelines.ltx2.vocoder.LTX2Vocoder | diffusers.pipelines.ltx2.vocoder.LTX2VocoderWithBWE, audio_scheduler: diffusers.schedulers.scheduling_flow_match_euler_discrete.FlowMatchEulerDiscreteScheduler | None = None, processor: transformers.processing_utils.ProcessorMixin | None = None, prompt_enhancer: transformers.models.gemma4.modeling_gemma4.Gemma4ForConditionalGeneration | None = None, duration_head: diffusers.pipelines.ltx2.duration_head.LTX2DurationHead | None = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_condition.py#L266)

비디오의 임의 위치에 이미지 조건을 삽입할 수 있는 비디오 생성용 Pipeline입니다.

Reference: https://github.com/Lightricks/LTX-Video

TODO

#### __호출__[[diffusers.LTX2ConditionPipeline.__call__]]

```python
__call__(conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = None, prompt: str | list[str] = None, negative_prompt: str | list[str] | None = None, height: int = 512, width: int = 768, num_frames: int | None = None, min_seconds: float = 1.0, max_seconds: float = 20.0, frame_rate: float = 24.0, motion_speed: float = 1.0, num_inference_steps: int = 30, sigmas: list[float] | None = None, timesteps: list[float] | None = None, guidance_scale: float = 3.0, stg_scale: float = 1.0, modality_scale: float = 3.0, guidance_rescale: float = 0.7, audio_guidance_scale: float | None = 7.0, audio_stg_scale: float | None = 1.0, audio_modality_scale: float | None = 3.0, audio_guidance_rescale: float | None = 0.7, spatio_temporal_guidance_blocks: list[int] | None = [28], noise_scale: float | None = None, num_videos_per_prompt: int | None = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, audio_latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, decode_timestep: float | list[float] = 0.0, decode_noise_scale: float | list[float] | None = None, use_cross_timestep: bool = True, system_prompt: str | None = None, enable_prompt_enhancement: bool = False, prompt_max_new_tokens: int | None = None, prompt_enhancement_kwargs: dict[str, typing.Any] | None = None, prompt_enhancement_seed: int = 10, output_type: str = 'pil', return_dict: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list = ['latents'], max_sequence_length: int = 1024)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_condition.py#L1348)

**매개변수:**

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의 인과적 시간 그리드에 맞춰 정렬되므로, 실제 길이는 양자화됩니다(24 fps 기준 약 0.33초).

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보다 작은 값은 동작을 늦춥니다. 예를 들어 Slow-Motion-Control LoRA의 5배 슬로 모션에는 `0.2`를 사용합니다. `frame_rate`는 재생 속도로 유지되며, 오디오 길이와 예측된 프레임 수는 이에 따라 결정됩니다.

num_inference_steps (`int`, *선택 사항*, 기본값 30) : 디노이징 단계의 수입니다. 디노이징 단계가 많을수록 일반적으로 추론 속도가 느려지는 대신 더 높은 품질의 이미지를 생성합니다.

sigmas (`List[float]`, *선택 사항*) : `set_timesteps` 메서드에서 `sigmas` 인자를 지원하는 스케줄러의 노이즈 제거 과정에 사용할 커스텀 시그마입니다. 정의되지 않은 경우, `num_inference_steps`가 전달될 때의 기본 동작이 사용됩니다.

timesteps (`List[int]`, *선택 사항*) : `set_timesteps` 메서드에 `timesteps` 인수를 지원하는 스케줄러의 노이즈 제거 과정에 사용할 커스텀 타임스텝입니다. 정의되지 않은 경우, `num_inference_steps`가 전달될 때의 기본 동작이 사용됩니다. 내림차순으로 정렬되어 있어야 합니다.

guidance_scale (`float`, *선택 사항*, 기본값 `4.0`) : [Classifier-Free Diffusion Guidance](https://huggingface.co/papers/2207.12598)에서 정의한 가이던스 스케일입니다. `guidance_scale`은 [Imagen Paper](https://huggingface.co/papers/2205.11487)의 2번 식의 `w`로 정의됩니다. `guidance_scale > 1`로 설정하면 가이던스 스케일이 활성화됩니다. 가이던스 스케일이 높을수록 `prompt` 텍스트와 밀접하게 연결된 이미지를 생성하도록 장려하지만, 일반적으로 이미지 품질이 낮아지는 대가를 치릅니다. 비디오 모달리티에 사용됩니다(오디오 모달리티에는 별도의 값 `audio_guidance_scale`이 있습니다).

stg_scale (`float`, *선택 사항*, 기본값 `0.0`) : [Spatiotemporal Skip Guidance for Enhanced Video Diffusion Sampling](https://arxiv.org/abs/2411.18664)에서 제안된 Spatio-Temporal Guidance(STG)를 위한 비디오 guidance scale입니다. STG는 CFG와 유사한 추정 방식을 사용하여, denoising 모델의 perturbed 버전에서 생성된 weak sample에서 샘플을 멀어지도록 이동시킵니다. STG를 활성화하면 denoising 모델의 forward pass가 추가로 수행되며, 기본값 `0.0`은 STG가 비활성화되어 있음을 의미합니다.

modality_scale (`float`, *선택 사항*, 기본값 `1.0`) : LTX-2.X 모달리티 격리 가이던스를 위한 비디오 가이던스 스케일입니다. 크로스 모달리티(오디오-비디오 및 비디오-오디오) 크로스 어텐션을 비활성화한 상태에서 디노이징 모델이 생성한 더 약한 샘플로부터 샘플을 이동시키는 CFG 유사 추정 방식을 사용합니다. 모달리티 가이던스를 활성화하면 디노이징 모델의 추가 포워드 패스가 발생합니다. 기본값 `1.0`은 모달리티 가이던스가 비활성화되어 있음을 의미합니다.

guidance_rescale (`float`, *선택 사항*, 기본값 0.0) : [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://huggingface.co/papers/2305.08891)에서 제안한 Guidance rescale factor입니다. `guidance_scale`은 [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://huggingface.co/papers/2305.08891)의 16번 식에서 `φ`로 정의됩니다. Guidance rescale factor는 zero terminal SNR을 사용할 때 과노출을 수정하는 데 사용됩니다. 비디오 모달리티에 사용됩니다.

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`) : 오디오 모달리티에 대한 별도의 guidance rescale factor입니다. `None`인 경우, 비디오 값인 `guidance_rescale`를 기본값으로 사용합니다.

spatio_temporal_guidance_blocks (`list[int]`, *선택 사항*, 기본값 `None`) : STG를 적용할 제로 인덱스 transformer 블록 인덱스입니다. STG를 사용하는 경우(`stg_scale` 또는 `audio_stg_scale`이 `0`보다 큰 경우) 반드시 제공해야 합니다. LTX-2.0에는 `[29]`를, LTX-2.3에는 `[28]`를 권장합니다.

noise_scale (`float`, *선택 사항*, 기본값 `None`) : 각 timestep에서 랜덤 노이즈와 디노이즈된 latents 사이의 보간 계수입니다. 디노이징을 계속하기 전에 `latents`와 `audio_latents`에 노이즈를 적용합니다. 설정되지 않으면 sigma schedule에서 추론됩니다.

num_videos_per_prompt (`int`, *선택 사항*, 기본값 1) : 프롬프트당 생성할 비디오의 수입니다.

generator (`torch.Generator` 또는 `List[torch.Generator]`, *선택 사항*) : 생성을 결정적으로 만들기 위한 [torch generator](https://pytorch.org/docs/stable/generated/torch.Generator.html) 하나 또는 목록.

latents (`torch.Tensor`, *선택 사항*) : 비디오 생성의 입력으로 사용할 가우시안 분포에서 샘플링된 사전 생성된 노이즈된 latents입니다. 동일한 생성을 다른 프롬프트로 조정하는 데 사용할 수 있습니다. 제공되지 않으면, 제공된 랜덤 `generator`를 사용하여 샘플링하여 latents 텐서가 생성됩니다.

audio_latents (`torch.Tensor`, *선택 사항*) : 가우시안 분포에서 샘플링하여 생성된 노이즈가 포함된 사전 생성된 latents로, 오디오 생성의 입력으로 사용됩니다. 동일한 생성을 다른 프롬프트로 조정하는 데 사용할 수 있습니다. 제공되지 않으면, 제공된 랜덤 `generator`를 사용하여 샘플링하여 latents 텐서가 생성됩니다.

prompt_embeds (`torch.Tensor`, *선택 사항*) : 미리 생성된 텍스트 임베딩입니다. *예를 들어* 프롬프트 가중치와 같은 텍스트 입력을 쉽게 조정하는 데 사용할 수 있습니다. 제공되지 않으면 `prompt` 입력 인자에서 텍스트 임베딩이 생성됩니다.

prompt_attention_mask (`torch.Tensor`, *선택 사항*) : 텍스트 임베딩을 위한 사전 생성된 어텐션 마스크입니다.

negative_prompt_embeds (`torch.FloatTensor`, *선택*) : 미리 생성된 부정 텍스트 임베딩입니다. PixArt-Sigma의 경우 이 negative prompt는 ""여야 합니다. 제공되지 않으면 `negative_prompt` 입력 인수에서 negative_prompt_embeds가 생성됩니다.

negative_prompt_attention_mask (`torch.FloatTensor`, *선택 사항*) : 부정 텍스트 임베딩에 사용할 사전 생성된 어텐션 마스크입니다.

decode_timestep (`float`, 기본값 `0.0`) : 생성된 비디오가 디코딩되는 타임스텝입니다.

decode_noise_scale (`float`, 기본값 `None`) : 디코딩 타임스텝에서 랜덤 노이즈와 디노이즈된 레이턴트 사이의 보간 계수입니다.

use_cross_timestep (`bool` *optional*, 기본값 `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`) : 프롬프트 강화 수행 시 생성할 새 토큰의 최대 수입니다. 지정되지 않으면 전용 Gemma 4 `prompt_enhancer`(LTX-2.5)의 경우 600, Gemma 3 `text_encoder` 폴백(LTX-2.0/2.3)의 경우 512를 사용합니다.

prompt_enhancement_kwargs (`dict[str, Any]`, *선택 사항*, 기본값 `None`) : 프롬프트 강화기의 `.generate` 호출에 사용할 키워드 인자입니다. 지정하지 않으면 강화 작업을 수행하는 모델에 따라 항상 다음과 같이 설정됩니다. 전용 `prompt_enhancer`(LTX-2.5)를 사용하는 경우 `do_sample=False, no_repeat_ngram_size=5`(그리디), `text_encoder` 폴백(LTX-2.0/2.3)을 사용하는 경우 `do_sample=True, temperature=0.7`입니다. 자세한 내용은 https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationMixin.generate 를 참조하세요.

prompt_enhancement_seed (`int`, *선택 사항*, 기본값 `10`) : 프롬프트 강화 과정 중 랜덤 연산에 사용되는 랜덤 시드입니다.

output_type (`str`, *선택 사항*, 기본값 `"pil"`) : 이미지 생성의 출력 형식입니다. [PIL](https://pillow.readthedocs.io/en/stable/): `PIL.Image.Image` 또는 `np.array` 중 하나를 선택합니다.

return_dict (`bool`, *선택 사항*, 기본값 `True`) : 일반 튜플 대신 `~pipelines.ltx.LTX2PipelineOutput`를 반환할지 여부.

attention_kwargs (`dict`, *선택 사항*) : 지정된 경우 [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py)의 `self.processor` 아래에서 정의된 `AttentionProcessor`로 전달되는 kwargs 사전입니다.

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`이 반환됩니다.

생성을 위해 파이프라인을 호출할 때 호출되는 함수.

예:
```py
>>> 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[[diffusers.LTX2ConditionPipeline.apply_first_frame_conditioning]]

```python
apply_first_frame_conditioning(latents: Tensor, conditioning_mask: Tensor, condition_latents: list, condition_strengths: list, condition_indices: list, latent_height: int, latent_width: int)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_condition.py#L964)

**매개변수:**

latents (`torch.Tensor`) : [batch_size, patch_seq_len, hidden_dim] 형태의 초기 패킹(패치화)된 latents.

conditioning_mask (`torch.Tensor`) : [batch_size, patch_seq_len, 1] 모양의 초기 패킹(패치화)된 조건 마스크로, 값은 [0, 1] 범위이며 0은 디노이징 모델 출력을 완전히 사용함을, 1은 조건을 완전히 사용함을 의미합니다.

**반환값:** `Tuple[torch.Tensor, torch.Tensor, torch.Tensor]`

다음과 같은 3개의 텐서 튜플을 반환합니다:
1. 첫 프레임 조건이 적용된 패킹된 비디오 잠재 변수입니다.
2. 첫 프레임 강도가 적용된 패킹된 조건화 마스크.
3. 첫 번째 프레임 위치의 깨끗한 조건부 잠재 변수(나머지 위치는 0).

first-frame 위치의 토큰을 덮어써서 첫 프레임 시각 조건화를 적용합니다.

`latent_idx == 0`인 조건만 여기에 적용됩니다(참조 구현의 `VideoConditionByLatentIndex`와 일치). 0이 아닌 latent 인덱스에 있는 조건은 `prepare_keyframe_extras`를 통해 별도의 keyframe 토큰으로 추가되며(`VideoConditionByKeyframeIndex`와 일치), 여기서는 건너뜁니다.

#### encode_prompt[[diffusers.LTX2ConditionPipeline.encode_prompt]]

```python
encode_prompt(prompt: str | list[str], negative_prompt: str | list[str] | None = None, do_classifier_free_guidance: bool = True, num_videos_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, max_sequence_length: int = 1024, scale_factor: int = 8, device: typing.Optional[torch.device] = None, dtype: typing.Optional[torch.dtype] = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_condition.py#L419)

**매개변수:**

prompt (`str` 또는 `list[str]`, *선택 사항*) : 인코딩할 프롬프트

negative_prompt (`str` 또는 `list[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` 입력 인수에서 negative_prompt_embeds가 생성됩니다.

device : (`torch.device`, *선택 사항*): torch device

dtype : (`torch.dtype`, *선택 사항*): torch dtype

프롬프트를 텍스트 인코더의 히든 상태로 인코딩합니다.

#### enhance_prompt[[diffusers.LTX2ConditionPipeline.enhance_prompt]]

```python
enhance_prompt(prompt: str, system_prompt: str, max_new_tokens: int | None = None, seed: int = 10, generator: typing.Optional[torch.Generator] = None, generation_kwargs: dict[str, typing.Any] | None = None, device: typing.Union[str, torch.device, NoneType] = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_condition.py#L627)

`prompt`를 입력받아 프롬프트 강화기(Gemma 조건 생성 모델)와 시스템 프롬프트를 활용하여 새로운 프롬프트를 생성합니다. `image`가 제공되면, 강화기는 해당 참조 프레임에도 조건을 부여하여 강화합니다(I2V/키프레임 스타일 강화). `prompt_enhancer` 구성 요소가 설정되어 있으면(예: 강화용으로 학습되지 않은 텍스트 인코더를 사용하는 LTX-2.5) 이를 사용하고, 그렇지 않으면 자체 강화기로 기능하는 메인 `text_encoder`(LTX-2.0/2.3)로 대체합니다.

메시지 템플릿, 디코딩 kwargs, 응답 정제, 이미지 긴 변 준비는 `ltx-core` / `ltx-pipelines`의 `enhance_t2v` / `enhance_i2v` / `generate_enhanced_prompt`와 일치합니다.

#### prepare_latents[[diffusers.LTX2ConditionPipeline.prepare_latents]]

```python
prepare_latents(conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = None, batch_size: int = 1, num_channels_latents: int = 128, height: int = 512, width: int = 768, num_frames: int = 121, frame_rate: float = 24.0, noise_scale: float = 1.0, dtype: typing.Optional[torch.dtype] = None, device: typing.Optional[torch.device] = None, generator: typing.Optional[torch.Generator] = None, latents: typing.Optional[torch.Tensor] = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_condition.py#L1071)

noisy video latents를 준비하고, 프레임 조건을 적용합니다.

첫 프레임 조건(`latent_idx == 0`)은 첫 프레임 위치의 토큰을 덮어쓰는 방식으로 적용됩니다(`VideoConditionByLatentIndex` 의미론). 첫 프레임이 아닌 조건(`latent_idx > 0`)은 토큰별 `conditioning_mask = strength`를 사용하여 메인 latent 시퀀스에 연결됩니다(`VideoConditionByKeyframeIndex` 의미론). 이후 디노이징 루프의 기존 timestep 공식 `t * (1 - conditioning_mask)`와 후처리 블렌딩 `denoised * (1 - conditioning_mask) + clean * conditioning_mask`이 이를 단계별로 처리합니다.

4-튜플을 반환합니다:
- `latents`: 패킹된 노이저티드 레이턴트(베이스 토큰 + 시퀀스 차원에 cat된 모든 키프레임 토큰).
- `conditioning_mask`: `[0, 1]` 범위의 값으로 구성된 packed conditioning mask — 첫 번째 프레임 위치에는 `1`, keyframe 위치에는 `strength`, 그 외에는 `0`.
- `clean_latents`: 조건부 위치의 clean condition 값(나머지 위치는 0); `latents`와 동일한 shape.
- `keyframe_coords`: `video_coords`에 추가할 `[B, 3, num_keyframe_patches, 2]` 위치 좌표. 첫 번째 프레임이 아닌 조건이 없으면 `None`.

#### preprocess_conditions[[diffusers.LTX2ConditionPipeline.preprocess_conditions]]

```python
preprocess_conditions(conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = None, height: int = 512, width: int = 768, num_frames: int = 121, device: typing.Optional[torch.device] = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_condition.py#L846)

**매개변수:**

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]]`

다음과 같이 `len(conditions)` 길이의 리스트 4개로 구성된 4-tuple을 반환합니다:
1. 첫 번째 목록은 [batch_size=1, num_channels, num_frames, height, width] 모양의 전처리된 비디오 텐서 목록입니다.
2. 두 번째 목록은 조건화 강도(conditioning strengths)의 목록입니다.
3. 세 번째 목록은 각 조건에 대한 잠재 공간 인덱스 목록입니다.
4. 네 번째 목록은 각 조건에 대한 (잘린) 픽셀 공간 프레임 수 목록입니다. 이는 키프레임 좌표 의미론에 필요합니다(단일 픽셀 프레임 키프레임은 클램프된 시간 범위를 가짐).

조건 이미지/영상을 torch 텐서로 전처리합니다.

#### trim_conditioning_sequence[[diffusers.LTX2ConditionPipeline.trim_conditioning_sequence]]

```python
trim_conditioning_sequence(start_frame: int, sequence_num_frames: int, target_num_frames: int)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_condition.py#L829)

**매개변수:**

start_frame (int) : 시퀀스의 첫 번째 프레임의 대상 프레임 번호.

sequence_num_frames (int) : 시퀀스의 프레임 수.

target_num_frames (int) : 생성된 비디오의 목표 프레임 수.

**반환값:** `int`

업데이트된 시퀀스 길이

조건부 시퀀스를 허용된 프레임 수로 잘라냅니다.

## LTX2DFRPipeline[[diffusers.LTX2DFRPipeline]]

#### diffusers.LTX2DFRPipeline[[diffusers.LTX2DFRPipeline]]

```python
diffusers.LTX2DFRPipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKLLTX2Video, audio_vae: AutoencoderKLLTX2Audio, text_encoder: transformers.models.gemma3.modeling_gemma3.Gemma3ForConditionalGeneration | transformers.models.gemma4_unified.modeling_gemma4_unified.Gemma4UnifiedForConditionalGeneration, tokenizer: GemmaTokenizer, connectors: LTX2TextConnectors, transformer: LTX2VideoTransformer3DModel, vocoder: diffusers.pipelines.ltx2.vocoder.LTX2Vocoder | diffusers.pipelines.ltx2.vocoder.LTX2VocoderWithBWE, processor: transformers.processing_utils.ProcessorMixin | None = None, prompt_enhancer: transformers.models.gemma4.modeling_gemma4.Gemma4ForConditionalGeneration | None = None, duration_head: diffusers.pipelines.ltx2.duration_head.LTX2DurationHead | None = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr.py#L122)

**매개변수:**

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/ko/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : `transformer`와 함께 사용하여 인코딩된 비디오 잠재를 디노이즈하는 데 사용되는 스케줄러입니다.

vae ([AutoencoderKLLTX2Video](/docs/diffusers/main/ko/api/models/autoencoderkl_ltx_2#diffusers.AutoencoderKLLTX2Video)) : 잠재 표현으로 비디오를 인코딩 및 디코딩하는 Variational Auto-Encoder (VAE) 모델.

audio_vae ([AutoencoderKLLTX2Audio](/docs/diffusers/main/ko/api/models/autoencoderkl_audio_ltx_2#diffusers.AutoencoderKLLTX2Audio)) : 오디오 스펙트로그램을 인코딩 및 디코딩하는 오디오 VAE입니다.

text_encoder (`Gemma3ForConditionalGeneration` 또는 `Gemma4UnifiedForConditionalGeneration`) : 텍스트 인코더 모델.

tokenizer (`GemmaTokenizer` 또는 `GemmaTokenizerFast`) : 텍스트 인코더용 토크나이저.

connectors (`LTX2TextConnectors`) : 비디오 및 오디오 브랜치를 위해 텍스트 인코더의 히든 상태를 적응시키기 위해 사용되는 텍스트 커넥터 스택입니다.

transformer ([LTX2VideoTransformer3DModel](/docs/diffusers/main/ko/api/models/ltx2_video_transformer3d#diffusers.LTX2VideoTransformer3DModel)) : 인코딩된 비디오 잠재 변수를 디노이즈하기 위한 조건부 Transformer 아키텍처.

vocoder (`LTX2Vocoder` 또는 `LTX2VocoderWithBWE`): 멜 스펙트로그램을 오디오 웨이브폼으로 변환하는 Vocoder입니다.

processor (`ProcessorMixin`, *선택 사항*) : 프롬프트 강화용 채팅 템플릿팅에 사용되는 프로세서입니다.

prompt_enhancer (`Gemma4ForConditionalGeneration`, *선택 사항*) : 전용 프롬프트 향상 모델(LTX-2.5).

duration_head (`LTX2DurationHead`, *선택 사항*) : `num_frames`가 제공되지 않은 경우 프롬프트 임베딩에서 `num_frames`를 예측합니다.

LTX-2.5를 사용한 Diffusion Fidelity Rendering(DFR) 디노이즈 패스 1회용 파이프라인.

패스는 비디오와 추가적인 단일 픽셀 프레임의 키프레임 슬롯을 *그리고* 생성하거나, 해당 슬롯에서 시드된 제공된 잠재를 다시 디노이즈합니다. 호출자는 단계를 구성합니다: 이 파이프라인을 반 해상도로 실행하고, [LTX2LatentUpsamplePipeline](/docs/diffusers/main/ko/api/pipelines/ltx2#diffusers.LTX2LatentUpsamplePipeline)로 공간적으로 업샘플링한 뒤, 업샘플링된 슬롯과 IC-LoRA 참조를 사용하여 이 파이프라인을 전체 해상도로 다시 실행하고, 각 시간적 정제 라운드마다 [LTX2DFRTemporalRefinePipeline](/docs/diffusers/main/ko/api/pipelines/ltx2#diffusers.LTX2DFRTemporalRefinePipeline)를 실행합니다. 1080p 레시피에 대해서는 LTX-2 문서를 참조하세요.

Slot 위치는 VAE의 시간 경계에 정렬된 세그먼트 그리드(`resolve_canvas`)에서 가져옵니다. 캔버스는 세그먼트의 정수 배로 패딩되며, `output_type="latent"`는 패딩된 그리드를 반환하여 패딩 영역의 slot이 누락되지 않도록 합니다. VAE 디코딩 전에 `trim_canvas`로 잘라내야 합니다.

`generate_slots=True`인 경우, `use_keyframes_abs_pos_embedding`를 설정하는 config를 가진 transformer가 필요합니다(LTX-2.5 이상).

참고: https://github.com/Lightricks/LTX-2

#### __호출__[[diffusers.LTX2DFRPipeline.__call__]]

```python
__call__(prompt: str | list[str] = None, conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = None, height: int = 704, width: int = 1216, num_frames: int | None = None, frame_rate: float = 24.0, min_seconds: float = 1.0, max_seconds: float = 20.0, latents: typing.Optional[torch.Tensor] = None, audio_latents: typing.Optional[torch.Tensor] = None, keyframes_latents: typing.Optional[torch.Tensor] = None, keyframe_positions: list[int] | None = None, reference_latents: typing.Optional[torch.Tensor] = None, reference_downscale_factor: int = 2, guidance_keyframe_latents: typing.Optional[torch.Tensor] = None, guidance_keyframe_positions: list[int] | None = None, guidance_keyframe_strength: float = 1.0, generate_slots: bool = True, sigmas: list = [1.0, 0.99375, 0.9875, 0.98125, 0.975, 0.909375, 0.725, 0.421875], noise_scale: float | None = None, freeze_audio: bool = False, video_tiles: list[diffusers.pipelines.ltx2.dfr_layout.LTX2DFREpilogueTile] | None = None, num_videos_per_prompt: int | None = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, decode_timestep: float | list[float] = 0.0, decode_noise_scale: float | list[float] | None = None, use_cross_timestep: bool = True, system_prompt: str | None = None, enable_prompt_enhancement: bool = False, prompt_max_new_tokens: int | None = None, prompt_enhancement_kwargs: dict[str, typing.Any] | None = None, prompt_enhancement_seed: int = 10, output_type: str = 'pil', return_dict: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list = ['latents'], max_sequence_length: int = 1024)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr.py#L1522)

**매개변수:**

prompt (`str` 또는 `List[str]`, *선택 사항*) : 비디오 생성을 안내할 프롬프트입니다. 정의되지 않은 경우 `prompt_embeds`를 전달해야 합니다.

conditions (`LTX2VideoCondition` 또는 `List[LTX2VideoCondition]`, *optional*) : 프레임 수준의 이미지 또는 비디오 조건. `index`는 이 패스의 `num_frames`에 대한 *latent* 인덱스입니다.

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`, *선택 사항*) : 재디노이즈(2단계 / 에필로그)할 원시 `(batch_size, channels, frames, height, width)` 비디오 잠재 변수(latents).

audio_latents (`torch.Tensor`, *선택 사항*) : 원본 unpacked `(batch_size, channels, length, mel_bins)` 오디오 latents입니다. Stage 2는 여전히 joint audio pass를 실행하지만, 구성된 recipe의 shipped waveform은 stage 1의 것입니다. 호출자는 이를 유지합니다.

keyframes_latents (`torch.Tensor`, *선택 사항*) : `generate_slots=True`일 때 사용되는, `(batch_size, channels, num_slots, height, width)` 형식의 원시 슬롯 초기값입니다.

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`, *선택 사항*) : 고정된(raw pinned) 가이던스 키프레임 `(batch_size, channels, K, height, width)` — 에필로그 경로입니다. 생성되지 않은 슬롯입니다.

guidance_keyframe_positions (`list[int]`, *선택 사항*) : `guidance_keyframe_latents`의 픽셀 프레임 인덱스.

guidance_keyframe_strength (`float`, *선택 사항*, 기본값 `1.0`) : 고정된 가이던스 키프레임에 대한 조건화 강도입니다.

generate_slots (`bool`, *선택 사항*, 기본값 `True`) : 생성된 keyframe-slot 토큰을 추가합니다. epilogue는 이 값을 `False`로 설정하고 대신 `guidance_keyframe_latents`를 고정합니다.

sigmas (`list[float]`, *선택 사항*) : 이 패스에 대한 노이즈 스케줄이며, 종단 `0.0`은 제외됩니다.

noise_scale (`float`, *선택 사항*) : 무조건 토큰이 시작하는 노이즈 레벨입니다. 기본값은 `sigmas[0]`입니다.

freeze_audio (`bool`, *선택 사항*, 기본값 `False`) : 시그마 0에서 오디오를 유지합니다(에필로그 / 동결된 1단계 웨이브폼을 따르는 경우).

video_tiles (`list[LTX2DFREpilogueTile]`, *optional*) : `epilogue_tiles()`에서 가져온 Epilogue tiling입니다. 하나의 forward pass에 해상도가 너무 큰 경우에도 단일 canvas를 단계별로 처리할 수 있습니다. 각 단계에서 transformer가 타일당 한 번씩 실행되고 예측 결과가 블렌딩됩니다. 이 pass 자체의 RoPE 좌표에 대해 토큰 계획으로 해석되므로, 좌표는 [prepare_latents()](/docs/diffusers/main/ko/api/pipelines/ltx2#diffusers.LTX2DFRPipeline.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`) : 크로스 어텐션 변조를 위해 크로스 모달리티 시그마를 사용할지 여부. LTX-2.3+의 경우 `True`입니다.

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"` 중 하나를 선택합니다. Latent 출력은 트리밍되지 않은 캔버스입니다.

return_dict (`bool`, *선택 사항*, 기본값 `True`) : [LTX2DFRPipelineOutput](/docs/diffusers/main/ko/api/pipelines/ltx2#diffusers.LTX2DFRPipelineOutput)을 반환할지, 아니면 단순한 `(frames, audio, keyframes, keyframe_positions)` 튜플을 반환할지를 결정합니다.

attention_kwargs (`dict`, *선택 사항*) : attention processor에 전달되는 추가 kwargs입니다.

callback_on_step_end (`Callable`, *선택 사항*) : 각 디노이징 단계의 끝에서 호출되는 함수.

callback_on_step_end_tensor_inputs (`List`, *선택 사항*, 기본값 `["latents"]`) : 콜백 함수의 Tensor 입력입니다.

max_sequence_length (`int`, *선택 사항*, 기본값 `1024`) : 텍스트 프롬프트의 최대 시퀀스 길이입니다.

**반환값:** [LTX2DFRPipelineOutput](/docs/diffusers/main/ko/api/pipelines/ltx2#diffusers.LTX2DFRPipelineOutput) 또는 `tuple`

`return_dict`가 `True`인 경우 [LTX2DFRPipelineOutput](/docs/diffusers/main/ko/api/pipelines/ltx2#diffusers.LTX2DFRPipelineOutput)가 반환되고, 그렇지 않으면 `(video, audio, keyframes, keyframe_positions)`의 `tuple`이 반환됩니다.

생성을 위해 파이프라인을 호출할 때 호출되는 함수.

`height` × `width` 해상도로 denoise 패스를 한 번 수행합니다. 호출부에서 단계를 구성합니다: 이 파이프라인을 반 해상도로 실행하고, 공간적 업샘플링을 수행한 뒤, `latents` / `keyframes_latents` / `reference_latents`를 사용하여 이 파이프라인을 다시 실행하고, 각 시간적 라운드마다 [LTX2DFRTemporalRefinePipeline](/docs/diffusers/main/ko/api/pipelines/ltx2#diffusers.LTX2DFRTemporalRefinePipeline)을 실행합니다.

예:
```py
>>> 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[[diffusers.LTX2DFRPipeline.denoise]]

```python
denoise(latents: Tensor, conditioning_mask: Tensor, clean_latents: Tensor, video_coords: Tensor, keyframes_mask: Tensor, prompt_embeds: Tensor, audio_prompt_embeds: Tensor, prompt_attention_mask: Tensor, sigmas: list, frame_rate: float, audio_latents: Tensor, freeze_audio: bool = False, video_tile_plan: list | None = None, generator: typing.Optional[torch.Generator] = None, use_cross_timestep: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, progress_bar = None, step_offset: int = 0, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] | None = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr.py#L1225)

**매개변수:**

sigmas (`list[float]`) : 이 패스에 대한 노이즈 스케줄이며, 종단 `0.0`은 제외됩니다.

freeze_audio (`bool`, *선택 사항*, 기본값 `False`) : `audio_latents`를 깨끗한 상태(timestep/sigma 0, 오디오 Euler 단계 없음)로 유지하면서 오디오-비디오 크로스 어텐션을 계속 실행합니다. `audio_latents`가 `None`인 경우 무시됩니다.

video_tile_plan (`list`, *선택 사항*) : `video_tile_plan`[`~diffusers.pipelines.ltx2.dfr_layout.video_tile_plan`]에서 가져온 타일별 토큰 계획입니다. 이 값이 제공되면 각 단계에서 변환기가 타일별로 한 번씩 실행되고 예측 결과가 블렌딩되므로, 샘플러는 여전히 단일 전체 캔버스를 단계별로 처리하며 모든 단계에서 타일 간 겹치는 부분이 일치합니다.

generator (`torch.Generator`, *선택 사항*) : `LTXEulerAncestralRFScheduler.step()`으로 전달됩니다. 시간 타일은 타일별 시드를 전달하여, 선조 샘플링이 스트림을 공유하거나 다음 타일의 초기 노이즈가 읽는 상태를 소모하지 않도록 합니다. 디스틸드 Euler는 이를 읽지 않습니다.

step_offset (`int`) : 파이프라인 전체 스케줄 내에서 이 pass의 첫 번째 단계 인덱스입니다. `callback_on_step_end`와 공유 진행률 표시줄에 사용됩니다.

`sigmas`에 대해 DFR 노이즈 제거 패스를 한 번 실행하고, 둘 다 여전히 패킹된 상태인 `(latents, audio_latents)`를 반환합니다.

디스틸된 스케줄은 classifier-free guidance 없이 사용되므로, 각 단계마다 transformer 호출이 한 번만 수행됩니다. 비디오 브랜치는 생성된 오디오가 폐기되는 경우에도 cross-modal attention이 필요하기 때문에 모든 패스에서 두 스트림이 모두 실행됩니다. `freeze_audio=True`는 오디오 스트림을 sigma 0에 고정하여(Euler step 없음) 비디오가 여전히 해당 스트림에 cross-attend할 수 있도록 합니다. temporal refine tiles와 epilogue는 이를 사용하여 각 tile이 서로 다른 오디오 실현을 다시 denoise하지 않고 stage-1의 발화를 따르도록 합니다.

x0 conditioning blend 이후, velocity는 `(latents - denoised) / sigma`가 되므로 RF step `x0 = x - σ v`는 블렌딩된 `denoised`를 복원합니다. Stage 1 / 2 / epilogue는 [FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/ko/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)를 유지하고 해당 Euler step을 그대로 사용합니다. Temporal refine은 `LTXEulerAncestralRFScheduler`(`eta=0.5`)로 교체합니다. 이 step은 모든 토큰에 재노이즈를 적용하므로, 이후에 conditioning blend를 다시 적용하지 않으면 strength-0.95 seam 앵커가 침식됩니다.

#### encode_conditions[[diffusers.LTX2DFRPipeline.encode_conditions]]

```python
encode_conditions(conditions: list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None, height: int, width: int, num_frames: int, device: typing.Optional[torch.device] = None, dtype: typing.Optional[torch.dtype] = None, generator: typing.Optional[torch.Generator] = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr.py#L1189)

픽셀 프레임으로 위치를 지정하여 프레임 조건을 전처리하고 VAE 인코딩합니다.

각 조건별로 `(pixel_frame_index, latent, strength, num_pixel_frames)`을 반환하며, [prepare_latents()](/docs/diffusers/main/ko/api/pipelines/ltx2#diffusers.LTX2DFRPipeline.prepare_latents)의 `condition_latents`에 바로 사용할 수 있는 형태입니다. 인코딩은 배치와 분리되어 유지됩니다. 이는 temporal refine 라운드가 각 조건의 위치를 `2 ** round`로 스케일링하고 타일별로 기준을 재설정하기 때문에, 동일한 정지 프레임을 타일마다 다시 인코딩하지 않기 위함입니다.

반환된 인덱스는 `num_frames` 자체의 픽셀 그리드 기준입니다. 이를 정제된 캔버스에 매핑하는 것은 호출자의 책임입니다.

#### encode_prompt[[diffusers.LTX2DFRPipeline.encode_prompt]]

```python
encode_prompt(prompt: str | list[str], num_videos_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, max_sequence_length: int = 1024, device: typing.Optional[torch.device] = None, dtype: typing.Optional[torch.dtype] = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr.py#L529)

**매개변수:**

prompt (`str` 또는 `list[str]`, *선택 사항*) : 인코딩할 프롬프트

num_videos_per_prompt (`int`, *선택 사항*, 기본값 1) : 프롬프트당 생성할 비디오의 수.

prompt_embeds (`torch.Tensor`, *선택 사항*) : 미리 생성된 텍스트 임베딩입니다. *예를 들어* 프롬프트 가중치와 같은 텍스트 입력을 쉽게 조정하는 데 사용할 수 있습니다. 제공되지 않으면 `prompt` 입력 인자에서 텍스트 임베딩이 생성됩니다.

prompt_attention_mask (`torch.Tensor`, *선택 사항*) : `prompt_embeds`에 대한 사전 생성된 attention mask입니다.

device : (`torch.device`, *선택 사항*): torch device

dtype : (`torch.dtype`, *선택 사항*): torch dtype

프롬프트를 텍스트 인코더의 히든 상태로 인코딩합니다.

DFR은 classifier-free guidance 없이 사용하도록 학습된 distilled sigma schedule을 실행하므로, 여기에는 negative branch가 없습니다.

#### enhance_prompt[[diffusers.LTX2DFRPipeline.enhance_prompt]]

```python
enhance_prompt(prompt: str, system_prompt: str, max_new_tokens: int | None = None, seed: int = 10, generator: typing.Optional[torch.Generator] = None, generation_kwargs: dict[str, typing.Any] | None = None, device: typing.Union[str, torch.device, NoneType] = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr.py#L389)

`prompt`를 입력받아 프롬프트 강화기(Gemma 조건 생성 모델)와 시스템 프롬프트를 활용하여 새로운 프롬프트를 생성합니다. `image`가 제공되면, 강화기는 해당 참조 프레임에도 조건을 부여하여 강화합니다(I2V/키프레임 스타일 강화). `prompt_enhancer` 구성 요소가 설정되어 있으면(예: 강화용으로 학습되지 않은 텍스트 인코더를 사용하는 LTX-2.5) 이를 사용하고, 그렇지 않으면 자체 강화기로 기능하는 메인 `text_encoder`(LTX-2.0/2.3)로 대체합니다.

메시지 템플릿, 디코딩 kwargs, 응답 정제, 이미지 긴 변 준비는 `ltx-core` / `ltx-pipelines`의 `enhance_t2v` / `enhance_i2v` / `generate_enhanced_prompt`와 일치합니다.

#### prepare_latents[[diffusers.LTX2DFRPipeline.prepare_latents]]

```python
prepare_latents(conditions: list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = None, condition_latents: list[tuple[int, torch.Tensor, float, int]] | None = None, keyframe_latents: list[tuple[int, torch.Tensor, float]] | None = None, slot_frame_indices: list[int] | None = None, slot_initial_latents: typing.Optional[torch.Tensor] = None, reference_latents: typing.Optional[torch.Tensor] = None, reference_downscale_factor: int = 1, batch_size: int = 1, num_channels_latents: int = 128, height: int = 512, width: int = 768, num_frames: int = 121, frame_rate: float = 24.0, noise_scale: float = 1.0, dtype: typing.Optional[torch.dtype] = None, device: typing.Optional[torch.device] = None, generator: typing.Optional[torch.Generator] = None, latents: typing.Optional[torch.Tensor] = None, latents_normalized: bool = True)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr.py#L886)

**매개변수:**

conditions (`list[LTX2VideoCondition]`, *선택 사항*) : latent 인덱스로 위치가 지정되는 프레임 수준의 이미지/비디오 조건입니다.

condition_latents (`list[tuple[int, torch.Tensor, float, int]]`, *선택 사항*) : `conditions`의 이미 인코딩된 대체 값으로, `(pixel_frame_index, latent, strength, num_pixel_frames)` 형식입니다. temporal refine 라운드에서 조건의 위치가 `2 ** round` 배로 스케일링되고 그 결과가 일반적으로 latent 경계에 정확히 위치하지 않기 때문에, latent 인덱스가 아닌 픽셀 인덱스를 사용합니다. 해당 경계에 위치할 수 있는 것은 추가된 keyframe 토큰뿐이며, 이는 픽셀 기준으로 배치됩니다. `pixel_frame_index == 0`은 여전히 "첫 번째 프레임을 대체한다"는 의미를 가집니다.

keyframe_latents (`list[tuple[int, torch.Tensor, float]]`, *선택 사항*) : `(pixel_frame_index, latent, strength)` 형식으로 이미 인코딩된 keyframe guidance입니다. 여기서 `latent`의 shape은 `(batch_size, num_channels_latents, 1, latent_height, latent_width)`입니다. 이전 라운드에서 가져온 seam keyframe을 고정하기 위해 temporal refine 라운드에서 사용됩니다.

slot_frame_indices (`list[int]`, *선택 사항*) : 생성된 keyframe 슬롯의 픽셀 프레임 위치입니다.

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)` IC-LoRA 참조 latent.

reference_downscale_factor (`int`, 기본값 `1`) : 대상 해상도와 기준 해상도 사이의 비율.

latents (`torch.Tensor`, *선택 사항*) : `(batch_size, num_channels_latents, F, H, W)` 기본 토큰의 초기 내용입니다. 공개된 파이프라인의 latents는 원본(정규화되지 않은) 상태이므로 해당 경계에서는 `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`은 패킹된 시퀀스에서 생성된 keyframe slot token을 인덱싱하며, 요청된 slot이 없으면 `None`입니다.

DFR 디노이징 패스 하나를 위해 노이즈가 포함된 패킹된 비디오 라텐트를 준비합니다.

패킹된 시퀀스는 `[base | keyframes | slots | reference]`로 배치됩니다:

- Base tokens는 `latents`가 제공된 경우 이를 시드로 사용하여 대상 latent grid를 커버합니다.
- `index == 0`인 프레임 조건은 첫 번째 프레임 위치에 깨끗한 타겟을 설정하며, `index > 0`인 조건과 `keyframe_latents`의 모든 항목은 토큰별 조건화 마스크가 해당 강도와 같도록 추가 키프레임 토큰으로 추가됩니다.
- `slot_frame_indices`는 각 위치마다 *생성된* 키프레임 토큰을 1개 latent 프레임 분량씩 추가하며, 조건부 마스크는 `0`(완전히 디노이즈됨)이고 RoPE 시간 범위는 정확히 1개 픽셀 프레임입니다. 이는 DFR에 추가 프레임을 제공하는 키프레임 슬롯이며, `slot_initial_latents`가 해당 슬롯의 내용을 초기화합니다.
- `reference_latents`는 스테이지 1의 반해상도 latent를 완전히 깨끗한 IC-LoRA 참조로 추가하며, 공간 좌표는 `reference_downscale_factor`로 스케일링되어 대상 좌표 공간에 매핑됩니다.

추가된 conditioning 토큰은 `clean_latents`에 내용을, `latents`에는 0 플레이스홀더를 담고, keyframe 슬롯은 `latents`에 시드를, `clean_latents`에는 0을 담습니다. 반환되는 `latents`는 이 둘의 노이즈 혼합 결과입니다(해당 메서드 끝의 noising 단계 참조).

#### preprocess_conditions[[diffusers.LTX2DFRPipeline.preprocess_conditions]]

```python
preprocess_conditions(conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = None, height: int = 512, width: int = 768, num_frames: int = 121, device: typing.Optional[torch.device] = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr.py#L707)

**매개변수:**

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]]`

다음과 같이 `len(conditions)` 길이의 리스트 4개로 구성된 4-tuple을 반환합니다:
1. 첫 번째 목록은 [batch_size=1, num_channels, num_frames, height, width] 모양의 전처리된 비디오 텐서 목록입니다.
2. 두 번째 목록은 조건화 강도(conditioning strengths)의 목록입니다.
3. 세 번째 목록은 각 조건에 대한 잠재 공간 인덱스 목록입니다.
4. 네 번째 목록은 각 조건에 대한 (잘린) 픽셀 공간 프레임 수 목록입니다. 이는 키프레임 좌표 의미론에 필요합니다(단일 픽셀 프레임 키프레임은 클램프된 시간 범위를 가짐).

조건 이미지/영상을 torch 텐서로 전처리합니다.

#### rebuild_epilogue_keyframes[[diffusers.LTX2DFRPipeline.rebuild_epilogue_keyframes]]

```python
rebuild_epilogue_keyframes(keyframe_latents: Tensor, decode_timestep: float, decode_noise_scale: float, seed: int, device: device, dtype: dtype)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr.py#L1454)

**매개변수:**

keyframe_latents (`torch.Tensor`) : 이전 패스에서 반환된 대로, 원본 `(batch_size, C, K, H, W)` 키프레임

seed (`int`) : 기본 시드; 평면 `i`는 `seed + 4000 + i` 아래에서 디코딩되므로, 해당 평면의 픽셀은 그 이전에 디코딩된 평면의 수에 의존하지 않습니다.

**반환값:** `torch.Tensor`

`(batch_size, C, K, 2H, 2W)` 형태의 Raw latents로, `guidance_keyframe_latents`로 바로 다시 전달할 수 있는 상태입니다.

RGB를 통해 carry keyframe을 원래 해상도의 두 배로 재인코딩합니다.

이 프레임들은 refine 라운드에서 이미 결정된 것이므로, epilogue는 생성을 요청받지 않고 *주어지는* 상태입니다. 픽셀로 디코딩한 뒤 Lanczos로 2배 확대하고 다시 인코딩하면 프레임이 보존되면서 출력 그리드에 정확히 위치하게 되며, 이를 통해 epilogue가 프레임을 완전히 깨끗하게 고정할 수 있습니다.

각 평면은 자체의 1프레임 클립으로 디코딩됩니다. VAE는 인과적(causal)이므로, 스택된 디코딩을 사용하면 인접한 평면이 서로 영향을 미칩니다. 이들은 독립적인 정지 이미지이지 시퀀스가 아니기 때문입니다.

#### trim_conditioning_sequence[[diffusers.LTX2DFRPipeline.trim_conditioning_sequence]]

```python
trim_conditioning_sequence(start_frame: int, sequence_num_frames: int, target_num_frames: int)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr.py#L689)

**매개변수:**

start_frame (int) : 시퀀스의 첫 번째 프레임의 대상 프레임 번호.

sequence_num_frames (int) : 시퀀스의 프레임 수.

target_num_frames (int) : 생성된 비디오의 목표 프레임 수.

**반환값:** `int`

업데이트된 시퀀스 길이

조건부 시퀀스를 허용된 프레임 수로 잘라냅니다.

## LTX2DFRTemporalRefinePipeline[[diffusers.LTX2DFRTemporalRefinePipeline]]

#### diffusers.LTX2DFRTemporalRefinePipeline[[diffusers.LTX2DFRTemporalRefinePipeline]]

```python
diffusers.LTX2DFRTemporalRefinePipeline(scheduler: LTXEulerAncestralRFScheduler, vae: AutoencoderKLLTX2Video, audio_vae: AutoencoderKLLTX2Audio, text_encoder: transformers.models.gemma3.modeling_gemma3.Gemma3ForConditionalGeneration | transformers.models.gemma4_unified.modeling_gemma4_unified.Gemma4UnifiedForConditionalGeneration, tokenizer: GemmaTokenizer, connectors: LTX2TextConnectors, transformer: LTX2VideoTransformer3DModel, vocoder: diffusers.pipelines.ltx2.vocoder.LTX2Vocoder | diffusers.pipelines.ltx2.vocoder.LTX2VocoderWithBWE, temporal_latent_upsampler: LTX2LatentUpsamplerModel)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr_temporal_refine.py#L151)

**매개변수:**

scheduler (`LTXEulerAncestralRFScheduler`) : rectified-flow parameterization의 Ancestral Euler 스케줄러입니다. DFR temporal recipe와 일치하도록 `eta=0.5`로 구성하세요.

vae ([AutoencoderKLLTX2Video](/docs/diffusers/main/ko/api/models/autoencoderkl_ltx_2#diffusers.AutoencoderKLLTX2Video)) : 잠재 표현으로 비디오를 인코딩 및 디코딩하는 Variational Auto-Encoder (VAE) 모델.

audio_vae ([AutoencoderKLLTX2Audio](/docs/diffusers/main/ko/api/models/autoencoderkl_audio_ltx_2#diffusers.AutoencoderKLLTX2Audio)) : 오디오 스펙트로그램을 인코딩 및 디코딩하는 오디오 VAE입니다.

text_encoder (`Gemma3ForConditionalGeneration` 또는 `Gemma4UnifiedForConditionalGeneration`) : 텍스트 인코더 모델.

tokenizer (`GemmaTokenizer` 또는 `GemmaTokenizerFast`) : 텍스트 인코더용 토크나이저.

connectors (`LTX2TextConnectors`) : 비디오 및 오디오 브랜치를 위해 텍스트 인코더의 히든 상태를 적응시키기 위해 사용되는 텍스트 커넥터 스택입니다.

transformer ([LTX2VideoTransformer3DModel](/docs/diffusers/main/ko/api/models/ltx2_video_transformer3d#diffusers.LTX2VideoTransformer3DModel)) : 인코딩된 비디오 잠재 변수를 디노이즈하기 위한 조건부 Transformer 아키텍처.

vocoder (`LTX2Vocoder` 또는 `LTX2VocoderWithBWE`): 멜 스펙트로그램을 오디오 웨이브폼으로 변환하는 Vocoder입니다.

temporal_latent_upsampler (`LTX2LatentUpsamplerModel`) : 라운드의 시작 시점에 적용되는 Temporal x2 latent upsampler입니다.

One temporal DFR refine round: 캔버스를 시간 방향으로 2배 보간하고, 키프레임 경계에 타일링을 수행한 후 각 타일을 ancestral-denoise 처리합니다. 이후 뒤쪽 타일의 lead-in을 제거하여 스티칭하고, carry-keyframe bag을 병합합니다.

스케줄러는 `LTXEulerAncestralRFScheduler`입니다(기본값은 `eta=0.5`). Stage 1 / 2 / spatial epilogue는 [LTX2DFRPipeline](/docs/diffusers/main/ko/api/pipelines/ltx2#diffusers.LTX2DFRPipeline)을 통해 [FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/ko/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)를 유지합니다. 이 파이프라인은 라운드당 한 번 호출하며, 호출 측에서 2x / 4x를 반복합니다.

입력되는 `latents` / `keyframes_latents` / `audio_latents`는 정규화되지 않은 원시 값이며, [LTX2Pipeline](/docs/diffusers/main/ko/api/pipelines/ltx2#diffusers.LTX2Pipeline)과 일치합니다. `keyframe_positions`는 이전 패스에서 반환된 위치여야 하며, 라운드가 실행된 후에는 원래의 `num_frames`로부터 다시 도출할 수 없습니다.

#### __호출__[[diffusers.LTX2DFRTemporalRefinePipeline.__call__]]

```python
__call__(prompt: str | list[str] = None, latents: Tensor = None, keyframes_latents: Tensor = None, keyframe_positions: list = None, audio_latents: Tensor = None, conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = None, height: int = 704, width: int = 1216, num_frames: int = 121, frame_rate: float = 24.0, source_seconds: float | None = None, condition_num_frames: int | None = None, round_index: int = 1, sigmas: list = [0.975, 0.909375, 0.725, 0.421875], noise_scale: float | None = None, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, decode_timestep: float | list[float] = 0.0, decode_noise_scale: float | list[float] | None = None, use_cross_timestep: bool = True, output_type: str = 'pil', return_dict: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list = ['latents'], max_sequence_length: int = 1024)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr_temporal_refine.py#L1349)

**매개변수:**

prompt (`str` 또는 `List[str]`, *선택 사항*) : 비디오 생성을 안내할 프롬프트입니다. 정의되지 않은 경우 `prompt_embeds`를 전달해야 합니다.

latents (`torch.Tensor`) : **input** 캔버스의 원시 비디오 latents, `(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`) : 동결된 stage-1 오디오로, 언패킹 및 비정규화가 적용된 상태입니다. 각 타일에는 해당 재생 윈도우를 덮는 슬라이스가 전달되며, 반환되는 오디오는 타일별 재디노이즈가 아닌 이 웨이브폼입니다.

conditions (`LTX2VideoCondition` 또는 `List[LTX2VideoCondition]`, *optional*) : `condition_num_frames`(원본 요청)을 기준으로 인덱싱된 프레임 단위 조건입니다. 각 라운드에서 조건의 픽셀 위치를 `2 ** round_index`배로 스케일링합니다.

height (`int`, *선택 사항*, 기본값 `704`) : 이 패스의 픽셀 높이(들어오는 비디오와 동일).

width (`int`, *선택 사항*, 기본값 `1216`) : 이 패스의 픽셀 너비.

num_frames (`int`, *선택 사항*, 기본값 `121`) : **입력** 캔버스의 픽셀 프레임 수(트림 전).

frame_rate (`float`, *선택 사항*, 기본값 `24.0`) : **입력**의 재생 fps입니다. round가 이를 두 배로 만듭니다.

source_seconds (`float`, *선택 사항*) : 동결된 stage-1 오디오의 길이입니다. 기본값은 `num_frames / frame_rate`이며, 이는 첫 번째 라운드에서 올바른 값입니다. 이후 라운드에서는 타일이 어긋나지 않도록 원래의 stage-1 길이를 전달해야 합니다.

condition_num_frames (`int`, *선택 사항*) : `conditions`을 인코딩하는 데 사용된 원래 생성 `num_frames`입니다. 기본값은 `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`) : 크로스 어텐션 변조를 위해 크로스 모달리티 시그마를 사용할지 여부. LTX-2.3+의 경우 `True`입니다.

output_type (`str`, *선택 사항*, 기본값 `"pil"`) : 출력 형식. `"pil"`, `"np"`, `"pt"` 또는 `"latent"` 중 하나를 선택합니다. Latent 출력은 트리밍되지 않은 캔버스입니다.

return_dict (`bool`, *선택 사항*, 기본값 `True`) : [LTX2DFRPipelineOutput](/docs/diffusers/main/ko/api/pipelines/ltx2#diffusers.LTX2DFRPipelineOutput)을 반환할지, 아니면 단순한 `(frames, audio, keyframes, keyframe_positions)` 튜플을 반환할지를 결정합니다.

attention_kwargs (`dict`, *선택 사항*) : attention processor에 전달되는 추가 kwargs입니다.

callback_on_step_end (`Callable`, *선택 사항*) : 모든 타일에서 각 디노이징 단계의 끝에서 호출되는 함수입니다.

callback_on_step_end_tensor_inputs (`List`, *선택 사항*, 기본값 `["latents"]`) : 콜백 함수의 Tensor 입력입니다.

max_sequence_length (`int`, *선택 사항*, 기본값 `1024`) : 텍스트 프롬프트의 최대 시퀀스 길이입니다.

**반환값:** [LTX2DFRPipelineOutput](/docs/diffusers/main/ko/api/pipelines/ltx2#diffusers.LTX2DFRPipelineOutput) 또는 `tuple`

`return_dict`가 `True`인 경우 [LTX2DFRPipelineOutput](/docs/diffusers/main/ko/api/pipelines/ltx2#diffusers.LTX2DFRPipelineOutput)가 반환되고, 그렇지 않으면 `(video, audio, keyframes, keyframe_positions)`의 `tuple`이 반환됩니다.

temporal refine 라운드를 한 번 실행합니다.

예:
```py
>>> 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[[diffusers.LTX2DFRTemporalRefinePipeline.denoise]]

```python
denoise(latents: Tensor, conditioning_mask: Tensor, clean_latents: Tensor, video_coords: Tensor, keyframes_mask: Tensor, prompt_embeds: Tensor, audio_prompt_embeds: Tensor, prompt_attention_mask: Tensor, sigmas: list, frame_rate: float, audio_latents: Tensor, freeze_audio: bool = False, video_tile_plan: list | None = None, generator: typing.Optional[torch.Generator] = None, use_cross_timestep: bool = True, attention_kwargs: dict[str, typing.Any] | None = None, progress_bar = None, step_offset: int = 0, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] | None = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr_temporal_refine.py#L1138)

**매개변수:**

sigmas (`list[float]`) : 이 패스에 대한 노이즈 스케줄이며, 종단 `0.0`은 제외됩니다.

freeze_audio (`bool`, *선택 사항*, 기본값 `False`) : `audio_latents`를 깨끗한 상태(timestep/sigma 0, 오디오 Euler 단계 없음)로 유지하면서 오디오-비디오 크로스 어텐션을 계속 실행합니다. `audio_latents`가 `None`인 경우 무시됩니다.

video_tile_plan (`list`, *선택 사항*) : `video_tile_plan`[`~diffusers.pipelines.ltx2.dfr_layout.video_tile_plan`]에서 가져온 타일별 토큰 계획입니다. 이 값이 제공되면 각 단계에서 변환기가 타일별로 한 번씩 실행되고 예측 결과가 블렌딩되므로, 샘플러는 여전히 단일 전체 캔버스를 단계별로 처리하며 모든 단계에서 타일 간 겹치는 부분이 일치합니다.

generator (`torch.Generator`, *선택 사항*) : `LTXEulerAncestralRFScheduler.step()`으로 전달됩니다. 시간 타일은 타일별 시드를 전달하여, 선조 샘플링이 스트림을 공유하거나 다음 타일의 초기 노이즈가 읽는 상태를 소모하지 않도록 합니다. 디스틸드 Euler는 이를 읽지 않습니다.

step_offset (`int`) : 파이프라인 전체 스케줄 내에서 이 pass의 첫 번째 단계 인덱스입니다. `callback_on_step_end`와 공유 진행률 표시줄에 사용됩니다.

`sigmas`에 대해 DFR 노이즈 제거 패스를 한 번 실행하고, 둘 다 여전히 패킹된 상태인 `(latents, audio_latents)`를 반환합니다.

디스틸된 스케줄은 classifier-free guidance 없이 사용되므로, 각 단계마다 transformer 호출이 한 번만 수행됩니다. 비디오 브랜치는 생성된 오디오가 폐기되는 경우에도 cross-modal attention이 필요하기 때문에 모든 패스에서 두 스트림이 모두 실행됩니다. `freeze_audio=True`는 오디오 스트림을 sigma 0에 고정하여(Euler step 없음) 비디오가 여전히 해당 스트림에 cross-attend할 수 있도록 합니다. temporal refine tiles와 epilogue는 이를 사용하여 각 tile이 서로 다른 오디오 실현을 다시 denoise하지 않고 stage-1의 발화를 따르도록 합니다.

x0 conditioning blend 이후, velocity는 `(latents - denoised) / sigma`가 되므로 RF step `x0 = x - σ v`는 블렌딩된 `denoised`를 복원합니다. Stage 1 / 2 / epilogue는 [FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/ko/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)를 유지하고 해당 Euler step을 그대로 사용합니다. Temporal refine은 `LTXEulerAncestralRFScheduler`(`eta=0.5`)로 교체합니다. 이 step은 모든 토큰에 재노이즈를 적용하므로, 이후에 conditioning blend를 다시 적용하지 않으면 strength-0.95 seam 앵커가 침식됩니다.

#### encode_conditions[[diffusers.LTX2DFRTemporalRefinePipeline.encode_conditions]]

```python
encode_conditions(conditions: list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None, height: int, width: int, num_frames: int, device: typing.Optional[torch.device] = None, dtype: typing.Optional[torch.dtype] = None, generator: typing.Optional[torch.Generator] = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr_temporal_refine.py#L1101)

픽셀 프레임으로 위치를 지정하여 프레임 조건을 전처리하고 VAE 인코딩합니다.

각 조건별로 `(pixel_frame_index, latent, strength, num_pixel_frames)`을 반환하며, [prepare_latents()](/docs/diffusers/main/ko/api/pipelines/ltx2#diffusers.LTX2DFRPipeline.prepare_latents)의 `condition_latents`에 바로 사용할 수 있는 형태입니다. 인코딩은 배치와 분리되어 유지됩니다. 이는 temporal refine 라운드가 각 조건의 위치를 `2 ** round`로 스케일링하고 타일별로 기준을 재설정하기 때문에, 동일한 정지 프레임을 타일마다 다시 인코딩하지 않기 위함입니다.

반환된 인덱스는 `num_frames` 자체의 픽셀 그리드 기준입니다. 이를 정제된 캔버스에 매핑하는 것은 호출자의 책임입니다.

#### encode_prompt[[diffusers.LTX2DFRTemporalRefinePipeline.encode_prompt]]

```python
encode_prompt(prompt: str | list[str], num_videos_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, max_sequence_length: int = 1024, device: typing.Optional[torch.device] = None, dtype: typing.Optional[torch.dtype] = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr_temporal_refine.py#L470)

**매개변수:**

prompt (`str` 또는 `list[str]`, *선택 사항*) : 인코딩할 프롬프트

num_videos_per_prompt (`int`, *선택 사항*, 기본값 1) : 프롬프트당 생성할 비디오의 수.

prompt_embeds (`torch.Tensor`, *선택 사항*) : 미리 생성된 텍스트 임베딩입니다. *예를 들어* 프롬프트 가중치와 같은 텍스트 입력을 쉽게 조정하는 데 사용할 수 있습니다. 제공되지 않으면 `prompt` 입력 인자에서 텍스트 임베딩이 생성됩니다.

prompt_attention_mask (`torch.Tensor`, *선택 사항*) : `prompt_embeds`에 대한 사전 생성된 attention mask입니다.

device : (`torch.device`, *선택 사항*): torch device

dtype : (`torch.dtype`, *선택 사항*): torch dtype

프롬프트를 텍스트 인코더의 히든 상태로 인코딩합니다.

DFR은 classifier-free guidance 없이 사용하도록 학습된 distilled sigma schedule을 실행하므로, 여기에는 negative branch가 없습니다.

#### prepare_latents[[diffusers.LTX2DFRTemporalRefinePipeline.prepare_latents]]

```python
prepare_latents(conditions: list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = None, condition_latents: list[tuple[int, torch.Tensor, float, int]] | None = None, keyframe_latents: list[tuple[int, torch.Tensor, float]] | None = None, slot_frame_indices: list[int] | None = None, slot_initial_latents: typing.Optional[torch.Tensor] = None, reference_latents: typing.Optional[torch.Tensor] = None, reference_downscale_factor: int = 1, batch_size: int = 1, num_channels_latents: int = 128, height: int = 512, width: int = 768, num_frames: int = 121, frame_rate: float = 24.0, noise_scale: float = 1.0, dtype: typing.Optional[torch.dtype] = None, device: typing.Optional[torch.device] = None, generator: typing.Optional[torch.Generator] = None, latents: typing.Optional[torch.Tensor] = None, latents_normalized: bool = True)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr_temporal_refine.py#L828)

**매개변수:**

conditions (`list[LTX2VideoCondition]`, *선택 사항*) : latent 인덱스로 위치가 지정되는 프레임 수준의 이미지/비디오 조건입니다.

condition_latents (`list[tuple[int, torch.Tensor, float, int]]`, *선택 사항*) : `conditions`의 이미 인코딩된 대체 값으로, `(pixel_frame_index, latent, strength, num_pixel_frames)` 형식입니다. temporal refine 라운드에서 조건의 위치가 `2 ** round` 배로 스케일링되고 그 결과가 일반적으로 latent 경계에 정확히 위치하지 않기 때문에, latent 인덱스가 아닌 픽셀 인덱스를 사용합니다. 해당 경계에 위치할 수 있는 것은 추가된 keyframe 토큰뿐이며, 이는 픽셀 기준으로 배치됩니다. `pixel_frame_index == 0`은 여전히 "첫 번째 프레임을 대체한다"는 의미를 가집니다.

keyframe_latents (`list[tuple[int, torch.Tensor, float]]`, *선택 사항*) : `(pixel_frame_index, latent, strength)` 형식으로 이미 인코딩된 keyframe guidance입니다. 여기서 `latent`의 shape은 `(batch_size, num_channels_latents, 1, latent_height, latent_width)`입니다. 이전 라운드에서 가져온 seam keyframe을 고정하기 위해 temporal refine 라운드에서 사용됩니다.

slot_frame_indices (`list[int]`, *선택 사항*) : 생성된 keyframe 슬롯의 픽셀 프레임 위치입니다.

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)` IC-LoRA 참조 latent.

reference_downscale_factor (`int`, 기본값 `1`) : 대상 해상도와 기준 해상도 사이의 비율.

latents (`torch.Tensor`, *선택 사항*) : `(batch_size, num_channels_latents, F, H, W)` 기본 토큰의 초기 내용입니다. 공개된 파이프라인의 latents는 원본(정규화되지 않은) 상태이므로 해당 경계에서는 `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`은 패킹된 시퀀스에서 생성된 keyframe slot token을 인덱싱하며, 요청된 slot이 없으면 `None`입니다.

DFR 디노이징 패스 하나를 위해 노이즈가 포함된 패킹된 비디오 라텐트를 준비합니다.

패킹된 시퀀스는 `[base | keyframes | slots | reference]`로 배치됩니다:

- Base tokens는 `latents`가 제공된 경우 이를 시드로 사용하여 대상 latent grid를 커버합니다.
- `index == 0`인 프레임 조건은 첫 번째 프레임 위치에 깨끗한 타겟을 설정하며, `index > 0`인 조건과 `keyframe_latents`의 모든 항목은 토큰별 조건화 마스크가 해당 강도와 같도록 추가 키프레임 토큰으로 추가됩니다.
- `slot_frame_indices`는 각 위치마다 *생성된* 키프레임 토큰을 1개 latent 프레임 분량씩 추가하며, 조건부 마스크는 `0`(완전히 디노이즈됨)이고 RoPE 시간 범위는 정확히 1개 픽셀 프레임입니다. 이는 DFR에 추가 프레임을 제공하는 키프레임 슬롯이며, `slot_initial_latents`가 해당 슬롯의 내용을 초기화합니다.
- `reference_latents`는 스테이지 1의 반해상도 latent를 완전히 깨끗한 IC-LoRA 참조로 추가하며, 공간 좌표는 `reference_downscale_factor`로 스케일링되어 대상 좌표 공간에 매핑됩니다.

추가된 conditioning 토큰은 `clean_latents`에 내용을, `latents`에는 0 플레이스홀더를 담고, keyframe 슬롯은 `latents`에 시드를, `clean_latents`에는 0을 담습니다. 반환되는 `latents`는 이 둘의 노이즈 혼합 결과입니다(해당 메서드 끝의 noising 단계 참조).

#### preprocess_conditions[[diffusers.LTX2DFRTemporalRefinePipeline.preprocess_conditions]]

```python
preprocess_conditions(conditions: diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition | list[diffusers.pipelines.ltx2.pipeline_ltx2_condition.LTX2VideoCondition] | None = None, height: int = 512, width: int = 768, num_frames: int = 121, device: typing.Optional[torch.device] = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr_temporal_refine.py#L648)

**매개변수:**

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]]`

다음과 같이 `len(conditions)` 길이의 리스트 4개로 구성된 4-tuple을 반환합니다:
1. 첫 번째 목록은 [batch_size=1, num_channels, num_frames, height, width] 모양의 전처리된 비디오 텐서 목록입니다.
2. 두 번째 목록은 조건화 강도(conditioning strengths)의 목록입니다.
3. 세 번째 목록은 각 조건에 대한 잠재 공간 인덱스 목록입니다.
4. 네 번째 목록은 각 조건에 대한 (잘린) 픽셀 공간 프레임 수 목록입니다. 이는 키프레임 좌표 의미론에 필요합니다(단일 픽셀 프레임 키프레임은 클램프된 시간 범위를 가짐).

조건 이미지/영상을 torch 텐서로 전처리합니다.

#### trim_conditioning_sequence[[diffusers.LTX2DFRTemporalRefinePipeline.trim_conditioning_sequence]]

```python
trim_conditioning_sequence(start_frame: int, sequence_num_frames: int, target_num_frames: int)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr_temporal_refine.py#L630)

**매개변수:**

start_frame (int) : 시퀀스의 첫 번째 프레임의 대상 프레임 번호.

sequence_num_frames (int) : 시퀀스의 프레임 수.

target_num_frames (int) : 생성된 비디오의 목표 프레임 수.

**반환값:** `int`

업데이트된 시퀀스 길이

조건부 시퀀스를 허용된 프레임 수로 잘라냅니다.

#### upsample_latents[[diffusers.LTX2DFRTemporalRefinePipeline.upsample_latents]]

```python
upsample_latents(latents: Tensor, upsampler: LTX2LatentUpsamplerModel)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_dfr_temporal_refine.py#L1090)

`upsampler`를 정규화된 latents에 실행합니다. `upsampler`가 기대하는 대로 raw VAE latent space를 경유합니다.

## LTX2DFRPipelineOutput[[diffusers.LTX2DFRPipelineOutput]]

#### diffusers.LTX2DFRPipelineOutput[[diffusers.LTX2DFRPipelineOutput]]

```python
diffusers.LTX2DFRPipelineOutput(frames: Tensor, audio: Tensor, keyframes: typing.Optional[torch.Tensor] = None, keyframe_positions: list[int] | None = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_output.py#L27)

**매개변수:**

frames (`torch.Tensor`, `np.ndarray`, 또는 list[list[PIL.Image.Image]]) : 노이즈가 제거된 비디오. Latent 출력은 트리밍되지 않은 캔버스이며, shape은 `(batch_size, num_channels, latent_frames, latent_height, latent_width)`입니다.

audio (`torch.Tensor`, `np.ndarray`) : 해당 오디오의 잠재 변수(latents) 또는 웨이브폼.

keyframes (`torch.Tensor`, *선택 사항*) : `(batch_size, num_channels, num_keyframes, latent_height, latent_width)` 형식의 생성되거나 전달된 keyframe latents입니다. `output_type != "latent"`인 경우 또는 패스가 슬롯을 생성하지 않은 경우(예: tiled epilogue)에는 `None`입니다.

keyframe_positions (`list[int]`, *선택 사항*) : 이 pass의 캔버스에서 각 keyframe의 픽셀 프레임 인덱스입니다. `keyframes`가 `None`인 경우 `None`입니다. 시간적 라운드 이후에는 원래의 `num_frames`에서 다시 유도할 수 없으므로 다음 단계로 전달해야 합니다.

DFR 파이프라인의 출력 클래스입니다.

## LTX2LatentUpsamplePipeline[[diffusers.LTX2LatentUpsamplePipeline]]

#### diffusers.LTX2LatentUpsamplePipeline[[diffusers.LTX2LatentUpsamplePipeline]]

```python
diffusers.LTX2LatentUpsamplePipeline(vae: AutoencoderKLLTX2Video, latent_upsampler: LTX2LatentUpsamplerModel)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_latent_upsample.py#L104)

#### __호출__[[diffusers.LTX2LatentUpsamplePipeline.__call__]]

```python
__call__(video: list[typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]] | None = None, height: int = 512, width: int = 768, num_frames: int = 121, spatial_patch_size: int = 1, temporal_patch_size: int = 1, latents: typing.Optional[torch.Tensor] = None, latents_normalized: bool = False, decode_timestep: float | list[float] = 0.0, decode_noise_scale: float | list[float] | None = None, adain_factor: float = 0.0, tone_map_compression_ratio: float = 0.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, output_type: str | None = 'pil', return_dict: bool = True)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_latent_upsample.py#L264)

**매개변수:**

video (`list[PipelineImageInput]`, *선택 사항*) : 업샘플링할 비디오(예: LTX 2.0 1단계 출력). 제공되지 않으면 `latents`를 제공해야 합니다.

height (`int`, *선택 사항*, 기본값 `512`) : 입력 비디오의 픽셀 단위 높이(생성된 비디오는 더 높은 해상도를 가지므로 해당되지 않음).

width (`int`, *선택 사항*, 기본값 `768`) : 입력 비디오의 픽셀 단위 너비입니다(생성된 비디오는 더 높은 해상도를 가지므로 해당되지 않습니다).

num_frames (`int`, *선택 사항*, 기본값 `121`) : 입력 비디오의 프레임 수입니다.

spatial_patch_size (`int`, *선택 사항*, 기본값 `1`) : 비디오 latents의 공간 패치 크기입니다. `latents`가 제공되고 unpacking이 필요한 경우 사용됩니다.

temporal_patch_size (`int`, *선택 사항*, 기본값 `1`) : 비디오 latents의 temporal patch size입니다. `latents`가 제공되고 unpacking이 필요한 경우 사용됩니다.

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 latent의 평균과 표준편차로 정규화되었는지 여부입니다. `True`인 경우, `latents`는 latent upsampler에 전달되기 전에 비정규화됩니다.

decode_timestep (`float`, 기본값 `0.0`) : 생성된 비디오가 디코딩되는 타임스텝입니다.

decode_noise_scale (`float`, 기본값 `None`) : 디코딩 타임스텝에서 랜덤 노이즈와 디노이즈된 레이턴트 사이의 보간 계수입니다.

adain_factor (`float`, *선택 사항*, 기본값 `0.0`) : 업샘플링된 latent와 원래 latent 사이의 Adaptive Instance Normalization(AdaIN) 블렌딩 계수. 값은 [-10.0, 10.0] 범위에 있어야 하며, 0.0(기본값)을 지정하면 AdaIN이 수행되지 않습니다.

tone_map_compression_ratio (`float`, *선택 사항*, 기본값 `0.0`) : 톤 매핑을 위한 압축 강도로, latent 값의 동적 범위를 줄입니다. 이는 높은 분산의 latent를 정규화하거나 생성 과정에서 출력을 조건부로 제어하는 데 유용합니다. 값은 [0, 1] 범위에 있어야 하며, 0.0(기본값)은 톤 매핑이 적용되지 않음을, 1.0은 완전한 압축 효과를 나타냅니다.

generator (`torch.Generator` 또는 `list[torch.Generator]`, *선택 사항*) : 생성을 결정적으로 만들기 위한 [torch generator](https://pytorch.org/docs/stable/generated/torch.Generator.html) 하나 또는 목록.

output_type (`str`, *선택 사항*, 기본값 `"pil"`) : 이미지 생성의 출력 형식입니다. [PIL](https://pillow.readthedocs.io/en/stable/): `PIL.Image.Image` 또는 `np.array` 중 하나를 선택합니다.

return_dict (`bool`, *선택 사항*, 기본값 `True`) : 일반 튜플 대신 `~pipelines.ltx.LTXPipelineOutput`을 반환할지 여부.

**반환값:** `~pipelines.ltx.LTXPipelineOutput` 또는 `tuple`

`return_dict`가 `True`인 경우 `~pipelines.ltx.LTXPipelineOutput`가 반환되고, 그렇지 않으면 첫 번째 요소가 업샘플링된 비디오인 `tuple`이 반환됩니다.

생성을 위해 파이프라인을 호출할 때 호출되는 함수.

예:
```py
>>> 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[[diffusers.LTX2LatentUpsamplePipeline.adain_filter_latent]]

```python
adain_filter_latent(latents: Tensor, reference_latents: Tensor, factor: float = 1.0)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_latent_upsample.py#L168)

**매개변수:**

latents (`torch.Tensor`) : 정규화할 입력 latents

reference_latents (`torch.Tensor`) : 스타일 통계를 제공하는 참조 잠재 변수(latents).

factor (`float`) : 원본과 변환된 latent 사이의 블렌딩 계수. 범위: -10.0에서 10.0, 기본값: 1.0

**반환값:** `torch.Tensor`

변환된 잠재 텐서

참조 latent tensor의 통계량을 기반으로 latent tensor에 Adaptive Instance Normalization(AdaIN)을 적용합니다.

#### tone_map_latents[[diffusers.LTX2LatentUpsamplePipeline.tone_map_latents]]

```python
tone_map_latents(latents: Tensor, compression: float)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_latent_upsample.py#L196)

**매개변수:**

latents : torch.Tensor 임의의 형태를 가진 입력 잠재 텐서. 대략 [-1, 1] 또는 [0, 1] 범위에 있을 것으로 예상됩니다.

compression : float [0, 1] 범위의 압축 강도. - 0.0: 톤 매핑 없음(항등 변환) - 1.0: 전체 압축 효과

**반환값:**

torch.Tensor 입력과 동일한 shape를 가진 tone-mapped latent tensor.

시그모이드 기반 압축을 사용하여 잠재 값의 동적 범위를 지각적으로 매끄러운 방식으로 줄이기 위해 비선형 톤 매핑 함수를 적용합니다.

`compression` 계수로 동적 동작을 제어하는 경우를 포함하여, 생성 과정에서 출력을 조건화하거나 높은 분산의 latents를 정규화하는 데 유용합니다.

## LTX2VideoDiffusionDecodePipeline[[diffusers.LTX2VideoDiffusionDecodePipeline]]

#### diffusers.LTX2VideoDiffusionDecodePipeline[[diffusers.LTX2VideoDiffusionDecodePipeline]]

```python
diffusers.LTX2VideoDiffusionDecodePipeline(diffusion_decoder: LTX2VideoDiffusionDecoderModel, scheduler, vae: AutoencoderKLLTX2Video = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_diffusion_decode.py#L27)

**매개변수:**

diffusion_decoder ([LTX2VideoDiffusionDecoderModel](/docs/diffusers/main/ko/api/models/ltx2_diffusion_decoder#diffusers.LTX2VideoDiffusionDecoderModel)) : 확산 비디오 디코더입니다.

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/ko/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : 디코더의 디노이징 단계를 제어하는 스케줄러.

vae ([AutoencoderKLLTX2Video](/docs/diffusers/main/ko/api/models/autoencoderkl_ltx_2#diffusers.AutoencoderKLLTX2Video), *선택 사항*) : 비정규화(denormalize)에 사용되는 잠재 통계(latent statistics)를 조회할 때만 참조됩니다. 이 인수를 생략하면 파이프라인은 LTX-2 기본값으로 폴백되므로, 디코딩 전용 워크플로에서는 두 번째 오토인코더를 로드할 필요가 없습니다.

LTX-2.5에서 소개된 diffusion decoder를 사용하여 LTX-2 비디오 latents를 디코딩합니다.

컨볼루션 디코더와 달리 이 디코더는 자체적으로 작은 diffusion 모델입니다: latent에서 구축된 context volume에 조건부 설정하여 픽셀의 노이즈를 제거하므로, scheduler와 generator가 필요합니다. `output_type="latent"`로 실행된 LTX-2 파이프라인과 함께 사용하며, 해당 경로에서 이미 latent 통계가 적용되었으므로 `denormalize=False`를 전달합니다.

#### __호출__[[diffusers.LTX2VideoDiffusionDecodePipeline.__call__]]

```python
__call__(latents: Tensor, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, output_type: str = 'pil', return_dict: bool = True, denormalize: bool = True)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_ltx2_diffusion_decode.py#L79)

**매개변수:**

latents (`torch.Tensor`) : `(B, C, F, H, W)` 형태의 Latents. `output_type="latent"`로 실행된 LTX-2 파이프라인은 *이미* 비정규화된 latents를 반환하므로, 해당 경우 `denormalize=False`를 전달하세요.

generator (`torch.Generator`, *선택 사항*) : 디코더는 노이즈를 제거할 노이즈를 샘플링하므로, 디코딩을 재현 가능하게 하려면 생성자를 전달하세요.

output_type (`str`, *선택 사항*, 기본값 `"pil"`) : 디코딩된 비디오의 출력 형식입니다. `"pil"`, `"np"`, `"pt"`, `"latent"` 중 하나를 선택합니다.

return_dict (`bool`, *선택 사항*, 기본값 `True`) : 일반 튜플 대신 `LTX2VideoDecodeOutput`를 반환할지 여부.

denormalize (`bool`, *선택 사항*, 기본값 `True`) : 디코딩 전에 잠재 변수 통계량을 적용할지 여부입니다. 잠재 변수가 이미 비정규화(denormalized)된 경우 `False`로 설정하세요.

**반환값:** `LTX2VideoDecodeOutput` 또는 `tuple`

## LTX2DurationHead[[diffusers.pipelines.ltx2.LTX2DurationHead]]

#### diffusers.pipelines.ltx2.LTX2DurationHead[[diffusers.pipelines.ltx2.LTX2DurationHead]]

```python
diffusers.pipelines.ltx2.LTX2DurationHead(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)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/duration_head.py#L81)

**매개변수:**

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`) : pooler가 사용하는 Attention heads의 수.

mlp_hidden_dim (`int`, 기본값 `256`) : 출력 MLP의 숨겨진 폭입니다. `mlp_hidden` 서브모듈과 충돌을 피하기 위해 `_dim` 접미사를 붙여 이름을 지었습니다. 그렇지 않으면 `ConfigMixin.__getattr__`가 이 설정 값으로 해당 서브모듈을 가리게 됩니다.

LTX-2 텍스트 커넥터 출력에서 캡션이 암시하는 샷의 자연스러운 길이를 예측합니다.

head는 모달리티에 무관합니다: video와 audio 커넥터 출력 중 하나 또는 둘 다를 전달할 수 있습니다. 모달리티별 입력 투영은 각 스트림을 공유된 pooler 차원으로 매핑하고, 학습 가능한 모달리티 임베딩은 pooler가 스트림을 구별할 수 있도록 태그를 부여하며, 작은 MLP는 풀링된 벡터를 log-duration으로 변환합니다. 회귀 목표는 log-초 단위로 학습되므로 `forward`는 지수 함수를 적용하여 호출자는 항상 초 단위의 값을 얻습니다.

LTX-2.5 체크포인트부터 제공됩니다.

#### forward[[diffusers.pipelines.ltx2.LTX2DurationHead.forward]]

```python
forward(video_tokens: typing.Optional[torch.Tensor] = None, audio_tokens: typing.Optional[torch.Tensor] = None)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/duration_head.py#L134)

**매개변수:**

video_tokens (`torch.Tensor`, shape `(batch_size, seq_len, video_cross_attention_dim)`, *선택 사항*) : 비디오 커넥터 출력.

audio_tokens (`torch.Tensor`, shape `(batch_size, seq_len, audio_cross_attention_dim)`, *선택 사항*) : 오디오 커넥터 출력.

**반환값:** `torch.Tensor`, shape `(batch_size,)`

초 단위로 예측된 지속 시간입니다.

#### predict_num_frames[[diffusers.pipelines.ltx2.LTX2DurationHead.predict_num_frames]]

```python
predict_num_frames(video_tokens: typing.Optional[torch.Tensor] = None, audio_tokens: typing.Optional[torch.Tensor] = None, frame_rate: float, temporal_compression_ratio: int, min_seconds: float = 1.0, max_seconds: float = 20.0)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/duration_head.py#L172)

**매개변수:**

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`)에 스냅됩니다.

클램프는 스냅핑 전에 적용됩니다. 클램프된 프레임 수는 그리드에 정렬되지 않을 수 있으므로, 스냅핑을 먼저 수행하면 결과가 달라집니다. 스냅핑은 버림(floor)을 수행하므로 최소값보다 아래에 위치할 수 있습니다. 이 경우 프레임 수가 범위를 벗어나지 않도록 다음 그리드 포인트로 위로 스냅핑됩니다.

좁은 범위는 그리드 포인트가 전혀 없는 프레임 윈도우로 변환될 수 있습니다. 24 fps에서 `[1.0s, 1.02s]`은 `[24, 24]`으로 반올림되며, 24는 `8k + 1`이 아닙니다. 이 경우 가장 가까운 그리드 포인트가 사용되고 경고가 기록됩니다. 그리드 스텝 하나 미만의 초과가 생성을 거부하는 것보다 나쁘지 않기 때문입니다. 따라서 반환되는 개수는 항상 그리드 위에 있지만, 이 경우 요청된 범위를 약간 벗어날 수 있습니다.

## LTX2PipelineOutput[[diffusers.pipelines.ltx2.LTX2PipelineOutput]]

#### diffusers.pipelines.ltx2.LTX2PipelineOutput[[diffusers.pipelines.ltx2.LTX2PipelineOutput]]

```python
diffusers.pipelines.ltx2.LTX2PipelineOutput(frames: Tensor, audio: Tensor)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ltx2/pipeline_output.py#L9)

**매개변수:**

frames (`torch.Tensor`, `np.ndarray`, 또는 list[list[PIL.Image.Image]]) : 비디오 출력 목록 - `batch_size,` 길이의 중첩 목록일 수 있으며, 각 하위 목록에는 `num_frames.` 길이의 노이즈 제거된 PIL 이미지 시퀀스가 포함됩니다. 또한 `(batch_size, num_frames, channels, height, width)` 형상의 NumPy 배열 또는 Torch 텐서일 수도 있습니다.

audio (`torch.Tensor`, `np.ndarray`) : TODO

LTX 파이프라인의 출력 클래스입니다.

## LTX2ModularPipeline[[diffusers.LTX2ModularPipeline]]

#### diffusers.LTX2ModularPipeline[[diffusers.LTX2ModularPipeline]]

```python
diffusers.LTX2ModularPipeline(blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = None, pretrained_model_name_or_path: str | os.PathLike | None = None, components_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = None, collection: str | None = None, workflow: str | None = None, modular_config_dict: dict[str, typing.Any] | None = None, config_dict: dict[str, typing.Any] | None = None, **kwargs)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/ltx2/modular_pipeline.py#L26)

LTX-2용 ModularPipeline(동영상 + 오디오 결합 생성).

## LTX2AutoBlocks[[diffusers.LTX2AutoBlocks]]

#### diffusers.LTX2AutoBlocks[[diffusers.LTX2AutoBlocks]]

```python
diffusers.LTX2AutoBlocks()
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/ltx2/modular_blocks_ltx2.py#L1761)

텍스트-투-비디오, 이미지-투-비디오, 조건-투-비디오 및 인-컨텍스트(IC-LoRA) 생성(비디오 + 오디오 결합)을 지원하는 LTX-2용 Auto 블록입니다.

지원되는 워크플로:
- `text2video`: `prompt` 필수
- `image2video`: `image`, `prompt` 필수
- `condition`: `conditions`, `prompt` 필요
- `in_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`)

Inputs: prompt (`str`, *선택 사항*): 이미지 생성을 안내할 프롬프트입니다. conditions (`list`, *선택 사항*): 생성된 비디오의 잠재 프레임 인덱스에 이미지/비디오 조건을 배치하는 `LTX2VideoCondition`(또는 그 목록)입니다. enable_prompt_enhancement (`bool`, *선택 사항*, 기본값 False): 프롬프트 향상기를 실행할지 여부입니다. Lightricks 참조 파이프라인과 일치하도록 옵트인 방식입니다. system_prompt (`str`, *선택 사항*): 향상을 위한 시스템 프롬프트입니다. `PIL.Image.Image` 조건 프레임이 사용 가능한 경우 기본값은 `LTX2_5_I2V_DEFAULT_SYSTEM_PROMPT`이고, 그렇지 않으면 `LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT`입니다. prompt_max_new_tokens (`int`, *선택 사항*): 프롬프트 향상 중에 생성할 새 토큰의 최대 수입니다. 기본값은 LTX-2.5 Gemma-4 향상기의 예산인 600입니다. 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`, *선택 사항*): VAE 인코딩 전에 조건부 `image`를 다시 압축할 때 사용되는 H.264 CRF 값으로, 모델이 학습된 압축과 일치합니다. `None`(기본값)은 텍스트 인코더 생성에서 해석됩니다(LTX-2.3까지는 33, LTX-2.5는 18). 다시 압축을 건너뛰려면 `0`을 전달합니다. 다시 압축이 실행될 때 `PIL.Image.Image`가 필요합니다. num_frames (`int`, *선택 사항*): 생성된 비디오의 프레임 수입니다. `duration_head`를 통해 자동 예측하려면 생략합니다(`LTX2AutoDurationStep` 참조). reference_conditions (`list`, *선택 사항*): IC-LoRA 어댑터가 주의를 기울이는 추가 잠재 토큰으로 인코딩되는 비디오를 가진 `LTX2ReferenceCondition`(또는 그 목록)입니다. reference_downscale_factor (`int`, *선택 사항*, 기본값 1): 대상 해상도와 참조 해상도 사이의 비율입니다. 2는 참조가 대상 해상도의 절반으로 전처리됨을 의미합니다. 공간 좌표는 이 계수로 스케일링되어 참조 토큰이 대상 좌표 공간에 위치하도록 합니다. IC-LoRA가 학습된 계수와 일치해야 합니다. conditioning_attention_strength (`float`, *선택 사항*, 기본값 1.0): 노이즈 토큰과 참조 토큰이 서로 얼마나 강하게 주의를 기울이는지 제어하는 [0, 1] 범위의 스칼라입니다. 1.0(기본값)은 주의를 마스킹하지 않습니다. conditioning_attention_mask (`Tensor`, *선택 사항*): [0, 1] 범위의 값으로 공간적으로 변화하는 주의 강도를 제공하는 (1, 1, F, H, W) 형태의 선택적 픽셀 공간 마스크입니다. 참조의 잠재 그리드로 다운샘플링되어 `conditioning_attention_strength`와 곱해집니다. motion_speed (`float`, *선택 사항*, 기본값 1.0): 실시간 대비 움직임의 속도입니다. 위치 임베딩은 `frame_rate / motion_speed`에 조건부이므로, 1보다 작은 값은 움직임을 늦춥니다. 예를 들어 Slow-Motion-Control LoRA의 5배 슬로우 모션에는 `0.2`를 사용합니다. `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`가 제공된 경우 `sigmas[0]`으로 해석되고, 그렇지 않으면 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`, *선택 사항*): 어텐션 프로세서에 사용할 추가 kwargs입니다. image_latents (`Tensor`, *선택 사항*): 이미지-비디오 조건부에 사용되는 VAE 인코딩된 참조 이미지 잠재 변수입니다. output_type (`str`, *선택 사항*, 기본값 pil): 출력 형식: 'pil', 'np', 'pt'. decode_timestep (`None`, *선택 사항*, 기본값 0.0): VAE가 최종 잠재 변수를 디코딩하는 타임스텝입니다. decode_noise_scale (`None`, *선택 사항*): 디코딩 타임스텝의 잠재 변수에 적용되는 노이즈 보간 계수입니다.

Outputs: videos (`list`): 생성된 비디오. audio (`Tensor`): 생성된 오디오 웨이브폼.

## LTX25ModularPipeline[[diffusers.LTX25ModularPipeline]]

#### diffusers.LTX25ModularPipeline[[diffusers.LTX25ModularPipeline]]

```python
diffusers.LTX25ModularPipeline(blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = None, pretrained_model_name_or_path: str | os.PathLike | None = None, components_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = None, collection: str | None = None, workflow: str | None = None, modular_config_dict: dict[str, typing.Any] | None = None, config_dict: dict[str, typing.Any] | None = None, **kwargs)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/ltx2/modular_pipeline.py#L125)

LTX-2.5용 ModularPipeline(동영상 + 오디오 결합 생성).

[LTX2ModularPipeline](/docs/diffusers/main/ko/api/pipelines/ltx2#diffusers.LTX2ModularPipeline)와 동일하지만, 기본 블록이 LTX-2.5부터 네이티브 기본값인 diffusion video decoder로 디코딩합니다. 체크포인트는 `modular_model_index.json`을 통해 여기로 라우팅됩니다.

## LTX25AutoBlocks[[diffusers.LTX25AutoBlocks]]

#### diffusers.LTX25AutoBlocks[[diffusers.LTX25AutoBlocks]]

```python
diffusers.LTX25AutoBlocks()
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/ltx2/modular_blocks_ltx25.py#L215)

LTX-2.5용 Auto blocks입니다. 텍스트-투-비디오, 이미지-투-비디오, 조건-투-비디오 및 인-컨텍스트(IC-LoRA) 생성(비디오 + 오디오 결합)을 지원합니다. `LTX2AutoBlocks`와 동일하지만, LTX-2.5부터 기본값이 되는 diffusion decoder를 사용하므로 비디오 decoder가 `LTX2DiffusionVaeDecoderStep`입니다. 대신 convolutional VAE로 디코딩하려면 decode block을 교체하세요: `blocks.sub_blocks["decode"] = LTX2AutoDecoderStep()`.

지원되는 워크플로:
- `text2video`: `prompt` 필수
- `image2video`: `image`, `prompt` 필수
- `condition`: `conditions`, `prompt` 필요
- `in_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`)

Inputs: prompt (`str`, *선택 사항*): 이미지 생성을 안내할 프롬프트입니다. conditions (`list`, *선택 사항*): 생성된 비디오의 잠재 프레임 인덱스에 이미지/비디오 조건을 배치하는 `LTX2VideoCondition`(또는 그 목록)입니다. enable_prompt_enhancement (`bool`, *선택 사항*, 기본값 False): 프롬프트 향상기를 실행할지 여부입니다. Lightricks 참조 파이프라인과 일치하도록 옵트인 방식입니다. system_prompt (`str`, *선택 사항*): 향상을 위한 시스템 프롬프트입니다. `PIL.Image.Image` 조건 프레임이 사용 가능한 경우 기본값은 `LTX2_5_I2V_DEFAULT_SYSTEM_PROMPT`이고, 그렇지 않으면 `LTX2_5_T2V_DEFAULT_SYSTEM_PROMPT`입니다. prompt_max_new_tokens (`int`, *선택 사항*): 프롬프트 향상 중에 생성할 새 토큰의 최대 수입니다. 기본값은 LTX-2.5 Gemma-4 향상기의 예산인 600입니다. 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`, *선택 사항*): VAE 인코딩 전에 조건부 `image`를 다시 압축할 때 사용되는 H.264 CRF 값으로, 모델이 학습된 압축과 일치합니다. `None`(기본값)은 텍스트 인코더 생성에서 해석됩니다(LTX-2.3까지는 33, LTX-2.5는 18). 재압축을 건너뛰려면 `0`을 전달합니다. 재압축이 실행될 때 `PIL.Image.Image`가 필요합니다. num_frames (`int`, *선택 사항*): 생성된 비디오의 프레임 수입니다. 생략하면 `duration_head`를 통해 자동 예측됩니다(`LTX2AutoDurationStep` 참조). reference_conditions (`list`, *선택 사항*): IC-LoRA 어댑터가 주의를 기울이는 추가 잠재 토큰으로 인코딩되는 비디오를 가진 `LTX2ReferenceCondition`(또는 그 목록)입니다. 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보다 작은 값은 움직임을 늦춥니다. 예를 들어 Slow-Motion-Control LoRA의 5배 슬로우 모션에는 `0.2`를 사용합니다. `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`가 제공된 경우 `sigmas[0]`으로 해석되고, 그렇지 않으면 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`, *선택 사항*): 어텐션 프로세서에 사용할 추가 kwargs입니다. image_latents (`Tensor`, *선택 사항*): 이미지-비디오 조건부에 사용되는 VAE 인코딩된 참조 이미지 잠재 변수입니다. output_type (`str`, *선택 사항*, 기본값 pil): 출력 형식: 'pil', 'np', 'pt'.

Outputs: videos (`list`): 생성된 비디오. audio (`Tensor`): 생성된 오디오 웨이브폼.