calesthio/OpenMontage · error · ValueError

This Gemini route requires at least one reference image

Error message

This Gemini route requires at least one reference image

What it means

Raised in _build_payload for media_style=='gemini_images' when the inputs contain no reference images at all. This Gemini route requires at least one image; a lone image_url is promoted into the images list, but if both image_url and reference_images are absent the payload cannot be built.

Source

Thrown at tools/video/atlas_video.py:245

        style = spec["media_style"]
        image = inputs.get("image_url") or inputs.get("reference_image_url")
        last_image = inputs.get("last_image_url") or inputs.get("end_image_url")
        images = list(inputs.get("reference_images") or [])
        videos = list(inputs.get("reference_videos") or [])
        audios = list(inputs.get("reference_audios") or [])
        video = inputs.get("video_url") or inputs.get("reference_video_url")

        if style in {"seedance_image", "gemini_image", "h3_image"}:
            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

View on GitHub (pinned to 95e1c3d0ab)

Solutions

  1. Pass reference_images (list) or a single image_url/reference_image_path — the lone image is auto-promoted to the list
  2. Verify the list is non-empty after your upload/normalization step before calling the tool
  3. If you actually wanted pure text-to-video, switch to a model whose spec supports it

Example fix

# before
inputs = {'model':'google/gemini-image','prompt':'a cat in the style of the frames'}

# after
inputs = {'model':'google/gemini-image','prompt':'a cat in the style of the frames','reference_images':['assets/frame1.png','assets/frame2.png']}
Defensive patterns

Strategy: validation

Validate before calling

images = list(inputs.get('reference_images') or [])
if inputs.get('image_url') and not images:
    images = [inputs['image_url']]
if not images:
    raise ValueError('gemini_images route needs >=1 reference image')
inputs['reference_images'] = images

Type guard

def gemini_images_ready(inputs: dict) -> bool:
    return bool(inputs.get('reference_images') or inputs.get('image_url') or inputs.get('reference_image_url'))

Try / catch

try:
    result = atlas_video.run(inputs=inputs)
except ValueError as e:
    if 'at least one reference image' in str(e):
        raise SystemExit('attach reference frames for this Gemini route') from e
    raise

Prevention

When it happens

Trigger: Calling the gemini_images model with only a text prompt; supplying reference_images as an empty list plus no image_url; misspelling the key (e.g. 'ref_images').

Common situations: Using a multi-reference Gemini route as if it were plain text-to-video; forgetting to attach the style/reference frames when porting a workflow from another provider; passing image paths under a key that was uploaded but not forwarded.

Related errors

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