> ## Documentation Index
> Fetch the complete documentation index at: https://veniceai-tomb-topaz-api-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Video Enhancement (Topaz)

> Upscale, restore, denoise, deblur, interpolate, colorize, and convert SDR to HDR on the Venice API with the Topaz enhancement model suite — full settings reference and examples.

The Topaz video enhancement suite on Venice covers every enhancement job — faithful upscaling, generative restoration, creative reimagining, denoising, deblurring, frame interpolation, SDR-to-HDR conversion, and colorization. All models share the same async queue flow: submit a source video to `/video/queue`, poll `/video/retrieve`, then call `/video/complete`.

The server detects the input video's duration, frame rate, and dimensions from the file — you don't provide them, and billing is calculated from the actual output.

## Models

| Model              | ID                           | What it does                                                                                                                       |
| ------------------ | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Precision**      | `topaz-video-precision`      | Faithful, non-generative upscaling. Best for clean, natural upscales of real-world footage.                                        |
| **Starlight**      | `topaz-video-starlight`      | Generative diffusion restoration — rebuilds detail the source no longer has. Best for AI-generated and heavily compressed footage. |
| **Starlight Fast** | `topaz-video-starlight-fast` | Half-price, fastest diffusion pass.                                                                                                |
| **Astra**          | `topaz-video-astra`          | Creative upscaling that invents new detail, typically delivering 4K. Optional guidance prompt.                                     |
| **Hyperion**       | `topaz-video-hyperion`       | SDR-to-HDR conversion (HDR10, 10-bit). Keeps source resolution and frame rate.                                                     |
| **Interpolate**    | `topaz-video-interpolate`    | Frame interpolation up to 120 fps, plus slow motion. Keeps source resolution.                                                      |
| **Denoise**        | `topaz-video-denoise`        | Dedicated noise/grain reduction at source resolution, with optional upscaling on top.                                              |
| **Deblur**         | `topaz-video-deblur`         | Motion deblur at source resolution.                                                                                                |
| **Colorize**       | `topaz-video-colorize`       | Brings natural color to black-and-white footage (output is at least 1080p).                                                        |

## Quick start

<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-precision",
      "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-precision",
          "video_url": "https://example.com/input-video.mp4",
          "upscale_factor": 2,
      },
  )

  queue_id = response.json()["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-precision",
      video_url: "https://example.com/input-video.mp4",
      upscale_factor: 2,
    }),
  });

  const { queue_id } = await response.json();
  ```
</CodeGroup>

Poll `/video/retrieve` with the `queue_id` until `status` is `completed`, then call `/video/complete`. See [Queue](/api-reference/endpoint/video/queue), [Retrieve](/api-reference/endpoint/video/retrieve), and [Complete](/api-reference/endpoint/video/complete).

## Settings reference

Every setting is optional — omitting it uses the model's default. Only the settings a model supports are accepted; anything else is rejected with a validation error. Discover each model's supported settings programmatically under `constraints.topaz` in [`GET /models`](/api-reference/endpoint/models).

### `upscale_factor`

Upscale multiplier for the upscaling models (Precision, Starlight, Starlight Fast, Astra, Denoise). Replaces `resolution`.

| Value         | Effect                                        |
| ------------- | --------------------------------------------- |
| `1`           | Enhance at the source resolution (no upscale) |
| `2` (default) | Double width and height                       |
| `4`           | Quadruple width and height                    |

<Warning>
  Astra 2 snaps to its own output resolution (typically 4K) regardless of the requested factor, and billing follows the delivered resolution. Hyperion, Interpolate, Deblur, and Colorize keep the source resolution and reject `upscale_factor`.
</Warning>

### `enhancement_model`

The provider-side enhancement model. Available values per Venice model:

| Venice model              | `enhancement_model` options (default in bold)                                                                                                                                                                                                                                                      |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `topaz-video-precision`   | **Proteus**, Proteus Natural, Iris, Iris Low Quality, Dione DV, Dione TV, Dione Robust, Dione Dehalo, Dione Robust Dehalo, Artemis High/Medium/Low Quality, Artemis Strong/Medium Halo, Artemis Aliasing & Moire, Gaia HQ, Gaia CG, Gaia 2, Rhea, Theia Fine Tune Detail, Theia Fine Tune Fidelity |
| `topaz-video-starlight`   | **Starlight Precise 2.6**, Starlight HQ, Starlight Mini, Starlight Sharp                                                                                                                                                                                                                           |
| `topaz-video-interpolate` | **Apollo**, Chronos, Aion                                                                                                                                                                                                                                                                          |
| `topaz-video-denoise`     | **Nyx**, Nyx Fast, Nyx XL, Nyx HF                                                                                                                                                                                                                                                                  |

Pricing follows the selected model where the provider's rates differ: Gaia 2 and Nyx Fast bill at half price; Aion bills at \~2.7x; Proteus Natural is cheaper at 4K.

<Note>
  Nyx Fast and Nyx HF are denoise-only — they reject `upscale_factor` greater than 1.
</Note>

### Sliders (0.0–1.0 unless noted)

| Parameter        | Models                                     | Effect                                                      |
| ---------------- | ------------------------------------------ | ----------------------------------------------------------- |
| `compression`    | Precision, Denoise                         | Compression artifact removal                                |
| `noise`          | Precision, Denoise                         | Noise reduction                                             |
| `halo`           | Precision, Denoise                         | Halo reduction around edges                                 |
| `grain` (0–0.1)  | Precision                                  | Adds film grain                                             |
| `recover_detail` | Precision                                  | Higher values preserve more original detail                 |
| `softness` (1–5) | Starlight — **Starlight Precise 2.6 only** | 1 is sharpest, 5 is softest                                 |
| `creativity`     | Astra                                      | How much new detail is invented (0 = faithful, 1 = maximum) |
| `realism`        | Astra                                      | Biases invented detail toward photorealism                  |
| `sharp`          | Astra                                      | Output sharpness (0.5 is neutral passthrough)               |

### `target_fps`

Target frame rate for frame interpolation, available on Precision, Starlight, Starlight Fast, Astra (16–60), and Interpolate (16–120, default 60). On the upscaling endpoints, output at 48 fps or higher doubles the price. On Interpolate, the price scales linearly with the output frame rate.

### `slowdown_factor`

Interpolate only. Slow-motion factor `1` (default), `2`, `4`, or `8` — the output is proportionally longer and billed accordingly (a 2x slowdown doubles the billed duration).

### `output_format`

Hyperion only. `mp4` (default) delivers 10-bit H.265 HDR10; `prores` delivers 10-bit ProRes 422 HQ in a `.mov` for grading and finishing pipelines (much larger files).

### `h264_output`

Available on Precision, Starlight, Starlight Fast, Astra, Interpolate, Denoise, Deblur, and Colorize. Output H.264 instead of the default H.265 — use when your player or pipeline doesn't support H.265.

<Warning>
  H.264 output is limited to 4K. Requests whose output would exceed 4K (for example a 1080p source at `upscale_factor` 4) are rejected with a validation error — keep the default H.265 for those.
</Warning>

### `prompt` (Astra only)

An optional text prompt guiding the detail Astra 2 invents. When set, the input video is limited to 450 frames (e.g. 15s at 30 fps).

```json theme={"system"}
{
  "model": "topaz-video-astra",
  "video_url": "https://example.com/clip.mp4",
  "prompt": "cinematic wildlife footage, crisp feather detail",
  "creativity": 0.8
}
```

## Pricing

Enhancement models bill per second of output video, tiered by output resolution. Get an exact quote from the [Video Quote API](/api-reference/endpoint/video/quote) before generating — quotes account for the detected source metadata and the price-affecting settings (`enhancement_model`, `target_fps`, `slowdown_factor`).

| Model                   | ≤720p      | 1080p      | 4K         |
| ----------------------- | ---------- | ---------- | ---------- |
| Precision               | \$0.0125/s | \$0.025/s  | \$0.075/s  |
| Starlight               | \$0.15/s   | \$0.15/s   | \$0.325/s  |
| Starlight Fast          | \$0.075/s  | \$0.075/s  | \$0.1625/s |
| Astra                   | \$0.375/s  | \$0.375/s  | \$0.625/s  |
| Hyperion                | \$0.30/s   | \$0.30/s   | \$0.6375/s |
| Interpolate (at 60 fps) | \$0.0375/s | \$0.0375/s | \$0.125/s  |
| Denoise                 | \$0.025/s  | \$0.025/s  | \$0.075/s  |
| Deblur                  | \$0.0125/s | \$0.0125/s | \$0.0375/s |
| Colorize                | \$0.0125/s | \$0.0125/s | \$0.0375/s |

Rates above are the base model rates. Gaia 2 and Nyx Fast bill at half; Aion at \~2.7x; Proteus Natural is cheaper at 4K. Output at 48 fps or higher doubles the price on the upscaling endpoints; Interpolate scales linearly with the output frame rate.

## Supported inputs

* **Formats**: MP4, MOV, WebM
* **Input methods**: HTTPS URL or `data:video/...;base64,...` data URL
* **Max duration**: 300 seconds (5 minutes)
* **Output**: H.265 MP4 by default (H.264 with `h264_output`, ProRes for Hyperion with `output_format`)

## Examples

### Restore a compressed archive clip (Starlight)

```bash 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-starlight",
    "video_url": "https://example.com/archive.mp4",
    "upscale_factor": 2,
    "enhancement_model": "Starlight Precise 2.6",
    "softness": 2
  }'
```

### Denoise high-ISO footage (Denoise)

```bash 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-denoise",
    "video_url": "https://example.com/high-iso.mp4",
    "enhancement_model": "Nyx XL",
    "noise": 0.8
  }'
```

### Convert SDR to HDR for grading (Hyperion, ProRes)

```bash 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-hyperion",
    "video_url": "https://example.com/flat-sdr.mp4",
    "output_format": "prores"
  }'
```

### Slow motion (Interpolate)

```bash 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-interpolate",
    "video_url": "https://example.com/action.mp4",
    "target_fps": 120,
    "slowdown_factor": 2
  }'
```