unslothai/unsloth · error · ValueError

MiniMax-H3 reference videos run {H3_REF_VIDEO_MIN_SECONDS:g}

Error message

MiniMax-H3 reference videos run {H3_REF_VIDEO_MIN_SECONDS:g} to {H3_REF_VIDEO_MAX_SECONDS:g} seconds; this one is longer than {H3_REF_VIDEO_MAX_SECONDS:g}s. Trim it first.

What it means

While decoding a reference video frame-by-frame, the decoder counts source frames and raises once decoded_count exceeds max_source_frames = floor(H3_REF_VIDEO_MAX_SECONDS * source_fps + 1e-6), i.e. the clip runs longer than the model's reference window (15s). Checking during the loop (rather than after) bounds decode work and memory for long 4K inputs instead of decoding 10 minutes to then refuse.

Source

Thrown at studio/backend/core/inference/video_minimax_h3.py:401

    with av.open(io.BytesIO(blob)) as container:
        if not container.streams.video:
            raise ValueError("That reference file carries no video track.")
        stream = container.streams.video[0]
        source_fps = float(stream.average_rate or stream.guessed_rate or H3_FPS)
        if source_fps <= 0:
            source_fps = float(H3_FPS)
        # Select, resample, and resize incrementally to bound memory for 4K inputs.
        from PIL import Image

        frames = []
        decoded_count = 0
        next_target = 0
        fitted_size = None
        max_source_frames = math.floor(H3_REF_VIDEO_MAX_SECONDS * source_fps + 1e-6)
        for source_index, frame in enumerate(container.decode(video = 0)):
            decoded_count = source_index + 1
            if decoded_count > max_source_frames:
                raise ValueError(
                    f"MiniMax-H3 reference videos run {H3_REF_VIDEO_MIN_SECONDS:g} to "
                    f"{H3_REF_VIDEO_MAX_SECONDS:g} seconds; this one is longer than "
                    f"{H3_REF_VIDEO_MAX_SECONDS:g}s. Trim it first."
                )
            target_source = int(next_target * source_fps / H3_FPS)
            if target_source > source_index:
                continue
            image = frame.to_image().convert("RGB")
            if fitted_size is None:
                fitted_size = h3_reference_frame_size(*image.size)
            if image.size != fitted_size:
                image = image.resize(fitted_size, Image.LANCZOS)
            while int(next_target * source_fps / H3_FPS) <= source_index:
                frames.append(image)
                next_target += 1

    if decoded_count == 0:
        raise ValueError("That reference video decoded to no frames.")

View on GitHub (pinned to 203007d190)

Solutions

  1. Trim the clip to at most 15s (H3_REF_VIDEO_MAX_SECONDS) before uploading.
  2. Trim to the 2-15s window in one pass: ffmpeg -i in.mp4 -t 15 out.mp4.
  3. Show the 2-15s constraint in the upload UI and validate duration client-side.

Example fix

# before: uploading the full 45s take
upload_reference(blob=open("take.mp4", "rb").read())

# after: trim to the model's window first
ffmpeg -ss 10 -t 5 -i take.mp4 -c copy ref.mp4  # 5s snippet, 2-15s window
Defensive patterns

Strategy: validation

Validate before calling

import av, io

H3_REF_VIDEO_MAX_SECONDS = 15.0

with av.open(io.BytesIO(blob)) as c:
    s = c.streams.video[0]
    fps = float(s.average_rate or s.guessed_rate or 25)
    n = s.frames or 0
    if n and n / fps > H3_REF_VIDEO_MAX_SECONDS:
        raise ValueError("trim reference video to <= 15s")

Try / catch

try:
    frames, wf, sr = decode_h3_reference_video(blob)
except ValueError as e:
    if "longer than" in str(e) and "seconds" in str(e):
        return HTTPException(400, "trim the reference video to 2-15s") from e
    raise

Prevention

When it happens

Trigger: Uploading a 60s or 10-minute clip as an H3 reference video; high-fps sources where even short wall-clock durations exceed the frame budget only after seconds > 15.

Common situations: Users pasting full shot takes instead of the relevant motion snippet; automated pipelines feeding untrimmed stock footage; forgetting the model's reference window is bounded.

Related errors

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