unslothai/unsloth · error · ValueError

each reference must be at most 32 MiB (base64)

Error message

each reference must be at most 32 MiB (base64)

What it means

Raised by the _bounded_reference_media field_validator on VideoGenerateRequest when any single base64 entry in reference_images or reference_audios exceeds 32 MiB. The cap mirrors first_frame's bound so a list cannot buffer what one field may not — one oversized reference in a multi-reference video request fails fast as a 422 instead of exhausting memory.

Source

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

        "Diffusers engine: stable-diffusion.cpp derives the audio schedule against a hardcoded "
        "3.0, so it has no flag to map this onto. null keeps the released value.",
    )
    reference_image_size: Optional[Literal["match", "max"]] = Field(
        None,
        description = "How reference images are sized: match (default) scales each down to the "
        "generation's pixel area; max uses the reference pipeline's 2048px short edge for "
        "stronger identity fidelity, several times slower. max needs the Diffusers engine -- "
        "stable-diffusion.cpp rescales every reference to the generation area regardless.",
    )

    @field_validator("reference_images", "reference_audios")
    @classmethod
    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 "

View on GitHub (pinned to 203007d190)

Solutions

1. Re-encode audio to a compressed format (MP3/OGG/Opus) and images to JPEG/WebP at reasonable resolution before base64.
2. Trim audio references to the needed span.
3. Assert len(b64) <= 32*1024*1024 per item pre-submit (see validationCode).

Example fix

# before
b64 = base64.b64encode(open('voice.wav', 'rb').read()).decode()

# after
import subprocess
subprocess.run(['ffmpeg', '-i', 'voice.wav', '-c:a', 'libopus', '-b:a', '48k', 'voice.opus'], check=True)
b64 = base64.b64encode(open('voice.opus', 'rb').read()).decode()

MAX_B64 = 32 * 1024 * 1024
def media_within_limit(refs: list[str] | None) -> bool:
    return refs is None or all(len(r) <= MAX_B64 for r in refs)

When it happens

Trigger: POST a video generation with reference_audios containing a long raw/WAV base64 (>32 MiB after encoding) or reference_images with an uncompressed full-res photo. WAV at 44.1kHz stereo 16-bit hits 32 MiB base64 in roughly 3 minutes of audio.

Common situations: Feeding uncompressed WAV instead of compressed audio; full-resolution camera frames as references; users assuming the limit is per-request rather than per-item and stacking many large references.

Related errors

• A reference decoded to no data.
• each reference image must be at most 32 MiB (base64)
• A reference was sent empty.
• Invalid base64 media data: {exc}
• Invalid base64 image data: {exc}

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