calesthio/OpenMontage · error · ValueError

Image too large ({len(raw)} bytes). Max ~6MB raw.

Error message

Image too large ({len(raw)} bytes). Max ~6MB raw.

What it means

ValueError from the Hunyuan reference-image resolver enforcing the upstream TokenHub API limit of roughly 6 MB per raw image file. The resolver reads the local file's bytes and rejects anything larger before base64 encoding, because encoding would inflate it further past the API cap.

Source

Thrown at tools/graphics/hunyuan_image.py:401

        Per upstream docs: single image 50-5000px per side, base64 < 6MB.
        Formats: jpg/jpeg/png/bmp/tiff/webp.
        """
        import base64

        resolved: list[str] = []
        for ref in refs:
            if ref.startswith("data:") or ref.startswith("http://") or ref.startswith("https://"):
                resolved.append(ref)
                continue

            image_path = Path(ref)
            if not image_path.is_file():
                raise FileNotFoundError(f"Reference image not found: {ref}")

            raw = image_path.read_bytes()
            max_raw = 6 * 1024 * 1024  # 6MB per upstream limit
            if len(raw) > max_raw:
                raise ValueError(
                    f"Image too large ({len(raw)} bytes). Max ~6MB raw."
                )

            suffix = image_path.suffix.lower()
            mime_map = {
                ".jpg": "image/jpeg",
                ".jpeg": "image/jpeg",
                ".png": "image/png",
                ".bmp": "image/bmp",
                ".tiff": "image/tiff",
                ".tif": "image/tiff",
                ".webp": "image/webp",
            }
            mime = mime_map.get(suffix, "image/png")
            data = base64.b64encode(raw).decode("ascii")
            resolved.append(f"data:{mime};base64,{data}")
        return resolved

View on GitHub (pinned to 95e1c3d0ab)

Solutions

1. Downscale or recompress the image (JPEG quality ~85, longest side ~2048px) before passing it as a reference
2. Strip EXIF and metadata, which can add significant size
3. If the image must stay local and large, host it and pass an https:// URL instead — the resolver skips the size check for URLs
4. Batch-check all references in a loop so one oversized file fails fast before the API call

Example fix

# before
refs = ["hero_raw.png"]  # 9 MB
# after
from PIL import Image
img = Image.open("hero_raw.png")
img.thumbnail((2048, 2048))
img.convert("RGB").save("hero_ref.jpg", "JPEG", quality=85)
refs = ["hero_ref.jpg"]

from pathlib import Path
MAX_RAW = 6 * 1024 * 1024
for ref in refs:
    if not ref.startswith(("data:", "http://", "https://")):
        assert Path(ref).stat().st_size <= MAX_RAW, f"{ref} exceeds 6MB raw limit"

When it happens

Trigger: Passing a high-resolution local reference image (e.g. a 12 MB camera photo or lossless PNG screenshot) as a reference to the Hunyuan image tool.

Common situations: Modern phone photos and 4K screenshots routinely exceed 6 MB; users re-using print-quality assets; PNG exports from design tools that avoid compression.

Related errors

• Reference image not found: {ref}
• TokenHub API error: code={code}, message={message}
• Image not found: {path}
• Image too large ({len(raw)} bytes). Max ~6MB raw (8MB base64
• ${res.status} ${url}

AI-assisted analysis of calesthio/OpenMontage@95e1c3d0ab (2026-08-15). Data as JSON: /api/errors/0e6f0830c877e235. Report an issue: GitHub.