MiniMax H3 Reference-to-Video API

minimax/h3/reference-to-video

2K · 5–15 sec

MiniMax H3 Reference-to-Video API accepts a prompt, up to 9 reference images, 3 reference videos, and 3 optional reference audio clips. Include at least one image or video, then choose a 5–15 second duration and adaptive or fixed framing for the fixed 2K video task.

Input

Prompt

688/2000

Reference images

1/9

Add image

Reference videos

1/3

Add video

Reference audios

1/3

natural-rain-5s.mp3

Resolution

Duration

Aspect ratio

Output

Ready

Continue with

MiniMax H3 Text-to-Video MiniMax H3 Image-to-Video

REST API

Quick Start

Make your first reference-to-video request in three steps. The short example shows how to assign a clear role to each reference, then returns a task_id for result retrieval.

Connect to the Vidgo API

Create an API key, keep it on your server, and send it in the Authorization header as a Bearer token.

Endpoint: POSThttps://api.vidgo.ai/api/generate/submit
Authentication: Authorization: Bearer VIDGO_API_KEY

Submit one generation task

Run the short example with at least one image or video reference. Audio is optional and cannot be submitted as the only reference type.

Submit request

curl --request POST \
  --url "https://api.vidgo.ai/api/generate/submit" \
  --header "Authorization: Bearer $VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "minimax/h3/reference-to-video",
  "input": {
    "prompt": "Use the first image for character appearance and the reference video for movement.",
    "reference_image_urls": [
      "https://example.com/character.jpg"
    ],
    "reference_video_urls": [
      "https://example.com/motion.mp4"
    ],
    "duration": 5,
    "resolution": "2K",
    "aspect_ratio": "adaptive"
  }
}'

Wait for the result

Use the returned task_id to check the same task until it reaches finished or failed. On success, read data.files[].file_url.

Track status

GET https://api.vidgo.ai/api/generate/status/{task_id}

Poll about every 2 seconds while the status is not_started or running. Stop on finished or failed; on success, read data.files[].file_url. For long-running jobs, increase the interval gradually, or add callback_url to the submit request to receive the final result asynchronously.

not_startedrunningfinishedfailed

Submit response

{
  "code": 200,
  "data": {
    "task_id": "task-unified-...",
    "status": "running",
    "created_time": "2026-08-22T10:00:00Z"
  }
}

Finished response

{
  "code": 200,
  "data": {
    "task_id": "task-unified-...",
    "status": "finished",
    "files": [
      {
        "file_url": "https://storage.vidgo.ai/generated/video.mp4",
        "file_type": "video"
      }
    ],
    "created_time": "2026-08-22T10:00:00Z",
    "progress": 100,
    "error_message": null
  }
}

Complete runnable example

Open this after the three-step flow is clear. It combines submission, polling, terminal-state handling, and result extraction in one script.

Complete runnable example

set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "minimax/h3/reference-to-video",
  "input": {
    "prompt": "Use the first image for character appearance and the reference video for movement.",
    "reference_image_urls": [
      "https://example.com/character.jpg"
    ],
    "reference_video_urls": [
      "https://example.com/motion.mp4"
    ],
    "duration": 5,
    "resolution": "2K",
    "aspect_ratio": "adaptive"
  }
}
JSON
)

SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://api.vidgo.ai/api/generate/submit" \
  --header "Authorization: Bearer $VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data "$REQUEST_BODY")

TASK_ID=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.data.task_id // .task_id // empty')
if [ -z "$TASK_ID" ]; then
  printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
  exit 1
fi

while true; do
  STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
    --url "https://api.vidgo.ai/api/generate/status/$TASK_ID" \
    --header "Authorization: Bearer $VIDGO_API_KEY")
  STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')

  case "$STATUS" in
    finished)
      printf '%s' "$STATUS_RESPONSE" | jq -r '(.data.files // .files // [])[]?.file_url'
      break
      ;;
    failed)
      printf '%s' "$STATUS_RESPONSE" | jq -r '.data.error_message // .error_message // "Generation failed"' >&2
      exit 1
      ;;
    not_started|running)
      sleep 2
      ;;
    *)
      printf 'Unexpected task status: %s
' "$STATUS" >&2
      exit 1
      ;;
  esac
done

Request Parameters

Send model and optional callback_url at the top level. Put the prompt, references, and generation settings inside input.

Field	Type	Required	Default	Description
model	string	Yes	—	Must be minimax/h3/reference-to-video.
callback_url	string (URL)	No	—	Optional public HTTP(S) endpoint that receives the final asynchronous result. Omit it when polling.
input	object	Yes	—	Container for the model-specific generation parameters below.
input.prompt	string	Yes	—	Trimmed scene and reference-role prompt from 1 to 2,000 characters.
input.reference_image_urls	string[]	Conditional	—	Up to 9 image URLs. At least one reference image or video is required.
input.reference_video_urls	string[]	Conditional	—	Up to 3 video URLs. At least one reference image or video is required.
input.reference_audio_urls	string[]	No	—	Up to 3 audio URLs. Audio cannot be the only reference type.
input.duration	integer	No	5	Generated duration in whole seconds, from 5 through 15.
input.resolution	string	No	2K	Fixed output resolution. The only accepted value is 2K.
input.aspect_ratio	string	No	—	adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, or 9:16.

Response Fields

Submission returns the task identity immediately. Status responses add progress, output files, or a failure message as the task advances.

Field	Type	Description
code	integer	Application result code. Successful responses use 0 or 200.
message	string	Human-readable response or error message when present.
data.task_id	string	Task identifier used in the status endpoint path.
data.status	string	Current state: not_started, running, finished, or failed.
data.created_time	string	Task creation time in date-time format.
data.progress	number	Completion percentage when the provider reports progress.
data.files[]	array	Generated output files returned after a successful task.
data.files[].file_url	string	Public URL of the generated video.
data.files[].file_type	string	Generated file type, such as video.
data.files[].watermark_url	string \| null	Watermarked output URL when one is available.
data.error_message	string \| null	Failure detail when status is failed.

Task Lifecycle

Treat not_started and running as non-terminal states. finished and failed are terminal alternatives; stop polling when either is returned.

not_started
The task was accepted and is waiting to begin.
running
Generation is in progress. Continue polling the same task_id.
finished
Generation succeeded. Read the video URL from data.files[].file_url.
failed
Generation stopped with an error. Read data.error_message and do not continue polling.

Polling and Errors

AuthenticationA 401 response indicates a missing or invalid Bearer API key. Correct the credential before retrying.
ValidationA 400 response means the request is invalid. Read the response message and correct the named field.
Polling intervalStart around every 2 seconds. Increase the interval gradually for long-running tasks.
Terminal statesContinue only for not_started or running. Stop immediately on finished or failed.
Callback optionProvide callback_url to receive the final asynchronous result; otherwise use the status endpoint.

Model Specifications

Specification	Value	Details
Input mode	Prompt + references	At least one reference image or video is required; reference audio is optional.
Output	Video	MiniMax H3 Reference-to-Video API returns an asynchronous video generation task.
Resolution	2K	Resolution is fixed for every accepted request.
Duration	5–15 seconds	Use a whole-second value; the default is 5 seconds.
Aspect ratio	Adaptive or fixed	Supports adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, and 9:16.
Reference limits	9 images / 3 videos / 3 audios	Audio cannot be submitted without at least one image or video reference.

View MiniMax H3 Reference-to-Video API documentation

MiniMax H3 Reference-to-Video API

MiniMax H3 Reference-to-Video API combines a required prompt with public HTTP(S) image, video, and optional audio URLs. A request must include at least one image or video; audio cannot be the only reference type. Successful submission returns an asynchronous fixed-2K video task.

Why Choose MiniMax H3 Reference-to-Video API?

Combine three reference-media types.Submit image and video URLs with optional audio URLs in the same request.
Use explicit reference limits.Combine up to 9 images, 3 videos, and 3 audio clips in one request.
Assign explicit source roles.In the prompt, identify the intended role of each image, video, and audio reference.
Choose adaptive or fixed framing.Set aspect_ratio to adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, or 9:16.
Fixed 2K output with itemized billing.Generated seconds, billable reference-video seconds, and reference images after the first five are priced separately.

Parameters

Parameter	Requirement	Description
prompt	Required	Describe the target scene, action, and role of each reference in 1 to 2,000 characters after trimming.
reference_image_urls	Conditional, max 9	Up to 9 public HTTP(S) image URLs. At least one image or video is required.
reference_video_urls	Conditional, max 3	Up to 3 public HTTP(S) video URLs. Billed video duration contributes to the final cost.
reference_audio_urls	Optional, max 3	Up to 3 public HTTP(S) audio URLs. Audio cannot be submitted without an image or video reference.
duration	Optional	Whole generated seconds from 5 through 15. Default`55–15`
resolution	Fixed	No other resolution is accepted. Default`2K`
aspect_ratio	Optional	Let the frame adapt or choose a fixed delivery ratio. `adaptive21:916:94:31:13:49:16`

How to Use

Choose the source setAdd at least one image or video, then include audio only when sound or rhythm should guide the result.
Assign source rolesState which source defines appearance, motion, setting, camera behavior, or sound.
Describe relationships and actionExplain how the referenced subject, movement, environment, and sound should combine in the new scene.
Set framing and timingChoose adaptive or fixed framing, then select 5 to 15 seconds.
Submit and trackRun the request, then poll the task ID or use a callback URL.

Pricing

Pricing combines generated duration with reference usage. Generated video and billed reference-video time cost 21 credits per second; images after the first five add a separate charge.

Usage	Rate	Details
Generated video	21 credits per second	Before reference charges, 5 seconds costs 105 credits, 10 seconds costs 210 credits, and 15 seconds costs 315 credits.
Reference video	21 credits per billed second	The backend rounds each reference video down to whole seconds separately, then adds the billed seconds.
Reference images 1 to 5	No image surcharge	The first five reference images do not add an image-specific charge.
Reference images 6 to 9	6.4 credits each	Each image after the first five adds 6.4 credits, up to the nine-image limit.

Best Use Cases

Character ConsistencyCarry recognizable character appearance and visual language across new short scenes.
Campaign Reference SetsSubmit approved product images, motion examples, and optional audio references in one video request.
Product and E-commerce VariantsGuide launch and catalog videos with existing product, environment, and motion references.
Game and Film PrevisualizationExplore staging, camera movement, and sound direction from a shared set of creative references.

Pro Tips

Use clean references with one obvious subject or purpose whenever possible.
Give each source one primary role instead of asking every reference to control the entire result.
Describe relationships explicitly, for example: use image one for character appearance, video one for motion, and audio one for sound direction.
Use images for appearance and setting, videos for movement and camera behavior, and optional audio for sound direction.
Use adaptive framing for mixed source shapes; choose a fixed ratio when the delivery format is known, and allow more time for complex interactions.
Remove redundant or conflicting references before adding more media to the request.

Notes

Reference audio is optional and is valid only when the request also includes at least one reference image or video.
Each reference-video duration is floored separately before billable seconds are added together.
Reference-image surcharges begin with the sixth image; the first five have no image surcharge.
A successful submission returns a task ID; poll until finished or failed, or provide callback_url.

Related Models

Kling 2.6 Motion ControlTransfer motion from a source video to a character image while preserving identity.

Wan 2.6Create 1080p videos with text, image, or video-guided workflows.

Hailuo 02Generate text-led or image-guided clips with 768p and 1080p options.

Seedance 1.0 ProBuild multi-shot videos with prompt control and first-frame guidance.

Kling 2.6Generate video with synchronized dialogue, effects, and ambient audio.

Wan AnimateAnimate a character from reference motion while retaining visual identity.

Sora 2Create videos with physical motion, synchronized audio, and image input.

Sora 2 ProUse the higher-resolution Sora workflow for polished video output.

Veo 3.1Generate 1080p scenes with native audio and extended creative controls.

Grok Imagine Video 1.5Turn text, a first frame, or reference images into videos up to 1080p.

Grok ImagineMove between image generation and video creation in one visual workflow.

Seedance 2Guide video generation with text, frames, and multimodal references.

Frequently Asked Questions about MiniMax H3 Reference to Video API

What is the MiniMax H3 Reference-to-Video API?

MiniMax H3 Reference-to-Video API accepts a prompt with up to 9 reference images, 3 reference videos, and 3 optional reference audio clips, then returns an asynchronous fixed-2K video task. At least one image or video is required, so an audio-only request is rejected.

How do I call the MiniMax H3 Reference-to-Video API?

Send a POST request to /api/generate/submit with a Bearer API key, model set to minimax/h3/reference-to-video, and generation fields inside input. The API returns a task_id immediately; runnable cURL, JavaScript, and Python examples appear in the API tab, with the full schema at https://docs.vidgo.ai/api-manual/video-series/minimax-h3-reference-to-video.

How much does MiniMax H3 Reference-to-Video cost?

Generated video costs 21 credits per second. Each reference video's duration is rounded down separately and billed at 21 credits per second; reference images six through nine add 6.4 credits each. The Run button shows the calculated USD price, or a minimum USD price until a remote reference video's duration is available.

What inputs does MiniMax H3 Reference-to-Video accept?

Key inputs are prompt, reference_image_urls, reference_video_urls, reference_audio_urls, duration, resolution, and aspect_ratio. At least one image or video is required, audio cannot be submitted alone, duration is 5 to 15 whole seconds, and resolution is fixed at 2K. The parameter table above lists the 9/3/3 reference limits, defaults, and adaptive or fixed framing values.

How do I get the generated video?

Poll GET /api/generate/status/{task_id} with the returned task_id until status is finished or failed. When finished, read the video URL from data.files[].file_url; alternatively, include callback_url in the submit request to receive the final result asynchronously.

Which MiniMax H3 API mode should I choose?

Use Reference-to-Video when the request needs several image, video, or optional audio references. Choose Image-to-Video for one required start frame and one optional end frame, or Text-to-Video when the request contains no source media.