unslothai/unsloth · error · ValueError

MiniMax-H3 supports aspect ratios from 1:4 to 4:1; this imag

Error message

MiniMax-H3 supports aspect ratios from 1:4 to 4:1; this image is {aspect_width:g}x{aspect_height:g} ({ratio:.2f}:1). Crop it first.

What it means

h3_canvas_for_aspect raises ValueError when the source image's aspect ratio falls outside MiniMax-H3's trained range of 1:4 to 4:1 (H3_MIN_ASPECT_RATIO..H3_MAX_ASPECT_RATIO). The canvas short-edge math (H3_CANVAS_SHORT_EDGE scaled by ratio) only produces sane output inside that window, so extreme panoramas or tall strips are refused with an instruction to crop first rather than being stretched.

Source

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

H3_MAX_ASPECT_RATIO = 4

# Upstream stretches the first frame and center cover-crops the last.
H3_ANCHOR_FIRST = "first"
H3_ANCHOR_LAST = "last"


def h3_canvas_for_aspect(aspect_width: float, aspect_height: float) -> tuple[int, int]:
    """Resolve MiniMax-H3's canvas for an aspect ratio.

    Raises ValueError outside the trained 1:4 to 4:1 range.
    """
    if aspect_width <= 0 or aspect_height <= 0:
        raise ValueError(
            f"The source image has no usable aspect ratio ({aspect_width}x{aspect_height})."
        )
    ratio = aspect_width / aspect_height
    if not H3_MIN_ASPECT_RATIO <= ratio <= H3_MAX_ASPECT_RATIO:
        raise ValueError(
            f"MiniMax-H3 supports aspect ratios from 1:4 to 4:1; this image is "
            f"{aspect_width:g}x{aspect_height:g} ({ratio:.2f}:1). Crop it first."
        )
    if ratio >= 1.0:
        width, height = H3_CANVAS_SHORT_EDGE * ratio, float(H3_CANVAS_SHORT_EDGE)
    else:
        width, height = float(H3_CANVAS_SHORT_EDGE), H3_CANVAS_SHORT_EDGE / ratio
    area = width * height
    if area > H3_CANVAS_MAX_PIXELS:
        scale = math.sqrt(H3_CANVAS_MAX_PIXELS / area)
        width, height = width * scale, height * scale
    snap = lambda v: max(  # noqa: E731
        H3_CANVAS_MULTIPLE, round(v / H3_CANVAS_MULTIPLE) * H3_CANVAS_MULTIPLE
    )
    return snap(width), snap(height)


def fit_h3_keyframe(image: Any, width: int, height: int, *, anchor: str) -> Any:

View on GitHub (pinned to 203007d190)

Solutions

Center-crop the source image to within 1:4..4:1 before generating (strip letterbox bars first if present).
Pad the short side instead of cropping if losing content is unacceptable — but crop is what the message recommends.
Pre-check ratio = width/height client-side: 0.25 <= ratio <= 4.0.

Example fix

# before: 2048x256 banner (8:1) -> ValueError
img = Image.open("banner.png")

# after: center-crop into the trained window
w, h = img.size
if w / h > 4: w = 4 * h
elif h / w > 4: h = 4 * w
img = img.crop(((img.width - w) // 2, (img.height - h) // 2,
                (img.width + w) // 2, (img.height + h) // 2))

Defensive patterns

Strategy: validation

Validate before calling

ratio = img.width / img.height  # dims already > 0
if not 0.25 <= ratio <= 4.0:
    # center-crop into the trained window (H3_MIN/MAX_ASPECT_RATIO)
    if ratio > 4:
        new_w = 4 * img.height
    else:
        new_h = 4 * img.width
    img = img.crop(((img.width - new_w) // 2, (img.height - new_h) // 2,
                    (img.width + new_w) // 2, (img.height + new_h) // 2))

Type guard

def h3_aspect_ok(w: float, h: float) -> bool:
    return w > 0 and h > 0 and 0.25 <= (w / h) <= 4.0

Try / catch

try:
    canvas = h3_canvas_for_aspect(w, h)
except ValueError as e:
    if "1:4 to 4:1" in str(e):
        img = center_crop_to_ratio(img)  # bring inside the window, then retry once
        canvas = h3_canvas_for_aspect(img.width, img.height)
    else:
        raise

Prevention

Strip letterbox/side bars before image-to-video.
Pre-check 0.25 <= w/h <= 4.0 on every source image.
Offer an auto-crop option in the UI instead of failing.

When it happens

Trigger: Image-to-video with an extreme source: a 20:1 banner, a 1:10 vertical strip, a cinematic letterboxed frame with black bars pushing the ratio past 4:1.

Common situations: Screenshot/video-frame sources with letterboxing or sidebars included; webtoon/scroll-capture uploads; auto-crop pipelines missing an aspect pre-pass.

Related errors

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