# Hailuo AI API

> Provider: **MiniMax**
> Source: https://www.pixazo.ai/models/hailuo

Advanced video, audio, and image generation by MiniMax.

## Hailuo v2.3

### Image to Video

## Base URL

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

HTTP Python JavaScript cURL

```
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"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=minimax-hailuo-ai-api&operation=generate-image-to-video-request)

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

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.

### Text to Video

## Base URL

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

HTTP Python JavaScript cURL

```
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"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=minimax-hailuo-ai&operation=generate-video-request)

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

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.