One continuous cinematic over-the-shoulder shot deep inside a vast limestone cavern. An adult cave surveyor in a matte red helmet and slate-gray coveralls turns their head slowly from left to right. The narrow helmet lamp beam sweeps across a dark rock wall, gradually revealing translucent calcite crystal clusters and sparse dust motes in the light. The camera pushes gently toward the newly illuminated crystals while the surveyor remains at the edge of frame. Light originates only from the lamp and responds coherently to rock geometry. Subtle realistic motion, no fantasy glow, no cuts, no text, no logos.
Hailuo 02 Pro Text to Video API
minimax/hailuo-02/pro/text-to-videoHailuo 02 Pro Text to Video transforms descriptive text prompts into cinematic 512P and 768P video scenes, featuring heightened dynamic tension, nuanced lighting, and optional prompt refinement. It captures complex narrative pacing and emotive expressions while sustaining scene-wide physical coherence and rich textural depth.
665
OutputReady
Examples
REST API Spec
Quick Start
Submit an endpoint request and poll for status. Replace example URLs with your accessible files.
01
Step 1: Configure API authentication
Obtain an API key from the dashboard and include Authorization: Bearer <API_KEY> in every request header.
- Submission Endpoint
- POST
https://api.vidgo.ai/api/generate/submit - Auth Header
- Authorization: Bearer VIDGO_API_KEY
02
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-02/pro/text-to-video",
"input": {
"prompt": "A quiet single-shot cinematic character moment inside a small self-service laundromat late at night. One adult Black female nurse in plain muted blue scrubs sits beside a slowly rotating washing machine. In a medium close-up with hands visible, she takes a small yellow folded paper crane from her scrub pocket, holds it on her palm, studies it and gradually changes from tired neutrality to a subtle tender smile. The paper crane stays still and keeps its folded shape. Soft fluorescent light mixed with warm street light, realistic skin, delicate continuous expression change, slow gentle push-in. No other people, no cuts, no logos, no writing, no advertisement.",
"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"03
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_startedrunningfinishedfailedSubmission Response
{
"code": 200,
"data": {
"task_id": "CKYXCWMX6O3DYACG",
"status": "running",
"created_time": "2026-09-22T16:04:52"
}
}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-02/pro/text-to-video",
"input": {
"prompt": "A quiet single-shot cinematic character moment inside a small self-service laundromat late at night. One adult Black female nurse in plain muted blue scrubs sits beside a slowly rotating washing machine. In a medium close-up with hands visible, she takes a small yellow folded paper crane from her scrub pocket, holds it on her palm, studies it and gradually changes from tired neutrality to a subtle tender smile. The paper crane stays still and keeps its folded shape. Soft fluorescent light mixed with warm street light, realistic skin, delicate continuous expression change, slow gentle push-in. No other people, no cuts, no logos, no writing, no advertisement.",
"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
doneRequest 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. No explicit length limit in the current upstream handler. |
| resolution | string | No | 768P | 512P or 768P; defaults to 768P. |
| prompt_optimizer | boolean | No | — | Optional boolean; omit to leave unspecified upstream. The playground starts with false. |
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_startedTask received and queued for execution.
runningGeneration is in progress.
finishedGeneration complete; retrieve video URL from data.files.
failedGeneration 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-02/pro/text-to-video | Root-level model field. |
| Resolution | 512P / 768P | 512P or 768P; defaults to 768P. |
| Duration | — | Do not send duration. |
Hailuo 02 Pro Text to Video
Hailuo 02 Pro Text to Video is MiniMax's premier model tailored for professional cinematic storytelling and commercial visualization. Compared to the Standard tier, the Pro edition significantly elevates motion range, complex physical interactions, and dramatic lighting coherence. Accepting detailed prompts without explicit length caps, it operates on a fixed 65-credit generation fee for top-tier visual delivery.
Why Choose This?
Cinematic Visual DramaticismFeatures a wide dynamic range and expressive key lighting that faithfully renders subtle facial expressions and atmospheric shifts.
Fluid High-Motion DynamicsDelivers smooth articulation across complex movements like running, jumping, and spinning while preserving anatomical realism.
Unconstrained Prompt NuanceOperates without explicit character length limits, accommodating detailed cinematic scripts with precise cues and mood boards.
Multi-Perspective CinematographyReliably executes multi-stage camera choreographies including rapid pans, sweeping drone flyovers, and steady dolly tracks.
Predictable Fixed-Per-Task PricingBilled at a straightforward flat rate of 65 credits ($0.325) for either 512P or 768P output.
Parameters
| Parameter | Requirement | Description |
|---|---|---|
| prompt | Required | Required nonblank string, trimmed before validation. No explicit length limit in the current upstream handler. |
| resolution | Optional | 512P or 768P; defaults to 768P. Default 768P |
| prompt_optimizer | Optional | Optional boolean; omit to leave unspecified upstream. The playground starts with false. |
How to Use
Draft a Script-Level PromptDescribe your character, lighting atmosphere, and scene progression with rich sensory details without worrying about character limits.
Detail Camera ChoreographySpecify cinematic angles and movement paths (e.g., 'low-angle slow tracking shot pulling back to reveal the expansive horizon').
Select Output ResolutionChoose between 512P and 768P (768P is recommended; both share the same flat generation rate).
Omit Duration ParameterPro mode operates on fixed single-task delivery; omit the duration parameter from your input object.
Submit and Download ResultLaunch the asynchronous task, monitor task_id, and retrieve your finalized high-tension MP4 video.
Pricing
1 credit = $0.005. Pro is billed per generation and does not accept duration.
| Usage | Rate | Details |
|---|---|---|
| 512P | 65 credits ($0.325) | Per generation |
| 768P | 65 credits ($0.325) | Per generation |
Best Use Cases
High-End Film & Concept PitchingConvert screenplay moments into visually striking conceptual previews to align creative teams.
Premium Brand & Luxury AdvertisingProduce sleek commercials featuring polished automotive surfaces, fluid fabric physics, and dynamic lighting.
Game Cinematic & CG StoryboardingShowcase combat sequences, magical VFX, and colossal creatures to guide pre-production animation.
Music Video & Visual Art DirectionGenerate surreal and emotionally evocative visual vignettes tailored to musical rhythm and abstract narrative.
Pro Tips
- Direct Lighting Accents for Richer Ambience: Prompt for specific lighting such as 'subtle volumetric rays', 'warm rim lighting', or 'shallow depth of field' to unlock Pro's rendering power.
- Structure Multi-Stage Narrative Sequentially: Organize longer scripts chronologically using transitional phrases like 'initially', 'then smoothly rotating to reveal', and 'concluding as'.
- Default to 768P Resolution: Because both 512P and 768P cost the exact same flat 65 credits, choose 768P for optimal visual fidelity.
- Anchor Character Actions to Tangible Environment Physics: Describe interactions like kicking up dust or stepping through water to maximize physical simulation accuracy.
- Focus Dynamic Motion on Cohesive Subjects: Highlight 1 or 2 focal actions per scene rather than cluttering simultaneous unrelated movements.
Notes
- No Duration Parameter Accepted: Pro mode operates on fixed single-task delivery; submitting a duration parameter will cause a request validation error.
- Flat Per-Generation Billing: Each successful task costs a fixed 65 credits ($0.325) regardless of resolution; deducted credits are refunded if a task fails.
- Pure Text Input Contract: This endpoint requires a nonblank prompt string and does not accept image attachments.
Related Models
Hailuo 02 Pro Text to Video API frequently asked questions
What is the Hailuo 02 Pro Text to Video API?
Hailuo 02 Pro Text to Video is a MiniMax model for professional video generation from text. It generates continuous 512P or 768P cinematic videos directly from text prompts, delivering heightened dynamic motion, complex physical interaction, and refined lighting textures. Built on MiniMax's premier video generation architecture, it faithfully executes narrative script pacing while preserving scene perspective and material realism. You can call it programmatically or try it from the playground above.
How does the pricing for Hailuo 02 Pro Text to Video work?
This endpoint uses flat per-generation pricing, charging a fixed 65 credits ($0.325) per task. Both 512P and 768P resolutions share this same rate, and deducted credits are refunded automatically if a task fails.
Does Hailuo 02 Pro Text to Video accept a duration parameter?
No, and submitting a duration parameter is strictly disallowed. Pro mode operates on fixed single-task generation; passing a duration field in your request payload will be rejected by validation.
What prompt length can I submit to Hailuo 02 Pro Text to Video?
The current handler imposes no explicit character length ceiling, requiring only a nonblank trimmed string. You can supply complete directorial scene descriptions incorporating lighting, camera movement, and character actions.
What visual advantages does Hailuo 02 Pro Text to Video offer over Standard?
The Pro mode is heavily optimized for larger motion amplitudes, dynamic action choreography, and advanced cinematography. It produces richer lighting depth and authentic physical motion blur suited for high-impact cinematic sequences.
Which resolution options are available for Hailuo 02 Pro Text to Video?
It supports 512P and 768P resolutions, defaulting to 768P. Because both resolutions share the exact same 65-credit cost, choosing 768P is recommended for maximum image definition and textural fidelity.
When should I enable the prompt optimizer in Hailuo 02 Pro Text to Video?
Enable prompt_optimizer when starting from brief or conceptual text to automatically enrich cinematic lighting and camera angles; keep it disabled when submitting a precise directorial script that must be followed word-for-word.