Vidu Q4 API, Vidu Q3 API Pro 7 Pro & Turbo, Vidu API: Pricing, Documentation

Authentication

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/vidu-q4/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 '{"prompt": "The subject turns slowly toward the camera and smiles, gentle push-in.", "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg", "duration": 5, "resolution": "720p"}'

Callback Payload (success)

{
  "request_id": "vidu-q4_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "vidu-q4",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-10-09T10:04:54.387Z",
  "completed_at": "2026-10-09 10:06:21"
}

Failure callback shape

{
  "request_id": "vidu-q4_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "vidu-q4",
  "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 with duration, in whole seconds from 3 to 16 (5 when you leave it out); seconds, num_frames, frames_per_second and music_length_ms are rejected.
• Set the resolution with resolution: 540p, 720p, 1080p, 2K or 4K, written exactly as listed (720p 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 exactly one image as image_url; image_urls, image, images and subjects are rejected.
• Image-to-video has no aspect-ratio or audio setting and takes no references: aspect_ratio, audio, reference_image_urls and reference_audio_urls are rejected (references go to the Reference to Video operation).
• Use the JSON types shown: duration and seed are whole numbers (5, not "5"), and enable_safety_checker is true or false, not a string.
• Omit a field instead of sending null.
• Results are always returned as a URL in output.media_url; sync_mode is accepted only as false.
• 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.
• Options this API does not offer are rejected: end_image_url, is_rec, off_peak, movement_amplitude, bgm, watermark, wm_position, wm_url, meta_data, voice_id, sounds, videos and reference_video_urls.

Length and Resolution

Set duration to the length you want in whole seconds, from 3 to 16; 5 applies when you leave it out. Set resolution to one of the values below; 720p applies when you leave it out. Billing is per second of the requested duration at the rate for the requested resolution, so a longer or higher-resolution video costs more.

Example: an 8-second video at 1080p

{
  "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg",
  "prompt": "Slow orbit around the subject, soft morning light.",
  "duration": 8,
  "resolution": "1080p"
}

Source Image

• Send exactly one image in image_url: a publicly reachable https URL (recommended) or a data URI such as data:image/png;base64,.... A list of images is rejected.
• Use a PNG, JPEG, JPG or WebP file. The image 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.
• The image becomes the first frame of the video. Image-to-video has no aspect-ratio setting. The video keeps the aspect ratio of your image.
• Describe the motion in prompt (optional, up to 5000 characters).

Example: send the image as a data URI (a URL is recommended)

{
  "image_url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
  "duration": 4,
  "resolution": "540p"
}

Audio

Image-to-video has no audio setting: audio and reference_audio_urls are rejected. Image-to-video output includes generated sound.

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 image 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 image_url (synchronous 400)

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

A value that is not allowed (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'resolution' must be one of: \"540p\", \"720p\", \"1080p\", \"2K\", \"4K\" (got \"1440p\")",
  "violations": [
    "'resolution' must be one of: \"540p\", \"720p\", \"1080p\", \"2K\", \"4K\" (got \"1440p\")"
  ]
}

A value out of range (synchronous 400)

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

A number sent as a string (synchronous 400)

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

A field image-to-video does not accept (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'aspect_ratio' must be one of:  (got \"16:9\"); 'aspect_ratio' is not accepted by image-to-video, which has no aspect-ratio setting. Remove the field from the request.",
  "violations": [
    "'aspect_ratio' must be one of:  (got \"16:9\")",
    "'aspect_ratio' is not accepted by image-to-video, which has no aspect-ratio setting. 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/vidu-q4_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY'

Completed response

{
  "request_id": "vidu-q4_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "vidu-q4",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-10-09T10:04:54.387Z",
  "completed_at": "2026-10-09 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/vidu-q4/v1/image-to-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 (720p when you leave it out) times duration (5 seconds when you leave it out). Higher resolutions cost more per second. The prompt, seed 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.

Authentication

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/vidu-q4/v1/reference-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 '{"prompt": "[@reference_image_1] walks slowly toward the camera and smiles.", "reference_image_urls": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg"], "duration": 5, "resolution": "720p", "aspect_ratio": "16:9"}'

Callback Payload (success)

{
  "request_id": "vidu-q4_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "vidu-q4",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-10-09T10:04:54.387Z",
  "completed_at": "2026-10-09 10:06:21"
}

Failure callback shape

{
  "request_id": "vidu-q4_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "vidu-q4",
  "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 with duration, in whole seconds from 3 to 16 (5 when you leave it out); seconds, num_frames, frames_per_second and music_length_ms are rejected.
• Set the resolution with resolution: 540p, 720p, 1080p, 2K or 4K, written exactly as listed (720p 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 1 to 12 reference images in reference_image_urls and refer to them in prompt by their position in the list ([@reference_image_1] is the first); image_url, image_urls, image, images and subjects are rejected.
• Omit a field instead of sending null; reference_image_urls must be non-empty URL strings.
• reference_audio_urls requires audio: true (it takes up to 3 mp3 clips).
• Use the JSON types shown: duration and seed are whole numbers (5, not "5"), and audio and enable_safety_checker are true or false, not strings.
• Results are always returned as a URL in output.media_url; sync_mode is accepted only as false.
• 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.
• Options this API does not offer are rejected: end_image_url, is_rec, off_peak, movement_amplitude, bgm, watermark, wm_position, wm_url, meta_data, voice_id, sounds, videos and reference_video_urls.

Length and Resolution

Set duration to the length you want in whole seconds, from 3 to 16; 5 applies when you leave it out. Set resolution to one of the values below; 720p applies when you leave it out. Billing is per second of the requested duration at the rate for the requested resolution, so a longer or higher-resolution video costs more.

Example: an 8-second video at 1080p

{
  "prompt": "[@reference_image_1] walks slowly toward the camera and smiles.",
  "reference_image_urls": [
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg"
  ],
  "duration": 8,
  "resolution": "1080p",
  "aspect_ratio": "16:9"
}

References

• Send 1 to 12 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.
• Optionally send up to 3 mp3 clips of 3 to 12 seconds each in reference_audio_urls; they need audio: true.
• Every input is downloaded when you submit. Very many or very large inputs may be refused at once with a 400, with nothing charged; so may a URL that cannot be downloaded.

Example: a portrait video

{
  "prompt": "[@reference_image_1] looks up at the falling snow and smiles.",
  "reference_image_urls": [
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg"
  ],
  "aspect_ratio": "9:16",
  "duration": 8,
  "resolution": "1080p"
}

Prompting Guide

• Refer to each reference by its position in its list: [@reference_image_1] is the first URL in reference_image_urls, [@reference_image_2] the second, and so on; [reference_audio_1] is the first clip in reference_audio_urls.
• Describe the action, the camera movement and the setting, and say which reference does what. The prompt is required and can be up to 5000 characters.

Example prompt with two references

[@reference_image_1] walks along the beach at sunset holding [@reference_image_2], then turns to the camera and smiles.

Aspect Ratio

Set aspect_ratio to 16:9, 9:16, 4:3, 3:4 or 1:1; 16:9 applies when you leave it out. It does not change the amount billed.

Audio

Set audio to true to request generated audio for the video; false applies when you leave it out. Turning audio on does not change the price. reference_audio_urls requires audio: true: a request with reference audio clips and audio left out or false is refused with a 400.

Example: turn audio on

{
  "prompt": "[@reference_image_1] waves and says hello.",
  "reference_image_urls": [
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/images/input.jpg"
  ],
  "audio": true,
  "duration": 5,
  "resolution": "720p"
}

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 so may be very many or very large inputs; the hold is then 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"
  ]
}

More than 12 reference images (synchronous 400)

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

A value that is not allowed (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'resolution' must be one of: \"540p\", \"720p\", \"1080p\", \"2K\", \"4K\" (got \"4k\")",
  "violations": [
    "'resolution' must be one of: \"540p\", \"720p\", \"1080p\", \"2K\", \"4K\" (got \"4k\")"
  ]
}

Reference audio without audio: true (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'reference_audio_urls' needs 'audio': true. Set 'audio': true, or remove 'reference_audio_urls'.",
  "violations": [
    "'reference_audio_urls' needs 'audio': true. Set 'audio': true, or remove 'reference_audio_urls'."
  ]
}

A field this operation does not accept (synchronous 400)

{
  "error": "Invalid request parameters",
  "message": "'num_images' must be one of:  (got 2); 'num_images' is not supported: Vidu Q4 returns one video per request. Send one request per video.",
  "violations": [
    "'num_images' must be one of:  (got 2)",
    "'num_images' is not supported: Vidu Q4 returns one video per request. Send one request per video."
  ]
}

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/vidu-q4_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY'

Completed response

{
  "request_id": "vidu-q4_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "vidu-q4",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-10-09T10:04:54.387Z",
  "completed_at": "2026-10-09 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/vidu-q4/v1/reference-to-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 (720p when you leave it out) times duration (5 seconds when you leave it out). Higher resolutions cost more per second. The prompt, seed, aspect ratio and safety setting do not change the amount. Turning audio on does not change the price. 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.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Add the X-Webhook-URL header to your submit request to receive a POST callback when the job completes — no polling required.

Using curl? These are HTTP request headers — pass each with -H, e.g. -H "X-Webhook-URL: https://your-server.com/webhook/callback". Do not paste them as bare lines, and end every line of a multi-line command with \.

Webhook Headers

Example: enable webhook

X-Webhook-URL: https://your-server.com/webhook/callback
X-Webhook-Mode: terminal

Callback Payload

Your endpoint receives a POST application/json with the same shape as the GET /v2/requests/status/{request_id} response. Example terminal callback (mode terminal):

{
  "request_id": "vidu-q3-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "vidu-q3-pro",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/vidu-q3-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-05-22T13:17:32.110Z",
  "updated_at": "2026-05-22 13:19:23",
  "completed_at": "2026-05-22 13:19:23"
}

Failure callback shape

{
  "request_id": "vidu-q3-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "vidu-q3-pro",
  "error": "Description of the error",
  "output": null,
  "created_at": "...",
  "updated_at": "...",
  "completed_at": "..."
}

Delivery semantics

• terminal mode (default) — exactly one POST when the request reaches a terminal status. No callback during PROCESSING.
• sync mode — POST on every status poll (with delay capped at ~15s) plus a final POST at terminal status. Use when you want progress updates.
• Idempotency — use request_id as your idempotency key. Network retries can deliver the same callback more than once; your handler must tolerate duplicates.
• Response — respond 200 OK within a few seconds. The queue does not block on slow handlers, but persistent failures may stop further deliveries.
• HTTPS required — plain http:// URLs are rejected.

Request Parameters - Text to Video

Request Headers

Response Handling

Common status codes.

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 'vidu-q3-pro' not found or is disabled"
}

Error via Status/Webhook

{
  "request_id": "vidu-q3-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "vidu-q3-pro",
  "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 -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/vidu-q3-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

{
  "request_id": "vidu-q3-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "vidu-q3-pro",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/vidu-q3-pro_019dxxxx-xxxx/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-04-07T10:00:00.000Z",
  "updated_at": "2026-04-07T10:02:30.000Z",
  "completed_at": "2026-04-07T10:02:30.000Z"
}

Response Fields

Status Values

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.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Add the X-Webhook-URL header to your submit request to receive a POST callback when the job completes — no polling required.

Using curl? These are HTTP request headers — pass each with -H, e.g. -H "X-Webhook-URL: https://your-server.com/webhook/callback". Do not paste them as bare lines, and end every line of a multi-line command with \.

Webhook Headers

Example: enable webhook

X-Webhook-URL: https://your-server.com/webhook/callback
X-Webhook-Mode: terminal

Callback Payload

Your endpoint receives a POST application/json with the same shape as the GET /v2/requests/status/{request_id} response. Example terminal callback (mode terminal):

{
  "request_id": "vidu-q3-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "vidu-q3-pro",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/vidu-q3-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-05-22T13:17:32.110Z",
  "updated_at": "2026-05-22 13:19:23",
  "completed_at": "2026-05-22 13:19:23"
}

Failure callback shape

{
  "request_id": "vidu-q3-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "vidu-q3-pro",
  "error": "Description of the error",
  "output": null,
  "created_at": "...",
  "updated_at": "...",
  "completed_at": "..."
}

Delivery semantics

• terminal mode (default) — exactly one POST when the request reaches a terminal status. No callback during PROCESSING.
• sync mode — POST on every status poll (with delay capped at ~15s) plus a final POST at terminal status. Use when you want progress updates.
• Idempotency — use request_id as your idempotency key. Network retries can deliver the same callback more than once; your handler must tolerate duplicates.
• Response — respond 200 OK within a few seconds. The queue does not block on slow handlers, but persistent failures may stop further deliveries.
• HTTPS required — plain http:// URLs are rejected.

Request Parameters - Image to Video

Content Item Types & Limits

Request Headers

Response Handling

Common status codes.

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 'vidu-q3-pro' not found or is disabled"
}

Error via Status/Webhook

{
  "request_id": "vidu-q3-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "vidu-q3-pro",
  "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 -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/vidu-q3-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

{
  "request_id": "vidu-q3-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "vidu-q3-pro",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/vidu-q3-pro_019dxxxx-xxxx/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-04-07T10:00:00.000Z",
  "updated_at": "2026-04-07T10:02:30.000Z",
  "completed_at": "2026-04-07T10:02:30.000Z"
}

Response Fields

Status Values

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.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Add the X-Webhook-URL header to your submit request to receive a POST callback when the job completes — no polling required.

Using curl? These are HTTP request headers — pass each with -H, e.g. -H "X-Webhook-URL: https://your-server.com/webhook/callback". Do not paste them as bare lines, and end every line of a multi-line command with \.

Webhook Headers

Example: enable webhook

X-Webhook-URL: https://your-server.com/webhook/callback
X-Webhook-Mode: terminal

Callback Payload

Your endpoint receives a POST application/json with the same shape as the GET /v2/requests/status/{request_id} response. Example terminal callback (mode terminal):

{
  "request_id": "vidu-q3-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "vidu-q3-pro",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/vidu-q3-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-05-22T13:17:32.110Z",
  "updated_at": "2026-05-22 13:19:23",
  "completed_at": "2026-05-22 13:19:23"
}

Failure callback shape

{
  "request_id": "vidu-q3-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "vidu-q3-pro",
  "error": "Description of the error",
  "output": null,
  "created_at": "...",
  "updated_at": "...",
  "completed_at": "..."
}

Delivery semantics

• terminal mode (default) — exactly one POST when the request reaches a terminal status. No callback during PROCESSING.
• sync mode — POST on every status poll (with delay capped at ~15s) plus a final POST at terminal status. Use when you want progress updates.
• Idempotency — use request_id as your idempotency key. Network retries can deliver the same callback more than once; your handler must tolerate duplicates.
• Response — respond 200 OK within a few seconds. The queue does not block on slow handlers, but persistent failures may stop further deliveries.
• HTTPS required — plain http:// URLs are rejected.

Request Parameters - Start / End Frame to Video

Content Item Types & Limits

Request Headers

Response Handling

Common status codes.

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 'vidu-q3-pro' not found or is disabled"
}

Error via Status/Webhook

{
  "request_id": "vidu-q3-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "vidu-q3-pro",
  "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 -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/vidu-q3-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

{
  "request_id": "vidu-q3-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "vidu-q3-pro",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/vidu-q3-pro_019dxxxx-xxxx/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-04-07T10:00:00.000Z",
  "updated_at": "2026-04-07T10:02:30.000Z",
  "completed_at": "2026-04-07T10:02:30.000Z"
}

Response Fields

Status Values

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.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Add the X-Webhook-URL header to your submit request to receive a POST callback when the job completes — no polling required.

Using curl? These are HTTP request headers — pass each with -H, e.g. -H "X-Webhook-URL: https://your-server.com/webhook/callback". Do not paste them as bare lines, and end every line of a multi-line command with \.

Webhook Headers

Example: enable webhook

X-Webhook-URL: https://your-server.com/webhook/callback
X-Webhook-Mode: terminal

Callback Payload

Your endpoint receives a POST application/json with the same shape as the GET /v2/requests/status/{request_id} response. Example terminal callback (mode terminal):

{
  "request_id": "vidu-q3-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "vidu-q3-turbo",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/vidu-q3-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-05-22T13:17:32.110Z",
  "updated_at": "2026-05-22 13:19:23",
  "completed_at": "2026-05-22 13:19:23"
}

Failure callback shape

{
  "request_id": "vidu-q3-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "vidu-q3-turbo",
  "error": "Description of the error",
  "output": null,
  "created_at": "...",
  "updated_at": "...",
  "completed_at": "..."
}

Delivery semantics

• terminal mode (default) — exactly one POST when the request reaches a terminal status. No callback during PROCESSING.
• sync mode — POST on every status poll (with delay capped at ~15s) plus a final POST at terminal status. Use when you want progress updates.
• Idempotency — use request_id as your idempotency key. Network retries can deliver the same callback more than once; your handler must tolerate duplicates.
• Response — respond 200 OK within a few seconds. The queue does not block on slow handlers, but persistent failures may stop further deliveries.
• HTTPS required — plain http:// URLs are rejected.

Request Parameters - Text to Video

Request Headers

Response Handling

Common status codes.

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 'vidu-q3-turbo' not found or is disabled"
}

Error via Status/Webhook

{
  "request_id": "vidu-q3-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "vidu-q3-turbo",
  "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 -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/vidu-q3-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

{
  "request_id": "vidu-q3-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "vidu-q3-turbo",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/vidu-q3-turbo_019dxxxx-xxxx/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-04-07T10:00:00.000Z",
  "updated_at": "2026-04-07T10:02:30.000Z",
  "completed_at": "2026-04-07T10:02:30.000Z"
}

Response Fields

Status Values

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.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Add the X-Webhook-URL header to your submit request to receive a POST callback when the job completes — no polling required.

Using curl? These are HTTP request headers — pass each with -H, e.g. -H "X-Webhook-URL: https://your-server.com/webhook/callback". Do not paste them as bare lines, and end every line of a multi-line command with \.

Webhook Headers

Example: enable webhook

X-Webhook-URL: https://your-server.com/webhook/callback
X-Webhook-Mode: terminal

Callback Payload

Your endpoint receives a POST application/json with the same shape as the GET /v2/requests/status/{request_id} response. Example terminal callback (mode terminal):

{
  "request_id": "vidu-q3-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "vidu-q3-turbo",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/vidu-q3-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-05-22T13:17:32.110Z",
  "updated_at": "2026-05-22 13:19:23",
  "completed_at": "2026-05-22 13:19:23"
}

Failure callback shape

{
  "request_id": "vidu-q3-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "vidu-q3-turbo",
  "error": "Description of the error",
  "output": null,
  "created_at": "...",
  "updated_at": "...",
  "completed_at": "..."
}

Delivery semantics

• terminal mode (default) — exactly one POST when the request reaches a terminal status. No callback during PROCESSING.
• sync mode — POST on every status poll (with delay capped at ~15s) plus a final POST at terminal status. Use when you want progress updates.
• Idempotency — use request_id as your idempotency key. Network retries can deliver the same callback more than once; your handler must tolerate duplicates.
• Response — respond 200 OK within a few seconds. The queue does not block on slow handlers, but persistent failures may stop further deliveries.
• HTTPS required — plain http:// URLs are rejected.

Request Parameters - Image to Video

Content Item Types & Limits

Request Headers

Response Handling

Common status codes.

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 'vidu-q3-turbo' not found or is disabled"
}

Error via Status/Webhook

{
  "request_id": "vidu-q3-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "vidu-q3-turbo",
  "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 -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/vidu-q3-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

{
  "request_id": "vidu-q3-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "vidu-q3-turbo",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/vidu-q3-turbo_019dxxxx-xxxx/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-04-07T10:00:00.000Z",
  "updated_at": "2026-04-07T10:02:30.000Z",
  "completed_at": "2026-04-07T10:02:30.000Z"
}

Response Fields

Status Values

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.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Add the X-Webhook-URL header to your submit request to receive a POST callback when the job completes — no polling required.

Using curl? These are HTTP request headers — pass each with -H, e.g. -H "X-Webhook-URL: https://your-server.com/webhook/callback". Do not paste them as bare lines, and end every line of a multi-line command with \.

Webhook Headers

Example: enable webhook

X-Webhook-URL: https://your-server.com/webhook/callback
X-Webhook-Mode: terminal

Callback Payload

Your endpoint receives a POST application/json with the same shape as the GET /v2/requests/status/{request_id} response. Example terminal callback (mode terminal):

{
  "request_id": "vidu-q3-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "vidu-q3-turbo",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/vidu-q3-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-05-22T13:17:32.110Z",
  "updated_at": "2026-05-22 13:19:23",
  "completed_at": "2026-05-22 13:19:23"
}

Failure callback shape

{
  "request_id": "vidu-q3-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "vidu-q3-turbo",
  "error": "Description of the error",
  "output": null,
  "created_at": "...",
  "updated_at": "...",
  "completed_at": "..."
}

Delivery semantics

• terminal mode (default) — exactly one POST when the request reaches a terminal status. No callback during PROCESSING.
• sync mode — POST on every status poll (with delay capped at ~15s) plus a final POST at terminal status. Use when you want progress updates.
• Idempotency — use request_id as your idempotency key. Network retries can deliver the same callback more than once; your handler must tolerate duplicates.
• Response — respond 200 OK within a few seconds. The queue does not block on slow handlers, but persistent failures may stop further deliveries.
• HTTPS required — plain http:// URLs are rejected.

Request Parameters - Reference to Video

Content Item Types & Limits

Request Headers

Response Handling

Common status codes.

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 'vidu-q3-turbo' not found or is disabled"
}

Error via Status/Webhook

{
  "request_id": "vidu-q3-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "vidu-q3-turbo",
  "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 -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/vidu-q3-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

{
  "request_id": "vidu-q3-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "vidu-q3-turbo",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/vidu-q3-turbo_019dxxxx-xxxx/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-04-07T10:00:00.000Z",
  "updated_at": "2026-04-07T10:02:30.000Z",
  "completed_at": "2026-04-07T10:02:30.000Z"
}

Response Fields

Status Values

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.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Add the X-Webhook-URL header to your submit request to receive a POST callback when the job completes — no polling required.

Using curl? These are HTTP request headers — pass each with -H, e.g. -H "X-Webhook-URL: https://your-server.com/webhook/callback". Do not paste them as bare lines, and end every line of a multi-line command with \.

Webhook Headers

Example: enable webhook

X-Webhook-URL: https://your-server.com/webhook/callback
X-Webhook-Mode: terminal

Callback Payload

Your endpoint receives a POST application/json with the same shape as the GET /v2/requests/status/{request_id} response. Example terminal callback (mode terminal):

{
  "request_id": "vidu_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "vidu",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/vidu_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-05-22T13:17:32.110Z",
  "updated_at": "2026-05-22 13:19:23",
  "completed_at": "2026-05-22 13:19:23"
}

Failure callback shape

{
  "request_id": "vidu_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "vidu",
  "error": "Description of the error",
  "output": null,
  "created_at": "...",
  "updated_at": "...",
  "completed_at": "..."
}

Delivery semantics

• terminal mode (default) — exactly one POST when the request reaches a terminal status. No callback during PROCESSING.
• sync mode — POST on every status poll (with delay capped at ~15s) plus a final POST at terminal status. Use when you want progress updates.
• Idempotency — use request_id as your idempotency key. Network retries can deliver the same callback more than once; your handler must tolerate duplicates.
• Response — respond 200 OK within a few seconds. The queue does not block on slow handlers, but persistent failures may stop further deliveries.
• HTTPS required — plain http:// URLs are rejected.

Request Parameters - Vidu generate request

Response

{
  "request_id": "vidu_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/vidu_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Request Headers

Response Handling

Common status codes for Vidu generate request.

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 'vidu' not found or is disabled"
}

Error via Status/Webhook

{
  "request_id": "vidu_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "vidu",
  "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 -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/vidu_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

{
  "request_id": "vidu_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "vidu",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/vidu_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

Status Values

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.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Add the X-Webhook-URL header to your submit request to receive a POST callback when the job completes — no polling required.

Using curl? These are HTTP request headers — pass each with -H, e.g. -H "X-Webhook-URL: https://your-server.com/webhook/callback". Do not paste them as bare lines, and end every line of a multi-line command with \.

Webhook Headers

Example: enable webhook

X-Webhook-URL: https://your-server.com/webhook/callback
X-Webhook-Mode: terminal

Callback Payload

Your endpoint receives a POST application/json with the same shape as the GET /v2/requests/status/{request_id} response. Example terminal callback (mode terminal):

{
  "request_id": "vidu-q2-reference-to-video-pro-api-454_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "vidu-q2-reference-to-video-pro-api-454",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/vidu-q2-reference-to-video-pro-api-454_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-05-22T13:17:32.110Z",
  "updated_at": "2026-05-22 13:19:23",
  "completed_at": "2026-05-22 13:19:23"
}

Failure callback shape

{
  "request_id": "vidu-q2-reference-to-video-pro-api-454_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "vidu-q2-reference-to-video-pro-api-454",
  "error": "Description of the error",
  "output": null,
  "created_at": "...",
  "updated_at": "...",
  "completed_at": "..."
}

Delivery semantics

• terminal mode (default) — exactly one POST when the request reaches a terminal status. No callback during PROCESSING.
• sync mode — POST on every status poll (with delay capped at ~15s) plus a final POST at terminal status. Use when you want progress updates.
• Idempotency — use request_id as your idempotency key. Network retries can deliver the same callback more than once; your handler must tolerate duplicates.
• Response — respond 200 OK within a few seconds. The queue does not block on slow handlers, but persistent failures may stop further deliveries.
• HTTPS required — plain http:// URLs are rejected.

Request Parameters - Vidu Q2 Reference to Video Pro API generate request

Content Item Types & Limits

Request Headers

Response Handling

Common status codes.

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 'vidu-q2-reference-to-video-pro-api-454' not found or is disabled"
}

Error via Status/Webhook

{
  "request_id": "vidu-q2-reference-to-video-pro-api-454_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "vidu-q2-reference-to-video-pro-api-454",
  "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 -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/vidu-q2-reference-to-video-pro-api-454_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

{
  "request_id": "vidu-q2-reference-to-video-pro-api-454_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "vidu-q2-reference-to-video-pro-api-454",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/vidu-q2-reference-to-video-pro-api-454_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

Status Values

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.