{"record":{"id":"243335f8942b91e0","repo":"unslothai/unsloth","slug":"each-reference-must-be-at-most-32-mib-base64","errorCode":null,"errorMessage":"each reference must be at most 32 MiB (base64)","messagePattern":"each reference must be at most 32 MiB \\(base64\\)","errorType":"validation","errorClass":"ValueError","httpStatus":422,"severity":"error","filePath":"studio/backend/models/inference.py","lineNumber":3776,"sourceCode":"        \"Diffusers engine: stable-diffusion.cpp derives the audio schedule against a hardcoded \"\n        \"3.0, so it has no flag to map this onto. null keeps the released value.\",\n    )\n    reference_image_size: Optional[Literal[\"match\", \"max\"]] = Field(\n        None,\n        description = \"How reference images are sized: match (default) scales each down to the \"\n        \"generation's pixel area; max uses the reference pipeline's 2048px short edge for \"\n        \"stronger identity fidelity, several times slower. max needs the Diffusers engine -- \"\n        \"stable-diffusion.cpp rescales every reference to the generation area regardless.\",\n    )\n\n    @field_validator(\"reference_images\", \"reference_audios\")\n    @classmethod\n    def _bounded_reference_media(cls, value: Optional[list[str]]) -> Optional[list[str]]:\n        # Bound each item like first_frame, so a list cannot buffer what one field may not.\n        if value is not None:\n            for item in value:\n                if len(item) > 32 * 1024 * 1024:\n                    raise ValueError(\"each reference must be at most 32 MiB (base64)\")\n        return value\n\n    @model_validator(mode = \"after\")\n    def _references_fit_the_models_budget(self) -> \"VideoGenerateRequest\":\n        images = self.reference_images or []\n        videos = self.reference_videos or []\n        audios = self.reference_audios or []\n        total = len(images) + len(videos) + len(audios)\n        if total > 12:\n            raise ValueError(f\"MiniMax-H3 takes at most 12 references in total, got {total}\")\n        # Standalone audio must accompany an image or video reference.\n        if audios and not images and not videos:\n            raise ValueError(\n                \"reference audio needs at least one reference image or video to go with\"\n            )\n        if (images or videos or audios) and (self.first_frame or self.last_frame):\n            raise ValueError(\n                \"keyframes and references cannot be combined: MiniMax-H3 runs them against \"","sourceCodeStart":3758,"sourceCodeEnd":3794,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/models/inference.py#L3758-L3794","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Re-encode audio to a compressed format (MP3/OGG/Opus) and images to JPEG/WebP at reasonable resolution before base64.","Trim audio references to the needed span.","Assert len(b64) <= 32*1024*1024 per item pre-submit (see validationCode)."],"exampleFix":"# before\nb64 = base64.b64encode(open('voice.wav', 'rb').read()).decode()\n\n# after\nimport subprocess\nsubprocess.run(['ffmpeg', '-i', 'voice.wav', '-c:a', 'libopus', '-b:a', '48k', 'voice.opus'], check=True)\nb64 = base64.b64encode(open('voice.opus', 'rb').read()).decode()","handlingStrategy":"validation","validationCode":"MAX_B64 = 32 * 1024 * 1024\ndef media_within_limit(refs: list[str] | None) -> bool:\n    return refs is None or all(len(r) <= MAX_B64 for r in refs)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Encode audio as Opus/MP3 and images as JPEG/WebP before base64","Trim audio references to the needed span","Budget per-item: a 32 MiB base64 WAV is only ~3 minutes of stereo audio"],"tags":["pydantic","validation","video","payload-limit","base64","reference-media"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}