calesthio/OpenMontage · error · ValueError

image_to_video requires image_url, image_path, or reference_

Error message

image_to_video requires image_url, image_path, or reference_image_path

What it means

Raised in _build_payload when the model's media_style is one of {'seedance_image','gemini_image','h3_image'} (single-image image-to-video routes) and no image source was supplied in inputs. The tool checks image_url, reference_image_url and the path-based keys that were normalized earlier; all were empty/falsy.

Source

Thrown at tools/video/atlas_video.py:237

        resolution = inputs.get("resolution", spec["default_resolution"])
        payload["resolution"] = self._validate_choice("resolution", resolution, spec["resolutions"])

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

        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, "

View on GitHub (pinned to 95e1c3d0ab)

Solutions

Add image_url (remote) or image_path/reference_image_path (local file) to inputs
If you have a reference_images list, pass its first entry explicitly as image_url/image_path for single-image styles
Optionally add last_image_url/end_image_url if you want a final-frame constraint

Example fix

# before
inputs = {'model':'minimax/h3','prompt':'animate this','operation':'image_to_video'}

# after
inputs = {'model':'minimax/h3','prompt':'animate this','operation':'image_to_video','image_path':'assets/hero.png'}

Defensive patterns

Strategy: validation

Validate before calling

image = inputs.get('image_url') or inputs.get('image_path') or inputs.get('reference_image_path')
if not image:
    raise ValueError('i2v call needs image_url/image_path/reference_image_path')
if inputs.get('image_path') and not Path(inputs['image_path']).is_file():
    raise ValueError(f"image file missing: {inputs['image_path']}")

Type guard

def has_i2v_image(inputs: dict) -> bool:
    return bool(inputs.get('image_url') or inputs.get('reference_image_url') or
                inputs.get('image_path') or inputs.get('reference_image_path'))

Try / catch

try:
    result = atlas_video.run(inputs=inputs)
except ValueError as e:
    if 'image_to_video requires' in str(e):
        raise SystemExit('attach an image before animating it') from e
    raise

Prevention

Always set an explicit image field for single-image i2v styles; never rely on reference_images
Validate local image paths exist before the call
Keep one canonical input-shape builder per operation so keys are never ad hoc

When it happens

Trigger: Calling operation='image_to_video' with only a prompt; passing the image under a key the tool does not read (e.g. 'image', 'first_frame'); passing image_path/reference_image_path that resolved to None because the file key was misspelled upstream.

Common situations: Renaming input keys in a wrapper script; assuming the model auto-picks an image from a references list (it does not — single-image styles ignore reference_images); migrating a call from a multi-reference model to a single-image model without adding an explicit image field.

Related errors

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