Buckets:
#
# 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 についてもこれらのデフォルト値を使用しています。
本番環境での高品質な生成を実現するための推奨パイプラインです。このパイプラインは2つの段階で構成されています。
- ステージ1: クラスフリーガイダンス（CFG）を用いた拡散サンプリングにより、ターゲット解像度で動画を生成します。このステージでは、テキスト/画像の条件付けを尊重した、一貫性のある低ノイズの動画シーケンスが生成されます。
- Stage 2: Stage 1 の出力を 2 倍にアップサンプリングし、蒸留された LoRA モデルを使用して詳細を精錬することで、忠実度と視覚的な品質を向上させます。Stage 2 では、Stage 1 の構造を維持しつつ、テクスチャとシャープネスを強化するために、より軽い CFG を適用する場合があります。
テキストから動画への変換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` を使用すると、任意の潜在インデックスで画像および/または動画の条件を指定できます。例えば、最初のフレームと最後のフレームの条件を両方指定することで、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",
)
```
条件付けは潜在フレームを介して行われるため、画像条件に指定された潜在フレームに対応する8つのデータ空間フレームは、静的になる傾向があります。
## マルチモーダルガイダンス
LTX-2.Xのパイプラインはマルチモーダルガイダンスをサポートしています。これは3つの項で構成され、すべてCFGスタイルの更新ルールを使用します。
1. Classifier-Free Guidance (CFG): 標準的な[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 については、自己注意をスキップする transformer ブロックのインデックスを `spatio_temporal_guidance_blocks` 引数で指定する必要があります。LTX-2.X パイプラインでは、guidance スケールが高値に設定された場合に問題になりうる過剰露出を軽減するために、[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) モデル）がシステムプロンプトを与えられてプロンプトを強化するため、サンプルの品質を向上させることができます。プロンプト強化を使用するには、任意の `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) には、2 つの transformer が同梱されています。`model_index.json` が指しているのは `transformer/` にある **distilled** DiT であり、もう一方の full/SFT DiT は `transformer_full/` にあり、明示的にロードする必要があります（[Full / SFT transformer](#full--sft-transformer) を参照）。リポジトリの `scheduler/` は distilled チェックポイント用に設定されており（`use_dynamic_shifting=False`、`shift_terminal=None`）、その sigma スケジュールがそのまま使用されるようになっています。[two-stage generation](#two-stage-generation-for-ltx-25) に必要なものもすべて同梱されており、`latent_upsampler/` サブフォルダと、リポジトリのルートにある stage 2 の distilled LoRA `ltx-2.5-22b-distilled-lora-450-bf16.safetensors` が含まれています。
蒸留推論はステップ数ではなく明示的なシグマスケジュールによって駆動され、ガイドなしで実行されます（`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 は 2 ステージのバリアントの両方をサポートしており、`DISTILLED_SIGMA_VALUES` / `STAGE_2_DISTILLED_SIGMA_VALUES` はそのリファレンススケジュールです:
- **蒸留済みチェックポイント（両ステージ）** — デフォルトの`transformer/`向けの参照レシピであり、以下に示すものです。transformerはすでに蒸留済みのため、ステージ2のLoRAは関与しません。これはLTX-2.5の重みを用いた[蒸留済みチェックポイントの生成](#distilled-checkpoint-generation)です。
- **Full/SFT ステージ 1 + 蒸留 LoRA ステージ 2** — このページの冒頭で説明されている[2段階の生成](#two-stages-generation)で、`transformer_full/`と付属の LoRA を使用します。変更点については[下記](#stage-2-with-the-distilled-lora)を参照してください。
Stage 1 はターゲット解像度の半分でのみ実行され、アップサンプラーによって解像度が2倍に拡大された後、Stage 2 がフル解像度で精細化を行います。これは動画*および*音声の両方に適用され、いずれも Stage 1 の潜在変数から `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]`) から実現された長さを復元してください。2 回目に予測するのではなく、このようにします。
```py
num_frames = (video_latent.shape[2] - 1) * pipe.vae_temporal_compression_ratio + 1
```
#### 蒸留されたLoRAを用いたステージ2
代わりに[2段階生成](#two-stages-generation)を実行する場合（ステージ1にフル/SFT DiT、ステージ2に蒸留LoRAを使用）は、[フル / SFT transformer](#full--sft-transformer)と同様にパイプラインを構築し、そのガイダンススタックでステージ1の潜在変数を生成します。その後、LTX-2.0/2.3とは2点異なります。LoRAは元の重みの隣ではなく、diffusersリポジトリ自体に格納されており、スケジューラの反転は逆方向です。LTX-2.5には*蒸留*スケジューラ設定が同梱されているため、ステージ1でダイナミックシフトが有効化され、ステージ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
)
```
アップサンプリングのステップとステージ2の呼び出し自体は、上記の蒸留レシピから変更されていません。いずれの場合もステージ2では蒸留モデルが実行されるため、`sigmas=STAGE_2_DISTILLED_SIGMA_VALUES`、`noise_scale`、`guidance_scale=1.0`はすべて同じです。
### 畳み込みおよび拡散デコーディング
LTX-2.5は、同じ潜在空間上で動作する2つのビデオデコーダーを備えており、そのため潜在変数はこれら間で相互に交換可能です。
- `vae/` — 畳み込み VAE（[AutoencoderKLLTX2Video](/docs/diffusers/main/ja/api/models/autoencoderkl_ltx_2#diffusers.AutoencoderKLLTX2Video)）。パイプラインがデコードに使用するコンポーネントであり、上記のスニペットはすべてこれを使用しています。また、2 つのうちタイル化（`pipe.vae.enable_tiling()`）に対応しているのはこれだけで、通常、これにより高解像度の出力が可能になります。
- `diffusion_decoder/` — [LTX2VideoDiffusionDecoderModel](/docs/diffusers/main/ja/api/models/ltx2_diffusion_decoder#diffusers.LTX2VideoDiffusionDecoderModel)。これはパイプラインのコンポーネントではなく、それ自体が拡散モデルであるため、`vae` として渡すことはありません。`output_type="latent"` を指定してパイプラインを実行し、得られた潜在変数を [LTX2VideoDiffusionDecodePipeline](/docs/diffusers/main/ja/api/pipelines/ltx2#diffusers.LTX2VideoDiffusionDecodePipeline) に渡してください。
エンコーディングは常に`vae/`を経由するため、画像および動画の条件付けは選択によって影響を受けません。
拡散デコーダでデコードを行うと、2つの点が変わります。`output_type="latent"`を指定するとボーコーダもスキップされるため、音声は潜在変数として返され、手動で処理を完了させる必要があります。また、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)と組み合わせるには、*stage 2*に対して`output_type="latent"`を指定し、その結果をデコードします。
`decoder.enable_tiling()` は、`pipe.vae.enable_tiling()` が畳み込み VAE に対して行うのと同様に、高解像度のデコードをメモリ内に保持するための機能です。デコードにおけるメモリ消費の主要部分である最後のアップサンプリング段階と拡散段階は、オーバーラップするタイルで実行され、その後それらがブレンドされて再結合されるため、ピークメモリは動画サイズではなくタイルサイズによって上限が設定されます。タイルリングは、潜在変数が 1 つのタイルを超えた場合にのみ有効になり、タイルサイズとオーバーラップサイズは `tile_sample_min_*` / `tile_sample_stride_*` 引数（デフォルト値は参照実装と一致）で調整できます。拡散段階では各タイルが個別にデノイズされるため、タイルリングによるデコードでは、タイルリングなしの結果と完全に一致する出力は得られません。
単一カードでは、デコードの前にパイプラインを退避させることも有効です（`pipe.scheduler` とボコーダーの `output_sampling_rate` を取得した後、`pipe.to("cpu")` と `torch.cuda.empty_cache()` を呼び出します）。これは、デコーダーが独自の空き領域を必要とするためです。アテンションのバックエンド、タイルリングの詳細、およびデコーダーのその他の動作については、[LTX2VideoDiffusionDecoderModel](/docs/diffusers/main/ja/api/models/ltx2_diffusion_decoder#diffusers.LTX2VideoDiffusionDecoderModel) を参照してください。
### フル / 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](#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` を用いた image-to-video にも同様のことが当てはまります。`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` を明示的に渡します。整数は常に head より優先されます:
```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 の場合、1 ステップあたり約 0.33 秒）。また、ヘッドがフレーム数ではなく秒数を予測するため、`frame_rate` によって変化します。`min_seconds` は `max_seconds` より厳密に小さい必要があります。`num_frames` が明示的に設定されている場合、これらの境界値は無視されます。
1グリッドステップより狭い範囲は、厳密には満たせない場合があります。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フレーム（24 fpsで約5秒）であり、変化するのは動きのペースだけです。[2段階生成](#two-stage-generation-for-ltx-25)では、**両方の**段階に同じ`motion_speed`を渡します。第2段階では動画が再デノイズされるため、リアルタイム軸で実行するとスローモーションが取り消されてしまいます。[reference driver](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 はモジュラーパイプラインとしても利用できます。デフォルトのブロックセットは拡散デコーダーを使用し、`num_frames` が省略されている場合は動画の長さを予測します。`guider` と `audio_guider` コンポーネントを通じて、動画と音声に対してそれぞれ個別にガイダンスを適用します。利用可能なガイダンスパラメータについては [LTX2Guidance](/docs/diffusers/main/ja/api/modular_diffusers/guiders#diffusers.LTX2Guidance) を参照してください。デフォルトでは、モジュラーパイプラインは [google/gemma-4-E2B-it](https://huggingface.co/google/gemma-4-E2B-it) リポジトリからプロンプトエンハンサーとプロセッサーをダウンロードします。以下は 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/ja/api/pipelines/ltx2#diffusers.LTX2AutoBlocks)、[LTX25AutoBlocks](/docs/diffusers/main/ja/api/pipelines/ltx2#diffusers.LTX25AutoBlocks)）で、サポートされているワークフローを確認できます。
### LTX-2.5 向けの Diffusion Fidelity Rendering (DFR)
`LTX2DFRPipeline` は、リアルタイム性（ウォールクロック時間）を犠牲にして詳細の忠実度を高めます。各 `__call__` は `height` × `width` での **1回のデノイズパス** であり、動画と、それらのスロットからシードされた追加の単一ピクセルフレームの **キーフレームスロット** を生成するか、これらのスロットからシードされた提供された潜在変数（latents）を再デノイズします。呼び出し側は、他の LTX 2段階パイプラインと同様にステージを組み合わせます。すなわち、このパイプライン、[LTX2LatentUpsamplePipeline](/docs/diffusers/main/ja/api/pipelines/ltx2#diffusers.LTX2LatentUpsamplePipeline)、再びこのパイプライン、そして各時間ラウンドごとに [LTX2DFRTemporalRefinePipeline](/docs/diffusers/main/ja/api/pipelines/ltx2#diffusers.LTX2DFRTemporalRefinePipeline) を実行します。
スロットは1ピクセルフレームを取得するために1フレーム分の潜在トークンを消費するため、その位置での実効的な時間方向の圧縮が緩和されます。これにより、周囲の映像は補間されたフレームではなく、真に新しいフレームを条件として生成されます。スロットの位置は、VAEの時間方向の境界（24ピクセルフレームまたは32ピクセルフレームのうち、リクエストへのパディングが少ない方）に整列されたセグメントグリッドから決定されます。キャンバスは内部でセグメントの整数倍にパディングされ、`output_type="latent"` はそのパディング済みグリッドを返すため、パディング上のスロットが破棄されることはありません。VAEデコードの前に `trim_canvas` でトリミングしてください。
この処理には、`use_keyframes_abs_pos_embedding` を設定した config を持つ transformer が必要です。この設定により、単一ピクセルフレームの latents に学習済み embedding が付与されます。LTX-2.5 のチェックポイントにはこれが同梱されていますが、それより古いバージョンでは、解釈できないトークンにトークン予算を消費するのを避けるため、パイプラインは例外を送出します。
追加トークンの予算について: 各スロットが1フレーム分の潜在フレームを追加するため、ステージ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` の場合は、同じ4つのフィールドがタプルとして返されます)。
以下の完全なレシピが、スタートに最適なものです: 1088×1920 の画像から動画への変換、1 回の x2 時間方向リファイン、およびステージ 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 の半解像度潜在変数を `reference_latents` として参照します。ステージ 1 と時間軸ラウンドでは、アダプターを無効にします。ステージ 1 より前に LoRA を読み込んだ場合、`transformer.disable_adapters()` で無効化できますが、`set_adapters` では**再有効化されません**。ステージ 2 の前に `transformer.enable_adapters()` を呼び出すか、レシピに従ってステージ 1 の後に重みをロードしてください。`reference_downscale_factor`（デフォルトは `2`）は、参照トークンの空間座標をターゲットの座標系にスケーリングします。
**時間方向の精錬。** [LTX2DFRTemporalRefinePipeline](/docs/diffusers/main/ja/api/pipelines/ltx2#diffusers.LTX2DFRTemporalRefinePipeline) は 1 ラウンドで、時間方向にアップサンプリングし、キーフレームの継ぎ目でタイル分割し、`LTXEulerAncestralRFScheduler`（`eta=0.5`）で祖先デノイズを実行し、後続タイルのリードインを破棄して結合し、キャリーキーフレームのバッグをマージします。このスケジューラは自分で構築してください。他のスケジューラではラウンドが拒否されます。決定論的なステップは最後まで実行され、より柔らかいキャンバスを返すだけになるためです。ラウンドごとにパイプラインを 1 回呼び出し、`round_index` を渡して 2 倍 / 4 倍のループを回します。ラウンドの終了後、`keyframe_positions` は元の `num_frames` から再導出できなくなるため、そのまま引き継ぐ必要があります。各タイルには、凍結されたステージ 1 のオーディオのうち、そのタイル自身の再生ウィンドウをカバーするスライスが渡されます。`source_seconds` は *ステージ 1* の長さであり、ラウンド間で固定されるため、後続のラウンドではデフォルト値を受け取るのではなく、明示的に渡す必要があります。
とは無関係に、再生が30を超える場合、のfpsは常に60です。RoPEの時間は`pixel_frame / fps`であるため、120 fpsの時間基準では、学習時の分布と比較して各トークンの時間的スパンが半分になり、48 fpsでは引き伸ばされます。両者は60であると偽り、デコードされたフレームを再生レートで扱います。
**第3の空間ステージ。**これらを組み合わせます。第4のパイプラインはありません。**動画のみ**を空間的にアップサンプリングし、RGBでキャリーキーフレームを再構築します（`decode` → Lanczos ×2 → `encode`、[rebuild_epilogue_keyframes()](/docs/diffusers/main/ja/api/pipelines/ltx2#diffusers.LTX2DFRPipeline.rebuild_epilogue_keyframes)経由。エピローグキーフレームを潜在空間でアップサンプリングしないこと）。その後、以下を実行します：
```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()
```
2つの軸は異なる方法で継ぎ目処理されています。空間的な境界のどちらの側にも既知の答えが存在しないため、これらの重複部分は台形重みでブレンドされます。時間方向のタイルは、最終的なリファインラウンドのキーフレームの継ぎ目で切り分けられます。
**拡散デコーダーによるデコーディング。** 最大のディテール忠実度を確保するには、`output_type="latent"` のまま、（すでに正規化解除済みで、場合によっては `trim_canvas` が適用済みの）潜変数を [LTX2VideoDiffusionDecodePipeline](/docs/diffusers/main/ja/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/ja/api/models/ltx_video_transformer3d#diffusers.LTXVideoTransformer3DModel)) : エンコードされた動画の潜在変数をノイズ除去するための条件付き Transformer アーキテクチャ。
scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/ja/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : `transformer` と組み合わせて、エンコードされた画像の潜在変数をデノイズするために使用するスケジューラー。
vae ([AutoencoderKLLTXVideo](/docs/diffusers/main/ja/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。
tokenizer (`T5TokenizerFast`) : クラス [T5TokenizerFast](https://huggingface.co/docs/transformers/en/model_doc/t5#transformers.T5TokenizerFast) の2番目の Tokenizer。
connectors (`LTX2TextConnectors`) : 動画および音声ブランチ用にテキストエンコーダーの隠れ状態を適応させるために使用されるテキストコネクタスタック。
テキストから動画を生成するためのPipeline。
参考: https://github.com/Lightricks/LTX-Video
#### __call__[[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[int] = 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[str] = ['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 を使用していない場合（`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`、*optional*、デフォルトは 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) 用のビデオガイダンススケールです。STG は CFG に似た推定値を使用し、デノイジングモデルの摂動バージョンからの弱いサンプルからサンプルを離れるように移動させます。STG を有効にすると、デノイジングモデルのフォワードパスが 1 回追加されます。デフォルト値の `0.0` は、STG が無効であることを意味します。
modality_scale (`float`、*任意*、デフォルトは `1.0`) : LTX-2.X のモダリティ分離ガイダンスにおける動画ガイダンススケールです。クロスモダリティ（音声から動画へ、および動画から音声へ）のクロスアテンションを無効化して生成された弱いサンプルから、CFG 類似の推定を用いてサンプルを離す方向に移動させます。モダリティガイダンスを有効にすると、デノイジングモデルのフォワードパスが 1 回追加されます。デフォルト値 `1.0` は、モダリティガイダンスが無効であることを意味します。
guidance_rescale (`float`, *optional*, defaults to 0.0) : Guidance rescale factor proposed by [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://huggingface.co/papers/2305.08891) `guidance_scale` is defined as `φ` in equation 16. of [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://huggingface.co/papers/2305.08891). Guidance rescale factor should fix overexposure when using zero terminal SNR. Used for the video modality.
audio_guidance_scale (`float`、*任意*、デフォルトは`None`) : 負のプロンプトに対する CFG のオーディオガイダンススケールです。CFG の更新ルールは動画とオーディオで同じですが、ガイダンススケールの値はそれぞれ異なる値を使用できます。LTX-2.X の著者たちは、`audio_guidance_scale` は動画の `guidance_scale` に対して高い値にすべきと提案しています（例：LTX-2.3 では、動画を 3.0、オーディオを 7.0 と提案しています）。`None` の場合、動画の値である `guidance_scale` がデフォルトとして使用されます。
audio_stg_scale (`float`、*任意*、デフォルトは`None`) : STG用のオーディオガイダンススケールです。CFGと同様に、STGの更新ルールは動画とオーディオで同じです。LTX-2.3では、動画とオーディオの両方に1.0の値を推奨します。`None`の場合、動画の値`stg_scale`がデフォルトとして使用されます。
audio_modality_scale (`float`、*任意*、デフォルトは`None`) : LTX-2.X のモダリティ分離ガイダンスにおけるオーディオガイダンススケール。CFG と同様に、モダリティガイダンスのルールは、ビデオとオーディオのいずれにおいても同じです。LTX-2.3 の場合、ビデオとオーディオの両方に対して 3.0 の値が推奨されます。`None` の場合、ビデオの値である`modality_scale`がデフォルトとして使用されます。
audio_guidance_rescale (`float`、*任意*、デフォルトは`None`) : 音声モダリティ用の別個のguidance rescale係数です。`None`の場合、デフォルトで動画の値`guidance_rescale`が使用されます。
spatio_temporal_guidance_blocks (`list[int]`、*optional*、デフォルトは`None`) : STGを適用するtransformerブロックのゼロ始まりのインデックスです。STGを使用する場合（`stg_scale`または`audio_stg_scale`が`0`より大きい場合）は、この値を指定する必要があります。LTX-2.0では`[29]`、LTX-2.3では`[28]`を推奨します。
noise_scale (`float`, *任意*、デフォルトは `0.0`) : 各タイムステップにおけるランダムノイズとデノイズ済み潜在変数の間の補間係数。デノイジングを続行する前に、`latents` と `audio_latents` にノイズを適用します。
num_videos_per_prompt (`int`、*optional*、デフォルトは 1) : プロンプトごとに生成する動画の数を指定します。
generator (`torch.Generator` または `list[torch.Generator]`、*任意*) : 生成を決定論的にするための [torch ジェネレーター](https://pytorch.org/docs/stable/generated/torch.Generator.html) 1 つまたはそのリスト。
latents (`torch.Tensor`, *任意*) : 動画生成の入力として使用する、ガウス分布からサンプリングされた事前生成されたノイジー・ラテンツ。異なるプロンプトで同じ生成を調整するために使用できます。指定されない場合、指定されたランダム`generator`を使用してサンプリングを行い、ラテンツのテンソルが生成されます。
audio_latents (`torch.Tensor`, *任意*) : 音声生成の入力として使用する、ガウス分布からサンプリングされた事前生成されたノイジー・ラテンツ。異なるプロンプトで同じ生成を調整するために使用できます。指定されない場合、指定されたランダムな`generator`を使用してサンプリングを行い、ラテンツのテンソルが生成されます。
prompt_embeds (`torch.Tensor`, *任意*) : 事前生成されたテキスト埋め込み。テキスト入力の調整、*例えば*プロンプトの重み付けなどを容易に行うために使用できます。指定されない場合、`prompt` 入力引数からテキスト埋め込みが生成されます。
prompt_attention_mask (`torch.Tensor`, *任意*) : テキスト埋め込み用の事前生成されたアテンションマスク。
negative_prompt_embeds (`torch.FloatTensor`, *任意*) : 事前に生成されたネガティブテキスト埋め込み。PixArt-Sigma の場合、このネガティブプロンプトは "" である必要があります。指定されない場合、`negative_prompt` 入力引数から 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`、*optional*、デフォルトは`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`、*optional*、デフォルトは 1) : 各プロンプトに対して生成すべき動画の数。結果の埋め込みを配置する torch デバイス
prompt_embeds (`torch.Tensor`, *任意*) : 事前生成されたテキスト埋め込み。テキスト入力の調整、*例えば*プロンプトの重み付けなどを容易に行うために使用できます。指定されない場合、`prompt` 入力引数からテキスト埋め込みが生成されます。
negative_prompt_embeds (`torch.Tensor`, *任意*) : 事前に生成されたネガティブなテキスト埋め込み。テキスト入力の調整、*例えば*プロンプトの重み付けなどを容易に行うために使用できます。指定されない場合、`negative_prompt` 入力引数から negative_prompt_embeds が生成されます。
device : (`torch.device`, *任意*): torch デバイス
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。
参考: https://github.com/Lightricks/LTX-Video
TODO
#### __call__[[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[str] = ['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 を使用していない場合（`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`、*optional*、デフォルトは 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) 用のビデオガイダンススケールです。STG は CFG に似た推定値を使用し、デノイジングモデルの摂動バージョンからの弱いサンプルからサンプルを離れるように移動させます。STG を有効にすると、デノイジングモデルのフォワードパスが 1 回追加されます。デフォルト値の `0.0` は、STG が無効であることを意味します。
modality_scale (`float`、*任意*、デフォルトは `1.0`) : LTX-2.X のモダリティ分離ガイダンスにおける動画ガイダンススケールです。クロスモダリティ（音声から動画へ、および動画から音声へ）のクロスアテンションを無効化して生成された弱いサンプルから、CFG 類似の推定を用いてサンプルを離す方向に移動させます。モダリティガイダンスを有効にすると、デノイジングモデルのフォワードパスが 1 回追加されます。デフォルト値 `1.0` は、モダリティガイダンスが無効であることを意味します。
guidance_rescale (`float`, *optional*, defaults to 0.0) : Guidance rescale factor proposed by [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://huggingface.co/papers/2305.08891) `guidance_scale` is defined as `φ` in equation 16. of [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://huggingface.co/papers/2305.08891). Guidance rescale factor should fix overexposure when using zero terminal SNR. Used for the video modality.
audio_guidance_scale (`float`、*任意*、デフォルトは`None`) : 負のプロンプトに対する CFG のオーディオガイダンススケールです。CFG の更新ルールは動画とオーディオで同じですが、ガイダンススケールの値はそれぞれ異なる値を使用できます。LTX-2.X の著者たちは、`audio_guidance_scale` は動画の `guidance_scale` に対して高い値にすべきと提案しています（例：LTX-2.3 では、動画を 3.0、オーディオを 7.0 と提案しています）。`None` の場合、動画の値である `guidance_scale` がデフォルトとして使用されます。
audio_stg_scale (`float`、*任意*、デフォルトは`None`) : STG用のオーディオガイダンススケールです。CFGと同様に、STGの更新ルールは動画とオーディオで同じです。LTX-2.3では、動画とオーディオの両方に1.0の値を推奨します。`None`の場合、動画の値`stg_scale`がデフォルトとして使用されます。
audio_modality_scale (`float`、*任意*、デフォルトは`None`) : LTX-2.X のモダリティ分離ガイダンスにおけるオーディオガイダンススケール。CFG と同様に、モダリティガイダンスのルールは、ビデオとオーディオのいずれにおいても同じです。LTX-2.3 の場合、ビデオとオーディオの両方に対して 3.0 の値が推奨されます。`None` の場合、ビデオの値である`modality_scale`がデフォルトとして使用されます。
audio_guidance_rescale (`float`、*任意*、デフォルトは`None`) : 音声モダリティ用の別個のguidance rescale係数です。`None`の場合、デフォルトで動画の値`guidance_rescale`が使用されます。
spatio_temporal_guidance_blocks (`list[int]`、*optional*、デフォルトは`None`) : STGを適用するtransformerブロックのゼロ始まりのインデックスです。STGを使用する場合（`stg_scale`または`audio_stg_scale`が`0`より大きい場合）は、この値を指定する必要があります。LTX-2.0では`[29]`、LTX-2.3では`[28]`を推奨します。
noise_scale (`float`, *任意*、デフォルトは `0.0`) : 各タイムステップにおけるランダムノイズとデノイズ済み潜在変数の間の補間係数。デノイジングを続行する前に、`latents` と `audio_latents` にノイズを適用します。
num_videos_per_prompt (`int`、*optional*、デフォルトは 1) : プロンプトごとに生成する動画の数を指定します。
generator (`torch.Generator` または `list[torch.Generator]`、*任意*) : 生成を決定論的にするための [torch ジェネレーター](https://pytorch.org/docs/stable/generated/torch.Generator.html) 1 つまたはそのリスト。
latents (`torch.Tensor`, *任意*) : 動画生成の入力として使用する、ガウス分布からサンプリングされた事前生成されたノイジー・ラテンツ。異なるプロンプトで同じ生成を調整するために使用できます。指定されない場合、指定されたランダム`generator`を使用してサンプリングを行い、ラテンツのテンソルが生成されます。
audio_latents (`torch.Tensor`, *任意*) : 音声生成の入力として使用する、ガウス分布からサンプリングされた事前生成されたノイジー・ラテンツ。異なるプロンプトで同じ生成を調整するために使用できます。指定されない場合、指定されたランダムな`generator`を使用してサンプリングを行い、ラテンツのテンソルが生成されます。
prompt_embeds (`torch.Tensor`, *任意*) : 事前生成されたテキスト埋め込み。テキスト入力の調整、*例えば*プロンプトの重み付けなどを容易に行うために使用できます。指定されない場合、`prompt` 入力引数からテキスト埋め込みが生成されます。
prompt_attention_mask (`torch.Tensor`, *任意*) : テキスト埋め込み用の事前生成されたアテンションマスク。
negative_prompt_embeds (`torch.FloatTensor`, *任意*) : 事前に生成されたネガティブテキスト埋め込み。PixArt-Sigma の場合、このネガティブプロンプトは "" である必要があります。指定されない場合、`negative_prompt` 入力引数から 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` が省略されている場合、LTX-2.5 は専用の `prompt_enhancer` が設定されている場合に `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`、*optional*、デフォルトは`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`、*optional*、デフォルトは 1) : 各プロンプトに対して生成すべき動画の数。結果の埋め込みを配置する torch デバイス
prompt_embeds (`torch.Tensor`, *任意*) : 事前生成されたテキスト埋め込み。テキスト入力の調整、*例えば*プロンプトの重み付けなどを容易に行うために使用できます。指定されない場合、`prompt` 入力引数からテキスト埋め込みが生成されます。
negative_prompt_embeds (`torch.Tensor`, *任意*) : 事前に生成されたネガティブなテキスト埋め込み。テキスト入力の調整、*例えば*プロンプトの重み付けなどを容易に行うために使用できます。指定されない場合、`negative_prompt` 入力引数から negative_prompt_embeds が生成されます。
device : (`torch.device`, *任意*): torch デバイス
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です。
参考: https://github.com/Lightricks/LTX-Video
TODO
#### __call__[[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[str] = ['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 を使用していない場合（`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`、*optional*、デフォルトは 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) 用のビデオガイダンススケールです。STG は CFG に似た推定値を使用し、デノイジングモデルの摂動バージョンからの弱いサンプルからサンプルを離れるように移動させます。STG を有効にすると、デノイジングモデルのフォワードパスが 1 回追加されます。デフォルト値の `0.0` は、STG が無効であることを意味します。
modality_scale (`float`、*任意*、デフォルトは `1.0`) : LTX-2.X のモダリティ分離ガイダンスにおける動画ガイダンススケールです。クロスモダリティ（音声から動画へ、および動画から音声へ）のクロスアテンションを無効化して生成された弱いサンプルから、CFG 類似の推定を用いてサンプルを離す方向に移動させます。モダリティガイダンスを有効にすると、デノイジングモデルのフォワードパスが 1 回追加されます。デフォルト値 `1.0` は、モダリティガイダンスが無効であることを意味します。
guidance_rescale (`float`, *optional*, defaults to 0.0) : Guidance rescale factor proposed by [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://huggingface.co/papers/2305.08891) `guidance_scale` is defined as `φ` in equation 16. of [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://huggingface.co/papers/2305.08891). Guidance rescale factor should fix overexposure when using zero terminal SNR. Used for the video modality.
audio_guidance_scale (`float`、*任意*、デフォルトは`None`) : 負のプロンプトに対する CFG のオーディオガイダンススケールです。CFG の更新ルールは動画とオーディオで同じですが、ガイダンススケールの値はそれぞれ異なる値を使用できます。LTX-2.X の著者たちは、`audio_guidance_scale` は動画の `guidance_scale` に対して高い値にすべきと提案しています（例：LTX-2.3 では、動画を 3.0、オーディオを 7.0 と提案しています）。`None` の場合、動画の値である `guidance_scale` がデフォルトとして使用されます。
audio_stg_scale (`float`、*任意*、デフォルトは`None`) : STG用のオーディオガイダンススケールです。CFGと同様に、STGの更新ルールは動画とオーディオで同じです。LTX-2.3では、動画とオーディオの両方に1.0の値を推奨します。`None`の場合、動画の値`stg_scale`がデフォルトとして使用されます。
audio_modality_scale (`float`、*任意*、デフォルトは`None`) : LTX-2.X のモダリティ分離ガイダンスにおけるオーディオガイダンススケール。CFG と同様に、モダリティガイダンスのルールは、ビデオとオーディオのいずれにおいても同じです。LTX-2.3 の場合、ビデオとオーディオの両方に対して 3.0 の値が推奨されます。`None` の場合、ビデオの値である`modality_scale`がデフォルトとして使用されます。
audio_guidance_rescale (`float`、*任意*、デフォルトは`None`) : 音声モダリティ用の別個のguidance rescale係数です。`None`の場合、デフォルトで動画の値`guidance_rescale`が使用されます。
spatio_temporal_guidance_blocks (`list[int]`、*optional*、デフォルトは`None`) : STGを適用するtransformerブロックのゼロ始まりのインデックスです。STGを使用する場合（`stg_scale`または`audio_stg_scale`が`0`より大きい場合）は、この値を指定する必要があります。LTX-2.0では`[29]`、LTX-2.3では`[28]`を推奨します。
noise_scale (`float`、*任意*、デフォルトは`None`) : 各タイムステップにおけるランダムノイズとデノイズ済み潜在変数の間の補間係数です。`latents`と`audio_latents`にノイズを適用してから、デノイジングを続行します。設定されていない場合、シグマスケジュールから推定されます。
num_videos_per_prompt (`int`、*optional*、デフォルトは 1) : プロンプトごとに生成する動画の数を指定します。
generator (`torch.Generator` または `List[torch.Generator]`、*任意*) : 生成を決定論的にするための [torch ジェネレーター](https://pytorch.org/docs/stable/generated/torch.Generator.html) 1 つまたはそのリスト。
latents (`torch.Tensor`, *任意*) : 動画生成の入力として使用する、ガウス分布からサンプリングされた事前生成されたノイジー・ラテンツ。異なるプロンプトで同じ生成を調整するために使用できます。指定されない場合、指定されたランダム`generator`を使用してサンプリングを行い、ラテンツのテンソルが生成されます。
audio_latents (`torch.Tensor`, *任意*) : 音声生成の入力として使用する、ガウス分布からサンプリングされた事前生成されたノイジー・ラテンツ。異なるプロンプトで同じ生成を調整するために使用できます。指定されない場合、指定されたランダムな`generator`を使用してサンプリングを行い、ラテンツのテンソルが生成されます。
prompt_embeds (`torch.Tensor`, *任意*) : 事前生成されたテキスト埋め込み。テキスト入力の調整、*例えば*プロンプトの重み付けなどを容易に行うために使用できます。指定されない場合、`prompt` 入力引数からテキスト埋め込みが生成されます。
prompt_attention_mask (`torch.Tensor`, *任意*) : テキスト埋め込み用の事前生成されたアテンションマスク。
negative_prompt_embeds (`torch.FloatTensor`, *任意*) : 事前に生成されたネガティブテキスト埋め込み。PixArt-Sigma の場合、このネガティブプロンプトは "" である必要があります。指定されない場合、`negative_prompt` 入力引数から 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`、*optional*、デフォルトは`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[torch.Tensor], condition_strengths: list[float], condition_indices: list[int], 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] の、初期のパック（パッチ化）された潜在変数。
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. 最初のフレームの位置にあるクリーンな条件付け潜在変数（その他の位置はゼロ）。
最初のフレームの位置のトークンを上書きすることにより、最初のフレームの視覚条件付けを適用します。
ここでは、`latent_idx == 0` の条件のみが適用されます（参照実装の `VideoConditionByLatentIndex` と一致）。非ゼロの潜在インデックスにおける条件は、`prepare_keyframe_extras` を介して個別のキーフレームトークンとして追加されます（`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`、*optional*、デフォルトは 1) : 各プロンプトに対して生成すべき動画の数。結果の埋め込みを配置する torch デバイス
prompt_embeds (`torch.Tensor`, *任意*) : 事前生成されたテキスト埋め込み。テキスト入力の調整、*例えば*プロンプトの重み付けなどを容易に行うために使用できます。指定されない場合、`prompt` 入力引数からテキスト埋め込みが生成されます。
negative_prompt_embeds (`torch.Tensor`, *任意*) : 事前に生成されたネガティブなテキスト埋め込み。テキスト入力の調整、*例えば*プロンプトの重み付けなどを容易に行うために使用できます。指定されない場合、`negative_prompt` 入力引数から negative_prompt_embeds が生成されます。
device : (`torch.device`, *任意*): torch デバイス
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)
フレーム条件を適用して、ノイズ付きの動画潜在変数を準備します。
`latent_idx == 0` の場合の初フレーム条件は、初フレーム位置のトークンを上書きすることで適用されます（`VideoConditionByLatentIndex` のセマンティクス）。初フレーム以外の条件（`latent_idx > 0`）は、トークンごとに `conditioning_mask = strength` を設定して、メインの潜在変数シーケンスに連結されます（`VideoConditionByKeyframeIndex` のセマンティクス）。その後、デノイジングループの既存のタイムステップ式 `t * (1 - conditioning_mask)` と後処理のブレンド `denoised * (1 - conditioning_mask) + clean * conditioning_mask` が、ステップごとにこれらを駆動します。
4つの要素のタプルを返します:
- `latents`: 詰められたノイジー・ラテンツ（ベーストークンと、シーケンス次元に連結された任意のキーフレームトークン）。
- `conditioning_mask`: `[0, 1]` の値を持つパックされた conditioning mask — 最初のフレームの位置に `1`、キーフレームの位置に `strength`、その他の位置に `0`。
- `clean_latents`: 条件付き位置におけるクリーンな条件値（その他の位置はゼロ）。`latents` と同じ形状です。
- `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]`、*optional*、デフォルトは `None`) : 画像/動画の条件インスタンスのリスト。
height (`int`、*optional*、デフォルトは`512`) : 希望するピクセル単位の縦幅。
width (`int`、*任意*、デフォルトは`768`) : 希望するピクセル単位の幅。
num_frames (`int`、*任意*、デフォルトは`121`) : 生成される動画の希望フレーム数。
device (`torch.device`、*optional*、デフォルトは`None`) : 前処理された画像/動画テンソルを配置するデバイス。
**戻り値:** `Tuple[List[torch.Tensor], List[float], List[int], List[int]]`
`len(conditions)` の長さを持つリストの4要素のタプルを、次のように返します:
1. 最初のリストは、形状が[batch_size=1, num_channels, num_frames, height, width]の事前処理済み動画テンソルのリストです。
2. 2番目のリストは、条件付けの強度のリストです。
3. 3番目のリストは、各条件に対する潜在空間のインデックスのリストです。
4. 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/ja/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : `transformer`と組み合わせて、エンコードされた動画の潜在変数（latents）のノイズ除去に使用するスケジューラー。
vae ([AutoencoderKLLTX2Video](/docs/diffusers/main/ja/api/models/autoencoderkl_ltx_2#diffusers.AutoencoderKLLTX2Video)) : 動画を潜在表現にエンコードし、潜在表現からデコードするための Variational Auto-Encoder (VAE) モデル。
audio_vae ([AutoencoderKLLTX2Audio](/docs/diffusers/main/ja/api/models/autoencoderkl_audio_ltx_2#diffusers.AutoencoderKLLTX2Audio)) : 音声スペクトログラムをエンコードおよびデコードするための音声 VAE。
text_encoder (`Gemma3ForConditionalGeneration` または `Gemma4UnifiedForConditionalGeneration`) : テキストエンコーダーモデル。
tokenizer (`GemmaTokenizer` または `GemmaTokenizerFast`) : テキストエンコーダー用のトークナイザー。
connectors (`LTX2TextConnectors`) : 動画および音声ブランチ用にテキストエンコーダーの隠れ状態を適応させるために使用されるテキストコネクタスタック。
transformer ([LTX2VideoTransformer3DModel](/docs/diffusers/main/ja/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回のノイズ除去パスのパイプライン。
A pass generates video *and* extra single-pixel-frame keyframe slots, or re-denoises supplied latents seeded from those slots. Callers compose stages: this pipeline at half resolution, [LTX2LatentUpsamplePipeline](/docs/diffusers/main/ja/api/pipelines/ltx2#diffusers.LTX2LatentUpsamplePipeline) spatially, this pipeline again at full resolution with the upsampled slots and an IC-LoRA reference, then [LTX2DFRTemporalRefinePipeline](/docs/diffusers/main/ja/api/pipelines/ltx2#diffusers.LTX2DFRTemporalRefinePipeline) for each temporal refine round. See the LTX-2 docs for the 1080p recipe.
スロットの位置は、VAE の時間軸境界に整列されたセグメントグリッド（`resolve_canvas`）から取得されます。キャンバスはセグメントの整数倍にパディングされ、`output_type="latent"` を指定すると、パディング上のスロットが欠落しないよう、そのパディング済みグリッドが返されます。VAE デコードの前に `trim_canvas` でトリミングしてください。
`generate_slots=True` の場合、`use_keyframes_abs_pos_embedding` が設定された config を持つ transformer が必要です（LTX-2.5 以降）。
参考: https://github.com/Lightricks/LTX-2
#### __call__[[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[float] = [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[str] = ['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`、*optional*、デフォルトは`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)` ビデオ潜在変数。
audio_latents (`torch.Tensor`, *任意*) : 生データのアンパック済み`(batch_size, channels, length, mel_bins)`オーディオ潜在変数。ステージ 2 では引き続きジョイントオーディオパスが実行されますが、合成レシピの出力される波形はステージ 1 のものであり、呼び出し側が保持します。
keyframes_latents (`torch.Tensor`, *任意*) : `generate_slots=True` の場合に使用される、生の `(batch_size, channels, num_slots, height, width)` 形式の slot initials。
keyframe_positions (`list[int]`、*任意*) : 生成スロットのピクセルフレームインデックス。デフォルトは`resolve_canvas(num_frames)`です。
reference_latents (`torch.Tensor`, *任意*) : 生の IC-LoRA 参照動画（通常はステージ 1 のフレーム）。
reference_downscale_factor (`int`、*optional*、デフォルトは`2`) : このパスと参照解像度の比率。参照トークンの座標をスケーリングするために使用されます。
guidance_keyframe_latents (`torch.Tensor`, *任意*) : 固定された生ガイダンスキーフレーム `(batch_size, channels, K, height, width)` — エピローグパス。生成スロットではありません。
guidance_keyframe_positions (`list[int]`、*任意*) : `guidance_keyframe_latents`のピクセルフレームインデックス。
guidance_keyframe_strength (`float`、*任意*、デフォルトは `1.0`) : 固定されたガイダンスキーフレームの条件付け強度です。
generate_slots (`bool`、*任意*、デフォルトは`True`) : 生成されたキーフレームスロットトークンを追加します。エピローグでは、これを`False`に設定し、代わりに`guidance_keyframe_latents`を固定します。
sigmas (`list[float]`, *任意*) : このパス用のノイズスケジュールです。末尾の`0.0`は含まれません。
noise_scale (`float`, *任意*) : 非条件トークンが開始するノイズレベルです。デフォルト値は `sigmas[0]` です。
freeze_audio (`bool`、*任意*、デフォルトは`False`) : シグマ 0 でオーディオを保持します（エピローグ / 凍結されたステージ 1 の波形に続く場合）。
video_tiles (`list[LTX2DFREpilogueTile]`、*optional*) : `epilogue_tiles()` からのエピローグタイルリング。これにより、1回のフォワードパスでは処理しきれないほど解像度が高い場合でも、単一のキャンバスをステップごとに処理できます。各ステップでは、タイルごとに1回ずつトランスフォーマーを実行し、予測結果をブレンドします。このパス固有の RoPE 座標に対してトークンプランとして解決されるため、レイアウトではなくプランが渡されるのではなく、レイアウトが渡されます。座標は [prepare_latents()](/docs/diffusers/main/ja/api/pipelines/ltx2#diffusers.LTX2DFRPipeline.prepare_latents) が実行されて初めて存在するようになるためです。
num_videos_per_prompt (`int`、*optional*、デフォルトは 1) : プロンプトごとに生成する動画の数を指定します。
generator (`torch.Generator` または `list[torch.Generator]`、*任意*) : 再現性のために使用する乱数ジェネレーター。
prompt_embeds (`torch.Tensor`, *任意*) : 事前に生成されたテキスト埋め込み。
prompt_attention_mask (`torch.Tensor`, *任意*) : テキスト埋め込み用の事前生成されたアテンションマスク。
decode_timestep (`float`、デフォルトは`0.0`) : 生成された動画がデコードされるタイムステップ。
decode_noise_scale (`float`、デフォルトは`None`) : デコード時のノイズスケール。
use_cross_timestep (`bool`、*任意*、デフォルトは`True`) : クロスアテンションのモジュレーションにクロスモーダリティのシグマを使用するかどうか。`True`はLTX-2.3以降です。
system_prompt (`str`, *任意*) : プロンプト強化用の任意のシステムプロンプト。`enable_prompt_enhancement`を参照してください。
enable_prompt_enhancement (`bool`、*任意*、デフォルトは`False`) : プロンプトの強化を実行するかどうか。
prompt_max_new_tokens (`int`, *任意*) : プロンプト強化を実行する際に生成する新しいトークンの最大数。
prompt_enhancement_kwargs (`dict[str, Any]`、*省略可*) : プロンプトエンハンサーの `.generate` 呼び出しに渡すキーワード引数。
prompt_enhancement_seed (`int`、*任意*、デフォルトは`10`) : プロンプト強化中のランダム操作に使用されるシード値。
output_type (`str`、*任意*、デフォルトは `"pil"`) : 出力形式。`"pil"`、`"np"`、`"pt"`、または `"latent"` を選択します。Latent 出力はトリムされていないキャンバスです。
return_dict (`bool`, *任意*, デフォルトは `True`) : [LTX2DFRPipelineOutput](/docs/diffusers/main/ja/api/pipelines/ltx2#diffusers.LTX2DFRPipelineOutput) を返すか、プレーンな `(frames, audio, keyframes, keyframe_positions)` タプルを返すかを指定します。
attention_kwargs (`dict`, *任意*) : attention プロセッサに渡される追加の kwargs。
callback_on_step_end (`Callable`, *任意*) : 各デノイジングステップの終了時に呼び出される関数。
callback_on_step_end_tensor_inputs (`List`、*任意*、デフォルトは `["latents"]`) : コールバック関数への Tensor 入力。
max_sequence_length (`int`、*任意*、デフォルトは`1024`) : テキストプロンプトの最大シーケンス長。
**戻り値:** [LTX2DFRPipelineOutput](/docs/diffusers/main/ja/api/pipelines/ltx2#diffusers.LTX2DFRPipelineOutput) または `tuple`
`return_dict` が `True` の場合、[LTX2DFRPipelineOutput](/docs/diffusers/main/ja/api/pipelines/ltx2#diffusers.LTX2DFRPipelineOutput) が返され、それ以外の場合は `(video, audio, keyframes, keyframe_positions)` の `tuple` が返されます。
生成用のパイプラインを呼び出したときに実行される関数。
`height` × `width` の解像度で 1 回のデノイズパスを実行します。呼び出し側で各ステージを構成してください。まずこのパイプラインを半解像度で実行し、空間的アップサンプリングを行い、その後 `latents` / `keyframes_latents` / `reference_latents` を指定してこのパイプラインを再度実行し、最後に各時間ラウンドに対して [LTX2DFRTemporalRefinePipeline](/docs/diffusers/main/ja/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[float], 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、audio Euler step なし）に保ちつつ、audio-to-video の cross-attention を実行します。`audio_latents` が `None` の場合は無視されます。
video_tile_plan (`list`、*任意*) : `video_tile_plan`[`~diffusers.pipelines.ltx2.dfr_layout.video_tile_plan`] からのタイルごとのトークンプラン。指定された場合、各ステップでトランスフォーマーがタイルごとに1回実行され、予測値がブレンドされるため、サンプラーは引き続き単一のフルキャンバスをステップし、各ステップでタイル間の重複部分が一致します。
generator (`torch.Generator`、*optional*) : `LTXEulerAncestralRFScheduler.step()` に転送されます。時間方向のタイルでは、タイルごとにシードを渡すことで、祖先サンプリングがストリームを共有したり、次のタイルの初期ノイズ付与が読み取る状態を消費したりすることを防ぎます。蒸留済み Euler では読み取られません。
step_offset (`int`) : パイプライン全体のスケジュールにおける、このパスの最初のステップのインデックス。`callback_on_step_end` と共有プログレスバーで使用されます。
`sigmas` に対して DFR のノイズ除去パスを 1 回実行し、`(latents, audio_latents)` を返します。どちらもまだパックされた状態のままです。
蒸留済みスケジュールは classifier-free guidance を使用しないため、各ステップごとに 1 回の transformer 呼び出しで済みます。すべてのパスで両方のストリームが実行されるのは、生成されたオーディオが破棄される箇所であっても、動画ブランチがクロスモーダルアテンションを必要とするためです。`freeze_audio=True` を設定すると、オーディオストリームは sigma 0 に固定され（Euler ステップなし）、動画が依然としてクロスアテンションを適用できるようになります。これにより、temporal refine タイルとエピローグは、各タイルが異なるオーディオ実現を再デノイズしなくても、ステージ 1 の発話を追従できます。
x0 条件ブレンドの後、速度は `(latents - denoised) / sigma` となるため、RF ステップ `x0 = x - σ v` を実行すると、ブレンドされた `denoised` が復元されます。ステージ 1 / 2 / エピローグでは [FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/ja/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler) を維持し、その Euler ステップをそのまま適用します。Temporal refine では `LTXEulerAncestralRFScheduler` (`eta=0.5`) に切り替えます。このステップではすべてのトークンに再ノイズが加えられるため、その後で条件ブレンドを再度適用しないと、strength-0.95 のシームアンカーが侵食されます。
#### 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エンコードします。
各条件について、[prepare_latents()](/docs/diffusers/main/ja/api/pipelines/ltx2#diffusers.LTX2DFRPipeline.prepare_latents) の `condition_latents` にそのまま渡せる `(pixel_frame_index, latent, strength, num_pixel_frames)` を返します。エンコーディングと配置を分離しているのは、temporal refine の各ラウンドで条件の位置を `2 ** round` 倍にスケーリングし、タイルごとに基準を再設定する必要があるためです。この処理のために、同じ静止画をタイルごとに1回ずつ再エンコードすべきではありません。
返されるインデックスは`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`、*optional*、デフォルトは 1) : 1 つのプロンプトに対して生成すべき動画の数。
prompt_embeds (`torch.Tensor`, *任意*) : 事前生成されたテキスト埋め込み。テキスト入力の調整、*例えば*プロンプトの重み付けなどを容易に行うために使用できます。指定されない場合、`prompt` 入力引数からテキスト埋め込みが生成されます。
prompt_attention_mask (`torch.Tensor`, *任意*) : `prompt_embeds`用の事前生成されたアテンションマスク。
device : (`torch.device`, *任意*): torch デバイス
dtype : (`torch.dtype`, *任意*): torch dtype
プロンプトをテキストエンコーダーの隠れ状態にエンコードします。
DFR は蒸留された sigma スケジュールを実行します。このスケジュールは classifier-free guidance なしで使用するよう訓練されているため、ここでは 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]`、*optional*) : レイテンツインデックスで位置が指定される、フレーム単位の画像 / 動画の条件。
condition_latents (`list[tuple[int, torch.Tensor, float, int]]`, *任意*) : `conditions` の事前エンコード済み代替値で、`(pixel_frame_index, latent, strength, num_pixel_frames)` の形式です。temporal refine ラウンドでは、条件の位置が `2 ** round` 倍にスケーリングされるため、結果は一般的に latent の境界に収まりません。境界に置けるのは追加された keyframe トークンだけで、これは pixel 単位で配置されます。`pixel_frame_index == 0` は引き続き「最初のフレームを置き換える」ことを意味します。
keyframe_latents (`list[tuple[int, torch.Tensor, float]]`, *任意*) : すでにエンコード済みのキーフレームガイダンスを `(pixel_frame_index, latent, strength)` として指定します。ここで `latent` の形状は `(batch_size, num_channels_latents, 1, latent_height, latent_width)` です。前ラウンドから引き継がれたシームのキーフレームを固定するために、時間方向のリファインラウンドで使用されます。
slot_frame_indices (`list[int]`、*任意*) : 生成されたキーフレームスロットのピクセルフレーム位置。
slot_initial_latents (`torch.Tensor`, *任意*) : ノイズ付与の前にスロットトークンに書き込まれる内容。`(batch_size, num_channels_latents, len(slot_frame_indices), latent_height, latent_width)`
reference_latents (`torch.Tensor`、*任意*) : `(batch_size, num_channels_latents, F, H, W)` IC-LoRA の参照潜在変数。
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`は、パックされたシーケンス内の生成されたキーフレームのスロットトークンをインデックス付けします。スロットが要求されていない場合は`None`です。
1回のDFRノイズ除去パス用に、ノイズ付きのパック済み動画潜在変数を準備します。
パックされたシーケンスは、`[base | keyframes | slots | reference]` のレイアウトで配置されます:
- ベーストークンは、ターゲットの潜在グリッドをカバーし、`latents`が指定されている場合はそこからシードされます。
- `index == 0` の条件は、最初のフレームの位置にクリーンターゲットを設定します。`index > 0` の条件と `keyframe_latents` のすべてのエントリは、トークンごとの条件付けマスクがその強度に等しい追加のキーフレームトークンとして追加されます。
- `slot_frame_indices` は、各位置に対して *生成* されたキーフレームトークンを 1 個の潜在フレーム分だけ追加します。このとき、条件付けマスクは `0`（完全にデノイズ済み）であり、RoPE の時間的範囲はちょうど 1 ピクセルフレーム分です。これらは DFR に追加のフレームを与えるキーフレームのスロットであり、`slot_initial_latents` がその内容を初期化します。
- `reference_latents` は、ステージ1の半解像度潜在変数を、完全にクリーンな IC-LoRA 参照として追加します。この際、空間座標は `reference_downscale_factor` 倍にスケーリングされ、ターゲットの座標空間にマッピングされます。
付加された条件トークンは、その内容を`clean_latents`に保持し、`latents`にはゼロのプレースホルダーを保持します。一方、キーフレームのスロットは、そのシードを`latents`に保持し、`clean_latents`にはゼロを保持します。返される`latents`は、これら2つのノイズ付きの混合です（このメソッドの末尾のノイズ付与ステップを参照）。
#### 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]`、*optional*、デフォルトは `None`) : 画像/動画の条件インスタンスのリスト。
height (`int`、*optional*、デフォルトは`512`) : 希望するピクセル単位の縦幅。
width (`int`、*任意*、デフォルトは`768`) : 希望するピクセル単位の幅。
num_frames (`int`、*任意*、デフォルトは`121`) : 生成される動画の希望フレーム数。
device (`torch.device`、*optional*、デフォルトは`None`) : 前処理された画像/動画テンソルを配置するデバイス。
**戻り値:** `Tuple[List[torch.Tensor], List[float], List[int], List[int]]`
`len(conditions)` の長さを持つリストの4要素のタプルを、次のように返します:
1. 最初のリストは、形状が[batch_size=1, num_channels, num_frames, height, width]の事前処理済み動画テンソルのリストです。
2. 2番目のリストは、条件付けの強度のリストです。
3. 3番目のリストは、各条件に対する潜在空間のインデックスのリストです。
4. 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)` の生ラテンツを、そのまま `guidance_keyframe_latents` として入力に渡せる状態にします。
RGB経由で、キャリーキーフレームを元の解像度の2倍に再エンコードします。
これらは 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`) : 整流フローパラメータ化における Ancestral Euler スケジューラです。DFR の時間レシピに合わせるには、`eta=0.5` で構築してください。
vae ([AutoencoderKLLTX2Video](/docs/diffusers/main/ja/api/models/autoencoderkl_ltx_2#diffusers.AutoencoderKLLTX2Video)) : 動画を潜在表現にエンコードし、潜在表現からデコードするための Variational Auto-Encoder (VAE) モデル。
audio_vae ([AutoencoderKLLTX2Audio](/docs/diffusers/main/ja/api/models/autoencoderkl_audio_ltx_2#diffusers.AutoencoderKLLTX2Audio)) : 音声スペクトログラムをエンコードおよびデコードするための音声 VAE。
text_encoder (`Gemma3ForConditionalGeneration` または `Gemma4UnifiedForConditionalGeneration`) : テキストエンコーダーモデル。
tokenizer (`GemmaTokenizer` または `GemmaTokenizerFast`) : テキストエンコーダー用のトークナイザー。
connectors (`LTX2TextConnectors`) : 動画および音声ブランチ用にテキストエンコーダーの隠れ状態を適応させるために使用されるテキストコネクタスタック。
transformer ([LTX2VideoTransformer3DModel](/docs/diffusers/main/ja/api/models/ltx2_video_transformer3d#diffusers.LTX2VideoTransformer3DModel)) : エンコードされた動画の潜在変数をノイズ除去するための条件付き Transformer アーキテクチャ。
vocoder (`LTX2Vocoder` または `LTX2VocoderWithBWE`) : メルスペクトログラムをオーディオ波形に変換するための Vocoder。
temporal_latent_upsampler (`LTX2LatentUpsamplerModel`) : ラウンドの開始時に適用される、時間方向に2倍の潜在アップサンプラー。
1回の時間軸DFRリファインラウンド: キャンバスを時間軸で2倍に補間し、キーフレームの継ぎ目部分でタイル分割を行い、各タイルに対して祖先デノイズを適用します。その後、後続タイルのリードインを切り捨てて結合し、キャリーキーフレームのバッグをマージします。
スケジューラは `LTXEulerAncestralRFScheduler`（デフォルトで `eta=0.5`）です。Stage 1 / 2 / 空間エピローグは、[LTX2DFRPipeline](/docs/diffusers/main/ja/api/pipelines/ltx2#diffusers.LTX2DFRPipeline) を通じて [FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/ja/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler) のままです。このパイプラインはラウンドごとに1回呼び出してください。呼び出し側が 2x / 4x のループを制御します。
入力される`latents` / `keyframes_latents` / `audio_latents`は正規化されていない生データであり、[LTX2Pipeline](/docs/diffusers/main/ja/api/pipelines/ltx2#diffusers.LTX2Pipeline)と一致します。`keyframe_positions`は、前回のパスで返された位置でなければなりません。ラウンドが実行された後では、元の`num_frames`から再導出することはできません。
#### __call__[[diffusers.LTX2DFRTemporalRefinePipeline.__call__]]
```python
__call__(prompt: str | list[str] = None, latents: Tensor = None, keyframes_latents: Tensor = None, keyframe_positions: list[int] = 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[float] = [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[str] = ['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**キャンバスの生動画潜在変数、`(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`) : 凍結されたステージ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によって2倍になります。
source_seconds (`float`, *optional*) : 凍結されたステージ1の音声の長さです。デフォルト値は `num_frames / frame_rate` であり、最初のラウンドではこれが正しく機能します。ただし、以降のラウンドではタイルがずれないように、元のステージ1の長さを渡す必要があります。
condition_num_frames (`int`, *optional*) : `conditions` をエンコードするために使用された元の生成 `num_frames`。デフォルト値は `num_frames` です。パディングや前回のラウンドの後には、`index=-1` がパディングされた末尾にラップしないように、元のリクエストを渡してください。
round_index (`int`、*optional*、デフォルトは`1`) : 1始まりのラウンド番号。タイルは、祖先ノイズを`seed + 1000 * round_index + tile`でシードし、条件は`2 ** round_index`倍でスケーリングされます。
sigmas (`list[float]`, *任意*) : 終端の`0.0`を除いた、このラウンドのタイル用の蒸留済みスケジュール。
noise_scale (`float`, *任意*) : 非条件トークンが開始するノイズレベルです。デフォルト値は `sigmas[0]` です。
generator (`torch.Generator` または `list[torch.Generator]`、*任意*) : 再現性のために使用する乱数ジェネレーター。祖先サンプリングでは、このジェネレーターの `initial_seed()` から派生したタイルごとの独立したシードを使用します。
prompt_embeds (`torch.Tensor`, *任意*) : 事前に生成されたテキスト埋め込み。
prompt_attention_mask (`torch.Tensor`, *任意*) : テキスト埋め込み用の事前生成されたアテンションマスク。
decode_timestep (`float`、デフォルトは`0.0`) : 生成された動画がデコードされるタイムステップ。
decode_noise_scale (`float`、デフォルトは`None`) : デコード時のノイズスケール。
use_cross_timestep (`bool`、*任意*、デフォルトは`True`) : クロスアテンションのモジュレーションにクロスモーダリティのシグマを使用するかどうか。`True`はLTX-2.3以降です。
output_type (`str`、*任意*、デフォルトは `"pil"`) : 出力形式。`"pil"`、`"np"`、`"pt"`、または `"latent"` を選択します。Latent 出力はトリムされていないキャンバスです。
return_dict (`bool`, *任意*, デフォルトは `True`) : [LTX2DFRPipelineOutput](/docs/diffusers/main/ja/api/pipelines/ltx2#diffusers.LTX2DFRPipelineOutput) を返すか、プレーンな `(frames, audio, keyframes, keyframe_positions)` タプルを返すかを指定します。
attention_kwargs (`dict`, *任意*) : attention プロセッサに渡される追加の kwargs。
callback_on_step_end (`Callable`、*任意*) : 各タイル全体で、デノイジングステップの終了時に呼び出される関数。
callback_on_step_end_tensor_inputs (`List`、*任意*、デフォルトは `["latents"]`) : コールバック関数への Tensor 入力。
max_sequence_length (`int`、*任意*、デフォルトは`1024`) : テキストプロンプトの最大シーケンス長。
**戻り値:** [LTX2DFRPipelineOutput](/docs/diffusers/main/ja/api/pipelines/ltx2#diffusers.LTX2DFRPipelineOutput) または `tuple`
`return_dict` が `True` の場合、[LTX2DFRPipelineOutput](/docs/diffusers/main/ja/api/pipelines/ltx2#diffusers.LTX2DFRPipelineOutput) が返され、それ以外の場合は `(video, audio, keyframes, keyframe_positions)` の `tuple` が返されます。
1回の時間軸リファインラウンドを実行します。
例:
```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[float], 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、audio Euler step なし）に保ちつつ、audio-to-video の cross-attention を実行します。`audio_latents` が `None` の場合は無視されます。
video_tile_plan (`list`、*任意*) : `video_tile_plan`[`~diffusers.pipelines.ltx2.dfr_layout.video_tile_plan`] からのタイルごとのトークンプラン。指定された場合、各ステップでトランスフォーマーがタイルごとに1回実行され、予測値がブレンドされるため、サンプラーは引き続き単一のフルキャンバスをステップし、各ステップでタイル間の重複部分が一致します。
generator (`torch.Generator`、*optional*) : `LTXEulerAncestralRFScheduler.step()` に転送されます。時間方向のタイルでは、タイルごとにシードを渡すことで、祖先サンプリングがストリームを共有したり、次のタイルの初期ノイズ付与が読み取る状態を消費したりすることを防ぎます。蒸留済み Euler では読み取られません。
step_offset (`int`) : パイプライン全体のスケジュールにおける、このパスの最初のステップのインデックス。`callback_on_step_end` と共有プログレスバーで使用されます。
`sigmas` に対して DFR のノイズ除去パスを 1 回実行し、`(latents, audio_latents)` を返します。どちらもまだパックされた状態のままです。
蒸留済みスケジュールは classifier-free guidance を使用しないため、各ステップごとに 1 回の transformer 呼び出しで済みます。すべてのパスで両方のストリームが実行されるのは、生成されたオーディオが破棄される箇所であっても、動画ブランチがクロスモーダルアテンションを必要とするためです。`freeze_audio=True` を設定すると、オーディオストリームは sigma 0 に固定され（Euler ステップなし）、動画が依然としてクロスアテンションを適用できるようになります。これにより、temporal refine タイルとエピローグは、各タイルが異なるオーディオ実現を再デノイズしなくても、ステージ 1 の発話を追従できます。
x0 条件ブレンドの後、速度は `(latents - denoised) / sigma` となるため、RF ステップ `x0 = x - σ v` を実行すると、ブレンドされた `denoised` が復元されます。ステージ 1 / 2 / エピローグでは [FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/ja/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler) を維持し、その Euler ステップをそのまま適用します。Temporal refine では `LTXEulerAncestralRFScheduler` (`eta=0.5`) に切り替えます。このステップではすべてのトークンに再ノイズが加えられるため、その後で条件ブレンドを再度適用しないと、strength-0.95 のシームアンカーが侵食されます。
#### 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エンコードします。
各条件について、[prepare_latents()](/docs/diffusers/main/ja/api/pipelines/ltx2#diffusers.LTX2DFRPipeline.prepare_latents) の `condition_latents` にそのまま渡せる `(pixel_frame_index, latent, strength, num_pixel_frames)` を返します。エンコーディングと配置を分離しているのは、temporal refine の各ラウンドで条件の位置を `2 ** round` 倍にスケーリングし、タイルごとに基準を再設定する必要があるためです。この処理のために、同じ静止画をタイルごとに1回ずつ再エンコードすべきではありません。
返されるインデックスは`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`、*optional*、デフォルトは 1) : 1 つのプロンプトに対して生成すべき動画の数。
prompt_embeds (`torch.Tensor`, *任意*) : 事前生成されたテキスト埋め込み。テキスト入力の調整、*例えば*プロンプトの重み付けなどを容易に行うために使用できます。指定されない場合、`prompt` 入力引数からテキスト埋め込みが生成されます。
prompt_attention_mask (`torch.Tensor`, *任意*) : `prompt_embeds`用の事前生成されたアテンションマスク。
device : (`torch.device`, *任意*): torch デバイス
dtype : (`torch.dtype`, *任意*): torch dtype
プロンプトをテキストエンコーダーの隠れ状態にエンコードします。
DFR は蒸留された sigma スケジュールを実行します。このスケジュールは classifier-free guidance なしで使用するよう訓練されているため、ここでは 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]`、*optional*) : レイテンツインデックスで位置が指定される、フレーム単位の画像 / 動画の条件。
condition_latents (`list[tuple[int, torch.Tensor, float, int]]`, *任意*) : `conditions` の事前エンコード済み代替値で、`(pixel_frame_index, latent, strength, num_pixel_frames)` の形式です。temporal refine ラウンドでは、条件の位置が `2 ** round` 倍にスケーリングされるため、結果は一般的に latent の境界に収まりません。境界に置けるのは追加された keyframe トークンだけで、これは pixel 単位で配置されます。`pixel_frame_index == 0` は引き続き「最初のフレームを置き換える」ことを意味します。
keyframe_latents (`list[tuple[int, torch.Tensor, float]]`, *任意*) : すでにエンコード済みのキーフレームガイダンスを `(pixel_frame_index, latent, strength)` として指定します。ここで `latent` の形状は `(batch_size, num_channels_latents, 1, latent_height, latent_width)` です。前ラウンドから引き継がれたシームのキーフレームを固定するために、時間方向のリファインラウンドで使用されます。
slot_frame_indices (`list[int]`、*任意*) : 生成されたキーフレームスロットのピクセルフレーム位置。
slot_initial_latents (`torch.Tensor`, *任意*) : ノイズ付与の前にスロットトークンに書き込まれる内容。`(batch_size, num_channels_latents, len(slot_frame_indices), latent_height, latent_width)`
reference_latents (`torch.Tensor`、*任意*) : `(batch_size, num_channels_latents, F, H, W)` IC-LoRA の参照潜在変数。
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`は、パックされたシーケンス内の生成されたキーフレームのスロットトークンをインデックス付けします。スロットが要求されていない場合は`None`です。
1回のDFRノイズ除去パス用に、ノイズ付きのパック済み動画潜在変数を準備します。
パックされたシーケンスは、`[base | keyframes | slots | reference]` のレイアウトで配置されます:
- ベーストークンは、ターゲットの潜在グリッドをカバーし、`latents`が指定されている場合はそこからシードされます。
- `index == 0` の条件は、最初のフレームの位置にクリーンターゲットを設定します。`index > 0` の条件と `keyframe_latents` のすべてのエントリは、トークンごとの条件付けマスクがその強度に等しい追加のキーフレームトークンとして追加されます。
- `slot_frame_indices` は、各位置に対して *生成* されたキーフレームトークンを 1 個の潜在フレーム分だけ追加します。このとき、条件付けマスクは `0`（完全にデノイズ済み）であり、RoPE の時間的範囲はちょうど 1 ピクセルフレーム分です。これらは DFR に追加のフレームを与えるキーフレームのスロットであり、`slot_initial_latents` がその内容を初期化します。
- `reference_latents` は、ステージ1の半解像度潜在変数を、完全にクリーンな IC-LoRA 参照として追加します。この際、空間座標は `reference_downscale_factor` 倍にスケーリングされ、ターゲットの座標空間にマッピングされます。
付加された条件トークンは、その内容を`clean_latents`に保持し、`latents`にはゼロのプレースホルダーを保持します。一方、キーフレームのスロットは、そのシードを`latents`に保持し、`clean_latents`にはゼロを保持します。返される`latents`は、これら2つのノイズ付きの混合です（このメソッドの末尾のノイズ付与ステップを参照）。
#### 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]`、*optional*、デフォルトは `None`) : 画像/動画の条件インスタンスのリスト。
height (`int`、*optional*、デフォルトは`512`) : 希望するピクセル単位の縦幅。
width (`int`、*任意*、デフォルトは`768`) : 希望するピクセル単位の幅。
num_frames (`int`、*任意*、デフォルトは`121`) : 生成される動画の希望フレーム数。
device (`torch.device`、*optional*、デフォルトは`None`) : 前処理された画像/動画テンソルを配置するデバイス。
**戻り値:** `Tuple[List[torch.Tensor], List[float], List[int], List[int]]`
`len(conditions)` の長さを持つリストの4要素のタプルを、次のように返します:
1. 最初のリストは、形状が[batch_size=1, num_channels, num_frames, height, width]の事前処理済み動画テンソルのリストです。
2. 2番目のリストは、条件付けの強度のリストです。
3. 3番目のリストは、各条件に対する潜在空間のインデックスのリストです。
4. 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`を実行し、期待される形式に合わせて生のVAE潜在空間を往復します。
## 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 の出力はトリミングされていないキャンバスで、形状は `(batch_size, num_channels, latent_frames, latent_height, latent_width)` です。
audio (`torch.Tensor`、`np.ndarray`) : 対応するオーディオの潜在変数または波形。
keyframes (`torch.Tensor`, *任意*) : 生成または引き継がれたキーフレームの潜在変数で、形状は `(batch_size, num_channels, num_keyframes, latent_height, latent_width)` です。`output_type != "latent"` の場合、またはパスがスロットを生成しなかった場合（例：タイル化されたエピローグ）は `None` になります。
keyframe_positions (`list[int]`、*任意*) : このパスのキャンバスにおける各キーフレームのピクセルフレームインデックス。`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)
#### __call__[[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`、*optional*、デフォルトは `768`) : 入力動画のピクセル単位の幅です（生成される動画はより高い解像度になります）。
num_frames (`int`、*任意*、デフォルトは`121`) : 入力動画のフレーム数。
spatial_patch_size (`int`、*任意*、デフォルトは `1`) : 動画潜在変数の空間パッチサイズです。`latents` が指定されている場合、アンパッキングが必要なときに使用されます。
temporal_patch_size (`int`、*任意*、デフォルトは `1`) : 動画潜在変数の時間方向のパッチサイズです。`latents` が指定されている場合、アンパッキングが必要なときに使用されます。
latents (`torch.Tensor`, *任意*) : 事前に生成された動画の潜在変数。`video` 引数の代わりに指定できます。形状が `(batch_size, seq_len, hidden_dim)` のパッチシーケンス、または形状が `(batch_size, latent_channels, latent_frames, latent_height, latent_width)` の動画潜在変数のいずれかです。
latents_normalized (`bool`、*任意*、デフォルトは`False`) : `latents`が指定されている場合、`latents`をVAEの潜在平均と標準偏差で正規化するかを示します。`True`の場合、`latents`は潜在アップサンプラーに渡される前に非正規化されます。
decode_timestep (`float`、デフォルトは`0.0`) : 生成された動画がデコードされるタイムステップ。
decode_noise_scale (`float`、デフォルトは`None`) : デコードタイムステップにおける、ランダムノイズとデノイズ済み潜在変数の間の補間係数。
adain_factor (`float`, *任意*、デフォルトは `0.0`) : アップサンプリングされた潜在変数と元の潜在変数の間の Adaptive Instance Normalization (AdaIN) ブレンディング係数。値は [-10.0, 10.0] の範囲である必要があります。デフォルトの 0.0 を指定すると、AdaIN は実行されません。
tone_map_compression_ratio (`float`、*任意*、デフォルトは `0.0`) : トーンマッピングの圧縮強度です。これにより、潜在値のダイナミックレンジが縮小されます。高分散の潜在値の正規化や、生成時の出力の条件付けに有用です。値は [0, 1] の範囲である必要があります。0.0（デフォルト）はトーンマッピングが適用されないことを意味し、1.0 は完全な圧縮効果に対応します。
generator (`torch.Generator` または `list[torch.Generator]`、*任意*) : 生成を決定論的にするための [torch ジェネレーター](https://pytorch.org/docs/stable/generated/torch.Generator.html) 1 つまたはそのリスト。
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`) : 正規化対象の入力潜在変数
reference_latents (`torch.Tensor`) : スタイル統計を提供する参照潜在変数。
factor (`float`) : 元の潜在変数と変換後の潜在変数の間のブレンド係数。範囲: -10.0 から 10.0、デフォルト: 1.0
**戻り値:** `torch.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 入力と同じ形状の、トーンマッピングされた潜在テンソル。
シグモイドベースの圧縮を用いて、潜在値のダイナミックレンジを知覚的に滑らかに低減するために、非線形トーンマッピング関数を潜在値に適用します。
`compression` 係数を用いて動的な挙動を制御する場合など、生成時の出力を条件付けたり、高分散な潜在変数を正則化したりする際に有用です。
## 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/ja/api/models/ltx2_diffusion_decoder#diffusers.LTX2VideoDiffusionDecoderModel)) : ディフュージョン・ビデオ・デコーダー。
scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/ja/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)) : デコーダーのデノイジングステップを制御するスケジューラー。
vae ([AutoencoderKLLTX2Video](/docs/diffusers/main/ja/api/models/autoencoderkl_ltx_2#diffusers.AutoencoderKLLTX2Video)、*任意*) : 非正規化に使用される潜在統計情報の参照にのみ使用されます。省略した場合、パイプラインは LTX-2 のデフォルト値にフォールバックするため、デコード専用のワークフローでは第 2 のオートエンコーダーを読み込む必要はありません。
LTX-2.5 で導入された拡散デコーダーを使用して、LTX-2 の動画潜在変数をデコードします。
畳み込みデコーダーとは異なり、このデコーダー自体が小型の拡散モデルです。潜在変数から構築されたコンテキストボリュームに条件付けられてピクセルのノイズ除去を行うため、スケジューラーとジェネレーターが必要です。`output_type="latent"` で実行された任意の LTX-2 パイプラインと組み合わせ、潜在変数の統計量がすでに適用されているため `denormalize=False` を渡してください。
#### __call__[[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`) : デコード前に潜在変数に統計情報を適用するかどうか。潜在変数がすでに正規化解除済みの場合は`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`) : video connector の出力幅。
audio_cross_attention_dim (`int`、デフォルトは`2048`) : 音声コネクタの出力幅。
pooler_hidden_dim (`int`、デフォルトは`256`) : 両方のモーダリティが射影される共有隠れ次元。
num_queries (`int`、デフォルトは`1`) : 学習可能なプーリングクエリの数。
num_pooler_heads (`int`、デフォルトは`4`) : プーラーで使用されるアテンションヘッドの数。
mlp_hidden_dim (`int`、デフォルトは`256`) : 出力 MLP の隠れ幅。`mlp_hidden` サブモジュールと衝突を避けるため、`_dim` サフィックスを付けて命名しています。そうしないと、`ConfigMixin.__getattr__` がこの設定値でサブモジュールをシャドウしてしまうためです。
キャプションから示唆されるショットの自然な長さを、LTX-2のテキストコネクタの出力から予測します。
ヘッドはモダリティ非依存です: ビデオとオーディオのコネクタ出力のいずれか、または両方を渡します。モダリティ固有の入力射影が各ストリームを共有プーラ次元にマッピングし、学習可能なモダリティ埋め込みがストリームにタグ付けを行うことで、プーラがそれらを区別できるようにします。さらに、小さな 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)`、*optional*) : Video connector の出力。
audio_tokens (`torch.Tensor`、shape `(batch_size, seq_len, audio_cross_attention_dim)`、*optional*) : Audio connector の出力。
**戻り値:** `torch.Tensor`、形状 `(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`) : 予測された再生時間をフレーム数に変換するために使用される、1秒あたりのフレーム数。
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`）にスナップします。
クランプはスナップの前に適用されます。クランプされたフレーム数は必ずしもグリッドに整列しているとは限るため、先にスナップを実行すると異なる結果になります。スナップは切り捨てを行うため、最小値を下回る可能性があります。その場合、結果は次のグリッドポイントに切り上げられてスナップされるため、フレーム数は範囲内に保たれます。
境界が狭すぎると、グリッドポイントが1つも含まれないフレームウィンドウに変換されることがあります。24 fps の場合、`[1.0s, 1.02s]` は `[24, 24]` に丸められ、24 は `8k + 1` ではありません。この場合、最も近いグリッドポイントが使用され、警告が記録されます。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)
LTX-2用のAutoブロック。テキストから動画へ、画像から動画へ、条件から動画へ、およびコンテキスト内（IC-LoRA）生成（動画と音声の同時生成）に対応しています。
サポートされているワークフロー:
- `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`)
入力: 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`, *任意*): プロンプトエンハンスメント中に生成する新しいトークンの最大数。デフォルトは 600 で、LTX-2.5 Gemma-4 エンハンサーの予算に相当します。 prompt_enhancement_kwargs (`dict`, *任意*): エンハンサーの `.generate` 呼び出し用のキーワード引数。デフォルトでは貪欲デコーディングを使用します。 prompt_enhancement_seed (`int`, *任意*, デフォルトは 10): プロンプトエンハンスメント用のランダムシード (LTX-2.5 の貪欲デコーディング下では無効)。 generator (`Generator`, *任意*): 決定論的な生成のための Torch ジェネレーター。 image (`Image | list`, *任意*): デノイジング用の参照画像。単一の画像または画像のリストを指定できます。 negative_prompt (`str`, *任意*): 画像生成をガイドしないためのプロンプトまたはプロンプトのリスト。 max_sequence_length (`int`, *任意*, デフォルトは 1024): プロンプトエンコーディングの最大シーケンス長。 min_seconds (`float`, *任意*, デフォルトは 1.0): 自動予測される再生時間の下限値。 max_seconds (`float`, *任意*, デフォルトは 20.0): 自動予測される再生時間の上限値。 `min_seconds` より厳密に大きい値である必要があります。 frame_rate (`float`, *任意*, デフォルトは 24.0): 生成される動画の毎秒フレーム数。 height (`int`, *任意*, デフォルトは 512): 生成される画像のピクセル単位の縦幅。 width (`int`, *任意*, デフォルトは 704): 生成される画像のピクセル単位の横幅。 image_crf (`int`, *任意*): 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`, *任意*): 形状 [1, C, F, H, W] の条件ごとの正規化された VAE 潜在変数。 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`, *任意*): デコードタイムステップでの潜在変数に適用されるノイズ補間係数。
出力: 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/ja/api/pipelines/ltx2#diffusers.LTX2ModularPipeline) と同一ですが、デフォルトのブロックが拡散型ビデオデコーダーでデコードされる点が異なります。これは LTX-2.5 以降のネイティブデフォルトです。チェックポイントは `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 以降のネイティブデフォルトが拡散デコーダーであるため、動画デコーダーが `LTX2DiffusionVaeDecoderStep` になっています。代わりに畳み込み VAE でデコードするには、デコードブロックを差し替えてください: `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`)
入力: 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`, *任意*): プロンプトエンハンスメント中に生成する新しいトークンの最大数。デフォルトは 600 で、LTX-2.5 Gemma-4 エンハンサーの予算に相当します。 prompt_enhancement_kwargs (`dict`, *任意*): エンハンサーの `.generate` 呼び出し用のキーワード引数。デフォルトでは貪欲デコーディングを使用します。 prompt_enhancement_seed (`int`, *任意*, デフォルトは 10): プロンプトエンハンスメント用の乱数シード (LTX-2.5 の貪欲デコーディング下では無効)。 generator (`Generator`, *任意*): 決定論的な生成のための Torch ジェネレーター。 image (`Image | list`, *任意*): デノイジング用の参照画像。単一の画像または画像のリストを指定できます。 negative_prompt (`str`, *任意*): 画像生成を導かないプロンプトまたはプロンプトのリスト。 max_sequence_length (`int`, *任意*, デフォルトは 1024): プロンプトエンコーディングの最大シーケンス長。 min_seconds (`float`, *任意*, デフォルトは 1.0): 自動予測される再生時間の下限。 max_seconds (`float`, *任意*, デフォルトは 20.0): 自動予測される再生時間の上限。 `min_seconds` より厳密に大きい値である必要があります。 frame_rate (`float`, *任意*, デフォルトは 24.0): 生成される動画の毎秒フレーム数。 height (`int`, *任意*, デフォルトは 512): 生成される画像のピクセル単位の縦幅。 width (`int`, *任意*, デフォルトは 704): 生成される画像のピクセル単位の横幅。 image_crf (`int`, *任意*): 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`, *任意*): `LTX2ReferenceCondition` (またはそのリスト) で、その動画は IC-LoRA アダプターが注意を向ける追加の潜在トークンにエンコードされます。 reference_downscale_factor (`int`, *任意*, デフォルトは 1): ターゲット解像度と参照解像度の比率。2 を指定すると、参照はターゲット解像度の半分での前処理が行われます。空間座標はこの係数でスケーリングされ、参照トークンがターゲット座標空間に配置されるようにします。IC-LoRA の学習時に使用した係数と一致させる必要があります。 conditioning_attention_strength (`float`, *任意*, デフォルトは 1.0): ノイジーなトークンと参照トークンが互いにどの程度強く注意を向けるかを制御する [0, 1] 内のスカラー。1.0 (デフォルト) では注意はマスクされません。 conditioning_attention_mask (`Tensor`, *任意*): 形状 (1, 1, F, H, W) で値が [0, 1] のピクセル空間マスク。空間的に変化する注意強度を指定します。参照の潜在グリッドにダウンサンプリングされ、 `conditioning_attention_strength` 倍されます。 motion_speed (`float`, *任意*, デフォルトは 1.0): 実時間に対するモーションの速度。位置埋め込みは `frame_rate / motion_speed` に条件付けられるため、1 未満の値はモーションを減速させます。例えば、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`, *任意*): 注意プロセッサー用の追加のキーワード引数。 image_latents (`Tensor`, *任意*): 画像から動画への条件付けに使用される VAE エンコードされた参照画像の潜在変数。 output_type (`str`, *任意*, デフォルトは pil): 出力形式: 'pil', 'np', 'pt'。
出力: videos (`list`): 生成された動画。 audio (`Tensor`): 生成された音声波形。
#
# 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 についてもこれらのデフォルト値を使用しています。
本番環境での高品質な生成を実現するための推奨パイプラインです。このパイプラインは2つの段階で構成されています。
- ステージ1: クラスフリーガイダンス（CFG）を用いた拡散サンプリングにより、ターゲット解像度で動画を生成します。このステージでは、テキスト/画像の条件付けを尊重した、一貫性のある低ノイズの動画シーケンスが生成されます。
- Stage 2: Stage 1 の出力を 2 倍にアップサンプリングし、蒸留された LoRA モデルを使用して詳細を精錬することで、忠実度と視覚的な品質を向上させます。Stage 2 では、Stage 1 の構造を維持しつつ、テクスチャとシャープネスを強化するために、より軽い CFG を適用する場合があります。
テキストから動画への変換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,
Xet Storage Details
- Size:
- 264 kB
- Xet hash:
- 7955a8653e5e2ecbf411e180066f0cc55b531de33daf0b3538d4ab28036e4070
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.