# Pixverse Video API

> Provider: **Pixverse**
> Source: https://www.pixazo.ai/models/pixverse

Pixverse Video API by Pixverse.

## Pixverse v6

### Text to Video

## Base URL

```
https://gateway.pixazo.ai/pixverse-v6-text-to-video/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

## PixVerse v6 Text to Video generate request

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/pixverse-v6-text-to-video/v1/pixverse-v6-text-to-video-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_API_KEY

{
  "prompt": "A cat sitting by a window watching birds outside, warm afternoon sunlight, cinematic",
  "negative_prompt": "blurry, low quality, pixelated",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5,
  "style": "cyberpunk",
  "generate_audio_switch": true
}
```

```
import requests

url = "https://gateway.pixazo.ai/pixverse-v6-text-to-video/v1/pixverse-v6-text-to-video-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
data = {
    "prompt": "A cat sitting by a window watching birds outside, warm afternoon sunlight, cinematic",
    "negative_prompt": "blurry, low quality, pixelated",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 5,
    "style": "cyberpunk",
    "generate_audio_switch": true
}

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

```
const url = "https://gateway.pixazo.ai/pixverse-v6-text-to-video/v1/pixverse-v6-text-to-video-request";
const headers = {
  "Content-Type": "application/json",
  "Cache-Control": "no-cache",
  "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
};
const data = {
  "prompt": "A cat sitting by a window watching birds outside, warm afternoon sunlight, cinematic",
  "negative_prompt": "blurry, low quality, pixelated",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5,
  "style": "cyberpunk",
  "generate_audio_switch": true
};

fetch(url, {
  method: "POST",
  headers: headers,
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));
```

```
curl -X POST "https://gateway.pixazo.ai/pixverse-v6-text-to-video/v1/pixverse-v6-text-to-video-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  --data-raw '{
    "prompt": "A cat sitting by a window watching birds outside, warm afternoon sunlight, cinematic",
    "negative_prompt": "blurry, low quality, pixelated",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 5,
    "style": "cyberpunk",
    "generate_audio_switch": true
}'
```

## Output

```
{
  "request_id": "pixverse-v6-text-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/pixverse-v6-text-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=pixverse-v6-text-to-video&operation=pixverse-v6-text-to-video-request)

## Webhook (Optional)

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

### Webhook Headers

Header

Required

Default

Description

`X-Webhook-URL`

Yes (to enable)

—

HTTPS endpoint on your server that will receive the `POST` callback. Must respond `2xx` within a few seconds (process async if needed).

`X-Webhook-Mode`

No

`terminal`

`terminal` — fires once at the final status (`COMPLETED`/`FAILED`/`ERROR`). `sync` — fires on every poll cycle plus the terminal event, and caps the queue’s polling delay at **15s** for tighter progress updates.

### 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": "pixverse-v6-text-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "pixverse-v6-text-to-video",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/pixverse-v6-text-to-video_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": "pixverse-v6-text-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "pixverse-v6-text-to-video",
  "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 - PixVerse v6 Text to Video generate request

Parameter

Required

Type

Default

Allowed values / range

Description

prompt

Yes

string

—

—

Text description of the video to generate. Must be detailed for best results.

negative\_prompt

No

string

""

—

Terms to exclude from the generated video. Use to refine output quality.

aspect\_ratio

No

enum

"16:9"

"16:9", "4:3", "1:1", "3:4", "9:16", "2:3", "3:2", "21:9"

Video aspect ratio.

resolution

No

enum

"720p"

"360p", "540p", "720p", "1080p"

Output video resolution.

duration

No

integer

5

1–15 (seconds)

Length of the video in seconds. Must be between 1 and 15 inclusive.

style

No

enum

—

"anime", "3d\_animation", "clay", "comic", "cyberpunk"

Visual style of the video.

seed

No

integer

—

—

Random seed for reproducible results. Use the same seed to regenerate identical outputs.

generate\_audio\_switch

No

boolean

false

—

Enable generation of background music (BGM), sound effects (SFX), and dialogue alongside the video.

generate\_multi\_clip\_switch

No

boolean

false

—

Enable dynamic camera transitions and multi-clip output for more complex, cinematic sequences.

thinking\_type

No

enum

—

"enabled", "disabled", "auto"

Prompt optimization mode.

## Example Request

```
{
  "prompt": "A cat sitting by a window watching birds outside, warm afternoon sunlight, cinematic",
  "negative_prompt": "blurry, low quality, pixelated",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5,
  "style": "cyberpunk",
  "generate_audio_switch": true
}
```

## Response

```
{
  "request_id": "pixverse-v6-text-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/pixverse-v6-text-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_API\_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 'pixverse-v6-text-to-video' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "pixverse-v6-text-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "pixverse-v6-text-to-video",
  "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/pixverse-v6-text-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "pixverse-v6-text-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "pixverse-v6-text-to-video",
  "error": null,
  "output": { "media_url": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/pixverse-v6-text-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.mp4"], "media_type": "video/mp4" },
  "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

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.

### Image to Video

## Base URL

```
https://gateway.pixazo.ai/pixverse-v6-image-to-video/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

## PixVerse V6 Image to Video generate request - PixVerse V6 Image to Video

## Request Code

HTTP Python JavaScript cURL

```
POST /pixverse-v6-image-to-video-request HTTP/1.1
Host: gateway.pixazo.ai
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "prompt": "A gentle snowfall begins around the snow-covered tree, with soft flakes drifting down while the branches sway slightly in the winter breeze. The camera slowly orbits the tree, cinematic, peaceful winter atmosphere.",
  "resolution": "720p",
  "duration": 5,
  "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/f1.png"
}
```

```
import requests

url = "https://gateway.pixazo.ai/pixverse-v6-image-to-video/v1/pixverse-v6-image-to-video-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "prompt": "A gentle snowfall begins around the snow-covered tree, with soft flakes drifting down while the branches sway slightly in the winter breeze. The camera slowly orbits the tree, cinematic, peaceful winter atmosphere.",
    "resolution": "720p",
    "duration": 5,
    "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/f1.png"
}

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

```
const url = 'https://gateway.pixazo.ai/pixverse-v6-image-to-video/v1/pixverse-v6-image-to-video-request';

const data = {
  prompt: 'A gentle snowfall begins around the snow-covered tree, with soft flakes drifting down while the branches sway slightly in the winter breeze. The camera slowly orbits the tree, cinematic, peaceful winter atmosphere.',
  resolution: '720p',
  duration: 5,
  image_url: 'https://pub-582b7213209642b9b995c96c95a30381.r2.dev/f1.png'
};

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/pixverse-v6-image-to-video/v1/pixverse-v6-image-to-video-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
    "prompt": "A gentle snowfall begins around the snow-covered tree, with soft flakes drifting down while the branches sway slightly in the winter breeze. The camera slowly orbits the tree, cinematic, peaceful winter atmosphere.",
    "resolution": "720p",
    "duration": 5,
    "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/f1.png"
  }'
```

## Output

```
{
  "request_id": "pixverse-v6-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/pixverse-v6-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

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

## Webhook (Optional)

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

### Webhook Headers

Header

Required

Default

Description

`X-Webhook-URL`

Yes (to enable)

—

HTTPS endpoint on your server that will receive the `POST` callback. Must respond `2xx` within a few seconds (process async if needed).

`X-Webhook-Mode`

No

`terminal`

`terminal` — fires once at the final status (`COMPLETED`/`FAILED`/`ERROR`). `sync` — fires on every poll cycle plus the terminal event, and caps the queue’s polling delay at **15s** for tighter progress updates.

### 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": "pixverse-v6-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "pixverse-v6-image-to-video",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/pixverse-v6-image-to-video_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": "pixverse-v6-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "pixverse-v6-image-to-video",
  "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 - PixVerse V6 Image to Video generate request

Parameter

Required

Type

Default

Allowed values / range

Description

prompt

Yes

string

—

—

A detailed text description of the desired video motion and atmosphere. Include camera movement, lighting, and mood.

resolution

No

string

720p

\`360p\`, \`480p\`, \`720p\`, \`1080p\`

Output video resolution. Supported values: \`360p\`, \`480p\`, \`720p\`, \`1080p\`.

duration

No

integer

5

1–15

Duration of the generated video in seconds. Must be between 1 and 15 inclusive.

negative\_prompt

No

string

—

—

Describes undesired elements to exclude from the output. Helps refine quality and avoid artifacts.

image\_url

Yes

string

—

—

Publicly accessible URL of the input image. Must be a valid HTTP/HTTPS link to a JPEG, PNG, or WebP image.

style

No

string

—

anime , 3d\_animation , clay , comic , cyberpunk

The style of the generated video. Supported values: `anime`, `3d_animation`, `clay`, `comic`, `cyberpunk`

seed

No

integer

—

—

Random seed for reproducible generation. Same seed + same prompt = same output

generate\_audio\_switch

No

boolean

false

true, false

Enable audio generation (BGM, SFX, dialogue). Increases cost per second

generate\_multi\_clip\_switch

No

boolean

false

true, false

Enable multi-clip generation with dynamic camera changes

thinking\_type

No

string

auto

enabled (optimize), disabled (turn off), auto (model decision)

Prompt optimization mode. Supported values: `enabled` (optimize), `disabled` (turn off), `auto` (model decision)

## Minimum Request

```
{
  "prompt": "A gentle snowfall begins around the snow-covered tree, with soft flakes drifting down while the branches sway slightly in the winter breeze. The camera slowly orbits the tree, cinematic, peaceful winter atmosphere.",
  "resolution": "720p",
  "duration": 5,
  "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/f1.png"
}
```

## Full Request (all options)

```
{
  "prompt": "A gentle snowfall begins around the snow-covered tree, with soft flakes drifting down while the branches sway slightly in the winter breeze. The camera slowly orbits the tree, cinematic, peaceful winter atmosphere.",
  "resolution": "720p",
  "duration": 5,
  "negative_prompt": "blurry, low quality, low resolution, pixelated, noisy, grainy, out of focus, poorly lit, poorly exposed, poorly composed, poorly framed, poorly cropped, poorly color corrected, poorly color graded",
  "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/f1.png"
}
```

## Response

```
{
  "request_id": "pixverse-v6-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/pixverse-v6-image-to-video_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 for PixVerse V6 Image to Video 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 'pixverse-v6-image-to-video' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "pixverse-v6-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "pixverse-v6-image-to-video",
  "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/pixverse-v6-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "pixverse-v6-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "pixverse-v6-image-to-video",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/pixverse-v6-image-to-video_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.

## Pixverse c1

### Text to Video

## Base URL

```
https://gateway.pixazo.ai/pixverse-c1-text-to-video/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

## PixVerse C1 Text to Video generate request

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/pixverse-c1-text-to-video/v1/pixverse-c1-text-to-video-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_API_KEY

{
  "prompt": "A cat sitting by a window watching birds outside, warm afternoon sunlight, cinematic",
  "negative_prompt": "blurry, low quality, pixelated",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5,
  "style": "cyberpunk",
  "generate_audio_switch": true
}
```

```
import requests

url = "https://gateway.pixazo.ai/pixverse-c1-text-to-video/v1/pixverse-c1-text-to-video-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
data = {
    "prompt": "A cat sitting by a window watching birds outside, warm afternoon sunlight, cinematic",
    "negative_prompt": "blurry, low quality, pixelated",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 5,
    "style": "cyberpunk",
    "generate_audio_switch": true
}

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

```
const url = "https://gateway.pixazo.ai/pixverse-c1-text-to-video/v1/pixverse-c1-text-to-video-request";
const headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
};
const data = {
    "prompt": "A cat sitting by a window watching birds outside, warm afternoon sunlight, cinematic",
    "negative_prompt": "blurry, low quality, pixelated",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 5,
    "style": "cyberpunk",
    "generate_audio_switch": true
};

fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error("Error:", error));
```

```
curl -X POST "https://gateway.pixazo.ai/pixverse-c1-text-to-video/v1/pixverse-c1-text-to-video-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  --data-raw '{
    "prompt": "A cat sitting by a window watching birds outside, warm afternoon sunlight, cinematic",
    "negative_prompt": "blurry, low quality, pixelated",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 5,
    "style": "cyberpunk",
    "generate_audio_switch": true
}'
```

## Output

```
{
  "request_id": "pixverse-c1-text-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/pixverse-c1-text-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=pixverse-c1-text-to-video&operation=pixverse-c1-text-to-video-request)

## Webhook (Optional)

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

### Webhook Headers

Header

Required

Default

Description

`X-Webhook-URL`

Yes (to enable)

—

HTTPS endpoint on your server that will receive the `POST` callback. Must respond `2xx` within a few seconds (process async if needed).

`X-Webhook-Mode`

No

`terminal`

`terminal` — fires once at the final status (`COMPLETED`/`FAILED`/`ERROR`). `sync` — fires on every poll cycle plus the terminal event, and caps the queue’s polling delay at **15s** for tighter progress updates.

### 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": "pixverse-c1-text-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "pixverse-c1-text-to-video",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/pixverse-c1-text-to-video_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": "pixverse-c1-text-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "pixverse-c1-text-to-video",
  "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 - PixVerse C1 Text to Video generate request

Parameter

Required

Type

Default

Allowed values / range

Description

prompt

Yes

string

—

—

Text description of the video to generate. Must be detailed for best results.

negative\_prompt

No

string

""

—

Terms to exclude from the generated video. Example: "blurry, low quality, pixelated".

aspect\_ratio

No

enum

"16:9"

"16:9", "4:3", "1:1", "3:4", "9:16", "2:3", "3:2", "21:9"

Video aspect ratio.

resolution

No

enum

"720p"

"360p", "540p", "720p", "1080p"

Output video resolution. Pricing varies by resolution.

duration

No

integer

5

1–15 (seconds)

Length of the video in seconds. Must be between 1 and 15 inclusive.

style

No

enum

—

"anime", "3d\_animation", "clay", "comic", "cyberpunk"

Visual style of the video.

seed

No

integer

—

—

Random seed for reproducible results. Use the same seed to generate identical outputs.

generate\_audio\_switch

No

boolean

false

—

Enable generation of native audio including background music, sound effects, and dialogue.

generate\_multi\_clip\_switch

No

boolean

false

—

Enable dynamic multi-clip output with automated camera transitions between scenes.

thinking\_type

No

enum

—

"enabled", "disabled", "auto"

Prompt optimization mode.

## Example Request

```
{
  "prompt": "A cat sitting by a window watching birds outside, warm afternoon sunlight, cinematic",
  "negative_prompt": "blurry, low quality, pixelated",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5,
  "style": "cyberpunk",
  "generate_audio_switch": true
}
```

## Response

```
{
  "request_id": "pixverse-c1-text-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/pixverse-c1-text-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_API\_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 'pixverse-c1-text-to-video' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "pixverse-c1-text-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "pixverse-c1-text-to-video",
  "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/pixverse-c1-text-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "pixverse-c1-text-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "pixverse-c1-text-to-video",
  "error": null,
  "output": {
    "media_url": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/pixverse-c1-text-to-video_019dxxxx/output.mp4"],
    "media_type": "video/mp4"
  },
  "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

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.

### Image to Video

## Base URL

```
https://gateway.pixazo.ai/pixverse-c1-image-to-video/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

## PixVerse C1 Image to Video generate request

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/pixverse-c1-image-to-video/v1/pixverse-c1-image-to-video-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_API_KEY

{
  "prompt": "A woman warrior with her hammer walking with her glacier wolf, cinematic camera move",
  "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/Image.jpeg",
  "resolution": "720p",
  "duration": 5,
  "generate_audio_switch": true
}
```

```
import requests

url = "https://gateway.pixazo.ai/pixverse-c1-image-to-video/v1/pixverse-c1-image-to-video-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
data = {
    "prompt": "A woman warrior with her hammer walking with her glacier wolf, cinematic camera move",
    "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/Image.jpeg",
    "resolution": "720p",
    "duration": 5,
    "generate_audio_switch": true
}

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

```
const url = "https://gateway.pixazo.ai/pixverse-c1-image-to-video/v1/pixverse-c1-image-to-video-request";
const headers = {
  "Content-Type": "application/json",
  "Cache-Control": "no-cache",
  "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
};
const data = {
  "prompt": "A woman warrior with her hammer walking with her glacier wolf, cinematic camera move",
  "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/Image.jpeg",
  "resolution": "720p",
  "duration": 5,
  "generate_audio_switch": true
};

fetch(url, {
  method: "POST",
  headers: headers,
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));
```

```
curl -X POST "https://gateway.pixazo.ai/pixverse-c1-image-to-video/v1/pixverse-c1-image-to-video-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  --data-raw '{
    "prompt": "A woman warrior with her hammer walking with her glacier wolf, cinematic camera move",
    "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/Image.jpeg",
    "resolution": "720p",
    "duration": 5,
    "generate_audio_switch": true
  }'
```

## Output

```
{
  "request_id": "pixverse-c1-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/pixverse-c1-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

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

## Webhook (Optional)

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

### Webhook Headers

Header

Required

Default

Description

`X-Webhook-URL`

Yes (to enable)

—

HTTPS endpoint on your server that will receive the `POST` callback. Must respond `2xx` within a few seconds (process async if needed).

`X-Webhook-Mode`

No

`terminal`

`terminal` — fires once at the final status (`COMPLETED`/`FAILED`/`ERROR`). `sync` — fires on every poll cycle plus the terminal event, and caps the queue’s polling delay at **15s** for tighter progress updates.

### 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": "pixverse-c1-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "pixverse-c1-image-to-video",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/pixverse-c1-image-to-video_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": "pixverse-c1-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "pixverse-c1-image-to-video",
  "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 - PixVerse C1 Image to Video generate request

Parameter

Required

Type

Default

Allowed values / range

Description

prompt

Yes

string

—

—

Text description guiding video motion and scene evolution. Must be detailed for best results.

image\_url

Yes

string

—

—

URL of the source image to animate. Supported formats: jpg, jpeg, png, webp, gif, avif.

resolution

No

enum

"720p"

"360p", "540p", "720p", "1080p"

Output video resolution.

duration

No

integer

5

1–15 (seconds)

Length of the output video in seconds. Must be between 1 and 15 inclusive.

seed

No

integer

—

—

Optional random seed for reproducible outputs. Same seed + same parameters = identical output.

generate\_audio\_switch

No

boolean

false

—

Enable generation of native audio including background music (BGM), sound effects (SFX), or dialogue synchronized with the video.

## Example Request

```
{
  "prompt": "A woman warrior with her hammer walking with her glacier wolf, cinematic camera move",
  "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/Image.jpeg",
  "resolution": "720p",
  "duration": 5,
  "generate_audio_switch": true
}
```

## Response

```
{
  "request_id": "pixverse-c1-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/pixverse-c1-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_API\_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 'pixverse-c1-image-to-video' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "pixverse-c1-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "pixverse-c1-image-to-video",
  "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/pixverse-c1-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "pixverse-c1-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "pixverse-c1-image-to-video",
  "error": null,
  "output": {
    "media_url": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/pixverse-c1-image-to-video_019dxxxx/output.mp4"],
    "media_type": "video/mp4"
  },
  "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

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.

## Pixverse v5.6

### Text to Video

## Base URL

```
https://gateway.pixazo.ai/pixverse/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

## Pixverse generate request - Pixverse

## Request Code

HTTP Python JavaScript cURL

```
POST /pixverse-request HTTP/1.1
Host: gateway.pixazo.ai
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "prompt": "A golden sunset timelapse over a coastal city, waves crashing against the pier, seagulls flying, warm cinematic lighting, aerial drone perspective",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5
}
```

```
import requests

url = "https://gateway.pixazo.ai/pixverse/v1/pixverse-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "prompt": "A golden sunset timelapse over a coastal city, waves crashing against the pier, seagulls flying, warm cinematic lighting, aerial drone perspective",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 5
}

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

```
const url = 'https://gateway.pixazo.ai/pixverse/v1/pixverse-request';
const headers = {
  'Content-Type': 'application/json',
  'Cache-Control': 'no-cache',
  'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
};
const body = {
  prompt: 'A golden sunset timelapse over a coastal city, waves crashing against the pier, seagulls flying, warm cinematic lighting, aerial drone perspective',
  aspect_ratio: '16:9',
  resolution: '720p',
  duration: 5
};

fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(body)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

```
curl -X POST "https://gateway.pixazo.ai/pixverse/v1/pixverse-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
    "prompt": "A golden sunset timelapse over a coastal city, waves crashing against the pier, seagulls flying, warm cinematic lighting, aerial drone perspective",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 5
  }'
```

## Output

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

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

## Webhook (Optional)

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

### Webhook Headers

Header

Required

Default

Description

`X-Webhook-URL`

Yes (to enable)

—

HTTPS endpoint on your server that will receive the `POST` callback. Must respond `2xx` within a few seconds (process async if needed).

`X-Webhook-Mode`

No

`terminal`

`terminal` — fires once at the final status (`COMPLETED`/`FAILED`/`ERROR`). `sync` — fires on every poll cycle plus the terminal event, and caps the queue’s polling delay at **15s** for tighter progress updates.

### 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": "pixverse_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "pixverse",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/pixverse_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": "pixverse_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "pixverse",
  "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 - Pixverse generate request

Parameter

Required

Type

Default

Allowed values / range

Description

prompt

Yes

string

—

—

Detailed text description of the desired video scene, including motion, lighting, and style

aspect\_ratio

Yes

string

—

"16:9", "9:16", "1:1", "4:3", "3:4"

Aspect ratio of the output video. Supported values: "16:9", "9:16", "1:1", "4:3", "3:4"

resolution

Yes

string

—

"720p", "1080p", "2160p"

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

duration

Yes

integer

—

3, 5, 7, 10

Duration of the video in seconds. Supported values: 3, 5, 7, 10

negative\_prompt

No

string

—

—

Descriptions of elements to avoid in the generated video. Helps refine output quality

## Minimum Request

```
{
  "prompt": "A golden sunset timelapse over a coastal city, waves crashing against the pier, seagulls flying, warm cinematic lighting, aerial drone perspective",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5
}
```

## Full Request (all options)

```
{
  "prompt": "A golden sunset timelapse over a coastal city, waves crashing against the pier, seagulls flying, warm cinematic lighting, aerial drone perspective",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5,
  "negative_prompt": "blurry, low quality, low resolution, pixelated, noisy, grainy, out of focus, poorly lit, poorly exposed, poorly composed, poorly framed, poorly cropped, poorly color corrected, poorly color graded"
}
```

## Response

```
{
  "request_id": "pixverse_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/pixverse_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 Pixverse 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 'pixverse' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "pixverse_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "pixverse",
  "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/pixverse_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

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

### Image to Video

## Base URL

```
https://gateway.pixazo.ai/pixverse-i2v/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

## Pixverse i2v generate request - Pixverse i2v

## Request Code

HTTP Python JavaScript cURL

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

{
  "prompt": "A fierce dragon breathing fire across a stormy night sky, lightning flashing in the background, cinematic dark fantasy",
  "resolution": "720p",
  "duration": "5",
  "image_url": "https://imagesai.appypie.com/7686410/ZU2sxXLmgRF6dgSktn9o_017731475651251.png"
}
```

```
import requests

url = "https://gateway.pixazo.ai/pixverse-i2v/v1/pixverse-i2v-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "prompt": "A fierce dragon breathing fire across a stormy night sky, lightning flashing in the background, cinematic dark fantasy",
    "resolution": "720p",
    "duration": "5",
    "image_url": "https://imagesai.appypie.com/7686410/ZU2sxXLmgRF6dgSktn9o_017731475651251.png"
}

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

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

const data = {
  prompt: 'A fierce dragon breathing fire across a stormy night sky, lightning flashing in the background, cinematic dark fantasy',
  resolution: '720p',
  duration: '5',
  image_url: 'https://imagesai.appypie.com/7686410/ZU2sxXLmgRF6dgSktn9o_017731475651251.png'
};

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/pixverse-i2v/v1/pixverse-i2v-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
    "prompt": "A fierce dragon breathing fire across a stormy night sky, lightning flashing in the background, cinematic dark fantasy",
    "resolution": "720p",
    "duration": "5",
    "image_url": "https://imagesai.appypie.com/7686410/ZU2sxXLmgRF6dgSktn9o_017731475651251.png"
  }'
```

## Output

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

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

## Webhook (Optional)

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

### Webhook Headers

Header

Required

Default

Description

`X-Webhook-URL`

Yes (to enable)

—

HTTPS endpoint on your server that will receive the `POST` callback. Must respond `2xx` within a few seconds (process async if needed).

`X-Webhook-Mode`

No

`terminal`

`terminal` — fires once at the final status (`COMPLETED`/`FAILED`/`ERROR`). `sync` — fires on every poll cycle plus the terminal event, and caps the queue’s polling delay at **15s** for tighter progress updates.

### 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": "pixverse-i2v_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "pixverse-i2v",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/pixverse-i2v_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": "pixverse-i2v_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "pixverse-i2v",
  "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 - Pixverse i2v generate request

Parameter

Required

Type

Default

Allowed values / range

Description

prompt

Yes

string

—

—

Text description describing the desired video motion and scene. Be detailed for best results.

resolution

Yes

string

—

"720p", "1080p"

Target video resolution. Supported values: "720p", "1080p".

duration

Yes

string

—

"5", "10"

Duration of the generated video in seconds. Supported values: "5", "10".

negative\_prompt

No

string

—

—

Describes undesired elements to exclude from the video. Helps refine output quality.

image\_url

Yes

string

—

—

Publicly accessible URL of the input image to animate. Must be a valid HTTP/HTTPS link.

## Minimum Request

```
{
  "prompt": "A fierce dragon breathing fire across a stormy night sky, lightning flashing in the background, cinematic dark fantasy",
  "resolution": "720p",
  "duration": "5",
  "image_url": "https://imagesai.appypie.com/7686410/ZU2sxXLmgRF6dgSktn9o_017731475651251.png"
}
```

## Full Request (all options)

```
{
  "prompt": "A fierce dragon breathing fire across a stormy night sky, lightning flashing in the background, cinematic dark fantasy",
  "resolution": "720p",
  "duration": "5",
  "negative_prompt": "blurry, low quality, low resolution, pixelated, noisy, grainy",
  "image_url": "https://imagesai.appypie.com/7686410/ZU2sxXLmgRF6dgSktn9o_017731475651251.png"
}
```

## Response

```
{
  "request_id": "pixverse-i2v_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/pixverse-i2v_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 Pixverse i2v 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 'pixverse-i2v' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "pixverse-i2v_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "pixverse-i2v",
  "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/pixverse-i2v_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

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