{"record":{"id":"6432c699f3488246","repo":"unslothai/unsloth","slug":"minimax-h3-supports-aspect-ratios-from-1-4-to-4-1","errorCode":null,"errorMessage":"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.","messagePattern":"MiniMax-H3 supports aspect ratios from 1:4 to 4:1; this image is (.+?)x(.+?) \\((.+?):1\\)\\. Crop it first\\.","errorType":"validation","errorClass":"ValueError","httpStatus":400,"severity":"error","filePath":"studio/backend/core/inference/video_minimax_h3.py","lineNumber":264,"sourceCode":"H3_MAX_ASPECT_RATIO = 4\n\n# Upstream stretches the first frame and center cover-crops the last.\nH3_ANCHOR_FIRST = \"first\"\nH3_ANCHOR_LAST = \"last\"\n\n\ndef h3_canvas_for_aspect(aspect_width: float, aspect_height: float) -> tuple[int, int]:\n    \"\"\"Resolve MiniMax-H3's canvas for an aspect ratio.\n\n    Raises ValueError outside the trained 1:4 to 4:1 range.\n    \"\"\"\n    if aspect_width <= 0 or aspect_height <= 0:\n        raise ValueError(\n            f\"The source image has no usable aspect ratio ({aspect_width}x{aspect_height}).\"\n        )\n    ratio = aspect_width / aspect_height\n    if not H3_MIN_ASPECT_RATIO <= ratio <= H3_MAX_ASPECT_RATIO:\n        raise ValueError(\n            f\"MiniMax-H3 supports aspect ratios from 1:4 to 4:1; this image is \"\n            f\"{aspect_width:g}x{aspect_height:g} ({ratio:.2f}:1). Crop it first.\"\n        )\n    if ratio >= 1.0:\n        width, height = H3_CANVAS_SHORT_EDGE * ratio, float(H3_CANVAS_SHORT_EDGE)\n    else:\n        width, height = float(H3_CANVAS_SHORT_EDGE), H3_CANVAS_SHORT_EDGE / ratio\n    area = width * height\n    if area > H3_CANVAS_MAX_PIXELS:\n        scale = math.sqrt(H3_CANVAS_MAX_PIXELS / area)\n        width, height = width * scale, height * scale\n    snap = lambda v: max(  # noqa: E731\n        H3_CANVAS_MULTIPLE, round(v / H3_CANVAS_MULTIPLE) * H3_CANVAS_MULTIPLE\n    )\n    return snap(width), snap(height)\n\n\ndef fit_h3_keyframe(image: Any, width: int, height: int, *, anchor: str) -> Any:","sourceCodeStart":246,"sourceCodeEnd":282,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/video_minimax_h3.py#L246-L282","documentation":"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.","triggerScenarios":"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.","commonSituations":"Screenshot/video-frame sources with letterboxing or sidebars included; webtoon/scroll-capture uploads; auto-crop pipelines missing an aspect pre-pass.","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."],"exampleFix":"# before: 2048x256 banner (8:1) -> ValueError\nimg = Image.open(\"banner.png\")\n\n# after: center-crop into the trained window\nw, h = img.size\nif w / h > 4: w = 4 * h\nelif h / w > 4: h = 4 * w\nimg = img.crop(((img.width - w) // 2, (img.height - h) // 2,\n                (img.width + w) // 2, (img.height + h) // 2))","handlingStrategy":"validation","validationCode":"ratio = img.width / img.height  # dims already > 0\nif not 0.25 <= ratio <= 4.0:\n    # center-crop into the trained window (H3_MIN/MAX_ASPECT_RATIO)\n    if ratio > 4:\n        new_w = 4 * img.height\n    else:\n        new_h = 4 * img.width\n    img = img.crop(((img.width - new_w) // 2, (img.height - new_h) // 2,\n                    (img.width + new_w) // 2, (img.height + new_h) // 2))","typeGuard":"def h3_aspect_ok(w: float, h: float) -> bool:\n    return w > 0 and h > 0 and 0.25 <= (w / h) <= 4.0","tryCatchPattern":"try:\n    canvas = h3_canvas_for_aspect(w, h)\nexcept ValueError as e:\n    if \"1:4 to 4:1\" in str(e):\n        img = center_crop_to_ratio(img)  # bring inside the window, then retry once\n        canvas = h3_canvas_for_aspect(img.width, img.height)\n    else:\n        raise","preventionTips":["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."],"tags":["video","minimax-h3","aspect-ratio","image","validation"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}