calesthio/OpenMontage · error · ValueError

mode must be one of: {', '.join(AVATAR_MODES)}

Error message

mode must be one of: {', '.join(AVATAR_MODES)}

What it means

ValueError from KlingAvatarTool._build_request when the mode input is not a member of AVATAR_MODES ('std' is the default; the set typically also includes 'pro'). The mode selects the Kling avatar model tier; anything else would be rejected by the API anyway, so the client fails fast with the allowed list spelled out in the message.

Source

Thrown at tools/avatar/kling_avatar.py:235

                "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,
            "operation": "image_to_avatar_video",
            "model": "kling-official-avatar",
            "avatar_source": inputs.get("image_url") or inputs.get("image_path"),
            "audio_source": audio_source,

View on GitHub (pinned to 95e1c3d0ab)

Solutions

1. Read the message — it lists the valid modes — and set mode to one of them (or omit it; 'std' is the default).
2. Normalize user-supplied mode strings (lowercase, trim) before passing to the tool.
3. Pin the mode against the AVATAR_MODES constant imported from the module rather than hardcoding.

Example fix

// before
result = tool.run({"image_path": "p.png", "mode": "HD", ...})

// after
from tools.avatar.kling_avatar import AVATAR_MODES
mode = str(inputs.get("mode", "std")).lower()
assert mode in AVATAR_MODES, f"mode must be one of {AVATAR_MODES}"
result = tool.run({"image_path": "p.png", "mode": mode, ...})

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

def is_valid_avatar_mode(mode: str) -> bool:
    return mode in AVATAR_MODES

When it happens

Trigger: Passing mode='hd', mode='professional', mode=1 (int), or any string outside AVATAR_MODES to kling_avatar.

Common situations: Copying mode values from a different Kling tool (video generation uses different mode semantics); mode names changed between API versions; passing an empty mode expecting auto-detection.

Related errors

• Kling avatar requires image_url or image_path
• Kling avatar requires audio_id, sound_file, sound_file_url,
• Kling avatar response contained no videos
• Kling avatar response item contained no downloadable URL: {i
• Unsupported Kling lip-sync operation: {operation}

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