Metadata-Version: 2.4
Name: mmh3-image
Version: 0.1.1
Summary: MiniMax-H3-Image GGUF on ComfyUI: one command to download and generate.
Author: yunfengwang
License: MIT
Project-URL: Model (GGUF), https://huggingface.co/Abiray/MiniMax-H3-Image-GGUF
Project-URL: Model (original), https://huggingface.co/MiniMaxAI/MiniMax-H3-Image
Keywords: minimax,h3,text-to-image,gguf,comfyui,dit
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: huggingface_hub>=0.23
Dynamic: license-file

# mmh3-image

MiniMax-H3-Image (33B DiT, GGUF) as a one-command CLI. It installs a private
ComfyUI with the GGUF loader, downloads the quantization you pick plus the
required 24-channel VAE and Qwen3-VL-32B text encoder, starts the server and
writes a PNG. Everything is cached, so only the first run pays the setup cost.

```bash
uvx --from mmh3-image mmh3-image "a clay badger baker outside a tiny bakery, warm lantern light" -o badger.png
```

## What it sets up

* `~/.cache/mmh3-image/ComfyUI` — ComfyUI checkout, venv, ComfyUI-GGUF node
* `~/.cache/mmh3-image/models` — DiT GGUF, text encoder, VAE
* an `extra_model_paths.yaml` in that checkout pointing at the cache

Need `git` and Python 3.9+. Weights are 20–28 GB and the model needs roughly
24 GB of RAM or VRAM; Apple silicon uses MPS, NVIDIA uses CUDA.

## Usage

```bash
# recommended quantization, native-quality 2048px
mmh3-image "prompt" -q q4 -r 2048

# smallest weights, 16:9 at 1080p, fixed seed
mmh3-image "prompt" -q q2 -r 1080p --seed 42 -o shot.png

# 4K still (slow: about 12 min on an M5 Pro)
mmh3-image "prompt" -r 4k -s 6

# prefetch only, no generation
mmh3-image -q q5 --download-only

# reuse an existing ComfyUI checkout or an already running server
mmh3-image "prompt" --comfyui ~/projects/ComfyUI
mmh3-image "prompt" --server-url http://127.0.0.1:8188
```

`-r` takes a preset (`720p`, `1080p`, `1440p`, `4k`, `square`), a single number
for a square, or `WIDTHxHEIGHT`. Values snap to 32 pixels, which is why `1080p`
is `1920x1088` — 1080 is not a multiple of 32 and would otherwise be floored.

Defaults matter for this model: **6 steps**, `euler` / `simple`, **CFG 1.0**.
It is a distilled 6-step model; more steps or a higher CFG degrade the result.

## Quantizations

| `-q` | File | Size | Notes |
|---|---|---|---|
| `q2` | Q2_K | 6.9 GB | smallest, but **unusable** on this model — output melts into smears |
| `q3` | Q3_K_M | 8.9 GB | 12 GB VRAM |
| `q4s` | Q4_K_S | 11.6 GB | fast 4-bit |
| `q4` | Q4_K_M | 11.6 GB | recommended sweet spot (default) |
| `q5` | Q5_K_M | 14.1 GB | closest to BF16 |

Text encoder: `--text-encoder q3` (12 GB, default) or `q4` (14.6 GB).

## List everything

```bash
mmh3-image --list
```

## Notes

* Weights come from [`Abiray/MiniMax-H3-Image-GGUF`](https://huggingface.co/Abiray/MiniMax-H3-Image-GGUF)
  and [`Comfy-Org/MiniMax-H3-Image`](https://huggingface.co/Comfy-Org/MiniMax-H3-Image).
  The model itself is under the MiniMax-H3-Image Community License; this CLI is
  MIT and ships code only.
* `--hf-endpoint https://hf-mirror.com` switches the download mirror.
* The CLI leaves the server running only with `--keep-server`; `--serve` skips
  generation and just serves.
* The package does not enable the optional Qwen3.5-9B prompt-expansion branch;
  the prompt is used verbatim, which is what the model card examples assume.
