MiniMax-H3

MiniMax-H3 gera o vídeo e sua trilha sonora juntos. Um único transformer remove o ruído de uma sequência empacotada que contém a condição de texto, a mídia de condicionamento e os latentes de vídeo e áudio de destino. Não há um vocoder separado nem uma etapa posterior de áudio: o vídeo e o áudio saem do mesmo loop de remoção de ruído.

Você pode encontrar os checkpoints originais do MiniMax-H3 na organização MiniMaxAI.

MiniMax-H3 é integrado apenas como blocos de Modular Diffusers, da mesma forma que o Anima: os blocos e seu MiniMaxH3ModularPipeline constituem toda a integração, e não há uma metade DiffusionPipeline.

Layout do checkpoint

O MiniMax-H3 foi lançado como duas partições de checkpoint que compartilham todos os componentes, exceto o transformer, portanto, a conversão do diffusers coloca ambos em um único repositório:

Tudo, exceto o transformer, ou seja, o VAE de vídeo, o VAE de áudio, o condicionador Qwen3-VL, seu tokenizer e processor, e os dois schedulers, é compartilhado e armazenado uma única vez.

O condicionador é um Qwen3VLForConditionalGeneration, e o MiniMax-H3 lê o estado oculto não normalizado após sua 50ª camada decodificadora, em vez da última, de modo que o checkpoint completo liberado é utilizado com sua cabeça de modelo de linguagem não utilizada.

As três tarefas são fluxos de trabalho do MiniMaxH3Blocks, e o repositório contém um modular_model_index.json que nomeia cada componente com sua própria especificação de carregamento. Para servir uma única tarefa, passe o fluxo de trabalho para from_pretrained: ele mantém apenas os blocos desse fluxo de trabalho, de modo que a assinatura do pipeline (pipe.doc) documenta exatamente as entradas dessa tarefa, apenas os componentes dessa tarefa são declarados e load_components busca exatamente seus subdiretórios — um pipeline t2va / fl2va nunca acessa transformer_ref/, e um pipeline ref2va nunca acessa transformer/.

import torch
from diffusers import ModularPipeline

pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", workflow="ref2va")
pipe.load_components(dtype=torch.bfloat16)

pipe.doc exibe o que o pipeline à sua frente recebe e retorna — cada entrada com seu valor padrão, os componentes que ele espera e as saídas que produz. Reduzido a um único fluxo de trabalho, ele descreve exatamente aquela tarefa, o que é a maneira mais rápida de ver o que uma solicitação precisa antes de fazê-la.

Para manter todos os fluxos de trabalho disponíveis em um único pipeline, deixe o argumento workflow de fora: o pipeline então seleciona o fluxo de trabalho a cada chamada com base nas entradas que recebe.

pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3")

O carregamento ainda pode ser feito um fluxo de trabalho por vez. Esta chamada única busca transformer/ e todos os componentes compartilhados, que atendem tanto ao t2va quanto ao fl2va:

pipe.load_components(workflow="t2va", dtype=torch.bfloat16)

Um load_components() simples, sem workflow=, carrega ambas as partições de 61,7 GB do transformer, o que permite que um único pipeline atenda aos três fluxos de trabalho sem uma nova chamada de carregamento. Combine-o com um ComponentsManager e offloading automático: os pesos ficam na RAM do host e o gerente move para o acelerador apenas o que cada etapa precisa, de modo que, quando o denoiser ref2va precisa do dispositivo, a estratégia faz o offloading do que for necessário para liberar espaço suficiente. Veja Memória para as receitas.

Dois agendadores

Os latentes de vídeo e de áudio seguem dois agendamentos diferentes dentro de uma única chamada do transformer por passo, motivo pelo qual os blocos esperam duas instâncias de MiniMaxH3Scheduler: scheduler para os latentes de vídeo (shift=12.0 nos checkpoints liberados) e audio_scheduler para os latentes de áudio (shift=3.0).

Ambas as partições do transformer são destiladas por orientação, portanto isso vale para todos os fluxos de trabalho: a orientação está incorporada nos pesos, não há um guia, nem negative_prompt e nem guidance_scale, e cada etapa executa exatamente uma passagem de frente.

Restrições de geração

• 24 fps, de 5 a 15 segundos. num_frames é arredondado para cima para o próximo 17 * n + 5 que o VAE de vídeo pode decodificar, e a duração resultante deve permanecer nessa janela.
• Uma borda curta de 768 pixels. height e width padrão para o próprio canvas do MiniMax-H3 para a proporção de aspecto do primeiro keyframe (ou 16:9 sem um) e devem ser múltiplos de 32.
• Um gerador, três extrações. Uma solicitação extrai primeiro o ruído de condicionamento do keyframe ou de referência, depois o ruído do vídeo e, por fim, o ruído do áudio, todos a partir do generator que é passado, de modo que duas execuções a partir do mesmo estado do gerador retornam o mesmo vídeo e trilha sonora. Passar latents ou audio_latents substitui a extração correspondente.
• num_inference_steps conta os pontos da grade de sigma, incluindo o terminal 0, portanto, ele resulta em uma avaliação a menos do modelo.

Memória

O transformer sozinho ocupa 61,7 GB em bfloat16 e o conditioner do Qwen3-VL ocupa mais 62,1 GB, portanto a receita de carregamento depende do hardware. Canvas menores são o principal fator de velocidade em qualquer configuração: height e width precisam apenas ser múltiplos de 32, e 960x544 executa cerca de 2,3x mais rápido por passo do que o 1344x768 treinado.

Em um cartão de 80 GB, registre os componentes em um ComponentsManager e deixe que ele os mova para dentro e para fora do acelerador:

import torch
from diffusers import ComponentsManager, ModularPipeline

manager = ComponentsManager()
pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", components_manager=manager)
pipe.load_components(workflow="t2va", dtype=torch.bfloat16)
manager.enable_auto_cpu_offload(device="cuda", memory_reserve_margin="12GB")  # or "mps", "xpu", "cpu"
pipe.transformer.set_attention_backend("_flash_3_hub")  # Hopper, roughly 3x faster; kernels fetched from the Hub

Em um cartão de consumo (24 a 32 GB), quantize os dois componentes grandes para int8 conforme eles são carregados e transmita os blocos do transformer a partir da RAM da CPU. Tudo abaixo usa apenas carregadores suportados, sem patches, e funciona diretamente a partir do checkpoint bfloat16:

import torch
from diffusers import MiniMaxH3Transformer3DModel, ModularPipeline, TorchAoConfig
from diffusers.hooks import apply_group_offloading
from transformers import Qwen3VLForConditionalGeneration
from transformers import TorchAoConfig as TransformersTorchAoConfig
from torchao.quantization import Int8WeightOnlyConfig

pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3")
pipe.update_components(
    transformer=MiniMaxH3Transformer3DModel.from_pretrained(
        "MiniMaxAI/MiniMax-H3", subfolder="transformer", dtype=torch.bfloat16,
        quantization_config=TorchAoConfig(
            Int8WeightOnlyConfig(version=2),
            modules_to_not_convert=[
                "proj_in", "audio_proj_in", "context_embedder", "time_embedder", "time_proj",
                "token_refiner", "norm_out", "proj_out", "audio_proj_out",
            ],
        ),
        low_cpu_mem_usage=False,
    ),
    text_encoder=Qwen3VLForConditionalGeneration.from_pretrained(
        "MiniMaxAI/MiniMax-H3", subfolder="text_encoder", dtype=torch.bfloat16,
        quantization_config=TransformersTorchAoConfig(
            Int8WeightOnlyConfig(version=2),
            modules_to_not_convert=["model.visual", "model.language_model.embed_tokens", "model.language_model.norm", "lm_head"],
        ),
    ),
)
pipe.load_components(workflow="t2va", dtype=torch.bfloat16)

# version=2 int8 tensors are pinnable, which streamed offload needs, and freezing removes the one autograd
# path the quantized tensors cannot serve.
pipe.transformer.requires_grad_(False)
pipe.text_encoder.requires_grad_(False)

offload = dict(onload_device=torch.device("cuda"), offload_device=torch.device("cpu"), use_stream=True)
pipe.transformer.enable_group_offload(offload_type="block_level", num_blocks_per_group=1, **offload)
apply_group_offloading(pipe.text_encoder.model, offload_type="leaf_level", **offload)
pipe.vae.to("cuda")  # or "mps", "xpu", "cpu"
pipe.audio_vae.to("cuda")

Com 12 a 16 GB, a mesma receita funciona com o grupo do VAE de vídeo também descarregado (offload_type="leaf_level", sem stream) e um canvas pequeno, como 960x544. Espere que os pesos fiquem na RAM do host: cerca de 75 GB em int8.

Com duas placas, nada precisa ser descarregado: divida o pipeline em duas partes e coloque cada metade em seu próprio dispositivo.

import torch
from diffusers import ComponentsManager, ModularPipeline

workflow = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3").blocks.get_workflow("t2va")

text_manager = ComponentsManager()
text_manager.enable_auto_cpu_offload(device="cuda:1")
conditioner = workflow.sub_blocks.pop("text_encoder").init_pipeline(
    "MiniMaxAI/MiniMax-H3", components_manager=text_manager
)
conditioner.load_components(dtype=torch.bfloat16)

manager = ComponentsManager()
manager.enable_auto_cpu_offload(device="cuda:0")
rest = workflow.init_pipeline("MiniMaxAI/MiniMax-H3", components_manager=manager)
rest.load_components(dtype=torch.bfloat16)

prompt = "A red fox trotting through a snowy pine forest, snow crunching underfoot"
state = conditioner(prompt=prompt)
results = rest(
    state=state,
    num_frames=124,
    generator=torch.Generator().manual_seed(42),
    output=["videos", "audio", "sampling_rate"],
)

Duas placas de 80 GB executam o bfloat16 completo dessa forma: cada metade cabe em sua própria placa, portanto nada é removido para a memória do host uma vez que esteja residente. Duas placas de 48 GB fazem o mesmo com o carregamento int8 acima em ambos os componentes.

Texto e keyframes

MiniMaxH3Blocks cobre texto para vídeo e áudio e condicionamento por quadro-chave. Um quadro-chave pode ser o quadro a partir do qual o vídeo começa (image), o quadro em que termina (last_image) ou ambos.

import torch
from diffusers import ComponentsManager, ModularPipeline
from diffusers.utils import load_image
from diffusers.utils.export_utils import encode_video

# 61.7GB of transformer and 62.1GB of conditioner do not sit on one accelerator, so the components are
# registered in a manager that moves each one on and off as the blocks reach it. See [Memory](#memory).
manager = ComponentsManager()
manager.enable_auto_cpu_offload(device="cuda")  # or "mps", "xpu", "cpu"

pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", components_manager=manager)
pipe.load_components(workflow="fl2va", dtype=torch.bfloat16)

prompt = "A red fox trotting through a snowy pine forest, snow crunching underfoot"
# `output=` returns exactly the named outputs instead of the whole pipeline state.
outputs = ["videos", "audio", "sampling_rate"]

# Text to video + audio.
results = pipe(prompt=prompt, num_frames=124, generator=torch.Generator().manual_seed(42), output=outputs)

# First frame (and optionally last frame) to video + audio. The canvas follows the first keyframe.
image = load_image(
    "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg"
)
results = pipe(prompt=prompt, image=image, num_frames=124, generator=torch.Generator().manual_seed(42), output=outputs)

encode_video(
    results["videos"][0],
    fps=24,
    output_path="minimax_h3_fl2va.mp4",
    audio=results["audio"][0],
    audio_sample_rate=results["sampling_rate"],
)

Vídeo e áudio são gerados conjuntamente e saem da chamada como saídas separadas, videos e audio, além da sampling_rate que a trilha sonora carrega; a multiplexação em um único arquivo fica a cargo do chamador, por exemplo, com encode_video().

Referências Omni

O workflow ref2va é condicionado por uma lista ordenada de referências: até 9 imagens, 3 vídeos e 3 clipes de áudio, totalizando 12. A ordem é semântica. Ela rotula as referências na apresentação do prompt ("<Picture 1>", "<Audio 1>", "<Video 1>") e avança o relógio rotativo compartilhado de áudio/vídeo, de modo que reordenar as mesmas referências constitui uma solicitação diferente.

Diferentemente dos keyframes acima, as referências não vinculam a geometria gerada: elas são codificadas em sua própria resolução e o canvas de destino padrão é o 16:9 do MiniMax-H3.

Existe uma classe de referência por modalidade, cada uma contendo a mídia em memória e a taxa que a mídia carrega:

As taxas são a partir das quais tudo é reamostrado: os quadros para os 24 fps próprios do MiniMax-H3, descartando e duplicando quadros inteiros, e a forma de onda para a taxa de amostragem do VAE de áudio. Mídias nas taxas próprias do MiniMax-H3 passam sem alterações, de modo que apenas dados produzidos em outra taxa precisam indicar isso.

Uma referência é construída de uma das duas formas: decodificada de um arquivo de mídia com o classmethod from_file da classe, ou construída diretamente a partir da mídia que a solicitação já mantém em memória — é assim que uma geração anterior é reutilizada (veja Uma geração como referência).

Os blocos nunca abrem um arquivo de mídia — decodificar um caminho é responsabilidade do chamador, assim como em qualquer outra parte da biblioteca. Cada classe de referência faz isso por meio de seu classmethod from_file, que aceita um caminho ou uma URL (vídeo e áudio através do PyAV) e retorna uma referência carregando as taxas reportadas pelo contêiner — um vídeo traz sua taxa de quadros e sua trilha sonora junto. Prefira from_file a load_video(), que descarta a taxa de quadros: uma referência construída a partir de quadros cuja taxa real foi perdida é condicionada na velocidade errada, e nada é lançado.

import torch
from diffusers import ComponentsManager, ModularPipeline
from diffusers.modular_pipelines.minimax_h3 import (
    MiniMaxH3AudioReference,
    MiniMaxH3ImageReference,
    MiniMaxH3VideoReference,
)
from diffusers.utils import load_video
from diffusers.utils.export_utils import encode_video

# `ref2va` is a workflow of the one MiniMax-H3 pipeline; selecting it loads only the `transformer_ref/`
# checkpoint partition, and the manager moves each component on and off the accelerator in turn.
manager = ComponentsManager()
manager.enable_auto_cpu_offload(device="cuda")  # or "mps", "xpu", "cpu"

pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", workflow="ref2va", components_manager=manager)
pipe.load_components(dtype=torch.bfloat16)

subject = MiniMaxH3ImageReference.from_file(
    "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg"
)

# Decoding a file brings its rates along: the video its own frame rate and its soundtrack, the clip its sample rate.
results = pipe(
    prompt="The character speaks in time with the reference recording, natural lip movement",
    references=[
        subject,
        MiniMaxH3VideoReference.from_file(
            "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/hiker.mp4"
        ),
        MiniMaxH3AudioReference.from_file("voice.wav"),
    ],
    num_frames=124,
    output=["videos", "audio", "sampling_rate"],
)

# Frames a request already holds declare the rate they carry — `load_video` does not preserve it.
motion = load_video("motion_ref.mp4")
results = pipe(
    prompt="The subject walks toward camera, matching the reference video's shot rhythm",
    references=[subject, MiniMaxH3VideoReference(frames=motion, fps=30.0)],
    num_frames=124,
    output=["videos", "audio", "sampling_rate"],
)

encode_video(
    results["videos"][0],
    fps=24,
    output_path="minimax_h3_ref2va.mp4",
    audio=results["audio"][0],
    audio_sample_rate=results["sampling_rate"],
)

num_frames é obrigatório para ref2va. Para gerar um vídeo exatamente com a duração de uma trilha sonora de referência, calcule-o a partir do clipe — round(samples / sample_rate * 24) — e ele será arredondado para cima até o próximo 17 * n + 5 que o VAE de vídeo pode decodificar; a duração resultante deve permanecer entre 5 e 15 segundos, que é o intervalo gerado pelo MiniMax-H3.

Uma geração como referência

Como os fluxos de trabalho compartilham um único pipeline, uma geração t2va pode ser usada diretamente como referência ref2va — e o construtor em memória foi projetado exatamente para essa transição. A mídia gerada já está nas taxas próprias do MiniMax-H3 (quadros a 24 fps, a trilha sonora na taxa de amostragem do VAE de áudio), portanto a referência não requer argumentos de taxa e nada é re-codificado por meio de um contêiner com perdas no caminho:

import torch
from diffusers import ComponentsManager, ModularPipeline
from diffusers.modular_pipelines.minimax_h3 import MiniMaxH3VideoReference

manager = ComponentsManager()
manager.enable_auto_cpu_offload(device="cuda")  # or "mps", "xpu", "cpu"

# The full pipeline holds every workflow and picks one per call from the inputs. Loading without a
# `workflow=` brings both transformer partitions in one call, so the `ref2va` request that follows the
# `t2va` generation needs no further loading.
pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", components_manager=manager)
pipe.load_components(dtype=torch.bfloat16)

results = pipe(
    prompt="An astronaut hiking through the mountains, humming a tune",
    num_frames=124,
    output=["videos", "audio", "sampling_rate"],
)

reference = MiniMaxH3VideoReference(
    frames=results["videos"][0],
    audio=results["audio"][0],
    sample_rate=results["sampling_rate"],
)
results = pipe(
    prompt="The same astronaut now walks along a beach at sunset, humming the same tune",
    references=[reference],
    num_frames=124,
    output=["videos", "audio", "sampling_rate"],
)

MiniMaxH3ModularPipeline

pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3", workflow="ref2va")

import torch
from diffusers import ModularPipeline

pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3")
pipe.load_components(dtype=torch.bfloat16)

MiniMaxH3Blocks

MiniMaxH3ImageReference

MiniMaxH3VideoReference

MiniMaxH3AudioReference