calesthio/OpenMontage · error · ValueError

image_to_video requires exactly one reference image

Error message

image_to_video requires exactly one reference image

What it means

Raised when operation is 'image_to_video' and _single_image_refs(inputs) does not return exactly one entry. Ark image-to-video requires exactly one first-frame image; zero or multiple image refs both fail here. This is a pre-flight payload validation error, not an API response.

Source

Thrown at tools/video/seedance_ark.py:747

        if inputs.get("reference_video_path"):
            raise ValueError(
                "reference_video_path is not supported by Ark; upload the "
                "video to a public/signed HTTPS URL or Ark asset first"
            )

        if operation == "text_to_video":
            if not prompt:
                raise ValueError("prompt is required for text_to_video")
            if self._has_any_media(inputs):
                raise ValueError(
                    "text_to_video does not accept reference media; use "
                    "image_to_video or reference_to_video"
                )
        elif operation == "image_to_video":
            first_refs = self._single_image_refs(inputs)
            if len(first_refs) != 1:
                raise ValueError("image_to_video requires exactly one reference image")
            content.append(self._image_content(first_refs[0], role="first_frame"))
            end_refs = [
                value
                for value in (
                    inputs.get("end_image_url"),
                    inputs.get("end_image_path"),
                )
                if value
            ]
            if len(end_refs) > 1:
                raise ValueError("provide only one of end_image_url/end_image_path")
            if end_refs:
                content.append(self._image_content(end_refs[0], role="last_frame"))
        else:
            image_refs = list(inputs.get("reference_image_urls") or [])
            image_refs.extend(inputs.get("reference_image_paths") or [])
            if inputs.get("reference_image_url"):
                image_refs.append(inputs["reference_image_url"])

View on GitHub (pinned to 95e1c3d0ab)

Solutions

1. Pass exactly one image via reference_image_url (or a single-entry reference_image_urls list)
2. Remove extra image keys so the total image ref count is 1
3. Use reference_to_video when multiple images must be honored

Example fix

# before
inputs = {"operation": "image_to_video", "reference_image_urls": [a, b]}

# after
inputs = {"operation": "image_to_video", "reference_image_url": a}

IMG_KEYS = ("reference_image_urls", "reference_image_paths", "reference_image_url", "reference_image_path")

def image_ref_count(inputs):
    n = sum(len(inputs.get(k) or []) for k in IMG_KEYS[:2])
    n += sum(1 for k in IMG_KEYS[2:] if inputs.get(k))
    return n

# before image_to_video: assert image_ref_count(inputs) == 1

def is_valid_i2v_inputs(inputs: dict) -> bool:
    return image_ref_count(inputs) == 1

When it happens

Trigger: operation='image_to_video' with no reference image at all, or with several image references collected from reference_image_urls/paths plus singular reference_image_url/path summing to 0 or >= 2.

Common situations: Passing a batch of images from a generation pipeline into image_to_video instead of reference_to_video; forgetting to attach the first-frame image; accidentally including both reference_image_url and reference_image_paths entries.

Related errors

• provide only one of end_image_url/end_image_path
• text_to_video does not accept reference media; use image_to_
• reference_to_video requires at least one image or video
• web_search is supported only for pure text input
• duration must be an integer from 4 to {max_seconds} or -1

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