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

# Video upscaling

> Migliora risoluzione e qualità dei video sull'API Venice con il modello Topaz Video Upscale: carica un clip, scegli la scala e recupera l'output.

L'upscaling video ti permette di migliorare video esistenti portandoli a risoluzioni più alte e migliorando al contempo la qualità visiva. Il modello **Topaz Video Upscale** usa upscaling guidato dall'AI per aumentare la risoluzione di 2x o 4x, oppure per applicare un miglioramento della qualità alla risoluzione originale (1x).

## Come funziona

L'upscaling video usa lo stesso sistema di queue asincrono della generazione video:

1. **Queue** — Invia il tuo video a `/video/queue` con il modello `topaz-video-upscale`
2. **Polling** — Controlla `/video/retrieve` con il `queue_id` restituito finché lo stato non è `completed`
3. **Complete** — Chiama `/video/complete` per finalizzare e ottenere l'URL di output

Il server rileva automaticamente la durata, il frame rate e le dimensioni del video di input dal file caricato. Non hai bisogno di fornire questi valori — la fatturazione viene calcolata dai metadati effettivi del video.

## Fattori di upscale

| `upscale_factor` | Risoluzione di output     | Caso d'uso                                               |
| ---------------- | ------------------------- | -------------------------------------------------------- |
| `1`              | Stessa dell'input         | Solo miglioramento della qualità (denoising, sharpening) |
| `2` (default)    | 2x le dimensioni di input | Upscale standard — un input 720p diventa output 1440p    |
| `4`              | 4x le dimensioni di input | Upscale massimo — un input 480p diventa output 1920p     |

<Note>
  Il parametro `upscale_factor` sostituisce `resolution` per i modelli di upscale. Passare `resolution` restituirà un errore. Questo perché la risoluzione di output dipende dalle dimensioni del video di input — un upscale `2x` di un video 720p produce un risultato diverso da un upscale `2x` di un video 480p.
</Note>

## Formati di input supportati

* **Formati**: MP4, MOV, WebM
* **Metodi di input**: URL HTTPS o data URL `data:video/...;base64,...`
* **Durata massima**: 300 secondi (5 minuti)

## Utilizzo dell'API

### Mettere in coda un job di upscale

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

La risposta include un `queue_id` per tracciare il job:

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

### Polling per il completamento

<CodeGroup>
  ```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 '{"queue_id": "abc123-def456-..."}'
  ```

  ```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={"queue_id": queue_id},
      )
      data = result.json()

      if data.get("status") == "completed":
          print(f"Video URL: {data['url']}")
          break

      time.sleep(5)
  ```

  ```javascript Node.js theme={"system"}
  const poll = async (queueId) => {
    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({ queue_id: queueId }),
      });
      const data = await res.json();

      if (data.status === "completed") {
        console.log(`Video URL: ${data.url}`);
        return data;
      }

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

  await poll(queue_id);
  ```
</CodeGroup>

### Finalizzare con complete

Dopo aver recuperato il risultato, chiama `/video/complete` per finalizzare:

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

***

## Parametri API

| Campo            | Tipo   | Obbligatorio | Descrizione                                                            |
| ---------------- | ------ | ------------ | ---------------------------------------------------------------------- |
| `model`          | string | **Sì**       | Deve essere `topaz-video-upscale`                                      |
| `video_url`      | string | **Sì**       | URL del video di input o data URL. Formati supportati: MP4, MOV, WebM. |
| `upscale_factor` | number | No           | `1`, `2` (default) o `4`. Controlla il moltiplicatore di upscale.      |

### Parametri non usati per i modelli di upscale

I seguenti parametri **non sono accettati** per `topaz-video-upscale` e restituiranno un errore se forniti:

| Campo        | Motivo                                                                                   |
| ------------ | ---------------------------------------------------------------------------------------- |
| `resolution` | Usa invece `upscale_factor`. La risoluzione di output dipende dalle dimensioni di input. |
| `prompt`     | L'upscaling non usa prompt testuali. Una stringa vuota viene impostata automaticamente.  |

Anche il parametro `duration` viene ignorato — il server rileva la durata direttamente dal file video per garantire l'accuratezza della fatturazione.

***

## Prezzi

I prezzi sono basati su **durata**, **tier di risoluzione di output** e **frame rate**. Il tier di risoluzione di output è determinato dall'altezza del video di input moltiplicata per il fattore di upscale.

### Tier di risoluzione di output

| Tier  | Altezza di output | Tariffa al secondo |
| ----- | ----------------- | ------------------ |
| 720p  | ≤ 720px           | \~\$0,013          |
| 1080p | 721–1080px        | \~\$0,025          |
| 4K    | > 1080px          | \~\$0,10           |

<Note>
  I video con frame rate sopra i 48fps costano il doppio della tariffa al secondo.
</Note>

### Esempi di prezzi

| Input        | Fattore di upscale | Output            | Durata | Costo stimato |
| ------------ | ------------------ | ----------------- | ------ | ------------- |
| 480p, 30fps  | 2x                 | 960p (tier 1080p) | 10s    | \~\$0,25      |
| 720p, 30fps  | 2x                 | 1440p (tier 4K)   | 10s    | \~\$1,00      |
| 1080p, 30fps | 2x                 | 2160p (tier 4K)   | 30s    | \~\$3,00      |
| 360p, 24fps  | 4x                 | 1440p (tier 4K)   | 10s    | \~\$1,00      |
| 480p, 60fps  | 2x                 | 960p (tier 1080p) | 10s    | \~\$0,50      |

Usa la [Video Quote API](/api-reference/endpoint/video/quote) per ottenere prezzi esatti prima di inviare un job.

### Ottenere un preventivo

```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",
    "duration": "10",
    "input_height": 720
  }'
```

L'endpoint quote accetta `input_height` in modo da poter stimare il tier di risoluzione di output. È opzionale — se omesso, il preventivo assume una stima conservativa.

***

## Troubleshooting

| Problema                                     | Causa probabile                                | Soluzione                                                                                                                      |
| -------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `"Use upscale_factor instead of resolution"` | `resolution` è stato passato nella richiesta   | Rimuovi `resolution` e usa invece `upscale_factor`                                                                             |
| Costo più alto del previsto                  | Il video di input ha risoluzione o FPS elevati | Controlla le dimensioni di input con l'endpoint quote. Input 720p+ con upscale 2x ricade nel tier di prezzo 4K.                |
| Il job richiede molto tempo                  | Video grande o lungo                           | L'upscaling è compute-intensive. Video più lunghi e fattori di upscale più alti richiedono tempi proporzionalmente più lunghi. |
| `"Insufficient balance"`                     | Crediti dell'account troppo bassi              | Aggiungi crediti su [venice.ai/settings/api](https://venice.ai/settings/api)                                                   |