ATH-MaaS/Pixelle-Video · error · ValueError

DashScope reference-to-video models require at least one ref

Error message

DashScope reference-to-video models require at least one reference_image or reference_video input.

What it means

For reference-to-video DashScope models, _build_reference_to_video_media assembles media inputs from reference images/videos. If it returns an empty/None media list, the client refuses to submit an empty request and raises this ValueError. The API would reject such a call anyway, so the client fails fast.

Source

Thrown at pixelle_video/services/api_services/video_dashscope.py:234

            if seed is not None:
                call_kwargs["seed"] = seed
            if audio is not None:
                call_kwargs["audio"] = audio

            rsp = self._with_network_retry(
                "submit task",
                lambda: VideoSynthesis.call(**call_kwargs),
            )
        elif self._is_reference_to_video_model(model):
            media = self._build_reference_to_video_media(
                image_path=image_path,
                reference_image_path=reference_image_path,
                reference_image_paths=reference_image_paths,
                reference_video_paths=reference_video_paths,
                reference_audio_path=None if "happyhorse" in model.lower() else reference_audio_path,
            )
            if not media:
                raise ValueError("DashScope reference-to-video models require at least one reference_image or reference_video input.")

            call_kwargs = {
                "api_key": self.api_key,
                "model": model,
                "prompt": prompt,
                "media": media,
                "duration": duration,
                "watermark": watermark,
            }
            if audio is not None:
                call_kwargs["audio"] = audio
            if negative_prompt:
                call_kwargs["negative_prompt"] = negative_prompt
            if resolution:
                call_kwargs["resolution"] = resolution
            if video_ratio:
                call_kwargs["ratio"] = video_ratio
            if prompt_extend is not None:

View on GitHub (pinned to 848b054e4f)

Solutions

Pass at least one existing reference_image_path or a non-empty reference_video_paths list.
Verify the model name actually requires references; if you want pure text-to-video, switch to a text-to-video model.
Log/inspect the reference arguments right before the call to confirm they are populated.
Fix upstream code that was supposed to supply the reference asset.

Example fix

// before
client.generate_video(model="wan2.6-ref-to-video", prompt=p)  # no refs
// after
client.generate_video(model="wan2.6-ref-to-video", prompt=p,
                      reference_image_path="assets/ref.jpg")

Defensive patterns

Strategy: validation

Validate before calling

if not (reference_image_path or reference_image_paths or reference_video_paths):
    raise ValueError("reference-to-video model needs at least one reference image/video")

Type guard

def has_reference_media(image, images, videos) -> bool:
    return bool(image or [i for i in (images or []) if i] or [v for v in (videos or []) if v])

Try / catch

try:
    client.generate_video(model=model, prompt=p, reference_image_paths=refs)
except ValueError as e:
    logger.error("invalid input combo: %s", e)
    raise

Prevention

Match the model family to available inputs: references for ref-to-video, none for text-to-video.
Guard upstream steps that produce reference assets; default to failing loudly if they yield nothing.
Log the resolved reference arguments before calling generate_video.
Centralize model->required-inputs mapping in one config to avoid drift.

When it happens

Trigger: A model classified by _is_reference_to_video_model is used, but reference_image_path, reference_image_paths, and reference_video_paths all resolve to no usable media (None, empty lists, or only falsy entries).

Common situations: Calling a reference-driven model with only a text prompt (forgot image/video); variable holding the reference path is None because an earlier step failed; passing empty list reference_image_paths=[]; code path refactor dropped the reference argument.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

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