MiniMax H3 Reference-to-Video API by MiniMax

MiniMax H3 Reference-to-Video

MiniMax H3 Reference-to-Video generates a video that keeps the subjects from your reference materials consistent throughout, driven by your text prompt. Instead of animating a fixed frame, it uses the references as identity anchors — ideal for placing a character, product, or style into new scenes and motions. References can be any mix of images, videos, and an audio track (e.g. a music beat) to sync the motion to.

Why Choose This?

• Subject consistency Preserve one or several people, characters, or objects' identities across the whole clip.

• Mix reference types Combine reference images, reference videos, and reference audio in a single request.

• Audio sync (optional) Provide a reference audio track and sync the action to the beat.

• Prompt-driven scenes Put the reference subjects into any scene or action you describe.

• High resolution output Generate videos in 2K quality.

• Flexible aspect ratios adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, or 9:16.

• Selectable duration Produce 4–15s clips.

Parameters

Task Status Callbacks (callback_url)

When you supply a callback_url, the MiniMax server notifies it on every task status change, so you don't have to poll for the result.

1. Verification handshake — right after the task is created, the server first sends a verification request to your URL containing a challenge field. Your endpoint must return the challenge value unchanged, within 3 seconds, to complete verification.
2. Status pushes — once verification succeeds, the server sends a POST to your URL every time the task status changes. The push body has the same structure as the Query Task (task status) response.

Callback status values: queued, running, succeeded, failed, cancelled.

The callback_url must be a publicly reachable HTTPS endpoint.

refers example

"refers": [
  { "url": "https://.../subject1.png", "type": "image" },
  { "url": "https://.../subject2.png" },
  { "url": "https://.../clip.mp4", "type": "video" },
  { "url": "https://.../beat.mp3", "type": "audio" }
]

How to Use

1. Add your references — any mix of images and/or videos (at least one), optionally plus an audio track.
2. Write your prompt — describe the scene, action, and camera movement for the subjects.
3. Set resolution and duration — balance quality against generation speed.
4. Choose an aspect ratio — match your target platform, or use adaptive.
5. Run — submit and download your video.

Best Use Cases

• Character Consistency — Keep the same character across multiple shots.
• Product Placement — Feature a specific product in generated scenes.
• Branded Content — Maintain a consistent mascot or spokesperson.
• Creative Series — Build multi-clip stories around a recurring subject.

Pro Tips

• Use clean, well-lit reference images with each subject clearly visible.
• Give one image per subject when combining several subjects in one video.
• Describe the new scene and action, not the reference materials themselves.
• Supply a reference audio track to drive the timing/beat of the motion.
• Combine with different ratios and durations to repurpose the same subjects across platforms.

Notes

• prompt and at least one reference image or video are required; a request with only audio is rejected.
• Reference-to-video and image-to-video are mutually exclusive: this model uses reference materials, not first/last frames — do not mix the two.
• Ensure all reference URLs (image / video / audio) are publicly accessible.
• Generation is asynchronous — submit, then poll for the finished video.

Related Models

• MiniMax H3 Text-to-Video — Generate video directly from a text prompt.
• MiniMax H3 Image-to-Video — Animate a first-frame image (optionally with a last frame).