MiniMax-H3

MiniMax-H3, videoyu ve ses kaydını birlikte üretir. Tek bir transformer, metin koşullandırmasını, koşullandırma ortamlarını ve hedef video ile ses latentlerini içeren tek bir paketlenmiş diziyi gürültüden arındırır. Ayrı bir vokoder veya ses için sonradan işleme adımı yoktur: video ve ses, aynı gürültüden arındırma döngüsünden çıkar.

Orijinal MiniMax-H3 checkpoint'lerini MiniMaxAI kuruluşu altında bulabilirsiniz.

MiniMax-H3 yalnızca Modular Diffusers blokları olarak entegre edilmiştir, tıpkı Anima'nın entegre edildiği gibi: bloklar ve MiniMaxH3ModularPipeline tüm entegrasyonu oluşturur ve DiffusionPipeline tarafı yoktur.

Kontrol noktası düzeni

MiniMax-H3, transformer dışında tüm bileşenleri paylaşan iki checkpoint bölümü olarak yayınlandığından, diffusers dönüşümü ikisini de tek bir repoda birleştirir:

Transformer hariç her şey, yani video VAE, ses VAE, Qwen3-VL conditioner, onun tokenizer ve processor'ı ile iki scheduler, paylaşımlıdır ve bir kez saklanır.

Koşullandırıcı bir Qwen3VLForConditionalGeneration'dir ve MiniMax-H3, son katman yerine 50. decoder katmanından sonraki normalize edilmemiş gizli durumu okuduğu için, dil modeli başlığı kullanılmadan tam olarak yayınlanan checkpoint kullanılır.

Üç görevin tamamı MiniMaxH3Blocks tek birinin iş akışlarıdır ve depo, her bileşeni kendi yükleme özelliğiyle adlandıran tek bir modular_model_index.json içerir. Tek bir görevi sunmak için iş akışını from_pretrained parametresi olarak iletin: yalnızca o iş akışının bloklarını korur, bu nedenle hattın imzası (pipe.doc) tam olarak o görevin girdilerini belgelemekte, yalnızca o görevin bileşenleri tanımlanmakta ve load_components tam olarak alt klasörlerini getirmektedir — bir t2va / fl2va hattı asla transformer_ref/ ile etkileşime girmez, bir ref2va hattı ise asla transformer/ ile etkileşime girmez.

import torch
from diffusers import ModularPipeline

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

pipe.doc, önünüzdeki hattın neyi aldığını ve neyi döndürdüğünü gösterir: varsayılanlarıyla birlikte her girdi, beklediği bileşenler ve ürettiği çıktılar. Tek bir iş akışına indirgenmiş haliyle tam olarak o görevi açıklar; bu da bir istek yapmadan önce o isteğin ne gerektirdiğini görmenin en hızlı yoludur.

Tüm iş akışlarının tek bir pipeline üzerinde kullanılabilir kalmasını sağlamak için workflow argümanını dışarıda bırakın: pipeline, bu durumda her çağrıda kendisine iletilen girdilerden iş akışını seçer.

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

Yükleme işlemi yine tek tek iş akışı olarak gerçekleştirilebilir. Bu çağrı, hem t2va hem de fl2va için kullanılan transformer/ bileşenini ve tüm paylaşılan bileşenleri getirir:

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

A plain load_components() with no workflow= pulls both 61.7GB transformer partitions, which is what lets one pipeline serve all three workflows without another loading call. Pair it with a ComponentsManager and auto offloading: the weights live in host RAM and the manager moves onto the accelerator just what each step needs, so when the ref2va denoiser wants the device the strategy offloads whatever frees enough room. See Memory for the recipes.

İki zamanlayıcı

Video ve ses latentleri, her adımda tek bir transformer çağrısı içinde iki farklı zaman çizelgesi üzerinden ilerler; bu nedenle bloklar iki MiniMaxH3Scheduler örneği bekler: video latentleri için scheduler (yayınlanan checkpoint'lerde shift=12.0) ve ses latentleri için audio_scheduler (shift=3.0).

Her iki transformer bölümü de rehberlik damıtması (guidance-distilled) yapılmıştır, bu nedenle bu durum her iş akışı için geçerlidir: rehberlik ağırlıklara gömülüdür, bir rehber (guider) yoktur, negative_prompt ve guidance_scale yoktur ve her adım tam olarak bir ileri geçiş (forward pass) çalıştırır.

Üretim kısıtlamaları

• 24 fps, 5 ila 15 saniye. num_frames, video VAE'nin çözebileceği bir sonraki 17 * n + 5 değerine yuvarlanır ve elde edilen süre bu aralıkta kalmalıdır.
• 768 piksel kısa kenar. height ve width varsayılan olarak MiniMax-H3'ün kendi tuvalini kullanır; bu, ilk anahtar karein en-boy oranına (veya anahtar kare yoksa 16:9'a) göre belirlenir ve 32'nin katları olmalıdır.
• Bir üreteç, üç çekim. Bir istek, önce anahtar kare veya referans koşullandırma gürültüsünü, ardından video gürültüsünü, ardından da ses gürültüsünü, kendisine geçirilen generator üzerinden çeker; böylece aynı üreteç durumundan yapılan iki çalıştırma aynı videoyu ve ses kaydını döndürür. latents veya audio_latents geçirildiğinde, ilgili çekim değiştirilir.
• num_inference_steps counts sigma grid points, the terminal 0 included, so it drives one model evaluation less.

Bellek

Dönüştürücü tek başına bfloat16'da 61,7 GB, Qwen3-VL koşullandırıcısı ise 62,1 GB olduğundan, yükleme yöntemi donanıma bağlıdır. Her yapılandırmada en büyük hız kaldıracı daha küçük tuval boyutlarıdır: height ve width değerlerinin yalnızca 32'nin katları olması yeterlidir ve 960x544, eğitimde kullanılan 1344x768'e kıyasla adım başına yaklaşık 2,3 kat daha hızlı çalışır.

Tek bir 80 GB kart üzerinde, bileşenleri ComponentsManager içinde kaydedin ve onları hızlandırıcıya taşımasını sağlayın:

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

Bir tüketici kartında (24 ila 32 GB), iki büyük bileşeni yükleme sırasında int8 olarak kuantize edin ve transformer bloklarını CPU RAM'den akış olarak işleyin. Aşağıdaki her şey yalnızca desteklenen yükleyicileri kullanır, yama gerektirmez ve bfloat16 checkpoint'ten doğrudan çalışır:

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

12 ila 16 GB aralığında, video VAE grubunun da offload edilmiş olduğu (offload_type="leaf_level", stream yok) ve 960x544 gibi küçük bir tuval kullanıldığında aynı yöntem işe yarar. Ağırlıkların host RAM’de barındırılmasını bekleyin: int8’de bunun yaklaşık 75 GB’ı tutar.

İki kartla hiçbir şeyin dışa aktarılmasına gerek yoktur: hattı ikiye bölün ve her yarısını kendi cihazına yerleştirin.

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

İki 80 GB kart bu şekilde tam bfloat16 çalıştırır: her yarısı kendi kartına sığdığı için, bir kez yerleştiğinde hiçbir şey host belleğine geri atılmaz. İki 48 GB kart, yukarıdaki int8 yükleme yöntemini her iki bileşende de uygulayarak aynı şeyi yapar.

Metin ve anahtar kareler

MiniMaxH3Blocks, metinden video ve ses üretimi ile anahtar kare koşullandırmasını kapsar. Bir anahtar kare, videonun başladığı kare (image), bittiği kare (last_image) veya her ikisi olabilir.

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 ve ses birlikte üretilir ve çağrıdan ayrı çıktılar olarak, sampling_rate ile birlikte ses kaydının taşıdığı videos ve audio olarak çıkar; bunların tek bir dosyada birleştirilmesi (muxing) çağrıya bırakılır, örneğin encode_video() ile.

Omni-references

ref2va iş akışı, sıralı bir referans listesine göre koşullanır: en fazla 9 görüntü, 3 video ve 3 ses kliği, toplamda 12 öğe. Sıra semantik niteliktedir. İfadelerdeki referansları etiketler ("<Picture 1>", "<Audio 1>", "<Video 1>") ve paylaşılan ses/video döner saatini ilerletir; bu nedenle aynı referansların yeniden sıralanması farklı bir istek oluşturur.

Yukarıdaki anahtar karelerin aksine, referanslar üretilen geometriyi bağlamaz: kendi çözünürlüklerinde kodlanırlar ve hedef tuval varsayılan olarak MiniMax-H3'ün 16:9 oranını kullanır.

Her modalite için bir referans sınıfı vardır ve her biri, bellek içi medyayı ve medyanın taşıdığı hızı tutar:

Oranlar, her şeyin yeniden örneklenmesinin yapıldığı kaynaktır: kareler, tüm kareleri atarak ve çoğaltarak MiniMax-H3'ün kendi 24 fps'ine; bir dalga formu ise ses VAE'sinin örneklem oranına. MiniMax-H3'ün kendi oranlarındaki medya olduğu gibi akar, bu nedenle yalnızca başka bir oranda üretilen verinin bunu belirtmesi gerekir.

Referans iki yoldan biriyle oluşturulur: sınıfın from_file sınıf metodu ile bir medya dosyasından çözümlenerek ya da isteğin bellekte zaten tuttuğu medyadan doğrudan inşa edilerek — önceki bir neslin geri beslenmesi de bu şekilde gerçekleşir (bkz. Bir nesil olarak referans).

Bloklar asla bir medya dosyası açmaz — bir yolu çözümlemek, kütüphanenin her yerinde olduğu gibi, çağıranın görevidir. Her referans sınıfı bunu from_file sınıf metodu aracılığıyla yapar; bu metot bir yol veya URL alır (video ve ses için PyAV üzerinden) ve konteynerin bildirdiği oranları taşıyan bir referans döndürür — bir video, kare hızını ve ses kaydını da beraberinde getirir. Kare hızını düşüren load_video() yerine from_file tercih edin: gerçek hızı kaybolmuş karelere dayalı olarak oluşturulan bir referans, yanlış hızda koşullandırılır ve hiçbir hata yükseltilmez.

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, ref2va için zorunludur. Referans ses kaydının tam olarak uzunluğunda bir video oluşturmak için bu değeri klipten hesaplayın — round(samples / sample_rate * 24) — ve video VAE'nin çözebileceği bir sonraki 17 * n + 5 değerine yuvarlanır; sonuçta elde edilen süre, MiniMax-H3'ün ürettiği 5 ile 15 saniye aralığında kalmalıdır.

Referans olarak bir nesil

İş akışları tek bir boru hattını paylaştığı için, t2va üretimi doğrudan bir ref2va referansı olarak geri beslenebilir — ve bellek içi yapıcı tam olarak bu devir için tasarlanmıştır. Üretilen medya zaten MiniMax-H3’ün kendi hızlarında olduğundan (kareler 24 fps’de, ses bandı ses VAE’sinin örneklem hızında), referans için hız argümanlarına gerek yoktur ve yolda kayıplı bir kapsayıcı üzerinden yeniden kodlama yapılmaz:

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