calesthio/OpenMontage · error · ValueError

MiniMax H3 reference_to_video requires at least one image or

Error message

MiniMax H3 reference_to_video requires at least one image or video in refers

What it means

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.

Source

Thrown at tools/video/atlas_video.py:275

                )
            if images:
                payload["reference_images"] = images
            if videos:
                payload["reference_videos"] = videos
            if audios:
                payload["reference_audios"] = audios
        elif style == "h3_refers":
            refers = list(inputs.get("refers") or [])
            if not refers:
                refers = [
                    *({"url": value, "type": "image"} for value in images),
                    *({"url": value, "type": "video"} for value in videos),
                    *({"url": value, "type": "audio"} for value in audios),
                ]
                if image:
                    refers.insert(0, {"url": image, "type": "image"})
            if not refers or not any(item.get("type") in {"image", "video"} for item in refers):
                raise ValueError("MiniMax H3 reference_to_video requires at least one image or video in refers")
            payload["refers"] = refers
        elif style == "gemini_video_clips":
            clips = list(inputs.get("video_clips") or [])
            if not clips and video:
                clips = [{"url": video, "start": 0, "ends": min(int(inputs.get("duration", 10)), 10)}]
            if len(clips) != 1:
                raise ValueError("Gemini Omni developer reference_to_video requires exactly one video_clip")
            payload["video_clips"] = clips
            if images:
                payload["images"] = images
        elif style == "gemini_video_edit":
            if not video:
                raise ValueError("video_edit requires video_url, video_path, or reference_video_path")
            payload["video"] = video
            if images:
                if len(images) > spec["media_limits"].get("images", 10):
                    raise ValueError("Gemini Omni video_edit accepts at most 10 reference images")
                payload["images"] = images

View on GitHub (pinned to 95e1c3d0ab)

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

Example fix

# before
inputs = {'model':'minimax/h3','operation':'reference_to_video','refers':[{'url':'a.mp3','type':'audio'}]}

# after
inputs = {'model':'minimax/h3','operation':'reference_to_video','refers':[{'url':'frame.png','type':'image'},{'url':'a.mp3','type':'audio'}]}

Defensive patterns

Strategy: validation

Validate before calling

refers = list(inputs.get('refers') or [])
if not any(r.get('type') in {'image', 'video'} for r in refers):
    if inputs.get('image_url') or inputs.get('reference_images'):
        pass  # tool will build visual refers for you
    else:
        raise ValueError('H3 refers need an image or video entry')

Type guard

def h3_refers_valid(refers: list[dict]) -> bool:
    return bool(refers) and any(r.get('type') in {'image', 'video'} for r in refers)

Try / catch

try:
    result = atlas_video.run(inputs=inputs)
except ValueError as e:
    if 'MiniMax H3 reference_to_video' in str(e):
        raise SystemExit('add at least one image/video refer') from e
    raise

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of calesthio/OpenMontage@95e1c3d0ab (2026-08-15). Data as JSON: /api/errors/f4e1e35b7c37de14. Report an issue: GitHub.