> ## 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.

> ## Agent Instructions
> The Venice API is OpenAI-compatible: use any OpenAI SDK with the base URL `https://api.venice.ai/api/v1` and a Venice API key, or pay per request from a USDC wallet through x402 with no account.
> Read model IDs from `GET /models` or `GET /models/traits` at runtime instead of hardcoding them from memory or from these pages. Models are added and retired often.
> Every model's price is in https://docs.venice.ai/pricing.md. Quote video and audio jobs with `POST /video/quote` or `POST /audio/quote` before you queue them.
> Search these docs from an MCP client at https://docs.venice.ai/mcp. The full agent guide is https://docs.venice.ai/agents.md.

# Video-Upscaling

> Verbessern Sie Videoauflösung und -qualität mit dem topaz-video-upscale-Modell in Venices asynchroner Video-Queue, mit 1x-, 2x- oder 4x-Upscaling.

Mit Video-Upscaling kannst du vorhandene Videos in höhere Auflösungen heben und gleichzeitig die visuelle Qualität verbessern. Das **Topaz-Video-Upscale**-Modell nutzt KI-basiertes Upscaling, um die Auflösung 2× oder 4× zu erhöhen, oder wendet bei 1× eine Qualitätsverbesserung in der Original-Auflösung an.

## Wie es funktioniert

Video-Upscaling nutzt dasselbe asynchrone Queue-System wie die Videogenerierung:

1. **Queue** — Video an `/video/queue` mit Modell `topaz-video-upscale` senden
2. **Poll** — `/video/retrieve` mit `model` und der zurückgegebenen `queue_id` aufrufen. Während der Job läuft, kommt JSON mit `"status": "PROCESSING"` zurück. Ist der Job fertig, ist der Response-Body das hochskalierte MP4 (`Content-Type: video/mp4`), also speicherst du ihn in einer Datei. Es gibt keine Output-URL.
3. **Aufräumen (optional)** — Nachdem du die Datei gespeichert hast, `/video/complete` aufrufen, um den gespeicherten Output zu löschen

Der Server erkennt Dauer, Bildrate und Dimensionen des Input-Videos automatisch aus der hochgeladenen Datei. Du musst diese Werte nicht angeben – die Abrechnung erfolgt anhand der tatsächlichen Videometadaten.

## Upscale-Faktoren

| `upscale_factor` | Output-Auflösung | Anwendungsfall |
| - | - | - |
| `1` | Wie Input | Nur Qualitätsverbesserung (Denoising, Sharpening) |
| `2` (Default) | 2× Input-Dimensionen | Standard-Upscale – 720p-Input wird 1440p-Output |
| `4` | 4× Input-Dimensionen | Maximales Upscale – 480p-Input wird 1920p-Output |

> [!NOTE]
>
> Der Parameter `upscale_factor` ersetzt `resolution` bei Upscale-Modellen. Wird `resolution` übergeben, gibt es einen Fehler. Das liegt daran, dass die Output-Auflösung von den Input-Dimensionen abhängt – ein `2×`-Upscale eines 720p-Videos ergibt etwas anderes als ein `2×`-Upscale eines 480p-Videos.

## Unterstützte Eingabeformate

* **Formate**: MP4, MOV, WebM
* **Input-Methoden**: HTTPS-URL oder `data:video/...;base64,...`-Data-URL
* **Max. Dauer**: 300 Sekunden (5 Minuten)

## API-Nutzung

### Upscale-Job in die Queue stellen

```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"]
download_url = data.get("download_url")
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, download_url } = await response.json();
console.log(`Queued: ${queue_id}`);
```

Die Antwort enthält eine `queue_id`, um den Job zu verfolgen:

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

### Pollen und Ergebnis speichern

```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 '{"model": "topaz-video-upscale", "queue_id": "abc123-def456-..."}' \
  -o upscaled.mp4 \
  -w '%{content_type}\n'
```

```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={"model": "topaz-video-upscale", "queue_id": queue_id},
    )
    result.raise_for_status()

    if "video/mp4" in result.headers.get("Content-Type", ""):
        with open("upscaled.mp4", "wb") as f:
            f.write(result.content)
        break

    if result.json().get("status") == "COMPLETED" and download_url:
        with open("upscaled.mp4", "wb") as f:
            f.write(requests.get(download_url).content)
        break

    time.sleep(5)

print("Saved upscaled.mp4")
```

```javascript Node.js theme={"system"}
import { writeFile } from "node:fs/promises";

const poll = async (queueId, downloadUrl) => {
  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({ model: "topaz-video-upscale", queue_id: queueId }),
    });
    if (!res.ok) {
      throw new Error(`${res.status}: ${await res.text()}`);
    }

    if (res.headers.get("Content-Type")?.includes("video/mp4")) {
      await writeFile("upscaled.mp4", Buffer.from(await res.arrayBuffer()));
      return;
    }

    const data = await res.json();
    if (data.status === "COMPLETED" && downloadUrl) {
      const video = await fetch(downloadUrl);
      await writeFile("upscaled.mp4", Buffer.from(await video.arrayBuffer()));
      return;
    }

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

await poll(queue_id, download_url);
console.log("Saved upscaled.mp4");
```

Das fertige Upscale ist der Response-Body selbst, kein JSON-Feld. Prüfe daher `Content-Type`, bevor du die Antwort parst. Das cURL-Beispiel gibt den Content-Type jeder Antwort aus: Wiederhole den Aufruf, bis `video/mp4` ausgegeben wird. Dann enthält `upscaled.mp4` das Video. Wenn die Queue-Antwort eine `download_url` enthielt, gibt retrieve stattdessen JSON mit `"status": "COMPLETED"` zurück, und du lädst die Datei von dieser URL herunter. Siehe [Private Download-Links](https://docs.venice.ai/de/guides/media/video-generation.md#private-download-links).

### Aufräumen (optional)

Nachdem du das MP4 gespeichert hast, kannst du `/video/complete` aufrufen, um den gespeicherten Output zu löschen. Der Aufruf gibt weder das Video noch eine URL zurück.

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

***

## API-Parameter

| Feld | Typ | Pflicht | Beschreibung |
| - | - | - | - |
| `model` | string | **Ja** | Muss `topaz-video-upscale` sein |
| `video_url` | string | **Ja** | Input-Video-URL oder Data-URL. Unterstützte Formate: MP4, MOV, WebM. |
| `upscale_factor` | number | Nein | `1`, `2` (Default) oder `4`. Steuert den Upscale-Multiplikator. |

### Bei Upscale-Modellen nicht verwendete Parameter

Die folgenden Parameter werden bei `topaz-video-upscale` **nicht akzeptiert** und führen zu einem Fehler:

| Feld | Grund |
| - | - |
| `resolution` | Stattdessen `upscale_factor` verwenden. Die Output-Auflösung hängt von den Input-Dimensionen ab. |
| `prompt` | Upscaling nutzt keine Text-Prompts. Ein leerer String wird automatisch gesetzt. |

Der Parameter `duration` wird ebenfalls ignoriert – der Server erkennt die Dauer für die Abrechnungsgenauigkeit direkt aus der Videodatei.

***

## Preise

Die Preise basieren auf **Dauer**, **Output-Auflösungs-Tier** und **Bildrate**. Der Output-Auflösungs-Tier ergibt sich aus der Höhe des Input-Videos multipliziert mit dem Upscale-Faktor.

### Output-Auflösungs-Tiers

| Tier | Output-Höhe | Pro-Sekunde-Rate |
| - | - | - |
| 720p | ≤ 720 px | \~\$0,013 |
| 1080p | 721–1080 px | \~\$0,025 |
| 4K | > 1080 px | \~\$0,10 |

> [!NOTE]
>
> Videos mit Bildraten über 48 fps kosten das 2-fache der Pro-Sekunde-Rate.

### Preisbeispiele

| Input | Upscale-Faktor | Output | Dauer | Geschätzte Kosten |
| - | - | - | - | - |
| 480p, 30fps | 2× | 960p (1080p-Tier) | 10 s | \~\$0,25 |
| 720p, 30fps | 2× | 1440p (4K-Tier) | 10 s | \~\$1,00 |
| 1080p, 30fps | 2× | 2160p (4K-Tier) | 30 s | \~\$3,00 |
| 360p, 24fps | 4× | 1440p (4K-Tier) | 10 s | \~\$1,00 |
| 480p, 60fps | 2× | 960p (1080p-Tier) | 10 s | \~\$0,50 |

Nutze die [Video-Quote-API](https://docs.venice.ai/api-reference/endpoint/video/quote.md), um vor dem Einreichen die genauen Kosten zu erhalten.

### Quote abrufen

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

`video_url` ist für Quotes auf Upscale-Modellen **erforderlich** – der Quote-Endpoint ruft die Datei ab und ermittelt Dauer, FPS und Höhe aus den Bytes, sodass du sie nicht angeben musst. Wird es weggelassen, kommt `400` mit *"video\_url is required for quotes on this model"* zurück.

Quotes für Upscale-Modelle erfordern einen API-Schlüssel. Requests ohne Schlüssel geben `403` zurück.

Übergib an `/video/quote` denselben `upscale_factor` (`1`, `2` oder `4`), den du auch an `/video/queue` senden wirst, damit das Quote zum Job passt. Quote akzeptiert bei Upscale-Modellen außerdem `resolution` (`"2x"` oder `"4x"`) als veralteten Alias; werden beide gesendet, hat `upscale_factor` Vorrang.

***

## Fehlerbehebung

| Problem | Wahrscheinliche Ursache | Lösung |
| - | - | - |
| `"Use upscale_factor instead of resolution"` | `resolution` wurde im Request übergeben | `resolution` entfernen und stattdessen `upscale_factor` verwenden |
| Höhere Kosten als erwartet | Input-Video hat hohe Auflösung oder hohe FPS | Input-Dimensionen über den Quote-Endpoint prüfen. 720p+-Input mit 2×-Upscale landet im 4K-Pricing-Tier. |
| Job dauert lange | Großes oder langes Video | Upscaling ist rechenintensiv. Längere Videos und höhere Upscale-Faktoren brauchen proportional länger. |
| `"Insufficient balance"` | Kontoguthaben zu niedrig | Credits unter [venice.ai/settings/api](https://venice.ai/settings/api?utm_source=venice-api-documentation) aufladen |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.