MiniMax-H3

MiniMax-H3 menghasilkan video dan soundtrack-nya secara bersamaan. Satu transformer melakukan denoising pada satu urutan yang dikemas, yang berisi kondisi teks, media pengkondisi, serta latens video dan audio target. Tidak ada vocoder terpisah dan tidak ada jalur pasca-pemrosesan audio: video dan audio keluar dari loop denoising yang sama.

Anda dapat menemukan checkpoint asli MiniMax-H3 di bawah organisasi MiniMaxAI.

MiniMax-H3 terintegrasi hanya sebagai blok Modular Diffusers, sama seperti Anima: blok-blok tersebut beserta MiniMaxH3ModularPipeline merupakan keseluruhan integrasi, dan tidak ada bagian DiffusionPipeline.

Tata letak checkpoint

MiniMax-H3 dirilis sebagai dua partisi checkpoint yang berbagi setiap komponen kecuali transformer, sehingga konversi diffusers menempatkan keduanya dalam satu repositori:

Semua komponen selain transformer, yaitu video VAE, audio VAE, conditioner Qwen3-VL, tokenizer dan processor-nya, serta dua scheduler, dibagikan dan disimpan sekali.

Conditioner-nya adalah Qwen3VLForConditionalGeneration, dan MiniMax-H3 membaca hidden state unnormalized setelah decoder layer ke-50-nya, bukan yang terakhir, sehingga checkpoint lengkap yang dirilis digunakan dengan head language-model-nya tidak terpakai.

Ketiga tugas tersebut merupakan alur kerja dari satu MiniMaxH3Blocks, dan repositori membawa satu modular_model_index.json yang menamai setiap komponen dengan spesifikasi pemuatannya masing-masing. Untuk menyajikan satu tugas, teruskan alur kerja ke from_pretrained: ia hanya menyimpan blok dari alur kerja tersebut, sehingga tanda tangan pipeline (pipe.doc) mendokumentasikan tepat input untuk tugas tersebut, hanya komponen untuk tugas tersebut yang dideklarasikan, dan load_components mengambil tepat subfolder mereka — pipeline t2va / fl2va tidak pernah menyentuh transformer_ref/, dan pipeline ref2va tidak pernah menyentuh transformer/.

import torch
from diffusers import ModularPipeline

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

pipe.doc menampilkan apa yang diterima dan dikembalikan oleh pipeline di depan Anda — setiap input beserta nilai default-nya, komponen yang diharapkan, dan output yang dihasilkan. Dipangkas menjadi satu alur kerja, deskripsinya tepat untuk tugas tersebut, yang merupakan cara tercepat untuk melihat apa yang dibutuhkan sebuah permintaan sebelum membuatnya.

Untuk tetap membuat setiap alur kerja tersedia pada satu pipeline, biarkan argumen workflow kosong: pipeline kemudian memilih alur kerja per panggilan berdasarkan input yang diteruskan.

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

Pemmuatan masih dapat dilakukan satu per satu alur kerja. Panggilan ini mengambil transformer/ dan setiap komponen bersama, yang melayani kedua t2va dan fl2va:

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

Panggilan load_components() polos tanpa workflow= akan menarik kedua partisi transformer berukuran 61,7GB, yang memungkinkan satu pipeline melayani ketiga workflow tanpa panggilan pemuatan lain. Gabungkan dengan ComponentsManager dan auto offloading: bobot disimpan di RAM host, dan manager memindahkan ke akselerator hanya apa yang dibutuhkan oleh setiap langkah, sehingga ketika denoiser ref2va membutuhkan perangkat, strategi akan meng-offload apa pun yang membebaskan ruang yang cukup. Lihat Memory untuk resepnya.

Dua penjadwal

Latent video dan audio mengikuti dua jadwal yang berbeda di dalam satu panggilan transformer per langkah, itulah mengapa blok mengharapkan dua instans MiniMaxH3Scheduler: scheduler untuk latent video (shift=12.0 pada checkpoint yang dirilis) dan audio_scheduler untuk latent audio (shift=3.0).

Kedua partisi transformer ini telah melalui distilasi panduan, sehingga hal ini berlaku untuk setiap alur kerja: panduan sudah tertanam dalam bobot, tidak ada pengarah, tidak ada negative_prompt dan tidak ada guidance_scale, serta setiap langkah hanya menjalankan satu kali forward pass.

Batasan generasi

• 24 fps, 5 hingga 15 detik. num_frames dibulatkan ke atas ke 17 * n + 5 berikutnya yang dapat didekode oleh VAE video, dan durasi yang dihasilkan harus tetap berada dalam rentang tersebut.
• Sisi pendek 768 piksel. height dan width secara default menggunakan kanvas MiniMax-H3 sendiri untuk rasio aspek keyframe pertama (atau 16:9 jika tidak ada) dan harus berupa kelipatan 32.
• Satu generator, tiga undian. Permintaan pertama mengambil noise kondisioning keyframe atau referensi, kemudian noise video, lalu noise audio, semuanya dari generator yang diteruskan, sehingga dua eksekusi dari keadaan generator yang sama akan mengembalikan video dan soundtrack yang sama. Menyalurkan latents atau audio_latents akan menggantikan undian yang sesuai.
• num_inference_steps menghitung titik-titik grid sigma, termasuk 0 terminal, sehingga mengurangi satu evaluasi model.

Memori

Transformer saja berukuran 61,7 GB dalam bfloat16 dan conditioner Qwen3-VL menambah 62,1 GB, sehingga resep pemuatan bergantung pada perangkat keras. Kanvas yang lebih kecil adalah tuas kecepatan terbesar di setiap konfigurasi: height dan width hanya perlu menjadi kelipatan 32, dan 960x544 berjalan sekitar 2,3x lebih cepat per langkah dibandingkan 1344x768 yang dilatih.

Pada satu kartu 80 GB, daftarkan komponen dalam ComponentsManager dan biarkan memindahkannya ke dan dari akselerator:

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

Pada kartu konsumen (24 hingga 32 GB), kuantisasi dua komponen besar ke int8 saat dimuat dan alirkan blok transformer dari RAM CPU. Semua di bawah ini hanya menggunakan loader yang didukung, tanpa patch, dan berfungsi langsung dari 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")

Pada 12 hingga 16 GB, resep yang sama juga berfungsi dengan grup video VAE yang di-offload (offload_type="leaf_level", tanpa stream) dan kanvas kecil seperti 960x544. Haraplah bobot akan berada di RAM host: sekitar 75 GB pada int8.

Dengan dua kartu, tidak ada yang perlu di-offload: bagi pipeline menjadi dua dan letakkan masing-masing setengahnya di perangkatnya sendiri.

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

Dua kartu 80 GB menjalankan bfloat16 penuh dengan cara ini: setiap setengah muat di kartunya sendiri, sehingga tidak ada yang dievakuasi kembali ke memori host setelah berada di kartu. Dua kartu 48 GB melakukan hal yang sama dengan pemuatan int8 di atas pada kedua komponen.

Teks dan keyframes

MiniMaxH3Blocks mencakup teks-ke-video-dan-audio serta kondisioning keyframe. Keyframe dapat berupa frame tempat video dimulai (image), frame tempat video diakhiri (last_image), atau keduanya.

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

Video dan audio dihasilkan secara bersama dan keluar dari panggilan sebagai output terpisah, videos dan audio, di samping sampling_rate yang dibawa oleh soundtrack; penggabungan keduanya ke dalam satu file dibiarkan kepada pemanggil, misalnya dengan encode_video().

Referensi-omni

Workflow ref2va mengondisikan pada daftar referensi yang terurut: hingga 9 gambar, 3 video, dan 3 klip audio, total 12. Urutannya bersifat semantik. Urutan ini memberi label pada referensi dalam presentasi prompt ("<Picture 1>", "<Audio 1>", "<Video 1>") dan menggerakkan jam rotasi audio/video bersama, sehingga pengurutan ulang referensi yang sama merupakan permintaan yang berbeda.

Berbeda dengan keyframe di atas, referensi tidak mengikat geometri yang dihasilkan: mereka dikodekan pada resolusi mereka sendiri dan kanvas target secara default menggunakan rasio 16:9 dari MiniMax-H3.

Ada satu kelas referensi per modalitas, masing-masing menyimpan media di memori dan laju yang dibawa oleh media tersebut:

Laju (rates) adalah acuan untuk semua proses resampling: frame diresample ke 24 fps milik MiniMax-H3 dengan cara membuang dan menduplikasi frame utuh, serta waveform diresample ke laju sampel (sample rate) dari audio VAE. Media yang sudah berada pada laju asli MiniMax-H3 akan diproses tanpa perubahan, sehingga hanya data yang dihasilkan pada laju lain yang perlu dinyatakan secara eksplisit.

Referensi dibangun dengan salah satu dari dua cara: didekodekan dari file media dengan classmethod from_file dari kelas tersebut, atau dibangun langsung dari media yang sudah dipegang oleh permintaan di memori — inilah cara generasi sebelumnya memberi umpan balik (lihat Generasi sebagai referensi).

Blok-blok ini tidak pernah membuka file media — decoding sebuah path adalah tanggung jawab pemanggil, sebagaimana di bagian lain pustaka. Setiap kelas referensi melakukannya melalui classmethod from_file, yang menerima path atau URL (video dan audio melalui PyAV) dan mengembalikan referensi yang membawa rate yang dilaporkan oleh container — sebuah video membawa frame rate dan soundtrack-nya. Lebih disarankan menggunakan from_file daripada load_video(), yang menghilangkan frame rate: referensi yang dibangun dari frame yang rate aslinya hilang akan dikondisikan pada kecepatan yang salah, dan tidak ada yang memicu error.

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 wajib untuk ref2va. Untuk menghasilkan video yang panjangnya persis sama dengan soundtrack referensi, hitung dari klip — round(samples / sample_rate * 24) — dan nilai tersebut akan dibulatkan ke atas ke 17 * n + 5 berikutnya yang dapat didekode oleh VAE video; durasi yang dihasilkan harus tetap berada di antara 5 dan 15 detik yang dihasilkan oleh MiniMax-H3.

Sebuah generasi sebagai referensi

Karena alur kerja berbagi satu pipeline, generasi t2va dapat langsung digunakan kembali sebagai referensi ref2va — dan konstruktor in-memory dirancang khusus untuk hand-off ini. Media yang dihasilkan sudah berada pada laju MiniMax-H3 itu sendiri (frame pada 24 fps, soundtrack pada laju sampel audio VAE), sehingga referensi tidak memerlukan argumen laju dan tidak ada yang di-encode ulang melalui container lossy di sepanjang jalan:

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