> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Video Upscaling

> Enhance video resolution and quality on the Venice API using the Topaz Video Upscale model — submit a source clip, pick a scale, and retrieve the result.

Video upscaling lets you enhance existing videos to higher resolutions while improving visual quality. The **Topaz Video Upscale** model uses AI-powered upscaling to increase resolution by 2x or 4x, or apply quality enhancement at the original resolution (1x).

## How it works

Video upscaling uses the same async queue system as video generation:

1. **Queue** — Submit your video to `/video/queue` with the `topaz-video-upscale` model
2. **Poll** — Check `/video/retrieve` with the returned `queue_id` until the status is `completed`
3. **Complete** — Call `/video/complete` to finalize and get the output URL

The server automatically detects the input video's duration, frame rate, and dimensions from the uploaded file. You don't need to provide these values — billing is calculated from the actual video metadata.

## Upscale factors

| `upscale_factor` | Output resolution   | Use case                                           |
| ---------------- | ------------------- | -------------------------------------------------- |
| `1`              | Same as input       | Quality enhancement only (denoising, sharpening)   |
| `2` (default)    | 2x input dimensions | Standard upscale — 720p input becomes 1440p output |
| `4`              | 4x input dimensions | Maximum upscale — 480p input becomes 1920p output  |

<Note>
  The `upscale_factor` parameter replaces `resolution` for upscale models. Passing `resolution` will return an error. This is because the output resolution depends on the input video's dimensions — a `2x` upscale of a 720p video produces a different result than a `2x` upscale of a 480p video.
</Note>

## Supported input formats

* **Formats**: MP4, MOV, WebM
* **Input methods**: HTTPS URL or `data:video/...;base64,...` data URL
* **Max duration**: 300 seconds (5 minutes)

## API usage

### Queue an upscale job

<CodeGroup>
  ```bash cURL theme={"system"}
  curl https://api.venice.ai/api/v1/video/queue \
    -H "Authorization: Bearer $VENICE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "topaz-video-upscale",
      "video_url": "https://example.com/input-video.mp4",
      "upscale_factor": 2
    }'
  ```

  ```python Python theme={"system"}
  import requests

  response = requests.post(
      "https://api.venice.ai/api/v1/video/queue",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      json={
          "model": "topaz-video-upscale",
          "video_url": "https://example.com/input-video.mp4",
          "upscale_factor": 2,
      },
  )

  data = response.json()
  queue_id = data["queue_id"]
  print(f"Queued: {queue_id}")
  ```

  ```javascript Node.js theme={"system"}
  const response = await fetch("https://api.venice.ai/api/v1/video/queue", {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "topaz-video-upscale",
      video_url: "https://example.com/input-video.mp4",
      upscale_factor: 2,
    }),
  });

  const { queue_id } = await response.json();
  console.log(`Queued: ${queue_id}`);
  ```
</CodeGroup>

The response includes a `queue_id` to track the job:

```json theme={"system"}
{
  "model": "topaz-video-upscale",
  "queue_id": "abc123-def456-..."
}
```

### Poll for completion

<CodeGroup>
  ```bash cURL theme={"system"}
  curl https://api.venice.ai/api/v1/video/retrieve \
    -H "Authorization: Bearer $VENICE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"queue_id": "abc123-def456-..."}'
  ```

  ```python Python theme={"system"}
  import time

  while True:
      result = requests.post(
          "https://api.venice.ai/api/v1/video/retrieve",
          headers={"Authorization": "Bearer YOUR_API_KEY"},
          json={"queue_id": queue_id},
      )
      data = result.json()

      if data.get("status") == "completed":
          print(f"Video URL: {data['url']}")
          break

      time.sleep(5)
  ```

  ```javascript Node.js theme={"system"}
  const poll = async (queueId) => {
    while (true) {
      const res = await fetch("https://api.venice.ai/api/v1/video/retrieve", {
        method: "POST",
        headers: {
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ queue_id: queueId }),
      });
      const data = await res.json();

      if (data.status === "completed") {
        console.log(`Video URL: ${data.url}`);
        return data;
      }

      await new Promise((r) => setTimeout(r, 5000));
    }
  };

  await poll(queue_id);
  ```
</CodeGroup>

### Finalize with complete

After retrieving the result, call `/video/complete` to finalize:

```bash theme={"system"}
curl https://api.venice.ai/api/v1/video/complete \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queue_id": "abc123-def456-..."}'
```

***

## API parameters

| Field            | Type   | Required | Description                                                     |
| ---------------- | ------ | -------- | --------------------------------------------------------------- |
| `model`          | string | **Yes**  | Must be `topaz-video-upscale`                                   |
| `video_url`      | string | **Yes**  | Input video URL or data URL. Supported formats: MP4, MOV, WebM. |
| `upscale_factor` | number | No       | `1`, `2` (default), or `4`. Controls the upscale multiplier.    |

### Parameters not used for upscale models

The following parameters are **not accepted** for `topaz-video-upscale` and will return an error if provided:

| Field        | Reason                                                                       |
| ------------ | ---------------------------------------------------------------------------- |
| `resolution` | Use `upscale_factor` instead. Output resolution depends on input dimensions. |
| `prompt`     | Upscaling does not use text prompts. An empty string is set automatically.   |

The `duration` parameter is also ignored — the server detects duration directly from the video file for billing accuracy.

***

## Pricing

Pricing is based on **duration**, **output resolution tier**, and **frame rate**. The output resolution tier is determined by the input video's height multiplied by the upscale factor.

### Output resolution tiers

| Tier  | Output height | Per-second rate |
| ----- | ------------- | --------------- |
| 720p  | ≤ 720px       | \~\$0.013       |
| 1080p | 721–1080px    | \~\$0.025       |
| 4K    | > 1080px      | \~\$0.10        |

<Note>
  Videos with frame rates above 48fps cost 2x the per-second rate.
</Note>

### Pricing examples

| Input        | Upscale factor | Output            | Duration | Estimated cost |
| ------------ | -------------- | ----------------- | -------- | -------------- |
| 480p, 30fps  | 2x             | 960p (1080p tier) | 10s      | \~\$0.25       |
| 720p, 30fps  | 2x             | 1440p (4K tier)   | 10s      | \~\$1.00       |
| 1080p, 30fps | 2x             | 2160p (4K tier)   | 30s      | \~\$3.00       |
| 360p, 24fps  | 4x             | 1440p (4K tier)   | 10s      | \~\$1.00       |
| 480p, 60fps  | 2x             | 960p (1080p tier) | 10s      | \~\$0.50       |

Use the [Video Quote API](/api-reference/endpoint/video/quote) to get exact pricing before submitting a job.

### Getting a quote

```bash theme={"system"}
curl https://api.venice.ai/api/v1/video/quote \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "topaz-video-upscale",
    "duration": "10",
    "input_height": 720
  }'
```

The quote endpoint accepts `input_height` so it can estimate the output resolution tier. This is optional — if omitted, the quote assumes a conservative estimate.

***

## Troubleshooting

| Problem                                      | Likely cause                                | Fix                                                                                                       |
| -------------------------------------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `"Use upscale_factor instead of resolution"` | `resolution` was passed in the request      | Remove `resolution` and use `upscale_factor` instead                                                      |
| Higher-than-expected cost                    | Input video has high resolution or high FPS | Check input dimensions with the quote endpoint. 720p+ input with 2x upscale lands in the 4K pricing tier. |
| Job takes a long time                        | Large or long video                         | Upscaling is compute-intensive. Longer videos and higher upscale factors take proportionally longer.      |
| `"Insufficient balance"`                     | Account credits too low                     | Add credits at [venice.ai/settings/api](https://venice.ai/settings/api)                                   |