# MiniMax-H3

  
    
  

MiniMax-H3 gera o vídeo e sua trilha sonora juntos. Um único transformer remove o ruído de uma sequência empacotada que contém a condição de texto, a mídia de condicionamento e os latentes de vídeo e áudio de destino. Não há um vocoder separado nem uma etapa posterior de áudio: o vídeo e o áudio saem do mesmo loop de remoção de ruído.

Você pode encontrar os checkpoints originais do MiniMax-H3 na organização [MiniMaxAI](https://huggingface.co/MiniMaxAI).

MiniMax-H3 é integrado apenas como blocos de [Modular Diffusers](../../modular_diffusers/overview), da mesma forma que o [Anima](./anima): os blocos e seu [MiniMaxH3ModularPipeline](/docs/diffusers/main/pt/api/pipelines/minimax_h3#diffusers.MiniMaxH3ModularPipeline) constituem toda a integração, e não há uma metade `DiffusionPipeline`.

## Layout do checkpoint

O MiniMax-H3 foi lançado como duas partições de checkpoint que compartilham todos os componentes, exceto o transformer, portanto, a conversão do diffusers coloca ambos em **um único repositório**:

| Subpasta | Fluxos de trabalho |
|---|---|
| `transformer/` | `t2va` (apenas texto), `fl2va` (primeiro e/ou último quadro-chave) |
| `transformer_ref/` | `ref2va` (uma mistura ordenada de referências de imagem, vídeo e áudio) |

Tudo, exceto o transformer, ou seja, o VAE de vídeo, o VAE de áudio, o condicionador Qwen3-VL, seu tokenizer e processor, e os dois schedulers, é compartilhado e armazenado uma única vez.

O condicionador é um `Qwen3VLForConditionalGeneration`, e o MiniMax-H3 lê o estado oculto *não normalizado* após sua 50ª camada decodificadora, em vez da última, de modo que o checkpoint completo liberado é utilizado com sua cabeça de modelo de linguagem não utilizada.

As três tarefas são fluxos de trabalho do [MiniMaxH3Blocks](/docs/diffusers/main/pt/api/pipelines/minimax_h3#diffusers.MiniMaxH3Blocks), e o repositório contém um `modular_model_index.json` que nomeia cada componente com sua própria especificação de carregamento. Para servir uma única tarefa, passe o fluxo de trabalho para `from_pretrained`: ele mantém apenas os blocos desse fluxo de trabalho, de modo que a assinatura do pipeline (`pipe.doc`) documenta exatamente as entradas dessa tarefa, apenas os componentes dessa tarefa são declarados e `load_components` busca exatamente seus subdiretórios — um pipeline `t2va` / `fl2va` nunca acessa `transformer_ref/`, e um pipeline `ref2va` nunca acessa `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` exibe o que o pipeline à sua frente recebe e retorna — cada entrada com seu valor padrão, os componentes que ele espera e as saídas que produz. Reduzido a um único fluxo de trabalho, ele descreve exatamente aquela tarefa, o que é a maneira mais rápida de ver o que uma solicitação precisa antes de fazê-la.

Para manter todos os fluxos de trabalho disponíveis em um único pipeline, deixe o argumento `workflow` de fora: o pipeline então seleciona o fluxo de trabalho a cada chamada com base nas entradas que recebe.

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

O *carregamento* ainda pode ser feito um fluxo de trabalho por vez. Esta chamada única busca `transformer/` e todos os componentes compartilhados, que atendem tanto ao `t2va` quanto ao `fl2va`:

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

Um `load_components()` simples, sem `workflow=`, carrega **ambas** as partições de 61,7 GB do transformer, o que permite que um único pipeline atenda aos três fluxos de trabalho sem uma nova chamada de carregamento. Combine-o com um [ComponentsManager](/docs/diffusers/main/pt/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager) e offloading automático: os pesos ficam na RAM do host e o gerente move para o acelerador apenas o que cada etapa precisa, de modo que, quando o denoiser `ref2va` precisa do dispositivo, a estratégia faz o offloading do que for necessário para liberar espaço suficiente. Veja [Memória](#memory) para as receitas.

## Dois agendadores

Os latentes de vídeo e de áudio seguem dois agendamentos diferentes dentro de uma única chamada do transformer por passo, motivo pelo qual os blocos esperam duas instâncias de [MiniMaxH3Scheduler](/docs/diffusers/main/pt/api/schedulers/minimax_h3#diffusers.MiniMaxH3Scheduler): `scheduler` para os latentes de vídeo (`shift=12.0` nos checkpoints liberados) e `audio_scheduler` para os latentes de áudio (`shift=3.0`).

Ambas as partições do transformer são destiladas por orientação, portanto isso vale para todos os fluxos de trabalho: a orientação está incorporada nos pesos, não há um guia, nem `negative_prompt` e nem `guidance_scale`, e cada etapa executa exatamente uma passagem de frente.

## Restrições de geração

- **24 fps, de 5 a 15 segundos.** `num_frames` é arredondado para cima para o próximo `17 * n + 5` que o VAE de vídeo pode decodificar, e a duração resultante deve permanecer nessa janela.
- **Uma borda curta de 768 pixels.** `height` e `width` padrão para o próprio canvas do MiniMax-H3 para a proporção de aspecto do primeiro keyframe (ou 16:9 sem um) e devem ser múltiplos de 32.
- **Um gerador, três extrações.** Uma solicitação extrai primeiro o ruído de condicionamento do keyframe ou de referência, depois o ruído do vídeo e, por fim, o ruído do áudio, todos a partir do `generator` que é passado, de modo que duas execuções a partir do mesmo estado do gerador retornam o mesmo vídeo e trilha sonora. Passar `latents` ou `audio_latents` substitui a extração correspondente.
- **`num_inference_steps` conta os pontos da grade de sigma**, incluindo o terminal `0`, portanto, ele resulta em uma avaliação a menos do modelo.

## Memória

O transformer sozinho ocupa 61,7 GB em bfloat16 e o conditioner do Qwen3-VL ocupa mais 62,1 GB, portanto a receita de carregamento depende do hardware. Canvas menores são o principal fator de velocidade em qualquer configuração: `height` e `width` precisam apenas ser múltiplos de 32, e 960x544 executa cerca de 2,3x mais rápido por passo do que o 1344x768 treinado.

Em um cartão de 80 GB, registre os componentes em um [ComponentsManager](/docs/diffusers/main/pt/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager) e deixe que ele os mova para dentro e para fora do acelerador:

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

Em um cartão de consumo (24 a 32 GB), quantize os dois componentes grandes para int8 conforme eles são carregados e transmita os blocos do transformer a partir da RAM da CPU. Tudo abaixo usa apenas carregadores suportados, sem patches, e funciona diretamente do 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")
```

Com 12 a 16 GB, a mesma receita funciona com o grupo do VAE de vídeo também descarregado (`offload_type="leaf_level"`, sem stream) e um canvas pequeno, como 960x544. Espere que os pesos fiquem na RAM do host: cerca de 75 GB em int8.

Com duas placas, nada precisa ser descarregado: divida o pipeline em duas partes e coloque cada metade em seu próprio dispositivo.

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

Duas placas de 80 GB executam o bfloat16 completo dessa forma: cada metade cabe em sua própria placa, portanto nada é removido para a memória do host uma vez que esteja residente. Duas placas de 48 GB fazem o mesmo com o carregamento int8 acima em ambos os componentes.

## Texto e keyframes

[MiniMaxH3Blocks](/docs/diffusers/main/pt/api/pipelines/minimax_h3#diffusers.MiniMaxH3Blocks) cobre texto para vídeo e áudio e condicionamento por quadro-chave. Um quadro-chave pode ser o quadro a partir do qual o vídeo começa (`image`), o quadro em que termina (`last_image`) ou ambos.

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

Vídeo e áudio são gerados conjuntamente e saem da chamada como saídas separadas, `videos` e `audio`, além da `sampling_rate` que a trilha sonora carrega; a multiplexação em um único arquivo fica a cargo do chamador, por exemplo, com [encode_video()](/docs/diffusers/main/pt/api/utilities#diffusers.utils.encode_video).

## Referências Omni

O workflow `ref2va` é condicionado por uma lista ordenada de referências: até 9 imagens, 3 vídeos e 3 clipes de áudio, totalizando 12. A ordem é semântica. Ela rotula as referências na apresentação do prompt (`"<Picture 1>"`, `"<Audio 1>"`, `"<Video 1>"`) e avança o relógio rotativo compartilhado de áudio/vídeo, de modo que reordenar as mesmas referências constitui uma solicitação diferente.

Diferentemente dos keyframes acima, as referências não vinculam a geometria gerada: elas são codificadas em sua própria resolução e o canvas de destino padrão é o 16:9 do MiniMax-H3.

Existe uma classe de referência por modalidade, cada uma contendo a mídia em memória e a taxa que a mídia carrega:

| referência | média | taxa que ele declara |
| --- | --- | --- |
| [MiniMaxH3ImageReference](/docs/diffusers/main/pt/api/pipelines/minimax_h3#diffusers.modular_pipelines.minimax_h3.MiniMaxH3ImageReference) | `image` | — |
| [MiniMaxH3VideoReference](/docs/diffusers/main/pt/api/pipelines/minimax_h3#diffusers.modular_pipelines.minimax_h3.MiniMaxH3VideoReference) | `frames` e `audio` para sua própria trilha sonora | `fps`, padrão de 24.0 do MiniMax-H3, e `sample_rate` |
| [MiniMaxH3AudioReference](/docs/diffusers/main/pt/api/pipelines/minimax_h3#diffusers.modular_pipelines.minimax_h3.MiniMaxH3AudioReference) | `audio` | `sample_rate`, padrão para a própria |

As taxas são a partir das quais tudo é reamostrado: os quadros para os 24 fps próprios do MiniMax-H3, descartando e duplicando quadros inteiros, e a forma de onda para a taxa de amostragem do VAE de áudio. Mídias nas taxas próprias do MiniMax-H3 passam sem alterações, de modo que apenas dados produzidos em outra taxa precisam indicar isso.

Uma referência é construída de uma das duas formas: decodificada de um arquivo de mídia com o classmethod `from_file` da classe, ou construída diretamente a partir da mídia que a solicitação já mantém em memória — é assim que uma geração anterior é reutilizada (veja [Uma geração como referência](#a-generation-as-a-reference)).

Os blocos nunca abrem um arquivo de mídia — decodificar um caminho é responsabilidade do chamador, assim como em qualquer outra parte da biblioteca. Cada classe de referência faz isso por meio de seu classmethod `from_file`, que aceita um caminho ou uma URL (vídeo e áudio através do [PyAV](https://github.com/PyAV-Org/PyAV)) e retorna uma referência carregando as taxas reportadas pelo contêiner — um vídeo traz sua taxa de quadros e sua trilha sonora junto. Prefira `from_file` a [load_video()](/docs/diffusers/main/pt/api/utilities#diffusers.utils.load_video), que descarta a taxa de quadros: uma referência construída a partir de quadros cuja taxa real foi perdida é condicionada na velocidade errada, e nada é lançado.

```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` é obrigatório para `ref2va`. Para gerar um vídeo exatamente com a duração de uma trilha sonora de referência, calcule-o a partir do clipe — `round(samples / sample_rate * 24)` — e ele será arredondado para cima até o próximo `17 * n + 5` que o VAE de vídeo pode decodificar; a duração resultante deve permanecer entre 5 e 15 segundos, que é o intervalo gerado pelo MiniMax-H3.

### Uma geração como referência

Como os fluxos de trabalho compartilham um único pipeline, uma geração `t2va` pode ser usada diretamente como referência `ref2va` — e o construtor em memória foi projetado exatamente para essa transição. A mídia gerada já está nas taxas próprias do MiniMax-H3 (quadros a 24 fps, a trilha sonora na taxa de amostragem do VAE de áudio), portanto a referência não requer argumentos de taxa e nada é re-codificado por meio de um contêiner com perdas no caminho:

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

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

Uma ModularPipeline para geração conjunta de vídeo + áudio com MiniMax-H3: os fluxos de trabalho `t2va` (apenas texto) e `fl2va` (primeiro e/ou último keyframe) em relação à partição de checkpoint `transformer/`, e o fluxo de trabalho `ref2va` (omni-reference) em relação a `transformer_ref/`. Um repositório contém ambas as partições, e a seleção de um fluxo de trabalho carrega apenas o

próprio:

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

MiniMax-H3 remove o ruído de **uma sequência empacotada** que contém, ao mesmo tempo, a condição de texto, os latentes de condição de quadro-chave, os latentes de áudio e os latentes de vídeo. É por isso que os blocos passam um layout de linha em vez de tensores por modalidade, e por isso o pipeline carrega dois agendadores (`shift = 12.0` para vídeo, `shift = 3.0` para áudio) que são executados dentro de uma única chamada do transformer.

O checkpoint é destilado por orientação: a orientação está incorporada nos pesos, portanto não há um guia, nem `negative_prompt` e nem `guidance_scale`, e cada etapa executa exatamente uma passagem para frente.

MiniMax-H3 é apenas modular: este pipeline e seus blocos constituem toda a integração, não existe uma metade `DiffusionPipeline`. Este módulo carrega os fatos do modelo em que cada bloco se baseia — a geometria derivada da configuração como propriedades e a aritmética de tela e contagem de quadros como funções — e os contratos de condicionamento, codificação e ruído estão nos próprios blocos.

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

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

Blocos de pipeline Auto Modular para geração conjunta de vídeo + áudio com MiniMax-H3: os fluxos de trabalho `t2va` (apenas texto), `fl2va` (primeiro e/ou último keyframe) e `ref2va` (referência omni), selecionados pelas entradas de `references` e keyframe. Sem um `workflow=`, o carregamento dos componentes traz **ambas** as partições de transformer de 61,7GB — passe um para carregar apenas o que a tarefa precisa.

Fluxos de trabalho suportados:
- `t2va`: requer `prompt`
- `fl2va`: requer `prompt`, `image` ou `prompt`, `last_image`
- `ref2va`: requer `prompt`, `references`

Componentes: 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 (padrão: 768) canvas_max_pixels (padrão: 1032192) reference_image_short_edge (padrão: 2048)

Inputs: references (`list`, *opcional*): As referências para as quais condicionar, **na ordem em que o modelo deve lê-las**: a ordem as rotula na apresentação do prompt e as organiza no relógio rotativo compartilhado, de modo que uma ordem diferente é uma solicitação diferente. Uma dataclass por modalidade, todas contendo mídia em memória — um `MiniMaxH3ImageReference` (no máximo 9), um `MiniMaxH3VideoReference` em seu próprio `fps` (no máximo 3, cuja trilha sonora `audio` também é condicionada) ou um `MiniMaxH3AudioReference` em sua própria `sample_rate` (no máximo 3) — para um total de no máximo 12 referências, e referências de áudio não podem ser as únicas. Esses blocos nunca abrem um arquivo de mídia: decodifique com o classmethod `from_file` de cada classe, que traz as taxas junto. height (`int`, *opcional*): Altura do vídeo gerado em pixels, um múltiplo de 32. width (`int`, *opcional*): Largura do vídeo gerado em pixels, um múltiplo de 32. num_frames (`int`, *opcional*): Número de quadros a gerar, na taxa fixa de 24 fps. Ajustado para cima para o próximo `17 * n + 5` que o VAE de vídeo pode decodificar; a duração resultante deve permanecer entre 5 e 15 segundos. Para gerar um vídeo tão longo quanto uma trilha sonora de referência, passe `round(samples / sample_rate * 24)`. image (`Image`, *opcional*): Keyframe a partir do qual o vídeo começa. Ele é *esticado* para o canvas de destino, que por padrão é derivado de sua própria proporção de aspecto. last_image (`Image`, *opcional*): Keyframe no qual o vídeo termina. Pode ser passado sozinho para gerar *até* um quadro. Combinado com `image`, é o seguidor dos dois e é recortado para cobrir o canvas. prompt (`str`): O prompt para guiar a geração, uma única string. normalized_references (`list`, *opcional*): As referências normalizadas pela etapa de configuração, em ordem empacotada. keyframes (`list`, *opcional*): Os keyframes colocados no canvas de destino, em ordem empacotada. condition_latents (`list`, *opcional*): Os latentes de condicionamento de vídeo codificados, um por referência de imagem e vídeo em ordem empacotada. Sua forma é de onde vem a geometria de cada bloco de referência. audio_condition_latents (`list`, *opcional*): As linhas de condicionamento de áudio codificadas, uma por referência com áudio em ordem empacotada. generator (`Generator`, *opcional*): O gerador da solicitação. O ruído de condicionamento é extraído dele primeiro, uma extração por condição, antes do ruído das linhas geradas. latents (`Tensor`): Ruído de vídeo pré-gerado de forma `(1, 24, num_latent_frames, latent_height, latent_width)`, usado no lugar da extração. audio_latents (`Tensor`): Ruído de áudio pré-gerado de forma `(2, 32, num_audio_latents)`. num_inference_steps (`int`, *opcional*, padrão 50): O número de etapas de remoção de ruído. **denoiser_input_fields (`None`, *opcional*): A descrição estrutural da sequência empacotada que o transformer lê por nome: `token_tags`, `position_ids` e os três tensores de índice de linha. attention_kwargs (`dict`, *opcional*): Kwargs adicionais para processadores de atenção. keyframe_anchors (`tuple`, *opcional*, padrão ()): A qual extremidade do vídeo cada keyframe está ancorado, em ordem empacotada. output_type (`str`, *opcional*, padrão pil): Formato de saída: 'pil', 'np' ou 'pt'.

Saídas: videos (`list`): O vídeo gerado. audio (`Tensor`): A trilha sonora gerada, de forma `(1, 2, num_samples)`. sampling_rate (`int`): Taxa de amostragem da trilha sonora gerada em 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])
```

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

**Parâmetros:**

image (`PIL.Image.Image`, `np.ndarray` ou `torch.Tensor`) : A imagem de referência: uma imagem, um array `(height, width, 3)` ou um tensor `(3, height, width)`, `uint8` ou ponto flutuante em `[0, 1]`. Ela nunca vincula a geometria gerada — é codificada em uma de suas bordas curtas, 2048 para o checkpoint liberado, independentemente da tela que a solicitação gera.

Uma referência de sujeito, estilo ou cena: no máximo 9 por solicitação.

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

```python
from_file(media)
```

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

**Parâmetros:**

media (`str` ou `os.PathLike`) : Caminho ou URL da imagem.

Carregue um arquivo de imagem em um `MiniMaxH3ImageReference`, por meio de [load_image()](/docs/diffusers/main/pt/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)
```

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

**Parâmetros:**

frames (`list[PIL.Image.Image]`, `np.ndarray` ou `torch.Tensor`) : Os quadros de referência: uma lista de imagens, um array `(num_frames, height, width, 3)` ou um tensor `(num_frames, 3, height, width)`, `uint8` ou ponto flutuante em `[0, 1]`.

fps (`float`, *opcional*, padrão 24.0) : A taxa de quadros que `frames` carrega, que é o que posiciona os blocos de visão da referência na grade de 2 fps do conditioner. O próprio relógio do MiniMax-H3 é de 24 fps, portanto qualquer outra taxa é reamostrada para ele por meio de exclusão e duplicação de quadros inteiros — o que torna este o campo a ser definido corretamente quando os quadros vieram de um arquivo.

audio (`torch.Tensor` de forma `(channels, num_samples)`, *opcional*) : A trilha sonora deste vídeo, mono ou estéreo, condicionada como a própria da referência, em vez de como uma referência para si mesma. Se omitida, a referência é condicionada apenas pelo movimento.

sample_rate (`int`, *opcional*) : A taxa na qual o `audio` carrega suas amostras. Se omitido, será a taxa própria do VAE de áudio, o que deixa as amostras inalteradas; qualquer outra taxa resultará em reamostragem para ela.

Uma referência de movimento e câmera: no máximo 3 por solicitação, condicionada em conjunto com sua própria trilha sonora.

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

```python
from_file(media)
```

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

**Parâmetros:**

media (`str` ou `os.PathLike`) : Caminho ou URL do vídeo.

**Retorna:** `MiniMaxH3VideoReference`

os quadros `(num_frames, height, width, 3)` `uint8` na taxa de quadros reportada pelo contêiner, incluindo sua trilha sonora e a própria taxa de amostragem dessa trilha quando há um fluxo de áudio.

Decodifique um arquivo de vídeo em um `MiniMaxH3VideoReference`, na resolução, na taxa de quadros e na trilha sonora que ele carrega.

As taxas são definidas na referência, que é o ponto de decodificar dessa forma em vez de usar [load_video()](/docs/diffusers/main/pt/api/utilities#diffusers.utils.load_video): o MiniMax-H3 reamostra uma referência para seus próprios 24 fps, portanto, uma taxa de quadros perdida na entrada é uma solicitação condicionada na velocidade errada, sem nada para alertar sobre isso. Um contêiner cujos metadados estão incorretos é corrigido sobrescrevendo `fps` ou `sample_rate` na referência retornada.

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

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

**Parâmetros:**

audio (`torch.Tensor` de forma `(channels, num_samples)`) : A forma de onda de referência, mono ou estéreo.

sample_rate (`int`, *opcional*) : A taxa na qual o `audio` carrega suas amostras. Se omitido, será a taxa própria do VAE de áudio, o que deixa as amostras inalteradas; qualquer outra taxa resultará em reamostragem para ela.

Uma referência de voz ou música: no máximo 3 por solicitação e nunca isolada — uma referência de áudio deve ser pareada com pelo menos uma referência de imagem ou vídeo. Ela nunca chega ao conditioner e é codificada apenas pelo VAE de áudio.

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

```python
from_file(media)
```

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

**Parâmetros:**

media (`str` ou `os.PathLike`) : Caminho ou URL do áudio, ou de um vídeo cuja trilha sonora será extraída.

**Retorna:** `MiniMaxH3AudioReference`

o waveform `(channels, num_samples)` float32 na taxa de amostragem informada pelo contêiner.

Decodifique um arquivo de áudio em um `MiniMaxH3AudioReference`, na taxa de amostragem que ele possui.

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