API de mejora de vídeo: un flujo de entrega y control de calidad

Tienes un clip corto que te gusta, generado de forma barata en 480p o recortado de material antiguo, y tiene que salir en 1080p o 4K con su pista de sonido intacta. Una API de mejora de vídeo lo hace en una sola llamada, pero la llamada es solo el centro del trabajo. Lo que decide si el archivo es utilizable es lo que haces antes (terminar el montaje, comprobar el origen) y después (descargar a tiempo, confirmar tamaño, duración y audio, exportar el lienzo exacto que pide el destino).

La versión corta: mejora el montaje final, una sola vez, en el nivel que necesita el destino. SpicyAPI Video Upscaler acepta un MP4 de 3 a 60 segundos y un nivel, y devuelve el mismo clip con mayor resolución y la misma duración, relación de aspecto, movimiento y pista de audio. No hay prompt. Precios: $0.006 por segundo de origen en 720p o 1080p, $0.012 en 2K, $0.024 en 4K.

Qué envías y qué pagas

Envía video_url (un enlace directo a un MP4 o un archivo subido) y, opcionalmente, resolution: 720p, 1080p (predeterminado), 2k o 4k. Los MP4 subidos pueden ocupar hasta 90 MB. La facturación es por segundo del clip de origen, redondeado hacia arriba a un segundo entero, con un mínimo de tres segundos.

El redondeo se aplica a cada clip enviado, así que tres clips de 5.2 segundos se facturan como 18 segundos, no como 16. La estimación que se muestra antes de enviar asume un clip de 60 segundos ($0.36 en 1080p, $1.44 en 4K); la parte sin usar se libera cuando la tarea se liquida, de modo que un clip de 6 segundos se factura por 6 segundos. Una tarea fallida se reembolsa.

El argumento de coste de la mejora está en el lado de la generación. Un clip de 10 segundos generado en 480p con Seedance 2.5 Spicy cuesta $2.16 por intento; en 1080p nativo cuesta $10.80. Haz el borrador en 480p, quédate con la toma que quieres y añade $0.06 para mejorarlo a 1080p. El mejorador agranda lo que ya está en el encuadre, así que un detalle que falta en el borrador no aparecerá. Si una etiqueta pequeña o una cara tienen que quedar bien, compruébalo en el borrador o haz el borrador a mayor resolución.

Prepara el origen

Termina primero el montaje. Recorta, reordena y mezcla el audio antes de mejorar. De lo contrario, cada edición posterior tendría que repetirse sobre un archivo con varias veces más píxeles, y pagarías por procesar segundos que vas a descartar. El mejorador no puede arreglar una toma equivocada: una mano deformada o un logo que se desplaza vuelve más grande.

Comprueba el archivo. ffprobe muestra lo que realmente estás enviando, incluida una duración que en pantalla redondea a "60 segundos" pero es 60.4:

ffprobe -v error \
  -show_entries format=duration,size:stream=codec_type,codec_name,width,height,avg_frame_rate,sample_rate,channels \
  -of json approved-source.mp4

Hay tres cosas que mirar. La duración debe estar entre 3 y 60 segundos. Un clip de móvil puede reproducirse en vertical mientras que el fotograma almacenado es horizontal más un indicador de rotación (ffprobe -show_streams lo lista en side data); aplica la rotación de forma definitiva antes de subir. Y anota la pista de audio: la compararás con el resultado.

Omite los clips que ya son suficientemente grandes. Un clip en el nivel o por encima de él vuelve con un tamaño casi igual y se cobra igualmente: un clip de 786x1178 enviado a 720p volvió a 784x1176. Si el origen ya cumple la especificación del destino, expórtalo y termina.

Empieza desde el master más limpio. Los bloques de compresión y el ruido se amplían junto con todo lo demás. Usa el master de generación o de edición, no una copia redescargada de un feed social.

Elige el nivel según el destino

El nivel es un presupuesto de píxeles con la relación de aspecto conservada, así que los orígenes poco habituales vuelven con tamaños poco habituales. Un clip de 832x480 volvió a 1896x1094 en 1080p y a 3792x2188 en 4K; un clip de 854x480 volvió a 1922x1080. No esperes exactamente 1920x1080.

• 720p o 1080p para feeds, páginas de destino y anuncios. Cuestan lo mismo, así que elige por el destino, no por el precio. 1080p es el predeterminado y suele ser el correcto.
• 2K o 4K para pantallas grandes, presentaciones o cuando después quieras recortar. Cuestan el doble y el cuádruple y tardan más: unos 35 segundos para un trabajo de 5 segundos en 1080p y unos 100 segundos en 4K. Un archivo de 5 segundos en 4K ocupa alrededor de 19 MB.
• Si el destino necesita un lienzo exacto, como 1080x1920 para un feed vertical, trátalo como un paso de exportación separado después de la mejora.

Mejorar un clip horizontal y recortarlo a vertical después paga por píxeles que se descartan. Decide el encuadre antes de mejorar y envía la composición final.

Pruébalo primero en Playground

1. Abre la página de Video Upscaler y quédate en la pestaña Playground, en la vista Form. Inicia sesión con una cuenta con saldo para ejecutar.
2. En Input video, coloca el MP4 aprobado (hasta 90 MB) o pega un enlace directo al archivo con Asset URL. Una página que reproduce el vídeo devuelve HTML y la llamada falla con el cargo reembolsado; subir el archivo es la vía más fiable.
3. Pon Resolution en 720p, 1080p, 2K o 4K. Está marcado como un campo que afecta al precio y la estimación se actualiza con tu elección.
4. Ejecútalo, reproduce el resultado contra el origen (mira las comprobaciones de abajo) y solo entonces cópialo a tu propio almacenamiento.

Un clip de 5 segundos cuesta unos centavos incluso en 4K, así que prueba tu clip real en el nivel que esperas entregar antes de escribir código.

Y luego ejecútalo desde código

Instala el SDK de Python (pip install spicyapi), define SPICY_API_KEY en el entorno de tu servidor y ejecuta:

import uuid
from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment

task = client.create_task(
    model="spicyapi/video-upscaler-v1/upscale",
    input_data={
        "video_url": "https://example.com/approved-product-ad.mp4",
        "resolution": "1080p",
    },
    idempotency_key=str(uuid.uuid4()),  # one key per approved clip and tier
)

print("Resume task:", task["taskId"], flush=True)
final = client.wait_for_terminal(task["taskId"])
if final["state"] != "succeeded":
    raise RuntimeError(f"{task['taskId']} ended as {final['state']}: {final.get('errorCode')}")
assets = output_assets(final)
if not assets or any(a.get("pending") or a.get("unavailable") or not a.get("url") for a in assets):
    raise RuntimeError(f"Task {task['taskId']} has no ready output; check this task before a new run")
print(assets[0]["url"])  # copy the file to your own storage now

Crear, esperar, los reintentos, los códigos de error y las descargas están cubiertos en la guía de tareas y en la referencia del SDK de Python; un archivo local pasa por el flujo de subida gratuito y se envía como URI spicy://. El enlace del resultado dura poco y el archivo se conserva unos 14 días, así que consulta retención y entrega antes de construir sobre él. Una tarea en succeeded solo significa que el servicio terminó; marca el clip como entregado cuando pasen las comprobaciones de abajo.

O deja que un agente lo ejecute

Cuando un asistente debe ejecutar la mejora, las tres herramientas oficiales muestran el precio y te preguntan antes de una llamada de pago.

• CLI. Pon {"video_url": "https://example.com/approved-product-ad.mp4", "resolution": "1080p"} en input.json y luego:

``bash spicyapi tasks create --model spicyapi/video-upscaler-v1/upscale --input-file input.json --wait ``

Consulta la documentación de la CLI; npx @spicyapi/cli funciona sin instalar.

• Servidor MCP. Añade el servidor MCP y luego pregunta: "Upscale approved-source.mp4 to 1080p with Video Upscaler." Sube el archivo con spicyapi_upload_file, llama a spicyapi_task_create, que se detiene para tu confirmación de precio, y luego a spicyapi_task_wait.
• Skill. npx skills add spicyapi-ai/spicy-skill instala el Agent Skill, que hace que un asistente de código lea el esquema real del modelo en lugar de adivinar campos.

Comprueba el resultado contra el origen

Ejecuta la misma sonda en ambos archivos y compara. Este es un script rápido que imprime una línea por clip:

probe() {
  ffprobe -v error -of json \
    -show_entries format=duration,size:stream=codec_type,codec_name,width,height,avg_frame_rate,sample_rate,channels,duration "$1" |
  jq -c '{size_bytes: (.format.size|tonumber), duration: (.format.duration|tonumber),
    video: (.streams|map(select(.codec_type=="video"))[0]|{codec:.codec_name,w:.width,h:.height,fps:.avg_frame_rate}),
    audio: (.streams|map(select(.codec_type=="audio"))[0]|if .==null then null else {codec:.codec_name,rate:.sample_rate,ch:.channels} end)}'
}
probe approved-source.mp4
probe returned.mp4

Qué confirmar:

1. Tamaño y forma. La relación de aspecto coincide con el origen y las dimensiones son las que debería dar el nivel. Anota el ancho y el alto reales; no los copies del nombre del nivel.
2. Duración. La duración coincide con el origen. Si tu destino depende de puntos de corte exactos, comprueba el primer y el último fotograma, no solo un número redondeado.
3. Audio. El archivo devuelto tiene una pista de audio con el mismo número de canales y la misma longitud que el origen. Que exista una pista no prueba que sea correcta, así que reproduce ambos archivos en los mismos puntos: la primera palabra hablada, un corte, la última frase. Si el origen era silencioso a propósito, el resultado también debería serlo.
4. Imagen en movimiento. Mira el clip entero a velocidad normal antes de inspeccionar fotogramas fijos. El parpadeo, la textura que centellea y los halos alrededor de bordes en movimiento se ven en la reproducción y rara vez en una imagen fija.
5. Detalle que significa algo. Las etiquetas de producto, los logotipos, el texto y las caras son donde un mejorador puede inventar detalle plausible en lugar de recuperar detalle real. Compáralos con el origen en el mismo recorte. Una marca comercial cambiada invalida el clip por nítida que parezca.

Para comparar un momento en paralelo, con el origen ampliado al tamaño de salida por vecino más cercano para que veas sus píxeles reales:

ffmpeg -ss 2.0 -i returned.mp4 -ss 2.0 -i approved-source.mp4 \
  -filter_complex "[1:v]scale=1896:1094:flags=neighbor[s];[s][0:v]hstack" \
  -frames:v 1 compare-at-2s.png

Ajusta la escala al ancho y al alto devueltos.

Exporta el archivo de entrega exacto

Cuando el destino necesita un lienzo fijo, termina con una exportación local. El ejemplo supone un origen aproximadamente vertical como 2:3; un horizontal mejorado y rellenado a 1080x1920 deja una franja estrecha de imagen. El relleno conserva el fotograma completo; el recorte lo llena pero corta los bordes, así que mira el producto después de cualquiera de los dos.

ffmpeg -i accepted-upscale.mp4 \
  -vf "scale=1080:1920:force_original_aspect_ratio=decrease,pad=1080:1920:(ow-iw)/2:(oh-ih)/2" \
  -c:v libx264 -pix_fmt yuv420p -crf 18 \
  -c:a aac -b:a 192k delivery-vertical.mp4

Esto vuelve a codificar el audio. Si necesitas la pista original intacta, usa -c:a copy cuando el destino lo acepte y luego vuelve a ejecutar la sonda sobre el archivo exportado. Incrusta subtítulos y gráficos después de la mejora, para que los bordes de las letras se dibujen al tamaño final y no se amplíen.

Conserva tres archivos: el origen aprobado, la mejora sin tocar y cada exportación. Así un recorte o una reexportación posterior nunca cuesta una segunda mejora.

Cuando algo sale mal

Corrige la etapa que falló en lugar de volver a ejecutar la mejora.

Un piloto antes de un lote

Pasa un clip con movimiento real y pista de audio por todo el recorrido: sonda, mejora, descarga, comparación, exportación y luego reproduce el archivo final en el destino real (el feed, el reproductor, la pantalla grande). Los reproductores y las plataformas locales decodifican y recomprimen de forma distinta, así que solo el destino muestra si el resultado aguanta. Para un lote, incluye un barrido rápido, un anuncio con muchos cortes y un clip de textura fina, y anota para cada clip la duración de origen, los segundos facturados, el nivel, el cargo final y el motivo de cualquier rechazo.

Si estás comparando niveles, mantén constante el clip y compara 1080p con 4K en el tamaño en que se verá. Si 1080p ya cumple el destino, los $0.018 adicionales por segundo no aportan nada visible.

La decisión

Trata el archivo devuelto como un master que compruebas, no como una entrega terminada. La llamada cuesta unos centavos; los costes evitables son rehacer el montaje a mayor resolución, mejorar un clip que ya era suficientemente grande y enviar un archivo cuyo audio o etiqueta de producto ha cambiado. Abre la página del modelo Video Upscaler para probar un clip.