> 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/video-quickstart.md).

# Video Quickstart

Get started with our Video API

Before we proceed, you need to create an [API key](https://account.topazlabs.com/manage-api).

This key will be used to authenticate your requests to the Topaz Labs API.

<details>

<summary>How do I get my API key?</summary>

In order to get access to the API, you'll need to [log into](http://topazlabs.com/account) your Topaz Labs account and create your unique API key. If you don't have an account, please follow the link [here](https://topazlabs.com/wp-login.php?action=register) to register.

Once you have an account, follow the below steps:

1. Log into your Topaz Labs account from our [website](https://topazlabs.com/my-account/)
2. Navigate to the **API** tab section on your account page
3. Click "Create API Key", then enter a "Key name" and other prompted information
4. Click "Create API Key" to confirm your inputted information
5. Click "Copy API Key" to copy it to your clipboard and store it in a safe place

{% hint style="warning" %}
You may only view your API key on creation, so please be sure to copy the key as it will no longer be visible to you once you exit the page. If you lose your key, you may log into your account portal to manage your existing keys and generate new ones.
{% endhint %}

</details>

Now, proceed with the below steps.

{% stepper %}
{% step %}

### Create Video Request

Create a video request—just include some details about the source video, output parameters, and desired enhancements.

{% hint style="info" %}
Visit out [API Reference](https://developer.topazlabs.com/reference/) page for up-to-date functionality. This endpoint is free to use.
{% endhint %}

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

```bash
curl --request POST \
     --url https://api.topazlabs.com/video/ \
     --header 'X-API-Key: Your-API-Key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
     {
          "source": {
               "resolution": {
                    "width": 800,
                    "height": 448
               },
               "container": "mp4",
               "size": 477010,
               "duration": 4,
               "frameRate": 24,
               "frameCount": 97
          },
          "output": {
               "resolution": {
                    "width": 800,
                    "height": 448
               },
               "audioCodec": "AAC",
               "audioTransfer": "Copy",
               "frameRate": 24,
               "dynamicCompressionLevel": "High",
               "container": "mp4"
          },
          "filters": [ {
               "model": "prob-4",
               "auto": "Auto"
               } ]
     }'
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch('https://api.topazlabs.com/video/', {
  method: 'POST',
  headers: {
    'X-API-Key': 'Your-API-Key',
    accept: 'application/json',
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    source: {
      resolution: { width: 800, height: 448 },
      container: 'mp4',
      size: 477010,
      duration: 4,
      frameRate: 24,
      frameCount: 97,
    },
    output: {
      resolution: { width: 800, height: 448 },
      audioCodec: 'AAC',
      audioTransfer: 'Copy',
      frameRate: 24,
      dynamicCompressionLevel: 'High',
      container: 'mp4',
    },
    filters: [{
      model: 'prob-4',
      auto: 'Auto',
    }],
  }),
});

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

{% endtab %}

{% tab title="Python" %}

```python
import requests

response = requests.post(
    "https://api.topazlabs.com/video/",
    headers={
        "X-API-Key": "Your-API-Key",
        "accept": "application/json"
    },
    json={
        "source": {
            "resolution": {"width": 800, "height": 448},
            "container": "mp4",
            "size": 477010,
            "duration": 4,
            "frameRate": 24,
            "frameCount": 97
        },
        "output": {
            "resolution": {"width": 800, "height": 448},
            "audioCodec": "AAC",
            "audioTransfer": "Copy",
            "frameRate": 24,
            "dynamicCompressionLevel": "High",
            "container": "mp4"
        },
        "filters": [{
            "model": "prob-4",
            "auto": "Auto"
        }]
    }
)

print(response.json())
```

{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

### Accept & Upload Video Request

After submitting the video request, you can choose to continue by calling this endpoint.

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

```bash
curl --request PATCH \
     --url https://api.topazlabs.com/video/[your-requestID]/accept \
     --header 'X-API-Key: Your-API-Key' \
     --header 'accept: application/json'
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch(
  'https://api.topazlabs.com/video/[your-requestID]/accept',
  {
    method: 'PATCH',
    headers: {
      'X-API-Key': 'Your-API-Key',
      accept: 'application/json',
    },
  },
);

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

{% endtab %}

{% tab title="Python" %}

```python
import requests

response = requests.patch(
    "https://api.topazlabs.com/video/[your-requestID]/accept",
    headers={
        "X-API-Key": "Your-API-Key",
        "accept": "application/json"
    }
)

print(response.json())
```

{% endtab %}
{% endtabs %}

Once this endpoint is called, you will receive a set of URL(s). You may use the following code snippet to upload the video to that link from your local device.

{% hint style="info" %}
In this example, we will upload the entire video file to a single URL due to its small file size.
{% endhint %}

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

```bash
S3_UPLOAD_URL=[https://...]

curl --verbose --request PUT \
     --upload-file "Your-Video-File" \
     --header "Content-Type: video/mp4" \
     "$S3_UPLOAD_URL"
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
import fs from 'fs';

const response = await fetch('https://...', {
  method: 'PUT',
  headers: { 'Content-Type': 'video/mp4' },
  body: fs.createReadStream('Your-Video-File'),
  duplex: 'half',
});

console.log(`eTag: ${response.headers.get('etag')}`);
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

with open("Your-Video-File", "rb") as video:
    response = requests.put(
        "https://...",
        headers={"Content-Type": "video/mp4"},
        data=video
    )

print(f"eTag: {response.headers.get('ETag')}")
```

{% endtab %}
{% endtabs %}

Once uploaded, you'll receive some information about your upload, including your *eTag* number. This will be useful for the next step.
{% endstep %}

{% step %}

### Complete Video Upload

After you have finished uploading your video segments, you may use the following request to confirm that all of your video segments have been received. Once this endpoint is called, you video will begin processing with its enhancements.

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

```bash
curl --request PATCH \
     --url https://api.topazlabs.com/video/[your-requestID]/complete-upload \
     --header 'X-API-Key: Your-API-Key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
       "uploadResults": [
         {
           "partNum": 1,
           "eTag": "your-eTag"
         }
       ]
     }'
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch(
  'https://api.topazlabs.com/video/[your-requestID]/complete-upload',
  {
    method: 'PATCH',
    headers: {
      'X-API-Key': 'Your-API-Key',
      accept: 'application/json',
      'content-type': 'application/json',
    },
    body: JSON.stringify({
      uploadResults: [{
        partNum: 1,
        eTag: 'your-eTag',
      }],
    }),
  },
);

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

{% endtab %}

{% tab title="Python" %}

```python
import requests

response = requests.patch(
    "https://api.topazlabs.com/video/[your-requestID]/complete-upload",
    headers={
        "X-API-Key": "Your-API-Key",
        "accept": "application/json"
    },
    json={
        "uploadResults": [{
            "partNum": 1,
            "eTag": "your-eTag"
        }]
    }
)

print(response.json())
```

{% endtab %}
{% endtabs %}

You should receive a response confirming that your request is queued for processing once you have called the endpoint.
{% endstep %}

{% step %}

### Get Video Status

You may use the following request to view the status of your video request

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

```bash
curl --request GET \
     --url https://api.topazlabs.com/video/[your-requestID]/status \
     --header 'X-API-Key: Your-API-Key' \
     --header 'accept: application/json'
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch(
  'https://api.topazlabs.com/video/[your-requestID]/status',
  {
    headers: {
      'X-API-Key': 'Your-API-Key',
      accept: 'application/json',
    },
  },
);

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

{% endtab %}

{% tab title="Python" %}

```python
import requests

response = requests.get(
    "https://api.topazlabs.com/video/[your-requestID]/status",
    headers={
        "X-API-Key": "Your-API-Key",
        "accept": "application/json"
    }
)

print(response.json())
```

{% endtab %}
{% endtabs %}

Once your video has finished processing, you will receive a link to download your video as a response to this endpoint.
{% endstep %}
{% endstepper %}

## Complete Programmatic Example

The examples below run the same complete workflow programmatically: create the request, accept it, upload the source video, complete the upload, poll until processing finishes, and download the result. They use a single upload URL for this small example. The cURL example also requires `jq`.

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

```bash
VIDEO_BASE="https://api.topazlabs.com/video"
INPUT_FILE="input.mp4"
OUTPUT_FILE="output.mp4"

# Create the request
request=$(curl --silent --fail-with-body \
  --request POST "$VIDEO_BASE/" \
  --header "X-API-Key: $TOPAZ_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "source": {
      "resolution": {
        "width": 800,
        "height": 448
      },
      "container": "mp4",
      "size": 477010,
      "duration": 4,
      "frameRate": 24,
      "frameCount": 97
    },
    "filters": [{
      "model": "prob-4",
      "auto": "Auto"
    }],
    "output": {
      "resolution": {
        "width": 1600,
        "height": 896
      },
      "audioTransfer": "Copy",
      "audioCodec": "AAC",
      "frameRate": 24,
      "dynamicCompressionLevel": "High",
      "container": "mp4"
    }
  }')

request_id=$(printf '%s' "$request" | jq -r '.requestId')

# Accept the request and get the upload URL
accepted=$(curl --silent --fail-with-body \
  --request PATCH "$VIDEO_BASE/$request_id/accept" \
  --header "X-API-Key: $TOPAZ_API_KEY")
upload_url=$(printf '%s' "$accepted" | jq -r '.urls[0]')

# Upload the source video
etag=$(curl --silent --show-error --fail-with-body \
  --request PUT \
  --upload-file "$INPUT_FILE" \
  --header "Content-Type: video/mp4" \
  --dump-header - \
  --output /dev/null \
  "$upload_url" |
  awk 'tolower($1) == "etag:" { gsub("\r", "", $2); print $2 }')

# Complete the upload
complete_body=$(jq -n --arg etag "$etag" \
  '{uploadResults: [{partNum: 1, eTag: $etag}]}')
curl --silent --show-error --fail-with-body \
  --request PATCH "$VIDEO_BASE/$request_id/complete-upload/" \
  --header "X-API-Key: $TOPAZ_API_KEY" \
  --header "Content-Type: application/json" \
  --data "$complete_body"

# Poll until processing finishes
while true; do
  status_response=$(curl --silent --fail-with-body \
    --header "X-API-Key: $TOPAZ_API_KEY" \
    "$VIDEO_BASE/$request_id/status")
  status=$(printf '%s' "$status_response" | jq -r '.status | ascii_downcase')
  echo "Status: $status"

  case "$status" in
    complete)
      download_url=$(printf '%s' "$status_response" | jq -r '.download.url')
      break
      ;;
    failed|canceled|cancelled)
      printf '%s\n' "$status_response" >&2
      exit 1
      ;;
  esac

  sleep 5
done

# Download the processed video
curl --silent --show-error --fail-with-body \
  --location "$download_url" \
  --output "$OUTPUT_FILE"

echo "Saved $OUTPUT_FILE"
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
import fs from 'node:fs';
import { Readable } from 'node:stream';
import { pipeline } from 'node:stream/promises';

const API_KEY = process.env.TOPAZ_API_KEY;
const VIDEO_BASE = 'https://api.topazlabs.com/video';
const INPUT_FILE = 'input.mp4';
const OUTPUT_FILE = 'output.mp4';
const HEADERS = { 'X-API-Key': API_KEY };

async function jsonOrThrow(response) {
  if (!response.ok) {
    throw new Error(`${response.status}: ${await response.text()}`);
  }
  return response.json();
}

// Create the request
const request = await jsonOrThrow(await fetch(`${VIDEO_BASE}/`, {
  method: 'POST',
  headers: {
    ...HEADERS,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    source: {
      resolution: {
        width: 800,
        height: 448,
      },
      container: 'mp4',
      size: 477010,
      duration: 4,
      frameRate: 24,
      frameCount: 97,
    },
    filters: [{
      model: 'prob-4',
      auto: 'Auto',
    }],
    output: {
      resolution: {
        width: 1600,
        height: 896,
      },
      audioTransfer: 'Copy',
      audioCodec: 'AAC',
      frameRate: 24,
      dynamicCompressionLevel: 'High',
      container: 'mp4',
    },
  }),
}));

const requestId = request.requestId;

// Accept the request and get the upload URL
const accepted = await jsonOrThrow(await fetch(
  `${VIDEO_BASE}/${requestId}/accept`,
  {
    method: 'PATCH',
    headers: HEADERS,
  },
));
const uploadUrl = accepted.urls[0];

// Upload the source video
const uploadResponse = await fetch(uploadUrl, {
  method: 'PUT',
  headers: { 'Content-Type': 'video/mp4' },
  body: fs.createReadStream(INPUT_FILE),
  duplex: 'half',
});
if (!uploadResponse.ok) {
  throw new Error(`Upload failed: ${uploadResponse.status}`);
}
const eTag = uploadResponse.headers.get('etag');
if (!eTag) {
  throw new Error('Upload response did not include an eTag');
}

// Complete the upload
const completeResponse = await fetch(
  `${VIDEO_BASE}/${requestId}/complete-upload/`,
  {
    method: 'PATCH',
    headers: {
      ...HEADERS,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      uploadResults: [{
        partNum: 1,
        eTag,
      }],
    }),
  },
);
if (!completeResponse.ok) {
  throw new Error(
    `${completeResponse.status}: ${await completeResponse.text()}`,
  );
}

// Poll until processing finishes
let downloadUrl;
while (!downloadUrl) {
  await new Promise(resolve => setTimeout(resolve, 5000));
  const result = await jsonOrThrow(await fetch(
    `${VIDEO_BASE}/${requestId}/status`,
    { headers: HEADERS },
  ));
  const status = result.status.toLowerCase();
  console.log(`Status: ${status}`);

  if (status === 'complete') {
    downloadUrl = result.download.url;
  } else if (['failed', 'canceled', 'cancelled'].includes(status)) {
    throw new Error(`Processing ${status}: ${JSON.stringify(result)}`);
  }
}

// Download the processed video
const downloadResponse = await fetch(downloadUrl);
if (!downloadResponse.ok || !downloadResponse.body) {
  throw new Error(`Download failed: ${downloadResponse.status}`);
}
await pipeline(
  Readable.fromWeb(downloadResponse.body),
  fs.createWriteStream(OUTPUT_FILE),
);

console.log(`Saved ${OUTPUT_FILE}`);
```

{% endtab %}

{% tab title="Python" %}

```python
import os
import time
import requests

API_KEY = os.environ["TOPAZ_API_KEY"]
VIDEO_BASE = "https://api.topazlabs.com/video"
INPUT_FILE = "input.mp4"
OUTPUT_FILE = "output.mp4"
HEADERS = {"X-API-Key": API_KEY}

# Create the request
response = requests.post(
    f"{VIDEO_BASE}/",
    headers=HEADERS,
    json={
        "source": {
            "resolution": {
                "width": 800,
                "height": 448
            },
            "container": "mp4",
            "size": 477010,
            "duration": 4,
            "frameRate": 24,
            "frameCount": 97
        },
        "filters": [{
            "model": "prob-4",
            "auto": "Auto"
        }],
        "output": {
            "resolution": {
                "width": 1600,
                "height": 896
            },
            "audioTransfer": "Copy",
            "audioCodec": "AAC",
            "frameRate": 24,
            "dynamicCompressionLevel": "High",
            "container": "mp4"
        }
    }
)
response.raise_for_status()
request = response.json()
request_id = request["requestId"]

# Accept the request and get the upload URL
accept_response = requests.patch(
    f"{VIDEO_BASE}/{request_id}/accept",
    headers=HEADERS
)
accept_response.raise_for_status()
upload_url = accept_response.json()["urls"][0]

# Upload the source video
with open(INPUT_FILE, "rb") as video:
    upload_response = requests.put(
        upload_url,
        headers={"Content-Type": "video/mp4"},
        data=video
    )
upload_response.raise_for_status()
e_tag = upload_response.headers["ETag"]

# Complete the upload
complete_response = requests.patch(
    f"{VIDEO_BASE}/{request_id}/complete-upload/",
    headers=HEADERS,
    json={
        "uploadResults": [{
            "partNum": 1,
            "eTag": e_tag
        }]
    }
)
complete_response.raise_for_status()

# Poll until processing finishes
while True:
    time.sleep(5)
    status_response = requests.get(
        f"{VIDEO_BASE}/{request_id}/status",
        headers=HEADERS
    )
    status_response.raise_for_status()
    result = status_response.json()
    status = result["status"].lower()
    print(f"Status: {status}")

    if status == "complete":
        download_url = result["download"]["url"]
        break
    if status in ("failed", "canceled", "cancelled"):
        raise RuntimeError(f"Processing {status}: {result}")

# Download the processed video
with requests.get(download_url, stream=True) as download_response:
    download_response.raise_for_status()
    with open(OUTPUT_FILE, "wb") as output:
        for chunk in download_response.iter_content(chunk_size=1024 * 1024):
            output.write(chunk)

print(f"Saved {OUTPUT_FILE}")
```

{% endtab %}
{% endtabs %}

Congratulations! You have just completed your first Video API request! 🎉

We have now made popular video models such as Starlight Precise 2.6 and Astra 2 available as ready-to-use APIs so that you can easily integrate them into your applications.

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-cover data-type="image">Cover image</th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><a class="button secondary medium">Video | Generative</a></td><td><h4>Starlight Precise 2.6</h4></td><td>Upscale AI-generated and archival video to 4K with realistic faces, textures, and text.</td><td></td><td><a href="https://developer.topazlabs.com/video-models/upscaling-and-enhancement/generative/starlight-precise-2.6.md">Starlight Precise 2.6</a></td></tr><tr><td><a class="button secondary medium">Video | Creative</a></td><td><h4>Astra 2</h4></td><td>Transform AI-generated and stylized video with bold new detail and prompt-guided direction.</td><td></td><td><a href="https://developer.topazlabs.com/video-models/upscaling-and-enhancement/creative/astra-2.md">Astra 2</a></td></tr></tbody></table>

Once you find a model that you want to use in our "Models" tab, you can grab the URL from the model's dedicated page. Individual model pages also provide some important information about the model including use cases and examples of how you can call it.

Check out our [Model Playground](https://playground.topazlabs.com/) to tinker with these models and let us know your feedback and questions on our [Developer Discord](https://discord.gg/pUqhyZvRHD).

<details>

<summary>How do I make an API call from the API Playground?</summary>

<figure><img src="https://938351258-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fik4tc42rkpL9SRR51NLK%2Fuploads%2FOkn9w1ictjQN1DOGOys7%2FScreen%20Recording%20Jul%2015%202025%20from%20Topaz%20Labs.gif?alt=media&amp;token=de2207ed-75b8-4862-9386-a5ef447fe0d7" alt=""><figcaption></figcaption></figure>

It's now easier more than ever to create and send your first API request. Once you have a Topaz Labs account and you have created your first API key, navigate over to our [API Playground](https://playground.topazlabs.com/) to better understand how to build requests. Please see the walkthrough above for an example of an image being upscaled with our Enhance Synchronous endpoint on the Image API.

</details>

### More Information

<details>

<summary>API Restrictions</summary>

* The API has access rate limits depending on the current load on the servers. If you receive a HTTP 429 response, please try again (soon). We recommend using an exponential backoff for the requests to avoid immediately hitting the limit again.
* The API only responds to HTTPS-secured communications. Any requests sent via HTTP return an HTTP 301 redirect to the corresponding HTTPS resources.
* The API enforces a request size limit of 500MB. If a request exceeds this limit, the server responds with an HTTP 413. Please ensure that requests stay within the size constraint to avoid this error.

</details>

Please reach out to <help@topazlabs.com> with any questions.

### Next Steps

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-cube">:cube:</i></td><td><h4>Model Selection</h4></td><td>Find the best model for your use case.</td><td><a href="https://developer.topazlabs.com/getting-started/model-selection.md">Model Selection</a></td></tr></tbody></table>


---

# 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/video-quickstart.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.
