MiniMax-AI published the official MiniMax-H3-Image repository and Hugging Face weights in November 2026—a 33.1B-parameter distilled diffusion transformer for six-step, ~16 megapixel text-to-image and multi-reference editing. The release is the upstream source behind community ports such as Pruna's P-H3-Image, but it targets full resolution tables, SGLang/vLLM serving, and API parity with MiniMax's commercial image endpoints.
TL;DR
| Question | Answer |
|---|---|
| Steps / guidance | 6 NFE; guidance_scale 1 (others rejected on SGLang API) |
| Resolution focus | ~4–20 MP working range; ~16 MP sweet spot |
| Architecture | H3 DiT without audio; Qwen3-VL text encoder from MiniMax-H3 |
| Editing | Up to 16 reference images per README marketing claims |
| Optional PE model | MiniMax-H3-Image-PE prompt expander on Hugging Face |
| License | MiniMax-H3-Image Community License Agreement |
What the official repo adds beyond community ports
explainx.ai covered P-H3-Image when Pruna shipped an 8 MP, 8-step variant tuned for 21 GB VRAM ComfyUI quants. The MiniMax-AI repo is the canonical artifact:
- Size table from 4096×4096 through 6272×2688 (21:9) without an upscaler.
- Unified generation and editing in one checkpoint.
- PDD fused heads and sampling schedule shipped beside the transformer.
- Examples folder reproducing MiniMax API quality on local SGLang.
The README stresses instruction following and reference-image editing (showcase includes ten furniture references composed into one room). Those demos are vendor media—run your own prompts before trusting marketing stills.
Hardware and serving expectations
MiniMax's quick-start table is honest about scale:
| Component | Approx size |
|---|---|
transformer/ DiT BF16 | 66.28 GB |
| Image VAE | 2.34 GB |
| Text encoder (from MiniMax-H3) | ~66.7 GB |
That is datacenter-first, not laptop-first. Multi-GPU Ulysses sequence parallel in SGLang is documented for latency reduction.
Serving sketch from the README:
sglang serve --model-path MiniMaxAI/MiniMax-H3-Image --host 0.0.0.0 --port 30000 --warmup-mode off
Image API fields emphasize size as WIDTHxHEIGHT, seed, generator_device cpu for reproducible noise, and no negative prompts.
Compare deployment economics to Qwen-Image-PE prompt tooling and ByteDance Seedream editing loops: 16 MP six-step trades VRAM for per-pixel quality and edit consistency.
Prompt expansion: cloud API vs local PE
Quality parity with the commercial API relies on H3-Image-Context-IR prompt expansion. MiniMax documents:
- Cloud:
/v1/h3_image_context_irthen/v1/images/generationsor/v1/images/edits - Local: optional MiniMax-H3-Image-PE weights
The examples/ scripts download via hf download and demonstrate text-to-image and edit pipelines side by side with api_generate.py E2E calls.
Builders without expansion still generate, but README workflow assumes detailed English scene descriptions—short prompts underperform relative to API demos.
License and geography
Weights ship under the MiniMax-H3-Image Community License Agreement. Section references in the README point to platform.minimax.io/license for separate written authorization in restricted regions.
Treat compliance like any geo-fenced open model: legal review before SaaS, not only VRAM checks.
How to evaluate against closed APIs
| Axis | What to test |
|---|---|
| Text in image | README highlights bilingual logic puzzles—verify on your fonts |
| Multi-reference edit | Order matters; maps to <Picture n> slots |
| Throughput | Six steps help, but 16 MP pixels dominate bandwidth |
| Identity drift | Long edit chains on faces—pair with your policy |
If you need smaller footprints, keep P-H3-Image as a derived path; if you need official sizing and heads, start from MiniMaxAI/MiniMax-H3-Image.
Model quantization and memory tradeoffs when serving large open image checkpoints locally
Size matrix from the README
MiniMax documents 16 MP-class widths/heights without a separate upscaler:
| Aspect | Width × height (pixels) |
|---|---|
| 1:1 | 4096 × 4096 |
| 4:3 | 4736 × 3552 |
| 3:4 | 3552 × 4736 |
| 3:2 | 5024 × 3360 |
| 2:3 | 3360 × 5024 |
| 16:9 | 5472 × 3072 |
| 9:16 | 3072 × 5472 |
| 21:9 | 6272 × 2688 |
The API accepts arbitrary WIDTHxHEIGHT strings within the documented 4–20 MP working band. min_generation_area defaults to 4194304 (2048×2048): smaller targets render on a larger canvas and LANCZOS resize down unless you pass 1024 to disable the behavior.
Architecture notes for integrators
From the README's model zoo and architecture sections:
- DiT: 33.1B parameters, 50 layers, BF16 weights with FP32 embeddings and timestep layers.
- VAE: 16× spatial downsampling, 24 latent channels; 2×2 patchification → 32×32 pixel footprint per token.
- Text: unchanged Qwen3-VL encoder from MiniMax-H3 (layer 50 hidden states feed the DiT).
PDD fused heads replace a monolithic output layer and ship beside pdd_config.json—serving stacks must load both or reject requests.
Optional MiniMax-H3-Image-PE adds NVFP4 prompt expansion (~17.9 GB in the model table).
Serving back ends compared
| Stack | When to pick it |
|---|---|
| SGLang | Production HTTP API parity with README examples |
| vLLM | Existing vLLM fleets already running image recipes |
| diffusers | Research notebooks and custom schedulers |
| ComfyUI | Artist workflows with T2I/Edit templates |
SGLang rejects num_inference_steps ≠ 6 and guidance_scale ≠ 1 with HTTP 400—hard constraints, not suggestions.
Multi-GPU example uses --ulysses-degree 4 on four GPUs to split sequence parallel. Budget network NVLink/PCIe bandwidth when you chase sub-10s 16 MP renders.
Editing workflow and reference order
Multi-reference image editing workflow for MiniMax-H3-Image server deployments
Multipart /v1/images/edits uploads define <Picture 1>, <Picture 2>, … in file order. Prompts must reference those indices explicitly.
The README's ten-furniture compose demo is the stress test: many references → attention load and identity consistency challenges. Start with one or two references before building production RAG-style asset pipelines.
Cloud H3-Image-Context-IR rewrites short prompts into detailed English scene specs and proposes aspect/size. Local PE weights aim to remove cloud dependency but add another ~18 GB class download.
Cost and ops checklist
- Cache the text encoder once if you already run MiniMax-H3 video—README says HF will not re-download.
- Pin seeds with
generator_device: cpuwhen auditing reproducibility across machines. - Log per-megapixel latency separately from step count—pixels dominate at 16 MP.
- Read license geography before customer-facing SaaS.
- Compare quantized community ports (P-H3-Image) when 80+ GB BF16 is impossible.
Failure modes to expect in first runs
| Symptom | Likely cause |
|---|---|
| HTTP 400 on steps | Non-six step count sent to SGLang |
| OOM at 16 MP | Full BF16 DiT on single GPU |
| Washed edits | Missing Context-IR / PE expansion |
| Wrong object moved | Reference index mismatch in edit prompt |
| Slow cold start | Parallel text encoder load from separate repo |
Relationship to the H3 video stack
MiniMax-H3-Image reuses the H3 text encoder and removes audio layers from the DiT. It does not output video frames. Video workflows stay on MiniMax-H3 proper and separate serving stacks.
For multimodal product teams, that split mirrors how labs ship narrow open weights (image-only) while keeping full omni checkpoints API-gated.
Related on explainx.ai
- P-H3-Image Pruna port
- Qwen-Image-PE visual prompt enhancer
- LongBanana multi-reference benchmark
- ByteDance Seedream 5.5 editing
- Adobe EditAgent verification
- Hugging Face Transformers GGUF parity
- Multimodal vision token budget guide
Example scripts and API parity
The examples/ directory is the fastest truth test against MiniMax cloud APIs:
context_ir.pycalls H3-Image-Context-IR to producerevised_prompt.txtandrevised_size.txt.t2i.py/edit.pyhit local SGLang with those artifacts.api_generate.pyruns the same prompts against hosted MiniMax endpoints for side-by-side PNGs.
README walkthroughs cite 4736×3552 and 4096×4096 outputs where local SGLang and API images are shown adjacently. Your parity test should hash PNGs only after matching seed, size, and expansion paths—otherwise you will chase irrelevant diffusion noise.
Environment variables:
MINIMAX_API_BASE—https://api.minimax.io(global) orhttps://api.minimax.cn(China).MINIMAX_API_KEY— platform key for Context-IR and generations.
Operators running air-gapped clusters can skip cloud steps and rely on PE weights, accepting quality drift if expansion differs.
Commercial surfaces named in the README
MiniMax points builders to:
- Global API:
platform.minimax.io - China API:
platform.minimax.cn - Web apps:
hailuoai.video/hailuoai.com - Desktop agents:
agent.minimax.io/agent.minimax.cn
Open weights do not automatically entitle hosted quota or enterprise SLAs. Treat the repo as bring-your-own-GPU, same as other community-license releases from Asian labs.
Benchmarks and comparisons readers ask for
| Comparison axis | What to measure yourself |
|---|---|
| vs P-H3-Image | MP count, VRAM, license geography |
| vs Seedream editing loops | Multi-round identity on product photos |
| vs Firefly enterprise | Legal indemnity vs open weights |
| vs Flux-class speed | Wall-clock at equal megapixels, not step count alone |
No independent Artificial Analysis row existed at publish time for MiniMax-H3-Image specifically—run LongBanana-style multi-reference tests if that is your workload.
Skills and prompt-writing assets in the repo
The GitHub tree includes skills/h3-image-prompt-writing — vendor-authored guidance for long-form English scene descriptions. If your team fine-tunes internal tools, mirror that structure in your own agent skills (explainx.ai skills directory) so operators do not improvise prompts that fight the Context-IR contract.
Showcase README sections (photorealistic, surreal editorial, environment concepts, characters, painting styles, text rendering, multi-reference edits) double as regression galleries. Re-run a subset weekly after pulling new commits; upstream PDD head changes can shift color and typography even when DiT weights are unchanged.
For teams already running ComfyUI graphs for Pruna, plan a parallel graph wired to official T2I/Edit templates before decommissioning the quantized path—license text differs even when tensors are related.
Document which checkpoint produced each marketing asset today. Legal and compliance teams increasingly ask for model lineage on AI-generated hero images, not only for people photos.
A practical rollout order helps. First, run the README examples unchanged on one GPU node and record latency, memory use, and output hashes. Second, repeat the same prompts with your own brand terms and reference images. Third, compare the results with your current image vendor on the same prompts. Only then decide whether the open weights replace, or sit beside, your hosted provider.
Support and escalation paths
README lists model@minimax.io for questions. For production, document your rollback path to API generation when local SGLang versions drift from pdd_config.json expectations after upstream commits.
Repository layout and size figures follow the MiniMax-AI README as of November 2026.