What causes "Image too large ({len(raw)} bytes). Max ~6MB raw (8MB base64-encoded)." in calesthio/OpenMontage?

Compress/resize the image: convert to JPEG at quality ~85 and cap the longest side (e.g. 1920px), which almost always lands under 6 MB.

calesthio/OpenMontage · error · ValueError

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

Error message

Image too large ({len(raw)} bytes). Max ~6MB raw (8MB base64-encoded).

What it means

Raised by _encode_image when the local image exceeds 6 MB raw (which base64-encodes to ~8 MB). The TokenHub endpoint is OpenAI-compatible and inlines the image as base64 in the JSON body, so the tool enforces a hard size cap to keep the request payload within API limits; oversized images raise ValueError instead of sending a doomed request.

Source

Thrown at tools/video/hunyuan_cloud_video.py:394

        """
        if inputs.get("model"):
            return inputs["model"]
        operation = inputs.get("operation", "text_to_video")
        return _MODEL_I2V if operation == "image_to_video" else _MODEL_T2V

    @staticmethod
    def _encode_image(path: str) -> str:
        """Read a local image file and return a base64-encoded string."""
        import base64

        image_path = Path(path)
        if not image_path.is_file():
            raise FileNotFoundError(f"Image not found: {path}")

        raw = image_path.read_bytes()
        max_raw = 6 * 1024 * 1024  # 6MB raw ≈ 8MB base64
        if len(raw) > max_raw:
            raise ValueError(
                f"Image too large ({len(raw)} bytes). Max ~6MB raw (8MB base64-encoded)."
            )

        return base64.b64encode(raw).decode("ascii")

    # ------------------------------------------------------------------
    # API communication (TokenHub OpenAI-compatible)
    # ------------------------------------------------------------------

    @staticmethod
    def _auth_headers(api_key: str) -> dict[str, str]:
        """Build common request headers for TokenHub API calls."""
        return {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        }

    def _submit_task(

View on GitHub (pinned to 95e1c3d0ab)

Solutions

Compress/resize the image: convert to JPEG at quality ~85 and cap the longest side (e.g. 1920px), which almost always lands under 6 MB.
Strip unnecessary alpha channels/metadata (PNG → JPEG) before passing it in.
If the image must stay lossless, downscale resolution to reduce raw bytes below the cap.

Example fix

# before
{"operation": "image_to_video", "image_path": "frame_4k.png"}  # 18MB

# after (shell)
ffmpeg -i frame_4k.png -vf scale=1920:-2 -q:v 3 frame.jpg
# then
{"operation": "image_to_video", "image_path": "frame.jpg"}

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path
import subprocess, tempfile

MAX_RAW = 6 * 1024 * 1024

def ensure_image_under_cap(path: str) -> str:
    p = Path(path)
    if p.stat().st_size <= MAX_RAW:
        return str(p)
    out = Path(tempfile.mkdtemp()) / (p.stem + ".jpg")
    subprocess.run(
        ["ffmpeg", "-y", "-i", str(p), "-vf", "scale=1920:-2", "-q:v", "3", str(out)],
        check=True, capture_output=True,
    )
    if out.stat().st_size > MAX_RAW:
        raise ValueError(f"still too large after re-encode: {out.stat().st_size}")
    return str(out)

Prevention

Standardize first frames as JPEG ~q85 at <=1920px longest side.
Check file size in your glue code before invoking the tool.
Remember base64 inflates by ~4/3 — budget raw size at 6MB, not 8MB.

When it happens

Trigger: Calling hunyuan_cloud_video with operation='image_to_video' where the image file is larger than 6*1024*1024 bytes. Common with high-resolution PNGs, photos straight from a camera, or lossless exports.

Common situations: 4K/8K PNG first frames; uncompressed TIFF/BMP exported from design tools; base64 inflation (x1.33) pushing an otherwise-acceptable 7 MB file over the endpoint's body limit.

Related errors

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