# Vidu Video API

> Provider: **Vidu**
> Source: https://www.pixazo.ai/models/vidu

Advanced video generation.

## Vidu Q3

### Text to Video

## Base URL

```
https://gateway.pixazo.ai/vidu/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Vidu generate request - Vidu

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/vidu/v1/vidu-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "prompt": "A slow-motion capture of a hummingbird hovering beside a vibrant red hibiscus flower, iridescent feathers catching sunlight, shallow depth of field, garden background",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "audio": true
}
```

```
import requests

url = "https://gateway.pixazo.ai/vidu/v1/vidu-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "prompt": "A slow-motion capture of a hummingbird hovering beside a vibrant red hibiscus flower, iridescent feathers catching sunlight, shallow depth of field, garden background",
    "duration": 5,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "audio": True
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

```
const url = 'https://gateway.pixazo.ai/vidu/v1/vidu-request';

const data = {
  prompt: 'A slow-motion capture of a hummingbird hovering beside a vibrant red hibiscus flower, iridescent feathers catching sunlight, shallow depth of field, garden background',
  duration: 5,
  aspect_ratio: '16:9',
  resolution: '720p',
  audio: true
};

fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Cache-Control': 'no-cache',
    'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

```
curl -X POST "https://gateway.pixazo.ai/vidu/v1/vidu-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
    "prompt": "A slow-motion capture of a hummingbird hovering beside a vibrant red hibiscus flower, iridescent feathers catching sunlight, shallow depth of field, garden background",
    "duration": 5,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "audio": true
}'
```

## Output

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

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

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

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

## Request Parameters - Vidu generate request

Field

Type

Required

Default

Description

prompt

string

Yes

—

Detailed text description of the desired video scene

duration

integer

Yes

—

Duration of the generated video in seconds (recommended: 3–10)

aspect\_ratio

string

Yes

—

Video aspect ratio: "16:9", "9:16", "1:1", "4:3", or "3:4"

resolution

string

Yes

—

Output resolution: "720p", "1080p", or "4K"

audio

boolean

Yes

—

Whether to generate synchronized audio with the video

## Minimum Request

```
{
  "prompt": "A slow-motion capture of a hummingbird hovering beside a vibrant red hibiscus flower, iridescent feathers catching sunlight, shallow depth of field, garden background",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "audio": true
}
```

## Full Request (all options)

```
{
  "prompt": "A slow-motion capture of a hummingbird hovering beside a vibrant red hibiscus flower, iridescent feathers catching sunlight, shallow depth of field, garden background",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "audio": true
}
```

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

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

Your API subscription key

## Response Handling

Common status codes for Vidu generate request.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

429

Too Many Requests

500

Internal Server Error

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model '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 Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/vidu_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

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

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type of the output

created\_at

string

When request was created

completed\_at

string|null

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

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

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

## Vidu v1

### Image to Image (Image Background Remover)

## Base URL

```
https://gateway.pixazo.ai/vidu-q2-reference-to-video-pro-api-454/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Vidu Q2 Reference to Video Pro API generate request - Vidu Q2 Reference to Video Pro API

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/vidu-q2-reference-to-video-pro-api-454/v1/vidu-q2-reference-to-video-pro-api-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "prompt": "@Figure 1 Character Reference@Refer to the special effects, movements, and camera work of Video 1.",
  "reference_image_urls": [
    "https://storage.googleapis.com/falserverless/model_tests/video_models/vidu-image-3123041388101890.png"
  ],
  "reference_video_urls": [
    "https://storage.googleapis.com/falserverless/model_tests/video_models/vidu-video-3123002003131623.mp4"
  ],
  "duration": 4,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "movement_amplitude": "auto"
}
```

```
import requests

url = "https://gateway.pixazo.ai/vidu-q2-reference-to-video-pro-api-454/v1/vidu-q2-reference-to-video-pro-api-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "prompt": "@Figure 1 Character Reference@Refer to the special effects, movements, and camera work of Video 1.",
    "reference_image_urls": [
        "https://storage.googleapis.com/falserverless/model_tests/video_models/vidu-image-3123041388101890.png"
    ],
    "reference_video_urls": [
        "https://storage.googleapis.com/falserverless/model_tests/video_models/vidu-video-3123002003131623.mp4"
    ],
    "duration": 4,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "movement_amplitude": "auto"
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

```
const url = 'https://gateway.pixazo.ai/vidu-q2-reference-to-video-pro-api-454/v1/vidu-q2-reference-to-video-pro-api-request';

const data = {
  prompt: '@Figure 1 Character Reference@Refer to the special effects, movements, and camera work of Video 1.',
  reference_image_urls: [
    'https://storage.googleapis.com/falserverless/model_tests/video_models/vidu-image-3123041388101890.png'
  ],
  reference_video_urls: [
    'https://storage.googleapis.com/falserverless/model_tests/video_models/vidu-video-3123002003131623.mp4'
  ],
  duration: 4,
  resolution: '720p',
  aspect_ratio: '16:9',
  movement_amplitude: 'auto'
};

fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Cache-Control': 'no-cache',
    'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

```
curl -X POST "https://gateway.pixazo.ai/vidu-q2-reference-to-video-pro-api-454/v1/vidu-q2-reference-to-video-pro-api-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
    "prompt": "@Figure 1 Character Reference@Refer to the special effects, movements, and camera work of Video 1.",
    "reference_image_urls": [
      "https://storage.googleapis.com/falserverless/model_tests/video_models/vidu-image-3123041388101890.png"
    ],
    "reference_video_urls": [
      "https://storage.googleapis.com/falserverless/model_tests/video_models/vidu-video-3123002003131623.mp4"
    ],
    "duration": 4,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "movement_amplitude": "auto"
  }'
```

## Output

```
{
  "request_id": "vidu-q2-reference-to-video-pro-api-454_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/vidu-q2-reference-to-video-pro-api-454_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=vidu-q2-reference-to-video-pro-api-454&operation=vidu-q2-reference-to-video-pro-api-request)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

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

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

Parameter

Required

Type

Description

prompt

Yes

string

A descriptive text prompt that defines the desired action, scene, or context, while referencing the style and motion from the provided reference video. Use \`@Figure X Character Reference@\` syntax to explicitly link character identities to reference imagery.

reference\_image\_urls

Yes

array of strings

Array of HTTPS URLs pointing to static reference images used to define character appearance, clothing, or static scene context. Each URL must be publicly accessible.

reference\_video\_urls

Yes

array of strings

Array of HTTPS URLs pointing to reference video clips that define motion patterns, camera movement, lighting transitions, and special effects to be replicated. Must be MP4 format.

duration

Optional

integer

Duration of the output video in seconds. Must be between 1 and 10.

resolution

Optional

string

Output video resolution. Supported values: "480p", "720p", "1080p".

aspect\_ratio

Optional

string

Output video aspect ratio. Supported values: "16:9", "9:16", "1:1".

movement\_amplitude

Optional

string

Controls the intensity of motion reproduction from reference video. Values: "low", "medium", "high", "auto". "auto" enables dynamic adaptation based on reference content.

## Example Request

```
{
  "prompt": "@Figure 1 Character Reference@Refer to the special effects, movements, and camera work of Video 1.",
  "reference_image_urls": [
    "https://storage.googleapis.com/falserverless/model_tests/video_models/vidu-image-3123041388101890.png"
  ],
  "reference_video_urls": [
    "https://storage.googleapis.com/falserverless/model_tests/video_models/vidu-video-3123002003131623.mp4"
  ],
  "duration": 4,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "movement_amplitude": "auto"
}
```

## Response

```
{
  "request_id": "vidu-q2-reference-to-video-pro-api-454_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/vidu-q2-reference-to-video-pro-api-454_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_SUBSCRIPTION\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model '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 Example

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

## Response (Completed)

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

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type of the output

created\_at

string

When request was created

completed\_at

string|null

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

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

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