Accept the MiniMax-H3-Image Community License Agreement to access these files

This repository is publicly accessible, but you have to accept the conditions to access its files and content.

These files are a Model Derivative of MiniMax-H3-Image and are licensed under the MiniMax-H3-Image Community License Agreement (LICENSE in this repository), including its Use Restrictions (Section V) and Acceptable Use Policy (Exhibit A). The license is granted only outside its Excluded Territories (the European Union, the United Kingdom, the Republic of Korea and the United States of America), and requires a separate written authorization from MiniMax for a Hosted Service or above 1 million USD annualized revenue (Section IV).

MiniMax-H3-Image GGUF

GGUF builds of MiniMax-H3-Image, made by Moonbox for on-device use. Each precision is one file at the root of this repository; pick one by the memory you have. Only the model's own weights are converted: the other parts of the pipeline (text encoder, VAE, tokenizer) come from the original repository unless the section below says otherwise.

Files

The last column is how far each file is from the original BF16 weights: the relative RMS error of its dequantized weights, averaged over all parameters. Image-quality scores against BF16 outputs are added as each precision passes the image eval.

Precision	File	Size	sha256	Checked against BF16
F16	`minimax-h3-image-F16.gguf`	40.25 GB	`df57ab8cf074`	0.0000001 % (8.8e-10)
BF16	`minimax-h3-image-BF16.gguf`	40.25 GB	`66bb7109a073`	exact
Q8_0	`minimax-h3-image-Q8_0.gguf`	21.46 GB	`142134608dde`	0.56 %
Q6_K	`minimax-h3-image-Q6_K.gguf`	16.61 GB	`cbedcf9a5f46`	1.9 %
Q5_K_M	`minimax-h3-image-Q5_K_M.gguf`	14.05 GB	`d6571e57f992`	3.7 %
Q4_K_M	`minimax-h3-image-Q4_K_M.gguf`	11.54 GB	`bf51152afb00`	7.2 %

How to run

These files are the MiniMax-H3-Image diffusion transformer only (20.1 B parameters as stable-diffusion.cpp and ComfyUI run it), made from Comfy-Org's single-file repackage of MiniMax's weights (minimax_h3_image_pruned_bf16.safetensors: the six per-step output heads included and the time-embedding modulation folded into 8 time curves; we checked it against the official weights). Text encoder and VAE are separate:

VAE: minimax_h3_image_vae_fp16.safetensors from Comfy-Org/MiniMax-H3-Image.
Text encoder: MiniMax-H3's Qwen3-VL-32B, e.g. qwen3vl_32b_minimax_h3-Q4_K_M.gguf (18 GB) from leejet/MiniMax-H3-GGUF, or the much smaller P-H3-Image text encoder (Qwen3-VL-4B with its connector, 5 GB) from PrunaAI/P-H3-Image-Comfy.

stable-diffusion.cpp (MiniMax-H3-Image support from master-1088; we ran master-1091, commit b9d7176):

sd-cli --diffusion-model minimax-h3-image-Q4_K_M.gguf --vae minimax_h3_image_vae_fp16.safetensors \
  --llm qwen3vl_32b_minimax_h3-Q4_K_M.gguf -p "a lovely cat holding a sign says 'moonbox'" \
  --cfg-scale 1.0 --steps 6 --sampling-method euler --sigmas minimax-h3-image -W 1024 -H 1024 \
  --offload-to-cpu --diffusion-fa --vae-tiling

Tested here: Q4_K_M with the P-H3-Image text encoder renders 1024 × 1024 in 13.4 s end to end on an RTX 3080 Laptop GPU (16 GB), adding --max-vram 14 --mmap --params-backend te=disk to the command above in place of --offload-to-cpu. Q8_0 (21.5 GB) did not run on that 16 GB card with 32 GB of RAM; the files above Q4_K_M are for GPUs with 24 GB or more.

Six steps, CFG 1, Euler with the model's own sigma schedule (--sigmas minimax-h3-image): the checkpoint is distilled to six steps and carries one output head per step. For editing, add -r <picture> (up to 16; refer to them as <Picture 1>, <Picture 2>, ... in the prompt). The schedule is also stored in each file's config metadata.

ComfyUI with ComfyUI-GGUF: the files are tagged minimax_h3, which the stock loader accepts once its pending change lands.

Which file: Q8_0 is the closest to the original at about half the size; Q6_K and Q5_K_M trade a little fidelity for memory; Q4_K_M is the smallest and fits a 16 GB GPU. BF16 / F16 are the unquantized weights.

License. The MiniMax-H3-Image Community License Agreement (LICENSE and NOTICE in this repository). It does not grant use in the European Union, the United Kingdom, the Republic of Korea or the United States of America, and a Hosted Service or more than 1 million USD annualized revenue needs MiniMax's written authorization.

How these were made

From MiniMax-H3-Image at revision 5f90473023: the original BF16 weights converted to GGUF F16 / BF16, then quantized with llama.cpp's llama-quantize. Every file was checked against the original before upload; the sha256 column above is what the files must hash to.

License

MiniMax-H3-Image Community License. These files are a derivative of the original model and carry its license: it is copied in this repository, and it governs your use of these files. The original model card follows unchanged.

Original model card

MiniMax-H3-Image

Online API

Use MiniMax-H3-Image directly via API.

Global: platform.minimax.io | CN: platform.minimax.cn

API docs:

Text-to-image: EN-docs, CN-docs
Image editing: EN-docs, CN-docs
Prompt expansion: EN-docs, CN-docs

Online App

Use MiniMax-H3-Image directly via App.

WebApp Global: hailuoai.video | CN: hailuoai.com
Desktop Global: agent.minimax.io | CN: agent.minimax.cn

Introduction

MiniMax-H3-Image is a state-of-the-art open-source model for image generation and editing from the MiniMax H3 family. It combines intelligent understanding of creative intent with the ability to build visual worlds: with precise instruction following, it develops a creative concept into concrete characters, scenes and atmosphere. Generation and editing are unified in one checkpoint, which generates images from text (text-to-image) and edits one or more reference images (image editing), giving creators and developers a flexible and controllable way to create images.

It generates images of about 16 megapixels at every aspect ratio, from 4096x4096 (1:1) to 6272x2688 (21:9), directly and without an upscaler (see Sizes). The checkpoint is distilled to 6 sampling steps (6 NFEs) with no classifier-free guidance. Its diffusion transformer (DiT) has the H3 architecture without the audio layers, and it uses the MiniMax-H3 text encoder unchanged.

Highlights

MiniMax-H3-Image brings together three core strengths: speed, image quality, and instruction following.

16-megapixel images at a practical computational cost. Compared with the 1–4 MP outputs common today, 16 MP (4096 × 4096) images offer far more detail but typically require substantially more computation. MiniMax-H3-Image keeps that computational cost manageable, making 16 MP generation practical for everyday creation.
Rich detail. Remarkable realism. MiniMax-H3-Image goes beyond the familiar “AI look” to produce images with intricate detail and lifelike realism, opening up more possibilities for creative and professional use. It brings generated imagery closer to the richness and nuance of the real visual world.
Stronger instruction following. Greater creative control. Great image generation goes beyond beautiful pictures—it helps creators bring their ideas to life. MiniMax-H3-Image delivers the strongest instruction following among open-source models and supports up to 16 reference images, giving creators more control over the final result.

Model Zoo

Model	Role	Precision	Size	Hugging Face
MiniMax-H3-Image	Text-to-image and image editing	BF16 (DiT)	68.65 GB	MiniMaxAI/MiniMax-H3-Image
MiniMax-H3-Image-PE (optional)	Prompt expander for text-to-image	NVFP4	17.9 GB	MiniMaxAI/MiniMax-H3-Image-PE

Model Architecture

MiniMax-H3-Image follows the H3-Base design with the audio branch removed. The text prompt and the reference images are encoded by the H3 text encoder; the reference images are also encoded by the image VAE. All tokens form one packed sequence for a single-stream transformer, which predicts the latent of the target image. The VAE decodes that latent into the image.

Text encoder: the full Qwen3-VL text encoder of MiniMax-H3, unchanged. The DiT reads the hidden states of its 50th layer.
Image VAE: a CNN encoder and a 2D ViT decoder (24 layers), with 16x spatial downsampling and 24 latent channels. The DiT patchifies the latent with a 2x2 patch, so each transformer token covers 32x32 pixels.
Diffusion transformer: 33.1B parameters, a dense single-stream transformer with 50 layers (hidden size 5376, 56 attention heads, FFN size 14336) and 3D multimodal RoPE, the same as the H3-Omni-Transformer. The weights are BF16; the embedding, timestep and output layers are FP32.

Quick Start

Download

Component	Content	Size
`transformer/`	DiT: BF16, with the embedding, timestep and output layers in FP32.	66.28 GB
`pdd_fused_heads.safetensors`, `pdd_config.json`	The per-step output heads that replace the transformer's output layer, and the sampling schedule.	12 MB
`vae/`	Image VAE, FP32.	2.34 GB
`tokenizer/`, `processor/`	Qwen3-VL tokenizer and processor, identical to MiniMax-H3.	23 MB
Text encoder	Not in this repository. `model_index.json` loads it from `MiniMaxAI/MiniMax-H3`, folder `text_encoder/`. If you already have MiniMax-H3, it is not downloaded again.	66.7 GB

MiniMax-H3-Image/
├── model_index.json
├── pdd_config.json
├── pdd_fused_heads.safetensors
├── processor/
├── tokenizer/
├── transformer/
└── vae/

Download this repository and the MiniMax-H3 text encoder into the Hugging Face cache:

hf download MiniMaxAI/MiniMax-H3-Image
hf download MiniMaxAI/MiniMax-H3 --include "text_encoder/*"
# optional prompt expander
hf download MiniMaxAI/MiniMax-H3-Image-PE

Local Deployment

We recommend the following inference frameworks to serve the model:

SGLang - see cookbook
vLLM-Omni - see vllm-omni recipe
diffusers - see diffusers docs
LightX2V - see Usage guide
ComfyUI - see Comfy tutorial; use T2I template / Edit template

vLLM-Omni Deployment

See the vLLM-Omni recipe for per-hardware deployment configurations and measured latency. Both NVIDIA and AMD accelerators are supported, including NVIDIA H200, RTX PRO 6000 Blackwell, AMD Instinct MI350X and more.

Start the server on one GPU:

vllm serve MiniMaxAI/MiniMax-H3-Image --omni --host 0.0.0.0 --port 8000

For lower latency, split each request over several GPUs with sequence parallelism (Ulysses), for example on 4 GPUs:

vllm serve MiniMaxAI/MiniMax-H3-Image --omni --host 0.0.0.0 --port 8000 \
  --num-gpus 4 --usp 4 --text-encoder-tp-size 4

SGLang Deployment

Here we use SGLang as a deployment example. See the MiniMax-H3-Image deployment guide for additional deployment configurations.

Start the server on one GPU:

sglang serve --model-path MiniMaxAI/MiniMax-H3-Image --host 0.0.0.0 --port 30000 --warmup-mode off

To use a local copy of the MiniMax-H3 text_encoder/ folder instead of the Hugging Face cache, add --text-encoder-path <path to text_encoder>.

For lower latency, split each request over several GPUs with sequence parallelism (Ulysses), for example on 4 GPUs:

sglang serve --model-path MiniMaxAI/MiniMax-H3-Image --host 0.0.0.0 --port 30000 --warmup-mode off \
  --num-gpus 4 --ulysses-degree 4

Request parameters

Text-to-image requests are JSON sent to /v1/images/generations. Image editing requests send the reference images as multipart form data to /v1/images/edits; their order defines <Picture 1>, <Picture 2>, and so on in the prompt. Both return the PNG in data[0].b64_json. Runnable examples are in Full Workflow.

Field	Text-to-image	Image editing	Notes
`prompt`	Required	Required	Used as given, truncated to 4096 tokens. See Full Workflow
`size`	Required	Required	`WIDTHxHEIGHT`. The returned image has exactly this size; see Sizes
`image`	—	One or more files	In upload order they are `<Picture 1>`, `<Picture 2>`, ... in the prompt
`seed`	Recommended	Recommended	Integer
`generator_device`	`cpu` recommended	`cpu` recommended	Same seed, same initial noise on every machine
`response_format`	`b64_json`	`b64_json`
`min_generation_area`	Optional	Optional	Minimum generated area in pixels, 1024-16777216, default 4194304 (2048x2048). A smaller `size` is generated at the same aspect ratio on a larger canvas and resized back with LANCZOS; pass 1024 to turn this off. All sizes in the table below are above the default
`num_inference_steps`	Omit or 6	Omit or 6	Other values return HTTP 400
`guidance_scale`	Omit or 1	Omit or 1	Other values return HTTP 400
`negative_prompt`	Not supported	Not supported	Rejected

Sizes

The effective working range of MiniMax-H3-Image is about 4 MP to 20 MP, and it generally gives the best results at around 16 MP. Common 16 MP sizes are listed below:

Aspect ratio	Size (width x height)
1:1	4096x4096
4:3 / 3:4	4736x3552 / 3552x4736
3:2 / 2:3	5024x3360 / 3360x5024
16:9 / 9:16	5472x3072 / 3072x5472
21:9	6272x2688

Full Workflow

MiniMax-H3-Image expects a detailed English description of the whole image. The MiniMax API turns a short prompt in any language into such a description with H3-Image-Context-IR before generation. We also provide MiniMax-H3-Image-PE, which can be deployed locally.

This section reproduces the quality of images generated directly by the MiniMax API with a locally deployed SGLang server. The scripts are in examples/ and use only the Python standard library; run them in that folder:

hf download MiniMaxAI/MiniMax-H3-Image --include "examples/*" --local-dir .
cd examples

Before running examples, set your MiniMax API endpoint and key to use the H3-Image-Context-IR API and the reference scripts. The scripts read them from the environment:

# MiniMax API endpoint (choose one)
# CN
export MINIMAX_API_BASE="https://api.minimax.cn"
# Global
# export MINIMAX_API_BASE="https://api.minimax.io"

# API key obtained from the MiniMax platform
export MINIMAX_API_KEY="<api-key>"

API docs:

H3-Image-Context-IR: use /v1/h3_image_context_ir EN-docs, CN-docs
Text-to-image: use /v1/images/generations EN-docs, CN-docs
Image editing: use /v1/images/edits EN-docs, CN-docs

case-T2I

instruction.t2i.txt.

Stage		Request	Result
Prompt Enhancement	H3-Image-Context-IR (MiniMax API)	`python3 context_ir.py t2i` (script)	`revised_prompt.txt`, `revised_size.txt`; our run: `revised_prompt.t2i.txt`, `revised_size.t2i.txt` (4736x3552)
Prompt Enhancement	local alternative: MiniMax-H3-Image-PE	`scripts/expand_prompt.py` in the PE repository	Save `expanded_caption` as `revised_prompt.txt` and the size for `aspect_ratio` as `revised_size.txt`
MiniMax-H3-Image generation: local SGLang		`python3 t2i.py --prompt revised_prompt.txt --size $(cat revised_size.txt)` (script)	`t2i.png`
E2E API Reference: text-to-image by directly calling the MiniMax API		`python3 api_generate.py t2i` (script)	`api_t2i.png`

Left: t2i.png from local SGLang with the enhanced prompt. Right: api_t2i.png from the MiniMax API. Both show an overhead farm-to-table feast with bread, vegetables and cheeses on a weathered wooden table

t2i.png from local SGLang (left) and api_t2i.png from the MiniMax API (right), 4736x3552 (4:3 picked by H3-Image-Context-IR)

case-Edit

instruction.edit.txt with the reference image reference1.png as <Picture 1>.

Stage	Request	Result
Prompt Enhancement: H3-Image-Context-IR (MiniMax API)	`python3 context_ir.py edit` (script)	`revised_prompt.txt`, `revised_size.txt`; our run: `revised_prompt.edit.txt`, `revised_size.edit.txt` (4096x4096)
MiniMax-H3-Image generation: local SGLang	`python3 edit.py --prompt revised_prompt.txt --size $(cat revised_size.txt)` (script)	`edit.png`
E2E API Reference: image editing by directly calling the MiniMax API	`python3 api_generate.py edit` (script)	`api_edit.png`

Left: reference1.png, the reference image of two podcast hosts with the man wearing headphones. Middle: edit.png from local SGLang with the enhanced prompt. Right: api_edit.png from the MiniMax API. In both results the headphones are gone and the hosts bump fists above the MONEY TALKS sign

Reference image reference1.png (left), edit.png from local SGLang (middle) and api_edit.png from the MiniMax API (right), 4096x4096 (1:1 picked by H3-Image-Context-IR)

Showcase

Text-to-image and image editing results, shown downscaled.

Three photorealistic photographs: a woman hanging white sheets on a rooftop at dusk under a full moon, a close-up profile of a curly-haired young man holding a cup, and flamingos wading in shallow water

Photorealistic photography

Three surreal editorial photographs: a barber trimming a cloud seated in a barber chair, a person slicing the moon on a lawn at night, and a model stepping out of a giant pear

Surreal editorial photography

Four environment concepts: ruins of an ancient open-air theater in a forest titled ENVIRONMENT CONCEPT: THE ANCIENT THEATER, a dragon rider on a red rock cliff, an abandoned railway station with an ARRIVALS sign, and shipwrecks frozen in an icy sea

Environment concepts

Characters, creatures and props: a soldier in a worn helmet and armor, a red-finned dragon-like creature in a forest, a weathered astronaut helmet on Mars, and a three-view character sheet of a figure in winter clothing

Characters, creatures and props

Four paintings and illustrations: mandarin ducks in a lotus pond in an oil painting style, a Jiangnan garden in light watercolor, tarot card XVIII THE MOON with a rabbit, and a Chinese gongbi painting of a pelican looking into a mirror with four calligraphy characters

Painting and illustration styles

Two logic puzzle boards: a Chinese candidate-selection puzzle with five conditions and the derived answer, and an English board titled CONFIDENTIAL FILE MISSING with six suspects, true/false stamps and a verification table

Text rendering with reasoning: logic puzzles in Chinese and English, solved correctly on the board

Left: untextured grey 3D render of a lunar base with habitat modules, a rover and an astronaut. Right: the same scene as a photorealistic film still on the lunar surface

Image editing, one reference: an untextured 3D render (left) turned into a film still of a lunar research base (right)

Left: illustrated game map with a river, a waterfall, bridges, a castle, a village, a mine and a harbor, and a red arrow on the southern lake. Right: first-person 3D game view from the lake towards the waterfall, the suspension bridge, the mine and the distant castle, with the map as a minimap in the top-left corner

Image editing, one reference: a game map (left) turned into a first-person 3D game view from the red arrow's position, with the map as a minimap (right)

Top: ten reference images, an empty sunlit room and nine pieces of furniture. Bottom: the empty room furnished with all nine pieces as a living room

Image editing, ten references: an empty room and nine pieces of furniture (top) composed into one living room (bottom)

License

MiniMax-H3-Image is released under the MiniMax-H3-Image Community License Agreement.
The T2I PE Model (MiniMax-H3-Image-PE) is part of MiniMax-H3-Image and is accordingly subject to MiniMax-H3-Image Community License Agreement.
The separate written authorization described in Section IV of the license is requested through Application form

Contact Us

Downloads last month: -

GGUF

Model size

20B params

Architecture

minimax_h3

Hardware compatibility

4-bit

5-bit

6-bit

8-bit

16-bit

Model tree for moonbox-ai/MiniMax-H3-Image-GGUF

Base model

MiniMaxAI/MiniMax-H3

Finetuned

MiniMaxAI/MiniMax-H3-Image

Quantized

(25)

this model