> For the complete documentation index, see [llms.txt](https://developer.topazlabs.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.topazlabs.com/getting-started/request-parameters/video.md).

# Video

Find the request-level parameters for all video endpoints

Every video model, on every video endpoint, takes the same request parameters. Create a request with either endpoint:

| Endpoint                                       | Use When                                                                                                                                                                                                                                       |
| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST https://api.topazlabs.com/video/`        | You can supply full source metadata and want a credit estimate before uploading. Follow with `PATCH /video/{requestId}/accept` and `PATCH /video/{requestId}/complete-upload/`.                                                                |
| `POST https://api.topazlabs.com/video/express` | You only know the container. Returns upload URLs right away, with no accept or complete-upload steps. **Note that this endpoint is only available for GAN models (i.e. most creative and generative upscaling models will not be supported).** |

Requests are JSON with four top-level objects: `source`, `filters`, `output`, and the optional `destination` and `notifications`. The models you put in `filters` decide a few `output` rules; see [Upscaling vs. Frame Interpolation](#upscaling-vs.-frame-interpolation).

## `source`

Describes the input video. On `POST /video/` every field except `md5Hash` and `external` is required so we can estimate the cost. On `POST /video/express` only `container` is required.

| Parameter           | Type      | Required / Default  | Accepted values                                                                                                                                    | Description                                                                                                                                                                                                                                   |
| ------------------- | --------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source.container`  | `string`  | Required            | `3gp`, `avi`, `dv`, `flv`, `m1v`, `m2t`, `m2ts`, `m2v`, `m4v`, `mkv`, `mov`, `mp4`, `mpeg`, `mpg`, `mts`, `mxf`, `ser`, `ts`, `vob`, `webm`, `wmv` | Container of the source file. Case-insensitive.                                                                                                                                                                                               |
| `source.size`       | `integer` | Required on /video/ | —                                                                                                                                                  | File size in bytes. Must be under 100 GB.                                                                                                                                                                                                     |
| `source.duration`   | `number`  | Required on /video/ | —                                                                                                                                                  | Duration in seconds.                                                                                                                                                                                                                          |
| `source.frameCount` | `integer` | Required on /video/ | —                                                                                                                                                  | Total number of frames.                                                                                                                                                                                                                       |
| `source.frameRate`  | `number`  | Required on /video/ | —                                                                                                                                                  | Frame rate in frames per second.                                                                                                                                                                                                              |
| `source.resolution` | `object`  | Required on /video/ | —                                                                                                                                                  | Source `width` and `height` in pixels.                                                                                                                                                                                                        |
| `source.md5Hash`    | `string`  | Optional            | —                                                                                                                                                  | MD5 hash of the source file, used to verify the upload.                                                                                                                                                                                       |
| `source.external`   | `object`  | Optional            | —                                                                                                                                                  | Read the source from your own S3 storage instead of uploading it, using a presigned URL or AWS AssumeRole. `provider` is required inside this object. See the [API Reference](https://developer.topazlabs.com/reference/) for the full shape. |

## `filters`

| Parameter | Type    | Required / Default | Accepted values | Description                                                                                                                                                                                                                                                                                                                                   |
| --------- | ------- | ------------------ | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `filters` | `array` | Required           | —               | One or more filter objects, applied in order. Each object needs a `model` value plus that model's settings, which are listed on each model's page under **Model Parameters**. Chain filters to combine operations, for example a denoise model followed by an upscaling model, or an upscaling model followed by a frame interpolation model. |

## `output`

| Parameter                        | Type      | Required / Default                                               | Accepted values                        | Description                                                                                                                                                                                           |
| -------------------------------- | --------- | ---------------------------------------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `output.resolution`              | `object`  | Required                                                         | —                                      | Output `width` and `height` in pixels. Rounded up to a multiple of 4. Forced to the source resolution when no upscaling model is in `filters`.                                                        |
| `output.frameRate`               | `number`  | Required on /video/                                              | —                                      | Output frame rate. Forced to the source frame rate when no frame interpolation model is in `filters`. On `/video/express`, required only when a frame interpolation filter doesn't set its own `fps`. |
| `output.audioTransfer`           | `string`  | <p>Required on /video/<br>Express default: <code>None</code></p> | `Copy`, `Convert`, `None`              | How to handle the source audio track.                                                                                                                                                                 |
| `output.audioCodec`              | `string`  | Optional                                                         | `AAC`, `AC3`, `PCM`                    | Audio codec for the output. Required when `audioTransfer` isn't `None`.                                                                                                                               |
| `output.audioBitrate`            | `string`  | Optional                                                         | —                                      | Audio bitrate for the output.                                                                                                                                                                         |
| `output.videoEncoder`            | `string`  | <p>Optional<br>Default: <code>H265</code></p>                    | `H265`, `H264`, `AV1`, `ProRes`, `VP9` | Video encoder for the output. See [Supported Encoders and Profiles](#supported-encoders-and-profiles).                                                                                                |
| `output.videoProfile`            | `string`  | <p>Optional<br>Default: <code>encoder default</code></p>         | —                                      | Profile for the chosen encoder. See [Supported Encoders and Profiles](#supported-encoders-and-profiles).                                                                                              |
| `output.videoBitrate`            | `string`  | Optional                                                         | —                                      | Target video bitrate. Required for `VP9`. Can't be combined with `dynamicCompressionLevel`.                                                                                                           |
| `output.dynamicCompressionLevel` | `string`  | <p>Optional<br>Default: <code>High</code></p>                    | `Low`, `Mid`, `High`                   | Quality-based bitrate control, used when `videoBitrate` isn't set. `AV1`, `H264`, and `H265` only.                                                                                                    |
| `output.cropToFit`               | `boolean` | Optional                                                         | —                                      | Crop the output to fill `output.resolution` instead of letterboxing when the aspect ratios differ.                                                                                                    |
| `output.container`               | `string`  | <p>Optional<br>Default: <code>mp4</code></p>                     | `mp4`, `mov`, `mkv`                    | Output container. `ProRes` always outputs `mov`; `AV1` and `VP9` always output `mp4`.                                                                                                                 |

## `destination` and `notifications`

| Parameter                  | Type     | Required / Default | Accepted values | Description                                                                        |
| -------------------------- | -------- | ------------------ | --------------- | ---------------------------------------------------------------------------------- |
| `destination.external`     | `object` | Optional           | —               | Write the output directly to your own S3 storage. Same shape as `source.external`. |
| `notifications.webhookUrl` | `string` | Optional           | —               | URL we `POST` a JSON notification to when the request completes or fails.          |

## Upscaling vs. Frame Interpolation

The request parameters are the same for every model. What changes is which `output` values the API honors, based on the models in `filters`:

| Models in `filters`                   | `output.resolution`             | `output.frameRate`                                          |
| ------------------------------------- | ------------------------------- | ----------------------------------------------------------- |
| Upscaling or enhancement only         | Used as the output size         | Forced to the source frame rate                             |
| Frame interpolation only              | Forced to the source resolution | Used as the output frame rate, unless the filter sets `fps` |
| Both (upscale, then interpolate)      | Used as the output size         | Used as the output frame rate, unless the filter sets `fps` |
| Neither (for example, denoising only) | Forced to the source resolution | Forced to the source frame rate                             |

Upscaling, denoising, SDR-to-HDR, and utility models all use the upscaling rules.

## Supported Encoders and Profiles

| Encoder (videoEncoder) | Profiles (videoProfile)                          | Containers          | Max Resolution | Max Bitrate |
| ---------------------- | ------------------------------------------------ | ------------------- | -------------- | ----------- |
| `H265`                 | `Main10` (default), `Main`                       | `mp4`, `mov`, `mkv` | 8192 × 8192    | 2000 Mbps   |
| `H264`                 | `High`                                           | `mp4`, `mov`, `mkv` | 4096 × 4096    | 2000 Mbps   |
| `AV1`                  | `8-bit` (default), `10-bit`                      | `mp4`               | 16384 × 8704   | 800 Mbps    |
| `ProRes`               | `422 HQ` (default), `422`, `422 LT`, `422 Proxy` | `mov`               | 16386 × 16386  | Uncapped    |
| `VP9`                  | `Good` (default), `Best`                         | `mp4`               | 8192 × 8192    | 2000 Mbps   |

Max resolution applies in either orientation. Requesting a resolution or bitrate above the encoder's limit returns `400 INVALID_INPUT`.

## Example

{% tabs %}
{% tab title="cURL" %}

```bash
curl --request POST "https://api.topazlabs.com/video/" \
  --header "X-API-Key: $TOPAZ_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "source": {
      "container": "mp4",
      "size": 104857600,
      "duration": 30,
      "frameCount": 720,
      "frameRate": 24,
      "resolution": { "width": 1920, "height": 1080 }
    },
    "filters": [
      { "model": "prob-4" }
    ],
    "output": {
      "resolution": { "width": 3840, "height": 2160 },
      "frameRate": 24,
      "audioTransfer": "Copy",
      "audioCodec": "AAC",
      "videoEncoder": "H265",
      "videoProfile": "Main10",
      "container": "mp4"
    },
    "notifications": {
      "webhookUrl": "https://example.com/topaz-webhook"
    }
  }'
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch('https://api.topazlabs.com/video/', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.TOPAZ_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    source: {
      container: 'mp4',
      size: 104857600,
      duration: 30,
      frameCount: 720,
      frameRate: 24,
      resolution: { width: 1920, height: 1080 },
    },
    filters: [
      { model: 'prob-4' },
    ],
    output: {
      resolution: { width: 3840, height: 2160 },
      frameRate: 24,
      audioTransfer: 'Copy',
      audioCodec: 'AAC',
      videoEncoder: 'H265',
      videoProfile: 'Main10',
      container: 'mp4',
    },
    notifications: {
      webhookUrl: 'https://example.com/topaz-webhook',
    },
  }),
});

if (!response.ok) {
  throw new Error(`${response.status}: ${await response.text()}`);
}

console.log(await response.json());
```

{% endtab %}

{% tab title="Python" %}

```python
import os
import requests

response = requests.post(
    "https://api.topazlabs.com/video/",
    headers={"X-API-Key": os.environ["TOPAZ_API_KEY"]},
    json={
        "source": {
            "container": "mp4",
            "size": 104857600,
            "duration": 30,
            "frameCount": 720,
            "frameRate": 24,
            "resolution": {"width": 1920, "height": 1080}
        },
        "filters": [
            {"model": "prob-4"}
        ],
        "output": {
            "resolution": {"width": 3840, "height": 2160},
            "frameRate": 24,
            "audioTransfer": "Copy",
            "audioCodec": "AAC",
            "videoEncoder": "H265",
            "videoProfile": "Main10",
            "container": "mp4"
        },
        "notifications": {
            "webhookUrl": "https://example.com/topaz-webhook"
        }
    }
)

response.raise_for_status()
print(response.json())
```

{% endtab %}
{% endtabs %}

For the full schema, see the [API Reference](https://developer.topazlabs.com/reference/).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.topazlabs.com/getting-started/request-parameters/video.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.