Instructions to use MiniMaxAI/MiniMax-H3-Image with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Libraries
- Diffusers
How to use MiniMaxAI/MiniMax-H3-Image with Diffusers:
pip install -U diffusers transformers accelerate
import torch from diffusers import DiffusionPipeline # switch to "mps" for apple devices pipe = DiffusionPipeline.from_pretrained("MiniMaxAI/MiniMax-H3-Image", dtype=torch.bfloat16, device_map="cuda") prompt = "Astronaut in a jungle, cold color palette, muted colors, detailed, 8k" image = pipe(prompt).images[0] - Notebooks
- Google Colab
- Kaggle
README: scope the download, fix the single-GPU vLLM-Omni command
Browse files- `hf download MiniMaxAI/MiniMax-H3-Image` now fetches about 204 GB, because the repository also holds the diffusers format (`transformer_diffusers/`, `vae_diffusers/`, `text_encoder/`). SGLang and vLLM-Omni only need the original checkpoint (68.7 GB) plus the MiniMax-H3 text encoder (66.7 GB). The new command downloads just those files. Checked with `--dry-run` on huggingface_hub 1.17.0 (30 files, 68.7 GB) and with a small real download on 0.35.3; both versions treat several positional names as patterns. Repeating `--include` per pattern would work on 1.x but keep only the last pattern on 0.x.
- The text encoder row said "Not in this repository", which is no longer true since the diffusers weights added `text_encoder/`.
- According to the [vLLM-Omni recipe](https://recipes.vllm.ai/MiniMaxAI/MiniMax-H3-Image), keeping the whole model on one GPU needs about 135 GiB, so the plain single-GPU command fits B200/B300 but not H200 or H100. Added the recipe's one-H200 profile, which offloads the text encoder.
|
@@ -127,7 +127,7 @@ into the image.
|
|
| 127 |
| `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 |
|
| 128 |
| `vae/` | Image VAE, FP32. | 2.34 GB |
|
| 129 |
| `tokenizer/`, `processor/` | Qwen3-VL tokenizer and processor, identical to MiniMax-H3. | 23 MB |
|
| 130 |
-
| Text encoder | Not
|
| 131 |
|
| 132 |
```text
|
| 133 |
MiniMax-H3-Image/
|
|
@@ -140,15 +140,21 @@ MiniMax-H3-Image/
|
|
| 140 |
└── vae/
|
| 141 |
```
|
| 142 |
|
| 143 |
-
|
|
|
|
|
|
|
| 144 |
|
| 145 |
```bash
|
| 146 |
-
hf download MiniMaxAI/MiniMax-H3-Image
|
| 147 |
hf download MiniMaxAI/MiniMax-H3 --include "text_encoder/*"
|
| 148 |
# optional prompt expander
|
| 149 |
hf download MiniMaxAI/MiniMax-H3-Image-PE
|
| 150 |
```
|
| 151 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 152 |
### Local Deployment
|
| 153 |
|
| 154 |
We recommend the following inference frameworks to serve the model:
|
|
@@ -164,12 +170,19 @@ See the [vLLM-Omni recipe](https://recipes.vllm.ai/MiniMaxAI/MiniMax-H3-Image) f
|
|
| 164 |
per-hardware deployment configurations and measured latency. Both NVIDIA and AMD accelerators are
|
| 165 |
supported, including NVIDIA H200, RTX PRO 6000 Blackwell, AMD Instinct MI350X and more.
|
| 166 |
|
| 167 |
-
Start the server on one GPU:
|
| 168 |
|
| 169 |
```bash
|
| 170 |
vllm serve MiniMaxAI/MiniMax-H3-Image --omni --host 0.0.0.0 --port 8000
|
| 171 |
```
|
| 172 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 173 |
For lower latency, split each request over several GPUs with sequence parallelism
|
| 174 |
(Ulysses), for example on 4 GPUs:
|
| 175 |
|
|
|
|
| 127 |
| `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 |
|
| 128 |
| `vae/` | Image VAE, FP32. | 2.34 GB |
|
| 129 |
| `tokenizer/`, `processor/` | Qwen3-VL tokenizer and processor, identical to MiniMax-H3. | 23 MB |
|
| 130 |
+
| Text encoder | Not part of the original checkpoint. `model_index.json` loads it from [`MiniMaxAI/MiniMax-H3`](https://huggingface.co/MiniMaxAI/MiniMax-H3), folder `text_encoder/`. If you already have MiniMax-H3, it is not downloaded again. | 66.7 GB |
|
| 131 |
|
| 132 |
```text
|
| 133 |
MiniMax-H3-Image/
|
|
|
|
| 140 |
└── vae/
|
| 141 |
```
|
| 142 |
|
| 143 |
+
The repository hosts this original checkpoint and the diffusers format side by side, so scope the
|
| 144 |
+
download to what your framework needs. Download the original checkpoint (SGLang, vLLM-Omni) and
|
| 145 |
+
the MiniMax-H3 text encoder into the Hugging Face cache:
|
| 146 |
|
| 147 |
```bash
|
| 148 |
+
hf download MiniMaxAI/MiniMax-H3-Image model_index.json "pdd_*" "processor/*" "tokenizer/*" "transformer/*" "vae/*"
|
| 149 |
hf download MiniMaxAI/MiniMax-H3 --include "text_encoder/*"
|
| 150 |
# optional prompt expander
|
| 151 |
hf download MiniMaxAI/MiniMax-H3-Image-PE
|
| 152 |
```
|
| 153 |
|
| 154 |
+
diffusers users do not need a manual download:
|
| 155 |
+
`ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3-Image")` fetches the diffusers-format
|
| 156 |
+
folders it needs.
|
| 157 |
+
|
| 158 |
### Local Deployment
|
| 159 |
|
| 160 |
We recommend the following inference frameworks to serve the model:
|
|
|
|
| 170 |
per-hardware deployment configurations and measured latency. Both NVIDIA and AMD accelerators are
|
| 171 |
supported, including NVIDIA H200, RTX PRO 6000 Blackwell, AMD Instinct MI350X and more.
|
| 172 |
|
| 173 |
+
Start the server on one GPU with about 135 GiB of free memory, such as B200 or B300:
|
| 174 |
|
| 175 |
```bash
|
| 176 |
vllm serve MiniMaxAI/MiniMax-H3-Image --omni --host 0.0.0.0 --port 8000
|
| 177 |
```
|
| 178 |
|
| 179 |
+
On one H200, offload the text encoder:
|
| 180 |
+
|
| 181 |
+
```bash
|
| 182 |
+
vllm serve MiniMaxAI/MiniMax-H3-Image --omni --host 0.0.0.0 --port 8000 --num-gpus 1 \
|
| 183 |
+
--diffusion-offload-config '{"mode":"layer","components":["text_encoder"]}'
|
| 184 |
+
```
|
| 185 |
+
|
| 186 |
For lower latency, split each request over several GPUs with sequence parallelism
|
| 187 |
(Ulysses), for example on 4 GPUs:
|
| 188 |
|