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 は、テキストから動画へ、および画像から動画への生成のために設計された 2B パラメータの拡散トランスフォーマーです。12 のデュアルストリーム + 16 のシングルストリーム + 8 の DDT デコーダー層からなる 3 段階アーキテクチャ、長い動画シーケンス下での安定したテキストと動画の整合性を保つ 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)

メモリ効率の良い推論

VRAMが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 を継承しています。すべてのパイプラインに実装されている汎用的なメソッド（ダウンロード、保存、特定のデバイスでの実行など）については、スーパークラスのドキュメントを参照してください。

__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 を渡す必要があります。guidance を使用しない場合は無視されます。
  • height (int、デフォルト値は 736) — 生成される動画のピクセル単位の縦幅です。
  • width (int、デフォルト値は 1280) — 生成される動画の幅（ピクセル単位）。
  • num_frames (int、デフォルトは 121) — 生成する動画のフレーム数です。
  • num_inference_steps (int, 省略可、デフォルト値は 50) — デノイジングのステップ数です。デノイジングのステップ数を増やすと、推論速度が遅くなる代わりに、通常、より高品質な動画が生成されます。
  • timesteps (List[int], 任意) — ノイズ除去プロセスに使用するカスタムタイムステップ。
  • num_videos_per_prompt (int、任意、デフォルト値は 1) — 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、任意) — attentionプロセッサに渡される引数。
  • 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 が返されます。このとき、最初の要素は生成された動画フレームのリストです。

テキストから動画を生成するための pipeline の呼び出し関数です。

例:

>>> 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 入力引数から negative_prompt_embeds が生成されます。
  • 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: 負のプロンプトのテキスト埋め込み（ガイダンスを使用しない場合は None）
  • prompt_attention_mask: ポジティブプロンプト用のアテンションマスク
  • negative_prompt_attention_mask: 負のプロンプト用のアテンションマスク（ガイダンスを使用しない場合は None）

プロンプトをテキストエンコーダーの隠れ状態にエンコードします。

MotifVideoImage2VideoPipeline

クラス 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 を継承しています。すべてのパイプラインに実装されている汎用的なメソッド（ダウンロード、保存、特定のデバイスでの実行など）については、スーパークラスのドキュメントを参照してください。

__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) — 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、任意) — attentionプロセッサに渡される引数。
  • 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 入力引数から negative_prompt_embeds が生成されます。
  • 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: 負のプロンプトのテキスト埋め込み（ガイダンスを使用しない場合は None）
  • prompt_attention_mask: ポジティブプロンプト用のアテンションマスク
  • negative_prompt_attention_mask: 負のプロンプト用のアテンションマスク（ガイダンスを使用しない場合は 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→