{"record":{"id":"2f7bcbf03b689279","repo":"calesthio/OpenMontage","slug":"kling-avatar-requires-image-url-or-image-path","errorCode":null,"errorMessage":"Kling avatar requires image_url or image_path","messagePattern":"Kling avatar requires image_url or image_path","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"tools/avatar/kling_avatar.py","lineNumber":231,"sourceCode":"                \"output_path\": str(paths[0]),\n                \"video_paths\": [str(path) for path in paths],\n                \"format\": \"mp4\",\n                \"cost_estimate_confidence\": \"low\",\n                \"cost_estimate_basis\": \"Conservative estimate pending official account-usage reconciliation.\",\n                **self._account_usage_result(inputs, client),\n                **self._callback_result_data(inputs, task_id),\n                **probed,\n            },\n            artifacts=[str(path) for path in paths],\n            cost_usd=self.estimate_cost(inputs),\n            duration_seconds=round(time.time() - start, 2),\n            model=\"kling-official-avatar\",\n        )\n\n    def _build_request(self, inputs: dict[str, Any]) -> dict[str, Any]:\n        image = normalize_image_input(inputs.get(\"image_url\"), inputs.get(\"image_path\"))\n        if not image:\n            raise ValueError(\"Kling avatar requires image_url or image_path\")\n\n        mode = str(inputs.get(\"mode\") or \"std\")\n        if mode not in AVATAR_MODES:\n            raise ValueError(f\"mode must be one of: {', '.join(AVATAR_MODES)}\")\n\n        payload: dict[str, Any] = {\n            \"image\": image,\n            \"mode\": mode,\n        }\n        if inputs.get(\"prompt\"):\n            payload[\"prompt\"] = str(inputs[\"prompt\"])\n\n        audio_source = self._copy_audio_input(inputs, payload)\n        self._copy_common_task_fields(inputs, payload)\n        return {\n            \"protocol\": \"classic\",\n            \"path\": \"/v1/videos/avatar/image2video\",\n            \"payload\": payload,","sourceCodeStart":213,"sourceCodeEnd":249,"githubUrl":"https://github.com/calesthio/OpenMontage/blob/95e1c3d0ab93482159818560f6a8c8e866b9139f/tools/avatar/kling_avatar.py#L213-L249","documentation":"ValueError from KlingAvatarTool._build_request when normalize_image_input returns nothing for both image_url and image_path. The avatar operation is image-conditioned: Kling animates a still portrait, so a driving image is mandatory. Missing file, empty string, or a path that does not exist all normalize to falsy.","triggerScenarios":"Invoking kling_avatar with neither image_url nor image_path; passing an image_path pointing to a nonexistent file; passing an empty/whitespace image_url string.","commonSituations":"Input schema defaults omitting the image; upstream pipeline step that was supposed to produce the portrait image failed or wrote to a different path; typo in the path.","solutions":["Supply a valid image_url (public HTTPS URL) or image_path (existing local file) in the tool inputs.","If using image_path, verify the file exists and is a readable image before calling the tool.","Check the upstream step that generates/downloads the portrait actually produced output at the expected path."],"exampleFix":"// before\nresult = tool.run({\"prompt\": \"make the avatar speak\", \"audio_path\": \"vo.mp3\"})\n\n// after\nresult = tool.run({\n    \"image_path\": \"portrait.png\",\n    \"prompt\": \"make the avatar speak\",\n    \"audio_path\": \"vo.mp3\",\n})","handlingStrategy":"validation","validationCode":"from pathlib import Path\nimage_url = inputs.get(\"image_url\")\nimage_path = inputs.get(\"image_path\")\nassert image_url or (image_path and Path(image_path).is_file()), \\\n    \"kling_avatar needs a valid image_url or an existing image_path\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Make the portrait image a required field in any wrapper schema around kling_avatar","Assert upstream image-producing steps succeeded before invoking the avatar tool"],"tags":["kling","avatar","input-validation","required-field"],"backgroundTag":null,"analyzedSha":"95e1c3d0ab93482159818560f6a8c8e866b9139f","analyzedAt":"2026-08-15T06:31:20.014Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}