Reading the repo
Opening the box…
Reading the repo
Opening the box…
How to install on macOS
MiniMax-H3-Image, an open-weight model for 16-megapixel image generation and editing.
Saved setup from 4 h ago
Will it work on macOS?
| 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
…
Then run bash setup.sh. It stops at the first error and is safe to run again. Servers and tests aren't started; it lists them at the end. Read it first.
Needs Git: xcode-select --install
git clone https://github.com/MiniMax-AI/MiniMax-H3-Image.git cd MiniMax-H3-Image
Python 3
brew install python
In the maintainers' order. Do the README instructions above first — they cover steps outside the terminal.
hf download MiniMaxAI/MiniMax-H3-Image model_index.json "pdd_*" "processor/*" "tokenizer/*" \
"transformer/*" "vae/*"
hf download MiniMaxAI/MiniMax-H3 --include "text_encoder/*"
hf download MiniMaxAI/MiniMax-H3-Image-PE
python3 -m pip install -e 'python[diffusion]'
sglang serve --model-path MiniMaxAI/MiniMax-H3-Image --host 0.0.0.0 --port 30000 --warmup-mode off
sglang serve --model-path MiniMaxAI/MiniMax-H3-Image --host 0.0.0.0 --port 30000 --warmup-mode off \
--num-gpus 4 --ulysses-degree 4
uv venv --python 3.12 --seed && source .venv/bin/activate
uv pip install vllm==0.33.0 --torch-backend=cu130
vllm serve MiniMaxAI/MiniMax-H3-Image --omni --host 0.0.0.0 --port 8000 \
--num-gpus 4 --usp 4 --text-encoder-tp-size 4
vllm serve MiniMaxAI/MiniMax-H3-Image --omni --host 0.0.0.0 --port 8000 --num-gpus 1
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"]}'
python3 -c "from context_ir import size_for; print(size_for('5:4'))" # 4576x3648
export MINIMAX_API_BASE="https://api.minimax.io" # China: https://api.minimax.cn
export MINIMAX_API_KEY="<api-key>"No reports for macOS yet.
GitManual AI Agent reads the 1 key files and writes a step-by-step guide for macOS. Once written, it's saved for everyone.