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.
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. |
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.