# MiniMax-H3

  
    
  

MiniMax-H3는 비디오와 그 사운드를 함께 생성합니다. 단일 transformer가 텍스트 조건부, 조건부 미디어, 그리고 대상 비디오 및 오디오 latents를 포함하는 하나의 packed sequence를 denoise합니다. 별도의 vocoder나 사후 오디오 처리 단계가 없습니다. 비디오와 오디오는 동일한 denoising loop에서 출력됩니다.

원본 MiniMax-H3 체크포인트는 [MiniMaxAI](https://huggingface.co/MiniMaxAI) 조직에서 찾을 수 있습니다.

MiniMax-H3는 [Anima](./anima)와 동일한 방식으로 [Modular Diffusers](../../modular_diffusers/overview) 블록으로만 통합됩니다. 즉, 블록과 해당 [MiniMaxH3ModularPipeline](/docs/diffusers/main/ko/api/pipelines/minimax_h3#diffusers.MiniMaxH3ModularPipeline)이 통합의 전부이며, `DiffusionPipeline` 부분은 존재하지 않습니다.

## Checkpoint 레이아웃

MiniMax-H3는 transformer를 제외한 모든 구성 요소를 공유하는 두 개의 체크포인트 파티션으로 출시되었으므로, diffusers 변환은 이 둘을 모두 **하나의 저장소**에 배치합니다:

| 서브폴더 | 워크플로 |
|---|---|
| `transformer/` | `t2va` (텍스트만), `fl2va` (첫 번째 및/또는 마지막 keyframe) |
| `transformer_ref/` | `ref2va` (이미지, 비디오 및 오디오 참조의 순서화된 혼합) |

Transformer를 제외한 모든 구성 요소, 즉 비디오 VAE, 오디오 VAE, Qwen3-VL conditioner, 해당 tokenizer와 processor, 그리고 두 개의 scheduler는 공유되며 한 번만 저장됩니다.

conditioner는 `Qwen3VLForConditionalGeneration`이며, MiniMax-H3는 마지막 레이어가 아닌 50번째 decoder 레이어 이후의 *unnormalized* hidden state를 읽습니다. 따라서 전체 공개 checkpoint가 사용되지만, 그 language-model head는 사용되지 않습니다.

세 가지 작업 모두 [MiniMaxH3Blocks](/docs/diffusers/main/ko/api/pipelines/minimax_h3#diffusers.MiniMaxH3Blocks)의 워크플로우이며, 저장소에는 각 구성 요소를 자체 로딩 사양과 함께 명시하는 `modular_model_index.json` 하나를 포함합니다. 단일 작업을 서빙하려면 해당 워크플로우를 `from_pretrained`에 전달하세요. 그러면 해당 워크플로우의 블록만 유지되므로, 파이프라인의 시그니처(`pipe.doc`)는 정확히 해당 작업의 입력을 문서화하고, 해당 작업의 구성 요소만 선언되며, `load_components`는 정확히 해당 하위 폴더만 가져옵니다. `t2va` / `fl2va` 파이프라인은 `transformer_ref/`에 절대 접근하지 않으며, `ref2va` 파이프라인은 `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`은 현재 파이프라인이 어떤 입력을 받아 어떤 출력을 반환하는지, 즉 기본값이 포함된 모든 입력, 기대하는 구성 요소, 그리고 생성하는 출력을 보여줍니다. 하나의 워크플로로 축소되어 해당 작업을 정확히 설명하므로, 요청을 보내기 전에 필요한 사항을 파악하는 가장 빠른 방법입니다.

대신 모든 워크플로를 하나의 파이프라인에서 사용하려면 `workflow` 인수를 생략하세요. 그러면 파이프라인은 호출 시 전달된 입력에 따라 워크플로를 선택합니다.

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

*로딩*은 여전히 워크플로우 하나씩 진행될 수 있습니다. 이 호출은 `transformer/`와 모든 공유 컴포넌트를 가져오며, 이는 `t2va`와 `fl2va` 모두에 사용됩니다:

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

`workflow=` 없이 `load_components()`를 호출하면 **두 개의** 61.7GB transformer 파티션을 모두 가져오며, 이를 통해 추가 로딩 호출 없이 하나의 파이프라인이 세 가지 워크플로를 모두 처리할 수 있습니다. [ComponentsManager](/docs/diffusers/main/ko/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager)와 자동 오프로딩을 함께 사용하면, 가중치는 호스트 RAM에 머물러 있고 매니저가 각 단계에 필요한 것만 가속기로 이동시킵니다. 따라서 `ref2va` 디노이저가 디바이스를 필요로 할 때 전략은 충분한 공간을 확보하기 위해 필요한 만큼 오프로딩합니다. 레시피는 [Memory](#memory)를 참고하세요.

## 두 개의 스케줄러

Video와 audio latents는 각 스텝마다 하나의 transformer 호출 내에서 서로 다른 두 개의 스케줄을 따라 진행됩니다. 이 때문에 블록은 두 개의 [MiniMaxH3Scheduler](/docs/diffusers/main/ko/api/schedulers/minimax_h3#diffusers.MiniMaxH3Scheduler) 인스턴스를 기대합니다: video latents용 `scheduler`(발행된 체크포인트에서 `shift=12.0`)과 audio latents용 `audio_scheduler`(`shift=3.0`).

두 transformer 파티션 모두 guidance-distilled이므로 모든 워크플로에 해당합니다. guidance가 가중치에 내장되어 있어 guider, `negative_prompt`, `guidance_scale`이 없으며, 모든 단계에서 정확히 한 번의 forward pass만 실행됩니다.

## 생성 제약

- **24 fps, 5~15초.** `num_frames`은 비디오 VAE가 디코딩할 수 있는 다음 `17 * n + 5` 값으로 반올림되며, 생성된 길이는 해당 범위 내에 있어야 합니다.
- **768픽셀의 짧은 변.** `height`와 `width`의 기본값은 첫 번째 키프레임의 종횡비(없을 경우 16:9)에 따라 MiniMax-H3 자체 캔버스로 설정되며, 32의 배수여야 합니다.
- **하나의 생성기, 세 번의 추출.** 요청은 먼저 키프레임 또는 참조 조건 노이즈를 추출한 다음, 비디오 노이즈, 그리고 오디오 노이즈를 순서대로 전달받은 `generator`에서 추출합니다. 따라서 동일한 생성기 상태에서 두 번 실행하면 동일한 비디오와 사운드가 반환됩니다. `latents` 또는 `audio_latents`를 전달하면 해당 추출을 대체합니다.
- **`num_inference_steps` counts sigma grid points**, the terminal `0` included, so it drives one model evaluation less.

## 메모리

Transformer만 bfloat16에서 61.7 GB이고 Qwen3-VL conditioner가 62.1 GB이므로, 로딩 방식은 하드웨어에 따라 달라집니다. 모든 설정에서 가장 큰 속도 레버는 더 작은 캔버스입니다: `height`와 `width`는 32의 배수만 충족하면 되며, 학습된 1344x768보다 960x544가 스텝당 약 2.3배 빠릅니다.

80 GB 카드 하나에서 [ComponentsManager](/docs/diffusers/main/ko/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager)에 구성 요소를 등록하고, 가속기 위/아래로 이동하도록 설정합니다:

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

소비자용 카드(24~32 GB)에서는 두 개의 대형 구성 요소를 로드할 때 int8로 양자화하고, transformer의 블록을 CPU RAM에서 스트리밍합니다. 아래 모든 내용은 지원되는 로더만 사용하고 패치는 필요 없으며, 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")
```

12~16 GB 환경에서는 비디오 VAE 그룹도 오프로드(`offload_type="leaf_level"`, 스트림 없음)하고 960x544와 같은 작은 캔버스를 사용하면 동일한 레시피가 작동합니다. 가중치가 호스트 RAM에 상주하는 것을 예상하세요. int8 기준 약 75 GB의 RAM이 필요합니다.

카드가 두 장이면 오프로딩할 필요가 없습니다. 파이프라인을 둘로 나누고 각 절반을 각각 다른 디바이스에 배치하세요.

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

80 GB 카드 2장으로 이 방식으로 완전한 bfloat16를 실행할 수 있습니다. 각 절반이 자체 카드에 적합하므로, 한 번 레지던트가 되면 호스트 메모리로 다시 에비트되지 않습니다. 48 GB 카드 2장도 위와 동일한 방식으로 두 구성 요소 모두에 int8 로딩을 적용하여 동일한 결과를 얻을 수 있습니다.

## 텍스트와 키프레임

[MiniMaxH3Blocks](/docs/diffusers/main/ko/api/pipelines/minimax_h3#diffusers.MiniMaxH3Blocks)는 텍스트에서 비디오 및 오디오 생성과 키프레임 조건화를 지원합니다. 키프레임은 비디오가 시작하는 프레임(`image`), 끝나는 프레임(`last_image`), 또는 둘 다를 지정할 수 있습니다.

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

비디오와 오디오는 함께 생성되며, `sampling_rate`를 가진 사운드트랙과 함께 `videos` 및 `audio`라는 별개의 출력으로 호출에서 반환됩니다. 이를 하나의 파일로 muxing하는 작업은 호출자에게 맡겨지며, 예를 들어 [encode_video()](/docs/diffusers/main/ko/api/utilities#diffusers.utils.encode_video)를 사용할 수 있습니다.

## Omni-references

`ref2va` 워크플로우는 정렬된 참조 목록을 조건으로 사용합니다. 최대 9개의 이미지, 3개의 비디오, 3개의 오디오 클립, 총 12개까지 가능합니다. 순서는 의미론적입니다. 프롬프트 제시에서 참조를 라벨링(`"<Picture 1>"`, `"<Audio 1>"`, `"<Video 1>"`)하고 공유 오디오/비디오 로터리 시계를 진행시키므로, 동일한 참조를 다른 순서로 재배치하면 다른 요청이 됩니다.

keyframes와 달리, 참조는 생성된 기하학을 고정하지 않습니다. 참조는 자체 해상도로 인코딩되며, 대상 캔버스는 기본적으로 MiniMax-H3의 16:9 비율을 사용합니다.

모달리티마다 참조 클래스가 하나씩 있으며, 각 클래스는 메모리에 있는 미디어와 해당 미디어가 가지는 비율을 보유합니다:

| 참고 | media | rate가 선언하는 |
| --- | --- | --- |
| [MiniMaxH3ImageReference](/docs/diffusers/main/ko/api/pipelines/minimax_h3#diffusers.modular_pipelines.minimax_h3.MiniMaxH3ImageReference) | `image` | — |
| [MiniMaxH3VideoReference](/docs/diffusers/main/ko/api/pipelines/minimax_h3#diffusers.modular_pipelines.minimax_h3.MiniMaxH3VideoReference) | `frames`, 그리고 자체 사운드트랙을 위한 `audio` | `fps`는 기본값이 MiniMax-H3의 24.0이며, `sample_rate` |
| [MiniMaxH3AudioReference](/docs/diffusers/main/ko/api/pipelines/minimax_h3#diffusers.modular_pipelines.minimax_h3.MiniMaxH3AudioReference) | `audio` | `sample_rate`, 기본값은 오디오 VAE 자체의 |

rates는 모든 것이 리샘플링되는 기준입니다. 프레임은 전체 프레임을 삭제하고 복제하여 MiniMax-H3 자체의 24 fps로, 웨이브폼은 오디오 VAE의 샘플 레이트로 리샘플링됩니다. MiniMax-H3 자체의 레이트로 생성된 미디어는 그대로 통과하므로, 다른 레이트로 생성된 데이터만 이를 명시해야 합니다.

Reference는 두 가지 방식 중 하나로 생성됩니다. 클래스의 `from_file` classmethod를 사용하여 미디어 파일에서 디코딩하거나, 요청이 이미 메모리에 보유하고 있는 미디어에서 직접 구성하는 것입니다. 이전 세대가 피드백으로 입력되는 방식이 바로 이 두 번째 방식입니다(자세한 내용은 [세대를 reference로](#a-generation-as-a-reference) 참조).

블록은 미디어 파일을 절대 열지 않습니다. 경로 디코딩은 라이브러리 전체와 마찬가지로 호출자의 책임입니다. 각 참조 클래스는 `from_file` 클래스 메서드를 통해 이를 수행하며, 이 메서드는 경로 또는 URL(비디오와 오디오는 [PyAV](https://github.com/PyAV-Org/PyAV)를 통해)을 받아 컨테이너가 보고하는 비율을 가진 참조를 반환합니다. 비디오는 프레임 레이트와 사운드를 함께 가져옵니다. 프레임 레이트를 제거하는 [load_video()](/docs/diffusers/main/ko/api/utilities#diffusers.utils.load_video)보다 `from_file`를 사용하는 것이 좋습니다. 실제 레이트가 손실된 프레임으로 구성된 참조는 잘못된 속도로 조건화되며, 어떤 예외도 발생하지 않습니다.

```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`은 `ref2va`에 필수적입니다. 참조 사운드트랙과 정확히 동일한 길이의 영상을 생성하려면 클립에서 계산해야 합니다 — `round(samples / sample_rate * 24)` — 그리고 이 값은 영상 VAE가 디코딩할 수 있는 다음 `17 * n + 5`로 반올림됩니다. 최종 생성되는 길이는 MiniMax-H3가 생성하는 5초에서 15초 사이여야 합니다.

### 참고용 생성

워크플로가 하나의 파이프라인을 공유하므로, `t2va` 생성 결과는 `ref2va` 참조로 바로 전달할 수 있으며, 인메모리 생성자는 정확히 이러한 전달을 위해 설계되었습니다. 생성된 미디어는 이미 MiniMax-H3 자체의 비율(프레임은 24 fps, 사운드트랙은 오디오 VAE의 샘플 레이트)에 맞춰져 있어 참조에 레이트 인자가 필요하지 않으며, 손실 압축 컨테이너를 통해 재인코딩되는 과정도 없습니다:

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

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/minimax_h3/modular_pipeline.py#L150)

MiniMax-H3의 비디오 + 오디오 결합 생성을 위한 ModularPipeline: `transformer/` 체크포인트 파티션에 대한 `t2va`(텍스트 전용) 및 `fl2va`(첫 번째 및/또는 마지막 키프레임) 워크플로, 그리고 `transformer_ref/`에 대한 `ref2va`(오미-리퍼런스) 워크플로입니다. 하나의 저장소에 두 파티션이 모두 포함되어 있으며, 워크플로를 선택하면 해당

own:

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

MiniMax-H3은 텍스트 조건부, 키프레임 조건부 잠재 변수, 오디오 잠재 변수, 비디오 잠재 변수를 모두 포함하는 **하나의 패킹된 시퀀스**를 노이즈 제거합니다. 이 때문에 블록들은 모달리티별 텐서 대신 행 레이아웃을 전달하며, 파이프라인은 단일 트랜스포머 호출 내에서 단계가 진행되는 두 개의 스케줄러(`shift = 12.0`는 비디오용, `shift = 3.0`는 오디오용)를 포함합니다.

체크포인트는 guidance-distilled입니다. guidance가 가중치에 이미 반영되어 있으므로 guider, `negative_prompt`, `guidance_scale`이 없으며, 모든 단계에서 정확히 한 번의 forward pass만 실행됩니다.

MiniMax-H3는 모듈식만 지원합니다. 이 파이프라인과 그 블록들이 통합의 전부이며, `DiffusionPipeline`의 일부는 존재하지 않습니다. 이 모듈은 모든 블록이 참조하는 모델 정보를 담고 있습니다. 설정에서 파생된 기하학적 구조는 프로퍼티로, 캔버스와 프레임 수 계산은 함수로 제공되며, 조건부 설정, 인코딩 및 노이즈 계약은 블록 자체에 정의되어 있습니다.

```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()
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/minimax_h3/modular_blocks_minimax_h3.py#L659)

MiniMax-H3를 활용한 영상 + 오디오 결합 생성을 위한 Auto Modular 파이프라인 블록: `references` 및 keyframe 입력에 따라 선택되는 `t2va` (텍스트 전용), `fl2va` (첫 번째 및/또는 마지막 keyframe), `ref2va` (omni-reference) 워크플로우입니다. `workflow=`를 지정하지 않으면 컴포넌트를 로드할 때 61.7GB transformer 파티션 **둘 다**가 로드되므로, 작업에 필요한 것만 로드하려면 하나를 전달하세요.

지원되는 워크플로:
- `t2va`: `prompt` 필수
- `fl2va`: `prompt`, `image` 또는 `prompt`, `last_image`가 필요합니다
- `ref2va`: `prompt`, `references` 필수

구성 요소: 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`)

Configs: canvas_short_edge (기본값: 768) canvas_max_pixels (기본값: 1032192) reference_image_short_edge (기본값: 2048)

Inputs: references (`list`, *선택 사항*): 조건으로 사용할 참조 자료입니다. **모델이 읽어야 할 순서대로** 제공해야 합니다. 순서는 프롬프트 제시 시 라벨을 지정하고 공유 회전 시계(rotary clock)에 배치하는 기준이 되므로, 순서가 다르면 다른 요청으로 처리됩니다. 각 모달리티당 하나의 dataclass를 사용하며, 모두 메모리 내 미디어를 포함합니다. `MiniMaxH3ImageReference`(최대 9개), 자체 `fps`를 가진 `MiniMaxH3VideoReference`(최대 3개, `audio` 사운드트랙도 조건으로 사용됨), 또는 자체 `sample_rate`를 가진 `MiniMaxH3AudioReference`(최대 3개)입니다. 참조 자료는 최대 12개까지 가능하며, 오디오 참조 자료만 단독으로 사용할 수 없습니다. 이러한 블록은 미디어 파일을 열지 않습니다. 각 클래스의 `from_file` 클래스 메서드를 사용하여 디코딩하면 샘플링 속도가 함께 가져와집니다. height (`int`, *선택 사항*): 생성될 비디오의 픽셀 단위 높이로, 32의 배수여야 합니다. width (`int`, *선택 사항*): 생성될 비디오의 픽셀 단위 너비로, 32의 배수여야 합니다. num_frames (`int`, *선택 사항*): 고정된 24 fps에서 생성할 프레임 수입니다. 비디오 VAE가 디코딩할 수 있는 다음 `17 * n + 5` 값으로 올림 처리되며, 결과 지속 시간은 5초에서 15초 사이여야 합니다. 참조 사운드트랙과 동일한 길이의 비디오를 생성하려면 `round(samples / sample_rate * 24)`를 전달하세요. image (`Image`, *선택 사항*): 비디오가 시작하는 키프레임입니다. *신장(stretched)*되어 대상 캔버스에 배치되며, 대상 캔버스는 기본적으로 해당 이미지의 자체 종횡비에서 파생됩니다. last_image (`Image`, *선택 사항*): 비디오가 끝나는 키프레임입니다. 단독으로 전달하여 *해당 프레임까지* 생성할 수 있습니다. `image`와 함께 전달되면 두 개 중 후속(follower)으로 처리되며, 캔버스에 커버 크롭(cover-cropped)됩니다. prompt (`str`): 생성을 안내하는 프롬프트로, 단일 문자열입니다. normalized_references (`list`, *선택 사항*): 설정 단계에서 정규화된 참조 자료로, 패킹된 순서대로 나열됩니다. keyframes (`list`, *선택 사항*): 대상 캔버스에 배치된 키프레임으로, 패킹된 순서대로 나열됩니다. condition_latents (`list`, *선택 사항*): 인코딩된 비디오 조건 latents로, 패킹된 순서대로 이미지 및 비디오 참조 자료마다 하나씩 포함됩니다. 이들의 shape은 모든 참조 블록의 기하학적 구조를 결정합니다. audio_condition_latents (`list`, *선택 사항*): 인코딩된 오디오 조건 행(row)으로, 패킹된 순서대로 오디오를 포함하는 참조 자료마다 하나씩 포함됩니다. generator (`Generator`, *선택 사항*): 요청의 generator입니다. 조건 노이즈가 먼저 추출되며, 조건마다 한 번씩 추출된 후 생성될 행의 노이즈가 추출됩니다. latents (`Tensor`): `(1, 24, num_latent_frames, latent_height, latent_width)` shape의 사전 생성된 비디오 노이즈로, 추출 대신 사용됩니다. audio_latents (`Tensor`): `(2, 32, num_audio_latents)` shape의 사전 생성된 오디오 노이즈입니다. num_inference_steps (`int`, *선택 사항*, 기본값 50): 디노이징 단계 수입니다. **denoiser_input_fields (`None`, *선택 사항*): transformer가 이름으로 읽는 패킹된 시퀀스의 구조적 설명입니다: `token_tags`, `position_ids` 및 세 개의 행 인덱스 텐서. attention_kwargs (`dict`, *선택 사항*): attention 프로세서용 추가 kwargs입니다. keyframe_anchors (`tuple`, *선택 사항*, 기본값 ()): 패킹된 순서대로 각 키프레임이 비디오의 어느 끝에 앵커링되는지를 나타냅니다. output_type (`str`, *선택 사항*, 기본값 pil): 출력 형식: 'pil', 'np' 또는 'pt'.

Outputs: videos (`list`): 생성된 비디오. audio (`Tensor`): `(1, 2, num_samples)` 모양의 생성된 사운드트랙. sampling_rate (`int`): 생성된 사운드트랙의 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])
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/minimax_h3/references.py#L82)

**매개변수:**

image (`PIL.Image.Image`, `np.ndarray` 또는 `torch.Tensor`) : 참조 이미지: 이미지, `(height, width, 3)` 배열 또는 `(3, height, width)` 텐서, `uint8` 또는 `[0, 1]` 범위의 부동소수점. 생성된 기하 구조에 절대 바인딩되지 않으며, 요청이 생성하는 캔버스와 무관하게 자체의 짧은 변(발행된 체크포인트의 경우 2048) 기준으로 인코딩됩니다.

주제, 스타일 또는 장면 참조: 요청당 최대 9개.

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

```python
from_file(media)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/minimax_h3/references.py#L98)

**매개변수:**

media (`str` 또는 `os.PathLike`) : 이미지의 경로 또는 URL.

`MiniMaxH3ImageReference`에 [load_image()](/docs/diffusers/main/ko/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)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/minimax_h3/references.py#L110)

**매개변수:**

frames (`list[PIL.Image.Image]`, `np.ndarray` 또는 `torch.Tensor`) : 기준 프레임: 이미지 목록, `(num_frames, height, width, 3)` 배열 또는 `(num_frames, 3, height, width)` 텐서, `uint8` 또는 `[0, 1]` 범위의 부동 소수점.

fps (`float`, *선택 사항*, 기본값 24.0) : `frames`가 가지는 프레임 레이트입니다. 이 값이 레퍼런스의 비전 블록을 컨디셔너의 2 fps 그리드에 배치하는 기준이 됩니다. MiniMax-H3 자체의 클록은 24 fps이므로, 다른 프레임 레이트의 경우 전체 프레임을 삭제하고 복제하여 24 fps로 리샘플링됩니다. 따라서 프레임이 파일에서 가져온 경우 이 필드를 올바르게 설정하는 것이 중요합니다.

audio (`torch.Tensor`, shape `(channels, num_samples)`, *선택 사항*) : 이 비디오의 사운드트랙입니다. 모노 또는 스테레오 형식이며, 참조 대상의 고유한 사운드트랙으로 조건화됩니다. 생략하면 참조는 움직임만으로 조건화됩니다.

sample_rate (`int`, *선택 사항*) : `audio`가 샘플을 처리하는 비율입니다. 이 값을 지정하지 않으면 오디오 VAE 자체의 비율을 사용하여 샘플이 그대로 유지되며, 다른 비율을 지정하면 해당 비율로 리샘플링됩니다.

모션 및 카메라 참조: 요청당 최대 3개까지 가능하며, 각 참조는 자체 사운드트랙과 함께 조건부로 사용됩니다.

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

```python
from_file(media)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/minimax_h3/references.py#L146)

**매개변수:**

media (`str` 또는 `os.PathLike`) : 비디오의 경로 또는 URL.

**반환값:** `MiniMaxH3VideoReference`

컨테이너가 보고하는 프레임 레이트로 `(num_frames, height, width, 3)` `uint8` 프레임들을 반환하며, 오디오 스트림이 있는 경우 해당 사운드트랙과 그 사운드트랙의 샘플 레이트도 함께 포함합니다.

`MiniMaxH3VideoReference`로 비디오 파일을 디코딩합니다. 이때 해당 비디오가 가진 해상도, 프레임 레이트, 사운드트랙을 그대로 유지합니다.

속도는 reference에 기록됩니다. [load_video()](/docs/diffusers/main/ko/api/utilities#diffusers.utils.load_video) 대신 이 방식으로 디코딩하는 이유가 바로 여기에 있습니다. MiniMax-H3는 reference를 자체 24 fps로 리샘플링하므로, 입력 과정에서 손실된 프레임 레이트는 잘못된 속도로 조건부 설정된 요청이 되며, 이를 알리는 어떠한 신호도 없습니다. 메타데이터가 잘못된 컨테이너의 경우, 반환된 reference에서 `fps` 또는 `sample_rate`를 오버라이드하여 수정할 수 있습니다.

[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)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/minimax_h3/references.py#L172)

**매개변수:**

audio (`torch.Tensor`, shape `(channels, num_samples)`) : 기준 웨이브폼, 모노 또는 스테레오.

sample_rate (`int`, *선택 사항*) : `audio`가 샘플을 처리하는 비율입니다. 이 값을 지정하지 않으면 오디오 VAE 자체의 비율을 사용하여 샘플이 그대로 유지되며, 다른 비율을 지정하면 해당 비율로 리샘플링됩니다.

음성 또는 음악 참조: 요청당 최대 3개이며, 단독으로 사용할 수 없습니다. 오디오 참조는 최소 하나의 이미지 또는 비디오 참조와 함께 사용해야 합니다. conditioner에는 전달되지 않으며, 오디오 VAE에 의해만 인코딩됩니다.

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

```python
from_file(media)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/minimax_h3/references.py#L191)

**매개변수:**

media (`str` 또는 `os.PathLike`) : 오디오의 경로 또는 URL, 또는 사운드트랙이 추출될 비디오의 경로 또는 URL.

**반환값:** `MiniMaxH3AudioReference`

컨테이너가 보고하는 샘플 레이트의 `(channels, num_samples)` float32 웨이브폼

`MiniMaxH3AudioReference`로 오디오 파일을 해당 파일이 포함하는 샘플 레이트로 디코딩합니다.

[PyAV](https://github.com/PyAV-Org/PyAV)가 필요합니다.