Minimax H3 Max API, Minimax Music 3.0 API (Free), Minimax Speech 2.8 API (HD & Turbo), Minimax Voice Design API, Minimax Hailuo API: Pricing and Documentation

MiniMax H3 Max API Documentation (Text to Video)

All requests require an API key passed via header.

Webhook (Optional)

Instead of polling, supply a callback URL and Pixazo will POST the result to it as soon as the request reaches a terminal state.

Example: enable webhook

curl -X POST https://gateway.pixazo.ai/minimax-hailuo-h3-max/v1/text-to-video \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-URL: https://your-server.example.com/hooks/video" \
  -H "X-Webhook-Mode: terminal" \
  -d '{"prompt": "a lone lighthouse beam sweeping across fog at dusk", "prompt_expansion_mode": "balanced"}'

Callback Payload

{
  "request_id": "minimax-hailuo-h3-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "minimax-hailuo-h3-max",
  "error": null,
  "output": {
    "media_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/minimax-hailuo-h3-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.mp4",
    "media_type": "video/mp4"
  },
  "created_at": "2026-08-27T09:42:17.774Z",
  "completed_at": "2026-08-27T09:45:02.118Z"
}

Failure callback shape

{
  "request_id": "minimax-hailuo-h3-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "minimax-hailuo-h3-max",
  "error": "Generation failed upstream",
  "output": null
}

Delivery semantics

• terminal fires exactly once, on COMPLETED or FAILED.
• sync also fires on intermediate transitions such as QUEUED → PROCESSING.
• Deliveries are idempotent on request_id — de-duplicate on it, as a callback may be retried.
• Respond 200 within a few seconds; slow endpoints are treated as failed deliveries.
• HTTPS is required.

Request Parameters - MiniMax H3 Max API (Text to Video)

Request Headers

Response Handling

Error Responses

Insufficient balance (402)

{
  "error": "Insufficient balance",
  "required": 0.4,
  "available": 0.12,
  "currency": "USD"
}

Invalid parameter (400)

{
  "error": "Invalid value for 'duration': must be between 5 and 15"
}

Failure after acceptance

A request that was accepted can still fail during generation. That is reported through the status endpoint or the webhook, with status set to ERROR:

{
  "request_id": "minimax-hailuo-h3-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "minimax-hailuo-h3-max",
  "error": "Generation failed upstream",
  "output": null
}

Retrieving Results

Poll the status endpoint with the request_id returned by the submit call.

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}

cURL Example

curl https://gateway.pixazo.ai/v2/requests/status/minimax-hailuo-h3-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY"

Response (Completed)

{
  "request_id": "minimax-hailuo-h3-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "minimax-hailuo-h3-max",
  "error": null,
  "output": {
    "media_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/minimax-hailuo-h3-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.mp4",
    "media_type": "video/mp4"
  },
  "created_at": "2026-08-27T09:42:17.774Z",
  "completed_at": "2026-08-27T09:45:02.118Z"
}

Response Fields

Status Values

Status Flow

QUEUED -> PROCESSING -> COMPLETED
                     -> FAILED
                     -> ERROR

Typical Workflow

1. POST the request body to https://gateway.pixazo.ai/minimax-hailuo-h3-max/v1/text-to-video.
2. Read request_id from the 202 response.
3. Poll https://gateway.pixazo.ai/v2/requests/status/{request_id} every few seconds, or wait for the webhook.
4. On COMPLETED, download output.media_url.

MiniMax H3 Max API Documentation (Image to Video)

All requests require an API key passed via header.

Webhook (Optional)

Instead of polling, supply a callback URL and Pixazo will POST the result to it as soon as the request reaches a terminal state.

Example: enable webhook

curl -X POST https://gateway.pixazo.ai/minimax-hailuo-h3-max/v1/image-to-video \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-URL: https://your-server.example.com/hooks/video" \
  -H "X-Webhook-Mode: terminal" \
  -d '{"prompt": "the camera slowly pushes in", "image_url": "https://your-cdn.example.com/first-frame.jpg", "prompt_expansion_mode": "balanced"}'

Callback Payload

{
  "request_id": "minimax-hailuo-h3-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "minimax-hailuo-h3-max",
  "error": null,
  "output": {
    "media_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/minimax-hailuo-h3-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.mp4",
    "media_type": "video/mp4"
  },
  "created_at": "2026-08-27T09:42:17.774Z",
  "completed_at": "2026-08-27T09:45:02.118Z"
}

Failure callback shape

{
  "request_id": "minimax-hailuo-h3-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "minimax-hailuo-h3-max",
  "error": "Generation failed upstream",
  "output": null
}

Delivery semantics

• terminal fires exactly once, on COMPLETED or FAILED.
• sync also fires on intermediate transitions such as QUEUED → PROCESSING.
• Deliveries are idempotent on request_id — de-duplicate on it, as a callback may be retried.
• Respond 200 within a few seconds; slow endpoints are treated as failed deliveries.
• HTTPS is required.

Request Parameters - MiniMax H3 Max API (Image to Video)

Request Headers

Response Handling

Error Responses

Insufficient balance (402)

{
  "error": "Insufficient balance",
  "required": 0.4,
  "available": 0.12,
  "currency": "USD"
}

Invalid parameter (400)

{
  "error": "Invalid value for 'duration': must be between 5 and 15"
}

Failure after acceptance

A request that was accepted can still fail during generation. That is reported through the status endpoint or the webhook, with status set to ERROR:

{
  "request_id": "minimax-hailuo-h3-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "minimax-hailuo-h3-max",
  "error": "Generation failed upstream",
  "output": null
}

Retrieving Results

Poll the status endpoint with the request_id returned by the submit call.

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}

cURL Example

curl https://gateway.pixazo.ai/v2/requests/status/minimax-hailuo-h3-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY"

Response (Completed)

{
  "request_id": "minimax-hailuo-h3-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "minimax-hailuo-h3-max",
  "error": null,
  "output": {
    "media_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/minimax-hailuo-h3-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.mp4",
    "media_type": "video/mp4"
  },
  "created_at": "2026-08-27T09:42:17.774Z",
  "completed_at": "2026-08-27T09:45:02.118Z"
}

Response Fields

Status Values

Status Flow

QUEUED -> PROCESSING -> COMPLETED
                     -> FAILED
                     -> ERROR

Typical Workflow

1. POST the request body to https://gateway.pixazo.ai/minimax-hailuo-h3-max/v1/image-to-video.
2. Read request_id from the 202 response.
3. Poll https://gateway.pixazo.ai/v2/requests/status/{request_id} every few seconds, or wait for the webhook.
4. On COMPLETED, download output.media_url.

MiniMax H3 Max API Documentation (Reference to Video)

All requests require an API key passed via header.

Webhook (Optional)

Instead of polling, supply a callback URL and Pixazo will POST the result to it as soon as the request reaches a terminal state.

Example: enable webhook

curl -X POST https://gateway.pixazo.ai/minimax-hailuo-h3-max/v1/reference-to-video \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-URL: https://your-server.example.com/hooks/video" \
  -H "X-Webhook-Mode: terminal" \
  -d '{"prompt": "the camera slowly pushes in", "reference_image_urls": ["https://your-cdn.example.com/subject.jpg"], "prompt_expansion_mode": "balanced"}'

Callback Payload

{
  "request_id": "minimax-hailuo-h3-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "minimax-hailuo-h3-max",
  "error": null,
  "output": {
    "media_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/minimax-hailuo-h3-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.mp4",
    "media_type": "video/mp4"
  },
  "created_at": "2026-08-27T09:42:17.774Z",
  "completed_at": "2026-08-27T09:45:02.118Z"
}

Failure callback shape

{
  "request_id": "minimax-hailuo-h3-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "minimax-hailuo-h3-max",
  "error": "Generation failed upstream",
  "output": null
}

Delivery semantics

• terminal fires exactly once, on COMPLETED or FAILED.
• sync also fires on intermediate transitions such as QUEUED → PROCESSING.
• Deliveries are idempotent on request_id — de-duplicate on it, as a callback may be retried.
• Respond 200 within a few seconds; slow endpoints are treated as failed deliveries.
• HTTPS is required.

Request Parameters - MiniMax H3 Max API (Reference to Video)

Request Headers

Response Handling

Error Responses

Insufficient balance (402)

{
  "error": "Insufficient balance",
  "required": 0.4,
  "available": 0.12,
  "currency": "USD"
}

Invalid parameter (400)

{
  "error": "Invalid value for 'duration': must be between 5 and 15"
}

Failure after acceptance

A request that was accepted can still fail during generation. That is reported through the status endpoint or the webhook, with status set to ERROR:

{
  "request_id": "minimax-hailuo-h3-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "minimax-hailuo-h3-max",
  "error": "Generation failed upstream",
  "output": null
}

Retrieving Results

Poll the status endpoint with the request_id returned by the submit call.

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}

cURL Example

curl https://gateway.pixazo.ai/v2/requests/status/minimax-hailuo-h3-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY"

Response (Completed)

{
  "request_id": "minimax-hailuo-h3-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "minimax-hailuo-h3-max",
  "error": null,
  "output": {
    "media_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/minimax-hailuo-h3-max_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.mp4",
    "media_type": "video/mp4"
  },
  "created_at": "2026-08-27T09:42:17.774Z",
  "completed_at": "2026-08-27T09:45:02.118Z"
}

Response Fields

Status Values

Status Flow

QUEUED -> PROCESSING -> COMPLETED
                     -> FAILED
                     -> ERROR

Typical Workflow

1. POST the request body to https://gateway.pixazo.ai/minimax-hailuo-h3-max/v1/reference-to-video.
2. Read request_id from the 202 response.
3. Poll https://gateway.pixazo.ai/v2/requests/status/{request_id} every few seconds, or wait for the webhook.
4. On COMPLETED, download output.media_url.

MiniMax H3 Max API Documentation (Audio to Video (Ref Audio + Ref Image to Video) - Lipsync)

All requests require an API key passed via header.

Webhook (Optional)

Instead of polling, you can receive a Webhook callback when the request reaches a terminal state. Provide a Webhook URL via header on the submit request.

Example: enable Webhook

curl -X POST 'https://gateway.pixazo.ai/minimax-hailuo-h3-max-lip-sync/v1/image-to-video' \
  -H 'Content-Type: application/json' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
  -H 'X-Webhook-URL: https://your-server.com/webhook' \
  --data-raw '{"image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/lipsync/talking-head-frame.jpg", "audio_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/audio/speech-6s.mp3", "resolution": "768P"}'

Callback Payload (success)

{
  "request_id": "minimax-hailuo-h3-max-lip-sync_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "minimax-hailuo-h3-max-lip-sync",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/minimax-hailuo-h3-max-lip-sync_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-09-18T10:40:08.748Z",
  "completed_at": "2026-09-18T10:43:36.118Z"
}

Failure callback shape

{
  "request_id": "minimax-hailuo-h3-max-lip-sync_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "minimax-hailuo-h3-max-lip-sync",
  "error": "Description of the failure",
  "output": null
}

Delivery semantics

• terminal mode: one Webhook callback when the request is COMPLETED or ERROR.
• sync mode: a Webhook callback on each status change.
• Callbacks are idempotent on request_id — de-duplicate on it.
• Respond 200 within a few seconds; the Webhook endpoint must be HTTPS.

Request Parameters - MiniMax H3 Max API (Audio to Video (Ref Audio + Ref Image to Video) - Lipsync)

• image_url and audio_url are the only required fields. Both must be public http(s) URLs that stay reachable until the request has been processed.
• There is no duration parameter. The length of the video follows the audio: at least 5 seconds, and at most 15 — audio over 15 seconds is clipped to its first 15 seconds.
• The model is fixed by the URL. Do not send a model_id in the body.

Input requirements

Image

• A public http(s) URL. The image is fetched when the request is processed, so the URL must stay reachable until then.
• The aspect ratio (width ÷ height) must be between 0.4 and 2.5 — from a tall 2:5 portrait to a wide 5:2 panorama. Images outside that range are rejected after acceptance.
• The output uses the supported aspect ratio nearest the image, at the chosen resolution.

Audio

• A public http(s) URL to an audio file, at least 5 seconds long. Shorter audio is rejected after acceptance.
• Audio over 15 seconds is clipped to its first 15 seconds, so the video is never longer than 15 seconds. Trim the audio yourself if a different 15 seconds is wanted.
• The (clipped) audio becomes the soundtrack of the returned MP4.

Request Headers

Response Handling

Parameter problems are caught when you submit and returned as a 400, before any hold is placed on your balance. Checks that need the files themselves — whether the URLs can be fetched, the audio length, the image aspect ratio, the safety check — run after the request is accepted and are reported through the status endpoint as status: "ERROR", with a message in error saying what to fix. Failed requests are not billed — the hold is released in full.

Error Responses

Invalid parameter (400)

Returned when you submit, before any hold is placed. violations lists every problem found, one entry per field.

{
  "error": "Invalid request parameters",
  "message": "'audio_url' is required",
  "violations": [
    "'audio_url' is required"
  ]
}

Failure after acceptance

A request that was accepted can still fail — an input URL that cannot be fetched, audio under 5 seconds, an image whose aspect ratio is outside 0.4–2.5, or content flagged by the safety checker. That is reported through the status endpoint or the webhook, with status set to ERROR. Failed requests are not billed.

{
  "request_id": "minimax-hailuo-h3-max-lip-sync_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "minimax-hailuo-h3-max-lip-sync",
  "error": "Description of the failure",
  "output": null
}

Retrieving Results

Poll the status endpoint with the request_id from the submit response until status is COMPLETED (or FAILED/ERROR), then download the video from output.media_url.

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}

cURL Example

curl 'https://gateway.pixazo.ai/v2/requests/status/minimax-hailuo-h3-max-lip-sync_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY'

Completed response

{
  "request_id": "minimax-hailuo-h3-max-lip-sync_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "minimax-hailuo-h3-max-lip-sync",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/minimax-hailuo-h3-max-lip-sync_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-09-18T10:40:08.748Z",
  "completed_at": "2026-09-18T10:43:36.118Z"
}

Response Fields

Status Values & Flow

QUEUED → PROCESSING → COMPLETED (success) or FAILED/ERROR (failure).

Typical workflow

1. POST the request body to https://gateway.pixazo.ai/minimax-hailuo-h3-max-lip-sync/v1/image-to-video.
2. Read request_id from the 202 response.
3. Poll https://gateway.pixazo.ai/v2/requests/status/{request_id} every few seconds, or wait for the webhook.
4. On COMPLETED, download output.media_url.

How billing is measured

Billing is measured on the length of the generated video, in seconds, at the rate for the resolution you chose — not on how long generation takes, and not on the length of the audio you upload beyond the 15 seconds that are used. Because the length is not known until the video exists, a hold covering the 15-second maximum at your resolution is placed when the request is submitted; it is reduced to the real cost once the video has been measured, and released in full if the request fails.

The current rate for each resolution is shown in the pricing panel on this page.

MiniMax H3 Max API Documentation (Video to Video (Video Extension))

All requests require an API key passed via header.

Webhook (Optional)

Instead of polling, you can receive a Webhook callback when the request reaches a terminal state. Provide a Webhook URL via header on the submit request.

Example: enable Webhook

curl -X POST 'https://gateway.pixazo.ai/minimax-hailuo-h3-max-edit/v1/extend-video' \
  -H 'Content-Type: application/json' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
  -H 'X-Webhook-URL: https://your-server.com/webhook' \
  --data-raw '{"video_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/video/input-17s.mp4", "prompt": "He finishes his sentence, smiles and gives a small wave to the camera.", "duration": 5, "resolution": "768P"}'

Callback Payload (success)

{
  "request_id": "minimax-hailuo-h3-max-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "minimax-hailuo-h3-max-edit",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-10-12T10:04:54.387Z",
  "completed_at": "2026-10-12 10:06:21"
}

Failure callback shape

{
  "request_id": "minimax-hailuo-h3-max-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "minimax-hailuo-h3-max-edit",
  "error": "Description of the failure"
}

Delivery semantics

• terminal mode: one Webhook callback when the request is COMPLETED or ERROR.
• sync mode: a Webhook callback on every poll while the request is processing (status PROCESSING), plus the final COMPLETED/ERROR callback.
• Callbacks are idempotent on request_id — de-duplicate on it.
• Respond 200 within a few seconds; the Webhook endpoint must be HTTPS.

Request Parameters

Good to know

• Each request returns one video. batch_size, num_images, number_of_images, n and count are rejected — send one request per video.
• Set the length of the new footage with duration, in seconds from 0.71 to 15 (5 when you leave it out); seconds, num_frames, frames_per_second and music_length_ms are rejected.
• Set the resolution with resolution: 480P, 768P, 1080P or 2K, written exactly as listed (768P when you leave it out).
• Send every field at the top level of the JSON body, with the text in prompt; parameters, content and text are rejected.
• Send your video as one URL in video_url; video, videos and video_uri are rejected.
• Extend Video takes no images and has no timing or color settings: image_url, image_urls, image, start_time, resume_time, color_match and reference_image_urls are rejected (they belong to the Insert Video operation).
• This API takes no reference audio or reference videos: reference_audio_urls, reference_video_urls and audio_url are rejected.
• Use the JSON types shown: duration is a number (5, not "5"), seed is a whole number, and the switches are true or false, not strings.
• Omit a field instead of sending null.
• Results are always returned as a URL in output.media_url; sync_mode and stream are rejected.
• Webhooks are set with the X-Webhook-URL / X-Webhook-Mode headers; webhook_url, webhook_mode and callback_url in the JSON body are rejected.

Length and Resolution

Set duration to the length of the new footage in seconds, from 0.71 to 15 (fractions are allowed); 5 applies when you leave it out. Set resolution to one of the values below, written exactly as listed; 768P applies when you leave it out. Billing is per second of the requested duration at the rate for the requested resolution. Only the new footage is billed: the length of your video does not change the amount.

Example: 8 seconds of new footage at 1080P

{
  "video_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/video/input-17s.mp4",
  "prompt": "The camera slowly pulls back to show the whole room as he keeps talking.",
  "duration": 8,
  "resolution": "1080P"
}

Source Video

• Send one video in video_url as a publicly reachable https URL (recommended). Use an MP4 file between 1.625 and 60 seconds long, with a width-to-height ratio between 0.4 and 2.5.
• The video is downloaded when you submit: a URL that cannot be downloaded, or a very large file, may be refused at once with a 400, with nothing charged.
• Describe what happens next in prompt (required, up to 50000 characters): the continuation, not your video.
• output: extended (the default) returns your video and the new footage as one video; continuation returns a clip that starts with a 1.625-second repeat of the end of your video, then the new footage. With output left as extended, the returned video is your video followed by the new footage.
• aspect_ratio: auto (the default) follows your video; any other value crops the video to that shape.

Example: return only the new footage (continuation)

{
  "video_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/video/input-17s.mp4",
  "prompt": "He looks to the side, then back at the camera and smiles.",
  "duration": 5,
  "resolution": "480P",
  "output": "continuation"
}

Audio

This API takes no reference audio: reference_audio_urls and audio_url are rejected. When your video has sound, the extended video has sound too.

Request Headers

Response Handling

Parameter problems are caught when you submit and returned as a 400, before any hold is placed on your balance. An input that cannot be downloaded is also refused at submit with a 400, and its hold is released at once: nothing is charged. Problems that need the model to run are reported through the status endpoint as status: "ERROR", with a message in error saying what went wrong. Failed requests are not billed — the hold is released in full.

Example error responses

A refused request returns error, a message that joins every problem found, and the same problems one by one in violations.

Missing prompt (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'prompt' is required",
  "violations": [
    "'prompt' is required"
  ]
}

A resolution in the wrong case (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'resolution' must be one of: \"480P\", \"768P\", \"1080P\", \"2K\" (got \"768p\")",
  "violations": [
    "'resolution' must be one of: \"480P\", \"768P\", \"1080P\", \"2K\" (got \"768p\")"
  ]
}

A value out of range (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'duration' must be <= 15 (got 16)",
  "violations": [
    "'duration' must be <= 15 (got 16)"
  ]
}

A number sent as a string (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'duration' must be number (got string)",
  "violations": [
    "'duration' must be number (got string)"
  ]
}

An Insert Video setting sent to Extend Video (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'color_match' must be one of:  (got true); 'color_match' is not accepted by extend-video. It is an insert-video setting.",
  "violations": [
    "'color_match' must be one of:  (got true)",
    "'color_match' is not accepted by extend-video. It is an insert-video setting."
  ]
}

Retrieving Results

Poll the status endpoint with the request_id from the submit response until status is COMPLETED or ERROR, then download the video from output.media_url. Treat any status other than QUEUED, PROCESSING or COMPLETED as a failure.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

cURL example

curl 'https://gateway.pixazo.ai/v2/requests/status/minimax-hailuo-h3-max-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY'

Completed response

{
  "request_id": "minimax-hailuo-h3-max-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "minimax-hailuo-h3-max-edit",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-10-12T10:04:54.387Z",
  "completed_at": "2026-10-12 10:06:21"
}

Response Fields

Status Values & Flow

QUEUED → PROCESSING → COMPLETED (success) or ERROR (failure).

Typical workflow

1. Send the request to POST https://gateway.pixazo.ai/minimax-hailuo-h3-max-edit/v1/extend-video.
2. Save the request_id from the 202 response.
3. Poll GET /v2/requests/status/{request_id} every 10 seconds or so, or use a Webhook instead.
4. When status is COMPLETED, download the video from output.media_url.

How Billing Is Measured

Billing is measured per second of the requested duration, at the rate for the requested resolution: the amount is the per-second rate for resolution (768P when you leave it out) times duration (5 seconds when you leave it out). Only the new footage is billed: the length of your video does not change the amount. Higher resolutions cost more per second. The prompt, seed, aspect ratio, output mode, prompt expansion and safety setting do not change the amount. The amount is placed as a hold when the request is submitted and released in full if the request fails. The current rate is shown in the pricing panel on this page.

MiniMax H3 Max API Documentation (Video to Video (Scene Insertion))

All requests require an API key passed via header.

Webhook (Optional)

Instead of polling, you can receive a Webhook callback when the request reaches a terminal state. Provide a Webhook URL via header on the submit request.

Example: enable Webhook

curl -X POST 'https://gateway.pixazo.ai/minimax-hailuo-h3-max-edit/v1/insert-video' \
  -H 'Content-Type: application/json' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
  -H 'X-Webhook-URL: https://your-server.com/webhook' \
  --data-raw '{"video_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/video/input-17s.mp4", "prompt": "A close-up of the potted plant beside him as soft light moves across its leaves.", "start_time": 2, "resume_time": 3, "duration": 5, "resolution": "768p"}'

Callback Payload (success)

{
  "request_id": "minimax-hailuo-h3-max-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "minimax-hailuo-h3-max-edit",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-10-12T10:04:54.387Z",
  "completed_at": "2026-10-12 10:06:21"
}

Failure callback shape

{
  "request_id": "minimax-hailuo-h3-max-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "minimax-hailuo-h3-max-edit",
  "error": "Description of the failure"
}

Delivery semantics

• terminal mode: one Webhook callback when the request is COMPLETED or ERROR.
• sync mode: a Webhook callback on every poll while the request is processing (status PROCESSING), plus the final COMPLETED/ERROR callback.
• Callbacks are idempotent on request_id — de-duplicate on it.
• Respond 200 within a few seconds; the Webhook endpoint must be HTTPS.

Request Parameters

Good to know

• Each request returns one video. batch_size, num_images, number_of_images, n and count are rejected — send one request per video.
• Set the length of the new scene with duration, in seconds from 5 to 13 (5 when you leave it out); seconds, num_frames, frames_per_second and music_length_ms are rejected.
• Set the resolution with resolution: 480p or 768p, written exactly as listed (768p when you leave it out).
• Send every field at the top level of the JSON body, with the text in prompt; parameters, content and text are rejected.
• Send your video as one URL in video_url; video, videos and video_uri are rejected.
• Send up to 4 guide images in reference_image_urls; image_url, image_urls and image are rejected.
• Insert Video has no aspect-ratio, output-mode or safety setting: aspect_ratio, output and enable_safety_checker are rejected.
• This API takes no reference audio or reference videos: reference_audio_urls, reference_video_urls and audio_url are rejected.
• Use the JSON types shown: duration, start_time and resume_time are numbers (5, not "5"), seed is a whole number, and the switches are true or false, not strings.
• Omit a field instead of sending null.
• Results are always returned as a URL in output.media_url; sync_mode and stream are rejected.
• Webhooks are set with the X-Webhook-URL / X-Webhook-Mode headers; webhook_url, webhook_mode and callback_url in the JSON body are rejected.

Length and Resolution

Set duration to the length of the new scene in seconds, from 5 to 13 (fractions are allowed); 5 applies when you leave it out. Set resolution to one of the values below, written exactly as listed; 768p applies when you leave it out. Billing is per second of the requested duration at the rate for the requested resolution. Only the new scene is billed, not the whole returned video.

Example: an 8-second scene at 480p

{
  "video_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/video/input-17s.mp4",
  "prompt": "The view drifts across the framed pictures on the wall.",
  "start_time": 4,
  "resume_time": 6.5,
  "duration": 8,
  "resolution": "480p"
}

Source Video and Timing

• Send one video in video_url as a publicly reachable https URL (recommended), as an MP4 file. It is downloaded when you submit: a URL that cannot be downloaded, or a very large file, may be refused at once with a 400, with nothing charged.
• start_time is where the new scene begins and resume_time is where your video picks up again, both in seconds from the start of your video (start_time from 1.625 to 60, resume_time from 1.63 to 60). The returned video is the whole video: your footage up to start_time, then the new scene, then your footage from resume_time to the end.
• Describe the new scene in prompt (optional, up to 50000 characters), and optionally add guide images (see References).
• color_match (on by default) matches the colors of the new scene to your video.

Example: replace the part between 5.5 and 8 seconds

{
  "video_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/video/input-17s.mp4",
  "prompt": "A close-up of the potted plant beside him as soft light moves across its leaves.",
  "start_time": 5.5,
  "resume_time": 8,
  "duration": 5,
  "resolution": "768p"
}

References

• Send up to 4 images in reference_image_urls, as non-empty URL strings: publicly reachable https URLs are recommended; data URIs are accepted. Use PNG, JPEG, JPG or WebP images.
• Together the images may hold at most 4096 image tokens. Each image counts its width × height / 1,024 tokens, so an image of 1,024 by 1,024 pixels counts 1,024 tokens: four of those fit, and so does one image of 2,048 by 2,048 pixels. A request over the budget is refused at once with a 400, with nothing charged.
• Every image is downloaded when you submit: an image that cannot be downloaded is refused at once with a 400, with nothing charged.

Example: guide the scene with a reference image

{
  "video_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/video/input-17s.mp4",
  "prompt": "A cutaway to the subject of the reference image, who turns toward the camera and smiles.",
  "reference_image_urls": [
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg"
  ],
  "start_time": 2,
  "resume_time": 3,
  "duration": 5,
  "resolution": "768p"
}

4 images over the token budget (synchronous 400)

For example, 4 images of 853 by 1,280 pixels count about 4,265 tokens together:

{
  "error": "Invalid request parameters",
  "message": "'reference_image_urls' totals about 4265 image tokens, over the 4096 allowed. Tokens are (width x height) / 1024 per image, so send smaller reference images or fewer of them.",
  "violations": [
    "'reference_image_urls' totals about 4265 image tokens, over the 4096 allowed. Tokens are (width x height) / 1024 per image, so send smaller reference images or fewer of them."
  ]
}

Audio

This API takes no reference audio or reference videos: reference_audio_urls, reference_video_urls and audio_url are rejected. When your video has sound, the returned video has sound too.

Request Headers

Response Handling

Parameter problems are caught when you submit and returned as a 400, before any hold is placed on your balance. An input that cannot be downloaded is also refused at submit with a 400, and its hold is released at once: nothing is charged. Reference images over the image-token budget are refused with a 400 before any hold is placed. Problems that need the model to run are reported through the status endpoint as status: "ERROR", with a message in error saying what went wrong. Failed requests are not billed — the hold is released in full.

Example error responses

A refused request returns error, a message that joins every problem found, and the same problems one by one in violations.

Missing start_time (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'start_time' is required",
  "violations": [
    "'start_time' is required"
  ]
}

A resolution this operation does not offer (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'resolution' must be one of: \"480p\", \"768p\" (got \"1080p\")",
  "violations": [
    "'resolution' must be one of: \"480p\", \"768p\" (got \"1080p\")"
  ]
}

A value out of range (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'duration' must be >= 5 (got 4)",
  "violations": [
    "'duration' must be >= 5 (got 4)"
  ]
}

More than 4 reference images (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'reference_image_urls' must have at most 4 items (got 5)",
  "violations": [
    "'reference_image_urls' must have at most 4 items (got 5)"
  ]
}

An Extend Video setting sent to Insert Video (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'aspect_ratio' must be one of:  (got \"16:9\"); 'aspect_ratio' is not accepted by insert-video: the scene keeps the source video's frame.",
  "violations": [
    "'aspect_ratio' must be one of:  (got \"16:9\")",
    "'aspect_ratio' is not accepted by insert-video: the scene keeps the source video's frame."
  ]
}

Retrieving Results

Poll the status endpoint with the request_id from the submit response until status is COMPLETED or ERROR, then download the video from output.media_url. Treat any status other than QUEUED, PROCESSING or COMPLETED as a failure.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

cURL example

curl 'https://gateway.pixazo.ai/v2/requests/status/minimax-hailuo-h3-max-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY'

Completed response

{
  "request_id": "minimax-hailuo-h3-max-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "minimax-hailuo-h3-max-edit",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-10-12T10:04:54.387Z",
  "completed_at": "2026-10-12 10:06:21"
}

Response Fields

Status Values & Flow

QUEUED → PROCESSING → COMPLETED (success) or ERROR (failure).

Typical workflow

1. Send the request to POST https://gateway.pixazo.ai/minimax-hailuo-h3-max-edit/v1/insert-video.
2. Save the request_id from the 202 response.
3. Poll GET /v2/requests/status/{request_id} every 10 seconds or so, or use a Webhook instead.
4. When status is COMPLETED, download the video from output.media_url.

How Billing Is Measured

Billing is measured per second of the requested duration, at the rate for the requested resolution: the amount is the per-second rate for resolution (768p when you leave it out) times duration (5 seconds when you leave it out). Only the new scene is billed, not the whole returned video. Higher resolutions cost more per second. The prompt, reference images, timing, seed, prompt expansion and color matching do not change the amount. The amount is placed as a hold when the request is submitted and released in full if the request fails. The current rate is shown in the pricing panel on this page.

MiniMax H3 Max API Documentation (Video to Video (Relighting))

All requests require an API key passed via header.

Webhook (Optional)

Instead of polling, you can receive a Webhook callback when the request reaches a terminal state. Provide a Webhook URL via header on the submit request.

Example: enable Webhook

curl -X POST 'https://gateway.pixazo.ai/minimax-hailuo-h3-max-v2v/v1/relight-video' \
  -H 'Content-Type: application/json' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
  -H 'X-Webhook-URL: https://your-server.com/webhook' \
  --data-raw '{"video_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/video/input-5s.mp4", "reference_image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/lighting-sphere.png", "resolution": "768P"}'

Callback Payload (success)

{
  "request_id": "minimax-hailuo-h3-max-v2v_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "minimax-hailuo-h3-max-v2v",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-10-12T10:04:54.387Z",
  "completed_at": "2026-10-12 10:06:21"
}

Failure callback shape

{
  "request_id": "minimax-hailuo-h3-max-v2v_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "minimax-hailuo-h3-max-v2v",
  "error": "Description of the failure"
}

Delivery semantics

• terminal mode: one Webhook callback when the request is COMPLETED or ERROR.
• sync mode: a Webhook callback on every poll while the request is processing (status PROCESSING), plus the final COMPLETED/ERROR callback.
• Callbacks are idempotent on request_id — de-duplicate on it.
• Respond 200 within a few seconds; the Webhook endpoint must be HTTPS.

Request Parameters

Good to know

• Each request returns one video. batch_size, num_images, number_of_images, n and count are rejected — send one request per video.
• There is no duration to set: duration, seconds, num_frames, frames_per_second and music_length_ms are rejected. Billing follows the length of the returned video (see How Billing Is Measured).
• Set the resolution with resolution: 480P, 768P, 1080P or 2K, written exactly as listed (768P when you leave it out).
• Send every field at the top level of the JSON body; parameters, content and text are rejected.
• Send your video as one URL in video_url; video, videos and video_uri are rejected.
• Send the lighting image as one URL in reference_image_url; image_url, image_urls and image are rejected.
• Relight Video takes no prompt and no photos of people: prompt, reference_image_urls and enhance_realism are rejected (they belong to the Recast Video operation).
• This API takes no reference audio or reference videos: reference_audio_urls, reference_video_urls and audio_url are rejected.
• Use the JSON types shown: seed is a whole number, and the switches are true or false, not strings.
• Omit a field instead of sending null.
• Results are always returned as a URL in output.media_url; sync_mode and stream are rejected.
• Webhooks are set with the X-Webhook-URL / X-Webhook-Mode headers; webhook_url, webhook_mode and callback_url in the JSON body are rejected.

Resolution and Length

Set resolution to one of the values below, written exactly as listed; 768P applies when you leave it out. There is no duration to set: you are billed per second of the returned video, at the rate for the requested resolution (see How Billing Is Measured).

Example: relight at 1080P

{
  "video_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/video/input-5s.mp4",
  "reference_image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/lighting-sphere.png",
  "resolution": "1080P"
}

Source Video and Lighting

• Send one video in video_url as a publicly reachable https URL (recommended), from about 2.33 to 15 seconds long. It is downloaded and measured when you submit: a URL that cannot be downloaded, or a very large file, may be refused at once with a 400, and a video longer than 30 seconds is refused at once with a 400, with nothing charged. Before relighting, your video is trimmed at the end by up to about 0.7 seconds to fit the model's frame pattern, and the returned video is as long as the trimmed video.
• Send the lighting in reference_image_url: an image of a sphere lit the way you want your video lit, for example a warm light from the upper left and a cool fill from the right.
• aspect_ratio sets the frame shape of the result; 16:9 applies when you leave it out, whatever the shape of your video.

Example: a square result at 480P

{
  "video_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/video/input-5s.mp4",
  "reference_image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/lighting-sphere.png",
  "resolution": "480P",
  "aspect_ratio": "1:1"
}

A video longer than 30 seconds (synchronous 400)

{
  "error": "Input too long",
  "message": "The source media is 40s. This API accepts inputs up to 30s — split it into shorter segments.",
  "max_input_seconds": 30,
  "input_seconds": 40
}

Request Headers

Response Handling

Parameter problems are caught when you submit and returned as a 400, before any hold is placed on your balance. An input that cannot be downloaded is also refused at submit with a 400, and its hold is released at once: nothing is charged. A source video longer than 30 seconds is refused with a 400 before any hold is placed. Problems that need the model to run are reported through the status endpoint as status: "ERROR", with a message in error saying what went wrong. Failed requests are not billed — the hold is released in full.

Example error responses

A refused request returns error, a message that joins every problem found, and the same problems one by one in violations.

Missing reference_image_url (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'reference_image_url' is required",
  "violations": [
    "'reference_image_url' is required"
  ]
}

A resolution in the wrong case (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'resolution' must be one of: \"480P\", \"768P\", \"1080P\", \"2K\" (got \"768p\")",
  "violations": [
    "'resolution' must be one of: \"480P\", \"768P\", \"1080P\", \"2K\" (got \"768p\")"
  ]
}

A duration sent (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'duration' must be one of:  (got 5); 'duration' is not accepted. The length comes from your source video: there is nothing to set.",
  "violations": [
    "'duration' must be one of:  (got 5)",
    "'duration' is not accepted. The length comes from your source video: there is nothing to set."
  ]
}

A seed sent as a string (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'seed' must be integer (got string)",
  "violations": [
    "'seed' must be integer (got string)"
  ]
}

A Recast Video setting sent to Relight Video (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'prompt' must be one of:  (got \"Warm evening light\"); 'prompt' is not accepted by relight-video: the lighting comes from 'reference_image_url'.",
  "violations": [
    "'prompt' must be one of:  (got \"Warm evening light\")",
    "'prompt' is not accepted by relight-video: the lighting comes from 'reference_image_url'."
  ]
}

Retrieving Results

Poll the status endpoint with the request_id from the submit response until status is COMPLETED or ERROR, then download the video from output.media_url. Treat any status other than QUEUED, PROCESSING or COMPLETED as a failure.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

cURL example

curl 'https://gateway.pixazo.ai/v2/requests/status/minimax-hailuo-h3-max-v2v_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY'

Completed response

{
  "request_id": "minimax-hailuo-h3-max-v2v_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "minimax-hailuo-h3-max-v2v",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-10-12T10:04:54.387Z",
  "completed_at": "2026-10-12 10:06:21"
}

Response Fields

Status Values & Flow

QUEUED → PROCESSING → COMPLETED (success) or ERROR (failure).

Typical workflow

1. Send the request to POST https://gateway.pixazo.ai/minimax-hailuo-h3-max-v2v/v1/relight-video.
2. Save the request_id from the 202 response.
3. Poll GET /v2/requests/status/{request_id} every 10 seconds or so, or use a Webhook instead.
4. When status is COMPLETED, download the video from output.media_url.

How Billing Is Measured

Billing is measured per second of the returned video, at the rate for the requested resolution (resolution, 768P when you leave it out). There is no duration to set. When you submit, your video is measured and a hold is placed for its length in whole seconds, rounded up; when the result is delivered, the amount settles to the length of the returned video, counted the same way and never more than the hold. If your video cannot be measured, the hold covers 30 seconds and the amount still settles to the returned video. Higher resolutions cost more per second. The lighting image, frame shape, seed and safety setting do not change the amount. The hold is released in full if the request fails. The current rate is shown in the pricing panel on this page.

MiniMax H3 Max API Documentation (Video to Video (Character Replacement))

All requests require an API key passed via header.

Webhook (Optional)

Instead of polling, you can receive a Webhook callback when the request reaches a terminal state. Provide a Webhook URL via header on the submit request.

Example: enable Webhook

curl -X POST 'https://gateway.pixazo.ai/minimax-hailuo-h3-max-v2v/v1/recast-video' \
  -H 'Content-Type: application/json' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
  -H 'X-Webhook-URL: https://your-server.com/webhook' \
  --data-raw '{"video_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/video/input-5s.mp4", "reference_image_urls": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg"], "prompt": "The man in the video becomes the woman in the photo.", "resolution": "1080P"}'

Callback Payload (success)

{
  "request_id": "minimax-hailuo-h3-max-v2v_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "minimax-hailuo-h3-max-v2v",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-10-12T10:04:54.387Z",
  "completed_at": "2026-10-12 10:06:21"
}

Failure callback shape

{
  "request_id": "minimax-hailuo-h3-max-v2v_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "minimax-hailuo-h3-max-v2v",
  "error": "Description of the failure"
}

Delivery semantics

• terminal mode: one Webhook callback when the request is COMPLETED or ERROR.
• sync mode: a Webhook callback on every poll while the request is processing (status PROCESSING), plus the final COMPLETED/ERROR callback.
• Callbacks are idempotent on request_id — de-duplicate on it.
• Respond 200 within a few seconds; the Webhook endpoint must be HTTPS.

Request Parameters

Good to know

• Each request returns one video. batch_size, num_images, number_of_images, n and count are rejected — send one request per video.
• There is no duration to set: duration, seconds, num_frames, frames_per_second and music_length_ms are rejected. Billing follows the length of the returned video (see How Billing Is Measured).
• Set the resolution with resolution: 768P or 1080P, written exactly as listed (1080P when you leave it out).
• Send every field at the top level of the JSON body; parameters, content and text are rejected.
• Send your video as one URL in video_url; video, videos and video_uri are rejected.
• Send the photos in reference_image_urls, as a list even for one photo; image_url, image_urls and image are rejected.
• Recast Video has no frame-shape or lighting setting: aspect_ratio and reference_image_url are rejected (they belong to the Relight Video operation).
• This API takes no reference audio or reference videos: reference_audio_urls, reference_video_urls and audio_url are rejected.
• Use the JSON types shown: seed is a whole number, and the switches are true or false, not strings.
• Omit a field instead of sending null.
• Results are always returned as a URL in output.media_url; sync_mode and stream are rejected.
• Webhooks are set with the X-Webhook-URL / X-Webhook-Mode headers; webhook_url, webhook_mode and callback_url in the JSON body are rejected.

Resolution and Length

Set resolution to one of the values below, written exactly as listed; 1080P applies when you leave it out. There is no duration to set: you are billed per second of the returned video, at the rate for the requested resolution (see How Billing Is Measured).

Example: recast at 768P

{
  "video_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/video/input-5s.mp4",
  "reference_image_urls": [
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg"
  ],
  "resolution": "768P"
}

Source Video and People

• Send one video in video_url as a publicly reachable https URL (recommended), 5 to 30 seconds long, with no single shot longer than 15 seconds. It is downloaded and measured when you submit: a URL that cannot be downloaded, or a very large file, may be refused at once with a 400, and a video longer than 30 seconds is refused at once with a 400, with nothing charged. The returned video is as long as your video.
• Send one photo per new person in reference_image_urls (1 to 4 photos, always as a list). By default the people in the photos replace the main people in your video from left to right.
• Optionally say who becomes whom, or what else to keep or change, in prompt (up to 2000 characters).
• enhance_realism (off by default) asks for more natural skin and better blending of the new people into the scene.

Example: say who becomes whom, with enhance_realism

{
  "video_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/video/input-5s.mp4",
  "reference_image_urls": [
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg"
  ],
  "prompt": "The man in the video becomes the woman in the photo; keep his clothes and the room as they are.",
  "enhance_realism": true,
  "resolution": "1080P"
}

A video longer than 30 seconds (synchronous 400)

{
  "error": "Input too long",
  "message": "The source media is 40s. This API accepts inputs up to 30s — split it into shorter segments.",
  "max_input_seconds": 30,
  "input_seconds": 40
}

Request Headers

Response Handling

Parameter problems are caught when you submit and returned as a 400, before any hold is placed on your balance. An input that cannot be downloaded is also refused at submit with a 400, and its hold is released at once: nothing is charged. A source video longer than 30 seconds is refused with a 400 before any hold is placed. Problems that need the model to run are reported through the status endpoint as status: "ERROR", with a message in error saying what went wrong. Failed requests are not billed — the hold is released in full.

Example error responses

A refused request returns error, a message that joins every problem found, and the same problems one by one in violations.

Missing reference_image_urls (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'reference_image_urls' is required",
  "violations": [
    "'reference_image_urls' is required"
  ]
}

A resolution this operation does not offer (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'resolution' must be one of: \"768P\", \"1080P\" (got \"480P\")",
  "violations": [
    "'resolution' must be one of: \"768P\", \"1080P\" (got \"480P\")"
  ]
}

More than 4 photos (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'reference_image_urls' must have at most 4 items (got 5)",
  "violations": [
    "'reference_image_urls' must have at most 4 items (got 5)"
  ]
}

One photo sent as a string instead of a list (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'reference_image_urls' must be array (got string)",
  "violations": [
    "'reference_image_urls' must be array (got string)"
  ]
}

A Relight Video setting sent to Recast Video (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'aspect_ratio' must be one of:  (got \"16:9\"); 'aspect_ratio' is not accepted by recast-video. Remove the field from the request.",
  "violations": [
    "'aspect_ratio' must be one of:  (got \"16:9\")",
    "'aspect_ratio' is not accepted by recast-video. Remove the field from the request."
  ]
}

Retrieving Results

Poll the status endpoint with the request_id from the submit response until status is COMPLETED or ERROR, then download the video from output.media_url. Treat any status other than QUEUED, PROCESSING or COMPLETED as a failure.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

cURL example

curl 'https://gateway.pixazo.ai/v2/requests/status/minimax-hailuo-h3-max-v2v_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY'

Completed response

{
  "request_id": "minimax-hailuo-h3-max-v2v_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "minimax-hailuo-h3-max-v2v",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-10-12T10:04:54.387Z",
  "completed_at": "2026-10-12 10:06:21"
}

Response Fields

Status Values & Flow

QUEUED → PROCESSING → COMPLETED (success) or ERROR (failure).

Typical workflow

1. Send the request to POST https://gateway.pixazo.ai/minimax-hailuo-h3-max-v2v/v1/recast-video.
2. Save the request_id from the 202 response.
3. Poll GET /v2/requests/status/{request_id} every 10 seconds or so, or use a Webhook instead.
4. When status is COMPLETED, download the video from output.media_url.

How Billing Is Measured

Billing is measured per second of the returned video, at the rate for the requested resolution (resolution, 1080P when you leave it out). There is no duration to set. When you submit, your video is measured and a hold is placed for its length in whole seconds, rounded up; when the result is delivered, the amount settles to the length of the returned video, counted the same way and never more than the hold. If your video cannot be measured, the hold covers 30 seconds and the amount still settles to the returned video. Higher resolutions cost more per second. The number of photos, the prompt, the seed, the realism setting and the safety setting do not change the amount. The hold is released in full if the request fails. The current rate is shown in the pricing panel on this page.

MiniMax H3 Max Turbo API Documentation (Text to Video)

All requests require an API key passed via header.

Webhook (Optional)

Instead of polling, supply a callback URL and Pixazo will POST the result to it as soon as the request reaches a terminal state.

Example: enable webhook

curl -X POST https://gateway.pixazo.ai/minimax-hailuo-h3-max-turbo/v1/text-to-video \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-URL: https://your-server.example.com/hooks/video" \
  -H "X-Webhook-Mode: terminal" \
  -d '{"prompt": "a lone lighthouse beam sweeping across fog at dusk", "prompt_expansion_mode": "balanced"}'

Callback Payload

{
  "request_id": "minimax-hailuo-h3-max-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "minimax-hailuo-h3-max-turbo",
  "error": null,
  "output": {
    "media_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/minimax-hailuo-h3-max-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.mp4",
    "media_type": "video/mp4"
  },
  "created_at": "2026-08-27T09:42:17.774Z",
  "completed_at": "2026-08-27T09:45:02.118Z"
}

Failure callback shape

{
  "request_id": "minimax-hailuo-h3-max-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "minimax-hailuo-h3-max-turbo",
  "error": "Generation failed upstream",
  "output": null
}

Delivery semantics

• terminal fires exactly once, on COMPLETED or FAILED.
• sync also fires on intermediate transitions such as QUEUED → PROCESSING.
• Deliveries are idempotent on request_id — de-duplicate on it, as a callback may be retried.
• Respond 200 within a few seconds; slow endpoints are treated as failed deliveries.
• HTTPS is required.

Request Parameters - MiniMax H3 Max Turbo API (Text to Video)

Request Headers

Response Handling

Error Responses

Insufficient balance (402)

{
  "error": "Insufficient balance",
  "required": 0.4,
  "available": 0.12,
  "currency": "USD"
}

Invalid parameter (400)

{
  "error": "Invalid value for 'duration': must be between 5 and 15"
}

Failure after acceptance

A request that was accepted can still fail during generation. That is reported through the status endpoint or the webhook, with status set to ERROR:

{
  "request_id": "minimax-hailuo-h3-max-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "minimax-hailuo-h3-max-turbo",
  "error": "Generation failed upstream",
  "output": null
}

Retrieving Results

Poll the status endpoint with the request_id returned by the submit call.

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}

cURL Example

curl https://gateway.pixazo.ai/v2/requests/status/minimax-hailuo-h3-max-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY"

Response (Completed)

{
  "request_id": "minimax-hailuo-h3-max-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "minimax-hailuo-h3-max-turbo",
  "error": null,
  "output": {
    "media_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/minimax-hailuo-h3-max-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.mp4",
    "media_type": "video/mp4"
  },
  "created_at": "2026-08-27T09:42:17.774Z",
  "completed_at": "2026-08-27T09:45:02.118Z"
}

Response Fields

Status Values

Status Flow

QUEUED -> PROCESSING -> COMPLETED
                     -> FAILED
                     -> ERROR

Typical Workflow

1. POST the request body to https://gateway.pixazo.ai/minimax-hailuo-h3-max-turbo/v1/text-to-video.
2. Read request_id from the 202 response.
3. Poll https://gateway.pixazo.ai/v2/requests/status/{request_id} every few seconds, or wait for the webhook.
4. On COMPLETED, download output.media_url.

MiniMax H3 Max Turbo API Documentation (Image to Video)

All requests require an API key passed via header.

Webhook (Optional)

Instead of polling, supply a callback URL and Pixazo will POST the result to it as soon as the request reaches a terminal state.

Example: enable webhook

curl -X POST https://gateway.pixazo.ai/minimax-hailuo-h3-max-turbo/v1/image-to-video \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-URL: https://your-server.example.com/hooks/video" \
  -H "X-Webhook-Mode: terminal" \
  -d '{"prompt": "the camera slowly pushes in", "image_url": "https://your-cdn.example.com/first-frame.jpg", "prompt_expansion_mode": "balanced"}'

Callback Payload

{
  "request_id": "minimax-hailuo-h3-max-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "minimax-hailuo-h3-max-turbo",
  "error": null,
  "output": {
    "media_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/minimax-hailuo-h3-max-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.mp4",
    "media_type": "video/mp4"
  },
  "created_at": "2026-08-27T09:42:17.774Z",
  "completed_at": "2026-08-27T09:45:02.118Z"
}

Failure callback shape

{
  "request_id": "minimax-hailuo-h3-max-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "minimax-hailuo-h3-max-turbo",
  "error": "Generation failed upstream",
  "output": null
}

Delivery semantics

• terminal fires exactly once, on COMPLETED or FAILED.
• sync also fires on intermediate transitions such as QUEUED → PROCESSING.
• Deliveries are idempotent on request_id — de-duplicate on it, as a callback may be retried.
• Respond 200 within a few seconds; slow endpoints are treated as failed deliveries.
• HTTPS is required.

Request Parameters - MiniMax H3 Max Turbo API (Image to Video)

Request Headers

Response Handling

Error Responses

Insufficient balance (402)

{
  "error": "Insufficient balance",
  "required": 0.4,
  "available": 0.12,
  "currency": "USD"
}

Invalid parameter (400)

{
  "error": "Invalid value for 'duration': must be between 5 and 15"
}

Failure after acceptance

A request that was accepted can still fail during generation. That is reported through the status endpoint or the webhook, with status set to ERROR:

{
  "request_id": "minimax-hailuo-h3-max-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "minimax-hailuo-h3-max-turbo",
  "error": "Generation failed upstream",
  "output": null
}

Retrieving Results

Poll the status endpoint with the request_id returned by the submit call.

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}

cURL Example

curl https://gateway.pixazo.ai/v2/requests/status/minimax-hailuo-h3-max-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY"

Response (Completed)

{
  "request_id": "minimax-hailuo-h3-max-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "minimax-hailuo-h3-max-turbo",
  "error": null,
  "output": {
    "media_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/minimax-hailuo-h3-max-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.mp4",
    "media_type": "video/mp4"
  },
  "created_at": "2026-08-27T09:42:17.774Z",
  "completed_at": "2026-08-27T09:45:02.118Z"
}

Response Fields

Status Values

Status Flow

QUEUED -> PROCESSING -> COMPLETED
                     -> FAILED
                     -> ERROR

Typical Workflow

1. POST the request body to https://gateway.pixazo.ai/minimax-hailuo-h3-max-turbo/v1/image-to-video.
2. Read request_id from the 202 response.
3. Poll https://gateway.pixazo.ai/v2/requests/status/{request_id} every few seconds, or wait for the webhook.
4. On COMPLETED, download output.media_url.

MiniMax Music 3.0 API Documentation (Text to Music)

All requests require an API key passed via header.

Webhook (Optional)

Instead of polling, you can receive a Webhook callback when the request reaches a terminal state. A track takes a couple of minutes to render, so a webhook is usually the better fit.

Example: enable Webhook

curl -X POST 'https://gateway.pixazo.ai/minimax-music-3-0/v1/text-to-music' \
  -H 'Content-Type: application/json' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
  -H 'X-Webhook-URL: https://your-server.com/webhook' \
  --data-raw '{"prompt": "Indie folk, melancholic, introspective, longing, solitary walk, coffee shop", "lyrics": "[verse]\nStreetlights flicker, the night breeze sighs\nShadows stretch as I walk alone\n[chorus]\nPushing the wooden door, the aroma spreads\nIn a familiar corner, a stranger gazes", "format": "mp3", "sample_rate": 44100, "bitrate": 256000}'

Callback Payload (success)

{
  "request_id": "minimax-music-3-0_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "minimax-music-3-0",
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/audio.mp3"
    ],
    "media_type": "audio/mpeg"
  },
  "created_at": "2026-08-06T09:14:16.102Z",
  "completed_at": "2026-08-06T09:16:01.870Z"
}

Failure callback shape

{
  "request_id": "minimax-music-3-0_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "minimax-music-3-0",
  "error": "Description of the failure"
}

Delivery semantics

• terminal mode: one Webhook callback when the request is COMPLETED or ERROR.
• sync mode: a Webhook callback on each status change.
• Callbacks are idempotent on request_id — de-duplicate on it.
• Respond 200 within a few seconds; the Webhook endpoint must be HTTPS.

Request Parameters

Notes

The paid tier. Higher throughput, suited to production traffic.

Lyrics, or let the model write them

Exactly one of three things must be true: you supply lyrics, you set lyrics_optimizer to have them written for you, or you set is_instrumental for a track with no vocals. Sending none of the three is rejected.

Instrumental — no vocals, no lyrics needed

{
  "prompt": "Warm lo-fi jazz, rainy afternoon, mellow keys, no vocals",
  "is_instrumental": true,
  "format": "mp3"
}

Let the model write the lyrics from your prompt

{
  "prompt": "Upbeat synthwave about a late night drive through neon streets",
  "lyrics_optimizer": true,
  "format": "mp3"
}

Structure tags

Inside lyrics, tags on their own line mark sections and shape the arrangement:

[verse]\nStreetlights flicker, the night breeze sighs\n[chorus]\nPushing the wooden door, the aroma spreads\n[bridge]\nA stranger gazes from the corner

Request Headers

Response Handling

Retrieving Results

Poll the status endpoint with the request_id from the submit response until status is COMPLETED (or ERROR), then download output.media_url. A track typically takes one to three minutes.

curl 'https://gateway.pixazo.ai/v2/requests/status/minimax-music-3-0_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY'

Completed response

{
  "request_id": "minimax-music-3-0_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "minimax-music-3-0",
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/audio.mp3"
    ],
    "media_type": "audio/mpeg"
  },
  "created_at": "2026-08-06T09:14:16.102Z",
  "completed_at": "2026-08-06T09:16:01.870Z"
}

Response Fields

Status Values & Flow

QUEUED → PROCESSING → COMPLETED (success) or ERROR (failure).

Pricing

Billed at $0.15 per generated track, a flat price regardless of the length of the song — a five-minute track costs the same as a one-minute one.

Failed requests are not billed.

MiniMax Music 3.0 Fast (Free) API Documentation (Text to Music)

All requests require an API key passed via header.

Webhook (Optional)

Instead of polling, you can receive a Webhook callback when the request reaches a terminal state. A track takes a couple of minutes to render, so a webhook is usually the better fit.

Example: enable Webhook

curl -X POST 'https://gateway.pixazo.ai/minimax-music-3-0-fast/v1/text-to-music' \
  -H 'Content-Type: application/json' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
  -H 'X-Webhook-URL: https://your-server.com/webhook' \
  --data-raw '{"prompt": "Indie folk, melancholic, introspective, longing, solitary walk, coffee shop", "lyrics": "[verse]\nStreetlights flicker, the night breeze sighs\nShadows stretch as I walk alone\n[chorus]\nPushing the wooden door, the aroma spreads\nIn a familiar corner, a stranger gazes", "format": "mp3", "sample_rate": 44100, "bitrate": 256000}'

Callback Payload (success)

{
  "request_id": "minimax-music-3-0-fast_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "minimax-music-3-0-fast",
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/audio.mp3"
    ],
    "media_type": "audio/mpeg"
  },
  "created_at": "2026-08-06T09:14:16.102Z",
  "completed_at": "2026-08-06T09:16:01.870Z"
}

Failure callback shape

{
  "request_id": "minimax-music-3-0-fast_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "minimax-music-3-0-fast",
  "error": "Description of the failure"
}

Delivery semantics

• terminal mode: one Webhook callback when the request is COMPLETED or ERROR.
• sync mode: a Webhook callback on each status change.
• Callbacks are idempotent on request_id — de-duplicate on it.
• Respond 200 within a few seconds; the Webhook endpoint must be HTTPS.

Request Parameters

Notes

A free tier with lower throughput, intended for trials and low-volume use. It is rate limited upstream and shared across all callers, so it is not suited to production or bulk generation — use minimax-music-3-0 for that.

Lyrics, or let the model write them

Exactly one of three things must be true: you supply lyrics, you set lyrics_optimizer to have them written for you, or you set is_instrumental for a track with no vocals. Sending none of the three is rejected.

Instrumental — no vocals, no lyrics needed

{
  "prompt": "Warm lo-fi jazz, rainy afternoon, mellow keys, no vocals",
  "is_instrumental": true,
  "format": "mp3"
}

Let the model write the lyrics from your prompt

{
  "prompt": "Upbeat synthwave about a late night drive through neon streets",
  "lyrics_optimizer": true,
  "format": "mp3"
}

Structure tags

Inside lyrics, tags on their own line mark sections and shape the arrangement:

[verse]\nStreetlights flicker, the night breeze sighs\n[chorus]\nPushing the wooden door, the aroma spreads\n[bridge]\nA stranger gazes from the corner

Request Headers

Response Handling

Retrieving Results

Poll the status endpoint with the request_id from the submit response until status is COMPLETED (or ERROR), then download output.media_url. A track typically takes one to three minutes.

curl 'https://gateway.pixazo.ai/v2/requests/status/minimax-music-3-0-fast_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY'

Completed response

{
  "request_id": "minimax-music-3-0-fast_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "minimax-music-3-0-fast",
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/audio.mp3"
    ],
    "media_type": "audio/mpeg"
  },
  "created_at": "2026-08-06T09:14:16.102Z",
  "completed_at": "2026-08-06T09:16:01.870Z"
}

Response Fields

Status Values & Flow

QUEUED → PROCESSING → COMPLETED (success) or ERROR (failure).

Pricing

Free. There is no charge for this tier. It is rate limited upstream and that limit is shared across all callers, so requests may be rejected under load — use minimax-music-3-0 for production traffic.

Failed requests are not billed.

Authentication

All requests require an API key passed via header.

Request Parameters - MiniMax H3 API (Text to Video)

Request Headers

Response Handling

Error Responses

Submit-time errors come back on the POST itself:

{
  "error": "Insufficient Balance"
}

{
  "error": "Model not found"
}

Errors raised while the video is generating are reported on the status endpoint (and via webhook, if configured) with status set to ERROR. A job that fails this way is not charged — the reserved amount is released back to your wallet.

{
  "request_id": "minimax-hailuo-h3_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "minimax-hailuo-h3",
  "error": "Description of the error",
  "output": null
}

Retrieving Results

Poll the universal status endpoint to check progress and retrieve the finished video.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY

curl "https://gateway.pixazo.ai/v2/requests/status/minimax-hailuo-h3_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY"

{
  "request_id": "minimax-hailuo-h3_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "minimax-hailuo-h3",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/minimax-hailuo-h3_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-07-31T10:18:51.900Z",
  "completed_at": "2026-07-31T10:22:49.000Z"
}

Response Fields

Status Values

Status Flow

QUEUED  ->  PROCESSING  ->  COMPLETED
                     \->  FAILED / ERROR

Typical Workflow

1. POST your request and read request_id from the 202 response.
2. Wait roughly 30 seconds, then GET https://gateway.pixazo.ai/v2/requests/status/{request_id}.
3. Keep polling every 15 to 30 seconds while the status is QUEUED or PROCESSING. A 5 second clip typically finishes in 3 to 6 minutes.
4. On COMPLETED, download the file from output.media_url[0].
5. On FAILED or ERROR, read error. Nothing is charged for a failed generation.

Authentication

All requests require an API key passed via header.

Request Parameters - MiniMax H3 API (Image to Video)

Request Headers

Response Handling

Error Responses

Submit-time errors come back on the POST itself:

{
  "error": "Insufficient Balance"
}

{
  "error": "Model not found"
}

Errors raised while the video is generating are reported on the status endpoint (and via webhook, if configured) with status set to ERROR. A job that fails this way is not charged — the reserved amount is released back to your wallet.

{
  "request_id": "minimax-hailuo-h3_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "minimax-hailuo-h3",
  "error": "Description of the error",
  "output": null
}

Retrieving Results

Poll the universal status endpoint to check progress and retrieve the finished video.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY

curl "https://gateway.pixazo.ai/v2/requests/status/minimax-hailuo-h3_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY"

{
  "request_id": "minimax-hailuo-h3_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "minimax-hailuo-h3",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/minimax-hailuo-h3_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-07-31T10:18:51.900Z",
  "completed_at": "2026-07-31T10:22:49.000Z"
}

Response Fields

Status Values

Status Flow

QUEUED  ->  PROCESSING  ->  COMPLETED
                     \->  FAILED / ERROR

Typical Workflow

1. POST your request and read request_id from the 202 response.
2. Wait roughly 30 seconds, then GET https://gateway.pixazo.ai/v2/requests/status/{request_id}.
3. Keep polling every 15 to 30 seconds while the status is QUEUED or PROCESSING. A 5 second clip typically finishes in 3 to 6 minutes.
4. On COMPLETED, download the file from output.media_url[0].
5. On FAILED or ERROR, read error. Nothing is charged for a failed generation.

Authentication

All requests require an API key passed via header.

Request Parameters - MiniMax H3 API (Last Frame to Video)

Request Headers

Response Handling

Error Responses

Submit-time errors come back on the POST itself:

{
  "error": "Insufficient Balance"
}

{
  "error": "Model not found"
}

Errors raised while the video is generating are reported on the status endpoint (and via webhook, if configured) with status set to ERROR. A job that fails this way is not charged — the reserved amount is released back to your wallet.

{
  "request_id": "minimax-hailuo-h3_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "minimax-hailuo-h3",
  "error": "Description of the error",
  "output": null
}

Retrieving Results

Poll the universal status endpoint to check progress and retrieve the finished video.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY

curl "https://gateway.pixazo.ai/v2/requests/status/minimax-hailuo-h3_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY"

{
  "request_id": "minimax-hailuo-h3_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "minimax-hailuo-h3",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/minimax-hailuo-h3_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-07-31T10:18:51.900Z",
  "completed_at": "2026-07-31T10:22:49.000Z"
}

Response Fields

Status Values

Status Flow

QUEUED  ->  PROCESSING  ->  COMPLETED
                     \->  FAILED / ERROR

Typical Workflow

1. POST your request and read request_id from the 202 response.
2. Wait roughly 30 seconds, then GET https://gateway.pixazo.ai/v2/requests/status/{request_id}.
3. Keep polling every 15 to 30 seconds while the status is QUEUED or PROCESSING. A 5 second clip typically finishes in 3 to 6 minutes.
4. On COMPLETED, download the file from output.media_url[0].
5. On FAILED or ERROR, read error. Nothing is charged for a failed generation.

Authentication

All requests require an API key passed via header.