README проекта с github.com/MiniMax-AI/MiniMax-H3-Image. Одним файлом markdown: README.md.
One idea with open weights. A world of uses.
Prompt Writing Skill · Showcase · Use Online · Overview · Run Locally · Prompting Tips · License
The h3-image-prompt-writing skill turns a short idea, a brief or a set of reference images into a
full MiniMax-H3-Image prompt, and can render it through the MiniMax API. It works in any agent that
reads a SKILL.md, such as Claude Code, Codex and Cursor. Install it with the
skills CLI:
npx skills add https://github.com/MiniMax-AI/MiniMax-H3-Image --skill h3-image-prompt-writing
Then ask your agent, for example:
Use h3-image-prompt-writing to make a 3:4 poster of a night market in the rain,
titled "雨夜集市", and render it.
Rendering needs MINIMAX_API_KEY, and MINIMAX_API_BASE=https://api.minimax.cn on the China
platform. See skills/README.md for details.
Select an image to see it larger with its prompt, or browse by section.
| Global | China | |
|---|---|---|
| Web app | hailuoai.video | hailuoai.com |
| Desktop app | agent.minimax.io | agent.minimax.cn |
| API platform | platform.minimax.io | platform.minimax.cn |
| API reference | Text-to-image · Image editing · Prompt expansion | Text-to-image · Image editing · Prompt expansion |
MiniMax-H3-Image is a state-of-the-art open-source model for image generation and editing from the MiniMax H3 family, with text-to-image and multi-image editing in one checkpoint.
These are the specifications of the MiniMax API. A local server takes the fields in Request Parameters.
| Parameter | Specification |
|---|---|
| Model ID | MiniMax-H3-Image |
| Tasks | Text-to-image, image editing |
| Image size | width + height, or area + aspect_ratio. Default auto: 4K area, automatic aspect ratio |
| Output area | 1K, 2K or 4K (best results 👍); a custom width × height covers 655,360 to 20,000,000 pixels |
| Aspect ratio | 1:3 to 3:1 |
| Prompt | Up to 32,000 characters; content beyond 4,096 tokens is truncated |
| Reference images | Up to 16, each at most 64 MiB, with sides of 128 to 8192 pixels and an aspect ratio from 1:4 to 4:1 |
| Reference formats | JPG, PNG, WebP, HEIC or HEIF, sent as an HTTP(S) URL, Base64 or MiniMax file ID |
| Images per request | 1 to 10 |
| Prompt expansion | On by default for text-to-image and can be turned off; always on for image editing; the expanded prompt can be returned |
| Output | PNG (default), JPEG or WebP, with output_compression from 0 to 100; returned as a URL (default) or Base64 |
| Not yet supported | Mask-based inpainting, transparent backgrounds, user-specified seeds, preview images |
| 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 |
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.
| Component | Content | Size |
|---|---|---|
transformer/ |
DiT weights. | 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 part of the original checkpoint. 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 |
The Hugging Face repository holds this original checkpoint alongside the diffusers format, about 204 GB in total. SGLang and vLLM-Omni need only the original checkpoint and the MiniMax-H3 text encoder, about 135 GB:
hf download MiniMaxAI/MiniMax-H3-Image model_index.json "pdd_*" "processor/*" "tokenizer/*" \
"transformer/*" "vae/*"
hf download MiniMaxAI/MiniMax-H3 --include "text_encoder/*"
# optional prompt expander
hf download MiniMaxAI/MiniMax-H3-Image-PE
diffusers fetches its own files with ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3-Image").
We recommend the following inference frameworks to serve the model:
Install SGLang from the main branch with its diffusion dependencies (installation guide):
git clone https://github.com/sgl-project/sglang.git
cd sglang
python3 -m pip install -e 'python[diffusion]'
Serve on one GPU (SGLang offloads model components when less than 130 GiB is free), or split each request over several GPUs with sequence parallelism (Ulysses) for lower latency:
sglang serve --model-path MiniMaxAI/MiniMax-H3-Image --host 0.0.0.0 --port 30000 --warmup-mode off
# 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
Add --text-encoder-path <path to text_encoder> to use a local copy of the MiniMax-H3 text encoder.
The SGLang cookbook has
recipes for other GPUs, from B300 down to 12 GB cards.
Install vLLM 0.33.0, then vLLM-Omni from source:
uv venv --python 3.12 --seed && source .venv/bin/activate
uv pip install vllm==0.33.0 --torch-backend=cu130
git clone https://github.com/vllm-project/vllm-omni.git && cd vllm-omni && uv pip install -e .
Serve on 4 GPUs with sequence parallelism (Ulysses), or on one GPU: a B200 or B300 holds the whole model in about 135 GiB, and one H200 offloads the text encoder:
vllm serve MiniMaxAI/MiniMax-H3-Image --omni --host 0.0.0.0 --port 8000 \
--num-gpus 4 --usp 4 --text-encoder-tp-size 4
# one B200 or B300
vllm serve MiniMaxAI/MiniMax-H3-Image --omni --host 0.0.0.0 --port 8000 --num-gpus 1
# one H200: offload the text encoder
vllm serve MiniMaxAI/MiniMax-H3-Image --omni --host 0.0.0.0 --port 8000 --num-gpus 1 \
--diffusion-offload-config '{"mode":"layer","components":["text_encoder"]}'
The vLLM-Omni recipe covers AMD Instinct and other GPUs.
SGLang takes text-to-image requests as JSON at /v1/images/generations and image editing requests
as multipart form data at /v1/images/edits; both return the PNG in data[0].b64_json. vLLM-Omni
takes slightly different fields; see its recipe.
| Field | Text-to-image | Image editing | Notes |
|---|---|---|---|
prompt |
Required | Required | Used as given, truncated to 4096 tokens |
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 |
The model works at about 4 MP to 20 MP and generally gives the best results at about 16 MP. Common 16 MP sizes:
| 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 |
For another aspect ratio, keep about 16 MP with both sides a multiple of 32. size_for() in
examples/context_ir.py computes it:
cd MiniMax-H3-Image/examples
python3 -c "from context_ir import size_for; print(size_for('5:4'))" # 4576x3648
The MiniMax API expands a short prompt in any language into a detailed English description of the
whole image with H3-Image-Context-IR before generating. A local server uses the prompt as
given, so expand it first, as in the cases below. The scripts in examples/ reproduce
the API results with the SGLang server above, using only the Python standard library:
git clone https://github.com/MiniMax-AI/MiniMax-H3-Image.git
cd MiniMax-H3-Image/examples
export MINIMAX_API_BASE="https://api.minimax.io" # China: https://api.minimax.cn
export MINIMAX_API_KEY="<api-key>"
t2i.py and edit.py send requests to http://127.0.0.1:30000; pass --url to use another
address.
| 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 | |
| agent alternative: h3-image-prompt-writing | Ask your agent to write a prompt and an aspect ratio for instruction.t2i.txt with the skill | Save the prompt as revised_prompt.txt and the size for that 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)
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) |
| Prompt Enhancement, agent alternative: h3-image-prompt-writing | Ask your agent to rewrite instruction.edit.txt for reference1.png with the skill |
Save the prompt as revised_prompt.txt and 4096x4096 as revised_size.txt |
| 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)
These tips from the official user guide apply to the MiniMax API and to a local server alike; the Prompt Writing Skill follows them for you.
Contact us at [email protected].