Hugging Face's logo

Diffusers documentation

Motif-Video

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Motif-Video

技术报告

Motif-Video 是一个拥有 20 亿参数的扩散 Transformer，专为文本生成视频和图像生成视频而设计。它采用三阶段架构，包含 12 层双流 + 16 层单流 + 8 层 DDT 解码器层，具备用于在长视频序列下实现稳定文本-视频对齐的 Shared Cross-Attention，使用 T5Gemma2 文本编码器，并采用 rectified flow matching 进行速度预测。

Motif-Video architecture

文本到视频生成

使用 MotifVideoPipeline 进行文本到视频生成：

import torch
from diffusers import MotifVideoPipeline
from diffusers.utils import export_to_video


pipe = MotifVideoPipeline.from_pretrained(
    "Motif-Technologies/Motif-Video-2B",
    dtype=torch.bfloat16,
)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

prompt = "A woman with long brown hair and light skin smiles at another woman with long blonde hair."
negative_prompt = "worst quality, inconsistent motion, blurry, jittery, distorted"

video = pipe(
    prompt=prompt,
    negative_prompt=negative_prompt,
    width=1280,
    height=736,
    num_frames=121,
    num_inference_steps=50,
).frames[0]
export_to_video(video, "output.mp4", fps=24)

图像到视频生成

使用 MotifVideoImage2VideoPipeline 进行图像到视频的生成：

import torch
from diffusers import MotifVideoImage2VideoPipeline
from diffusers.utils import export_to_video, load_image


pipe = MotifVideoImage2VideoPipeline.from_pretrained(
    "Motif-Technologies/Motif-Video-2B",
    dtype=torch.bfloat16,
)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

image = load_image("input_image.png")
prompt = "A cinematic scene with vivid colors."
negative_prompt = "worst quality, blurry, jittery, distorted"

video = pipe(
    image=image,
    prompt=prompt,
    negative_prompt=negative_prompt,
    width=1280,
    height=736,
    num_frames=121,
    num_inference_steps=50,
).frames[0]
export_to_video(video, "i2v_output.mp4", fps=24)

内存高效推理

对于显存小于 30GB 的 GPU（例如 RTX 4090），请使用模型 CPU 卸载：

export PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True
import torch
from diffusers import MotifVideoPipeline
from diffusers.utils import export_to_video


pipe = MotifVideoPipeline.from_pretrained(
    "Motif-Technologies/Motif-Video-2B",
    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."
negative_prompt = "worst quality, inconsistent motion, blurry, jittery, distorted"

video = pipe(
    prompt=prompt,
    negative_prompt=negative_prompt,
    width=1280,
    height=736,
    num_frames=121,
    num_inference_steps=50,
).frames[0]
export_to_video(video, "output.mp4", fps=24)

MotifVideoPipeline

class diffusers.MotifVideoPipeline

< >

( scheduler: SchedulerMixinvae: AutoencoderKLWantext_encoder: T5Gemma2Encodertokenizer: PreTrainedTokenizerBasetransformer: MotifVideoTransformer3DModelguider: BaseGuidancefeature_extractor: typing.Optional[transformers.models.siglip.image_processing_pil_siglip.SiglipImageProcessorPil] = None )

参数

  • transformer (MotifVideoTransformer3DModel) — 用于对编码后的视频潜在变量进行去噪的条件 Transformer 架构。
  • scheduler (SchedulerMixin) — 用于与 transformer 配合，对编码后的视频潜变量进行去噪的调度器。应为继承自 SchedulerMixin 的类的实例，例如 DPMSolverMultistepScheduler。如果未提供，则使用预训练模型附带的调度器。
  • vae (AutoencoderKLWan) — 变分自编码器（VAE）模型，用于将视频编码为潜在表示，以及从潜在表示解码为视频。
  • text_encoder (T5Gemma2Encoder) — 用于将文本提示编码为嵌入的主要文本编码器。
  • tokenizer (PreTrainedTokenizerBase) — 与主文本编码器对应的分词器。
  • guider (BaseGuidance) — 要使用的引导方法。应为继承自 BaseGuidance 的类的实例，例如 ClassifierFreeGuidance、AdaptiveProjectedGuidance 或 SkipLayerGuidance。如果未提供， 则默认为 ClassifierFreeGuidance。

使用 Motif-Video 进行文本到视频生成的 Pipeline。

该模型继承自 DiffusionPipeline。有关为所有 pipeline 实现的通用方法（下载、保存、在特定设备上运行等），请参阅父类文档。

__call__

< >

( prompt: typing.Union[str, typing.List[str], NoneType] = Nonenegative_prompt: typing.Union[str, typing.List[str], NoneType] = Noneheight: int = 736width: int = 1280num_frames: int = 121num_inference_steps: int = 50timesteps: typing.Optional[typing.List[int]] = Nonenum_videos_per_prompt: typing.Optional[int] = 1generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Noneoutput_type: typing.Optional[str] = 'pil'return_dict: bool = Trueattention_kwargs: typing.Optional[typing.Dict[str, typing.Any]] = Nonecallback_on_step_end: typing.Union[typing.Callable[[int, int, typing.Dict], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = Nonecallback_on_step_end_tensor_inputs: typing.List[str] = ['latents']max_sequence_length: int = 512vae_batch_size: int | None = None ) → ~MotifVideoPipelineOutput or tuple

参数

  • prompt (str 或 List[str]，可选) — 用于引导视频生成的提示词或提示词列表。如果未定义，则必须传入 prompt_embeds。
  • negative_prompt (str 或 List[str]，可选) — 用于不引导视频生成的提示词。如果未定义，则必须传入 negative_prompt_embeds。在未使用引导时将被忽略。
  • height (int，默认为 736) — 生成视频的高度（以像素为单位）。
  • width (int，默认为 1280) — 生成视频的宽度（以像素为单位）。
  • num_frames (int，默认为 121) — 要生成的视频帧数。
  • num_inference_steps (int，可选，默认值为 50) — 去噪步数。更多的去噪步数通常能生成更高质量的视频，但推理速度会变慢。
  • timesteps (List[int]，可选) — 用于去噪过程的自定义时间步。
  • num_videos_per_prompt (int，可选，默认为 1) — 每个提示词生成的视频数量。
  • generator (torch.Generator 或 List[torch.Generator]，可选) — 用于确定性生成的 PyTorch Generator 对象。
  • latents (torch.Tensor, 可选) — 预生成的含噪潜变量。
  • prompt_embeds (torch.Tensor, 可选) — 预生成的文本嵌入。
  • prompt_attention_mask (torch.Tensor，可选) — 为文本嵌入预生成的注意力掩码。
  • negative_prompt_embeds (torch.FloatTensor，可选) — 预生成的负向文本嵌入。
  • negative_prompt_attention_mask (torch.FloatTensor, 可选) — 为负向文本嵌入预生成的注意力掩码。
  • output_type (str，可选，默认为 "pil") — 生成视频的输出格式。可选 "pil"、"np" 或 "latent"。
  • return_dict (bool，可选，默认为 True) — 是否返回 ~MotifVideoPipelineOutput 而不是普通元组。
  • attention_kwargs (dict，可选) — 传递给注意力处理器的参数。
  • callback_on_step_end (Callable，可选) — 在每个去噪步骤结束时调用的函数，或 PipelineCallback 或 MultiPipelineCallbacks 的子类。
  • callback_on_step_end_tensor_inputs (List, 可选) — callback_on_step_end 函数的张量输入列表。
  • max_sequence_length (int，默认为 512) — 分词器的最大序列长度。
  • vae_batch_size (int, 可选) — VAE 解码的批大小。如果提供了该值且 latents 的批大小更大，则 VAE 解码将分块进行。

返回值

~MotifVideoPipelineOutput 或 tuple

如果 return_dict 为 True，则返回 ~MotifVideoPipelineOutput，否则返回一个 tuple，其中第一个元素是生成的视频帧列表。

用于文本生成视频流水线的调用函数。

示例：

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

>>> # Load the Motif-Video pipeline
>>> motif_video_model_id = "Motif-Technologies/Motif-Video-2B"
>>> pipe = MotifVideoPipeline.from_pretrained(motif_video_model_id, 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=1280,
...     height=736,
...     num_frames=121,
...     num_inference_steps=50,
... ).frames[0]
>>> export_to_video(video, "output.mp4", fps=24)

encode_prompt

< >

( prompt: typing.Union[str, typing.List[str]]negative_prompt: typing.Union[str, typing.List[str], NoneType] = Nonenum_videos_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Nonemax_sequence_length: int = 512device: typing.Optional[torch.device] = Nonedtype: typing.Optional[torch.dtype] = None ) → tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]

参数

  • prompt (str 或 List[str]，可选) — 要编码的提示词或提示词列表。
  • negative_prompt (str 或 List[str]，可选) — 用于引导图像生成的负面提示词。如果未定义，则必须传入 negative_prompt_embeds。当不使用引导时（即 guidance_scale 小于 1 时）将被忽略。
  • num_videos_per_prompt (int，可选，默认为 1) — 每个提示词生成的视频数量。
  • prompt_embeds (torch.Tensor, 可选) — 预生成的文本嵌入。
  • negative_prompt_embeds (torch.Tensor, 可选) — 预生成的负向文本嵌入。可用于轻松调整文本输入，例如提示词加权。如果未提供，negative_prompt_embeds 将从 negative_prompt 输入参数生成。
  • prompt_attention_mask (torch.Tensor，可选) — 为文本嵌入预生成的注意力掩码。
  • negative_prompt_attention_mask (torch.Tensor, 可选) — 为负向文本嵌入预生成的注意力掩码。
  • max_sequence_length (int，默认为 512) — 分词器的最大序列长度。
  • device (torch.device，可选) — 用于放置张量的设备。
  • dtype (torch.dtype，可选) — 张量的数据类型。

返回值

tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]

包含以下内容的元组：

  • prompt_embeds：正向提示词的文本嵌入
  • negative_prompt_embeds：负面提示词（negative prompt）的文本嵌入（如果未使用 guidance，则为 None）
  • prompt_attention_mask：正向提示词的注意力掩码
  • negative_prompt_attention_mask：负面提示词的注意力掩码（如果未使用 guidance，则为 None）

将提示词编码为文本编码器的隐藏状态。

MotifVideoImage2VideoPipeline

class diffusers.MotifVideoImage2VideoPipeline

< >

( scheduler: SchedulerMixinvae: AutoencoderKLWantext_encoder: T5Gemma2Encodertokenizer: PreTrainedTokenizerBasetransformer: MotifVideoTransformer3DModelguider: BaseGuidancefeature_extractor: SiglipImageProcessorPil )

参数

  • transformer (MotifVideoTransformer3DModel) — 用于对编码后的视频潜在变量进行去噪的条件 Transformer 架构。
  • scheduler (SchedulerMixin) — 用于与 transformer 配合，对编码后的视频潜变量进行去噪的调度器。应为继承自 SchedulerMixin 的类的实例，例如 DPMSolverMultistepScheduler。如果未提供，则使用预训练模型附带的调度器。
  • vae (AutoencoderKLWan) — 变分自编码器（VAE）模型，用于将视频编码为潜在表示，以及从潜在表示解码为视频。
  • text_encoder (T5Gemma2Encoder) — 用于将文本提示编码为嵌入的主要文本编码器。
  • tokenizer (PreTrainedTokenizerBase) — 与主文本编码器对应的分词器。
  • feature_extractor (SiglipImageProcessor) — SigLIP 视觉编码器的图像处理器。
  • guider (BaseGuidance) — 要使用的引导方法。应为继承自 BaseGuidance 的类的实例，例如 ClassifierFreeGuidance、AdaptiveProjectedGuidance 或 SkipLayerGuidance。如果未提供， 则默认为 ClassifierFreeGuidance。

使用 Motif-Video 进行首帧条件控制，实现图像到视频生成的 Pipeline。

该模型继承自 DiffusionPipeline。有关为所有 pipeline 实现的通用方法（下载、保存、在特定设备上运行等），请参阅父类文档。

__call__

< >

( image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]prompt: typing.Union[str, typing.List[str]]negative_prompt: typing.Union[str, typing.List[str], NoneType] = Noneheight: int = 736width: int = 1280num_frames: int = 121num_inference_steps: int = 50timesteps: typing.Optional[typing.List[int]] = Nonenum_videos_per_prompt: typing.Optional[int] = 1generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Noneoutput_type: typing.Optional[str] = 'pil'return_dict: bool = Trueattention_kwargs: typing.Optional[typing.Dict[str, typing.Any]] = Nonecallback_on_step_end: typing.Union[typing.Callable[[int, int, typing.Dict], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = Nonecallback_on_step_end_tensor_inputs: typing.List[str] = ['latents']max_sequence_length: int = 512 ) → ~MotifVideoPipelineOutput or tuple

参数

  • image (PipelineImageInput) — 用于视频生成的首帧输入图像。
  • prompt (str 或 List[str]) — 用于引导视频生成的提示词或提示词列表。
  • negative_prompt (str 或 List[str]，可选) — 用于引导视频生成的负面提示词。
  • height (int，默认为 736) — 生成视频的高度（以像素为单位）。
  • width (int，默认为 1280) — 生成视频的宽度（以像素为单位）。
  • num_frames (int，默认为 121) — 要生成的视频帧数。
  • num_inference_steps (int，可选，默认值为 50) — 去噪步数。
  • timesteps (List[int]，可选) — 用于去噪过程的自定义时间步。
  • num_videos_per_prompt (int，可选，默认为 1) — 每个提示词生成的视频数量。
  • generator (torch.Generator 或 List[torch.Generator]，可选) — 用于确定性生成的 PyTorch Generator 对象。
  • latents (torch.Tensor, 可选) — 预生成的含噪潜变量。
  • prompt_embeds (torch.Tensor, 可选) — 预生成的文本嵌入。
  • prompt_attention_mask (torch.Tensor，可选) — 为文本嵌入预生成的注意力掩码。
  • negative_prompt_embeds (torch.FloatTensor，可选) — 预生成的负向文本嵌入。
  • negative_prompt_attention_mask (torch.FloatTensor, 可选) — 为负向文本嵌入预生成的注意力掩码。
  • output_type (str，可选，默认为 "pil") — 生成视频的输出格式。
  • return_dict (bool，可选，默认为 True) — 是否返回 ~MotifVideoPipelineOutput 而不是普通元组。
  • attention_kwargs (dict，可选) — 传递给注意力处理器的参数。
  • callback_on_step_end (Callable, 可选) — 在每个去噪步骤结束时调用的函数或 PipelineCallback 的子类。
  • callback_on_step_end_tensor_inputs (List, 可选) — callback_on_step_end 函数的张量输入列表。
  • max_sequence_length (int，默认为 512) — 分词器的最大序列长度。

返回值

~MotifVideoPipelineOutput 或 tuple

如果 return_dict 为 True，则返回 ~MotifVideoPipelineOutput，否则返回一个 tuple，其中第一个元素是生成的视频帧列表。

用于图像到视频生成的 pipeline 的调用函数。

示例：

>>> import torch
>>> from PIL import Image
>>> from diffusers import MotifVideoImage2VideoPipeline
>>> from diffusers.utils import export_to_video, load_image

>>> # Load the Motif-Video image-to-video pipeline
>>> motif_video_model_id = "Motif-Technologies/Motif-Video-2B"
>>> pipe = MotifVideoImage2VideoPipeline.from_pretrained(motif_video_model_id, torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")

>>> # Load an image
>>> image = load_image(
...     "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.png"
... )

>>> prompt = "An astronaut is walking on the moon surface, kicking up dust with each step"
>>> negative_prompt = "worst quality, inconsistent motion, blurry, jittery, distorted"

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

encode_prompt

< >

( prompt: typing.Union[str, typing.List[str]]negative_prompt: typing.Union[str, typing.List[str], NoneType] = Nonenum_videos_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_attention_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_attention_mask: typing.Optional[torch.Tensor] = Nonemax_sequence_length: int = 512device: typing.Optional[torch.device] = Nonedtype: typing.Optional[torch.dtype] = None ) → tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]

参数

  • prompt (str 或 List[str]，可选) — 要编码的提示词或提示词列表。
  • negative_prompt (str 或 List[str]，可选) — 用于引导图像生成的负面提示词。如果未定义，则必须传入 negative_prompt_embeds。当不使用引导时（即 guidance_scale 小于 1 时）将被忽略。
  • num_videos_per_prompt (int，可选，默认为 1) — 每个提示词生成的视频数量。
  • prompt_embeds (torch.Tensor, 可选) — 预生成的文本嵌入。
  • negative_prompt_embeds (torch.Tensor, 可选) — 预生成的负向文本嵌入。可用于轻松调整文本输入，例如提示词加权。如果未提供，negative_prompt_embeds 将从 negative_prompt 输入参数生成。
  • prompt_attention_mask (torch.Tensor，可选) — 为文本嵌入预生成的注意力掩码。
  • negative_prompt_attention_mask (torch.Tensor, 可选) — 为负向文本嵌入预生成的注意力掩码。
  • max_sequence_length (int，默认为 512) — 分词器的最大序列长度。
  • device (torch.device，可选) — 用于放置张量的设备。
  • dtype (torch.dtype，可选) — 张量的数据类型。

返回值

tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]

包含以下内容的元组：

  • prompt_embeds：正向提示词的文本嵌入
  • negative_prompt_embeds：负面提示词（negative prompt）的文本嵌入（如果未使用 guidance，则为 None）
  • prompt_attention_mask：正向提示词的注意力掩码
  • negative_prompt_attention_mask：负面提示词的注意力掩码（如果未使用 guidance，则为 None）

将提示词编码为文本编码器的隐藏状态。

MotifVideoPipelineOutput

class diffusers.MotifVideoPipelineOutput

< >

( frames: Tensor )

参数

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

Motif-Video 流水线的输出类。

Update on GitHub

←Mochi PAN 2→