# SeedVR Upscale API

> Provider: **Seed VR**
> Source: https://www.pixazo.ai/models/seedvr

Image and video upscaling capabilities.

## SeedVR2 3B

### Image to Image (Image Upscaler)

## Base URL

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

## Upscale Image Request - SeedVR Upscale API

## Request Code

HTTP Python JavaScript cURL

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

{
  "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/vt_human.jpg",
  "upscale_factor": 2,
  "output_format": "png"
}
```

```
import requests

url = "https://gateway.pixazo.ai/seedvr-upscale/v1/upscale-image/generate"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/vt_human.jpg",
    "upscale_factor": 2,
    "output_format": "png"
}

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

```
async function upscaleImage() {
  const response = await fetch('https://gateway.pixazo.ai/seedvr-upscale/v1/upscale-image/generate', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Cache-Control': 'no-cache',
      'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
    },
    body: JSON.stringify({
      image_url: 'https://pub-582b7213209642b9b995c96c95a30381.r2.dev/vt_human.jpg',
      upscale_factor: 2,
      output_format: 'png'
    })
  });
  
  const data = await response.json();
  console.log(data);
}

upscaleImage();
```

```
curl -X POST https://gateway.pixazo.ai/seedvr-upscale/v1/upscale-image/generate \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  -d '{
    "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/vt_human.jpg",
    "upscale_factor": 2,
    "output_format": "png"
  }'
```

## Output

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

[Try Now](https://api.pixazo.ai/api-details#api=seedvr-upscale-api&operation=upscale-image-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": "seedvr-upscale_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "seedvr-upscale",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/seedvr-upscale_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.png"
    ],
    "media_type": "image/png"
  },
  "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": "seedvr-upscale_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "seedvr-upscale",
  "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 - Upscale Image Request

Parameter

Required

Type

Default

Allowed values / range

Description

image\_url

Yes

string

—

—

URL of the image to upscale. Must be publicly accessible (HTTPS recommended). Supported formats: PNG, JPEG, WebP.

upscale\_mode

No

string

—

—

Upscaling mode. Valid values: \`factor\` (multiply resolution), \`target\` (specific resolution).

upscale\_factor

No

number

—

—

Upscale multiplier (1-8). Only used with \`upscale\_mode: "factor"\`. Higher values = larger output. Recommended: 2-4 for best results.

target\_resolution

No

string

—

—

Target output resolution. Valid values: \`720p\`, \`1080p\`, \`1440p\`, \`2160p\`. Only used with \`upscale\_mode: "target"\`.

noise\_scale

No

number

—

—

Noise reduction strength (0.0-1.0). Lower = preserve details/texture, Higher = smoother/cleaner. Recommended: 0.05-0.15 for photos, 0.08-0.12 for digital art.

output\_format

No

string

—

—

Output image format. Valid values: \`jpg\` (smaller files, photos), \`png\` (lossless, graphics), \`webp\` (modern, efficient).

seed

No

integer

—

—

Random seed for reproducibility. Use the same seed to get consistent results across runs.

sync\_mode

No

boolean

—

true, false

Synchronous mode. If true, returns image as data URI (not recommended for production).

webhook

No

string

—

—

Callback URL for completion notification. POST request sent with upscaling results when complete.

webhook\_events\_filter

No

array

—

—

Events that trigger webhook. Valid values: \`\["\*"\]\` (all events), \`\["completed"\]\` (success/failure only).

## Example Request

```
{
  "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/vt_human.jpg",
  "upscale_factor": 2,
  "output_format": "png"
}
```

## Response

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

### Error via Status/Webhook

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

## Response (Completed)

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

### Video to Video (Video Upscaler)

## Base URL

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

## Upscale Video Request - SeedVR Upscale API

## Request Code

HTTP Python JavaScript cURL

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

{
  "video_url": "https://example.com/my-video.mp4",
  "upscale_factor": 2
}
```

```
import requests

url = "https://gateway.pixazo.ai/seedvr-upscale/v1/upscale-video/generate"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "video_url": "https://example.com/my-video.mp4",
    "upscale_factor": 2
}

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

```
const url = 'https://gateway.pixazo.ai/seedvr-upscale/v1/upscale-video/generate';
const headers = {
  'Content-Type': 'application/json',
  'Cache-Control': 'no-cache',
  'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
};
const body = {
  video_url: 'https://example.com/my-video.mp4',
  upscale_factor: 2
};

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/seedvr-upscale/v1/upscale-video/generate" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
    "video_url": "https://example.com/my-video.mp4",
    "upscale_factor": 2
  }'
```

## Output

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

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

## 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": "seedvr-upscale_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "seedvr-upscale",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/seedvr-upscale_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": "seedvr-upscale_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "seedvr-upscale",
  "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 - Upscale Video Request

Parameter

Required

Type

Default

Allowed values / range

Description

video\_url

Yes

string

—

—

URL of the video to upscale. Must be publicly accessible (HTTPS recommended). Supported formats: MP4, MOV, AVI, WebM.

upscale\_mode

No

string

—

—

Upscaling mode. Valid values: \`factor\` (multiply resolution), \`target\` (specific resolution).

upscale\_factor

No

number

—

—

Upscale multiplier (1-4). Only used with \`upscale\_mode: "factor"\`. Higher values = larger output. Use 1 for quality enhancement without size increase.

target\_resolution

No

string

—

—

Target output resolution. Valid values: \`720p\`, \`1080p\`. Only used with \`upscale\_mode: "target".

noise\_scale

No

number

—

—

Noise reduction strength (0.0-1.0). Lower = preserve details/grain, Higher = smoother/cleaner. Recommended: 0.05-0.2.

output\_format

No

string

—

—

Output video codec. Valid values: \`X264 (.mp4)\` (widely compatible), \`H265 (.mp4)\` (better compression, newer devices).

output\_quality

No

string

—

—

Output encoding quality. Valid values: \`low\` (faster, smaller file), \`medium\` (balanced), \`high\` (best quality, recommended).

output\_write\_mode

No

string

—

—

Encoding speed/quality tradeoff. Valid values: \`fast\` (quick encoding), \`balanced\` (recommended), \`quality\` (slower, best quality).

seed

No

integer

—

—

Random seed for reproducibility. Use the same seed to get consistent results across runs.

webhook

No

string

—

—

Callback URL for completion notification. POST request sent with upscaling results when complete.

webhook\_events\_filter

No

array

—

—

Events that trigger webhook. Valid values: \`\["\*"\]\` (all events), \`\["completed"\]\` (success/failure only), \`\["start", "output", "completed"\]\`.

## Example Request

```
{
  "video_url": "https://example.com/my-video.mp4",
  "upscale_factor": 2
}
```

## Response

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

### Error via Status/Webhook

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

## Response (Completed)

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

## SeedVR2 7B

### Image to Image (Image Upscaler)

## Base URL

```
https://gateway.pixazo.ai/seedvr2-7b-upscale
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Image Upscale Request - SeedVR2 7B

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/seedvr2-7b-upscale/image-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_API_KEY

{
  "image_url": "https://your-cdn.com/source.png"
}
```

```
import requests

url = "https://gateway.pixazo.ai/seedvr2-7b-upscale/image-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
data = {
    "image_url": "https://your-cdn.com/source.png"
}

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

```
const url = 'https://gateway.pixazo.ai/seedvr2-7b-upscale/image-request';
const headers = {
  'Content-Type': 'application/json',
  'Cache-Control': 'no-cache',
  'Ocp-Apim-Subscription-Key': 'YOUR_API_KEY'
};
const data = {
  image_url: 'https://your-cdn.com/source.png'
};

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/seedvr2-7b-upscale/image-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  --data-raw '{
    "image_url": "https://your-cdn.com/source.png"
  }'
```

## Output

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

[Try Now](https://api.pixazo.ai/api-details#api=seedvr2-7b-upscale&operation=image-upscale-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": "seedvr2-7b-upscale_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "seedvr2-7b-upscale",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/seedvr2-7b-upscale_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.png"
    ],
    "media_type": "image/png"
  },
  "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": "seedvr2-7b-upscale_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "seedvr2-7b-upscale",
  "error": "Description of the error",
  "output": null,
  "created_at": "...",
  "updated_at": "...",
  "completed_at": "..."
}
```

### Delivery semantics

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

## Request Parameters - Image Upscale Request

Parameter

Required

Type

Default

Allowed values / range

Description

image\_url

Yes

string (URI)

—

Any reachable HTTPS image URL

Source image to upscale (PNG, JPEG, or WebP).

upscale\_factor

No

number

2.0

1.0 – 8.0

Scale multiplier applied to the source image.

res\_h

No

integer

auto

256 – 4096

Target output height in pixels. Overrides `upscale_factor` when provided.

res\_w

No

integer

auto

256 – 4096

Target output width in pixels. Overrides `upscale_factor` when provided.

output\_format

No

string

png

"jpeg", "png", "webp"

Encoding for the upscaled image.

noise\_scale

No

number

0.0

0.0 – 1.0

Detail / noise injection strength. Higher values add more synthetic detail.

seed

No

integer

random

0 – 2147483647

Random seed for reproducible output.

job\_id

No

string

auto

Any client-supplied id

Optional client-provided identifier. The gateway returns its own `request_id` regardless.

## Example Request

```
{
  "image_url": "https://your-cdn.com/source.png",
  "upscale_factor": 4.0,
  "res_h": 2048,
  "res_w": 2048,
  "output_format": "webp",
  "noise_scale": 0.0,
  "seed": 12345
}
```

## Response

```
{
  "request_id": "seedvr2-7b-upscale_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/seedvr2-7b-upscale_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 'seedvr2-7b-upscale' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "seedvr2-7b-upscale_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "seedvr2-7b-upscale",
  "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/seedvr2-7b-upscale_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "seedvr2-7b-upscale_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "seedvr2-7b-upscale",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/seedvr2-7b-upscale_019dxxxx-xxxx/output.png"
    ],
    "media_type": "image/png"
  },
  "created_at": "2026-05-12T10:00:00.000Z",
  "updated_at": "2026-05-12T10:00:15.000Z",
  "completed_at": "2026-05-12T10: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 the upscaled image(s) on R2 CDN

output.media\_type

string

MIME type of the output (image/png by default)

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 an upscale 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.