calesthio/OpenMontage · error · ValueError

{model} accepts at most {limits['images']} images, {limits['

Error message

{model} accepts at most {limits['images']} images, {limits['videos']} videos, and {limits['audios']} audio references

What it means

Raised in _build_payload for seedance_references styles when the number of supplied images/videos/audios exceeds the per-model caps stored in spec['media_limits']. It is a hard client-side cap check done before payload submission.

Source

Thrown at tools/video/atlas_video.py:254

            if not image:
                raise ValueError("image_to_video requires image_url, image_path, or reference_image_path")
            payload["image"] = image
            if last_image:
                payload["last_image" if style == "seedance_image" else "end_image"] = last_image
        elif style == "gemini_images":
            if image and not images:
                images = [image]
            if not images:
                raise ValueError("This Gemini route requires at least one reference image")
            payload["images"] = images
        elif style == "seedance_references":
            if image and not images:
                images = [image]
            if not (images or videos or (audios and spec["family"] == "bytedance/seedance-2.5")):
                raise ValueError("reference_to_video requires supported reference media for the selected model")
            limits = spec["media_limits"]
            if len(images) > limits["images"] or len(videos) > limits["videos"] or len(audios) > limits["audios"]:
                raise ValueError(
                    f"{model} accepts at most {limits['images']} images, {limits['videos']} videos, "
                    f"and {limits['audios']} audio references"
                )
            if images:
                payload["reference_images"] = images
            if videos:
                payload["reference_videos"] = videos
            if audios:
                payload["reference_audios"] = audios
        elif style == "h3_refers":
            refers = list(inputs.get("refers") or [])
            if not refers:
                refers = [
                    *({"url": value, "type": "image"} for value in images),
                    *({"url": value, "type": "video"} for value in videos),
                    *({"url": value, "type": "audio"} for value in audios),
                ]
                if image:

View on GitHub (pinned to 95e1c3d0ab)

Solutions

Read the message — it states the exact caps for your model; trim each list to fit (e.g. images[:limits['images']])
Remember the lone image promotion: if you pass image_url AND reference_images, the image is added to the list, so budget for it
For larger reference sets, switch to a model family with higher media_limits (bytedance/seedance-2.5)

Example fix

# before
inputs = {'model': model, 'reference_images': all_30_frames}  # exceeds cap on seedance-2.0

# after
limits = atlas_video.get_info()['model_catalog'][model]['media_limits']
inputs = {'model': model, 'reference_images': all_30_frames[:limits['images']]}

Defensive patterns

Strategy: validation

Validate before calling

spec = atlas_video.get_info()['model_catalog'][model]
lim = spec['media_limits']
inputs['reference_images'] = inputs.get('reference_images', [])[:lim['images']]
inputs['reference_videos'] = inputs.get('reference_videos', [])[:lim['videos']]
inputs['reference_audios'] = inputs.get('reference_audios', [])[:lim['audios']]

Type guard

def within_media_limits(inputs: dict, lim: dict) -> bool:
    return (len(inputs.get('reference_images') or []) <= lim['images'] and
            len(inputs.get('reference_videos') or []) <= lim['videos'] and
            len(inputs.get('reference_audios') or []) <= lim['audios'])

Try / catch

try:
    result = atlas_video.run(inputs=inputs)
except ValueError as e:
    if 'accepts at most' in str(e):
        # parse caps from message or refetch spec, trim, retry once
        trim_to_limits(inputs)
        result = atlas_video.run(inputs=inputs)
    else:
        raise

Prevention

Always clamp lists with [:limit] from the live spec
Remember a lone image_url is added to reference_images and counts toward the cap
Re-read media_limits when swapping model families — caps differ between 2.0 and 2.5

When it happens

Trigger: Passing 11 reference_images to a model whose media_limits['images'] is 10; mixing a promoted lone image plus a full reference_images list so the effective count crosses the cap; batch pipelines that fan out N references without clamping.

Common situations: Upgrading a workflow from seedance-2.0 (smaller caps) to more references than it allows, or downgrading a 2.5 workflow (up to 30 images) to a 2.0 model; not realizing the lone image_url is prepended to reference_images and counts toward the limit.

Related errors

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