ATH-MaaS/Pixelle-Video · error · ValueError

API video models require image_path, first_clip_path, or ref

Error message

API video models require image_path, first_clip_path, or reference media inputs. Use an image template first or pass input image/video/reference media when calling media generation.

What it means

_generate_video validates that the video model has some input to condition on: an image_path, first_clip_path, reference image/video media, or native text-to-video ability (from adapter_ability_types). If none are present it raises ValueError explaining the requirement.

Source

Thrown at pixelle_video/services/api_media.py:533

        prompt: str,
        image_path: Optional[str],
        output_path: Optional[str],
        duration: Optional[float],
        width: Optional[int],
        height: Optional[int],
        **params,
    ) -> MediaResult:
        from pixelle_video.services.api_services.video_client import VideoClient

        first_clip_path = params.get("first_clip_path") or params.get("first_video_path")
        reference_image_path = params.get("reference_image_path")
        reference_image_paths = params.get("reference_image_paths") or []
        reference_video_paths = params.get("reference_video_paths") or []
        has_reference_inputs = bool(reference_image_path or reference_image_paths or reference_video_paths)
        capabilities = self._video_capabilities(provider, model)
        supports_text_to_video = "text_to_video" in set(capabilities.get("adapter_ability_types") or [])
        if not image_path and not first_clip_path and not has_reference_inputs and not supports_text_to_video:
            raise ValueError(
                "API video models require image_path, first_clip_path, or reference media inputs. "
                "Use an image template first or pass input image/video/reference media when calling media generation."
            )
        if first_clip_path and not image_path and provider != "dashscope":
            raise ValueError(f"first_clip_path is only supported for DashScope wan2.7 models, not provider={provider}.")

        client = self._create_video_client()
        save_path = output_path or os.path.join(self._save_dir(None, "api_videos"), "video.mp4")
        ratio = params.get("video_ratio") or params.get("ratio") or self._ratio(width, height)
        requested_duration = int(duration or params.get("duration") or 5)
        safe_duration = self._video_duration(provider, model, requested_duration)
        resolution = params.get("resolution") or self._video_resolution(provider, width, height)
        video_options = self._video_options(provider, model, params, resolution)

        prompt_to_use = prompt
        max_safety_retries = int(params.get("prompt_safety_retries", 1))
        for attempt in range(max_safety_retries + 1):
            try:

View on GitHub (pinned to 848b054e4f)

Solutions

Provide an input image via image_path (image-to-video), or first_clip_path for DashScope wan2.7
Attach reference_image_paths/reference_video_paths in params when the model supports reference conditioning
Choose a video model whose adapter_ability_types includes 'text_to_video' if you only have a text prompt
Generate an image first (image template) and feed it as image_path

Example fix

# before
await api_media(prompt="ocean waves", media_type="video", workflow="x/i2v-model")
# after
await api_media(prompt="ocean waves", media_type="video", workflow="x/i2v-model",
                image_path="/tmp/first_frame.png")

Defensive patterns

Strategy: validation

Validate before calling

caps = service._video_capabilities(provider, model)
supports_t2v = "text_to_video" in set(caps.get("adapter_ability_types") or [])
if not image_path and not first_clip_path and not refs and not supports_t2v:
    raise ValueError("video model needs an image, first clip, or reference media")

Type guard

def can_generate_video(params: dict, caps: dict) -> bool:
    has_inputs = bool(params.get("image_path") or params.get("first_clip_path")
                      or params.get("reference_image_paths") or params.get("reference_video_paths"))
    return has_inputs or "text_to_video" in set(caps.get("adapter_ability_types") or [])

Try / catch

try:
    out = await api_media(prompt=p, media_type="video", workflow=wf)
except ValueError as e:
    if "require image_path" in str(e):
        frame = await api_media(prompt=p, media_type="image", workflow=image_wf)
        out = await api_media(prompt=p, media_type="video", workflow=wf, image_path=frame)
    else:
        raise

Prevention

Check the model's adapter_ability_types to know if text-to-video is supported
For i2v-only models, generate or supply a first-frame image before video generation
Keep first_clip_path usage restricted to DashScope wan2.7 models
Validate required media inputs in your app before calling video generation

When it happens

Trigger: Calling __call__ with media_type='video' for a model that only does image-to-video, without image_path/first_clip_path/reference media, and the model lacks the 'text_to_video' ability type.

Common situations: Assuming all video models support pure text-to-video (most i2v models don't); passing only a text prompt to an image-conditioned model; forgetting to attach reference media; using a model whose capabilities list doesn't include text_to_video.

Related errors

AI-assisted analysis of ATH-MaaS/Pixelle-Video@848b054e4f (2026-08-30). Data as JSON: /api/errors/fd1c2fee0ef6e0ad. Report an issue: GitHub.