# Grok Imagine Video API

> Provider: **xAI**
> Source: https://www.pixazo.ai/models/grok-imagine-video

Video generation and editing by xAI. Grok Imagine Video supports text-to-video, image-to-video, video-to-video editing, and reference-driven multi-image video synthesis (uses @Image1..@ImageN syntax to position reference images in the prompt).

## Grok Imagine Video v1

### Text to Video

## Base URL

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

## Grok Imagine Video (Text to Video) generate request

## Request Code

HTTP Python JavaScript cURL

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

{
  "prompt": "Anime schoolgirl bursting out of house door, cherry blossoms blowing, morning light, speed lines, vibrant colors",
  "duration": 6,
  "aspect_ratio": "16:9",
  "resolution": "720p"
}
```

```
import requests

url = "https://gateway.pixazo.ai/grok-imagine-video-text-to-video/v1/grok-imagine-video-text-to-video-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
data = {
    "prompt": "Anime schoolgirl bursting out of house door, cherry blossoms blowing, morning light, speed lines, vibrant colors",
    "duration": 6,
    "aspect_ratio": "16:9",
    "resolution": "720p"
}

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

```
const url = "https://gateway.pixazo.ai/grok-imagine-video-text-to-video/v1/grok-imagine-video-text-to-video-request";
const headers = {
  "Content-Type": "application/json",
  "Cache-Control": "no-cache",
  "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
};
const data = {
  "prompt": "Anime schoolgirl bursting out of house door, cherry blossoms blowing, morning light, speed lines, vibrant colors",
  "duration": 6,
  "aspect_ratio": "16:9",
  "resolution": "720p"
};

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/grok-imagine-video-text-to-video/v1/grok-imagine-video-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": "Anime schoolgirl bursting out of house door, cherry blossoms blowing, morning light, speed lines, vibrant colors",
    "duration": 6,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }'
```

## Output

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

[Try Now](https://api.pixazo.ai/api-details#api=grok-imagine-video-text-to-video&operation=grok-imagine-video-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": "grok-imagine-video-text-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "grok-imagine-video-text-to-video",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/grok-imagine-video-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": "grok-imagine-video-text-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "grok-imagine-video-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 - Grok Imagine Video (Text to Video) generate request

Parameter

Required

Type

Default

Allowed values / range

Description

prompt

Yes

string

—

—

Text description of the desired video. Must be detailed and descriptive for best results.

duration

No

integer

6

3–10 (seconds)

Duration of the generated video in seconds. Must be a positive integer.

aspect\_ratio

No

enum

"16:9"

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

Aspect ratio of the output video.

resolution

No

enum

"720p"

"480p", "720p"

Resolution of the output video.

## Example Request

```
{
  "prompt": "Anime schoolgirl bursting out of house door, cherry blossoms blowing, morning light, speed lines, vibrant colors",
  "duration": 6,
  "aspect_ratio": "16:9",
  "resolution": "720p"
}
```

## Response

```
{
  "request_id": "grok-imagine-video-text-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/grok-imagine-video-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 'grok-imagine-video-text-to-video' not found or is disabled"
}
```

### Error via Status/Webhook

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

## Response (Completed)

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

## Grok Imagine Video (Image to Video) generate request

## Request Code

HTTP Python JavaScript cURL

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

{
  "prompt": "Medieval knight in ornate armor walking through a mystical forest, bioluminescent plants, over-the-shoulder camera, dark fantasy aesthetic",
  "image_url": "https://v3b.example.com/files/b/0a8b90e0/BFLE9VDlZqsryU-UA3BoD_image_004.png"
}
```

```
import requests

url = "https://gateway.pixazo.ai/grok-imagine-video-image-to-video/v1/grok-imagine-video-image-to-video-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
data = {
    "prompt": "Medieval knight in ornate armor walking through a mystical forest, bioluminescent plants, over-the-shoulder camera, dark fantasy aesthetic",
    "image_url": "https://v3b.example.com/files/b/0a8b90e0/BFLE9VDlZqsryU-UA3BoD_image_004.png"
}

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

```
const url = "https://gateway.pixazo.ai/grok-imagine-video-image-to-video/v1/grok-imagine-video-image-to-video-request";

const data = {
  prompt: "Medieval knight in ornate armor walking through a mystical forest, bioluminescent plants, over-the-shoulder camera, dark fantasy aesthetic",
  image_url: "https://v3b.example.com/files/b/0a8b90e0/BFLE9VDlZqsryU-UA3BoD_image_004.png"
};

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

```
curl -X POST "https://gateway.pixazo.ai/grok-imagine-video-image-to-video/v1/grok-imagine-video-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": "Medieval knight in ornate armor walking through a mystical forest, bioluminescent plants, over-the-shoulder camera, dark fantasy aesthetic",
    "image_url": "https://v3b.example.com/files/b/0a8b90e0/BFLE9VDlZqsryU-UA3BoD_image_004.png"
  }'
```

## Output

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

[Try Now](https://api.pixazo.ai/api-details#api=grok-imagine-video-image-to-video&operation=grok-imagine-video-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": "grok-imagine-video-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "grok-imagine-video-image-to-video",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/grok-imagine-video-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": "grok-imagine-video-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "grok-imagine-video-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 - Grok Imagine Video (Image to Video) generate request

Parameter

Required

Type

Default

Allowed values / range

Description

prompt

Yes

string

—

—

Text description of the desired motion or scene in the video. Be specific about camera movement, lighting, environment, and action (e.g., “over-the-shoulder camera, slow pan left, bioluminescent plants glowing”).

image\_url

Yes

string

—

—

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

duration

No

integer

6

3–10 seconds

Duration of the generated video in seconds.

aspect\_ratio

No

enum

"auto"

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

Aspect ratio of the output video.

resolution

No

enum

"720p"

"480p", "720p"

Resolution of the output video.

## Example Request

```
{
  "prompt": "Medieval knight in ornate armor walking through a mystical forest, bioluminescent plants, over-the-shoulder camera, dark fantasy aesthetic",
  "image_url": "https://v3b.example.com/files/b/0a8b90e0/BFLE9VDlZqsryU-UA3BoD_image_004.png",
  "duration": 6,
  "aspect_ratio": "auto",
  "resolution": "720p"
}
```

## Response

```
{
  "request_id": "grok-imagine-video-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/grok-imagine-video-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 'grok-imagine-video-image-to-video' not found or is disabled"
}
```

### Error via Status/Webhook

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

## Response (Completed)

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

### Video to Video (Video Editing)

## Base URL

```
https://gateway.pixazo.ai/grok-imagine-video-edit-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

## Grok Imagine Video (Edit Video) generate request

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/grok-imagine-video-edit-video/v1/grok-imagine-video-edit-video-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_API_KEY

{
  "prompt": "Colorize the video",
  "video_url": "https://v3b.example.com/files/b/0a8b9112/V5Z_NIPE3ppMDWivNo6_q_video_019.mp4",
  "resolution": "auto"
}
```

```
import requests

url = "https://gateway.pixazo.ai/grok-imagine-video-edit-video/v1/grok-imagine-video-edit-video-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
data = {
    "prompt": "Colorize the video",
    "video_url": "https://v3b.example.com/files/b/0a8b9112/V5Z_NIPE3ppMDWivNo6_q_video_019.mp4",
    "resolution": "auto"
}

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

```
const url = "https://gateway.pixazo.ai/grok-imagine-video-edit-video/v1/grok-imagine-video-edit-video-request";
const headers = {
  "Content-Type": "application/json",
  "Cache-Control": "no-cache",
  "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
};
const data = {
  "prompt": "Colorize the video",
  "video_url": "https://v3b.example.com/files/b/0a8b9112/V5Z_NIPE3ppMDWivNo6_q_video_019.mp4",
  "resolution": "auto"
};

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/grok-imagine-video-edit-video/v1/grok-imagine-video-edit-video-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  --data-raw '{
    "prompt": "Colorize the video",
    "video_url": "https://v3b.example.com/files/b/0a8b9112/V5Z_NIPE3ppMDWivNo6_q_video_019.mp4",
    "resolution": "auto"
  }'
```

## Output

```
{
  "request_id": "grok-imagine-video-edit-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/grok-imagine-video-edit-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=grok-imagine-video-edit-video&operation=grok-imagine-video-edit-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": "grok-imagine-video-edit-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "grok-imagine-video-edit-video",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/grok-imagine-video-edit-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": "grok-imagine-video-edit-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "grok-imagine-video-edit-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 - Grok Imagine Video (Edit Video) generate request

Parameter

Required

Type

Default

Allowed values / range

Description

prompt

Yes

string

—

—

Text description of the desired video edit. Must be detailed and specific for best results.

video\_url

Yes

string

—

—

Publicly accessible URL of the input video to edit. Must be reachable by the Pixazo service.

resolution

No

enum

auto

auto, 480p, 720p

Target output resolution. When set to auto, the model selects the optimal resolution based on input and prompt.

## Example Request

```
{
  "prompt": "Colorize the video",
  "video_url": "https://v3b.example.com/files/b/0a8b9112/V5Z_NIPE3ppMDWivNo6_q_video_019.mp4",
  "resolution": "auto"
}
```

## Response

```
{
  "request_id": "grok-imagine-video-edit-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/grok-imagine-video-edit-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 'grok-imagine-video-edit-video' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "grok-imagine-video-edit-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "grok-imagine-video-edit-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/grok-imagine-video-edit-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

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

### Reference to Video (Ref Images to Video)

## Base URL

```
https://gateway.pixazo.ai/grok-imagine-video-reference-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

## Grok Imagine Video (Reference to Video) generate request

## Request Code

HTTP Python JavaScript cURL

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

{
  "prompt": "A @Image1 running through a sunlit meadow, cinematic slow motion",
  "reference_image_urls": [
    "https://v3b.example.com/files/b/0a8b90e0/BFLE9VDlZqsryU-UA3BoD_image_004.png"
  ],
  "duration": 8,
  "aspect_ratio": "16:9",
  "resolution": "480p"
}
```

```
import requests

url = "https://gateway.pixazo.ai/grok-imagine-video-reference-to-video/v1/grok-imagine-video-reference-to-video-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
data = {
    "prompt": "A @Image1 running through a sunlit meadow, cinematic slow motion",
    "reference_image_urls": [
        "https://v3b.example.com/files/b/0a8b90e0/BFLE9VDlZqsryU-UA3BoD_image_004.png"
    ],
    "duration": 8,
    "aspect_ratio": "16:9",
    "resolution": "480p"
}

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

```
const url = "https://gateway.pixazo.ai/grok-imagine-video-reference-to-video/v1/grok-imagine-video-reference-to-video-request";
const headers = {
  "Content-Type": "application/json",
  "Cache-Control": "no-cache",
  "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
};
const data = {
  "prompt": "A @Image1 running through a sunlit meadow, cinematic slow motion",
  "reference_image_urls": [
    "https://v3b.example.com/files/b/0a8b90e0/BFLE9VDlZqsryU-UA3BoD_image_004.png"
  ],
  "duration": 8,
  "aspect_ratio": "16:9",
  "resolution": "480p"
};

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/grok-imagine-video-reference-to-video/v1/grok-imagine-video-reference-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 @Image1 running through a sunlit meadow, cinematic slow motion",
    "reference_image_urls": [
        "https://v3b.example.com/files/b/0a8b90e0/BFLE9VDlZqsryU-UA3BoD_image_004.png"
    ],
    "duration": 8,
    "aspect_ratio": "16:9",
    "resolution": "480p"
}'
```

## Output

```
{
  "request_id": "grok-imagine-video-reference-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/grok-imagine-video-reference-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=grok-imagine-video-reference-to-video&operation=grok-imagine-video-reference-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": "grok-imagine-video-reference-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "grok-imagine-video-reference-to-video",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/grok-imagine-video-reference-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": "grok-imagine-video-reference-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "grok-imagine-video-reference-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 - Grok Imagine Video (Reference to Video) generate request

Parameter

Required

Type

Default

Allowed values / range

Description

prompt

Yes

string

—

—

Text prompt describing the desired video. Use @Image1, @Image2, ..., @Image7 to reference the corresponding URLs in \`reference\_image\_urls\` in order. Example: "A @Image1 running through a sunlit meadow, cinematic slow motion".

reference\_image\_urls

Yes

string\[\]

—

—

Array of one to seven public HTTP URLs to reference images. Each image is referenced in the prompt by @Image1, @Image2, etc., in the order provided. Maximum of 7 images allowed.

duration

No

integer

8

3–15 (seconds)

Duration of the generated video in seconds. Must be a positive integer.

aspect\_ratio

No

enum

"16:9"

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

Aspect ratio of the output video.

resolution

No

enum

"480p"

"480p", "720p"

Resolution of the output video.

## Example Request

```
{
  "prompt": "A @Image1 running through a sunlit meadow, cinematic slow motion",
  "reference_image_urls": [
    "https://v3b.example.com/files/b/0a8b90e0/BFLE9VDlZqsryU-UA3BoD_image_004.png"
  ],
  "duration": 8,
  "aspect_ratio": "16:9",
  "resolution": "480p"
}
```

## Response

```
{
  "request_id": "grok-imagine-video-reference-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/grok-imagine-video-reference-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 'grok-imagine-video-reference-to-video' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "grok-imagine-video-reference-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "grok-imagine-video-reference-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/grok-imagine-video-reference-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

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