unslothai/unsloth · error · ValueError

MiniMax-H3 takes at most 12 references in total, got {total}

Error message

MiniMax-H3 takes at most 12 references in total, got {total}

What it means

Raised by a Pydantic model_validator on VideoGenerateRequest for the MiniMax-H3 video model. The model accepts three kinds of reference inputs (reference_images, reference_videos, reference_audios) but enforces a combined budget of 12 items across all three. The check runs after field validation, so it fires only when the summed count exceeds 12. Pydantic surfaces it as a ValidationError (typically HTTP 422 in FastAPI) with the offending total embedded in the message.

Source

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

    @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 "
                "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

View on GitHub (pinned to 203007d190)

Solutions

1. Reduce the combined reference count to 12 or fewer by removing the least important items from reference_images / reference_videos / reference_audios.
2. Split the generation into multiple requests, each with at most 12 references, and stitch the results.
3. If you genuinely need more references, check whether a different model family without this cap applies to your use case.
4. Add a client-side counter over the three arrays before submitting so users get feedback in the UI.

Example fix

// before
req = {
  "prompt": p,
  "reference_images": imgs,   // 10 items
  "reference_videos": vids,   // 3 items
}
// after
req = {
  "prompt": p,
  "reference_images": imgs[:10],
  "reference_videos": vids[:2],  // total <= 12
}

def reference_count(req: dict) -> int:
    return sum(len(req.get(k) or []) for k in ("reference_images", "reference_videos", "reference_audios"))

def fits_reference_budget(req: dict) -> bool:
    return reference_count(req) <= 12

function isSubmittableVideoRequest(req: unknown): boolean {
  const r = req as Record<string, unknown[]>;
  const n = (r.reference_images?.length ?? 0) + (r.reference_videos?.length ?? 0) + (r.reference_audios?.length ?? 0);
  return n <= 12;
}

try { await client.generate(req) } catch (e) { if (e instanceof ValidationError && e.message.includes('at most 12 references')) trimAndRetry(req); else throw e; }

When it happens

Trigger: POST to the video generation endpoint with any combination of reference_images + reference_videos + reference_audios whose lengths sum to 13 or more, e.g. 8 reference_images + 4 reference_videos + 2 reference_audios (total 14). Each list alone may be under 12; only the combined total triggers it.

Common situations: Building a multi-shot storyboard pipeline that attaches one image per scene shot; batching all reference assets into a single generate call instead of splitting into multiple requests; UI layers that let users attach unlimited references before submit.

Related errors

• reference audio needs at least one reference image or video
• keyframes and references cannot be combined: MiniMax-H3 runs
• width and height must be sent together, or both omitted
• Provide either content_base64 or file_ids, not both
• Provide either content_base64 or file_ids

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