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

Laporan Teknis

Motif-Video adalah diffusion transformer dengan 2B parameter yang dirancang untuk generasi text-to-video dan image-to-video. Model ini memiliki arsitektur tiga tahap dengan 12 lapisan dual-stream + 16 lapisan single-stream + 8 lapisan decoder DDT, Shared Cross-Attention untuk keselarasan teks-video yang stabil di bawah urutan video panjang, text encoder T5Gemma2, dan rectified flow matching untuk prediksi kecepatan.

Motif-Video architecture

Generasi Teks-ke-Video

Gunakan MotifVideoPipeline untuk pembuatan video dari teks:

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)

Generasi Gambar-ke-Video

Gunakan MotifVideoImage2VideoPipeline untuk pembuatan video dari gambar:

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)

Inferensi hemat memori

Untuk GPU dengan VRAM kurang dari 30GB (misalnya, RTX 4090), gunakan model CPU offloading:

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

kelas diffusers.MotifVideoPipeline

< >

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

Parameter

  • transformer (MotifVideoTransformer3DModel) — Arsitektur Transformer bersyarat untuk mendenoise latens video yang telah dikodekan.
  • scheduler (SchedulerMixin) — Scheduler yang digunakan bersama dengan transformer untuk mendenoise latens video yang telah dienkod. Harus berupa instans dari kelas yang mewarisi dari SchedulerMixin, seperti DPMSolverMultistepScheduler. Jika tidak disediakan, scheduler yang terlampir pada model pretrained akan digunakan.
  • vae (AutoencoderKLWan) — Model Variational Auto-Encoder (VAE) untuk mengodekan dan mendekodekan video ke dan dari representasi laten.
  • text_encoder (T5Gemma2Encoder) — Encoder teks utama untuk mengkodekan prompt teks menjadi embedding.
  • tokenizer (PreTrainedTokenizerBase) — Tokenizer yang sesuai dengan encoder teks utama.
  • guider (BaseGuidance) — Metode panduan yang akan digunakan. Harus berupa instance dari kelas yang mewarisi dari BaseGuidance, seperti ClassifierFreeGuidance, AdaptiveProjectedGuidance, atau SkipLayerGuidance. Jika tidak disediakan, default-nya adalah ClassifierFreeGuidance.

Pipeline untuk generasi teks-ke-video menggunakan Motif-Video.

Model ini mewarisi dari DiffusionPipeline. Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan untuk semua pipeline (mengunduh, menyimpan, menjalankan pada perangkat tertentu, dll.).

__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

Parameter

  • prompt (str atau List[str], opsional) — Prompt atau prompt-prompt untuk mengarahkan generasi video. Jika tidak didefinisikan, Anda harus meneruskan prompt_embeds.
  • negative_prompt (str atau List[str], opsional) — Prompt atau prompt-prompt yang tidak digunakan untuk mengarahkan generasi video. Jika tidak didefinisikan, Anda harus meneruskan negative_prompt_embeds sebagai gantinya. Diabaikan jika tidak menggunakan guidance.
  • height (int, defaultnya 736) — Tinggi video yang dihasilkan dalam piksel.
  • width (int, defaultnya 1280) — Lebar video yang dihasilkan dalam piksel.
  • num_frames (int, defaultnya 121) — Jumlah bingkai video yang akan dihasilkan.
  • num_inference_steps (int, opsional, default 50) — Jumlah langkah denoising. Semakin banyak langkah denoising, biasanya menghasilkan video dengan kualitas lebih tinggi, namun dengan biaya inferensi yang lebih lambat.
  • timesteps (List[int], opsional) — Timesteps kustom untuk digunakan dalam proses denoising.
  • num_videos_per_prompt (int, opsional, default 1) — Jumlah video yang akan dihasilkan per prompt.
  • generator (torch.Generator atau List[torch.Generator], opsional) — Objek Generator PyTorch untuk generasi deterministik.
  • latents (torch.Tensor, opsional) — Latents berisik yang telah dibuat sebelumnya.
  • prompt_embeds (torch.Tensor, opsional) — Embedding teks yang telah dibuat sebelumnya.
  • prompt_attention_mask (torch.Tensor, opsional) — Mask attention yang telah dibuat sebelumnya untuk embedding teks.
  • negative_prompt_embeds (torch.FloatTensor, opsional) — Embedding teks negatif yang telah dibuat sebelumnya.
  • negative_prompt_attention_mask (torch.FloatTensor, opsional) — Attention mask yang telah dibuat sebelumnya untuk embedding teks negatif.
  • output_type (str, opsional, default "pil") — Format output dari video yang dihasilkan. Pilih antara "pil", "np", atau "latent".
  • return_dict (bool, opsional, defaultnya True) — Apakah akan mengembalikan ~MotifVideoPipelineOutput alih-alih tuple biasa.
  • attention_kwargs (dict, opsional) — Argumen yang diteruskan ke pemroses perhatian.
  • callback_on_step_end (Callable, opsional) — Fungsi atau subkelas dari PipelineCallback atau MultiPipelineCallbacks yang dipanggil di akhir setiap langkah denoising.
  • callback_on_step_end_tensor_inputs (List, opsional) — Daftar input tensor untuk fungsi callback_on_step_end.
  • max_sequence_length (int, defaultnya 512) — Panjang maksimum urutan untuk tokenizer.
  • vae_batch_size (int, opsional) — Ukuran batch untuk decoding VAE. Jika diberikan dan ukuran batch latents lebih besar, decoding VAE akan dilakukan dalam chunk.

Mengembalikan

~MotifVideoPipelineOutput atau tuple

Jika return_dict adalah True, ~MotifVideoPipelineOutput dikembalikan, selain itu sebuah tuple dikembalikan di mana elemen pertama adalah daftar bingkai video yang dihasilkan.

Fungsi panggilan untuk pipeline pada generasi teks-ke-video.

Contoh:

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

Parameter

  • prompt (str atau List[str], opsional) — Prompt atau prompt-prompt yang akan dikodekan.
  • negative_prompt (str atau List[str], opsional) — Prompt atau prompt-prompt yang tidak digunakan untuk mengarahkan generasi gambar. Jika tidak didefinisikan, Anda harus meneruskan negative_prompt_embeds sebagai gantinya. Diabaikan saat tidak menggunakan guidance (yaitu, diabaikan jika guidance_scale kurang dari 1).
  • num_videos_per_prompt (int, opsional, default 1) — Jumlah video yang akan dihasilkan per prompt.
  • prompt_embeds (torch.Tensor, opsional) — Embedding teks yang telah dibuat sebelumnya.
  • negative_prompt_embeds (torch.Tensor, opsional) — Embedding teks negatif yang telah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya penimbangan prompt. Jika tidak disediakan, negative_prompt_embeds akan dibuat dari argumen input negative_prompt.
  • prompt_attention_mask (torch.Tensor, opsional) — Mask attention yang telah dibuat sebelumnya untuk embedding teks.
  • negative_prompt_attention_mask (torch.Tensor, opsional) — Attention mask yang telah dibuat sebelumnya untuk embedding teks negatif.
  • max_sequence_length (int, defaultnya 512) — Panjang maksimum urutan untuk tokenizer.
  • device (torch.device, opsional) — Perangkat untuk menempatkan tensor.
  • dtype (torch.dtype, opsional) — Tipe data untuk tensor.

Mengembalikan

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

Tuple yang berisi:

  • prompt_embeds: Embedding teks untuk prompt positif
  • negative_prompt_embeds: Embedding teks untuk prompt negatif (None jika tidak menggunakan guidance)
  • prompt_attention_mask: Mask perhatian untuk prompt positif
  • negative_prompt_attention_mask: Attention mask untuk prompt negatif (None jika tidak menggunakan guidance)

Mengkodekan prompt menjadi hidden states dari text encoder.

MotifVideoImage2VideoPipeline

kelas diffusers.MotifVideoImage2VideoPipeline

< >

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

Parameter

  • transformer (MotifVideoTransformer3DModel) — Arsitektur Transformer bersyarat untuk mendenoise latens video yang telah dikodekan.
  • scheduler (SchedulerMixin) — Scheduler yang digunakan bersama dengan transformer untuk mendenoise latens video yang telah dienkod. Harus berupa instans dari kelas yang mewarisi dari SchedulerMixin, seperti DPMSolverMultistepScheduler. Jika tidak disediakan, scheduler yang terlampir pada model pretrained akan digunakan.
  • vae (AutoencoderKLWan) — Model Variational Auto-Encoder (VAE) untuk mengodekan dan mendekodekan video ke dan dari representasi laten.
  • text_encoder (T5Gemma2Encoder) — Encoder teks utama untuk mengkodekan prompt teks menjadi embedding.
  • tokenizer (PreTrainedTokenizerBase) — Tokenizer yang sesuai dengan encoder teks utama.
  • feature_extractor (SiglipImageProcessor) — Pemroses gambar untuk encoder visual SigLIP.
  • guider (BaseGuidance) — Metode panduan yang akan digunakan. Harus berupa instance dari kelas yang mewarisi dari BaseGuidance, seperti ClassifierFreeGuidance, AdaptiveProjectedGuidance, atau SkipLayerGuidance. Jika tidak disediakan, default-nya adalah ClassifierFreeGuidance.

Pipeline untuk generasi gambar-ke-video menggunakan Motif-Video dengan kondisioning bingkai pertama.

Model ini mewarisi dari DiffusionPipeline. Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan untuk semua pipeline (mengunduh, menyimpan, menjalankan pada perangkat tertentu, dll.).

__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

Parameter

  • image (PipelineImageInput) — Gambar input yang digunakan sebagai bingkai pertama untuk pembuatan video.
  • prompt (str atau List[str]) — Prompt atau kumpulan prompt untuk mengarahkan generasi video.
  • negative_prompt (str atau List[str], opsional) — Prompt atau prompt-prompt yang tidak digunakan untuk mengarahkan generasi video.
  • height (int, defaultnya 736) — Tinggi video yang dihasilkan dalam piksel.
  • width (int, defaultnya 1280) — Lebar video yang dihasilkan dalam piksel.
  • num_frames (int, defaultnya 121) — Jumlah bingkai video yang akan dihasilkan.
  • num_inference_steps (int, opsional, default 50) — Jumlah langkah denoising.
  • timesteps (List[int], opsional) — Timesteps kustom untuk digunakan dalam proses denoising.
  • num_videos_per_prompt (int, opsional, default 1) — Jumlah video yang akan dihasilkan per prompt.
  • generator (torch.Generator atau List[torch.Generator], opsional) — Objek Generator PyTorch untuk generasi deterministik.
  • latents (torch.Tensor, opsional) — Latents berisik yang telah dibuat sebelumnya.
  • prompt_embeds (torch.Tensor, opsional) — Embedding teks yang telah dibuat sebelumnya.
  • prompt_attention_mask (torch.Tensor, opsional) — Mask attention yang telah dibuat sebelumnya untuk embedding teks.
  • negative_prompt_embeds (torch.FloatTensor, opsional) — Embedding teks negatif yang telah dibuat sebelumnya.
  • negative_prompt_attention_mask (torch.FloatTensor, opsional) — Attention mask yang telah dibuat sebelumnya untuk embedding teks negatif.
  • output_type (str, opsional, default "pil") — Format output dari video yang dihasilkan.
  • return_dict (bool, opsional, defaultnya True) — Apakah akan mengembalikan ~MotifVideoPipelineOutput alih-alih tuple biasa.
  • attention_kwargs (dict, opsional) — Argumen yang diteruskan ke pemroses perhatian.
  • callback_on_step_end (Callable, opsional) — Fungsi atau subkelas dari PipelineCallback yang dipanggil di akhir setiap langkah denoising.
  • callback_on_step_end_tensor_inputs (List, opsional) — Daftar input tensor untuk fungsi callback_on_step_end.
  • max_sequence_length (int, defaultnya 512) — Panjang maksimum urutan untuk tokenizer.

Mengembalikan

~MotifVideoPipelineOutput atau tuple

Jika return_dict adalah True, ~MotifVideoPipelineOutput dikembalikan, selain itu sebuah tuple dikembalikan di mana elemen pertama adalah daftar bingkai video yang dihasilkan.

Fungsi panggilan untuk pipeline pada generasi gambar-ke-video.

Contoh:

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

Parameter

  • prompt (str atau List[str], opsional) — Prompt atau prompt-prompt yang akan dikodekan.
  • negative_prompt (str atau List[str], opsional) — Prompt atau prompt-prompt yang tidak digunakan untuk mengarahkan generasi gambar. Jika tidak didefinisikan, Anda harus meneruskan negative_prompt_embeds sebagai gantinya. Diabaikan saat tidak menggunakan guidance (yaitu, diabaikan jika guidance_scale kurang dari 1).
  • num_videos_per_prompt (int, opsional, default 1) — Jumlah video yang akan dihasilkan per prompt.
  • prompt_embeds (torch.Tensor, opsional) — Embedding teks yang telah dibuat sebelumnya.
  • negative_prompt_embeds (torch.Tensor, opsional) — Embedding teks negatif yang telah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya penimbangan prompt. Jika tidak disediakan, negative_prompt_embeds akan dibuat dari argumen input negative_prompt.
  • prompt_attention_mask (torch.Tensor, opsional) — Mask attention yang telah dibuat sebelumnya untuk embedding teks.
  • negative_prompt_attention_mask (torch.Tensor, opsional) — Attention mask yang telah dibuat sebelumnya untuk embedding teks negatif.
  • max_sequence_length (int, defaultnya 512) — Panjang maksimum urutan untuk tokenizer.
  • device (torch.device, opsional) — Perangkat untuk menempatkan tensor.
  • dtype (torch.dtype, opsional) — Tipe data untuk tensor.

Mengembalikan

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

Tuple yang berisi:

  • prompt_embeds: Embedding teks untuk prompt positif
  • negative_prompt_embeds: Embedding teks untuk prompt negatif (None jika tidak menggunakan guidance)
  • prompt_attention_mask: Mask perhatian untuk prompt positif
  • negative_prompt_attention_mask: Attention mask untuk prompt negatif (None jika tidak menggunakan guidance)

Mengkodekan prompt menjadi hidden states dari text encoder.

MotifVideoPipelineOutput

kelas diffusers.MotifVideoPipelineOutput

< >

( frames: Tensor )

Parameter

  • frames (torch.Tensor, np.ndarray, atau List[List[PIL.Image.Image]]) — Daftar output video - Dapat berupa daftar bersarang dengan panjang batch_size, di mana setiap sub-daftar berisi urutan gambar PIL yang telah didenois dengan panjang num_frames. Dapat juga berupa array NumPy atau tensor Torch dengan bentuk (batch_size, num_frames, channels, height, width).

Kelas output untuk pipeline Motif-Video.

Update on GitHub

←Mochi PAN 2→