Hailuo 2.3 Pro Text to Video API

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

Hailuo 2.3 Pro Text to Video turns descriptive text prompts into cinematic native 1080p video clips with true-to-life physics simulation, high dynamic range lighting, and refined motion details. It accurately follows intricate multi-subject choreography, fluid camera pans, and natural inertia while delivering studio-grade visual clarity across fixed 6-second generations.

Input

Prompt

946/5000

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

Examples

A restrained cinematic comedy shot of ONE muscular adult amateur boxer reclining in a dental examination chair, wearing a plain dark charcoal T-shirt. Tight close-up of his face, neck and upper chest; his arms and all hands remain OUTSIDE the frame throughout. A single small dental inspection mirror on a thin metal stem enters slowly from the far left edge, held by an unseen dentist. It stays near the image edge and never touches the man. He notices it with only his eyes, swallows once with a visible small throat movement, then tightens his lips and furrows his brow while trying to seem brave. His head remains nearly still. Natural skin texture and subtle coherent facial muscle movement, consistent face, softly blurred clinical room background, fixed camera and soft light. One continuous six-second take, no cuts. No gloves, hands or extra people in frame, no mouth interior, no treatment, no blood, no writing, no logos, no watermark.

A single uninterrupted close-up of a quiet physics experiment on a dark laboratory bench. One large iridescent soap bubble is held between two clean vertical transparent acrylic plates. The right plate moves very slowly toward the left, gently flattening the bubble into a wider oval without bursting it; it then retreats slightly and the elastic soap film rounds out again. A thin wet contact boundary remains visible on each plate. Fine rainbow interference bands flow across the film, realistic transparent reflections and delicate oscillations. Locked camera, black background, soft rectangular laboratory lights; no people or labels. 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/text-to-video",
  "input": {
    "prompt": "A quiet forest in morning light, with a slow camera pan.",
    "duration": 6,
    "resolution": "1080p",
    "prompt_optimizer": false
  }
}
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/text-to-video",
  "input": {
    "prompt": "A quiet forest in morning light, with a slow camera pan.",
    "duration": 6,
    "resolution": "1080p",
    "prompt_optimizer": false
  }
}
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.
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/text-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 Text to Video

Hailuo 2.3 Pro Text to Video is MiniMax's flagship text-to-video generation model, engineered specifically for high-end cinematic visualization and commercial production. Operating at native 1080p full HD resolution with a fixed 6-second runtime, it delivers studio-quality spatial fidelity, physically accurate fluid and gravitational dynamics, and responsive camera motion control. Creators can input rich prompts up to 5,000 characters, utilize the complimentary prompt optimizer for lighting expansion, and integrate high-throughput rendering via a predictable 60-credit per video pricing tier.

Why Choose This?

Native 1080p Full HD FidelityRenders crisp 1080p resolution directly without post-upscaling artifacts, preserving intricate skin textures, garment folds, and environmental details.
Advanced Real-World Physics SimulationAccurately computes complex inertial motion, fluid splash dynamics, fabric drapery, and gravitational interactions across every frame.
Cinematic Lighting and Surface ReflectionsSimulates realistic volumetric scattering, specular highlights, shadow soft-falloff, and atmospheric perspective for true filmic aesthetics.
Extensive 5,000-Character Prompt CapacitySupports comprehensive multi-layer scene descriptions, directing lighting setups, shot progression, pacing, and subject interactions with precision.
Predictable Studio-Grade PricingFixed rate of 60 credits ($0.300) per 6-second full HD generation ensures straightforward budgeting for commercial production pipelines.

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`
prompt_optimizer	Optional	Optional boolean; omit to leave unspecified upstream. No API default. The playground starts with false; no extra charge.

How to Use

Craft Detailed Scene PromptDraft a comprehensive description specifying subject appearance, physical action sequences, lighting style, and camera trajectory up to 5,000 characters.
Confirm Resolution and Duration SpecificationsOutput is natively configured at 1080p resolution and a focused 6-second runtime for maximum per-frame cinematic rendering quality.
Toggle Prompt OptimizerOptionally enable prompt_optimizer to allow upstream AI to expand shorthand prompts with professional lighting and cinematography cues at no added cost.
Submit Async Generation RequestSend your POST request to /api/generate/submit with your API key to initialize rendering and receive a unique task_id immediately.
Poll Status and Download VideoCheck the status endpoint until marked finished, then retrieve the hosted MP4 file URL from data.files for post-production or streaming.

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

Commercial Advertising and Brand FilmsCreate broadcast-ready product showcases, visual effects, and high-impact hero shots with native 1080p clarity and premium lighting.
Film and Series Pre-VisualizationTranslate script excerpts and director notes into realistic dynamic camera previs shots, validating shot composition before live filming.
Game Cinematics and Teaser TrailersRender dynamic cutscenes, character introductions, and atmospheric environmental sequences with intense action and physics.
Social Media Brand CampaignsProduce captivating, high-fidelity promotional clips tailored for luxury, fashion, automotive, and technology brand narratives.

Pro Tips

Direct camera motion explicitly: Incorporate professional camera commands such as 'slow push-in', 'dolly left to reveal', or 'handheld tracking shot' to enhance visual rhythm.
Detail multi-layered environmental lighting: Describe distinct light sources like 'golden hour rim lighting with soft ambient blue fill' to maximize 1080p surface detail.
Structure actions chronologically: Describe sequential beats within the 6-second duration (e.g., 'the athlete pauses, looks up, then sprints forward') for cohesive timing.
Leverage prompt optimizer for shorthand concepts: Enable prompt_optimizer when testing rapid creative concepts to automatically fill in filmic stylistic nuances.
Specify material and atmospheric textures: Include physical descriptors such as 'mist swirling in damp cobblestone reflections' to activate the advanced physics engine.

Notes

Fixed 6-second duration design: Hailuo 2.3 Pro Text to Video is purposefully optimized for 6-second high-density sequences; requesting duration other than 6 is rejected.
Native 1080p rendering standard: Outputs render natively at full HD 1080p resolution without spatial interpolation, ensuring pristine professional clarity.
Async task lifecycle and credit safety: Generating tasks run asynchronously via task_id; credits are secured upon submission and automatically refunded if a job fails.

Hailuo 2.3 Pro Text to Video API frequently asked questions

What is the Hailuo 2.3 Pro Text to Video API?

Hailuo 2.3 Pro Text to Video is MiniMax's premier text-to-video generation model, developed for high-end cinematic motion and broadcast-grade visual production. It converts detailed natural language prompts into native 1080p full HD video clips with advanced physical simulation, volumetric lighting, and realistic camera choreography across focused 6-second sequences. Leveraging MiniMax's high-capacity multi-modal diffusion architecture, it renders realistic fluid, cloth, and character dynamics while maintaining pristine edge definition and frame-to-frame coherence. Developers can integrate the model programmatically through Vidgo's REST API or test creative ideas immediately in the interactive web playground above.

Does Hailuo 2.3 Pro Text to Video output native 1080p resolution?

Yes, Hailuo 2.3 Pro Text to Video outputs native 1080p full HD resolution directly from the generative model rather than relying on spatial upscaling, delivering razor-sharp textures, authentic depth of field, and filmic detail.

Why is Hailuo 2.3 Pro Text to Video limited to a 6-second duration?

The Pro tier is architected to maximize per-frame visual complexity, photoreal physics, and cinematic rendering density within a standardized 6-second window. The API only accepts duration=6; configuring any other duration value will result in a validation error.

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

Hailuo 2.3 Pro Text to Video is billed at a fixed rate of 60 credits ($0.300 based on $0.005 per credit) per 6-second generation. Using the prompt optimizer does not incur any additional charges.

How does Hailuo 2.3 Pro Text to Video handle complex physical motion?

The model incorporates a dedicated world-simulation physical prior that accurately accounts for gravitational pull, momentum, fluid splashing, smoke dissipation, and collision dynamics, preventing unnatural morphing during rapid movements.

Can I use up to 5,000 characters in Hailuo 2.3 Pro Text to Video prompts?

Yes, the prompt field supports up to 5,000 Unicode characters, allowing directors and prompts engineers to articulate comprehensive shot lists, lighting temperatures, actor staging, lens types, and sequential narrative progression.

When should I choose Hailuo 2.3 Pro Text to Video instead of the Standard endpoint?

Choose Hailuo 2.3 Pro Text to Video when your production requires native 1080p full HD clarity, broadcast-quality lighting, and intense physical action within a 6-second timeframe. If your workflow prioritizes rapid drafting, lower unit cost (35 credits for 6s), or requires 10-second extended shots (70 credits), the Standard Text to Video endpoint is the recommended choice.