calesthio/OpenMontage · error · ValueError

{model} accepts at most {maximum} source images

Error message

{model} accepts at most {maximum} source images

What it means

ValueError raised in _build_payload when the number of source images exceeds the model's max_images limit from its spec. The images list (image_urls, with image_url prepended) is counted after collection, so the single image_url counts toward the same budget as the list entries.

Source

Thrown at tools/graphics/atlas_image.py:169

        elif style == "x":
            payload["size"] = f"{width}x{height}"
        elif style == "ratio":
            payload["aspect_ratio"] = inputs.get("aspect_ratio") or atlas_client.aspect_ratio_from_size(
                width, height, _COMMON_RATIOS
            )
        elif style == "tier":
            payload["size"] = inputs.get("resolution", "auto")

        images = list(inputs.get("image_urls") or [])
        if inputs.get("image_url"):
            images.insert(0, inputs["image_url"])
        media_style = spec["media_style"]
        if media_style == "images":
            maximum = int(spec["max_images"])
            if not images:
                raise ValueError(f"{spec['operation']} requires at least one source image")
            if len(images) > maximum:
                raise ValueError(f"{model} accepts at most {maximum} source images")
            payload["images"] = images
        elif media_style == "image":
            if len(images) != 1:
                raise ValueError("layer decomposition requires exactly one source image")
            payload["image"] = images[0]

        for field in spec.get("optional_fields", ()):
            if inputs.get(field) is not None:
                payload[field] = inputs[field]
        if inputs.get("output_format") and inputs["output_format"] != "default":
            payload["output_format"] = inputs["output_format"]

        extra = inputs.get("extra_params")
        if isinstance(extra, dict):
            payload.update(extra)
        return payload

    @staticmethod

View on GitHub (pinned to 95e1c3d0ab)

Solutions

1. Trim image_urls to the model's max_images before the call (keep the most relevant references first).
2. Do not combine image_url with a full image_urls list — put everything in image_urls.
3. Read the per-model cap from get_info()'s model catalog and enforce it in your pipeline.
4. If you need more references than allowed, pick a model family with a higher max_images.

Example fix

# before
inputs = {"model": m, "image_urls": refs}  # len(refs)=6 > cap 4 -> ValueError

# after
cap = tool.get_info()["model_catalog"][m]["max_images"]
inputs = {"model": m, "image_urls": refs[:cap]}

cap = int(tool.get_info()["model_catalog"][inputs["model"]]["max_images"])
images = list(inputs.get("image_urls") or [])
if inputs.get("image_url"):
    images.insert(0, inputs["image_url"])
assert len(images) <= cap, f"{inputs['model']} accepts at most {cap} images"

def within_image_cap(tool, model: str, inputs: dict) -> bool:
    cap = int(tool.get_info()["model_catalog"][model]["max_images"])
    n = len(inputs.get("image_urls") or []) + (1 if inputs.get("image_url") else 0)
    return n <= cap

try:
    result = tool.run(inputs)
except ValueError as e:
    if "accepts at most" in str(e):
        cap = int(tool.get_info()["model_catalog"][inputs["model"]]["max_images"])
        inputs["image_urls"] = inputs["image_urls"][:cap]
        inputs.pop("image_url", None)
        result = tool.run(inputs)
    else:
        raise

When it happens

Trigger: Passing more image_urls than spec['max_images'] for a reference-conditioned model (e.g. 5 refs for a model capped at 4), or combining image_url with an already-full image_urls list so the prepend pushes it over the limit.

Common situations: Feeding an entire asset folder as references without checking the cap; mixing the convenience image_url field with image_urls and double-counting; models with different caps used interchangeably in a generic pipeline.

Related errors

• {spec['operation']} requires at least one source image
• layer decomposition requires exactly one source image
• Unsupported Atlas image model id {model!r}. Use get_info()['
• {family} does not expose generation_mode={operation!r} on At
• {model} accepts at most {limits['images']} images, {limits['

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