MiniMax-H3

MiniMax-H3 génère la vidéo et sa bande-son simultanément. Un seul transformer débruite une séquence compacte contenant le conditionnement textuel, les médias de conditionnement, ainsi que les latents de la vidéo et de l'audio cibles. Il n'y a ni vocoder séparé ni passe de post-traitement audio : la vidéo et l'audio sortent de la même boucle de débruitage.

Vous pouvez trouver les points de contrôle originaux de MiniMax-H3 sous l'organisation MiniMaxAI.

MiniMax-H3 est intégré uniquement sous forme de blocs Modular Diffusers, de la même manière qu'Anima : les blocs et leur MiniMaxH3ModularPipeline constituent l'intégralité de l'intégration, et il n'existe pas de moitié DiffusionPipeline.

Disposition du point de contrôle

MiniMax-H3 a été publié sous forme de deux partitions de points de contrôle qui partagent tous les composants, à l'exception du transformeur, de sorte que la conversion diffusers les place toutes deux dans un seul dépôt :

Tout, à l'exception du transformer, c'est-à-dire le VAE vidéo, le VAE audio, le conditionneur Qwen3-VL, son tokenizer et son processeur, ainsi que les deux schedulers, est partagé et stocké une seule fois.

Le conditionneur est un Qwen3VLForConditionalGeneration, et MiniMax-H3 lit l'état caché non normalisé après sa 50e couche décodeur plutôt que la dernière, de sorte que le point de contrôle complet publié est utilisé avec sa tête de modèle de langage inutilisée.

Les trois tâches sont des flux de travail du MiniMaxH3Blocks unique, et le dépôt contient un modular_model_index.json qui nomme chaque composant avec sa propre spécification de chargement. Pour servir une tâche unique, passez le flux de travail à from_pretrained : il ne conserve que les blocs de ce flux de travail, de sorte que la signature du pipeline (pipe.doc) documente exactement les entrées de cette tâche, seuls les composants de cette tâche sont déclarés, et load_components récupère exactement leurs sous-dossiers — un pipeline t2va / fl2va ne touche jamais à transformer_ref/, un pipeline ref2va ne touche jamais à transformer/.

import torch
from diffusers import ModularPipeline

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

pipe.doc affiche ce que le pipeline devant vous reçoit et renvoie — chaque entrée avec sa valeur par défaut, les composants qu’il attend et les sorties qu’il produit. Réduit à un seul flux de travail, il décrit exactement cette tâche, ce qui est le moyen le plus rapide de voir ce qu’une requête nécessite avant de l’envoyer.

Pour conserver tous les flux de travail disponibles sur un seul pipeline, omettez plutôt l'argument workflow : le pipeline choisit alors le flux de travail à chaque appel en fonction des entrées qui lui sont transmises.

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

Le chargement peut toujours se faire un flux de travail à la fois. Cet unique appel récupère transformer/ ainsi que tous les composants partagés, qui servent à la fois t2va et fl2va :

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

Un simple load_components() sans workflow= charge les deux partitions de transformeur de 61,7 Go, ce qui permet à un seul pipeline de servir les trois workflows sans un nouvel appel de chargement. Associez-le à un ComponentsManager et au déchargement automatique : les poids résident en RAM hôte et le manager transfère sur l'accélérateur uniquement ce dont chaque étape a besoin, de sorte que lorsque le débruiteur ref2va demande le périphérique, la stratégie décharge ce qui libère suffisamment d'espace. Consultez Mémoire pour les recettes.

Deux planificateurs

Les latents vidéo et audio suivent deux calendriers distincts au sein d'un seul appel de transformateur par étape, c'est pourquoi les blocs s'attendent à deux instances de MiniMaxH3Scheduler : scheduler pour les latents vidéo (shift=12.0 dans les points de contrôle publiés) et audio_scheduler pour les latents audio (shift=3.0).

Les deux partitions transformer sont distillées par guidage, ce qui s’applique à tous les flux de travail : le guidage est intégré aux poids, il n’y a ni guideur, ni negative_prompt, ni guidance_scale, et chaque étape exécute exactement un passage avant.

Contraintes de génération

• 24 images par seconde, 5 à 15 secondes. num_frames est arrondi à la valeur supérieure de la forme 17 * n + 5 que le VAE vidéo peut décoder, et la durée résultante doit rester dans cette plage.
• Un côté court de 768 pixels. height et width sont par défaut réglés sur le canevas de MiniMax-H3 pour le ratio d’aspect de la première image clé (ou 16:9 en l’absence de celle-ci) et doivent être des multiples de 32.
• Un générateur, trois tirages. Une requête tire d’abord le bruit de conditionnement de la clé d’image ou de référence, puis le bruit vidéo, puis le bruit audio, tous issus du generator qui lui est transmis, de sorte que deux exécutions à partir du même état du générateur renvoient la même vidéo et la même bande-son. Transmettre latents ou audio_latents remplace le tirage correspondant.
• num_inference_steps compte les points de la grille sigma, le terminal 0 inclus, ce qui réduit d'une évaluation le nombre d'appels au modèle.

Mémoire

Le transformer seul pèse 61,7 Go en bfloat16 et le conditionneur Qwen3-VL ajoute 62,1 Go, de sorte que la méthode de chargement dépend du matériel. Les toiles plus petites sont le principal levier de vitesse sur toute configuration : height et width n'ont besoin d'être que des multiples de 32, et 960x544 est environ 2,3 fois plus rapide par étape que la résolution d'entraînement 1344x768.

Sur une carte de 80 Go, enregistrez les composants dans un ComponentsManager et laissez-le les déplacer sur et hors de l'accélérateur :

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

Sur une carte grand public (24 à 32 Go), quantifiez les deux grands composants en int8 au moment du chargement et faites défiler les blocs du transformateur depuis la RAM CPU. Tout ce qui suit n'utilise que des chargeurs pris en charge, sans correctifs, et fonctionne directement à partir du point de contrôle 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")

Sur 12 à 16 Go, la même recette fonctionne avec le groupe VAE vidéo également déchargé (offload_type="leaf_level", sans flux) et un petit canevas tel que 960x544. Attendez-vous à ce que les poids résident en RAM hôte : environ 75 Go à int8.

Avec deux cartes, il n'est pas nécessaire de décharger quoi que ce soit : divisez le pipeline en deux et placez chaque moitié sur son propre appareil.

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"],
)

Deux cartes de 80 Go exécutent le bfloat16 complet de cette manière : chaque moitié tient sur sa propre carte, de sorte que rien n’est évacué vers la mémoire hôte une fois résident. Deux cartes de 48 Go font de même avec le chargement int8 ci-dessus sur les deux composants.

Texte et images clés

MiniMaxH3Blocks covers text-to-video-and-audio and keyframe conditioning. A keyframe can be the frame the video starts from (image), the frame it ends on (last_image), or both.

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"],
)

La vidéo et l’audio sont générés conjointement et sortent de l’appel sous forme de sorties distinctes, videos et audio, à côté du sampling_rate que porte la bande-son ; leur multiplexage dans un fichier unique est laissé à l’appelant, par exemple avec encode_video().

Références omni

Le workflow ref2va conditionne sur une liste ordonnée de références : jusqu’à 9 images, 3 vidéos et 3 clips audio, soit 12 au total. L’ordre est sémantique. Il étiquette les références dans la présentation du prompt ("<Picture 1>", "<Audio 1>", "<Video 1>") et fait avancer l’horloge rotative audio/vidéo partagée, de sorte que réordonner les mêmes références constitue une requête différente.

Contrairement aux images clés ci-dessus, les références ne contraignent pas la géométrie générée : elles sont encodées à leur propre résolution et le canevas cible est par défaut au format 16:9 de MiniMax-H3.

Il existe une classe de référence par modalité, chacune contenant les médias en mémoire et le taux auquel les médias sont transmis :

Les taux sont la référence à partir de laquelle tout est rééchantillonné : les images sont ramenées aux 24 fps propres à MiniMax-H3 en supprimant et en dupliquant des images entières, et le signal audio est adapté au taux d’échantillonnage du VAE audio. Les médias aux taux propres à MiniMax-H3 passent sans modification, si bien que seules les données produites à un autre taux doivent le signaler.

Une référence est construite de l’une des deux manières suivantes : décodée depuis un fichier média via la méthode de classe from_file de la classe, ou assemblée directement à partir des médias que la requête détient déjà en mémoire — c’est ainsi qu’une génération précédente est réinjectée (voir Une génération en tant que référence).

Les blocs n’ouvrent jamais de fichier média — le décodage d’un chemin est la responsabilité de l’appelant, comme partout ailleurs dans la bibliothèque. Chaque classe de référence le fait via sa méthode de classe from_file, qui prend un chemin ou une URL (vidéo et audio via PyAV) et renvoie une référence portant les taux signalés par le conteneur — une vidéo apporte son taux d’images et sa bande-son. Préférez from_file à load_video(), qui abandonne le taux d’images : une référence construite à partir d’images dont le taux réel a été perdu est conditionnée à la mauvaise vitesse, et rien ne lève d’exception.

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 est requis pour ref2va. Pour générer une vidéo dont la durée correspond exactement à celle d’une piste audio de référence, calculez cette valeur à partir du clip — round(samples / sample_rate * 24) — ; elle est ensuite arrondie à la valeur supérieure de la forme 17 * n + 5, que le VAE vidéo peut décoder. La durée résultante doit rester comprise entre 5 et 15 secondes, la plage générée par MiniMax-H3.

Une génération en tant que référence

Comme les flux de travail partagent un même pipeline, une génération t2va peut être réinjectée directement comme référence ref2va — et le constructeur en mémoire est conçu précisément pour ce transfert. Les médias générés sont déjà aux taux propres de MiniMax-H3 (images à 24 i/s, bande-son au taux d’échantillonnage du VAE audio), la référence n’a donc besoin d’aucun argument de taux et rien n’est réencodé via un conteneur avec perte en cours de route :

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