# MiniMax-H3-Image

MiniMax-H3-Image es un modelo de imágenes de MiniMax basado en [MiniMax-H3](./minimax_h3), para la generación de imágenes a partir de texto y la edición de imágenes de referencia. Puedes encontrar el punto de control en [MiniMaxAI/MiniMax-H3-Image](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image).

Al igual que MiniMax-H3, se integra únicamente como bloques de [Modular Diffusers](../../modular_diffusers/overview): [MiniMaxH3ImageBlocks](/docs/diffusers/v0.43.0/es/api/pipelines/minimax_h3_image#diffusers.MiniMaxH3ImageBlocks) y su [MiniMaxH3ImageModularPipeline](/docs/diffusers/v0.43.0/es/api/pipelines/minimax_h3_image#diffusers.MiniMaxH3ImageModularPipeline) constituyen toda la integración.

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

El transformer y el codificador de texto ocupan unos 62 GB cada uno en bfloat16 y no caben juntos en una GPU de 80 GB, por lo que los ejemplos utilizan auto offloading: el [ComponentsManager](/docs/diffusers/v0.43.0/es/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager) mueve cada componente al acelerador cuando un bloque lo necesita. Una imagen de 4736x3552 alcanza entonces un pico de unos 65 GB.

Texto a imagen:

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

Edición de una imagen de referencia:

```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 | Clase |
|---|---|
| `transformer` | [MiniMaxH3ImageTransformer2DModel](/docs/diffusers/v0.43.0/es/api/models/minimax_h3_image_transformer2d#diffusers.MiniMaxH3ImageTransformer2DModel) |
| `text_encoder` | `Qwen3VLForConditionalGeneration` |
| `vae` | [AutoencoderKLMiniMaxH3Image](/docs/diffusers/v0.43.0/es/api/models/autoencoderkl_minimax_h3_image#diffusers.AutoencoderKLMiniMaxH3Image) |
| `tokenizer`, `processor` | El tokenizador del codificador de texto y un `Qwen3VLProcessor` |
| `scheduler` | [MiniMaxH3Scheduler](/docs/diffusers/v0.43.0/es/api/schedulers/minimax_h3#diffusers.MiniMaxH3Scheduler) |

El codificador de texto es el mismo que utiliza [MiniMax-H3](./minimax_h3). El checkpoint conserva su propia copia para que el repositorio sea autosuficiente; el Hub deduplica archivos idénticos entre repositorios, por lo que la copia no ocupa almacenamiento adicional allí.

## Flujos de trabajo

El flujo de trabajo se selecciona en la entrada `image`:

- **`text2image`** genera a partir de `prompt`.
- **`image_conditioned`** genera a partir de `prompt` y una o más imágenes de referencia pasadas como `image`. El prompt se refiere a ellas en orden como `<Picture 1>`, `<Picture 2>`, y así sucesivamente. Las referencias conservan su propio tamaño: cada una se redimensiona solo cuando su lado corto está fuera del rango de 1024 a 2048 píxeles, y nunca al tamaño de la imagen generada.

El prompt se utiliza tal cual, sin plantilla de chat, y funcionan mejor las descripciones largas y completas. Un prompt de edición suele nombrar qué conservar, luego qué cambiar y, a continuación, describe la imagen objetivo por completo.

## Mejora de prompts

[MiniMax-H3-Image-PE](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image-PE) es el modelo de expansión de prompts de MiniMax: reescribe una solicitud breve en el tipo de descripción detallada con la que el modelo de imágenes funciona mejor, y recomienda una relación de aspecto. Los bloques personalizados [diffusers/minimax-h3-image-pe-blocks](https://huggingface.co/diffusers/minimax-h3-image-pe-blocks) lo ejecutan como un pipeline propio. Requieren `xgrammar` y aproximadamente 18 GB de memoria 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")
```

Pasa las imágenes de referencia como `image` para expandir una instrucción de edición. Luego, pasa `prompt` a la pipeline de imagen, con una `height` y un `width` que coincidan con `aspect_ratio`.

## Tamaño de la imagen

`height` y `width` son el tamaño de la imagen devuelta y su valor predeterminado es 2048. El modelo genera a 4 megapíxeles o más: una solicitud más pequeña se genera en un lienzo más grande con la misma relación de aspecto y se redimensiona de nuevo, por lo que una solicitud de 1024x1024 cuesta lo mismo que una de 2048x2028. `min_generation_area` establece ese umbral en píxeles; pase `1024` para generar siempre en el tamaño solicitado. De cualquier manera, los lados del lienzo se redondean a múltiplos de 32.

MiniMax recomienda 4096x4096 para 1:1, 4736x3552 para 4:3, 5024x3360 para 3:2, 5472x3072 para 16:9 y 6272x2688 para 21:9, o los mismos tamaños con la altura y el ancho intercambiados para formatos verticales.

## Muestreo

- Los checkpoints muestrean en 6 pasos sobre sus `sample_sigmas`, y el transformer tiene una cabeza de salida por paso, por lo que no hay `num_inference_steps`.
- El modelo está destilado con guía, por lo que no hay un guionista, `negative_prompt` ni `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)
```

[Fuente](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/minimax_h3_image/modular_pipeline.py#L27)

Un ModularPipeline para MiniMax-H3-Image: texto a imagen (`text2image`) y edición de imagen de referencia (`image_conditioned`).

MiniMax-H3-Image ejecuta el transformer MiniMax-H3 sin audio sobre una secuencia empaquetada de filas de texto, las filas de las imágenes de referencia y las filas de la imagen generada, que es un único marco latente. El checkpoint se destila dos veces: la guía está integrada en los pesos, por lo que no hay un guider, ni `negative_prompt` ni `guidance_scale`, y muestrea en una cuadrícula fija de seis pasos con una cabeza de salida del transformer por paso, por lo que tampoco hay `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()
```

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

Bloques de pipeline modulares para MiniMax-H3-Image: `text2image` y edición con imagen de referencia (`image_conditioned`) cuando se pasa `image`.

Flujos de trabajo admitidos:
- `text2image`: requiere `prompt`
- `image_conditioned`: requiere `prompt`, `image`

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

Configs: reference_min_short_edge (predeterminado: 1024) reference_max_short_edge (predeterminado: 2048) vision_min_short_edge (predeterminado: 1024) vision_max_short_edge (predeterminado: 1024) sample_sigmas (predeterminado: [1.0, 0.9675236940383911, 0.8875485062599182, 0.75, 0.5327739119529724, 0.23200887441635132, 0.0]): La cuadrícula de muestreo en la que se destilaron las cabezas de salida por paso del checkpoint.

Entradas: image (`Image | list`, *opcional*): La imagen de referencia de la edición, o una lista de ellas. El prompt se refiere a ellas en orden como `<Picture 1>`, `<Picture 2>`, ... prompt (`str`): El prompt para guiar la generación, una sola cadena de texto. vision_images (`list`, *opcional*): Las imágenes de referencia redimensionadas para el codificador de texto. reference_images (`list`, *opcional*): Las imágenes de referencia redimensionadas para el VAE. generator (`Generator`, *opcional*): El generador de la solicitud. Se extrae una muestra posterior por referencia de él. height (`int`): Altura de la imagen devuelta en píxeles. width (`int`): Ancho de la imagen devuelta en píxeles. min_generation_area (`int`, *opcional*, predeterminado a 4194304): El área más pequeña, en píxeles, a la que se genera una imagen. Un `height x width` más pequeño se genera en un lienzo escalado a este área y se redimensiona de vuelta a `height x width` después de la decodificación. Pasa 1024 para generar siempre en el tamaño solicitado. reference_latents (`list`, *opcional*): Los latentes de condicionamiento de las imágenes de referencia. Su forma es donde proviene la geometría de cada referencia. latents (`Tensor`): Ruido pregenerado de forma `(1, latent_channels, latent_height, latent_width)`, usado en lugar del sorteo. reference_noise (`list`, *opcional*): Ruido pregenerado para las imágenes de referencia, un tensor de la forma de cada entrada de `reference_latents`, usado en lugar de los sorteos. **denoiser_input_fields (`None`, *opcional*): La descripción estructural de la secuencia empaquetada que el transformer lee por nombre: `token_tags`, `position_ids` y los dos tensores de índices de fila. output_type (`str`, *opcional*, predeterminado a pil): Formato de salida: 'pil', 'np', 'pt'.

Salidas: imágenes (`list`): Imágenes generadas.