Diffusers 文档

LTX 视频

Diffusers

加入 Hugging Face 社区

并获得增强的文档体验

协作处理模型、数据集和 Spaces

通过加速推理获得更快的示例

切换文档主题

开始使用

LTX 视频

LTX Video 是首个基于 DiT 的视频生成模型，能够实时生成高质量视频。它以 768x512 分辨率生成 24 FPS 视频，速度比观看速度还快。该模型在大型多样化视频数据集上进行训练，生成具有逼真且内容多样的视频。我们为文本到视频以及图像+文本到视频用例提供模型。

请务必查看 Schedulers 指南，了解如何探索 scheduler 速度和质量之间的权衡，并查看跨 pipelines 重用组件部分，了解如何有效地将相同组件加载到多个 pipelines 中。

可用模型

模型名称	推荐 dtype
`LTX Video 0.9.0`	`torch.bfloat16`
`LTX Video 0.9.1`	`torch.bfloat16`

注意：推荐的 dtype 适用于 transformer 组件。VAE 和文本编码器可以是 torch.float32、torch.bfloat16 或 torch.float16，但推荐的 dtype 是 torch.bfloat16，与原始仓库中使用的一致。

加载单个文件

也可以使用 ~ModelMixin.from_single_file 加载原始 LTX Video 检查点。我们建议对 Lightricks 系列模型使用 from_single_file，因为他们计划将来以单个文件格式发布多个模型。

import torch
from diffusers import AutoencoderKLLTXVideo, LTXImageToVideoPipeline, LTXVideoTransformer3DModel

# `single_file_url` could also be https://huggingface.co/Lightricks/LTX-Video/ltx-video-2b-v0.9.1.safetensors
single_file_url = "https://huggingface.co/Lightricks/LTX-Video/ltx-video-2b-v0.9.safetensors"
transformer = LTXVideoTransformer3DModel.from_single_file(
  single_file_url, torch_dtype=torch.bfloat16
)
vae = AutoencoderKLLTXVideo.from_single_file(single_file_url, torch_dtype=torch.bfloat16)
pipe = LTXImageToVideoPipeline.from_pretrained(
  "Lightricks/LTX-Video", transformer=transformer, vae=vae, torch_dtype=torch.bfloat16
)

# ... inference code ...

或者，pipeline 可以使用 ~FromSingleFileMixin.from_single_file 加载权重。

import torch
from diffusers import LTXImageToVideoPipeline
from transformers import T5EncoderModel, T5Tokenizer

single_file_url = "https://huggingface.co/Lightricks/LTX-Video/ltx-video-2b-v0.9.safetensors"
text_encoder = T5EncoderModel.from_pretrained(
  "Lightricks/LTX-Video", subfolder="text_encoder", torch_dtype=torch.bfloat16
)
tokenizer = T5Tokenizer.from_pretrained(
  "Lightricks/LTX-Video", subfolder="tokenizer", torch_dtype=torch.bfloat16
)
pipe = LTXImageToVideoPipeline.from_single_file(
  single_file_url, text_encoder=text_encoder, tokenizer=tokenizer, torch_dtype=torch.bfloat16
)

也支持加载 LTX GGUF 检查点

import torch
from diffusers.utils import export_to_video
from diffusers import LTXPipeline, LTXVideoTransformer3DModel, GGUFQuantizationConfig

ckpt_path = (
    "https://huggingface.co/city96/LTX-Video-gguf/blob/main/ltx-video-2b-v0.9-Q3_K_S.gguf"
)
transformer = LTXVideoTransformer3DModel.from_single_file(
    ckpt_path,
    quantization_config=GGUFQuantizationConfig(compute_dtype=torch.bfloat16),
    torch_dtype=torch.bfloat16,
)
pipe = LTXPipeline.from_pretrained(
    "Lightricks/LTX-Video",
    transformer=transformer,
    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"

video = pipe(
    prompt=prompt,
    negative_prompt=negative_prompt,
    width=704,
    height=480,
    num_frames=161,
    num_inference_steps=50,
).frames[0]
export_to_video(video, "output_gguf_ltx.mp4", fps=24)

请务必阅读关于 GGUF 的文档，以了解有关我们 GGUF 支持的更多信息。

加载 LTX Video 0.9.1 权重并运行推理。

import torch
from diffusers import LTXPipeline
from diffusers.utils import export_to_video

pipe = LTXPipeline.from_pretrained("a-r-r-o-w/LTX-Video-0.9.1-diffusers", torch_dtype=torch.bfloat16)
pipe.to("cuda")

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"

video = pipe(
    prompt=prompt,
    negative_prompt=negative_prompt,
    width=768,
    height=512,
    num_frames=161,
    decode_timestep=0.03,
    decode_noise_scale=0.025,
    num_inference_steps=50,
).frames[0]
export_to_video(video, "output.mp4", fps=24)

请参阅此部分，详细了解如何优化内存消耗。

LTXPipeline

class diffusers.LTXPipeline

< source >

( scheduler: FlowMatchEulerDiscreteScheduler vae: AutoencoderKLLTXVideo text_encoder: T5EncoderModel tokenizer: T5TokenizerFast transformer: LTXVideoTransformer3DModel )

参数

transformer (LTXVideoTransformer3DModel) — 用于去噪编码视频潜在表示的条件 Transformer 架构。
scheduler (FlowMatchEulerDiscreteScheduler) — 一个与 transformer 结合使用的调度器，用于去噪编码图像潜在表示。
vae (AutoencoderKLLTXVideo) — 变分自动编码器 (VAE) 模型，用于将图像编码和解码为潜在表示和从潜在表示解码为图像。
text_encoder (T5EncoderModel) — T5, 特别是 google/t5-v1_1-xxl 变体。
tokenizer (CLIPTokenizer) — CLIPTokenizer 类的分词器。
tokenizer (T5TokenizerFast) — T5TokenizerFast 类的第二个分词器。

用于文本到视频生成的 Pipeline。

参考： https://github.com/Lightricks/LTX-Video

call

< source >

( prompt: typing.Union[str, typing.List[str]] = None negative_prompt: typing.Union[str, typing.List[str], NoneType] = None height: int = 512 width: int = 704 num_frames: int = 161 frame_rate: int = 25 num_inference_steps: int = 50 timesteps: typing.List[int] = None guidance_scale: float = 3 num_videos_per_prompt: typing.Optional[int] = 1 generator: typing.Union[torch._C.Generator, typing.List[torch._C.Generator], NoneType] = None 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: typing.Union[float, typing.List[float]] = 0.0 decode_noise_scale: typing.Union[float, typing.List[float], NoneType] = None output_type: typing.Optional[str] = 'pil' return_dict: bool = True attention_kwargs: typing.Optional[typing.Dict[str, typing.Any]] = None callback_on_step_end: typing.Optional[typing.Callable[[int, int, typing.Dict], NoneType]] = None callback_on_step_end_tensor_inputs: typing.List[str] = ['latents'] max_sequence_length: int = 128 ) → ~pipelines.ltx.LTXPipelineOutput 或 tuple

参数

prompt (str 或 List[str], 可选) — 用于引导图像生成的 prompt 或 prompts。如果未定义，则必须传递 prompt_embeds。代替。
height (int, 默认为 512) — 生成图像的高度像素值。默认设置为 480 以获得最佳效果。
width (int, 默认为 704) — 生成图像的宽度像素值。默认设置为 848 以获得最佳效果。
num_frames (int, 默认为 161) — 要生成的视频帧数。
num_inference_steps (int, 可选, 默认为 50) — 去噪步骤的数量。更多的去噪步骤通常会带来更高质量的图像，但会牺牲更慢的推理速度。
timesteps (List[int], 可选) — 用于支持在其 set_timesteps 方法中使用 timesteps 参数的调度器的去噪过程的自定义时间步长。如果未定义，则将使用传递 num_inference_steps 时的默认行为。必须按降序排列。
guidance_scale (float, 默认为 3 ) — Classifier-Free Diffusion Guidance 中定义的引导缩放。 guidance_scale 定义为 Imagen Paper 的公式 2 中的 w。通过设置 guidance_scale > 1 启用引导缩放。较高的引导缩放鼓励生成与文本 prompt 紧密相关的图像，通常以降低图像质量为代价。
num_videos_per_prompt (int, 可选, 默认为 1) — 每个 prompt 生成的视频数量。
generator (torch.Generator 或 List[torch.Generator], 可选) — 用于使生成具有确定性的一个或多个 torch generator(s)。
latents (torch.Tensor, 可选) — 预生成的噪声潜在表示，从高斯分布中采样，用作图像生成的输入。可用于使用不同的 prompts 调整相同的生成。如果未提供，则将使用提供的随机 generator 采样生成潜在张量。
prompt_embeds (torch.Tensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如 prompt 权重。如果未提供，将从 prompt 输入参数生成文本嵌入。
prompt_attention_mask (torch.Tensor, 可选) — 预生成的文本嵌入的注意力掩码。
negative_prompt_embeds (torch.FloatTensor, 可选) — 预生成的负面文本嵌入。对于 PixArt-Sigma，此负面 prompt 应为 ""。如果未提供，将从 negative_prompt 输入参数生成 negative_prompt_embeds。
negative_prompt_attention_mask (torch.FloatTensor, 可选) — 预生成的负面文本嵌入的注意力掩码。
decode_timestep (float, 默认为 0.0) — 生成视频被解码的时间步长。
decode_noise_scale (float, 默认为 None) — 解码时间步长时随机噪声和去噪潜在表示之间的插值因子。
output_type (str, 可选, 默认为 "pil") — 生成图像的输出格式。在 PIL: PIL.Image.Image 或 np.array 之间选择。
return_dict (bool, 可选, 默认为 True) — 是否返回 ~pipelines.ltx.LTXPipelineOutput 而不是普通元组。
attention_kwargs (dict, 可选) — 一个 kwargs 字典，如果指定，则作为 AttentionProcessor 传递，如 diffusers.models.attention_processor 中的 self.processor 下定义。
callback_on_step_end (Callable, 可选) — 在推理过程中，每个去噪步骤结束时调用的函数。该函数使用以下参数调用：callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)。 callback_kwargs 将包含由 callback_on_step_end_tensor_inputs 指定的所有张量列表。
callback_on_step_end_tensor_inputs (List, 可选) — callback_on_step_end 函数的张量输入列表。列表中指定的张量将作为 callback_kwargs 参数传递。您将只能包含管道类的 ._callback_tensor_inputs 属性中列出的变量。
max_sequence_length (int 默认为 128) — 与 prompt 一起使用的最大序列长度。

~pipelines.ltx.LTXPipelineOutput 或 tuple

如果 return_dict 为 True，则返回 ~pipelines.ltx.LTXPipelineOutput，否则返回 tuple，其中第一个元素是包含生成图像的列表。

调用管道进行生成时调用的函数。

示例

>>> import torch
>>> from diffusers import LTXPipeline
>>> from diffusers.utils import export_to_video

>>> pipe = LTXPipeline.from_pretrained("Lightricks/LTX-Video", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")

>>> 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"

>>> video = pipe(
...     prompt=prompt,
...     negative_prompt=negative_prompt,
...     width=704,
...     height=480,
...     num_frames=161,
...     num_inference_steps=50,
... ).frames[0]
>>> export_to_video(video, "output.mp4", fps=24)

encode_prompt

< source >

( prompt: typing.Union[str, typing.List[str]] negative_prompt: typing.Union[str, typing.List[str], NoneType] = 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 = 128 device: typing.Optional[torch.device] = None dtype: typing.Optional[torch.dtype] = None )

参数

prompt (str 或 List[str], 可选) — 要编码的 prompt
negative_prompt (str 或 List[str], 可选) — 不用于引导图像生成的 prompt 或 prompts。如果未定义，则必须传递 negative_prompt_embeds。当不使用引导时忽略（即，如果 guidance_scale 小于 1 则忽略）。
do_classifier_free_guidance (bool, 可选, 默认为 True) — 是否使用无分类器引导。
num_videos_per_prompt (int, 可选, 默认为 1) — 每个 prompt 应生成的视频数量。用于放置结果嵌入的 torch 设备
prompt_embeds (torch.Tensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如 prompt 权重。如果未提供，将从 prompt 输入参数生成文本嵌入。
negative_prompt_embeds (torch.Tensor, 可选) — 预生成的负面文本嵌入。可用于轻松调整文本输入，例如 prompt 权重。如果未提供，将从 negative_prompt 输入参数生成 negative_prompt_embeds。
device — (torch.device, 可选): torch 设备
dtype — (torch.dtype, 可选): torch 数据类型

将 prompt 编码为文本编码器隐藏状态。

LTXImageToVideoPipeline

class diffusers.LTXImageToVideoPipeline

< source >

( scheduler: FlowMatchEulerDiscreteScheduler vae: AutoencoderKLLTXVideo text_encoder: T5EncoderModel tokenizer: T5TokenizerFast transformer: LTXVideoTransformer3DModel )

参数

transformer (LTXVideoTransformer3DModel) — 条件 Transformer 架构，用于对编码的视频潜在空间进行去噪。
scheduler (FlowMatchEulerDiscreteScheduler) — 调度器，与 transformer 结合使用，以对编码的图像潜在空间进行去噪。
vae (AutoencoderKLLTXVideo) — 变分自动编码器 (VAE) 模型，用于将图像编码和解码为潜在表示形式，以及从潜在表示形式解码为图像。
text_encoder (T5EncoderModel) — T5，特别是 google/t5-v1_1-xxl 变体。
tokenizer (CLIPTokenizer) — CLIPTokenizer 类的分词器。
tokenizer (T5TokenizerFast) — T5TokenizerFast 类的第二个分词器。

用于图像到视频生成的管道。

参考： https://github.com/Lightricks/LTX-Video

call

< source >

( image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, typing.List[PIL.Image.Image], typing.List[numpy.ndarray], typing.List[torch.Tensor]] = None prompt: typing.Union[str, typing.List[str]] = None negative_prompt: typing.Union[str, typing.List[str], NoneType] = None height: int = 512 width: int = 704 num_frames: int = 161 frame_rate: int = 25 num_inference_steps: int = 50 timesteps: typing.List[int] = None guidance_scale: float = 3 num_videos_per_prompt: typing.Optional[int] = 1 generator: typing.Union[torch._C.Generator, typing.List[torch._C.Generator], NoneType] = None 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: typing.Union[float, typing.List[float]] = 0.0 decode_noise_scale: typing.Union[float, typing.List[float], NoneType] = None output_type: typing.Optional[str] = 'pil' return_dict: bool = True attention_kwargs: typing.Optional[typing.Dict[str, typing.Any]] = None callback_on_step_end: typing.Optional[typing.Callable[[int, int, typing.Dict], NoneType]] = None callback_on_step_end_tensor_inputs: typing.List[str] = ['latents'] max_sequence_length: int = 128 ) → ~pipelines.ltx.LTXPipelineOutput 或 tuple

参数

image (PipelineImageInput) — 作为生成条件输入的图像。必须是图像、图像列表或 torch.Tensor。
prompt (str 或 List[str], 可选) — 用于引导图像生成的 prompt 或 prompts。如果未定义，则必须传递 prompt_embeds。
height (int, defaults to 512) — 生成图像的高度，单位为像素。默认设置为 480 以获得最佳效果。
width (int, defaults to 704) — 生成图像的宽度，单位为像素。默认设置为 848 以获得最佳效果。
num_frames (int, defaults to 161) — 要生成的视频帧数。
num_inference_steps (int, 可选，默认为 50) — 去噪步骤的数量。更多的去噪步骤通常会带来更高质量的图像，但会牺牲推理速度。
timesteps (List[int], 可选) — 用于去噪过程的自定义时间步长，适用于调度器，这些调度器在其 set_timesteps 方法中支持 timesteps 参数。如果未定义，则将使用传递 num_inference_steps 时的默认行为。必须按降序排列。
guidance_scale (float, defaults to 3 ) — Classifier-Free Diffusion Guidance 中定义的引导缩放。 guidance_scale 定义为 Imagen Paper 的公式 2 中的 w。通过设置 guidance_scale > 1 启用引导缩放。较高的引导缩放鼓励生成与文本 prompt 紧密相关的图像，但通常以降低图像质量为代价。
num_videos_per_prompt (int, 可选，默认为 1) — 每个提示要生成的视频数量。
generator (torch.Generator 或 List[torch.Generator], 可选) — 用于使生成具有确定性的一个或多个 torch 生成器。
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, defaults to 0.0) — 解码生成视频的时间步。
decode_noise_scale (float, defaults to None) — 解码时间步长时，随机噪声和去噪后的潜变量之间的插值因子。
output_type (str, 可选，默认为 "pil") — 生成图像的输出格式。在 PIL: PIL.Image.Image 或 np.array 之间选择。
return_dict (bool, 可选，默认为 True) — 是否返回 ~pipelines.ltx.LTXPipelineOutput 而不是普通元组。
attention_kwargs (dict, 可选) — 一个 kwargs 字典，如果指定，则会传递给 AttentionProcessor，如 diffusers.models.attention_processor 中的 self.processor 下定义。
callback_on_step_end (Callable, 可选) — 在推理期间的每个去噪步骤结束时调用的函数。该函数使用以下参数调用：callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)。 callback_kwargs 将包含由 callback_on_step_end_tensor_inputs 指定的所有张量列表。
callback_on_step_end_tensor_inputs (List, 可选) — callback_on_step_end 函数的张量输入列表。列表中指定的张量将作为 callback_kwargs 参数传递。您将只能包含管道类的 ._callback_tensor_inputs 属性中列出的变量。
max_sequence_length (int defaults to 128 ) — 与 prompt 一起使用的最大序列长度。

~pipelines.ltx.LTXPipelineOutput 或 tuple

如果 return_dict 为 True，则返回 ~pipelines.ltx.LTXPipelineOutput，否则返回 tuple，其中第一个元素是包含生成图像的列表。

调用管道进行生成时调用的函数。

示例

>>> import torch
>>> from diffusers import LTXImageToVideoPipeline
>>> from diffusers.utils import export_to_video, load_image

>>> pipe = LTXImageToVideoPipeline.from_pretrained("Lightricks/LTX-Video", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")

>>> 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. Flames engulf the structure, with smoke billowing into the air. Firefighters in protective gear rush to the scene, a fire truck labeled '38' visible behind them. The girl's neutral expression contrasts sharply with the chaos of the fire, creating a poignant and emotionally charged scene."
>>> negative_prompt = "worst quality, inconsistent motion, blurry, jittery, distorted"

>>> video = pipe(
...     image=image,
...     prompt=prompt,
...     negative_prompt=negative_prompt,
...     width=704,
...     height=480,
...     num_frames=161,
...     num_inference_steps=50,
... ).frames[0]
>>> export_to_video(video, "output.mp4", fps=24)

encode_prompt

< source >

参数

prompt (str 或 List[str], 可选) — 要编码的提示。
negative_prompt (str 或 List[str], 可选) — 不用于引导图像生成的提示或提示列表。如果未定义，则必须传递 negative_prompt_embeds。当不使用引导时将被忽略（即，如果 guidance_scale 小于 1 则忽略）。
do_classifier_free_guidance (bool, 可选，默认为 True) — 是否使用无分类器引导。
num_videos_per_prompt (int, 可选，默认为 1) — 每个提示应生成的视频数量。用于放置结果嵌入的 torch 设备。
prompt_embeds (torch.Tensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如提示权重。如果未提供，将从 prompt 输入参数生成文本嵌入。
negative_prompt_embeds (torch.Tensor, 可选) — 预生成的负面文本嵌入。可用于轻松调整文本输入，例如提示权重。如果未提供，将从 negative_prompt 输入参数生成 negative_prompt_embeds。
device — (torch.device, 可选): torch 设备
dtype — (torch.dtype, 可选): torch dtype

将 prompt 编码为文本编码器隐藏状态。

LTXPipelineOutput

class diffusers.pipelines.ltx.pipeline_output.LTXPipelineOutput

< source >

( frames: Tensor )

参数

frames (torch.Tensor, np.ndarray, 或 List[List[PIL.Image.Image]]) — 视频输出列表 - 它可以是长度为 batch_size 的嵌套列表，其中每个子列表包含长度为 num_frames 的去噪 PIL 图像序列。它也可以是形状为 (batch_size, num_frames, channels, height, width) 的 NumPy 数组或 Torch 张量。

LTX 管道的输出类。

< > 在 GitHub 上更新

←LEDITS++ Lumina-T2X→

Diffusers

LTX 视频

加载单个文件

LTXPipeline

class diffusers.LTXPipeline

__call__

encode_prompt

LTXImageToVideoPipeline

class diffusers.LTXImageToVideoPipeline

__call__

encode_prompt

LTXPipelineOutput

class diffusers.pipelines.ltx.pipeline_output.LTXPipelineOutput

call

call