minimax/h3/reference-to-video
Generate native-stereo 2K video guided by image, video, and audio references with MiniMax H3.
PNG, JPEG, WebP, or GIF · 20 MiB maximum each · up to 9
Example output — click Run to generate your own
Send your first request
OpenAI-compatible endpoint with unified authentication and usage tracking.
https://api.sandbase.ai/v1/runminimax/h3/reference-to-videoInput Schema
8 parameters · 2 required · 6 optional
| Parameter | Type | Required | Description |
|---|---|---|---|
prompt | string | Required | Min length: 1 · Max length: 7000 · Default: "Keep the referenced character and motion consistent while creating a cinematic garden scene with synchronized ambient sound." |
duration | integer | Required | Options: 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 · Default: 5 456789101112131415 |
audios | string[] | Optional | Audio requires at least one reference image or video. |
images | string[] | Optional | — |
videos | string[] | Optional | Each clip must be 2–15 seconds; combined duration must not exceed 15 seconds. |
resolution | string | Optional | Output resolution. 768P is generated natively; 2K is upscaled via an in-context regeneration pass. · Options: 768P, 2K · Default: "2K" 768P2K |
aspect_ratio | string | Optional | Options: adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 · Default: "adaptive" adaptive21:916:94:31:13:49:16 |
aigc_watermark | boolean | Optional | Whether to add an AIGC label watermark to the generated video. · Default: false |
Output Schema
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the generation task |
status | string | Task status: pending, running, completed, failed, timeout |
model | string | Model used for the generation |
outputs | array | Array of output items |
outputs[].url | string | URL of the generated artifact |
outputs[].content_type | string | MIME type (e.g. image/png, video/mp4) |
error | object | null | Error details if failed, null on success |
error.type | string | Machine-readable error type code |
error.message | string | Human-readable error description |
Async Workflow
This model uses asynchronous execution. Submit a request and poll for the result.
- Submit — POST to /v1/run, receive an
id - Poll — GET /v1/run/{id} until status is
completed,failed, ortimeout - Retrieve — Read
outputsfrom the completed response
Code Examples
Ready-to-run snippets
# Step 1: Submit
curl -X POST https://api.sandbase.ai/v1/run \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"model": "minimax/h3/reference-to-video",
"prompt": "Keep the referenced character and motion consistent while creating a cinematic garden scene with synchronized ambient sound.",
"duration": 5,
"resolution": "2K",
"aspect_ratio": "adaptive",
"aigc_watermark": false
}'
# Step 2: Poll result (replace <id>)
curl https://api.sandbase.ai/v1/run/<id> \
-H "Authorization: Bearer YOUR_API_KEY"API README
MiniMax H3 Reference to Video
MiniMax H3 Reference to Video creates native-stereo video from a prompt plus optional image, video, and audio references. It can combine up to nine images, three video clips, and three audio clips, giving a single generation access to appearance, motion, scene, and sound cues.
The route supports 4–15 second outputs at 768P or 2K, with adaptive and six fixed aspect ratios. Reference clips can influence completed-task duration, so final billing prefers reported usage.total_seconds; the selected output duration is only the fallback when that usage value is absent.
Highlights
- Unified multimodal references. Mix images, video clips, and audio clips in one request to guide character identity, motion, environment, timing, and sound.
- Native stereo output. Generate video with synchronized stereo audio rather than treating sound as a separate post-production step.
- Longer reference-guided shots. Select 4–15 seconds of output and provide up to three reference videos, each 2–15 seconds with a 15-second combined limit.
- High-resolution delivery. Choose native 768P or 2K produced through an in-context regeneration upscale, with adaptive or fixed cinematic and social aspect ratios.
Pricing
Final billing uses completed-task usage.total_seconds when present. If it is absent, the selected duration is used. The time charge is $0.08 per total second at 768P or $0.13 per total second at 2K. The first five reference images are included; images 6–9 add $0.04 each. Reference audio has no separate term in this pricing formula.
Fallback duration prices below apply only when usage.total_seconds is absent and before any extra-image surcharge.
| Duration | Resolution | Fallback price | Condition |
|---|---|---|---|
| 4 seconds | 768P | $0.32 | Only when usage.total_seconds is absent; excludes extra-image surcharge. |
| 4 seconds | 2K | $0.52 | Only when usage.total_seconds is absent; excludes extra-image surcharge. |
| 5 seconds | 768P | $0.40 | Only when usage.total_seconds is absent; excludes extra-image surcharge. |
| 5 seconds | 2K | $0.65 | Only when usage.total_seconds is absent; excludes extra-image surcharge. |
| 6 seconds | 768P | $0.48 | Only when usage.total_seconds is absent; excludes extra-image surcharge. |
| 6 seconds | 2K | $0.78 | Only when usage.total_seconds is absent; excludes extra-image surcharge. |
| 7 seconds | 768P | $0.56 | Only when usage.total_seconds is absent; excludes extra-image surcharge. |
| 7 seconds | 2K | $0.91 | Only when usage.total_seconds is absent; excludes extra-image surcharge. |
| 8 seconds | 768P | $0.64 | Only when usage.total_seconds is absent; excludes extra-image surcharge. |
| 8 seconds | 2K | $1.04 | Only when usage.total_seconds is absent; excludes extra-image surcharge. |
| 9 seconds | 768P | $0.72 | Only when usage.total_seconds is absent; excludes extra-image surcharge. |
| 9 seconds | 2K | $1.17 | Only when usage.total_seconds is absent; excludes extra-image surcharge. |
| 10 seconds | 768P | $0.80 | Only when usage.total_seconds is absent; excludes extra-image surcharge. |
| 10 seconds | 2K | $1.30 | Only when usage.total_seconds is absent; excludes extra-image surcharge. |
| 11 seconds | 768P | $0.88 | Only when usage.total_seconds is absent; excludes extra-image surcharge. |
| 11 seconds | 2K | $1.43 | Only when usage.total_seconds is absent; excludes extra-image surcharge. |
| 12 seconds | 768P | $0.96 | Only when usage.total_seconds is absent; excludes extra-image surcharge. |
| 12 seconds | 2K | $1.56 | Only when usage.total_seconds is absent; excludes extra-image surcharge. |
| 13 seconds | 768P | $1.04 | Only when usage.total_seconds is absent; excludes extra-image surcharge. |
| 13 seconds | 2K | $1.69 | Only when usage.total_seconds is absent; excludes extra-image surcharge. |
| 14 seconds | 768P | $1.12 | Only when usage.total_seconds is absent; excludes extra-image surcharge. |
| 14 seconds | 2K | $1.82 | Only when usage.total_seconds is absent; excludes extra-image surcharge. |
| 15 seconds | 768P | $1.20 | Only when usage.total_seconds is absent; excludes extra-image surcharge. |
| 15 seconds | 2K | $1.95 | Only when usage.total_seconds is absent; excludes extra-image surcharge. |
| Reference images | Extra-image surcharge |
|---|---|
| 1–5 | $0.00 |
| 6 | $0.04 |
| 7 | $0.08 |
| 8 | $0.12 |
| 9 | $0.16 |
When to Use
| Use case | Why this model fits |
|---|---|
| Character-consistent scenes | Use several images to establish appearance, wardrobe, props, and environment. |
| Motion transfer and choreography | Provide short video references for movement, pacing, or camera behavior. |
| Audio-led video | Supply voice, music, or ambience references to guide synchronized native-stereo output. |
| Reference-rich story shots | Combine visual, motion, and sound cues within one 4–15 second generation. |
| High-resolution social or cinematic delivery | Choose adaptive framing or a fixed ratio at 768P or 2K. |
Prompt Guide
State what must remain consistent from the references, then describe the new action and scene in chronological order. Separate character, motion, camera, lighting, and audio direction into clear clauses. Use reference media only when it contributes a distinct cue, and remember that reference-video time can affect usage.total_seconds and therefore the final charge.
{
"prompt": "Keep the lead character's face, green jacket, and silver bicycle consistent with the reference images. Follow the smooth turn and forward motion from the reference video as the character rides through a sunlit botanical garden. Begin with a medium tracking shot, arc slowly to the front, and end on a wide reveal. Preserve the referenced birdsong and add subtle bicycle-wheel movement in native stereo.",
"images": [
"https://example.com/character-front.jpg",
"https://example.com/character-outfit.jpg"
],
"videos": ["https://example.com/bicycle-motion.mp4"],
"audios": ["https://example.com/garden-ambience.wav"],
"duration": 10,
"aspect_ratio": "16:9",
"resolution": "2K",
"aigc_watermark": false
}
Technical Specs
| Property | Details |
|---|---|
| Model ID | minimax/h3/reference-to-video |
| Required inputs | prompt, duration |
| Reference images | Up to 9 |
| Reference videos | Up to 3; each 2–15 seconds, maximum 15 seconds combined |
| Reference audio | Up to 3; requires at least one reference image or video |
| Prompt length | 1–7,000 characters |
| Output duration | Whole seconds from 4 through 15; default 5 |
| Resolution | 768P or 2K (default) |
| Aspect ratio | adaptive (default), 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 |
| Watermark control | Optional aigc_watermark; default false |
| Output | Downloadable video URL with optional content type |
| Execution | Asynchronous |
Related Models
minimax/h3/image-to-video— animate an input image with the H3 family.minimax/h3/text-to-video— generate H3 video directly from text.minimax/hailuo/2.3/pro/image-to-video— compare with MiniMax's Hailuo Pro image animation route.

