MiniMax H3 Image-to-Video API

minimax/h3/image-to-video

2K · 5–15 sec

MiniMax H3 Image-to-Video API accepts a start frame, a prompt, and an optional end frame, then returns a fixed 2K video task lasting 5–15 seconds. Put the start frame first and the optional end frame second in image_urls; do not send aspect_ratio.

Input

Prompt

576/2000

Start frame

End frame

Resolution

Duration

Output

Ready

Continue with

MiniMax H3 Text-to-Video MiniMax H3 Reference-to-Video

REST API

Quick Start

Make your first image-to-video request in three steps. The short example sends a start frame and prompt, 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 a public start-frame URL and prompt. Omit aspect_ratio because MiniMax H3 Image-to-Video API rejects that field.

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/image-to-video",
  "input": {
    "prompt": "Petals drift through the frame as the camera tracks beside the cyclist.",
    "image_urls": [
      "https://example.com/start-frame.jpg",
      "https://example.com/end-frame.jpg"
    ],
    "duration": 5,
    "resolution": "2K"
  }
}'

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/image-to-video",
  "input": {
    "prompt": "Petals drift through the frame as the camera tracks beside the cyclist.",
    "image_urls": [
      "https://example.com/start-frame.jpg",
      "https://example.com/end-frame.jpg"
    ],
    "duration": 5,
    "resolution": "2K"
  }
}
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, ordered frames, and generation settings inside input.

Field	Type	Required	Default	Description
model	string	Yes	—	Must be minimax/h3/image-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 motion and camera prompt from 1 to 2,000 characters.
input.image_urls	string[]	Yes	—	One or two ordered public HTTP(S) image URLs: start frame first, optional end frame second.
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	not accepted	No	—	Do not send this field. The output canvas follows the first image.

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 + 1–2 images	Provide a required start frame and an optional end frame in image_urls order.
Output	Video	MiniMax H3 Image-to-Video API returns an asynchronous video generation task.
Resolution	2K	Resolution is fixed and does not change the credit rate.
Duration	5–15 seconds	Use a whole-second value; the default is 5 seconds.
Composition	Follows start frame	The request schema does not accept input.aspect_ratio.
Billing basis	21 credits / second	Only generated duration contributes to the request cost; input frames have no surcharge.

View MiniMax H3 Image-to-Video API documentation

MiniMax H3 Image-to-Video API

MiniMax H3 Image-to-Video API accepts one or two ordered public HTTP(S) image URLs plus a 1–2,000-character prompt. The first image is the required start frame, the second is an optional end frame, and successful submission returns an asynchronous fixed-2K video task.

Why Choose MiniMax H3 Image-to-Video API?

Direct image-to-video workflow.Animate an existing image instead of rebuilding its subject and visual direction from text.
Use an approved image as the start frame.Place the image that defines the opening subject and composition first in image_urls.
Guide the ending when needed.Add a compatible second image when the final state needs tighter control.
Describe subject and camera motion.Use the prompt for subject movement, camera behavior, pacing, and transitions.
Fixed 2K resolution and per-second pricing.Generate 5–15 second videos at fixed 2K resolution and 21 credits per generated second.

Parameters

Parameter	Requirement	Description
prompt	Required	Describe subject motion, camera movement, pacing, and scene development in 1 to 2,000 characters after trimming.
image_urls	Required	One or two ordered public HTTP(S) image URLs: required start frame first, optional end frame second.
duration	Optional	Whole seconds from 5 through 15. Default`55–15`
resolution	Fixed	No other resolution is accepted. Default`2K`
aspect_ratio	Not accepted	Do not send this field; MiniMax H3 Image-to-Video API validation rejects aspect_ratio.

How to Use

Set the opening frameChoose the image that should be the first video frame, then place it first in image_urls.
Add an end frame if neededPlace a compatible second image after the start frame when the ending needs guidance.
Describe subject motionState what should move, how it should move, and how the action develops.
Direct the camera and sceneAdd camera movement, pacing, scene development, lighting, and mood.
Set timing and submitChoose 5 to 15 seconds, run the request, then poll the task ID or use a callback URL.

Pricing

Pricing depends only on generated duration: 21 credits for each second of output. Start and end frames do not add a separate surcharge.

Usage	Rate	Details
Generated video	21 credits per second	A 5 second clip costs 105 credits, a 10 second clip costs 210 credits, and a 15 second clip costs 315 credits.

Best Use Cases

Product Image AnimationUse an approved product image as the start frame and describe the required product or camera motion in the prompt.
Campaign Asset VariantsTurn key art into concise motion assets for launch, social, and display campaigns.
Start and End TransitionsGuide a planned transition between two compatible visual states with ordered source frames.
Storyboard Motion StudiesTurn a selected storyboard frame into a short movement study before producing the full sequence.

Pro Tips

Use a sharp start frame with one readable subject and a composition that already matches the delivery format.
Describe what should move instead of repeating appearance details that are visible in the image.
Write subject motion, camera motion, and pacing as separate instructions.
Use a shorter duration for one simple motion and more time when the scene needs a readable transition.
When using an end frame, keep subject identity, framing, and visual direction compatible with the start frame.
Avoid abrupt changes in viewpoint, lighting, or subject scale between the start and end frames.

Notes

The optional end frame is valid only after the required start frame and must be second in image_urls.
MiniMax H3 Image-to-Video API rejects aspect_ratio rather than accepting a user-selected ratio.
A successful submission returns a task ID rather than a completed video.
Poll while status is not_started or running, or provide callback_url to receive the terminal result.

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 Image to Video API

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

MiniMax H3 Image-to-Video is MiniMax's model for turning a still image into video. You provide a required start frame, describe the motion in text, and can add an end frame; it returns a fixed 2K video suited to product animation, character movement, and controlled visual transitions.

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

Send a POST request to /api/generate/submit with a Bearer API key, model set to minimax/h3/image-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-image-to-video.

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

The API costs 21 credits per generated second, with no separate start-frame or end-frame charge. A 5 second video costs 105 credits, a 10 second video costs 210 credits, and a 15 second video costs 315 credits. Before submission, the Run button shows the calculated USD price for the current duration.

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

Key inputs are prompt, image_urls, duration, and resolution. Provide a 1 to 2,000 character prompt and one or two ordered images: a required start frame, then an optional end frame; duration is an optional whole second from 5 to 15, resolution is fixed at 2K, and aspect_ratio is not accepted. The parameter table above lists requirements and defaults.

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 Image-to-Video when a start frame should define the composition and an optional end frame should guide the final state. Choose Text-to-Video when no source media is needed, or Reference-to-Video when multiple media references should guide appearance, motion, or sound.