calesthio/OpenMontage · error · ValueError

Kling avatar requires image_url or image_path

Error message

Kling avatar requires image_url or image_path

What it means

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.

Source

Thrown at tools/avatar/kling_avatar.py:231

                "output_path": str(paths[0]),
                "video_paths": [str(path) for path in paths],
                "format": "mp4",
                "cost_estimate_confidence": "low",
                "cost_estimate_basis": "Conservative estimate pending official account-usage reconciliation.",
                **self._account_usage_result(inputs, client),
                **self._callback_result_data(inputs, task_id),
                **probed,
            },
            artifacts=[str(path) for path in paths],
            cost_usd=self.estimate_cost(inputs),
            duration_seconds=round(time.time() - start, 2),
            model="kling-official-avatar",
        )

    def _build_request(self, inputs: dict[str, Any]) -> dict[str, Any]:
        image = normalize_image_input(inputs.get("image_url"), inputs.get("image_path"))
        if not image:
            raise ValueError("Kling avatar requires image_url or image_path")

        mode = str(inputs.get("mode") or "std")
        if mode not in AVATAR_MODES:
            raise ValueError(f"mode must be one of: {', '.join(AVATAR_MODES)}")

        payload: dict[str, Any] = {
            "image": image,
            "mode": mode,
        }
        if inputs.get("prompt"):
            payload["prompt"] = str(inputs["prompt"])

        audio_source = self._copy_audio_input(inputs, payload)
        self._copy_common_task_fields(inputs, payload)
        return {
            "protocol": "classic",
            "path": "/v1/videos/avatar/image2video",
            "payload": payload,

View on GitHub (pinned to 95e1c3d0ab)

Solutions

1. Supply a valid image_url (public HTTPS URL) or image_path (existing local file) in the tool inputs.
2. If using image_path, verify the file exists and is a readable image before calling the tool.
3. Check the upstream step that generates/downloads the portrait actually produced output at the expected path.

Example fix

// before
result = tool.run({"prompt": "make the avatar speak", "audio_path": "vo.mp3"})

// after
result = tool.run({
    "image_path": "portrait.png",
    "prompt": "make the avatar speak",
    "audio_path": "vo.mp3",
})

from pathlib import Path
image_url = inputs.get("image_url")
image_path = inputs.get("image_path")
assert image_url or (image_path and Path(image_path).is_file()), \
    "kling_avatar needs a valid image_url or an existing image_path"

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Kling avatar requires audio_id, sound_file, sound_file_url,
• mode must be one of: {', '.join(AVATAR_MODES)}
• Kling identify_face requires video_id or video_url
• Kling avatar response contained no videos
• Kling avatar response item contained no downloadable URL: {i

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