Hailuo 2.3 API - AI Video Generation APIs
by MiniMax
Hailuo 2.3 API, developers can generate videos from text descriptions or images, with support for various styles and durations. The API also includes audio generation and image capabilities, making it a comprehensive solution for multimedia content creation.
Models Version
Get $5 Free Credit on First Payment
No strings attached — add funds and get $5 bonus instantly
Hailuo v2.3 Image to Video API Documentation
https://gateway.pixazo.ai/minimax-hailuo-ai/v1
Authentication
All requests require an API key passed via header.
| Header | Type | Required | Description |
|---|---|---|---|
| Ocp-Apim-Subscription-Key | string | Yes | Your API subscription key |
Generate Image To Video Request - MiniMax Hailuo AI API
Request Code
POST https://gateway.pixazo.ai/minimax-hailuo-ai/v1/imageToVideo
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY
{
"prompt": "Man walked into winter cave with polar bear",
"first_frame_image": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/manwithbear.jpg",
"duration": 6,
"resolution": "768P",
"prompt_optimizer": true,
"fast_pretreatment": false,
"aigc_watermark": false
}
import requests
url = "https://gateway.pixazo.ai/minimax-hailuo-ai/v1/imageToVideo"
headers = {
"Content-Type": "application/json",
"Cache-Control": "no-cache",
"Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
"prompt": "Man walked into winter cave with polar bear",
"first_frame_image": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/manwithbear.jpg",
"duration": 6,
"resolution": "768P",
"prompt_optimizer": true,
"fast_pretreatment": false,
"aigc_watermark": false
}
response = requests.post(url, json=data, headers=headers)
print(response.json())
const url = "https://gateway.pixazo.ai/minimax-hailuo-ai/v1/imageToVideo";
const headers = {
"Content-Type": "application/json",
"Cache-Control": "no-cache",
"Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
};
const data = {
"prompt": "Man walked into winter cave with polar bear",
"first_frame_image": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/manwithbear.jpg",
"duration": 6,
"resolution": "768P",
"prompt_optimizer": true,
"fast_pretreatment": false,
"aigc_watermark": false
};
fetch(url, {
method: "POST",
headers: headers,
body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error("Error:", error));
curl -v -X POST "https://gateway.pixazo.ai/minimax-hailuo-ai/v1/imageToVideo" \
-H "Content-Type: application/json" \
-H "Cache-Control: no-cache" \
-H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
--data-raw '{
"prompt": "Man walked into winter cave with polar bear",
"first_frame_image": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/manwithbear.jpg",
"duration": 6,
"resolution": "768P",
"prompt_optimizer": true,
"fast_pretreatment": false,
"aigc_watermark": false
}'
Output
{
"request_id": "minimax-hailuo-ai_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"status": "QUEUED",
"polling_url": "https://gateway.pixazo.ai/v2/requests/status/minimax-hailuo-ai_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
Webhook (Optional)
Add the X-Webhook-URL header to your generate request to receive a POST callback instead of polling.
X-Webhook-URL: https://your-server.com/webhook/callback
Request Parameters - Generate Image To Video Request
| Parameter | Required | Type | Description |
|---|---|---|---|
| prompt | Yes | string | Video description, maximum 2000 characters. Supports camera movement. syntax for precise camera control . Supports 15+ camera movement instructions for professional video control. |
| first_frame_image | Yes | string | Image URL to use as the starting frame. Supports public URLs or Base64 encoded Data URLs. Image requirements: JPG/JPEG/PNG/WebP, <20MB, short side >300px, aspect ratio 2:5 to 5:2. |
| prompt_optimizer | No | boolean | Default: true. Automatically optimizes the prompt for better video quality. |
| fast_pretreatment | No | boolean | Default: false. Shortens prompt optimization time (only for MiniMax-Hailuo-2.3-Fast model). |
| duration | No | integer | Default: 6. Video duration in seconds. Must be 6 or 10 seconds for MiniMax-Hailuo-2.3-Fast model. |
| resolution | No | string | Default: "768P". Video resolution. Must be '768P' or '1080P' for MiniMax-Hailuo-2.3-Fast model. |
| callback_url | No | string | URL to receive task status update notifications. |
| aigc_watermark | No | boolean | Default: false. Whether to add AIGC watermark to the generated video. |
Example Request
{
"prompt": "Man walked into winter cave with polar bear",
"first_frame_image": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/manwithbear.jpg",
"duration": 6,
"resolution": "768P",
"prompt_optimizer": true,
"fast_pretreatment": false,
"aigc_watermark": false
}
Response
{
"request_id": "minimax-hailuo-ai_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"status": "QUEUED",
"polling_url": "https://gateway.pixazo.ai/v2/requests/status/minimax-hailuo-ai_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
Request Headers
| Header | Value |
|---|---|
| Content-Type | application/json |
| Cache-Control | no-cache |
| Ocp-Apim-Subscription-Key | YOUR_SUBSCRIPTION_KEY |
Response Handling
Common status codes.
| Code | Meaning |
|---|---|
| 202 | Accepted — Request queued |
| 400 | Bad Request |
| 401 | Unauthorized |
| 402 | Insufficient Balance |
| 403 | Forbidden |
| 429 | Too Many Requests |
| 500 | Internal Server Error |
Error Responses
Queue system errors and model validation errors.
Queue System Errors
// 402 — Insufficient balance
{
"error": "Insufficient Balance",
"message": "Your wallet does not have enough balance."
}
// 400 — Model not found
{
"error": "Model not found",
"message": "Model 'minimax-hailuo-ai' not found or is disabled"
}
Error via Status/Webhook
{
"request_id": "minimax-hailuo-ai_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"status": "ERROR",
"model_id": "minimax-hailuo-ai",
"error": "Description of the error",
"output": null
}
Retrieving Results
Poll the universal status endpoint to check progress and retrieve results.
Endpoint
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
cURL Example
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
"https://gateway.pixazo.ai/v2/requests/status/minimax-hailuo-ai_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
Response (Completed)
{
"request_id": "minimax-hailuo-ai_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"status": "COMPLETED",
"model_id": "minimax-hailuo-ai",
"error": null,
"output": {
"media_url": [
"https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/minimax-hailuo-ai_019dxxxx-xxxx/output.ext"
],
"media_type": "application/octet-stream"
},
"created_at": "2026-03-31T10:00:00.000Z",
"updated_at": "2026-03-31T10:00:15.000Z",
"completed_at": "2026-03-31T10:00:15.000Z"
}
Response Fields
| Field | Type | Description |
|---|---|---|
| request_id | string | Unique request identifier |
| status | string | QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR |
| model_id | string | Model that processed the request |
| error | string|null | Error message if failed |
| output.media_url | array | URLs to generated media (R2 CDN) |
| output.media_type | string | MIME type of the output |
| created_at | string | When request was created |
| completed_at | string|null | When request completed |
| polling_url | string | Status URL (initial response only) |
Status Values
| Status | Description |
|---|---|
| QUEUED | Request accepted, waiting to be processed |
| PROCESSING | Being processed by the model |
| COMPLETED | Done — output contains the result |
| FAILED | Failed — check error field |
| ERROR | System error — not charged |
Status Flow
QUEUED → PROCESSING → COMPLETED
→ FAILED
→ ERROR
Typical Workflow
- Send a generate request to the API endpoint
- Save the
request_idfrom the response - Poll every 5-10 seconds:
GET /v2/requests/status/{request_id} - When
statusis"COMPLETED", download fromoutput.media_url
Tip: Use X-Webhook-URL header to get a callback instead of polling.
Hailuo v2.3 Image to Video API Pricing
| Resolution | Duration | Price (USD) |
|---|---|---|
| All Resolution | 6s | $0.35 |
| All Resolution | 10s | $0.6 |
Hailuo v2.3 Text to Video API Documentation
https://gateway.pixazo.ai/minimax-hailuo-ai/v1
Authentication
All requests require an API key passed via header.
| Header | Type | Required | Description |
|---|---|---|---|
| Ocp-Apim-Subscription-Key | string | Yes | Your API subscription key |
Generate Video Request - MiniMax Hailuo AI API
Request Code
POST https://gateway.pixazo.ai/minimax-hailuo-ai/v1/generate
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY
{
"prompt": "A high-energy scene of a large, muscular bear leaping gracefully into a fast-flowing river to catch a fish. The video starts with the bear crouching by the riverbank, then transitions to it leaping mid-air, with water splashing dramatically around it. The camera follows the bear's movement, capturing the intensity and speed of the jump. The bear's paws extend toward the fish, which is darting through the clear water, as the background shows a lush, green forest and distant mountains. The scene is full of natural sounds — the rush of water, splashes, and the bear's powerful movement. Light filters through the trees, creating a dramatic, cinematic atmosphere.",
"duration": 6,
"resolution": "768P",
"prompt_optimizer": true,
"fast_pretreatment": false,
"aigc_watermark": false
}
import requests
url = "https://gateway.pixazo.ai/minimax-hailuo-ai/v1/generate"
headers = {
"Content-Type": "application/json",
"Cache-Control": "no-cache",
"Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
"prompt": "A high-energy scene of a large, muscular bear leaping gracefully into a fast-flowing river to catch a fish. The video starts with the bear crouching by the riverbank, then transitions to it leaping mid-air, with water splashing dramatically around it. The camera follows the bear's movement, capturing the intensity and speed of the jump. The bear's paws extend toward the fish, which is darting through the clear water, as the background shows a lush, green forest and distant mountains. The scene is full of natural sounds — the rush of water, splashes, and the bear's powerful movement. Light filters through the trees, creating a dramatic, cinematic atmosphere.",
"duration": 6,
"resolution": "768P",
"prompt_optimizer": True,
"fast_pretreatment": False,
"aigc_watermark": False
}
response = requests.post(url, json=data, headers=headers)
print(response.json())
const url = 'https://gateway.pixazo.ai/minimax-hailuo-ai/v1/generate';
const headers = {
'Content-Type': 'application/json',
'Cache-Control': 'no-cache',
'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
};
const data = {
prompt: 'A high-energy scene of a large, muscular bear leaping gracefully into a fast-flowing river to catch a fish. The video starts with the bear crouching by the riverbank, then transitions to it leaping mid-air, with water splashing dramatically around it. The camera follows the bear\'s movement, capturing the intensity and speed of the jump. The bear\'s paws extend toward the fish, which is darting through the clear water, as the background shows a lush, green forest and distant mountains. The scene is full of natural sounds — the rush of water, splashes, and the bear\'s powerful movement. Light filters through the trees, creating a dramatic, cinematic atmosphere.',
duration: 6,
resolution: '768P',
prompt_optimizer: true,
fast_pretreatment: false,
aigc_watermark: false
};
fetch(url, {
method: 'POST',
headers: headers,
body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
curl -v -X POST "https://gateway.pixazo.ai/minimax-hailuo-ai/v1/generate" \
-H "Content-Type: application/json" \
-H "Cache-Control: no-cache" \
-H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
--data-raw '{
"prompt": "A high-energy scene of a large, muscular bear leaping gracefully into a fast-flowing river to catch a fish. The video starts with the bear crouching by the riverbank, then transitions to it leaping mid-air, with water splashing dramatically around it. The camera follows the bear\'s movement, capturing the intensity and speed of the jump. The bear\'s paws extend toward the fish, which is darting through the clear water, as the background shows a lush, green forest and distant mountains. The scene is full of natural sounds — the rush of water, splashes, and the bear\'s powerful movement. Light filters through the trees, creating a dramatic, cinematic atmosphere.",
"duration": 6,
"resolution": "768P",
"prompt_optimizer": true,
"fast_pretreatment": false,
"aigc_watermark": false
}'
Output
{
"request_id": "minimax-hailuo-ai_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"status": "QUEUED",
"polling_url": "https://gateway.pixazo.ai/v2/requests/status/minimax-hailuo-ai_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
Webhook (Optional)
Add the X-Webhook-URL header to your generate request to receive a POST callback instead of polling.
X-Webhook-URL: https://your-server.com/webhook/callback
Request Parameters - Generate Video Request
| Parameter | Required | Type | Description |
|---|---|---|---|
| prompt | Yes | string | The narrative or scene description used to influence video generation. |
| duration | No | number | Duration of the video in seconds. |
| resolution | No | string | Video resolution. |
| prompt_optimizer | No | boolean | Automatically refines prompt input for better video quality. |
| fast_pretreatment | No | boolean | Enable fast pretreatment for quicker processing. |
| callback_url | No | string | URL to receive callback notifications when video is ready. |
| aigc_watermark | No | boolean | Add AIGC watermark to the generated video. |
Example Request
{
"prompt": "A high-energy scene of a large, muscular bear leaping gracefully into a fast-flowing river to catch a fish. The video starts with the bear crouching by the riverbank, then transitions to it leaping mid-air, with water splashing dramatically around it. The camera follows the bear's movement, capturing the intensity and speed of the jump. The bear's paws extend toward the fish, which is darting through the clear water, as the background shows a lush, green forest and distant mountains. The scene is full of natural sounds — the rush of water, splashes, and the bear's powerful movement. Light filters through the trees, creating a dramatic, cinematic atmosphere.",
"duration": 6,
"resolution": "768P",
"prompt_optimizer": true,
"fast_pretreatment": false,
"aigc_watermark": false
}
Response
{
"request_id": "minimax-hailuo-ai_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"status": "QUEUED",
"polling_url": "https://gateway.pixazo.ai/v2/requests/status/minimax-hailuo-ai_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
Request Headers
| Header | Value |
|---|---|
| Content-Type | application/json |
| Cache-Control | no-cache |
| Ocp-Apim-Subscription-Key | YOUR_SUBSCRIPTION_KEY |
Response Handling
Common status codes.
| Code | Meaning |
|---|---|
| 202 | Accepted — Request queued |
| 400 | Bad Request |
| 401 | Unauthorized |
| 402 | Insufficient Balance |
| 403 | Forbidden |
| 429 | Too Many Requests |
| 500 | Internal Server Error |
Error Responses
Queue system errors and model validation errors.
Queue System Errors
// 402 — Insufficient balance
{
"error": "Insufficient Balance",
"message": "Your wallet does not have enough balance."
}
// 400 — Model not found
{
"error": "Model not found",
"message": "Model 'minimax-hailuo-ai' not found or is disabled"
}
Error via Status/Webhook
{
"request_id": "minimax-hailuo-ai_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"status": "ERROR",
"model_id": "minimax-hailuo-ai",
"error": "Description of the error",
"output": null
}
Retrieving Results
Poll the universal status endpoint to check progress and retrieve results.
Endpoint
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
cURL Example
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
"https://gateway.pixazo.ai/v2/requests/status/minimax-hailuo-ai_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
Response (Completed)
{
"request_id": "minimax-hailuo-ai_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"status": "COMPLETED",
"model_id": "minimax-hailuo-ai",
"error": null,
"output": {
"media_url": [
"https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/minimax-hailuo-ai_019dxxxx-xxxx/output.ext"
],
"media_type": "application/octet-stream"
},
"created_at": "2026-03-31T10:00:00.000Z",
"updated_at": "2026-03-31T10:00:15.000Z",
"completed_at": "2026-03-31T10:00:15.000Z"
}
Response Fields
| Field | Type | Description |
|---|---|---|
| request_id | string | Unique request identifier |
| status | string | QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR |
| model_id | string | Model that processed the request |
| error | string|null | Error message if failed |
| output.media_url | array | URLs to generated media (R2 CDN) |
| output.media_type | string | MIME type of the output |
| created_at | string | When request was created |
| completed_at | string|null | When request completed |
| polling_url | string | Status URL (initial response only) |
Status Values
| Status | Description |
|---|---|
| QUEUED | Request accepted, waiting to be processed |
| PROCESSING | Being processed by the model |
| COMPLETED | Done — output contains the result |
| FAILED | Failed — check error field |
| ERROR | System error — not charged |
Status Flow
QUEUED → PROCESSING → COMPLETED
→ FAILED
→ ERROR
Typical Workflow
- Send a generate request to the API endpoint
- Save the
request_idfrom the response - Poll every 5-10 seconds:
GET /v2/requests/status/{request_id} - When
statusis"COMPLETED", download fromoutput.media_url
Tip: Use X-Webhook-URL header to get a callback instead of polling.
Hailuo v2.3 Text to Video API Pricing
| Resolution | Duration | Price (USD) |
|---|---|---|
| All Resolution | 6s | $0.35 |
| All Resolution | 10s | $0.6 |
