Hailuo 2.3 Pro Image to Video API

minimax/hailuo-2.3/pro/image-to-video

Hailuo 2.3 Pro Image to Video transforms static reference images into cinematic native 1080p video clips with pixel-accurate facial preservation, realistic physics, and expressive motion dynamics. It preserves delicate character features, clothing textures, and lighting balance while orchestrating natural micro-expressions and sweeping cinematic camera moves across focused 6-second sequences.

Input

Prompt

648/5000

Start Image Url

Required first frame. Playground uploads support JPG, PNG and WebP, up to 10 MiB. Use JSON mode to supply an HTTP(S) URL.

Resolution

Duration

Prompt Optimizer

OutputReady

Continue with

Hailuo 2.3 Standard Text-to-Video Hailuo 2.3 Standard Image-to-Video Hailuo 2.3 Pro Text-to-Video

Examples

Animate this exact adult telephone operator in one continuous medium close-up. Listening through the same headset, she first knits her eyebrows in puzzled concentration, shifts only her eyes briefly to the side as if checking whether she heard correctly, then presses her lips together to suppress a laugh. A tiny involuntary shoulder movement gives away her amusement. Preserve the face, hairstyle, headset, clothing and switchboard. Keep her hands still. Restrained believable micro-expressions, no broad grin, speaking or head turn. Locked camera and stable warm practical lighting. No cuts, no lettering, no logos, no advertising, no watermark.

Animate the exact maintenance worker and valve in this first frame. In one unbroken shot, the adult worker keeps both hands on the large valve wheel and slowly pulls it through the final half-turn. He adjusts one foot, bends his knees and lowers his center of gravity to apply controlled effort, then stops when the valve reaches its end. Both hands remain attached to the same solid wheel; the wheel rotates around its fixed axle, not the whole pipe. Preserve clothing, face, railing and pipe geometry. Fixed camera, realistic effort and industrial task lighting. No cuts, no lettering, no logos, no advertising, no watermark.

Animate this exact original orange gummy creature inside the same oversized gramophone horn. It has one sudden hiccup: its soft translucent belly compresses, its small body jolts once and a little settled dust puffs outward through the horn. Looking embarrassed, it brings its two small hands up to cover its mouth and becomes still. The creature stays seated in the horn, retaining its face, two arms, two legs and orange jelly material. A short soft secondary wobble follows the jolt. Fixed camera, charming detailed 3D animation, no speech, no extra creatures. No cuts, no lettering, no logos, no advertising, no watermark.

REST API Spec

Quick Start

Submit an endpoint request and poll for status. Replace example URLs with your accessible files.

Step 1: Configure API authentication

Obtain an API key from the dashboard and include Authorization: Bearer <API_KEY> in every request header.

Submission Endpoint: POSThttps://api.vidgo.ai/api/generate/submit
Auth Header: Authorization: Bearer VIDGO_API_KEY

Step 2: Submit a generation task

POST /api/generate/submit. Pass model and optional callback_url at the root level, with generation parameters inside input.

Request Payload

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "minimax/hailuo-2.3/pro/image-to-video",
  "input": {
    "prompt": "A quiet forest in morning light, with a slow camera pan.",
    "duration": 6,
    "resolution": "1080p",
    "prompt_optimizer": false,
    "start_image_url": "https://example.com/start-image.png"
  }
}
JSON
)

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")

CODE=$(printf '%s' "$RESPONSE" | jq -r '.code // empty')
if [ "$CODE" != "0" ] && [ "$CODE" != "200" ]; then
  printf 'API error: %s
' "$RESPONSE" >&2
  exit 1
fi
printf '%s
' "$RESPONSE"

Step 3: Poll for task completion

Poll status with task_id; continue while not_started or running, and stop on finished or failed. Read video URLs from data.files[].file_url on success, or data.error_message on failure.

Status Endpoint

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

Poll status using task_id; continue while not_started or running, stop when finished or failed. On success, read data.files[].file_url; on failure, read data.error_message.

not_startedrunningfinishedfailed

Submission Response

{
  "code": 200,
  "data": {
    "task_id": "task-example",
    "status": "not_started",
    "created_time": "2026-09-23T08:00:00"
  }
}

Completed Response Data

{
  "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 end-to-end script example

Expand to view a production-ready script with retry logic, error handling, and timeout safeguards.

Complete end-to-end script example

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

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "minimax/hailuo-2.3/pro/image-to-video",
  "input": {
    "prompt": "A quiet forest in morning light, with a slow camera pan.",
    "duration": 6,
    "resolution": "1080p",
    "prompt_optimizer": false,
    "start_image_url": "https://example.com/start-image.png"
  }
}
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')
BUSINESS_CODE=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.code // empty')
if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
  printf 'Submit failed:
%s
' "$SUBMIT_RESPONSE" >&2
  exit 1
fi
if [ -z "$TASK_ID" ]; then
  printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
  exit 1
fi

START_TIME=$(date +%s)
POLL_DELAY=2
while true; do
  if [ $(( $(date +%s) - START_TIME )) -ge 600 ]; then
    printf 'Timed out after 600 seconds
' >&2
    exit 1
  fi
  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')
  BUSINESS_CODE=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.code // empty')
  if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
    printf 'Status request failed:
%s
' "$STATUS_RESPONSE" >&2
    exit 1
  fi

  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 "$POLL_DELAY"
      if [ "$POLL_DELAY" -lt 10 ]; then POLL_DELAY=$((POLL_DELAY + 1)); fi
      ;;
    *)
      printf 'Unexpected task status: %s
' "$STATUS" >&2
      exit 1
      ;;
  esac
done

Request Parameters (input object)

Supported generation parameters inside the input object when submitting a POST request to /api/generate/submit:

Field	Type	Required	Default	Description
prompt	string	Yes	—	Required nonblank string, trimmed before validation. Maximum 5,000 Unicode characters.
duration	integer	No	6	Only 6 seconds; defaults to 6.
resolution	string	No	1080p	Fixed to 1080p for this endpoint; used when omitted.
start_image_url	string	Yes	—	Required first-frame HTTP(S) image URL with a hostname and no embedded credentials. End frames, arrays and data URLs are not supported.
prompt_optimizer	boolean	No	—	Optional boolean; omit to leave unspecified upstream. No API default. The playground starts with false; no extra charge.

Response Fields (query result)

Task details returned when polling GET /api/generate/status/{task_id}:

Field	Type	Description
code	integer	Business response code, 200 on success.
data.task_id	string	Globally unique asynchronous task identifier.
data.status	string	Execution status: not_started, running, finished, or failed.
data.files	array	Generated video files upon completion, each with file_url and file_type.
data.error_message	string \| null	Error description if task fails.

Task Lifecycle

Clients should inspect the status field and stop polling when reaching finished or failed:

not_started
Task received and queued for execution.
running
Generation is in progress.
finished
Generation complete; retrieve video URL from data.files.
failed
Generation failed; inspect data.error_message; deducted credits are refunded per standard policy.

Polling & Error Handling

Recommended Polling IntervalStart polling every 2–3 seconds, increasing to 5 seconds as the task continues, to avoid excessive requests.
Network Fluctuations & RetriesIf status polling encounters 5xx or timeouts, the task is still running; retry querying after a brief pause.
Asynchronous Webhook CallbackProvide callback_url at the root of the request payload to receive the completed task result automatically via POST.

Specifications

Specification	Value	Description
Model ID	minimax/hailuo-2.3/pro/image-to-video	Root-level model field.
Resolution	1080p	Fixed to 1080p for this endpoint; used when omitted.
Duration	6s	Only 6 seconds; defaults to 6.

View endpoint documentation

Hailuo 2.3 Pro Image to Video

Hailuo 2.3 Pro Image to Video is MiniMax's premier image-guided video generation model, tailored for broadcast commercials, digital humans, and high-end film production. By supplying a single high-resolution start image URL alongside descriptive motion prompts, creators can generate native 1080p full HD sequences in fixed 6-second runtimes. The model excels at maintaining uncompromising facial likeness and intricate wardrobe details while driving sophisticated physical motion, realistic depth parallax, and nuanced micro-expressions, backed by a straightforward 60-credit per video rate.

Why Choose This?

Native 1080p Output ClarityDelivers true 1080p full HD rendering directly from generation, avoiding digital upscaling artifacts and maintaining crystal-clear subject details.
Uncompromising Identity and Texture FidelityLocks key facial proportions, skin tone nuances, and intricate textile textures from the initial frame across dramatic motion sequences.
Subtle Micro-Expression NuanceTranslates emotional intent into believable eye movements, smiles, and facial muscle shifts for evocative close-up character performances.
Sophisticated 3D Camera ParallaxComputes authentic multi-plane depth separation during tracking, panning, and crane camera trajectories for rich spatial immersion.
Transparent Commercial PricingBilled at a fixed 60 credits ($0.300) per 6-second generation with automatic refund protection if generation fails.

Parameters

Parameter	Requirement	Description
prompt	Required	Required nonblank string, trimmed before validation. Maximum 5,000 Unicode characters.
duration	Optional	Only 6 seconds; defaults to 6. Default`6`
resolution	Optional	Fixed to 1080p for this endpoint; used when omitted. Default`1080p`
start_image_url	Required	Required first-frame HTTP(S) image URL with a hostname and no embedded credentials. End frames, arrays and data URLs are not supported.
prompt_optimizer	Optional	Optional boolean; omit to leave unspecified upstream. No API default. The playground starts with false; no extra charge.

How to Use

Host High-Resolution Start ImageUpload a pristine JPG, PNG, or WebP reference image to a publicly accessible HTTP(S) address and assign it to start_image_url.
Direct Motion and Camera DynamicsCompose prompt instructions detailing how the subject moves from the start pose and specifying camera pans, orbits, or push-ins.
Confirm Output SpecificationsOutputs are natively rendered at 1080p full HD resolution with a focused 6-second duration engineered for dense cinematic shots.
Optionally Enable Prompt OptimizerActivate prompt_optimizer to allow upstream AI to augment camera angles and ambient lighting nuances at no additional cost.
Submit Task and Retrieve VideoPost your payload to /api/generate/submit, poll the task_id status endpoint, and download the finished MP4 video upon completion.

Pricing

1 credit = $0.005. Billed per video; prompt optimization does not change the rate.

Usage	Rate	Details
1080p / 6s	60 credits ($0.300)	Per video

Best Use Cases

High-End Brand and Luxury CommercialsAnimate luxury product photography, jewelry, and fashion models with native 1080p clarity, flawless lighting, and slow-motion pan aesthetics.
Digital Avatars and Virtual Actor PerformancesBring photorealistic character portraits to life with emotive eye contact, head turns, and realistic conversational micro-expressions.
Cinematic Pre-Visualization and Shot ExtensionExtend conceptual production stills into dynamic live-action camera tests to evaluate composition, movement, and atmospheric pacing.
Architectural and Automotive ShowcasesTransform still architectural renderings and automotive photography into fluid exterior fly-throughs and dynamic specular reveals.

Pro Tips

Provide crisp 1080p source imagery: Inputting high-resolution start images with clean edge definitions ensures optimal 1080p rendering fidelity.
Guide natural micro-expressions: Specify subtle emotional cues such as 'a subtle, knowing smile forms as she glances toward the camera' for expressive close-ups.
Direct movement along the camera axis: Combine subject action with camera moves, such as 'subject strides forward while camera dollies back', for dramatic depth.
Respect initial posture and lighting: Describe movements that evolve naturally from the starting frame to preserve shadow consistency and anatomical balance.
Utilize the 5,000-character prompt budget: Provide thorough descriptions of atmospheric elements like wind gusts, floating dust motes, and reflective highlights.

Notes

Single start image input protocol: Hailuo 2.3 Pro Image to Video requires a single start_image_url and prompt; end frame inputs are not supported.
Standardized 6-second runtime: Designed specifically for 6-second high-density sequences; duration values other than 6 are rejected by API validation.
Async polling and credit safety: Generation runs asynchronously using task_id; credits are secured upon request submission and refunded automatically if failed.

Hailuo 2.3 Pro Image to Video API frequently asked questions

What is the Hailuo 2.3 Pro Image to Video API?

Hailuo 2.3 Pro Image to Video is MiniMax's premier image-guided video generation model, engineered for commercial advertising, virtual human acting, and cinematic shot animation. It animates a single reference start image into a native 1080p full HD video sequence across a focused 6-second duration, guided by natural language prompts up to 5,000 characters. Powered by MiniMax's high-capacity generative diffusion architecture, it guarantees pixel-level identity preservation, realistic micro-expressions, and depth-aware camera parallax while maintaining the original lighting and composition. Developers can integrate this endpoint via Vidgo's high-performance REST API or test image animations directly within the interactive playground above.

What resolution does Hailuo 2.3 Pro Image to Video produce?

Hailuo 2.3 Pro Image to Video outputs native 1080p full HD video files directly from generation without relying on post-generation spatial interpolation, preserving sharp textures, authentic film grain, and intricate background details.

What image formats are supported for the start image in Hailuo 2.3 Pro Image to Video?

When calling the API, start_image_url requires a public HTTP or HTTPS URL pointing to a JPG, PNG, or WebP image. In the interactive playground, you can directly upload image files up to 10 MiB in size.

Does Hailuo 2.3 Pro Image to Video support an end frame parameter?

No, this endpoint is specifically optimized for single first-frame image animation via start_image_url. If you need to direct where the video ends, describe the final position, expression, and camera framing in detail within the prompt text.

Why is Hailuo 2.3 Pro Image to Video fixed to a 6-second duration?

The Pro tier concentrates computational capacity on per-frame photorealism, authentic physics, and high-definition micro-movements within a calibrated 6-second format. Setting duration to any value other than 6 will return a validation error.

How does pricing work for Hailuo 2.3 Pro Image to Video?

Generating a video with Hailuo 2.3 Pro Image to Video costs a flat 60 credits ($0.300 based on $0.005 per credit) per 6-second 1080p render. Toggling prompt_optimizer does not add any extra fees.

When should I choose Hailuo 2.3 Pro Image to Video over the Standard Image to Video endpoint?

Choose Hailuo 2.3 Pro Image to Video when your project demands native 1080p clarity, immaculate facial micro-expression fidelity, and cinematic 3D camera parallax for luxury advertising or film assets. For rapid concept prototyping, tighter production budgets (35 credits for 6s), or when 10-second extended animations (70 credits) are required, the Standard Image to Video endpoint is the ideal choice.