{
  "hf_id": "MiniMaxAI/MiniMax-H3-Image",
  "meta": {
    "title": "MiniMax-H3-Image",
    "slug": "minimax-h3-image",
    "provider": "MiniMax",
    "description": "Open-weight text-to-image and reference-image editing on the MiniMax-H3 DiT — six CFG-distilled steps per image, up to nine reference images, 2K-class canvases, served via vLLM-Omni",
    "date_added": "2026-11-10",
    "date_updated": "2026-11-10",
    "tasks": [
      "omni"
    ],
    "performance_headline": "A 2720×1536 image in about 0.8 s and a 2048² edit in 1.35 s end to end on 4×H200",
    "default_hardware": "h200",
    "related_recipes": [
      "MiniMaxAI/MiniMax-H3"
    ],
    "hardware": {
      "h200": "verified",
      "rtx_pro_6000_2x": "verified",
      "rtx_pro_6000_4x": "verified"
    }
  },
  "model": {
    "model_id": "MiniMaxAI/MiniMax-H3-Image",
    "min_vllm_version": "0.33.0",
    "docker_image": "vllm/vllm-omni:minimax-h3-image",
    "architecture": "dense",
    "parameter_count": "67B",
    "active_parameters": "67B",
    "context_length": 0,
    "base_args": [
      "--host",
      "0.0.0.0",
      "--port",
      "8000",
      "--num-gpus",
      "4",
      "--usp",
      "4",
      "--text-encoder-tp-size",
      "4"
    ],
    "base_env": {},
    "install": {
      "pip": {
        "command": "uv venv --python 3.12 --seed && source .venv/bin/activate\nuv pip install vllm==0.33.0 --torch-backend=cu130\ngit clone https://github.com/vllm-project/vllm-omni.git && cd vllm-omni && uv pip install -e .\n",
        "note": "MiniMax-H3-Image support is in vLLM-Omni source; install it on top of vLLM 0.33.0."
      },
      "docker": {
        "command": "docker pull vllm/vllm-omni:minimax-h3-image",
        "note": "The image bundles vLLM 0.33.0 and vLLM-Omni with MiniMax-H3-Image support."
      }
    }
  },
  "omni": {
    "port": 8000,
    "tasks": [
      {
        "id": "t2i",
        "description": "Text to image. Six steps; requests smaller than 2048² are generated on a 2048²-area canvas and resized back. 0.77 s for 1024² and 0.88 s for 2048² end to end on 4×H200.",
        "curl": "curl -s http://localhost:8000/v1/images/generations \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"MiniMaxAI/MiniMax-H3-Image\",\n    \"prompt\": \"Documentary photograph of a lighthouse keeper on a cliff at dawn, Kodak Portra 400\",\n    \"size\": \"2720x1536\",\n    \"seed\": 42,\n    \"response_format\": \"b64_json\"\n  }' | jq -r '.data[0].b64_json' | base64 -d > t2i.png\n"
      },
      {
        "id": "i2i",
        "description": "Reference-image editing. One to nine references, presented to the model as Picture 1, Picture 2, … in upload order. 1.35 s for a 2048² edit on 4×H200.",
        "curl": "curl -s http://localhost:8000/v1/images/edits \\\n  -F model=MiniMaxAI/MiniMax-H3-Image \\\n  -F image=@cabin.png \\\n  -F 'prompt=<Picture 1> is a cabin by a lake. Everything is preserved exactly; only the season changes to a snowy winter evening.' \\\n  -F size=2720x1536 \\\n  -F seed=42 \\\n  -F response_format=b64_json | jq -r '.data[0].b64_json' | base64 -d > edit.png\n# Repeat -F image=@... for more references, in the order the prompt names them.\n"
      }
    ]
  },
  "features": {},
  "opt_in_features": [],
  "variants": {
    "default": {
      "precision": "bf16",
      "vram_minimum_gb": 153,
      "description": "BF16 checkpoint: 66 GB DiT, 67 GB Qwen3-VL text encoder, 2.3 GB FP32 VAE. Peak per GPU on H200: 81.3 GiB (SP 4), 52.2 GiB (TP 2 × SP 2), 36.2 GiB (TP 4), 63.3 GiB (2 GPUs, TP 2).",
      "hardware_overrides": {
        "h100": {
          "extra_args": [
            "--num-gpus",
            "4",
            "--tensor-parallel-size",
            "4",
            "--usp",
            "1",
            "--text-encoder-tp-size",
            "4"
          ]
        },
        "rtx_pro_6000_2x": {
          "extra_args": [
            "--num-gpus",
            "2",
            "--tensor-parallel-size",
            "2",
            "--usp",
            "1",
            "--text-encoder-tp-size",
            "2"
          ]
        }
      }
    },
    "dlo": {
      "label": "BF16 + DLO",
      "precision": "bf16",
      "vram_minimum_gb": 16,
      "description": "One GPU with distributed layerwise offload: the DiT and the text encoder stay in pinned host memory (about 124 GiB) and stream one block at a time. 14.7 GiB peak and 8.3 s per 2048² image on one H200.",
      "extra_args": [
        "--num-gpus",
        "1",
        "--usp",
        "1",
        "--text-encoder-tp-size",
        "1",
        "--diffusion-offload-config",
        "{\"mode\":\"layer\",\"components\":[\"dit\",\"text_encoder\"]}"
      ]
    }
  },
  "hardware_overrides": {},
  "guide": "## Overview\n\nMiniMax-H3-Image generates and edits images with the MiniMax-H3 DiT\n(33.1B, audio disabled), the base model's Qwen3-VL text encoder, a native\n2D-decoder image VAE and fused per-step PDD output heads. Every request runs\nsix CFG-distilled steps and returns one image. A request with reference\nimages is an edit; there is no task flag.\n\n| Component | Source | Precision | Parameters |\n|---|---|---|---|\n| DiT | `MiniMaxAI/MiniMax-H3-Image/transformer` | BF16 | 33.1B |\n| Text encoder (Qwen3-VL) | `MiniMaxAI/MiniMax-H3/text_encoder` | BF16 | 33.4B |\n| Image VAE | `MiniMaxAI/MiniMax-H3-Image/vae` | FP32 | 0.58B |\n\n`model_index.json` names the base repository for the text encoder; vLLM-Omni\ndownloads only that folder. Plan for about 127 GB of disk.\n\n## Request contract\n\n- `num_inference_steps`: omit or 6. `guidance_scale`: omit or 1.\n  `negative_prompt` is not supported. One image per request.\n- `size` defaults to `1024x1024`. Requests below 2048² pixels are generated on\n  a same-aspect canvas of at least 2048² (sides on a 32-pixel grid) and\n  resized back with LANCZOS. Requesting the canvas size directly (2048x2048,\n  2720x1536, 1536x2720, 2368x1760, 2496x1664, 3136x1344) skips the resize.\n- `extra_args.min_generation_area` overrides the canvas area per request\n  (32² to 4096²).\n- Edits: give references at the canvas size of the requested aspect ratio and\n  request that size for the best alignment; combine several changes into one\n  edit rather than chaining edits.\n\n## Deployment profiles\n\nAll rows were run on H200; the RTX PRO 6000 recipe has its own measurements.\nOther accelerators reuse these commands sized from the H200 peaks\n(configuration-only). DLO is `--diffusion-offload-config` with\n`mode: layer`.\n\n| GPUs | Profile | Extra flags | Peak / GPU | 2048² t2i |\n|---|---|---|---|---|\n| 1 | DiT resident, text encoder offloaded | `--num-gpus 1 --diffusion-offload-config '{\"mode\":\"layer\",\"components\":[\"text_encoder\"]}'` | 73.4 GiB | 3.2 s |\n| 1 | DLO, DiT and text encoder | `--num-gpus 1 --diffusion-offload-config '{\"mode\":\"layer\",\"components\":[\"dit\",\"text_encoder\"]}'` | 14.7 GiB | 8.3 s |\n| 2 | Ulysses SP 2, resident | `--num-gpus 2 --usp 2 --text-encoder-tp-size 2` | 94.6 GiB | 1.5 s |\n| 2 | Ulysses SP 2 + DLO (DiT AllGather) | `--num-gpus 2 --usp 2 --text-encoder-tp-size 2 --diffusion-offload-config '{\"mode\":\"layer\",\"components\":[\"dit\",\"text_encoder\"],\"layer_options\":{\"dit\":{\"weight_transfer\":\"allgather\"},\"text_encoder\":{\"weight_transfer\":\"rank-local\"}}}'` | 12.0 GiB | 5.6 s |\n| 2 | DiT TP 2, resident | `--num-gpus 2 --tensor-parallel-size 2 --usp 1 --text-encoder-tp-size 2` | 63.3 GiB | 1.5 s |\n| 4 | Ulysses SP 4, resident (default) | `--num-gpus 4 --usp 4 --text-encoder-tp-size 4` | 81.3 GiB | 0.88 s |\n| 4 | DiT TP 4, resident | `--num-gpus 4 --tensor-parallel-size 4 --usp 1 --text-encoder-tp-size 4` | 36.2 GiB | 1.0 s |\n\nFull single-GPU residency needs an estimated 135 GiB and was not measured; it\nis the natural choice on B200 and B300 (`--num-gpus 1`). On 80 GB H100, use DLO\non one or two GPUs, or TP 4 on four (SP 4 does not fit). On 96 GB RTX PRO 6000,\nevery resident layout fits (SP 2 peaks at 68.1 GiB, TP 2 at 49.7 GiB), and SP 4\nis the fastest four-GPU layout over PCIe. Keep `resident_layers` at 0:\n24 resident blocks ran at about 15 s per step on H200. CFG parallel and HSDP\nare rejected; model CPU offload, quantization and cache acceleration are not\nqualified.\n\n## Measured latency (4×H200, SP 4)\n\nMedian of three warm requests at concurrency 1, client end-to-end time:\n\n| Request | Latency |\n|---|---|\n| t2i 1024x1024 | 0.77 s |\n| t2i 2048x2048 | 0.88 s |\n| t2i 4736x3552 | 3.84 s |\n| edit 2048x2048 (one reference) | 1.35 s |\n\nPer-profile numbers and the correctness guard are in the in-repo recipe.\n\n## References\n\n- [Model card](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image)\n- [H200 recipe with measurements](https://github.com/vllm-project/vllm-omni/blob/main/recipes/MiniMaxAI/MiniMax-H3-Image-H200.md)\n- [MiniMax-H3 recipe](https://recipes.vllm.ai/MiniMaxAI/MiniMax-H3)\n",
  "source": {
    "source": "vllm-omni",
    "repo": "vllm-project/vllm-omni",
    "ref": "main",
    "sha": "d8751cd14a854369b5b349eb23c885f595d68ca5",
    "path": "recipes/models/MiniMaxAI/MiniMax-H3-Image.yaml",
    "edit_url": "https://github.com/vllm-project/vllm-omni/edit/main/recipes/models/MiniMaxAI/MiniMax-H3-Image.yaml",
    "overlays": []
  }
}