{"record":{"id":"fd1c2fee0ef6e0ad","repo":"ATH-MaaS/Pixelle-Video","slug":"api-video-models-require-image-path-first-clip-pa","errorCode":null,"errorMessage":"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.","messagePattern":"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\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"pixelle_video/services/api_media.py","lineNumber":533,"sourceCode":"        prompt: str,\n        image_path: Optional[str],\n        output_path: Optional[str],\n        duration: Optional[float],\n        width: Optional[int],\n        height: Optional[int],\n        **params,\n    ) -> MediaResult:\n        from pixelle_video.services.api_services.video_client import VideoClient\n\n        first_clip_path = params.get(\"first_clip_path\") or params.get(\"first_video_path\")\n        reference_image_path = params.get(\"reference_image_path\")\n        reference_image_paths = params.get(\"reference_image_paths\") or []\n        reference_video_paths = params.get(\"reference_video_paths\") or []\n        has_reference_inputs = bool(reference_image_path or reference_image_paths or reference_video_paths)\n        capabilities = self._video_capabilities(provider, model)\n        supports_text_to_video = \"text_to_video\" in set(capabilities.get(\"adapter_ability_types\") or [])\n        if not image_path and not first_clip_path and not has_reference_inputs and not supports_text_to_video:\n            raise ValueError(\n                \"API video models require image_path, first_clip_path, or reference media inputs. \"\n                \"Use an image template first or pass input image/video/reference media when calling media generation.\"\n            )\n        if first_clip_path and not image_path and provider != \"dashscope\":\n            raise ValueError(f\"first_clip_path is only supported for DashScope wan2.7 models, not provider={provider}.\")\n\n        client = self._create_video_client()\n        save_path = output_path or os.path.join(self._save_dir(None, \"api_videos\"), \"video.mp4\")\n        ratio = params.get(\"video_ratio\") or params.get(\"ratio\") or self._ratio(width, height)\n        requested_duration = int(duration or params.get(\"duration\") or 5)\n        safe_duration = self._video_duration(provider, model, requested_duration)\n        resolution = params.get(\"resolution\") or self._video_resolution(provider, width, height)\n        video_options = self._video_options(provider, model, params, resolution)\n\n        prompt_to_use = prompt\n        max_safety_retries = int(params.get(\"prompt_safety_retries\", 1))\n        for attempt in range(max_safety_retries + 1):\n            try:","sourceCodeStart":515,"sourceCodeEnd":551,"githubUrl":"https://github.com/ATH-MaaS/Pixelle-Video/blob/848b054e4fae40dabc62ec58e960b573e83793ac/pixelle_video/services/api_media.py#L515-L551","documentation":"_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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\nawait api_media(prompt=\"ocean waves\", media_type=\"video\", workflow=\"x/i2v-model\")\n# after\nawait api_media(prompt=\"ocean waves\", media_type=\"video\", workflow=\"x/i2v-model\",\n                image_path=\"/tmp/first_frame.png\")","handlingStrategy":"validation","validationCode":"caps = service._video_capabilities(provider, model)\nsupports_t2v = \"text_to_video\" in set(caps.get(\"adapter_ability_types\") or [])\nif not image_path and not first_clip_path and not refs and not supports_t2v:\n    raise ValueError(\"video model needs an image, first clip, or reference media\")","typeGuard":"def can_generate_video(params: dict, caps: dict) -> bool:\n    has_inputs = bool(params.get(\"image_path\") or params.get(\"first_clip_path\")\n                      or params.get(\"reference_image_paths\") or params.get(\"reference_video_paths\"))\n    return has_inputs or \"text_to_video\" in set(caps.get(\"adapter_ability_types\") or [])","tryCatchPattern":"try:\n    out = await api_media(prompt=p, media_type=\"video\", workflow=wf)\nexcept ValueError as e:\n    if \"require image_path\" in str(e):\n        frame = await api_media(prompt=p, media_type=\"image\", workflow=image_wf)\n        out = await api_media(prompt=p, media_type=\"video\", workflow=wf, image_path=frame)\n    else:\n        raise","preventionTips":["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"],"tags":["validation","missing-argument","video-generation"],"backgroundTag":"missing-required-input","analyzedSha":"848b054e4fae40dabc62ec58e960b573e83793ac","analyzedAt":"2026-08-30T03:24:41.468Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}