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

# Escalado de vídeo

> Mejora la resolución y calidad de los vídeos en la API de Venice con Topaz Video Upscale: envía el clip, elige escala y obtén el resultado.

El escalado de vídeo te permite mejorar vídeos existentes a resoluciones más altas mientras mejoras la calidad visual. El modelo **Topaz Video Upscale** utiliza escalado impulsado por IA para aumentar la resolución 2x o 4x, o aplicar mejora de calidad a la resolución original (1x).

## Cómo funciona

El escalado de vídeo usa el mismo sistema de cola asíncrono que la generación de vídeo:

1. **Encolar** — envía tu vídeo a `/video/queue` con el modelo `topaz-video-upscale`
2. **Polling** — consulta `/video/retrieve` con el `queue_id` devuelto hasta que el estado sea `completed`
3. **Completar** — llama a `/video/complete` para finalizar y obtener la URL de salida

El servidor detecta automáticamente la duración, la tasa de frames y las dimensiones del vídeo subido. No necesitas proporcionar estos valores: la facturación se calcula a partir de los metadatos reales del vídeo.

## Factores de escalado

| `upscale_factor`     | Resolución de salida      | Caso de uso                                           |
| -------------------- | ------------------------- | ----------------------------------------------------- |
| `1`                  | Misma que la entrada      | Solo mejora de calidad (denoising, sharpening)        |
| `2` (predeterminado) | Dimensiones 2x la entrada | Escalado estándar — entrada 720p produce salida 1440p |
| `4`                  | Dimensiones 4x la entrada | Escalado máximo — entrada 480p produce salida 1920p   |

<Note>
  El parámetro `upscale_factor` reemplaza a `resolution` para los modelos de escalado. Pasar `resolution` devolverá un error. Esto se debe a que la resolución de salida depende de las dimensiones del vídeo de entrada — un escalado `2x` de un vídeo 720p produce un resultado diferente al escalado `2x` de un vídeo 480p.
</Note>

## Formatos de entrada admitidos

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

## Uso de la API

### Encolar un trabajo de escalado

<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 respuesta incluye un `queue_id` para hacer seguimiento del trabajo:

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

### Polling de finalización

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

### Finalizar con complete

Después de recuperar el resultado, llama a `/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 de la API

| Campo            | Tipo   | Obligatorio | Descripción                                                              |
| ---------------- | ------ | ----------- | ------------------------------------------------------------------------ |
| `model`          | string | **Sí**      | Debe ser `topaz-video-upscale`                                           |
| `video_url`      | string | **Sí**      | URL del vídeo de entrada o data URL. Formatos admitidos: MP4, MOV, WebM. |
| `upscale_factor` | number | No          | `1`, `2` (predeterminado) o `4`. Controla el multiplicador de escalado.  |

### Parámetros no usados para modelos de escalado

Los siguientes parámetros **no se aceptan** para `topaz-video-upscale` y devolverán un error si se proporcionan:

| Campo        | Razón                                                                                            |
| ------------ | ------------------------------------------------------------------------------------------------ |
| `resolution` | Usa `upscale_factor` en su lugar. La resolución de salida depende de las dimensiones de entrada. |
| `prompt`     | El escalado no usa prompts de texto. Se establece una cadena vacía automáticamente.              |

El parámetro `duration` también se ignora — el servidor detecta la duración directamente del archivo de vídeo para la precisión de la facturación.

***

## Precios

El precio se basa en **duración**, **nivel de resolución de salida** y **tasa de frames**. El nivel de resolución de salida se determina por la altura del vídeo de entrada multiplicada por el factor de escalado.

### Niveles de resolución de salida

| Nivel | Altura de salida | Tarifa por segundo |
| ----- | ---------------- | ------------------ |
| 720p  | ≤ 720px          | \~\$0.013          |
| 1080p | 721–1080px       | \~\$0.025          |
| 4K    | > 1080px         | \~\$0.10           |

<Note>
  Los vídeos con tasas de frames superiores a 48fps cuestan 2x la tarifa por segundo.
</Note>

### Ejemplos de precios

| Entrada      | Factor de escalado | Salida             | Duración | Coste estimado |
| ------------ | ------------------ | ------------------ | -------- | -------------- |
| 480p, 30fps  | 2x                 | 960p (nivel 1080p) | 10s      | \~\$0.25       |
| 720p, 30fps  | 2x                 | 1440p (nivel 4K)   | 10s      | \~\$1.00       |
| 1080p, 30fps | 2x                 | 2160p (nivel 4K)   | 30s      | \~\$3.00       |
| 360p, 24fps  | 4x                 | 1440p (nivel 4K)   | 10s      | \~\$1.00       |
| 480p, 60fps  | 2x                 | 960p (nivel 1080p) | 10s      | \~\$0.50       |

Usa la [API de cotización de vídeo](/api-reference/endpoint/video/quote) para obtener precios exactos antes de enviar un trabajo.

### Obtener una cotización

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

El endpoint de cotización acepta `input_height` para poder estimar el nivel de resolución de salida. Esto es opcional — si se omite, la cotización asume una estimación conservadora.

***

## Resolución de problemas

| Problema                                     | Causa probable                                       | Solución                                                                                                                               |
| -------------------------------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `"Use upscale_factor instead of resolution"` | Se pasó `resolution` en la solicitud                 | Elimina `resolution` y usa `upscale_factor` en su lugar                                                                                |
| Coste mayor de lo esperado                   | El vídeo de entrada tiene alta resolución o alta FPS | Comprueba las dimensiones de entrada con el endpoint de cotización. Una entrada de 720p+ con escalado 2x cae en el nivel de precio 4K. |
| El trabajo tarda mucho                       | Vídeo grande o largo                                 | El escalado es intensivo en cómputo. Los vídeos más largos y los factores de escalado más altos tardan proporcionalmente más.          |
| `"Insufficient balance"`                     | Créditos de cuenta demasiado bajos                   | Añade créditos en [venice.ai/settings/api](https://venice.ai/settings/api)                                                             |