Motif-Video

Relatório Técnico

Motif-Video é um difusão transformer de 2B parâmetros projetado para geração de texto-para-vídeo e imagem-para-vídeo. Ele apresenta uma arquitetura de três estágios com 12 camadas de decodificador dual-stream + 16 single-stream + 8 DDT, Shared Cross-Attention para alinhamento estável de texto-vídeo sob sequências longas de vídeo, codificador de texto T5Gemma2 e rectified flow matching para previsão de velocidade.

Motif-Video architecture

Geração de Texto para Vídeo

Use MotifVideoPipeline para geração de vídeo a partir de texto:

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)

Geração de Vídeo a Partir de Imagem

Use MotifVideoImage2VideoPipeline para geração de vídeo a partir de imagem:

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)

Inferência eficiente em memória

Para GPUs com menos de 30GB de VRAM (por exemplo, RTX 4090), use o offloading de modelo para 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

classe diffusers.MotifVideoPipeline

< source >

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

Parâmetros

transformer (MotifVideoTransformer3DModel) — Arquitetura de Transformer condicional para desruidar os latentes de vídeo codificados.
scheduler (SchedulerMixin) — Um scheduler a ser usado em combinação com transformer para desruidar os latentes de vídeo codificados. Deve ser uma instância de uma classe que herda de SchedulerMixin, como DPMSolverMultistepScheduler. Se não for fornecido, usa o scheduler anexado ao modelo pré-treinado.
vae (AutoencoderKLWan) — Modelo de Autoencoder Variacional (VAE) para codificar e decodificar vídeos para e a partir de representações latentes.
text_encoder (T5Gemma2Encoder) — Codificador de texto principal para codificar prompts de texto em embeddings.
tokenizer (PreTrainedTokenizerBase) — Tokenizer correspondente ao codificador de texto principal.
guider (BaseGuidance) — O método de orientação a ser usado. Deve ser uma instância de uma classe que herda de BaseGuidance, como ClassifierFreeGuidance, AdaptiveProjectedGuidance ou SkipLayerGuidance. Se não for fornecido, o padrão é ClassifierFreeGuidance.

Pipeline para geração de texto para vídeo usando Motif-Video.

Este modelo herda de DiffusionPipeline. Consulte a documentação da superclasse para os métodos genéricos implementados para todos os pipelines (download, salvamento, execução em um dispositivo específico, etc.).

call

< source >

( 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

Parâmetros

prompt (str ou List[str], opcional) — O prompt ou prompts para orientar a geração do vídeo. Se não definido, é necessário passar prompt_embeds.
negative_prompt (str ou List[str], opcional) — O prompt ou os prompts que não devem orientar a geração do vídeo. Se não for definido, é necessário passar negative_prompt_embeds em vez disso. Ignorado quando não se usa orientação.
height (int, padrão 736) — A altura, em pixels, do vídeo gerado.
width (int, padrão 1280) — A largura em pixels do vídeo gerado.
num_frames (int, padrão 121) — O número de quadros de vídeo a serem gerados.
num_inference_steps (int, opcional, padrão 50) — O número de etapas de remoção de ruído. Mais etapas de remoção de ruído geralmente resultam em um vídeo de maior qualidade, à custa de uma inferência mais lenta.
timesteps (List[int], opcional) — Timesteps personalizados para usar no processo de remoção de ruído.
num_videos_per_prompt (int, opcional, padrão 1) — O número de vídeos a serem gerados por prompt.
generator (torch.Generator ou List[torch.Generator], opcional) — Objeto(s) de Generator do PyTorch para geração determinística.
latents (torch.Tensor, opcional) — Latentes ruidosos pré-gerados.
prompt_embeds (torch.Tensor, opcional) — Incorporações de texto pré-geradas.
prompt_attention_mask (torch.Tensor, opcional) — Máscara de atenção pré-gerada para embeddings de texto.
negative_prompt_embeds (torch.FloatTensor, opcional) — Incorporações de texto negativo pré-geradas.
negative_prompt_attention_mask (torch.FloatTensor, opcional) — Máscara de atenção pré-gerada para embeddings de texto negativos.
output_type (str, opcional, padrão "pil") — O formato de saída do vídeo gerado. Escolha entre "pil", "np" ou "latent".
return_dict (bool, opcional, padrão True) — Se deve ou não retornar um ~MotifVideoPipelineOutput em vez de uma tupla simples.
attention_kwargs (dict, opcional) — Argumentos passados ao processador de atenção.
callback_on_step_end (Callable, opcional) — Uma função ou subclasse de PipelineCallback ou MultiPipelineCallbacks chamada no final de cada etapa de desruidamento.
callback_on_step_end_tensor_inputs (List, opcional) — A lista de entradas de tensor para a função callback_on_step_end.
max_sequence_length (int, padrão 512) — Comprimento máximo da sequência para o tokenizer.
vae_batch_size (int, opcional) — Tamanho do lote para a decodificação do VAE. Se fornecido e o tamanho do lote dos latentes for maior, a decodificação do VAE será feita em blocos.

Retorna

~MotifVideoPipelineOutput ou tuple

Se return_dict for True, ~MotifVideoPipelineOutput é retornado; caso contrário, uma tuple é retornada, em que o primeiro elemento é uma lista de quadros de vídeo gerados.

A função de chamada do pipeline para geração de texto para vídeo.

Exemplos:

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

< source >

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

Parâmetros

prompt (str ou List[str], opcional) — O prompt ou os prompts a serem codificados.
negative_prompt (str ou List[str], opcional) — O prompt ou os prompts que não devem orientar a geração da imagem. Se não for definido, é necessário passar negative_prompt_embeds em vez disso. Ignorado quando não se usa orientação (ou seja, ignorado se guidance_scale for menor que 1).
num_videos_per_prompt (int, opcional, padrão 1) — Número de vídeos a serem gerados por prompt.
prompt_embeds (torch.Tensor, opcional) — Incorporações de texto pré-geradas.
negative_prompt_embeds (torch.Tensor, opcional) — Incorporações de texto negativas pré-geradas. Pode ser usado para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompts. Se não for fornecido, negative_prompt_embeds será gerado a partir do argumento de entrada negative_prompt.
prompt_attention_mask (torch.Tensor, opcional) — Máscara de atenção pré-gerada para embeddings de texto.
negative_prompt_attention_mask (torch.Tensor, opcional) — Máscara de atenção pré-gerada para embeddings de texto negativos.
max_sequence_length (int, padrão 512) — Comprimento máximo da sequência para o tokenizer.
device (torch.device, opcional) — Dispositivo em que os tensores serão colocados.
dtype (torch.dtype, opcional) — Tipo de dados para tensores.

Retorna

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

Uma tupla contendo:

prompt_embeds: As incorporações de texto para o prompt positivo
negative_prompt_embeds: Os embeddings de texto para o prompt negativo (None se não estiver usando guidance)
prompt_attention_mask: A máscara de atenção para o prompt positivo
negative_prompt_attention_mask: A máscara de atenção para o prompt negativo (None se não estiver usando guidance)

Codifica o prompt em estados ocultos do codificador de texto.

MotifVideoImage2VideoPipeline

classe diffusers.MotifVideoImage2VideoPipeline

< source >

Parâmetros

transformer (MotifVideoTransformer3DModel) — Arquitetura de Transformer condicional para desruidar os latentes de vídeo codificados.
scheduler (SchedulerMixin) — Um scheduler a ser usado em combinação com transformer para desruidar os latentes de vídeo codificados. Deve ser uma instância de uma classe que herda de SchedulerMixin, como DPMSolverMultistepScheduler. Se não for fornecido, usa o scheduler anexado ao modelo pré-treinado.
vae (AutoencoderKLWan) — Modelo de Autoencoder Variacional (VAE) para codificar e decodificar vídeos para e a partir de representações latentes.
text_encoder (T5Gemma2Encoder) — Codificador de texto principal para codificar prompts de texto em embeddings.
tokenizer (PreTrainedTokenizerBase) — Tokenizer correspondente ao codificador de texto principal.
feature_extractor (SiglipImageProcessor) — Processador de imagem para o codificador de visão do SigLIP.
guider (BaseGuidance) — O método de orientação a ser usado. Deve ser uma instância de uma classe que herda de BaseGuidance, como ClassifierFreeGuidance, AdaptiveProjectedGuidance ou SkipLayerGuidance. Se não for fornecido, o padrão é ClassifierFreeGuidance.

Pipeline para geração de vídeo a partir de imagem usando Motif-Video com condicionamento do primeiro quadro.

call

< source >

( 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

Parâmetros

image (PipelineImageInput) — A imagem de entrada a ser usada como o primeiro quadro para a geração de vídeo.
prompt (str ou List[str]) — O prompt ou os prompts para orientar a geração do vídeo.
negative_prompt (str ou List[str], opcional) — O prompt ou os prompts que não devem orientar a geração do vídeo.
height (int, padrão 736) — A altura, em pixels, do vídeo gerado.
width (int, padrão 1280) — A largura em pixels do vídeo gerado.
num_frames (int, padrão 121) — O número de quadros de vídeo a serem gerados.
num_inference_steps (int, opcional, padrão 50) — O número de etapas de remoção de ruído.
timesteps (List[int], opcional) — Timesteps personalizados para usar no processo de remoção de ruído.
num_videos_per_prompt (int, opcional, padrão 1) — O número de vídeos a serem gerados por prompt.
generator (torch.Generator ou List[torch.Generator], opcional) — Objeto(s) de Generator do PyTorch para geração determinística.
latents (torch.Tensor, opcional) — Latentes ruidosos pré-gerados.
prompt_embeds (torch.Tensor, opcional) — Incorporações de texto pré-geradas.
prompt_attention_mask (torch.Tensor, opcional) — Máscara de atenção pré-gerada para embeddings de texto.
negative_prompt_embeds (torch.FloatTensor, opcional) — Incorporações de texto negativo pré-geradas.
negative_prompt_attention_mask (torch.FloatTensor, opcional) — Máscara de atenção pré-gerada para embeddings de texto negativos.
output_type (str, opcional, padrão "pil") — O formato de saída do vídeo gerado.
return_dict (bool, opcional, padrão True) — Se deve ou não retornar um ~MotifVideoPipelineOutput em vez de uma tupla simples.
attention_kwargs (dict, opcional) — Argumentos passados ao processador de atenção.
callback_on_step_end (Callable, opcional) — Uma função ou subclasse de PipelineCallback chamada no final de cada etapa de desruidamento.
callback_on_step_end_tensor_inputs (List, opcional) — A lista de entradas de tensor para a função callback_on_step_end.
max_sequence_length (int, padrão 512) — Comprimento máximo da sequência para o tokenizer.

Retorna

~MotifVideoPipelineOutput ou tuple

Se return_dict for True, ~MotifVideoPipelineOutput é retornado; caso contrário, uma tuple é retornada, em que o primeiro elemento é uma lista de quadros de vídeo gerados.

A função de chamada do pipeline para geração de vídeo a partir de imagem.

Exemplos:

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

< source >

Parâmetros

prompt (str ou List[str], opcional) — O prompt ou os prompts a serem codificados.
negative_prompt (str ou List[str], opcional) — O prompt ou os prompts que não devem orientar a geração da imagem. Se não for definido, é necessário passar negative_prompt_embeds em vez disso. Ignorado quando não se usa orientação (ou seja, ignorado se guidance_scale for menor que 1).
num_videos_per_prompt (int, opcional, padrão 1) — Número de vídeos a serem gerados por prompt.
prompt_embeds (torch.Tensor, opcional) — Incorporações de texto pré-geradas.
negative_prompt_embeds (torch.Tensor, opcional) — Incorporações de texto negativas pré-geradas. Pode ser usado para ajustar facilmente as entradas de texto, por exemplo, ponderação de prompts. Se não for fornecido, negative_prompt_embeds será gerado a partir do argumento de entrada negative_prompt.
prompt_attention_mask (torch.Tensor, opcional) — Máscara de atenção pré-gerada para embeddings de texto.
negative_prompt_attention_mask (torch.Tensor, opcional) — Máscara de atenção pré-gerada para embeddings de texto negativos.
max_sequence_length (int, padrão 512) — Comprimento máximo da sequência para o tokenizer.
device (torch.device, opcional) — Dispositivo em que os tensores serão colocados.
dtype (torch.dtype, opcional) — Tipo de dados para tensores.

Retorna

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

Uma tupla contendo:

prompt_embeds: As incorporações de texto para o prompt positivo
negative_prompt_embeds: Os embeddings de texto para o prompt negativo (None se não estiver usando guidance)
prompt_attention_mask: A máscara de atenção para o prompt positivo
negative_prompt_attention_mask: A máscara de atenção para o prompt negativo (None se não estiver usando guidance)

Codifica o prompt em estados ocultos do codificador de texto.

MotifVideoPipelineOutput

classe diffusers.MotifVideoPipelineOutput

< source >

( frames: Tensor )

Parâmetros

frames (torch.Tensor, np.ndarray ou List[List[PIL.Image.Image]]) — Lista de saídas de vídeo - Pode ser uma lista aninhada de comprimento batch_size, com cada sublista contendo sequências de imagens PIL desruidas de comprimento num_frames. Também pode ser um array NumPy ou tensor Torch de forma (batch_size, num_frames, channels, height, width).

Classe de saída para pipelines do Motif-Video.

Update on GitHub

Diffusers

Motif-Video

Geração de Texto para Vídeo

Geração de Vídeo a Partir de Imagem

Inferência eficiente em memória

MotifVideoPipeline

classe diffusers.MotifVideoPipeline

__call__

encode_prompt

MotifVideoImage2VideoPipeline

classe diffusers.MotifVideoImage2VideoPipeline

__call__

encode_prompt

MotifVideoPipelineOutput

classe diffusers.MotifVideoPipelineOutput

call

call