# MiniMax-H3-Image

MiniMax-H3-Image adalah model gambar dari MiniMax yang didasarkan pada [MiniMax-H3](./minimax_h3), untuk generasi teks-ke-gambar dan pengeditan gambar referensi. Anda dapat menemukan checkpoint di [MiniMaxAI/MiniMax-H3-Image](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image).

Seperti MiniMax-H3, model ini terintegrasi hanya sebagai blok [Modular Diffusers](../../modular_diffusers/overview): [MiniMaxH3ImageBlocks](/docs/diffusers/main/id/api/pipelines/minimax_h3_image#diffusers.MiniMaxH3ImageBlocks) dan [MiniMaxH3ImageModularPipeline](/docs/diffusers/main/id/api/pipelines/minimax_h3_image#diffusers.MiniMaxH3ImageModularPipeline) mereka merupakan keseluruhan integrasi.

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

Transformer dan text encoder masing-masing berukuran sekitar 62 GB dalam bfloat16 dan tidak muat bersama di GPU 80 GB, sehingga contoh-contoh menggunakan auto offloading: [ComponentsManager](/docs/diffusers/main/id/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager) memindahkan setiap komponen ke akselerator ketika sebuah blok membutuhkannya. Gambar berukuran 4736x3552 kemudian mencapai puncak sekitar 65 GB.

Teks-ke-gambar:

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

Mengedit gambar referensi:

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

## Komponen

| Komponen | Kelas |
|---|---|
| `transformer` | [MiniMaxH3ImageTransformer2DModel](/docs/diffusers/main/id/api/models/minimax_h3_image_transformer2d#diffusers.MiniMaxH3ImageTransformer2DModel) |
| `text_encoder` | `Qwen3VLForConditionalGeneration` |
| `vae` | [AutoencoderKLMiniMaxH3Image](/docs/diffusers/main/id/api/models/autoencoderkl_minimax_h3_image#diffusers.AutoencoderKLMiniMaxH3Image) |
| `tokenizer`, `processor` | Tokenizer dari text encoder dan `Qwen3VLProcessor` |
| `scheduler` | [MiniMaxH3Scheduler](/docs/diffusers/main/id/api/schedulers/minimax_h3#diffusers.MiniMaxH3Scheduler) |

Text encoder-nya sama dengan yang digunakan oleh [MiniMax-H3](./minimax_h3). Checkpoint menyimpan salinannya sendiri agar repositori bersifat mandiri; Hub menduplikasi file yang identik di antara repositori, sehingga salinan tersebut tidak memakan penyimpanan tambahan di sana.

## Alur Kerja

Alur kerja dipilih pada input `image`:

- **`text2image`** menghasilkan dari `prompt`.
- **`image_conditioned`** menghasilkan gambar dari `prompt` dan satu atau beberapa gambar referensi yang diteruskan sebagai `image`. Prompt merujuk pada gambar-gambar tersebut secara berurutan sebagai `<Picture 1>`, `<Picture 2>`, dan seterusnya. Referensi mempertahankan ukuran aslinya: masing-masing hanya di-resize ketika sisi pendeknya berada di luar rentang 1024 hingga 2048 piksel, dan tidak pernah disesuaikan ke ukuran gambar yang dihasilkan.

Prompt digunakan apa adanya, tanpa template chat, dan deskripsi panjang serta lengkap memberikan hasil terbaik. Prompt editasi biasanya menyebutkan apa yang harus dipertahankan, kemudian apa yang harus diubah, lalu menggambarkan gambar target secara lengkap.

## Peningkatan prompt

[MiniMax-H3-Image-PE](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image-PE) adalah model ekspansi prompt dari MiniMax: model ini menulis ulang permintaan singkat menjadi deskripsi detail yang paling cocok untuk model gambar, dan merekomendasikan rasio aspek. Blok kustom `diffusers/minimax-h3-image-pe-blocks` menjalankannya sebagai pipeline tersendiri. Blok ini membutuhkan `xgrammar` dan sekitar 18 GB memori 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")
```

Lewatkan gambar referensi sebagai `image` untuk memperluas instruksi pengeditan. Kemudian, lewati `prompt` ke pipeline gambar, dengan `height` dan `width` yang sesuai dengan `aspect_ratio`.

## Ukuran gambar

`height` dan `width` adalah ukuran gambar yang dikembalikan dan secara default bernilai 2048. Model menghasilkan gambar dengan resolusi 4 megapiksel atau lebih: permintaan yang lebih kecil akan dihasilkan pada kanvas yang lebih besar dengan rasio aspek yang sama, lalu di-resize kembali, sehingga permintaan 1024x1024 memiliki biaya yang sama dengan permintaan 2048x2048. `min_generation_area` mengatur ambang batas tersebut dalam piksel; berikan `1024` untuk selalu menghasilkan gambar pada ukuran yang diminta. Dalam kedua kasus, sisi kanvas dibulatkan ke kelipatan 32.

MiniMax merekomendasikan 4096x4096 untuk 1:1, 4736x3552 untuk 4:3, 5024x3360 untuk 3:2, 5472x3072 untuk 16:9, dan 6272x2688 untuk 21:9, atau ukuran yang sama dengan tinggi dan lebar ditukar untuk format potret.

## Sampling

- Checkpoint mengambil sampel dalam 6 langkah di atas `sample_sigmas`-nya, dan transformer memiliki satu kepala output per langkah, sehingga tidak ada `num_inference_steps`.
- Model ini telah melalui distilasi panduan, sehingga tidak ada `negative_prompt` atau `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)
```

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

A ModularPipeline untuk MiniMax-H3-Image: teks-ke-gambar (`text2image`) dan pengeditan gambar referensi (`image_conditioned`).

MiniMax-H3-Image menjalankan transformer MiniMax-H3 tanpa audio di atas satu urutan terpadu dari baris teks, baris gambar referensi, dan baris gambar yang dihasilkan, yang merupakan satu frame laten tunggal. Checkpoint ini didistilasi dua kali: guidance dipanggang ke dalam bobot, sehingga tidak ada guider, tidak ada `negative_prompt` dan tidak ada `guidance_scale`, dan ia melakukan sampling pada grid tetap enam langkah dengan satu kepala output transformer per langkah, sehingga tidak ada `num_inference_steps` juga.

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

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

Blok pipeline modular untuk MiniMax-H3-Image: `text2image`, dan pengeditan gambar referensi (`image_conditioned`) ketika `image` diteruskan.

Alur kerja yang didukung:
- `text2image`: membutuhkan `prompt`
- `image_conditioned`: membutuhkan `prompt`, `image`

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

Configs: reference_min_short_edge (default: 1024) reference_max_short_edge (default: 2048) vision_min_short_edge (default: 1024) vision_max_short_edge (default: 1024) sample_sigmas (default: [1.0, 0.9675236940383911, 0.8875485062599182, 0.75, 0.5327739119529724, 0.23200887441635132, 0.0]): Grid sampling tempat kepala output per-langkah checkpoint didistilasi.

Inputs: image (`Image | list`, *optional*): The reference image of the edit, or a list of them. The prompt refers to them in order as `<Picture 1>`, `<Picture 2>`, ... prompt (`str`): The prompt to guide generation, a single string. vision_images (`list`, *optional*): The reference images resized for the text encoder. reference_images (`list`, *optional*): The reference images resized for the VAE. generator (`Generator`, *optional*): The generator of the request. One posterior sample per reference is drawn from it. height (`int`): Height of the returned image in pixels. width (`int`): Width of the returned image in pixels. min_generation_area (`int`, *optional*, defaults to 4194304): The smallest area, in pixels, an image is generated at. A smaller `height x width` is generated on a canvas scaled up to this area and resized back to `height x width` after decoding. Pass 1024 to always generate at the requested size. reference_latents (`list`, *optional*): The conditioning latents of the reference images. Their shape is where every reference's geometry comes from. latents (`Tensor`): Pre-generated noise of shape `(1, latent_channels, latent_height, latent_width)`, used instead of the draw. reference_noise (`list`, *optional*): Pre-generated noise for the reference images, one tensor of the shape of each entry of `reference_latents`, used instead of the draws. **denoiser_input_fields (`None`, *optional*): The structural description of the packed sequence the transformer reads by name: `token_tags`, `position_ids` and the two row-index tensors. output_type (`str`, *optional*, defaults to pil): Output format: 'pil', 'np', 'pt'.

Output: gambar (`list`): Gambar yang dihasilkan.