{"record":{"id":"da91c78757f5f784","repo":"calesthio/OpenMontage","slug":"image-to-video-requires-exactly-one-reference-imag","errorCode":null,"errorMessage":"image_to_video requires exactly one reference image","messagePattern":"image_to_video requires exactly one reference image","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"tools/video/seedance_ark.py","lineNumber":747,"sourceCode":"\n        if inputs.get(\"reference_video_path\"):\n            raise ValueError(\n                \"reference_video_path is not supported by Ark; upload the \"\n                \"video to a public/signed HTTPS URL or Ark asset first\"\n            )\n\n        if operation == \"text_to_video\":\n            if not prompt:\n                raise ValueError(\"prompt is required for text_to_video\")\n            if self._has_any_media(inputs):\n                raise ValueError(\n                    \"text_to_video does not accept reference media; use \"\n                    \"image_to_video or reference_to_video\"\n                )\n        elif operation == \"image_to_video\":\n            first_refs = self._single_image_refs(inputs)\n            if len(first_refs) != 1:\n                raise ValueError(\"image_to_video requires exactly one reference image\")\n            content.append(self._image_content(first_refs[0], role=\"first_frame\"))\n            end_refs = [\n                value\n                for value in (\n                    inputs.get(\"end_image_url\"),\n                    inputs.get(\"end_image_path\"),\n                )\n                if value\n            ]\n            if len(end_refs) > 1:\n                raise ValueError(\"provide only one of end_image_url/end_image_path\")\n            if end_refs:\n                content.append(self._image_content(end_refs[0], role=\"last_frame\"))\n        else:\n            image_refs = list(inputs.get(\"reference_image_urls\") or [])\n            image_refs.extend(inputs.get(\"reference_image_paths\") or [])\n            if inputs.get(\"reference_image_url\"):\n                image_refs.append(inputs[\"reference_image_url\"])","sourceCodeStart":729,"sourceCodeEnd":765,"githubUrl":"https://github.com/calesthio/OpenMontage/blob/95e1c3d0ab93482159818560f6a8c8e866b9139f/tools/video/seedance_ark.py#L729-L765","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass exactly one image via reference_image_url (or a single-entry reference_image_urls list)","Remove extra image keys so the total image ref count is 1","Use reference_to_video when multiple images must be honored"],"exampleFix":"# before\ninputs = {\"operation\": \"image_to_video\", \"reference_image_urls\": [a, b]}\n\n# after\ninputs = {\"operation\": \"image_to_video\", \"reference_image_url\": a}","handlingStrategy":"validation","validationCode":"IMG_KEYS = (\"reference_image_urls\", \"reference_image_paths\", \"reference_image_url\", \"reference_image_path\")\n\ndef image_ref_count(inputs):\n    n = sum(len(inputs.get(k) or []) for k in IMG_KEYS[:2])\n    n += sum(1 for k in IMG_KEYS[2:] if inputs.get(k))\n    return n\n\n# before image_to_video: assert image_ref_count(inputs) == 1","typeGuard":"def is_valid_i2v_inputs(inputs: dict) -> bool:\n    return image_ref_count(inputs) == 1","tryCatchPattern":null,"preventionTips":["Use the singular reference_image_url key for image_to_video","Route multi-image requests to reference_to_video by design"],"tags":["validation","seedance","ark","image-to-video","input-validation"],"backgroundTag":null,"analyzedSha":"95e1c3d0ab93482159818560f6a8c8e866b9139f","analyzedAt":"2026-08-15T06:31:20.014Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}