yasutoshi-lab/MiniMax-H3-Image-GGUF

MiniMax-H3-Image GGUF

MiniMaxAI/MiniMax-H3-Image（revision 5f90473）を GGUF に量子化したものです。MiniMax 公式の配布物ではありません。

ライセンスと利用できる地域：このリポジトリのファイルは MiniMax-H3-Image Community License Agreement（LICENSE）に従います。このライセンスは、欧州連合・英国・韓国・米国（Excluded Territories）での利用・複製・配布を認めていません。詳細はライセンスページをご覧ください。

元のモデルから変更した点（ライセンス III.2 による表示）

このリポジトリのファイルは、元のモデルのファイルを次のとおり変更しています。学習などによる重みの変更はしていません。

• DiT（transformer/）：stable-diffusion.cpp が読める 1 ファイルにまとめ、量子化しました。
  • AdaLN：6 ステップの PDD で使う 7 つの時刻（6 つの sigma と参照画像の 0.999）の出力をあらかじめ計算し、表（adaln_t_table）にしました。このため、PDD の 6 ステップ（--sigmas minimax-h3-image）以外の時刻では使えません。time_embedder.* は含みません。
  • 出力ヘッド：pdd_fused_heads.safetensors の 6 本を、stable-diffusion.cpp の形式（0 番 = ヘッド 0、k 番 = ヘッド k − ヘッド 0）で final_layer.video_out に入れました。
  • attn.qkv_proj.weight：行の並びを [heads, (q,k,v), head_dim] から [(q,k,v), heads, head_dim] に並べ替えました。
• TE（text_encoder/）：Qwen3-VL-32B のテキスト部を、MiniMax-H3-Image が使う 50 層に切り（層 50〜63 を削除）、llama.cpp で量子化しました。ビジョン部は mmproj-F16.gguf です。IQ 系は imatrix を使っています。
• VAE（vae/）：公式の VAE を変更せず、そのまま置いています。

ファイルのハッシュは SHA256SUMS にあります。

組み合わせたときの合計容量

DiT・TE を同じ量子化で組み合わせたときの、ファイルの合計容量です（GB = 10^9 バイト）。VAE（2.34 GB）はどの組み合わせでも同じものを使います。

DiT	TE	DiT (GB)	TE (GB)	合計 (GB) （DiT + TE + VAE）	画像編集時の合計 (GB) （+ mmproj-F16.gguf）
BF16	BF16	40.32	51.88	94.54	95.73
Q8_0	Q8_0	21.54	27.56	51.44	52.63
Q6_K	Q6_K	16.68	21.28	40.30	41.50
Q5_K_M	Q5_K_M	15.08	18.39	35.81	37.00
Q4_K_M	Q4_K_M	12.77	15.68	30.78	31.97
IQ4_XS	IQ4_XS	10.89	14.05	27.28	28.48
IQ3_S	IQ3_S	8.86	11.49	22.68	23.88
IQ3_XXS	IQ3_XXS	7.92	10.21	20.46	21.66
IQ2_S	IQ2_S	6.66	8.40	17.40	18.60
IQ2_XS	IQ2_XS	6.04	7.95	16.32	17.52

• 画像編集（参照画像あり）では、TE のビジョン部 text_encoder/mmproj-F16.gguf（1.20 GB）も読み込みます。
• 実行時のメモリ使用量は、ファイルの容量とは一致しません。

低精度の量子化について：Q8_0〜Q4_K_M は BF16 と同じ構図を保ちます。IQ4_XS・IQ3 系は構図が変わりやすくなります。IQ2 系は文字からの生成が崩れます（画像編集は IQ2_S までおおむね保たれます）。劣化は主に DiT の量子化によるもので、TE は Q5_K_M まで画質にほとんど影響しません。

使い方の例（stable-diffusion.cpp）

DiT と TE を Q4_K_M にした例です。stable-diffusion.cpp 32d516c で確かめました。

hf download yasutoshi-lab/MiniMax-H3-Image-GGUF \
  transformer/DiT-Q4_K_M.gguf text_encoder/TE-Q4_K_M.gguf text_encoder/mmproj-F16.gguf \
  vae/config.json vae/diffusion_pytorch_model.safetensors --local-dir h3-image-gguf
G=h3-image-gguf

# 文字から画像を作る
sd-cli --diffusion-model $G/transformer/DiT-Q4_K_M.gguf --llm $G/text_encoder/TE-Q4_K_M.gguf \
  --vae $G/vae/diffusion_pytorch_model.safetensors \
  -p "A red apple on a wooden table, soft window light, photorealistic" \
  --sigmas minimax-h3-image --steps 6 --cfg-scale 1.0 --sampling-method euler \
  -W 1024 -H 1024 -o apple.png

# 画像を編集する（TE のビジョン部 mmproj と参照画像 -r を足す）
sd-cli --diffusion-model $G/transformer/DiT-Q4_K_M.gguf --llm $G/text_encoder/TE-Q4_K_M.gguf \
  --llm_vision $G/text_encoder/mmproj-F16.gguf --vae $G/vae/diffusion_pytorch_model.safetensors \
  -r apple.png -p "Edit <Picture 1>. Replace the red apple with a green pear. Keep everything else unchanged." \
  --sigmas minimax-h3-image --steps 6 --cfg-scale 1.0 --sampling-method euler \
  -W 1024 -H 1024 -o pear.png

• ステップ数は 6 から変えられません（AdaLN を 6 ステップの時刻だけの表にしているため）。

動作確認

DiT 10 種 × TE 10 種のうち 28 構成で、文字からの生成と画像編集を stable-diffusion.cpp で行い、すべて画像が出ることを確かめました。

• GPU：NVIDIA RTX PRO 6000 96GB
• stable-diffusion.cpp 32d516c、llama.cpp aa75ff323

以下は公式のモデルカード（MiniMaxAI/MiniMax-H3-Image、revision 5f90473）の引用です。

---

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.

1. 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.
2. 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.
3. 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)
	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

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

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.

Photorealistic photography

Surreal editorial photography

Environment concepts

Characters, creatures and props

Painting and illustration styles

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

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

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)

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

Contact us at model@minimax.io.