API de ampliação de vídeo: um fluxo de entrega e controle de qualidade

Você tem um clip curto do qual gosta, gerado barato em 480p ou recortado de material antigo, e ele precisa sair em 1080p ou 4K com a trilha sonora intacta. Uma API de ampliação de vídeo faz isso em uma única chamada, mas a chamada é apenas o meio do trabalho. O que decide se o arquivo é utilizável é o que você faz antes (concluir a montagem, verificar a origem) e depois (baixar a tempo, confirmar tamanho, duração e áudio, exportar a tela exata que o destino exige).

A versão curta: amplie a montagem final, uma única vez, no nível de que o destino precisa. O SpicyAPI Video Upscaler aceita um MP4 de 3 a 60 segundos e um nível, e devolve o mesmo clip em resolução maior com a mesma duração, proporção de tela, movimento e trilha de áudio. Não há prompt. Preços: $0,006 por segundo de origem em 720p ou 1080p, $0,012 em 2K e $0,024 em 4K.

O que você envia e o que paga

Envie video_url (um link direto para um MP4 ou um arquivo enviado) e, opcionalmente, resolution: 720p, 1080p (padrão), 2k ou 4k. Os MP4 enviados podem ter até 90 MB. A cobrança é por segundo do clip de origem, arredondada para cima até um segundo inteiro, com mínimo de três segundos.

O arredondamento vale para cada clip enviado, então três clips de 5,2 segundos são cobrados como 18 segundos, não 16. A estimativa mostrada antes do envio pressupõe um clip de 60 segundos ($0,36 em 1080p, $1,44 em 4K); a parte não usada é liberada quando a tarefa é liquidada, então um clip de 6 segundos é cobrado por 6 segundos. Uma tarefa com falha é reembolsada.

O argumento de custo da ampliação está do lado da geração. Um clip de 10 segundos gerado em 480p com o Seedance 2.5 Spicy custa $2,16 por tentativa; em 1080p nativo custa $10,80. Faça o rascunho em 480p, guarde o take que quiser e acrescente $0,06 para ampliar para 1080p. O ampliador aumenta o que já está no quadro, então um detalhe que falta no rascunho não vai aparecer. Se uma etiqueta pequena ou um rosto tiver de ficar correto, verifique no rascunho ou faça o rascunho em resolução mais alta.

Prepare a origem

Termine a montagem primeiro. Corte, reordene e misture o áudio antes de ampliar. Toda edição posterior teria de ser refeita em um arquivo com várias vezes mais pixels, e você paga para processar segundos que vai descartar. O ampliador não corrige um take errado: uma mão distorcida ou um logo que desliza volta maior.

Verifique o arquivo. O ffprobe mostra o que você está realmente enviando, incluindo uma duração que na tela arredonda para "60 segundos" mas é 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

Três coisas a observar. A duração precisa ficar entre 3 e 60 segundos. Um clip de celular pode tocar na vertical enquanto o quadro armazenado é horizontal mais um sinalizador de rotação (ffprobe -show_streams lista isso em side data); aplique a rotação de forma definitiva antes de enviar. E anote o fluxo de áudio: você vai compará-lo com o resultado.

Pule clips que já são grandes o bastante. Um clip no nível ou acima dele volta com quase o mesmo tamanho e ainda é cobrado: um clip de 786x1178 enviado em 720p voltou como 784x1176. Se a origem já atende à especificação do destino, exporte-a e pare.

Comece pelo master mais limpo. Blocos de compressão e ruído são ampliados junto com todo o resto. Use o master de geração ou de edição, não uma cópia baixada de novo de um feed social.

Escolha o nível a partir do destino

O nível é um orçamento de pixels com a proporção de tela preservada, então origens incomuns voltam com tamanhos incomuns. Um clip de 832x480 voltou como 1896x1094 em 1080p e como 3792x2188 em 4K; um clip de 854x480 voltou como 1922x1080. Não espere exatamente 1920x1080.

• 720p ou 1080p para feeds, páginas de destino e anúncios. Custam o mesmo, então escolha pelo destino, não pelo preço. 1080p é o padrão e costuma ser o certo.
• 2K ou 4K para telas grandes, apresentações ou quando você for recortar depois. Custam duas e quatro vezes mais e demoram mais: cerca de 35 segundos para um trabalho de 5 segundos em 1080p e cerca de 100 segundos em 4K. Um arquivo de 5 segundos em 4K fica em torno de 19 MB.
• Se o destino precisar de uma tela exata, como 1080x1920 para um feed vertical, trate isso como uma etapa de exportação separada depois da ampliação.

Ampliar um clip horizontal e depois recortá-lo para vertical paga por pixels que você descarta. Decida o enquadramento antes da ampliação e envie a composição final.

Teste primeiro no Playground

1. Abra a página do Video Upscaler e fique na aba Playground, na visão Form. Entre com uma conta com saldo para executar.
2. Em Input video, coloque o MP4 aprovado (até 90 MB) ou cole um link direto para o arquivo com Asset URL. Uma página que reproduz o vídeo devolve HTML e a chamada falha com a cobrança reembolsada; enviar o arquivo é o caminho mais confiável.
3. Coloque Resolution em 720p, 1080p, 2K ou 4K. O campo está marcado como influenciando o preço, e a estimativa se atualiza com a sua escolha.
4. Execute, reproduza o resultado ao lado da origem (veja as verificações abaixo) e só então copie para o seu próprio armazenamento.

Um clip de 5 segundos custa poucos centavos mesmo em 4K, então teste seu clip real no nível em que pretende entregar antes de escrever código.

Depois execute pelo código

Instale o SDK de Python (pip install spicyapi), defina SPICY_API_KEY no ambiente do seu servidor e execute:

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

Criação, espera, retentativas, códigos de erro e downloads estão no guia de tarefas e na referência do SDK de Python; um arquivo local passa pelo fluxo de envio gratuito e é informado como URI spicy://. O link do resultado tem vida curta e o arquivo é guardado por cerca de 14 dias, então veja retenção e entrega antes de construir em cima dele. Uma tarefa succeeded significa apenas que o serviço terminou; marque o clip como entregue depois que as verificações abaixo passarem.

Ou deixe um agente executar

Quando um assistente deve fazer a ampliação, as três ferramentas oficiais mostram o preço e pedem confirmação antes de uma chamada paga.

• CLI. Coloque {"video_url": "https://example.com/approved-product-ad.mp4", "resolution": "1080p"} em input.json e então:

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

Veja a documentação da CLI; o npx @spicyapi/cli funciona sem instalação.

• Servidor MCP. Adicione o servidor MCP e então pergunte: "Upscale approved-source.mp4 to 1080p with Video Upscaler." Ele envia o arquivo com spicyapi_upload_file, chama spicyapi_task_create, que para para a sua confirmação de preço, e depois spicyapi_task_wait.
• Skill. npx skills add spicyapi-ai/spicy-skill instala o Agent Skill, que faz um assistente de código ler o esquema real do modelo em vez de adivinhar campos.

Confira o resultado contra a origem

Execute a mesma sonda nos dois arquivos e compare. Este é um script rápido que imprime uma linha 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

O que confirmar:

1. Tamanho e formato. A proporção de tela bate com a origem e as dimensões são as que o nível deveria entregar. Registre a largura e a altura reais; não as copie do nome do nível.
2. Duração. A duração bate com a origem. Se o seu destino depender de pontos de corte exatos, verifique o primeiro e o último quadro, não apenas um número arredondado.
3. Áudio. O arquivo devolvido tem um fluxo de áudio com o mesmo número de canais e o mesmo comprimento da origem. A existência de um fluxo não prova que ele esteja certo, então reproduza os dois arquivos nos mesmos pontos: a primeira palavra falada, um corte, a última frase. Se a origem era muda de propósito, o resultado também deve ser.
4. Imagem em movimento. Assista ao clip inteiro na velocidade normal antes de inspecionar quadros fixos. Cintilação, textura trêmula e halos ao redor de bordas em movimento aparecem na reprodução e raramente em uma imagem fixa.
5. Detalhe que carrega significado. Etiquetas de produto, logos, textos e rostos são onde um ampliador pode inventar detalhe plausível em vez de recuperar detalhe real. Compare com a origem no mesmo recorte. Uma marca alterada reprova o clip, por mais nítido que pareça.

Para comparar um momento lado a lado, com a origem ampliada até o tamanho de saída por vizinho mais próximo para você ver os pixels reais dela:

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

Ajuste a escala para a largura e a altura devolvidas.

Exporte o arquivo de entrega exato

Quando o destino precisa de uma tela fixa, termine com uma exportação local. O exemplo pressupõe uma origem aproximadamente vertical, como 2:3; uma imagem horizontal ampliada e preenchida até 1080x1920 deixa uma faixa estreita de imagem. O preenchimento preserva o quadro inteiro; o recorte preenche mas corta as bordas, então olhe o produto depois de qualquer um dos dois.

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

Isso recodifica o áudio. Se você precisar da trilha original intacta, use -c:a copy quando o destino aceitar e depois rode a sonda de novo no arquivo exportado. Incorpore legendas e gráficos depois da ampliação, para que as bordas das letras sejam desenhadas no tamanho final em vez de ampliadas.

Guarde três arquivos: a origem aprovada, a ampliação intocada e cada exportação. Um recorte ou uma reexportação posterior nunca custará uma segunda ampliação.

Quando algo dá errado

Corrija a etapa que falhou em vez de rodar a ampliação de novo.

Um piloto antes do lote

Passe um clip com movimento de verdade e trilha de áudio por todo o caminho: sonda, ampliação, download, comparação, exportação e depois reproduzir o arquivo final no destino real (o feed, o player, a tela grande). Players locais e plataformas decodificam e recomprimem de formas diferentes, então só o destino mostra se o resultado se sustenta. Para um lote, inclua uma panorâmica rápida, um anúncio cheio de cortes e um clip de textura fina, e registre para cada clip a duração de origem, os segundos cobrados, o nível, a cobrança final e o motivo de qualquer rejeição.

Se você está comparando níveis, mantenha o clip constante e compare 1080p com 4K no tamanho em que ele será visto. Se 1080p já atende ao destino, os $0,018 extras por segundo não compram nada visível.

A decisão

Trate o arquivo devolvido como um master a conferir, não como uma entrega pronta. A chamada custa poucos centavos; os custos evitáveis são refazer a montagem em resolução mais alta, ampliar um clip que já era grande o bastante e enviar um arquivo cujo áudio ou rótulo de produto mudou. Abra a página do modelo Video Upscaler para experimentar um clip.