# topaz/video/upscale

> Topaz Video Upscale upscales and enhances video up to 4K with Topaz's precision Proteus, Artemis, Gaia, Theia, Iris and Dione models. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

## Overview

- **Endpoint**: `https://api.wavespeed.ai/api/v3/topaz/video/upscale`
- **Polling/result URL**: `https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result`
- **Model ID**: `topaz/video/upscale`
- **Category**: upscale-video

## Pricing

Pricing is calculated upfront from the source video duration and selected resolution and processing model. The source duration is rounded up to the next whole second, capped at 300 seconds for billing. The minimum charge is **$0.10**, and the total is rounded up to the next **$0.10**.

### Example Costs

For a **10-second source video**:

| Model | 720p | 1080p | 2k | 4k |
| --- | --- | --- | --- | --- |
| Other listed models | $0.10 | $0.20 | $0.30 | $0.50 |
| Gaia 2 Animation | $0.10 | $0.10 | $0.30 | $0.30 |

Examples use the selected resolution and a billing basis of 30 source frames per second. Other durations have different totals; the displayed price is calculated before submission.

---

## API Information

This model can be used via our HTTP API or more conveniently via our client libraries.
The API is asynchronous: submit a prediction, then poll its result URL until it completes.

### Input Schema

The API accepts the following input parameters:

- **`video`** (`string`, _required_):
  The video to process.

- **`model`** (`string`, _optional_):
  The Topaz model to use. Proteus: The default choice for video enhancement and upscaling (default). Proteus Natural: Next-generation natural enhancement; always upscales 2x. Rhea: High-fidelity upscaling for fine detail. Artemis High Quality: Enhancement for high-quality sources. Artemis Medium Quality: Balanced enhancement for medium-quality footage. Artemis Low Quality: Heavier restoration for low-quality footage. Artemis Medium Halo: Removes moderate edge haloing. Artemis Strong Halo: Removes pronounced edge haloing. Artemis Aliasing & Moire: Reduces aliasing and moire. Gaia High Quality: Fine detail for already-clean sources. Gaia CG: Upscaling for animation, CG and stylized footage. Gaia 2 Animation: Animation upscaling; always upscales 2x. Theia Fine Tune Detail: Aggressive per-frame detail enhancement. Theia Fine Tune Fidelity: Stable, consistent detail with high fidelity. Iris Medium Quality: Face recovery for mid-quality footage. Iris Low Quality: Face recovery for degraded footage. Dione DV: Deinterlacing for DV sources. Dione TV: Deinterlacing for TV sources. Dione Robust: Deinterlacing for challenging interlaced content. Dione Dehalo: Deinterlacing plus halo removal. Dione Robust Dehalo: Robust deinterlacing plus halo removal.
  - Default: `"Proteus"`
  - Options: "Proteus", "Proteus Natural", "Rhea", "Artemis High Quality", "Artemis Medium Quality", "Artemis Low Quality", "Artemis Medium Halo", "Artemis Strong Halo", "Artemis Aliasing & Moire", "Gaia High Quality", "Gaia CG", "Gaia 2 Animation", "Theia Fine Tune Detail", "Theia Fine Tune Fidelity", "Iris Medium Quality", "Iris Low Quality", "Dione DV", "Dione TV", "Dione Robust", "Dione Dehalo", "Dione Robust Dehalo"

- **`target_resolution`** (`string`, _optional_):
  Target resolution to upscale to. The source aspect ratio is preserved.
  - Default: `"1080p"`
  - Options: "720p", "1080p", "2k", "4k"



**Required Parameters Example**:

```json
{
  "video": "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4"
}
```

**Full Example**:

```json
{
  "video": "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4",
  "model": "Proteus",
  "target_resolution": "1080p"
}
```

### Result Data Schema

The `data` object returned by the API has the following fields:

- **`created_at`** (`string (date-time)`, _optional_):
  ISO timestamp of when the request was created (e.g., "2023-04-01T12:34:56.789Z").

- **`id`** (`string`, _optional_):
  Unique identifier for the prediction, the ID of the prediction to get.

- **`model`** (`string`, _optional_):
  Model ID used for the prediction.

- **`outputs`** (`array of string | object`, _optional_):
  Array of generated outputs (empty when status is not completed). Items are usually URL strings, but may be text strings or structured result objects, depending on the model.

- **`status`** (`string`, _optional_):
  Status of the task: created, processing, completed, or failed.

- **`urls`** (`object`, _optional_):
  Object containing related API endpoints.



**Example `data` Object**:

```json
{
  "created_at": "example",
  "id": "example",
  "model": "example",
  "outputs": [],
  "status": "example",
  "urls": {}
}
```

## Usage Examples

The examples use `jq` to read JSON. Set your API key first:

```bash
set -euo pipefail
export WAVESPEED_API_KEY="your-api-key"
```

### 1. Submit a prediction

```bash
REQUEST_BODY=$(cat <<'JSON'
{
  "video": "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4"
}
JSON
)

SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url https://api.wavespeed.ai/api/v3/topaz/video/upscale \
  --header "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  --header "Content-Type: application/json" \
  --data "${REQUEST_BODY}")

printf '%s\n' "${SUBMIT_RESPONSE}" | jq .
```

The response contains the prediction ID in `data.id`.

### 2. Poll until complete and read `outputs`

```bash
PREDICTION_ID=$(printf '%s' "${SUBMIT_RESPONSE}" | jq -r '.data.id')
if [ -z "${PREDICTION_ID}" ] || [ "${PREDICTION_ID}" = "null" ]; then
  printf 'Submission response did not contain data.id\n' >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

while true; do
  RESPONSE=$(curl --silent --show-error --fail-with-body \
    --request GET \
    --url "${RESULT_URL}" \
    --header "Authorization: Bearer ${WAVESPEED_API_KEY}")

  RESULT=$(printf '%s' "${RESPONSE}" | jq -e '.data')
  STATUS=$(printf '%s' "${RESULT}" | jq -er '.status')
  case "${STATUS}" in
    completed)
      # Generated files are returned in the outputs array.
      printf '%s\n' "${RESULT}" | jq '.outputs'
      break
      ;;
    failed|cancelled|timeout|deleted)
      printf '%s\n' "${RESULT}" | jq '{status, error, code}'
      exit 1
      ;;
    *)
      sleep 2
      ;;
  esac
done
```

## Additional Resources

### Documentation

- [Model Playground](https://wavespeed.ai/models/topaz/video/upscale)
- [API Documentation](https://wavespeed.ai/docs/docs-api/topaz/topaz-video-upscale)
