Blog

Tutorial

Cómo usar topaz-upscale/video con la API de HiAPI: ejemplos en curl y Python

Nov 17, 2026
Imagen de portada: varias láminas de vidrio translúcido superpuestas en ángulos contenidos, que refractan franjas de color azul frío paralelas sobre un fondo claro; la imagen no contiene texto.
En esta página

Qué hace topaz-upscale/video y cuándo usarlo

topaz-upscale/video es el endpoint de mejora de video en HiAPI. Le envías un video fuente y una instrucción, y devuelve el video mejorado: mayor resolución, detalles finos reconstruidos y, opcionalmente, movimiento más fluido mediante interpolación de fotogramas. Este endpoint debe usarse cuando el material ya existe y el problema es la calidad, no la generación de contenido.

Casos de uso

Tareas típicas que encajan naturalmente con este endpoint:

  • Archivo y material antiguo: grabaciones antiguas, capturas de pantalla comprimidas o medios heredados que necesitan verse presentables en resoluciones modernas.
  • Pipelines de renderizado: secuencias terminadas que se renderizaron a baja resolución por velocidad y luego se mejoran para la entrega.
  • Limpieza de movimiento: fuentes de baja tasa de fotogramas que necesitan fotogramas interpolados para evitar tartamudeo durante la reproducción.
  • Variantes de entrega: un master, múltiples niveles de salida, aplicando mejoras por nivel.

Cuándo elegirlo frente a alternativas

La decisión suele reducirse a tres preguntas:

  1. ¿El problema es la resolución y el detalle, o el contenido? Si necesitas inventar píxeles nuevos (escenas que nunca se filmaron), esta no es la herramienta adecuada. La mejora asume que hay fotogramas fuente reales subyacentes.
  2. ¿Tu pipeline puede tolerar trabajo asíncrono? Las tareas de video no son instantáneas. Si la experiencia de usuario exige respuestas en menos de un segundo, este endpoint debe ejecutarse en una tarea en segundo plano, no en el manejador de la solicitud.
  3. ¿Necesitas interpolación de fotogramas y escalado? Si la fluidez del movimiento importa, querrás ambas capacidades en un solo procesamiento, no encadenar herramientas independientes. topaz-upscale/video cubre ambas.

Si tu fuente es una imagen estática única, usa el escalador de imágenes. Si la fuente está bien pero mal codificada, corrige primero la codificación: la mejora no puede recuperar detalles que una compresión severa ya destruyó, y pagarás por cómputo sin ganancia de calidad.

Preparar la solicitud antes de la primera llamada

La mayoría de los fallos en la primera llamada se deben a piezas faltantes, no a prompts malos. Prepara esto antes de escribir cualquier código.

Cuenta y credenciales

Necesitas una clave de API de HiAPI con acceso a topaz-upscale/video. Guarda la clave en una variable de entorno en lugar de en el código fuente; cada ejemplo a continuación lee HIAPI_API_KEY del entorno.

export HIAPI_API_KEY="your-key-here"

Medio fuente accesible

El modelo debe poder obtener tu entrada. Dos patrones fiables:

  • URL pública o firmada: una URL que el servicio pueda descargar sin autenticación interactiva. Si tu almacenamiento requiere enlaces firmados, genera uno con amplia validez y recuerda regenerarlo al reintentar; de lo contrario, las tareas largas fallarán a mitad de camino.
  • Subir primero: envía el archivo mediante el mecanismo de carga de la plataforma y referencia el identificador devuelto. Es la opción más segura para archivos grandes y cualquier cosa detrás de una red privada.

Características de la fuente que conviene revisar

Antes de gastar una llamada, confirma:

  • Duración. Los videos largos implican tareas largas. Si estás probando, toma un clip de 5 a 10 segundos de la parte central de la fuente; el centro suele ser más representativo que los fotogramas iniciales.
  • Códec y contenedor. Los códecs poco comunes a veces no se pueden decodificar. En caso de duda, vuelve a empaquetar en un contenedor común.
  • Tasa de fotogramas. Anótala con precisión; la usarás al razonar sobre la interpolación de fotogramas.
  • Resolución. Registra las dimensiones exactas de la fuente para que tu comparación antes/después sea honesta.

Define tu objetivo de salida

Decide la resolución y la tasa de fotogramas de salida antes de la primera llamada, no después. Una configuración de mejora razonable para escalar una fuente de 720p a 1080p difiere de la que se usa para escalar una fuente de 480p a 4K. Anota el objetivo; lo reutilizarás en cada solicitud posterior.

Realizar la llamada con curl

La solicitud es un POST con cuerpo JSON al endpoint topaz-upscale/video. A continuación, un ejemplo completo y ejecutable; sustitúyelo por la URL de tu propio medio.

curl -sS https://api.hiapi.ai/v1/video/enhance \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "topaz-upscale/video",
    "input": {
      "video": "https://your-bucket.example.com/clips/source_720p.mp4"
    },
    "parameters": {
      "target_resolution": "1080p",
      "target_fps": 60,
      "interpolation": "smooth",
      "detail": "balanced"
    },
    "prompt": "Restaura texturas finas en telas y piel, mantén el grano natural, interpola a 60 fps sin imágenes fantasma"
  }'

Interpretar la respuesta

La respuesta inmediata confirma la tarea. Recibirás un identificador de tarea y un campo de estado. El trabajo de video es asíncrono, así que el patrón real es:

# 1. Enviar y capturar el id de la tarea
JOB_ID=$(curl -sS https://api.hiapi.ai/v1/video/enhance \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json | jq -r '.id')

# 2. Sondear hasta que el estado sea terminal
curl -sS "https://api.hiapi.ai/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY" | jq '.status, .output'

Al leer el resultado, tres campos importan:

  • status: pasa de en cola a en ejecución y luego a un estado terminal. Trata cualquier estado no reconocido como "sigue esperando", no como éxito.
  • output: presente en caso de éxito, contiene la URL o el identificador del video mejorado.
  • error: presente en caso de fallo. Lee el mensaje literalmente; normalmente señala el campo problemático.

Si estás iterando prompts, coloca el cuerpo de la solicitud en un archivo (request.json) y usa -d @request.json. Esto mantiene limpio el historial del shell y te permite comparar diferentes versiones de la misma solicitud.

Llamar al mismo endpoint desde Python

La versión en Python es un envoltorio ligero sobre el mismo contrato HTTP. Usa requests, guarda la clave en el entorno y envuelve el envío y el bucle de sondeo en funciones, para que quien llame no necesite saber que es asíncrono.

import os
import time
import requests

BASE = "https://api.hiapi.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
    "Content-Type": "application/json",
}

def enhance_video(
    video_url: str,
    prompt: str,
    target_resolution: str = "1080p",
    target_fps: int = 60,
    poll_interval: float = 5.0,
    timeout: float = 1800.0,
) -> str:
    payload = {
        "model": "topaz-upscale/video",
        "input": {"video": video_url},
        "parameters": {
            "target_resolution": target_resolution,
            "target_fps": target_fps,
            "interpolation": "smooth",
            "detail": "balanced",
        },
        "prompt": prompt,
    }

    resp = requests.post(f"{BASE}/video/enhance",
                         headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    job_id = resp.json()["id"]

    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        r = requests.get(f"{BASE}/jobs/{job_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()
        if data["status"] == "succeeded":
            return data["output"]["video"]
        if data["status"] == "failed":
            raise RuntimeError(data.get("error", "La mejora falló"))
        time.sleep(poll_interval)

    raise TimeoutError(f"La tarea {job_id} no se completó en el tiempo esperado")

Consideraciones para usarlo en un pipeline real

  • Sondeo con retroceso exponencial. Un intervalo fijo de cinco segundos está bien para un script de shell; en producción, aplica retroceso y establece un límite superior al intervalo. Los videos largos pueden tardar; sondear con más frecuencia no los hará terminar antes.
  • Idempotencia. Si la llamada de envío expira, puede que no sepas si la tarea se inició. Registra el cuerpo de la solicitud junto con el id de la tarea para detectar duplicados, en lugar de reenviar a ciegas.
  • Persistir el id de la tarea. Escríbelo en la base de datos en cuanto lo recibas. Si el proceso muere a mitad del sondeo, puedes reanudar por id sin pagar por una segunda mejora.

Recetas de prompts para interpolación de fotogramas

La interpolación de fotogramas es donde los prompts más fácilmente fallan: o son demasiado vagos para guiar nada, o son tan prescriptivos que el modelo persigue objetivos contradictorios. El prompt coexiste con parámetros estructurados; deja que las palabras se refieran a la intención y las características del movimiento, y que los parámetros lleven los objetivos numéricos.

Patrón: describe el movimiento, no las matemáticas

Deficiente:

interpolar

Mejor:

Interpola a 60 fps suaves. Mantén el ritmo original del movimiento: no cambies la velocidad. Los desplazamientos y movimientos de cámara deben ser lineales y estables; evita distorsiones en los bordes de los fotogramas.

Ya le indicaste a la API la tasa de fotogramas objetivo en parameters. El prompt debe describir cómo se ve el movimiento suave para este material.

Patrón: nombra los artefactos que hay que evitar

Suaviza de 24p a 60 fps. Evita imágenes fantasma en manos que se mueven rápido, evita estelas alrededor de objetos finos como barandillas y cabello. Los fondos estáticos deben permanecer completamente inmóviles.

Nombrar modos de fallo concretos es mucho más efectivo que "alta calidad". El modelo puede contrastar su salida con instrucciones específicas.

Patrón: separa el movimiento de la textura

Esta pasada se centra solo en la fluidez del movimiento. Mantén los detalles y el grano existentes sin cambios; la restauración de texturas se maneja por separado.

Útil cuando encadenas dos etapas de procesamiento, de modo que cada prompt tenga una sola responsabilidad.

Patrón: manejar material con movimiento mixto

Para clips de entrevista con cámara fija pero sujeto en movimiento, nombrar explícitamente la quietud de la cámara funciona bien:

Interpola a 60 fps. La cámara está fija: el fondo debe permanecer completamente inmóvil o parpadear. Solo la cabeza y las manos del hablante deben mostrar movimiento suave.

Resiste la tentación de escribir largos ensayos. Tres frases que cubran el movimiento objetivo, los artefactos a evitar y lo que debe permanecer inmóvil cubren casi todos los casos.

Recetas de prompts para reconstrucción de detalles

La reconstrucción de detalles es la mitad de la tarea que inventa estructuras finas plausibles. El modo de fallo es la textura alucinada: la piel parece plástico, la vegetación se vuelve ruido, el texto se vuelve ilegible. El prompt debe poner límites a la invención.

Patrón: anclar a la fuente

Reconstruye detalles coherentes con los fotogramas fuente. No inventes texturas que los píxeles originales no sugieran. Donde el detalle se haya perdido realmente, prefiere un resultado suave y creíble antes que ruido agudizado.

Esta única instrucción previene la mayoría de las patologías de sobreexageración.

Patrón: nombra los materiales de la escena

Restaura detalles finos en la textura de telas, mechones de cabello y poros de la piel. Mantén el tono de piel natural y los poros irregulares; evita una apariencia suave y aerografiada. Las superficies metálicas deben conservar los reflejos existentes y no generar nuevos.

Las instrucciones específicas por material le dan al modelo restricciones prácticas sin necesidad de un párrafo genérico.

Patrón: proteger texto y gráficos

Este clip contiene subtítulos en pantalla y logotipos. El texto debe permanecer nítido y legible, sin distorsión. No redibujes ni cambies el estilo de ningún elemento gráfico.

El texto es el detalle de mayor riesgo: subtítulos ilegibles son peores que subtítulos ligeramente borrosos. Si la legibilidad es crítica, verifícala en la fase de comparación, no confíes en el prompt.

Patrón: modular el enfoque intencionadamente

Aplica una cantidad contenida de restauración de detalle. El objetivo es material de aspecto natural a 1080p, no un fotograma fijo agudizado. Una ligera suavidad es aceptable; el ringing y los halos no lo son.

Combinar ambos

Cuando interpolas y reconstruyes en un solo procesamiento, escribe un prompt que cubra ambos, pero con una sola preocupación por cláusula:

Reconstruye texturas finas —telas, cabello, piel— coherentes con la fuente, evitando la suavidad plástica. Interpola a 60 fps, con movimiento estable, sin imágenes fantasma en las manos y con el fondo completamente inmóvil.

Comparar la salida antes y después

Un video mejorado que se ve impresionante en un solo fotograma puede desmoronarse en movimiento. Establece un flujo de comparación fijo y ejecútalo cada vez que cambies un parámetro o un prompt; de lo contrario, estarás adivinando, y adivinar es caro.

Construir un conjunto estándar de clips de prueba

Elige tres clips cortos (5–10 segundos cada uno) que nunca cambies:

  1. Fácil: fuente limpia, bien iluminada y de movimiento lento. Debería verse casi perfecto; si no, algo está mal configurado.
  2. Difícil: movimiento rápido, detalles finos o tipos de movimiento mixtos. Aquí aparecerán los artefactos de interpolación.
  3. Adversario: texto en pantalla, estructuras finas o compresión previa severa. Aquí se manifestarán las alucinaciones.

Ejecuta cada cambio de prompt o parámetro contra los tres. Un cambio que ayuda al clip fácil pero perjudica al adversario no es una mejora.

Comparar en este orden

  • Comparación lado a lado al 100% de zoom. No uses ajuste a ventana; los artefactos se ocultan. Revisa las mismas regiones recortadas: rostros, zonas de texto y zonas de alto movimiento.
  • Desplazamiento fotograma a fotograma. Avanza fotograma a fotograma por las secciones de movimiento rápido buscando imágenes fantasma, distorsiones y parpadeos.
  • Reproducción a velocidad real. Muchos artefactos desaparecen al desplazarse fotograma a fotograma y aparecen en movimiento, y viceversa. Mira ambos.
  • Comprobación de legibilidad del texto. Lee cada subtítulo en la versión mejorada contra la fuente. Es la comprobación objetiva de aprobado/fallo más rápida que tienes.

Calidad y costo a la par

La facturación sigue el trabajo que realiza el endpoint: la duración y la resolución de salida son los factores determinantes; consulta el panel de precios del sitio para conocer las tarifas actuales. Consecuencia práctica: los clips más largos con mejoras marginales de calidad suelen ser peor negocio que los clips más cortos con mejoras notables. Para cada configuración candidata, registra la duración y resolución de salida que produjiste y pregúntate si la mejora visible justifica el gasto. Conserva al ganador, descarta el resto y, antes de conectar el endpoint a un pipeline automatizado, congela una configuración y documéntala —prompt, parámetros y resultados de pruebas— para que los cambios futuros puedan medirse contra ella.

Solucionar problemas comunes de solicitud

La mayor parte de la fricción de integración con topaz-upscale/video cae en unas pocas categorías. Abórdalas en este orden.

Autenticación y acceso

Un 401 significa que la clave falta, está mal formada o no se envió; verifica que la variable de entorno esté realmente configurada en el shell que ejecuta el comando, no solo en el editor. Un 403 suele significar que la clave es válida pero la cuenta carece de acceso a este modelo. Confirma que el nombre del modelo esté escrito exactamente como topaz-upscale/video.

El servicio no puede obtener tu video

Este es el fallo más común. Síntoma: la tarea falla temprano con un error de descarga o de entrada. Causas:

  • La URL es privada o requiere inicio de sesión interactivo.
  • La URL firmada expira antes de que la tarea llegue al paso de descarga, especialmente probable en colas largas.
  • El host bloquea solicitudes automatizadas o es tan lento que se agota el tiempo.

Solución: sube el archivo mediante la plataforma y referencia el identificador devuelto, o genera una URL firmada con amplia validez al enviar.

Fallo de decodificación

Si el error menciona el medio en lugar de la solicitud, vuelve a empaquetar la fuente en un contenedor común y reintenta. Prueba el archivo localmente primero; si tu propio reproductor tiene dificultades, el servicio también las tendrá.

La tarea sigue ejecutándose o expira

Las fuentes largas tardan mucho, y algunas solicitudes tardan desproporcionadamente. Antes de reenviar, consulta el estado de la tarea por id; puede que estés viendo una tarea en cola, no una fallida. Reenviar a ciegas puede duplicar el costo. Si sondeas desde un script, asegúrate de que el tiempo de espera de tu cliente sea mayor que la duración esperada de la tarea; de lo contrario, abandonarás una tarea que sigue ejecutándose correctamente.

La salida se ve peor que la fuente

La solicitud tuvo éxito pero el resultado está sobreexagerado, tiene aspecto plástico o imágenes fantasma. Es un problema de prompt, no de la API: vuelve a las recetas de reconstrucción de detalles e interpolación, añade límites explícitos —"coherente con la fuente", "sin imágenes fantasma", "el fondo debe permanecer inmóvil"—. Luego vuelve a ejecutar tu conjunto estándar de comparación.

Fallos intermitentes y no reproducibles

Registra el cuerpo completo de la solicitud y el id de la tarea en cada llamada. Sin ambos, no puedes saber si el fallo proviene de una carga diferente o de un problema temporal del servicio. Con una docena de fallos registrados, el patrón suele emerger en minutos.

Artículos relacionados

Ver todos los artículos →

Empieza a crear con artefactos de IA persistentes

Consigue tu API key y llama a modelos de imagen, vídeo y audio a través de una única API basada en tasks.

Leer la documentación de la API