unslothai/unsloth · error · ValueError

reference audio needs at least one reference image or video

Error message

reference audio needs at least one reference image or video to go with

What it means

Raised by the same model_validator on VideoGenerateRequest (MiniMax-H3). MiniMax-H3 treats reference audio as a modifier of an image or video reference, not a standalone conditioning input, so the request must include at least one reference_image or reference_video whenever reference_audios is non-empty. The check deliberately runs after the 12-item budget check, so a 13-item standalone-audio request fails with the budget error first. It surfaces as a Pydantic ValidationError / HTTP 422.

Source

Thrown at studio/backend/models/inference.py:3789

    def _bounded_reference_media(cls, value: Optional[list[str]]) -> Optional[list[str]]:
        # Bound each item like first_frame, so a list cannot buffer what one field may not.
        if value is not None:
            for item in value:
                if len(item) > 32 * 1024 * 1024:
                    raise ValueError("each reference must be at most 32 MiB (base64)")
        return value

    @model_validator(mode = "after")
    def _references_fit_the_models_budget(self) -> "VideoGenerateRequest":
        images = self.reference_images or []
        videos = self.reference_videos or []
        audios = self.reference_audios or []
        total = len(images) + len(videos) + len(audios)
        if total > 12:
            raise ValueError(f"MiniMax-H3 takes at most 12 references in total, got {total}")
        # Standalone audio must accompany an image or video reference.
        if audios and not images and not videos:
            raise ValueError(
                "reference audio needs at least one reference image or video to go with"
            )
        if (images or videos or audios) and (self.first_frame or self.last_frame):
            raise ValueError(
                "keyframes and references cannot be combined: MiniMax-H3 runs them against "
                "different denoiser partitions"
            )
        return self

    @model_validator(mode = "after")
    def _keyframe_canvas_needs_both_axes(self) -> "VideoGenerateRequest":
        # Omit both axes for "match source", or provide both for an explicit canvas.
        # KEYFRAME requests only. There a half-specified canvas is silently discarded:
        # _resolve_keyframes matches the source aspect whenever either axis is missing, so the
        # axis that was sent never reaches the render and the API would accept one recipe and
        # draw another. Without a keyframe the backend deliberately resolves the missing axis
        # from the family's default preset -- validate_video_request_shape and generate() both
        # document and implement that -- so applying the rule to every request would reject

View on GitHub (pinned to 203007d190)

Solutions

1. Add at least one reference_image or reference_video to the same request alongside the audio.
2. If your intent was audio-only generation, use a dedicated audio endpoint/model instead of video generation.
3. If the audio was meant to set the soundtrack, check whether the model exposes a separate soundtrack/music parameter that composes with prompt-only requests.

Example fix

# before
req = {
  "prompt": p,
  "reference_audios": [audio_b64],
}
# after
req = {
  "prompt": p,
  "reference_images": [image_b64],  # visual anchor required
  "reference_audios": [audio_b64],
}

def audio_has_visual_anchor(req: dict) -> bool:
    has_audio = bool(req.get("reference_audios"))
    has_visual = bool(req.get("reference_images") or req.get("reference_videos"))
    return not has_audio or has_visual

function audioOk(req: { reference_audios?: unknown[]; reference_images?: unknown[]; reference_videos?: unknown[] }): boolean {
  const audio = (req.reference_audios?.length ?? 0) > 0;
  const visual = (req.reference_images?.length ?? 0) + (req.reference_videos?.length ?? 0) > 0;
  return !audio || visual;
}

try { await client.generate(req) } catch (e) { if (/reference audio needs/.test(String(e))) throw new UserError('Attach an image or video with the audio'); else throw e; }

When it happens

Trigger: POST to the video generation endpoint with a non-empty reference_audios array while both reference_images and reference_videos are empty or omitted, e.g. {"prompt": p, "reference_audios": ["data:audio/mp3;base64,..."]} with no visual reference.

Common situations: Trying to do audio-driven or music-driven video generation with no visual anchor; porting a workflow from another API where standalone audio conditioning is supported; forgetting to attach the image that was supposed to accompany a voiceover reference.

Related errors

• MiniMax-H3 takes at most 12 references in total, got {total}
• keyframes and references cannot be combined: MiniMax-H3 runs
• width and height must be sent together, or both omitted
• load error: {p.get('error')}
• model load did not reach ready within {timeout_s}s

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/7079a4768b3dffb2. Report an issue: GitHub.