# 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](https://huggingface.co/MiniMaxAI).

MiniMax-H3 terintegrasi hanya sebagai blok [Modular Diffusers](../../modular_diffusers/overview), sama seperti [Anima](./anima): blok-blok tersebut beserta [MiniMaxH3ModularPipeline](/docs/diffusers/v0.43.0/id/api/pipelines/minimax_h3#diffusers.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**:

| Subfolder | Alur Kerja |
|---|---|
| `transformer/` | `t2va` (teks saja), `fl2va` (keyframe pertama dan/atau terakhir) |
| `transformer_ref/` | `ref2va` (campuran terurut dari referensi gambar, video, dan audio) |

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](/docs/diffusers/v0.43.0/id/api/pipelines/minimax_h3#diffusers.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/`.

```py
import torch
from diffusers import ModularPipeline

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

> [!TIP]
> `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.

```py
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`:

```py
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](/docs/diffusers/v0.43.0/id/api/modular_diffusers/pipeline_components#diffusers.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](#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](/docs/diffusers/v0.43.0/id/api/schedulers/minimax_h3#diffusers.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](/docs/diffusers/v0.43.0/id/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager) dan biarkan memindahkannya ke dan dari akselerator:

```py
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:

```py
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.

```py
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](/docs/diffusers/v0.43.0/id/api/pipelines/minimax_h3#diffusers.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.

```py
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()](/docs/diffusers/v0.43.0/id/api/utilities#diffusers.utils.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:

| referensi | media | laju yang ia deklarasikan |
| --- | --- | --- |
| [MiniMaxH3ImageReference](/docs/diffusers/v0.43.0/id/api/pipelines/minimax_h3#diffusers.modular_pipelines.minimax_h3.MiniMaxH3ImageReference) | `image` | — |
| [MiniMaxH3VideoReference](/docs/diffusers/v0.43.0/id/api/pipelines/minimax_h3#diffusers.modular_pipelines.minimax_h3.MiniMaxH3VideoReference) | `frames`, dan `audio` untuk soundtrack-nya | `fps`, secara default 24.0 dari MiniMax-H3, dan `sample_rate` |
| [MiniMaxH3AudioReference](/docs/diffusers/v0.43.0/id/api/pipelines/minimax_h3#diffusers.modular_pipelines.minimax_h3.MiniMaxH3AudioReference) | `audio` | `sample_rate`, secara default mengikuti |

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](#a-generation-as-a-reference)).

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](https://github.com/PyAV-Org/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()](/docs/diffusers/v0.43.0/id/api/utilities#diffusers.utils.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.

```py
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:

```py
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[[diffusers.MiniMaxH3ModularPipeline]]

#### diffusers.MiniMaxH3ModularPipeline[[diffusers.MiniMaxH3ModularPipeline]]

```python
diffusers.MiniMaxH3ModularPipeline(blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = None, pretrained_model_name_or_path: str | os.PathLike | None = None, components_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = None, collection: str | None = None, workflow: str | None = None, modular_config_dict: dict[str, typing.Any] | None = None, config_dict: dict[str, typing.Any] | None = None, **kwargs)
```

[Sumber](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/minimax_h3/modular_pipeline.py#L150)

ModularPipeline untuk generasi video + audio bersama dengan MiniMax-H3: alur kerja `t2va` (hanya teks) dan `fl2va` (keyframe pertama dan/atau terakhir) terhadap partisi checkpoint `transformer/`, serta alur kerja `ref2va` (omni-reference) terhadap `transformer_ref/`. Satu repositori menyimpan kedua partisi, dan memilih alur kerja hanya memuat

milik:

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

MiniMax-H3 melakukan denoising pada **satu sequence yang dikemas** yang sekaligus menyimpan kondisi teks, latens kondisi keyframe, latens audio, dan latens video, itulah mengapa blok-bloknya meneruskan tata letak baris alih-alih tensor per-modalitas, dan mengapa pipeline membawa dua scheduler (`shift = 12.0` untuk video, `shift = 3.0` untuk audio) yang di-step di dalam satu panggilan transformer.

Checkpoint ini telah melalui distilasi panduan: panduan telah diintegrasikan ke dalam bobot, sehingga tidak ada guider, tidak ada `negative_prompt` dan tidak ada `guidance_scale`, serta setiap langkah hanya menjalankan satu forward pass.

MiniMax-H3 bersifat modular saja: pipeline ini beserta blok-bloknya merupakan seluruh integrasi, tidak ada bagian `DiffusionPipeline`. Modul ini membawa fakta-fakta model yang menjadi acuan setiap blok — geometri yang diturunkan dari config sebagai properti, serta aritmetika kanvas dan jumlah frame sebagai fungsi — sementara kontrak conditioning, encoding, dan noise berada pada blok-blok itu sendiri.

```py
import torch
from diffusers import ModularPipeline

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

## MiniMaxH3Blocks[[diffusers.MiniMaxH3Blocks]]

#### diffusers.MiniMaxH3Blocks[[diffusers.MiniMaxH3Blocks]]

```python
diffusers.MiniMaxH3Blocks()
```

[Sumber](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py#L659)

Auto Modular pipeline blocks untuk generasi video + audio bersama dengan MiniMax-H3: alur kerja `t2va` (teks saja), `fl2va` (keyframe pertama dan/atau terakhir), serta `ref2va` (omni-reference), yang dipilih berdasarkan input `references` dan keyframe. Tanpa `workflow=`, memuat komponen akan menarik **kedua** partisi transformer berukuran 61,7GB — berikan salah satunya untuk hanya memuat apa yang dibutuhkan tugas.

Alur kerja yang didukung:
- `t2va`: membutuhkan `prompt`
- `fl2va`: membutuhkan `prompt`, `image` atau `prompt`, `last_image`
- `ref2va`: membutuhkan `prompt`, `references`

Komponen: image_processor (`VaeImageProcessor`) text_encoder (`Qwen3VLForConditionalGeneration`) tokenizer (`Qwen2Tokenizer`) processor (`Qwen3VLProcessor`) vae (`AutoencoderKLMiniMaxH3`) audio_vae (`AutoencoderKLMiniMaxH3Audio`) scheduler (`MiniMaxH3Scheduler`) audio_scheduler (`MiniMaxH3Scheduler`) transformer_ref (`MiniMaxH3Transformer3DModel`) transformer (`MiniMaxH3Transformer3DModel`) video_processor (`VideoProcessor`)

Konfigurasi: canvas_short_edge (default: 768) canvas_max_pixels (default: 1032192) reference_image_short_edge (default: 2048)

Inputs: references (`list`, *optional*): The references to condition on, **in the order the model should read them**: the order labels them in the prompt presentation and lays them out on the shared rotary clock, so a different order is a different request. One dataclass per modality, all holding in-memory media — a `MiniMaxH3ImageReference` (at most 9), a `MiniMaxH3VideoReference` at its own `fps` (at most 3, whose `audio` soundtrack is conditioned on as well), or a `MiniMaxH3AudioReference` at its own `sample_rate` (at most 3) — for at most 12 references in total, and audio references cannot be the only ones. These blocks never open a media file: decode with each class's `from_file` classmethod, which brings the rates along. height (`int`, *optional*): Height of the generated video in pixels, a multiple of 32. width (`int`, *optional*): Width of the generated video in pixels, a multiple of 32. num_frames (`int`, *optional*): Number of frames to generate, at the fixed 24 fps. Snapped up to the next `17 * n + 5` the video VAE can decode; the resulting duration must stay between 5 and 15 seconds. To generate a video as long as a reference soundtrack, pass `round(samples / sample_rate * 24)`. image (`Image`, *optional*): Keyframe the video starts from. It is *stretched* onto the target canvas, which by default is derived from its own aspect ratio. last_image (`Image`, *optional*): Keyframe the video ends on. Can be passed on its own to generate *up to* a frame. Combined with `image` it is the follower of the two and is cover-cropped onto the canvas. prompt (`str`): The prompt to guide generation, a single string. normalized_references (`list`, *optional*): The references normalized by the setup step, in packed order. keyframes (`list`, *optional*): The keyframes put onto the target canvas, in packed order. condition_latents (`list`, *optional*): The encoded video conditioning latents, one per image and video reference in packed order. Their shape is where every reference block's geometry comes from. audio_condition_latents (`list`, *optional*): The encoded audio conditioning rows, one per audio-bearing reference in packed order. generator (`Generator`, *optional*): The generator of the request. The conditioning noise is drawn from it first, one draw per condition, before the noise of the generated rows. latents (`Tensor`): Pre-generated video noise of shape `(1, 24, num_latent_frames, latent_height, latent_width)`, used instead of the draw. audio_latents (`Tensor`): Pre-generated audio noise of shape `(2, 32, num_audio_latents)`. num_inference_steps (`int`, *optional*, defaults to 50): The number of denoising steps. **denoiser_input_fields (`None`, *optional*): The structural description of the packed sequence the transformer reads by name: `token_tags`, `position_ids` and the three row-index tensors. attention_kwargs (`dict`, *optional*): Additional kwargs for attention processors. keyframe_anchors (`tuple`, *optional*, defaults to ()): Which end of the video every keyframe is anchored to, in packed order. output_type (`str`, *optional*, defaults to pil): Output format: 'pil', 'np' or 'pt'.

Output: video (`list`): Video yang dihasilkan. audio (`Tensor`): Soundtrack yang dihasilkan, dengan bentuk `(1, 2, num_samples)`. sampling_rate (`int`): Laju sampel soundtrack yang dihasilkan dalam Hz.

## MiniMaxH3ImageReference[[diffusers.modular_pipelines.minimax_h3.MiniMaxH3ImageReference]]

#### diffusers.modular_pipelines.minimax_h3.MiniMaxH3ImageReference[[diffusers.modular_pipelines.minimax_h3.MiniMaxH3ImageReference]]

```python
diffusers.modular_pipelines.minimax_h3.MiniMaxH3ImageReference(image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor])
```

[Sumber](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/minimax_h3/references.py#L82)

**Parameter:**

image (`PIL.Image.Image`, `np.ndarray` atau `torch.Tensor`) : Gambar referensi: sebuah gambar, array `(height, width, 3)` atau tensor `(3, height, width)`, `uint8` atau floating point pada `[0, 1]`. Gambar ini tidak pernah mengikat geometri yang dihasilkan — ia di-encode pada sisi pendeknya sendiri, 2048 untuk checkpoint yang dirilis, apa pun kanvas yang dihasilkan oleh permintaan.

Referensi subjek, gaya, atau adegan: maksimal 9 per permintaan.

#### from_file[[diffusers.modular_pipelines.minimax_h3.MiniMaxH3ImageReference.from_file]]

```python
from_file(media)
```

[Sumber](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/minimax_h3/references.py#L98)

**Parameter:**

media (`str` atau `os.PathLike`) : Path atau URL dari gambar.

Muat file gambar ke dalam `MiniMaxH3ImageReference`, melalui [load_image()](/docs/diffusers/v0.43.0/id/api/utilities#diffusers.utils.load_image).

## MiniMaxH3VideoReference[[diffusers.modular_pipelines.minimax_h3.MiniMaxH3VideoReference]]

#### diffusers.modular_pipelines.minimax_h3.MiniMaxH3VideoReference[[diffusers.modular_pipelines.minimax_h3.MiniMaxH3VideoReference]]

```python
diffusers.modular_pipelines.minimax_h3.MiniMaxH3VideoReference(frames: typing.Union[list[PIL.Image.Image], numpy.ndarray, torch.Tensor], fps: float | None = None, audio: typing.Optional[torch.Tensor] = None, sample_rate: int | None = None)
```

[Sumber](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/minimax_h3/references.py#L110)

**Parameter:**

frames (`list[PIL.Image.Image]`, `np.ndarray` atau `torch.Tensor`) : Bingkai referensi: daftar gambar, array `(num_frames, height, width, 3)` atau tensor `(num_frames, 3, height, width)`, `uint8` atau floating point di `[0, 1]`.

fps (`float`, *opsional*, default 24.0) : Laju frame yang dibawa oleh `frames`, yang menentukan penempatan blok visual referensi pada grid 2 fps kondisioner. Jam internal MiniMax-H3 sendiri adalah 24 fps, sehingga laju lain akan disampel ulang ke laju tersebut dengan membuang dan menduplikasi frame utuh — hal ini menjadikan parameter ini yang harus diatur dengan benar jika frame berasal dari file.

audio (`torch.Tensor` dengan bentuk `(channels, num_samples)`, *opsional*) : Soundtrack video ini, mono atau stereo, yang dikondisikan sebagai milik referensi itu sendiri, bukan sebagai referensi dari miliknya. Jika diabaikan, referensi hanya dikondisikan berdasarkan gerakan.

sample_rate (`int`, *opsional*) : Laju di mana `audio` membawa sampelnya. Jika dibiarkan kosong, lajunya adalah laju bawaan VAE audio, yang membuat sampel tetap tidak berubah; laju lain akan di-resample ke laju tersebut.

Referensi gerakan dan kamera: maksimal 3 per permintaan, dikondisikan bersama dengan soundtrack-nya sendiri.

#### from_file[[diffusers.modular_pipelines.minimax_h3.MiniMaxH3VideoReference.from_file]]

```python
from_file(media)
```

[Sumber](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/minimax_h3/references.py#L146)

**Parameter:**

media (`str` atau `os.PathLike`) : Path atau URL dari video.

**Mengembalikan:** `MiniMaxH3VideoReference`

frame `(num_frames, height, width, 3)` `uint8` pada laju frame yang dilaporkan oleh kontainer, membawa soundtrack-nya dan laju sampel soundtrack tersebut ketika memiliki stream audio.

Decode file video menjadi `MiniMaxH3VideoReference`, pada resolusi, frame rate, dan soundtrack yang dibawanya.

Laju tersebut mendarat pada referensi, yang merupakan inti dari proses decoding dengan cara ini alih-alih menggunakan [load_video()](/docs/diffusers/v0.43.0/id/api/utilities#diffusers.utils.load_video): MiniMax-H3 melakukan resampling referensi ke 24 fps miliknya sendiri, sehingga laju frame yang hilang saat input adalah permintaan yang dikondisikan pada kecepatan yang salah, tanpa ada mekanisme untuk memperingatkannya. Kontainer yang metadatanya salah dikoreksi dengan menimpa `fps` atau `sample_rate` pada referensi yang dikembalikan.

Memerlukan [PyAV](https://github.com/PyAV-Org/PyAV).

## MiniMaxH3AudioReference[[diffusers.modular_pipelines.minimax_h3.MiniMaxH3AudioReference]]

#### diffusers.modular_pipelines.minimax_h3.MiniMaxH3AudioReference[[diffusers.modular_pipelines.minimax_h3.MiniMaxH3AudioReference]]

```python
diffusers.modular_pipelines.minimax_h3.MiniMaxH3AudioReference(audio: Tensor, sample_rate: int | None = None)
```

[Sumber](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/minimax_h3/references.py#L172)

**Parameter:**

audio (`torch.Tensor` dengan bentuk `(channels, num_samples)`) : Gelombang referensi, mono atau stereo.

sample_rate (`int`, *opsional*) : Laju di mana `audio` membawa sampelnya. Jika dibiarkan kosong, lajunya adalah laju bawaan VAE audio, yang membuat sampel tetap tidak berubah; laju lain akan di-resample ke laju tersebut.

Referensi suara atau musik: maksimal 3 per permintaan, dan tidak boleh berdiri sendiri — referensi audio harus dipasangkan dengan setidaknya satu referensi gambar atau video. Referensi ini tidak pernah mencapai conditioner dan hanya dienkod oleh audio VAE.

#### from_file[[diffusers.modular_pipelines.minimax_h3.MiniMaxH3AudioReference.from_file]]

```python
from_file(media)
```

[Sumber](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/minimax_h3/references.py#L191)

**Parameter:**

media (`str` atau `os.PathLike`) : Path atau URL dari audio, atau dari video yang soundtrack-nya diambil.

**Mengembalikan:** `MiniMaxH3AudioReference`

waveform float32 `(channels, num_samples)` pada laju sampel yang dilaporkan oleh kontainer.

Decode file audio menjadi `MiniMaxH3AudioReference`, pada sample rate yang dibawanya.

Memerlukan [PyAV](https://github.com/PyAV-Org/PyAV).