{"record":{"id":"f4e1e35b7c37de14","repo":"calesthio/OpenMontage","slug":"minimax-h3-reference-to-video-requires-at-least-on","errorCode":null,"errorMessage":"MiniMax H3 reference_to_video requires at least one image or video in refers","messagePattern":"MiniMax H3 reference_to_video requires at least one image or video in refers","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"tools/video/atlas_video.py","lineNumber":275,"sourceCode":"                )\n            if images:\n                payload[\"reference_images\"] = images\n            if videos:\n                payload[\"reference_videos\"] = videos\n            if audios:\n                payload[\"reference_audios\"] = audios\n        elif style == \"h3_refers\":\n            refers = list(inputs.get(\"refers\") or [])\n            if not refers:\n                refers = [\n                    *({\"url\": value, \"type\": \"image\"} for value in images),\n                    *({\"url\": value, \"type\": \"video\"} for value in videos),\n                    *({\"url\": value, \"type\": \"audio\"} for value in audios),\n                ]\n                if image:\n                    refers.insert(0, {\"url\": image, \"type\": \"image\"})\n            if not refers or not any(item.get(\"type\") in {\"image\", \"video\"} for item in refers):\n                raise ValueError(\"MiniMax H3 reference_to_video requires at least one image or video in refers\")\n            payload[\"refers\"] = refers\n        elif style == \"gemini_video_clips\":\n            clips = list(inputs.get(\"video_clips\") or [])\n            if not clips and video:\n                clips = [{\"url\": video, \"start\": 0, \"ends\": min(int(inputs.get(\"duration\", 10)), 10)}]\n            if len(clips) != 1:\n                raise ValueError(\"Gemini Omni developer reference_to_video requires exactly one video_clip\")\n            payload[\"video_clips\"] = clips\n            if images:\n                payload[\"images\"] = images\n        elif style == \"gemini_video_edit\":\n            if not video:\n                raise ValueError(\"video_edit requires video_url, video_path, or reference_video_path\")\n            payload[\"video\"] = video\n            if images:\n                if len(images) > spec[\"media_limits\"].get(\"images\", 10):\n                    raise ValueError(\"Gemini Omni video_edit accepts at most 10 reference images\")\n                payload[\"images\"] = images","sourceCodeStart":257,"sourceCodeEnd":293,"githubUrl":"https://github.com/calesthio/OpenMontage/blob/95e1c3d0ab93482159818560f6a8c8e866b9139f/tools/video/atlas_video.py#L257-L293","documentation":"Raised in _build_payload for media_style=='h3_refers' (MiniMax H3 reference route) when the assembled refers list is empty or contains no item with type 'image' or 'video'. H3 requires at least one visual refer; audio-only refers are rejected.","triggerScenarios":"Calling H3 reference_to_video with only audios (they get mapped to type 'audio' and the any() check fails); passing a custom refers list whose entries all have type 'audio' or a missing/misspelled type field; empty refers plus no images/videos/audios/image_url.","commonSituations":"Reusing a seedance-2.5 audio-only workflow on H3; hand-building refers dicts with 'kind' instead of 'type'; an upstream step filtering out all visual assets.","solutions":["Ensure at least one refer entry has type 'image' or type 'video' (exact string) — pass image_url, reference_images, or reference_videos and let the tool build refers for you","If you pass custom refers dicts, verify each has keys url and type in {'image','video','audio'}","For audio-driven generation, use a different model family that supports audio-only references"],"exampleFix":"# before\ninputs = {'model':'minimax/h3','operation':'reference_to_video','refers':[{'url':'a.mp3','type':'audio'}]}\n\n# after\ninputs = {'model':'minimax/h3','operation':'reference_to_video','refers':[{'url':'frame.png','type':'image'},{'url':'a.mp3','type':'audio'}]}","handlingStrategy":"validation","validationCode":"refers = list(inputs.get('refers') or [])\nif not any(r.get('type') in {'image', 'video'} for r in refers):\n    if inputs.get('image_url') or inputs.get('reference_images'):\n        pass  # tool will build visual refers for you\n    else:\n        raise ValueError('H3 refers need an image or video entry')","typeGuard":"def h3_refers_valid(refers: list[dict]) -> bool:\n    return bool(refers) and any(r.get('type') in {'image', 'video'} for r in refers)","tryCatchPattern":"try:\n    result = atlas_video.run(inputs=inputs)\nexcept ValueError as e:\n    if 'MiniMax H3 reference_to_video' in str(e):\n        raise SystemExit('add at least one image/video refer') from e\n    raise","preventionTips":["Prefer letting the tool build refers from reference_images/reference_videos instead of hand-rolling dicts","When hand-building, use exactly {'url': ..., 'type': 'image'|'video'|'audio'}","Never port audio-only seedance-2.5 workflows to H3 unchanged"],"tags":["atlas-cloud","minimax-h3","video-generation","validation"],"backgroundTag":null,"analyzedSha":"95e1c3d0ab93482159818560f6a8c8e866b9139f","analyzedAt":"2026-08-15T06:31:20.014Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}