# MiniMax-H3-Image

MiniMax-H3-Image é um modelo de imagem da MiniMax baseado no [MiniMax-H3](./minimax_h3), para geração de imagem a partir de texto e edição de imagem de referência. Você pode encontrar o checkpoint em [MiniMaxAI/MiniMax-H3-Image](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image).

Assim como o MiniMax-H3, ele é integrado apenas como blocos de [Modular Diffusers](../../modular_diffusers/overview): [MiniMaxH3ImageBlocks](/docs/diffusers/v0.43.0/pt/api/pipelines/minimax_h3_image#diffusers.MiniMaxH3ImageBlocks) e seu [MiniMaxH3ImageModularPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/minimax_h3_image#diffusers.MiniMaxH3ImageModularPipeline) constituem toda a integração.

```py
import torch
from diffusers import ComponentsManager, ModularPipeline

manager = ComponentsManager()
manager.enable_auto_cpu_offload(device="cuda")

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

O transformer e o codificador de texto têm cerca de 62 GB cada em bfloat16 e não cabem juntos em uma GPU de 80 GB, portanto, os exemplos usam auto offloading: o [ComponentsManager](/docs/diffusers/v0.43.0/pt/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager) move cada componente para o acelerador quando um bloco precisa dele. Uma imagem de 4736x3552 então atinge um pico de cerca de 65 GB.

Texto para imagem:

```py
prompt = (
    "An overhead photograph of a rustic farm-to-table spread on a weathered wooden table: a round loaf of sourdough "
    "on burlap, wedges of cheese on a dark board, a copper bowl of vegetables, vine tomatoes, olives and walnuts."
)
image = pipe(
    prompt=prompt, height=3552, width=4736, generator=torch.Generator().manual_seed(42), output="images"
)[0]
```

Editando uma imagem de referência:

```py
from diffusers.utils import load_image

reference = load_image("https://huggingface.co/MiniMaxAI/MiniMax-H3-Image/resolve/main/examples/reference1.png")
image = pipe(
    prompt="Keep everything in <Picture 1> as it is, but remove the headphones and have the two hosts fist bump.",
    image=reference,
    height=4096,
    width=4096,
    generator=torch.Generator().manual_seed(1234),
    output="images",
)[0]
```

## Componentes

| Componente | Classe |
|---|---|
| `transformer` | [MiniMaxH3ImageTransformer2DModel](/docs/diffusers/v0.43.0/pt/api/models/minimax_h3_image_transformer2d#diffusers.MiniMaxH3ImageTransformer2DModel) |
| `text_encoder` | `Qwen3VLForConditionalGeneration` |
| `vae` | [AutoencoderKLMiniMaxH3Image](/docs/diffusers/v0.43.0/pt/api/models/autoencoderkl_minimax_h3_image#diffusers.AutoencoderKLMiniMaxH3Image) |
| `tokenizer`, `processor` | O tokenizer do codificador de texto e um `Qwen3VLProcessor` |
| `scheduler` | [MiniMaxH3Scheduler](/docs/diffusers/v0.43.0/pt/api/schedulers/minimax_h3#diffusers.MiniMaxH3Scheduler) |

O codificador de texto é o mesmo utilizado pelo [MiniMax-H3](./minimax_h3). O checkpoint mantém uma cópia própria para que o repositório seja autocontido; o Hub deduplica arquivos idênticos entre repositórios, portanto a cópia não ocupa armazenamento extra lá.

## Fluxos de trabalho

O workflow é selecionado na entrada `image`:

- **`text2image`** gera a partir de `prompt`.
- **`image_conditioned`** gera a partir de `prompt` e uma ou mais imagens de referência passadas como `image`. O prompt se refere a elas em ordem como `<Picture 1>`, `<Picture 2>`, e assim por diante. As referências mantêm seu próprio tamanho: cada uma é redimensionada apenas quando sua borda curta está fora de 1024 a 2048 pixels, e nunca para o tamanho da imagem gerada.

O prompt é usado literalmente, sem template de chat, e descrições longas e completas funcionam melhor. Um prompt de edição geralmente nomeia o que preservar, depois o que alterar e, em seguida, descreve a imagem de destino por completo.

## Melhoria de prompt

[MiniMax-H3-Image-PE](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image-PE) é o modelo de expansão de prompt da MiniMax: ele reescreve uma solicitação curta no tipo de descrição detalhada com a qual o modelo de imagem funciona melhor e recomenda uma proporção de aspecto. Os blocos personalizados [diffusers/minimax-h3-image-pe-blocks](https://huggingface.co/diffusers/minimax-h3-image-pe-blocks) o executam como um pipeline próprio. Eles precisam de `xgrammar` e de cerca de 18 GB de memória de GPU.

```py
import torch
from diffusers import ModularPipeline

enhancer = ModularPipeline.from_pretrained("diffusers/minimax-h3-image-pe-blocks", trust_remote_code=True)
enhancer.load_components(dtype=torch.bfloat16, device_map="cuda")

state = enhancer(prompt="a cozy cabin in the snow")
prompt, aspect_ratio = state.get("prompt"), state.get("aspect_ratio")
```

Passe as imagens de referência como `image` para expandir uma instrução de edição. Em seguida, passe `prompt` para o pipeline de imagem, com `height` e `width` que correspondam a `aspect_ratio`.

## Tamanho da imagem

`height` e `width` são o tamanho da imagem retornada e, por padrão, são 2048. O modelo gera em 4 megapixels ou mais: uma solicitação menor é gerada em um canvas maior com a mesma proporção de aspecto e redimensionada de volta, portanto, uma solicitação de 1024x1024 custa o mesmo que uma de 2048x2048. `min_generation_area` define esse limite em pixels; passe `1024` para sempre gerar no tamanho solicitado. De qualquer forma, os lados do canvas são arredondados para múltiplos de 32.

A MiniMax recomenda 4096x4096 para 1:1, 4736x3552 para 4:3, 5024x3360 para 3:2, 5472x3072 para 16:9 e 6272x2688 para 21:9, ou os mesmos tamanhos com altura e largura invertidos para formatos retrato.

## Amostragem

- O checkpoint amostra em 6 etapas sobre seu `sample_sigmas`, e o transformer possui uma cabeça de saída por etapa, portanto não há `num_inference_steps`.
- O modelo é destilado por orientação, portanto não há um guia, `negative_prompt` ou `guidance_scale`.

## MiniMaxH3ImageModularPipeline[[diffusers.MiniMaxH3ImageModularPipeline]]

#### diffusers.MiniMaxH3ImageModularPipeline[[diffusers.MiniMaxH3ImageModularPipeline]]

```python
diffusers.MiniMaxH3ImageModularPipeline(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/v0.43.0/src/diffusers/modular_pipelines/minimax_h3_image/modular_pipeline.py#L27)

Uma ModularPipeline para MiniMax-H3-Image: texto-para-imagem (`text2image`) e edição de imagem de referência (`image_conditioned`).

MiniMax-H3-Image executa o transformer MiniMax-H3 sem áudio sobre uma sequência empacotada de linhas de texto, as linhas das imagens de referência e as linhas da imagem gerada, que é um único frame latente. O checkpoint é destilado duas vezes: o guidance é incorporado nos pesos, portanto não há guider, nem `negative_prompt` e nem `guidance_scale`, e ele amostra em uma grade fixa de seis passos com uma cabeça de saída do transformer por passo, portanto também não há `num_inference_steps`.

```py
import torch
from diffusers import ModularPipeline

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

## MiniMaxH3ImageBlocks[[diffusers.MiniMaxH3ImageBlocks]]

#### diffusers.MiniMaxH3ImageBlocks[[diffusers.MiniMaxH3ImageBlocks]]

```python
diffusers.MiniMaxH3ImageBlocks()
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/minimax_h3_image/modular_blocks_minimax_h3_image.py#L371)

Blocos de pipeline modulares para MiniMax-H3-Image: `text2image` e edição de imagem de referência (`image_conditioned`) quando `image` é passado.

Fluxos de trabalho suportados:
- `text2image`: requer `prompt`
- `image_conditioned`: requer `prompt`, `image`

Componentes: image_processor (`VaeImageProcessor`) text_encoder (`Qwen3VLForConditionalGeneration`) tokenizer (`Qwen2Tokenizer`) processor (`Qwen3VLProcessor`) vae (`AutoencoderKLMiniMaxH3Image`) scheduler (`MiniMaxH3Scheduler`) transformer (`MiniMaxH3ImageTransformer2DModel`)

Configs: reference_min_short_edge (padrão: 1024) reference_max_short_edge (padrão: 2048) vision_min_short_edge (padrão: 1024) vision_max_short_edge (padrão: 1024) sample_sigmas (padrão: [1.0, 0.9675236940383911, 0.8875485062599182, 0.75, 0.5327739119529724, 0.23200887441635132, 0.0]): A grade de amostragem na qual as cabeças de saída por etapa do checkpoint foram destiladas.

Inputs: image (`Image | list`, *opcional*): A imagem de referência da edição, ou uma lista delas. O prompt se refere a elas em ordem como `<Picture 1>`, `<Picture 2>`, ... prompt (`str`): O prompt para orientar a geração, uma única string. vision_images (`list`, *opcional*): As imagens de referência redimensionadas para o codificador de texto. reference_images (`list`, *opcional*): As imagens de referência redimensionadas para o VAE. generator (`Generator`, *opcional*): O gerador da solicitação. Uma amostra posterior por referência é extraída dele. height (`int`): Altura da imagem retornada em pixels. width (`int`): Largura da imagem retornada em pixels. min_generation_area (`int`, *opcional*, padrão 4194304): A menor área, em pixels, na qual uma imagem é gerada. Um `height x width` menor é gerado em um canvas ampliado para essa área e redimensionado de volta para `height x width` após a decodificação. Passe 1024 para sempre gerar no tamanho solicitado. reference_latents (`list`, *opcional*): Os latentes de condicionamento das imagens de referência. Sua forma é de onde a geometria de cada referência vem. latents (`Tensor`): Ruído pré-gerado de forma `(1, latent_channels, latent_height, latent_width)`, usado no lugar da extração. reference_noise (`list`, *opcional*): Ruído pré-gerado para as imagens de referência, um tensor da forma de cada entrada de `reference_latents`, usado no lugar das extrações. **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 dois tensores de índice de linha. output_type (`str`, *opcional*, padrão pil): Formato de saída: 'pil', 'np', 'pt'.

Saídas: imagens (`list`): Imagens geradas.