calesthio/OpenMontage · error · ValueError

operation must be text_to_video, image_to_video, or referenc

Error message

operation must be text_to_video, image_to_video, or reference_to_video

What it means

First validation in `_build_payload`: `operation` (default 'text_to_video') must be exactly one of text_to_video, image_to_video, or reference_to_video. The operation determines the entire content-array structure of the Ark request — text-only, single first-frame image, or multi-reference — so an unknown value cannot be mapped to a payload. Runs before resolution/aspect/duration checks.

Source

Thrown at tools/video/seedance_ark.py:694

            elif action in {"query", "cancel"} and inputs.get("task_id"):
                error_data = {"task_id": str(inputs["task_id"])}
            return ToolResult(
                success=False,
                data=error_data,
                error=(
                    f"Ark Seedance request failed: {self._safe_error(exc, api_key)}"
                ),
                duration_seconds=round(time.time() - started, 2),
            )

    def _build_payload(self, inputs: dict[str, Any]) -> dict[str, Any]:
        operation = str(inputs.get("operation", "text_to_video"))
        if operation not in {
            "text_to_video",
            "image_to_video",
            "reference_to_video",
        }:
            raise ValueError(
                "operation must be text_to_video, image_to_video, or reference_to_video"
            )

        model, variant = self._resolve_model(inputs)
        resolution = str(inputs.get("resolution", "720p")).lower()
        if resolution not in self.OUTPUT_DIMENSIONS:
            raise ValueError("resolution must be 480p, 720p, 1080p, or 4k")
        if variant in {"2.5", "fast", "mini"} and resolution not in {
            "480p",
            "720p",
        }:
            raise ValueError(f"{variant} supports only 480p or 720p resolution")

        ratio = str(inputs.get("aspect_ratio", "16:9"))
        valid_ratios = {
            "adaptive",
            "21:9",
            "16:9",

View on GitHub (pinned to 95e1c3d0ab)

Solutions

Use one of the three exact lowercase strings: 'text_to_video', 'image_to_video', 'reference_to_video'
text-only → text_to_video; one still as first frame → image_to_video; multiple images/video refs → reference_to_video
Check the tool schema's enum before calling

Example fix

# before
inputs = {"operation": "t2v", "prompt": "..."}
# after
inputs = {"operation": "text_to_video", "prompt": "..."}

Defensive patterns

Strategy: validation

Validate before calling

op = str(inputs.get("operation", "text_to_video"))
if op not in {"text_to_video", "image_to_video", "reference_to_video"}:
    raise ValueError(f"operation {op!r} invalid")

Type guard

def is_valid_operation(op: object) -> bool:
    return str(op) in {"text_to_video", "image_to_video", "reference_to_video"}

Prevention

Use dry_run to validate the whole payload before the paid execute
Define operation constants once in your calling code

When it happens

Trigger: Passing `operation: "t2v"` / `"video"` / `"img2vid"` shorthand; a typo like "image_to_vido"; wrong-case "Image_To_Video"; passing None (becomes 'none').

Common situations: Developers porting from other OpenMontage tools or raw API examples that use different operation names; LLM-composed inputs abbreviating; docs from a different Seedance gateway (fal, BytePlus) with their own operation vocabulary.

Related errors

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