mmh3-image 0.1.0__tar.gz

mmh3_image-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yunfengwang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mmh3_image-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: mmh3-image
+Version: 0.1.0
+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, fits 8–10 GB VRAM |
+| `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.

mmh3_image-0.1.0/README.md

@@ -0,0 +1,76 @@
+# 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, fits 8–10 GB VRAM |
+| `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.

mmh3_image-0.1.0/mmh3_image/__init__.py

@@ -0,0 +1,3 @@
+"""MiniMax-H3-Image GGUF text-to-image on a local ComfyUI, from one command."""
+
+__version__ = "0.1.0"

mmh3_image-0.1.0/mmh3_image/cli.py

@@ -0,0 +1,211 @@
+"""``mmh3-image``: MiniMax-H3-Image GGUF text-to-image from one command.
+
+    mmh3-image "a clay badger baker outside a tiny bakery" -o badger.png
+
+The first run installs ComfyUI into ``~/.cache/mmh3-image/ComfyUI`` (Python
+venv plus the ComfyUI-GGUF node), downloads the selected quantization and the
+required companions (24-channel image VAE, Qwen3-VL-32B text encoder), starts
+a local ComfyUI server and writes the PNG. Later runs reuse everything.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import random
+import sys
+import time
+
+from . import __version__
+
+#: Resolutions in the model's native multiples of 32. 1080p is 1920x1088
+#: because 1080 is not a multiple of 32; the model would floor it to 1072.
+PRESETS = {
+    "720p": (1280, 736),
+    "1080p": (1920, 1088),
+    "1440p": (2560, 1440),
+    "4k": (4096, 4096),
+    "square": (1024, 1024),
+}
+
+
+def build_parser():
+    from .download import QUANTS, TEXT_ENCODERS
+
+    parser = argparse.ArgumentParser(
+        prog="mmh3-image",
+        description="MiniMax-H3-Image (GGUF) text-to-image via a local ComfyUI.",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    parser.add_argument("prompt", nargs="?", help="the prompt (dense English works best)")
+    parser.add_argument("--prompt-file", default=None, help="read the prompt from a file")
+    parser.add_argument("-o", "--output", default=None,
+                        help="output PNG path (default: mmh3-image-<seed>.png)")
+
+    model = parser.add_argument_group("model")
+    model.add_argument("-q", "--quant", default="q4", choices=sorted(QUANTS),
+                       help="DiT quantization: " + ", ".join(
+                           f"{k}={v[2]}" for k, v in QUANTS.items()))
+    model.add_argument("--text-encoder", default="q3", choices=sorted(TEXT_ENCODERS),
+                       help="Qwen3-VL-32B text encoder quantization")
+    model.add_argument("--cache-dir", default=None,
+                       help="where weights and ComfyUI live (default: ~/.cache/mmh3-image)")
+    model.add_argument("--hf-endpoint", default=None,
+                       help="Hub endpoint, e.g. https://hf-mirror.com")
+    model.add_argument("--download-only", action="store_true",
+                       help="fetch ComfyUI and the weights, then exit")
+
+    size = parser.add_argument_group("size")
+    size.add_argument("-r", "--resolution", default="1024",
+                      help="a preset (" + ", ".join(PRESETS) + "), a single number "
+                           "for a square, or WIDTHxHEIGHT; values snap to 32")
+    size.add_argument("--width", type=int, default=None, help="override width")
+    size.add_argument("--height", type=int, default=None, help="override height")
+
+    sample = parser.add_argument_group("sampling")
+    sample.add_argument("-s", "--steps", type=int, default=6,
+                        help="denoise steps; the distilled model is calibrated for 6")
+    sample.add_argument("--seed", type=int, default=None,
+                        help="seed (default: random; the used seed is printed)")
+    sample.add_argument("--sampler", default="euler", help="KSampler sampler name")
+    sample.add_argument("--scheduler", default="simple", help="KSampler scheduler")
+    sample.add_argument("--cfg", type=float, default=1.0,
+                        help="CFG scale; 1.0 is correct, higher values degrade")
+
+    run = parser.add_argument_group("runtime")
+    run.add_argument("--comfyui", default=None,
+                     help="existing ComfyUI checkout to use instead of the cache one")
+    run.add_argument("--server-url", default=None,
+                     help="use an already running ComfyUI (skips install and download)")
+    run.add_argument("--dit-name", default=None, help="override DiT filename on that server")
+    run.add_argument("--te-name", default=None, help="override text encoder filename")
+    run.add_argument("--vae-name", default=None, help="override VAE filename")
+    run.add_argument("--port", type=int, default=8188)
+    run.add_argument("--keep-server", action="store_true",
+                     help="leave the ComfyUI server running after the image is saved")
+    run.add_argument("--serve", action="store_true",
+                     help="only prepare everything and run the server in the foreground")
+    run.add_argument("--timeout", type=float, default=3600.0,
+                     help="generation timeout in seconds")
+    run.add_argument("--quiet", action="store_true", help="only print errors")
+
+    parser.add_argument("--list", action="store_true", help="show quantizations and exit")
+    parser.add_argument("--version", action="version", version=f"mmh3-image {__version__}")
+    return parser
+
+
+def resolve_size(spec, width=None, height=None):
+    """Turn a preset / ``1024`` / ``1920x1088`` into 32-aligned (w, h)."""
+    if width and height:
+        w, h = width, height
+    elif spec in PRESETS:
+        w, h = PRESETS[spec]
+    elif "x" in spec.lower():
+        left, right = spec.lower().split("x", 1)
+        w, h = int(left), int(right)
+    else:
+        w = h = int(spec)
+    snap = lambda n: max(32, round(n / 32) * 32)
+    return snap(w), snap(h)
+
+
+def main(argv=None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    from .download import QUANTS, TEXT_ENCODERS, describe, ensure_models
+
+    if args.list:
+        print(f"mmh3-image {__version__}\n")
+        print("quantizations (DiT):")
+        for key in sorted(QUANTS):
+            filename, size, note = QUANTS[key]
+            print(f"  {key:<4} {size / 1e9:5.2f} GB  {note}")
+        print("\ntext encoders (Qwen3-VL-32B):")
+        for key in sorted(TEXT_ENCODERS):
+            _, _, size, note = TEXT_ENCODERS[key]
+            print(f"  {key:<4} {size / 1e9:5.2f} GB  {note}")
+        print("\npresets:", ", ".join(f"{k}={v[0]}x{v[1]}" for k, v in PRESETS.items()))
+        return 0
+
+    quiet = args.quiet
+
+    def say(message):
+        if not quiet:
+            print(message, flush=True)
+
+    prompt = args.prompt
+    if args.prompt_file:
+        with open(args.prompt_file, encoding="utf-8") as handle:
+            prompt = handle.read().strip()
+    if not prompt and not (args.download_only or args.serve):
+        parser.error("no prompt given")
+
+    seed = args.seed if args.seed is not None else random.randint(0, 2**31 - 1)
+    width, height = resolve_size(args.resolution, args.width, args.height)
+    output = args.output or f"mmh3-image-{seed}.png"
+
+    diT = QUANTS[args.quant][0]
+    text_encoder = TEXT_ENCODERS[args.text_encoder][1]
+
+    models_root = None
+    server = None
+    if args.server_url:
+        url = args.server_url.rstrip("/")
+        diT = args.dit_name or diT
+        text_encoder = args.te_name or text_encoder
+        vae_name = args.vae_name or "minimax_h3_image_vae_fp16.safetensors"
+        say(f"[mmh3-image] using running server {url}")
+    else:
+        from . import comfy
+
+        root = comfy.ensure_comfyui(args.comfyui, quiet=quiet)
+        from .download import cache_root
+        cache = cache_root(args.cache_dir)
+        models = os.path.join(cache, "models")
+        say(f"[mmh3-image] ComfyUI: {root}")
+        say(f"[mmh3-image] weights: {models}")
+        say(f"[mmh3-image] {describe(args.quant, args.text_encoder)}")
+        paths = ensure_models(args.quant, args.text_encoder, cache_dir=cache,
+                              endpoint=args.hf_endpoint, quiet=quiet)
+        if args.download_only:
+            say("[mmh3-image] downloads complete")
+            return 0
+        vae_name = os.path.basename(paths["vae"])
+        comfy.write_extra_model_paths(root, models, quiet=quiet)
+        if not comfy.server_ready(f"http://127.0.0.1:{args.port}"):
+            server = comfy.start_server(root, args.port, quiet=quiet)
+        url = f"http://127.0.0.1:{args.port}"
+
+    if args.serve:
+        say(f"[mmh3-image] server on {url} (Ctrl-C to stop)")
+        try:
+            while True:
+                time.sleep(3600)
+        except KeyboardInterrupt:
+            return 0
+
+    from .workflow import build_prompt
+    graph = build_prompt(dit_name=diT, te_name=text_encoder, vae_name=vae_name,
+                         prompt=prompt, width=width, height=height,
+                         steps=args.steps, seed=seed, sampler=args.sampler,
+                         scheduler=args.scheduler, cfg=args.cfg)
+
+    say(f"[mmh3-image] {width}x{height}, {args.steps} steps, seed {seed}")
+    started = time.time()
+    try:
+        from . import comfy
+        image = comfy.generate(url, graph, timeout=args.timeout, say=say)
+    finally:
+        if server is not None and not args.keep_server:
+            comfy.stop_server(server)
+
+    with open(output, "wb") as handle:
+        handle.write(image)
+    say(f"[mmh3-image] wrote {output} ({len(image) / 1e6:.1f} MB) "
+        f"in {time.time() - started:.1f}s")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mmh3_image-0.1.0/mmh3_image/comfy.py

@@ -0,0 +1,194 @@
+"""Install, point at and talk to a local ComfyUI.
+
+The image model only exists as a ComfyUI node (``MiniMaxH3ImageConditioning``),
+so the CLI bootstraps a private ComfyUI checkout with the ComfyUI-GGUF node and
+drives it over the HTTP API. An existing checkout or a running server can be
+used instead with ``--comfyui`` / ``--server-url``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+
+COMFY_REPO = "https://github.com/comfyanonymous/ComfyUI"
+GGUF_REPO = "https://github.com/city96/ComfyUI-GGUF"
+MARKER = ".mmh3-image-installed"
+
+EXTRA_PATHS_BLOCK = """mmh3_image:
+    base_path: {models}
+    diffusion_models: diffusion_models
+    text_encoders: text_encoders
+    vae: vae
+"""
+
+
+def _run(cmd, cwd=None, quiet=False):
+    if not quiet:
+        print(f"[mmh3-image] $ {' '.join(str(c) for c in cmd)}", flush=True)
+    subprocess.run(cmd, cwd=cwd, check=True)
+
+
+def _venv_python(root):
+    if os.name == "nt":
+        return os.path.join(root, "venv", "Scripts", "python.exe")
+    return os.path.join(root, "venv", "bin", "python")
+
+
+def ensure_comfyui(root=None, cache_dir=None, quiet=False):
+    """Return a ComfyUI checkout with the GGUF node and its dependencies."""
+    if root is None:
+        from .download import cache_root
+        root = os.path.join(cache_root(cache_dir), "ComfyUI")
+    root = os.path.abspath(os.path.expanduser(root))
+
+    if not os.path.isfile(os.path.join(root, "main.py")):
+        os.makedirs(os.path.dirname(root) or ".", exist_ok=True)
+        _run(["git", "clone", "--depth", "1", COMFY_REPO, root], quiet=quiet)
+
+    python = _venv_python(root)
+    if not os.path.isfile(python):
+        if not quiet:
+            print(f"[mmh3-image] creating venv in {root}", flush=True)
+        _run([sys.executable, "-m", "venv", os.path.join(root, "venv")], quiet=quiet)
+
+    marker = os.path.join(root, MARKER)
+    if not os.path.isfile(marker):
+        _run([python, "-m", "pip", "install", "-q", "--upgrade", "pip"], quiet=quiet)
+        _run([python, "-m", "pip", "install", "-r",
+              os.path.join(root, "requirements.txt")], quiet=quiet)
+        open(marker, "w").close()
+
+    node = os.path.join(root, "custom_nodes", "ComfyUI-GGUF")
+    if not os.path.isdir(node):
+        _run(["git", "clone", "--depth", "1", GGUF_REPO, node], quiet=quiet)
+        req = os.path.join(node, "requirements.txt")
+        if os.path.isfile(req):
+            _run([python, "-m", "pip", "install", "-r", req], quiet=quiet)
+    return root
+
+
+def write_extra_model_paths(root, models_root, quiet=False):
+    """Teach that ComfyUI checkout where the cached weights are."""
+    path = os.path.join(root, "extra_model_paths.yaml")
+    block = EXTRA_PATHS_BLOCK.format(models=models_root)
+    existing = ""
+    if os.path.isfile(path):
+        with open(path, encoding="utf-8") as handle:
+            existing = handle.read()
+        if f"base_path: {models_root}" in existing:
+            return path
+        if existing and not existing.endswith("\n"):
+            existing += "\n"
+    with open(path, "w", encoding="utf-8") as handle:
+        handle.write(existing + ("\n" if existing else "") + block)
+    if not quiet:
+        print(f"[mmh3-image] model paths -> {path}", flush=True)
+    return path
+
+
+def server_ready(url, timeout=1.0):
+    try:
+        with urllib.request.urlopen(url.rstrip("/") + "/system_stats",
+                                    timeout=timeout) as response:
+            return response.status == 200
+    except Exception:
+        return False
+
+
+def start_server(root, port=8188, quiet=False, wait=900):
+    url = f"http://127.0.0.1:{port}"
+    python = _venv_python(root)
+    log_path = os.path.join(os.path.dirname(root.rstrip(os.sep)), "comfyui.log")
+    log = open(log_path, "ab")
+    if not quiet:
+        print(f"[mmh3-image] starting ComfyUI on {url} (log: {log_path})", flush=True)
+    proc = subprocess.Popen(
+        [python, "main.py", "--listen", "127.0.0.1", "--port", str(port),
+         "--disable-auto-launch"],
+        cwd=root, stdout=log, stderr=subprocess.STDOUT)
+    started = time.time()
+    while time.time() - started < wait:
+        if proc.poll() is not None:
+            raise RuntimeError(f"ComfyUI exited with {proc.returncode}; see {log_path}")
+        if server_ready(url):
+            if not quiet:
+                print(f"[mmh3-image] server ready in {time.time() - started:.1f}s",
+                      flush=True)
+            return proc
+        time.sleep(1.0)
+    proc.terminate()
+    raise RuntimeError(f"ComfyUI did not become ready within {wait}s; see {log_path}")
+
+
+def stop_server(proc):
+    if proc is None or proc.poll() is not None:
+        return
+    proc.terminate()
+    try:
+        proc.wait(timeout=30)
+    except subprocess.TimeoutExpired:
+        proc.kill()
+
+
+def _post(url, payload):
+    request = urllib.request.Request(
+        url, json.dumps(payload).encode(), {"Content-Type": "application/json"})
+    return json.loads(urllib.request.urlopen(request, timeout=60).read())
+
+
+def _get_json(url):
+    with urllib.request.urlopen(url, timeout=60) as response:
+        return json.loads(response.read())
+
+
+def generate(url, graph, timeout=3600, say=print):
+    """Queue ``graph``, wait for it and return the first PNG's bytes."""
+    url = url.rstrip("/")
+    client_id = uuid.uuid4().hex
+    try:
+        queued = _post(url + "/prompt", {"prompt": graph, "client_id": client_id})
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode("utf-8", "replace")
+        raise SystemExit(f"ComfyUI rejected the workflow:\n{detail[:3000]}")
+    if queued.get("node_errors"):
+        raise SystemExit("workflow validation failed:\n" +
+                         json.dumps(queued["node_errors"], indent=1)[:3000])
+
+    prompt_id = queued["prompt_id"]
+    started = time.time()
+    last_report = started
+    while True:
+        if time.time() - started > timeout:
+            raise SystemExit(f"timed out after {timeout:.0f}s")
+        history = _get_json(f"{url}/history/{prompt_id}")
+        entry = history.get(prompt_id)
+        if entry:
+            status = entry.get("status", {})
+            if status.get("status_str") == "error":
+                raise SystemExit("generation failed:\n" +
+                                 json.dumps(status, indent=1)[:3000])
+            images = [img for node in entry.get("outputs", {}).values()
+                      for img in node.get("images", [])]
+            if images:
+                image = images[0]
+                query = urllib.parse.urlencode({
+                    "filename": image["filename"],
+                    "subfolder": image.get("subfolder", ""),
+                    "type": image.get("type", "output"),
+                })
+                with urllib.request.urlopen(f"{url}/view?{query}", timeout=300) as resp:
+                    return resp.read()
+            raise SystemExit("generation finished but produced no image")
+        now = time.time()
+        if now - last_report > 20:
+            say(f"[mmh3-image] still sampling... {now - started:.0f}s")
+            last_report = now
+        time.sleep(2.0)

mmh3_image-0.1.0/mmh3_image/download.py

@@ -0,0 +1,100 @@
+"""Fetch the GGUF weights this package drives.
+
+Nothing is bundled in the wheel: the selected quantization plus the two
+required companions are pulled into ``~/.cache/mmh3-image/models`` on first
+use and reused afterwards. ``hf_hub_download`` resumes partial files, so an
+interrupted download picks up where it stopped.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+DEFAULT_CACHE = "~/.cache/mmh3-image"
+
+DIT_REPO = "Abiray/MiniMax-H3-Image-GGUF"
+TE_Q3_REPO = "Abiray/Qwen3-VL-32B-Instruct-GGUF"
+TE_Q4_REPO = "Abiray/MiniMax-H3-GGUF"
+VAE_REPO = "Comfy-Org/MiniMax-H3-Image"
+
+VAE_FILENAME = "vae/minimax_h3_image_vae_fp16.safetensors"
+
+
+#: key -> (filename, approximate bytes, description)
+QUANTS = {
+    "q2": ("MiniMax-H3-Image-Pruned-Q2_K.gguf", 6.88e9, "smallest, 8-10 GB VRAM"),
+    "q3": ("MiniMax-H3-Image-Pruned-Q3_K_M.gguf", 8.91e9, "efficient, 12 GB VRAM"),
+    "q4s": ("MiniMax-H3-Image-Pruned-Q4_K_S.gguf", 11.60e9, "fast 4-bit"),
+    "q4": ("MiniMax-H3-Image-Pruned-Q4_K_M.gguf", 11.60e9, "recommended sweet spot"),
+    "q5": ("MiniMax-H3-Image-Pruned-Q5_K_M.gguf", 14.08e9, "closest to BF16"),
+}
+
+#: key -> (repo, filename, approximate bytes, description)
+TEXT_ENCODERS = {
+    "q3": (TE_Q3_REPO, "Qwen3vl_32b_h3-Q3_K_M.gguf", 12.00e9, "12 GB, recommended"),
+    "q4": (TE_Q4_REPO, "text_encoders/qwen3vl_32b_minimax_h3-Q4_K_M.gguf", 14.60e9,
+           "14.6 GB, slightly better prompt fidelity"),
+}
+
+
+def cache_root(cache_dir=None):
+    return os.path.abspath(os.path.expanduser(cache_dir or os.environ.get(
+        "MMH3_IMAGE_CACHE", DEFAULT_CACHE)))
+
+
+def describe(quant, text_encoder):
+    dit = QUANTS[quant]
+    te = TEXT_ENCODERS[text_encoder]
+    total = (dit[1] + te[2] + 1.17e9) / 1e9
+    return (f"DiT {quant} ({dit[1] / 1e9:.2f} GB, {dit[2]}) + "
+            f"text encoder {text_encoder} ({te[2] / 1e9:.2f} GB) + VAE 1.17 GB "
+            f"= about {total:.1f} GB")
+
+
+def _file(repo, filename, local_dir, expected, endpoint=None, quiet=False):
+    os.makedirs(local_dir, exist_ok=True)
+    path = os.path.join(local_dir, filename)
+    if os.path.isfile(path) and abs(os.path.getsize(path) - expected) < expected * 0.01:
+        return path
+    if endpoint:
+        os.environ["HF_ENDPOINT"] = endpoint.rstrip("/")
+    from huggingface_hub import hf_hub_download
+
+    if not quiet:
+        print(f"[mmh3-image] downloading {filename} ({expected / 1e9:.2f} GB) "
+              f"from {repo}", flush=True)
+    downloaded = hf_hub_download(repo_id=repo, filename=filename,
+                                 local_dir=local_dir)
+    size = os.path.getsize(downloaded)
+    if abs(size - expected) > expected * 0.01:
+        raise RuntimeError(f"{downloaded} is {size} bytes, expected about "
+                           f"{int(expected)}; the download is incomplete, rerun "
+                           f"the command to resume")
+    return downloaded
+
+
+def ensure_models(quant="q4", text_encoder="q3", cache_dir=None, endpoint=None,
+                  quiet=False):
+    """Download the DiT, text encoder and VAE; return their paths."""
+    if quant not in QUANTS:
+        raise SystemExit(f"unknown quantization {quant!r}; pick one of {sorted(QUANTS)}")
+    if text_encoder not in TEXT_ENCODERS:
+        raise SystemExit(f"unknown text encoder {text_encoder!r}; "
+                         f"pick one of {sorted(TEXT_ENCODERS)}")
+
+    models = os.path.join(cache_root(cache_dir), "models")
+    dit_name = QUANTS[quant][0]
+    te_repo, te_name = TEXT_ENCODERS[text_encoder][0], TEXT_ENCODERS[text_encoder][1]
+    # Files that live under a subdirectory in their repo are mirrored from the
+    # models root, so they land where ComfyUI scans for them.
+    te_local = models if "/" in te_name else os.path.join(models, "text_encoders")
+
+    dit = _file(DIT_REPO, dit_name, os.path.join(models, "diffusion_models"),
+                QUANTS[quant][1], endpoint, quiet)
+    if not quiet:
+        print(f"[mmh3-image] text encoder {te_name}", flush=True)
+    te = _file(te_repo, te_name, te_local,
+               TEXT_ENCODERS[text_encoder][2], endpoint, quiet)
+    vae = _file(VAE_REPO, VAE_FILENAME, models, 1.168505312e9, endpoint, quiet)
+    return {"dit": dit, "text_encoder": te, "vae": vae, "models": models}

mmh3_image-0.1.0/mmh3_image/workflow.py

@@ -0,0 +1,35 @@
+"""The ComfyUI API graph for one MiniMax-H3-Image generation.
+
+Defaults follow the model card: euler / simple, exactly six steps, CFG 1.0 and
+no negative prompt (the distilled PDD heads are calibrated for that).
+"""
+
+from __future__ import annotations
+
+ALIGN = 32
+
+
+def build_prompt(dit_name, te_name, vae_name, prompt, width, height,
+                 steps=6, seed=0, sampler="euler", scheduler="simple", cfg=1.0):
+    if width % ALIGN or height % ALIGN:
+        raise ValueError(f"width and height must be multiples of {ALIGN}")
+    return {
+        "1": {"class_type": "UnetLoaderGGUF", "inputs": {"unet_name": dit_name}},
+        "2": {"class_type": "CLIPLoaderGGUF",
+              "inputs": {"clip_name": te_name, "type": "minimax"}},
+        "3": {"class_type": "VAELoader", "inputs": {"vae_name": vae_name}},
+        "4": {"class_type": "MiniMaxH3ImageConditioning",
+              "inputs": {"clip": ["2", 0], "vae": ["3", 0], "prompt": prompt,
+                         "width": width, "height": height}},
+        "5": {"class_type": "ConditioningZeroOut", "inputs": {"conditioning": ["4", 0]}},
+        "6": {"class_type": "KSampler",
+              "inputs": {"seed": seed, "steps": steps, "cfg": cfg,
+                         "sampler_name": sampler, "scheduler": scheduler,
+                         "denoise": 1.0, "model": ["1", 0],
+                         "positive": ["4", 0], "negative": ["5", 0],
+                         "latent_image": ["4", 1]}},
+        "7": {"class_type": "VAEDecode",
+              "inputs": {"samples": ["6", 0], "vae": ["3", 0]}},
+        "8": {"class_type": "SaveImage",
+              "inputs": {"images": ["7", 0], "filename_prefix": "mmh3-image"}},
+    }

mmh3_image-0.1.0/mmh3_image.egg-info/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: mmh3-image
+Version: 0.1.0
+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, fits 8–10 GB VRAM |
+| `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.

mmh3_image-0.1.0/mmh3_image.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+mmh3_image/__init__.py
+mmh3_image/cli.py
+mmh3_image/comfy.py
+mmh3_image/download.py
+mmh3_image/workflow.py
+mmh3_image.egg-info/PKG-INFO
+mmh3_image.egg-info/SOURCES.txt
+mmh3_image.egg-info/dependency_links.txt
+mmh3_image.egg-info/entry_points.txt
+mmh3_image.egg-info/requires.txt
+mmh3_image.egg-info/top_level.txt

mmh3_image-0.1.0/mmh3_image.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mmh3_image-0.1.0/mmh3_image.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mmh3-image = mmh3_image.cli:main

mmh3_image-0.1.0/mmh3_image.egg-info/requires.txt

@@ -0,0 +1 @@
+huggingface_hub>=0.23

mmh3_image-0.1.0/mmh3_image.egg-info/top_level.txt

@@ -0,0 +1 @@
+mmh3_image

mmh3_image-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mmh3-image"
+version = "0.1.0"
+description = "MiniMax-H3-Image GGUF on ComfyUI: one command to download and generate."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "yunfengwang" }]
+keywords = ["minimax", "h3", "text-to-image", "gguf", "comfyui", "dit"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia :: Graphics",
+]
+dependencies = [
+    "huggingface_hub>=0.23",
+]
+
+[project.scripts]
+mmh3-image = "mmh3_image.cli:main"
+
+[project.urls]
+"Model (GGUF)" = "https://huggingface.co/Abiray/MiniMax-H3-Image-GGUF"
+"Model (original)" = "https://huggingface.co/MiniMaxAI/MiniMax-H3-Image"
+
+[tool.setuptools.packages.find]
+include = ["mmh3_image*"]

mmh3_image-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+