MiniMax-H3

MiniMax-H3 genera el video y su banda sonora de forma conjunta. Un único transformer desruidifica una secuencia empaquetada que contiene la condición de texto, los medios de condición y los latentes objetivo de video y audio. No hay un vocoder separado ni una pasada de audio a posteriori: el video y el audio salen del mismo bucle de desruidificación.

Puedes encontrar los puntos de control originales de MiniMax-H3 bajo la organización MiniMaxAI.

MiniMax-H3 se integra únicamente como bloques de Modular Diffusers, de la misma manera que Anima: los bloques y su MiniMaxH3ModularPipeline constituyen toda la integración, y no existe una mitad de DiffusionPipeline.

Distribución del punto de control

MiniMax-H3 se publicó como dos particiones de puntos de control que comparten todos los componentes excepto el transformador, por lo que la conversión de diffusers coloca ambos en un solo repositorio:

Todo, excepto el transformer, es decir, el VAE de video, el VAE de audio, el condicionador Qwen3-VL, su tokenizador y procesador, y los dos programadores, se comparte y se almacena una sola vez.

El acondicionador es un Qwen3VLForConditionalGeneration, y MiniMax-H3 lee el estado oculto sin normalizar después de su 50.ª capa decodificadora en lugar de la última, por lo que se utiliza el punto de control completo publicado con su cabeza de modelo de lenguaje sin usar.

Las tres tareas son flujos de trabajo del único MiniMaxH3Blocks, y el repositorio incluye un único modular_model_index.json que nombra cada componente con su propia especificación de carga. Para servir una sola tarea, pase el flujo de trabajo a from_pretrained: este conserva solo los bloques de ese flujo de trabajo, por lo que la firma de la tubería (pipe.doc) documenta exactamente las entradas de esa tarea, solo se declaran los componentes de esa tarea y load_components recupera exactamente sus subcarpetas: una tubería t2va / fl2va nunca toca transformer_ref/, y una ref2va nunca toca transformer/.

import torch
from diffusers import ModularPipeline

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

pipe.doc muestra qué recibe y devuelve el pipeline que tienes delante: cada entrada con su valor predeterminado, los componentes que espera y las salidas que produce. Recortado a un solo flujo de trabajo, describe exactamente esa tarea, lo cual es la forma más rápida de ver lo que necesita una solicitud antes de hacerla.

Para mantener todos los flujos de trabajo disponibles en un solo pipeline, en su lugar, omita el argumento workflow: el pipeline selecciona entonces el flujo de trabajo por llamada a partir de las entradas que se le pasan.

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

La carga aún puede realizarse un flujo de trabajo a la vez. Esta llamada obtiene transformer/ y todos los componentes compartidos, que sirven tanto para t2va como para fl2va:

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

Un load_components() simple, sin workflow=, carga ambas particiones de transformador de 61,7 GB, lo que permite que un solo pipeline atienda los tres flujos de trabajo sin una llamada de carga adicional. Combínalo con un ComponentsManager y el descargado automático: los pesos residen en la RAM del host y el gestor transfiere al acelerador solo lo que cada paso necesita, de modo que cuando el desruidador ref2va requiere el dispositivo, la estrategia descarga lo que libere suficiente espacio. Consulta Memoria para las recetas.

Dos programadores

Los latentes de video y de audio avanzan por dos agendas distintas dentro de una única llamada al transformer por paso, por lo que los bloques esperan dos instancias de MiniMaxH3Scheduler: scheduler para los latentes de video (shift=12.0 en los puntos de control publicados) y audio_scheduler para los latentes de audio (shift=3.0).

Ambas particiones de transformer están destiladas con guía, por lo que esto se aplica a cada flujo de trabajo: la guía está integrada en los pesos, no hay un guionista, no hay negative_prompt ni guidance_scale, y cada paso ejecuta exactamente una pasada hacia adelante.

Restricciones de generación

• 24 fps, de 5 a 15 segundos. num_frames se ajusta al siguiente 17 * n + 5 que el VAE de video puede decodificar, y la duración resultante debe permanecer en ese rango.
• Un borde corto de 768 píxeles. height y width se establecen por defecto en el lienzo propio de MiniMax-H3 para la relación de aspecto del primer fotograma clave (o 16:9 si no hay ninguno) y deben ser múltiplos de 32.
• Un generador, tres extracciones. Una solicitud extrae primero el ruido de condicionamiento de fotograma clave o de referencia, luego el ruido del video y luego el ruido del audio, todo desde el generator que se le pasa, de modo que dos ejecuciones desde el mismo estado del generador devuelven el mismo video y banda sonora. Pasar latents o audio_latents reemplaza la extracción correspondiente.
• num_inference_steps cuenta los puntos de la cuadrícula de sigma, incluido el 0 terminal, por lo que reduce en una la cantidad de evaluaciones del modelo.

Memoria

El transformer por sí solo ocupa 61,7 GB en bfloat16 y el conditioner de Qwen3-VL ocupa otros 62,1 GB, por lo que la receta de carga depende del hardware. Los lienzos más pequeños son el mayor palanca de velocidad en cualquier configuración: height y width solo tienen que ser múltiplos de 32, y 960x544 se ejecuta unas 2,3 veces más rápido por paso que el 1344x768 con el que se entrenó.

En una tarjeta de 80 GB, registra los componentes en un ComponentsManager y déjalo moverlos sobre y fuera del 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

En una tarjeta de consumo (24 a 32 GB), cuantice los dos componentes grandes a int8 a medida que se cargan y transmita los bloques del transformer desde la RAM de la CPU. Todo lo siguiente utiliza solo cargadores admitidos, sin parches, y funciona directamente desde el 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")

En 12 a 16 GB, la misma receta funciona con el grupo de VAE de video también descargado (offload_type="leaf_level", sin stream) y un lienzo pequeño como 960x544. Espera que los pesos residan en la RAM del host: alrededor de 75 GB de ella en int8.

Con dos tarjetas no es necesario descargar nada: divide el pipeline en dos y coloca cada mitad en su propio 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"],
)

Dos tarjetas de 80 GB ejecutan el modelo completo en bfloat16 de esta manera: cada mitad cabe en su propia tarjeta, por lo que nada se expulsa a la memoria del host una vez que está residente. Dos tarjetas de 48 GB hacen lo mismo con la carga en int8 descrita anteriormente en ambos componentes.

Texto y fotogramas clave

MiniMaxH3Blocks cubre la generación de video y audio a partir de texto y el condicionamiento por fotogramas clave. Un fotograma clave puede ser el fotograma desde el que comienza el video (image), el fotograma en el que termina (last_image) o 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"],
)

El video y el audio se generan de forma conjunta y salen de la llamada como salidas separadas, videos y audio, junto con la sampling_rate que lleva la banda sonora; la multiplexación en un solo archivo queda a cargo del llamador, por ejemplo con encode_video().

Referencias universales

El flujo de trabajo ref2va se condiciona en una lista ordenada de referencias: hasta 9 imágenes, 3 videos y 3 clips de audio, 12 en total. El orden es semántico. Etiqueta las referencias en la presentación del prompt ("<Picture 1>", "<Audio 1>", "<Video 1>") y avanza el reloj rotativo compartido de audio/video, por lo que reordenar las mismas referencias constituye una solicitud diferente.

A diferencia de los fotogramas clave anteriores, las referencias no fijan la geometría generada: se codifican en su propia resolución y el lienzo de destino predeterminado es 16:9 de MiniMax-H3.

Existe una clase de referencia por modalidad, cada una de las cuales almacena los medios en memoria y la tasa a la que dichos medios se transmiten:

Las tasas son las que se usan para re-muestrear todo: los fotogramas a las 24 fps propias de MiniMax-H3 mediante la eliminación y duplicación de fotogramas completos, y la forma de onda a la tasa de muestreo del VAE de audio. Los medios a las tasas propias de MiniMax-H3 pasan sin modificaciones, por lo que solo los datos generados a otra tasa deben indicarlo.

Una referencia se construye de una de dos maneras: decodificada desde un archivo multimedia mediante el método de clase from_file de la clase, o construida directamente desde los medios que la solicitud ya mantiene en memoria, que es la forma en que una generación anterior se reintroduce (consulte Una generación como referencia).

Los bloques nunca abren un archivo multimedia: decodificar una ruta es responsabilidad del llamador, como ocurre en todas las demás partes de la biblioteca. Cada clase de referencia lo hace a través de su classmethod from_file, que toma una ruta o una URL (vídeo y audio a través de PyAV) y devuelve una referencia con las tasas que informa el contenedor: un vídeo trae consigo su tasa de fotogramas y su banda sonora. Prefiera from_file sobre load_video(), que descarta la tasa de fotogramas: una referencia construida a partir de fotogramas cuya tasa real se perdió se condiciona a la velocidad incorrecta, y nada lanza una excepción.

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 es obligatorio para ref2va. Para generar un video con la duración exacta de una banda sonora de referencia, calcúlalo a partir del clip — round(samples / sample_rate * 24) — y se redondea hacia arriba al siguiente 17 * n + 5 que el VAE de video puede decodificar; la duración resultante debe permanecer entre los 5 y 15 segundos que genera MiniMax-H3.

Una generación como referencia

Dado que los flujos de trabajo comparten un mismo pipeline, una generación t2va puede usarse directamente como referencia ref2va, y el constructor en memoria está diseñado precisamente para esta transición. Los medios generados ya están en las tasas propias de MiniMax-H3 (marcos a 24 fps y la banda sonora a la tasa de muestreo del VAE de audio), por lo que la referencia no necesita argumentos de tasa y nada se vuelve a codificar a través de un contenedor con pérdida en el proceso:

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