# Sora Video API

> Provider: **OpenAI**
> Source: https://www.pixazo.ai/models/sora

Advanced video generation by OpenAI.

## Sora 2 Pro

### Image to Video

## Base URL

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

## Generate Image to Video Request - Sora Video API

## Request Code

HTTP Python JavaScript cURL

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

{
  "prompt": "The woman turns her head and smiles",
  "image": "https://example.com/image-1280x720.jpg"
}
```

```
import requests
import json

url = "https://gateway.pixazo.ai/sora-video/v1/video/i2v/generate"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "prompt": "The woman turns her head and smiles",
    "image": "https://example.com/image-1280x720.jpg"
}

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

```
const url = 'https://gateway.pixazo.ai/sora-video/v1/video/i2v/generate';
const headers = {
  'Content-Type': 'application/json',
  'Cache-Control': 'no-cache',
  'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
};
const body = {
  prompt: 'The woman turns her head and smiles',
  image: 'https://example.com/image-1280x720.jpg'
};

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 -v -X POST "https://gateway.pixazo.ai/sora-video/v1/video/i2v/generate" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
    "prompt": "The woman turns her head and smiles",
    "image": "https://example.com/image-1280x720.jpg"
  }'
```

## Output

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

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

## Webhook (Optional)

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

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

## Request Parameters - Generate Image to Video Request

Parameter

Required

Type

Description

prompt

Yes

string

The text description of how you want to animate the image. Describe the motion, action, or transformation you want to see.

image

Yes

string

The input image URL (http:// or https://) or base64-encoded string (e.g., data:image/jpeg;base64,...). **Must be exactly one of these dimensions: 1280×720, 720×1280, 1792×1024, or 1024×1792.** Images in other sizes must be resized before uploading — the API will reject unsupported dimensions with a 400 error.

model

No

string

The ID of the Sora model to use for generation. Currently supports sora-2-pro.

size

No

string

The resolution of the output video. **Must match the input image dimensions exactly.** If omitted, derived from the input image. Valid values: 1280x720, 720x1280, 1792x1024, 1024x1792.

seconds

No

integer

The duration of the output video in seconds. Valid values: 4, 8, or 12.

callback\_url

No

string

Callback notification URL for the result of this generation task. When the video generation completes, the system sends a POST request with the video details. If omitted, use polling to retrieve results.

## Example Request

```
{
  "prompt": "The cityscape comes alive as the sun sets, lights gradually turning on across the buildings, traffic moving below",
  "image": "https://example.com/city-skyline-1792x1024.jpg",
  "size": "1792x1024",
  "seconds": 12,
  "callback_url": "https://your-domain.com/webhook/notify"
}
```

## Response

```
{
  "request_id": "sora-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/sora-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

## Check Video Result - Sora Video API

## Request Code

HTTP Python JavaScript cURL

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

{
  "video_id": "video_68e4ff15fd8c8193ae7c27ca15812XXXXXXXXXXXXXXXXXXX"
}
```

```
import requests
import json

url = "https://gateway.pixazo.ai/sora-video/v1/video/result"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "video_id": "video_68e4ff15fd8c8193ae7c27ca15812XXXXXXXXXXXXXXXXXXX"
}

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

```
const url = 'https://gateway.pixazo.ai/sora-video/v1/video/result';
const headers = {
  'Content-Type': 'application/json',
  'Cache-Control': 'no-cache',
  'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
};
const body = {
  video_id: 'video_68e4ff15fd8c8193ae7c27ca15812XXXXXXXXXXXXXXXXXXX'
};

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 -v -X POST "https://gateway.pixazo.ai/sora-video/v1/video/result" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
    "video_id": "video_68e4ff15fd8c8193ae7c27ca15812XXXXXXXXXXXXXXXXXXX"
  }'
```

## Output

```
{
  "id": "video_68e4ff15fd8c...",
  "status": "completed",
  "video_url": "https://...XXXXXXXXXXXXXXXXXXXXX.mp4"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=sora-video&operation=check-video-result)

## Request Parameters - Check Video Result

Parameter

Required

Type

Description

video\_id

Yes

string

The unique identifier of the video generation task to check.

## Example Request

```
{
  "video_id": "video_68e4ff15fd8c8193ae7c27ca15812XXXXXXXXXXXXXXXXXXX"
}
```

## Response

```
{
  "id": "video_68e4ff15fd8c8193ae7c27ca15812XXXXXXXXXXXXXXXXXXX",
  "status": "completed",
  "model": "sora-2-pro",
  "prompt": "She turns around and smiles, then slowly walks out of the frame",
  "created_at": 1759837181637,
  "completed_at": 1759837336742,
  "video_url": "https://...XXXXXXXXXXXXXXXXXXXXX.mp4",
  "metadata": {
    "total_attempts": 5,
    "polling_duration_seconds": 155
  }
}
```

## 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 Check Video Result.

Code

Meaning

200

Success

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

### Error via Status/Webhook

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

## Response (Completed)

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

### Text to Video

## Base URL

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

## Generate Text to Video Request - Sora Video API

## Request Code

HTTP Python JavaScript cURL

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

{
  "prompt": "A serene beach at sunset with gentle waves rolling onto the shore, palm trees swaying in the breeze, and seagulls flying overhead",
  "size": "1280x720",
  "seconds": 4,
  "callback_url": "https://your-domain.com/webhook/notify"
}
```

```
import requests
import json

url = "https://gateway.pixazo.ai/sora-video/v1/video/generate"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "prompt": "A serene beach at sunset with gentle waves rolling onto the shore, palm trees swaying in the breeze, and seagulls flying overhead",
    "size": "1280x720",
    "seconds": 4,
    "callback_url": "https://your-domain.com/webhook/notify"
}

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

```
const url = 'https://gateway.pixazo.ai/sora-video/v1/video/generate';
const headers = {
  'Content-Type': 'application/json',
  'Cache-Control': 'no-cache',
  'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
};
const data = {
  prompt: 'A serene beach at sunset with gentle waves rolling onto the shore, palm trees swaying in the breeze, and seagulls flying overhead',
  size: '1280x720',
  seconds: 4,
  callback_url: 'https://your-domain.com/webhook/notify'
};

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 -v -X POST "https://gateway.pixazo.ai/sora-video/v1/video/generate" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
    "prompt": "A serene beach at sunset with gentle waves rolling onto the shore, palm trees swaying in the breeze, and seagulls flying overhead",
    "size": "1280x720",
    "seconds": 4,
    "callback_url": "https://your-domain.com/webhook/notify"
  }'
```

## Output

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

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

## Webhook (Optional)

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

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

## Request Parameters - Generate Text to Video Request

Parameter

Required

Type

Description

prompt

Yes

string

The text description of the video you want to generate. Be descriptive and specific for best results.

model

No

string

The ID of the Sora model to use for generation. Currently supports \`sora-2-pro\`.

size

No

string

The resolution of the output video. Valid values: \`1280x720\`, \`720x1280\`, \`1792x1024\`, \`1024x1792\`.

seconds

No

integer

The duration of the output video in seconds. Valid values: \`4\`, \`8\`, or \`12\`.

callback\_url

No

string

Callback notification URL for the result of this generation task. When the video generation completes, the system sends a POST request with the video details. If omitted, use polling to retrieve results.

## Example Request

```
{
  "prompt": "A futuristic city at night with flying cars, neon lights reflecting off glass skyscrapers, and holographic advertisements floating in the air",
  "size": "1792x1024",
  "seconds": 12,
  "callback_url": "https://your-domain.com/webhook/notify"
}
```

## Response

```
{
  "request_id": "sora-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/sora-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.

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

### Error via Status/Webhook

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

## Response (Completed)

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