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

# Upscaling de vídeo

> Aprimore resolução e qualidade de vídeos na Venice API com o modelo Topaz Video Upscale: envie o clipe, escolha a escala e baixe o resultado.

O upscaling de vídeo permite aprimorar vídeos existentes para resoluções mais altas enquanto melhora a qualidade visual. O modelo **Topaz Video Upscale** usa upscaling com IA para aumentar a resolução em 2x ou 4x, ou aplicar aprimoramento de qualidade na resolução original (1x).

## Como funciona

O upscaling de vídeo usa o mesmo sistema de fila assíncrona da geração de vídeo:

1. **Enfileire** — Envie seu vídeo para `/video/queue` com o modelo `topaz-video-upscale`
2. **Polling** — Verifique `/video/retrieve` com o `queue_id` retornado até o status ser `completed`
3. **Complete** — Chame `/video/complete` para finalizar e obter a URL de saída

O servidor detecta automaticamente a duração, taxa de frames e dimensões do vídeo de entrada a partir do arquivo enviado. Você não precisa fornecer esses valores — a cobrança é calculada a partir dos metadados reais do vídeo.

## Fatores de upscale

| `upscale_factor` | Resolução de saída          | Caso de uso                                               |
| ---------------- | --------------------------- | --------------------------------------------------------- |
| `1`              | Igual à entrada             | Apenas aprimoramento de qualidade (denoising, sharpening) |
| `2` (padrão)     | 2x das dimensões de entrada | Upscale padrão — entrada de 720p vira saída de 1440p      |
| `4`              | 4x das dimensões de entrada | Upscale máximo — entrada de 480p vira saída de 1920p      |

<Note>
  O parâmetro `upscale_factor` substitui `resolution` para modelos de upscale. Passar `resolution` retornará um erro. Isso é porque a resolução de saída depende das dimensões do vídeo de entrada — um upscale `2x` de um vídeo 720p produz um resultado diferente de um upscale `2x` de um vídeo 480p.
</Note>

## Formatos de entrada suportados

* **Formatos**: MP4, MOV, WebM
* **Métodos de entrada**: URL HTTPS ou data URL `data:video/...;base64,...`
* **Duração máxima**: 300 segundos (5 minutos)

## Uso da API

### Enfileire um job de 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>

A resposta inclui um `queue_id` para rastrear o job:

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

### Polling para conclusão

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

### Finalize com complete

Após recuperar o resultado, chame `/video/complete` para finalizar:

```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-..."}'
```

***

## Parâmetros da API

| Campo            | Tipo   | Obrigatório | Descrição                                                                 |
| ---------------- | ------ | ----------- | ------------------------------------------------------------------------- |
| `model`          | string | **Sim**     | Deve ser `topaz-video-upscale`                                            |
| `video_url`      | string | **Sim**     | URL do vídeo de entrada ou data URL. Formatos suportados: MP4, MOV, WebM. |
| `upscale_factor` | number | Não         | `1`, `2` (padrão) ou `4`. Controla o multiplicador de upscale.            |

### Parâmetros não usados para modelos de upscale

Os seguintes parâmetros **não são aceitos** para `topaz-video-upscale` e retornarão um erro se fornecidos:

| Campo        | Motivo                                                                                    |
| ------------ | ----------------------------------------------------------------------------------------- |
| `resolution` | Use `upscale_factor` em vez disso. A resolução de saída depende das dimensões de entrada. |
| `prompt`     | Upscaling não usa prompts de texto. Uma string vazia é definida automaticamente.          |

O parâmetro `duration` também é ignorado — o servidor detecta a duração diretamente do arquivo de vídeo para precisão de cobrança.

***

## Preços

A cobrança é baseada em **duração**, **tier de resolução de saída** e **taxa de frames**. O tier de resolução de saída é determinado pela altura do vídeo de entrada multiplicada pelo fator de upscale.

### Tiers de resolução de saída

| Tier  | Altura de saída | Taxa por segundo |
| ----- | --------------- | ---------------- |
| 720p  | ≤ 720px         | \~\$0,013        |
| 1080p | 721–1080px      | \~\$0,025        |
| 4K    | > 1080px        | \~\$0,10         |

<Note>
  Vídeos com taxas de frames acima de 48fps custam 2x a taxa por segundo.
</Note>

### Exemplos de preços

| Entrada      | Fator de upscale | Saída             | Duração | Custo estimado |
| ------------ | ---------------- | ----------------- | ------- | -------------- |
| 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       |

Use a [API de cotação de vídeo](/api-reference/endpoint/video/quote) para obter preços exatos antes de enviar um job.

### Obtendo uma cotação

```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
  }'
```

O endpoint de cotação aceita `input_height` para que possa estimar o tier de resolução de saída. Isso é opcional — se omitido, a cotação assume uma estimativa conservadora.

***

## Solução de problemas

| Problema                                     | Causa provável                                  | Correção                                                                                                                 |
| -------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `"Use upscale_factor instead of resolution"` | `resolution` foi passado na requisição          | Remova `resolution` e use `upscale_factor` em vez disso                                                                  |
| Custo maior que o esperado                   | Vídeo de entrada tem alta resolução ou alto FPS | Verifique as dimensões de entrada com o endpoint de cotação. Entrada de 720p+ com upscale 2x cai no tier de preço 4K.    |
| Job leva muito tempo                         | Vídeo grande ou longo                           | Upscaling é intensivo em computação. Vídeos mais longos e fatores de upscale maiores levam proporcionalmente mais tempo. |
| `"Insufficient balance"`                     | Créditos da conta muito baixos                  | Adicione créditos em [venice.ai/settings/api](https://venice.ai/settings/api)                                            |