API di upscaling video: un flusso di consegna e controllo qualità

Hai un clip corto che ti piace, generato economicamente a 480p oppure ritagliato da materiali più vecchi, e deve uscire a 1080p o 4K con la sua traccia audio intatta. Un'API di upscaling video lo fa in una sola chiamata, ma la chiamata è solo il centro del lavoro. A decidere se il file è utilizzabile è ciò che fai prima (completare il montaggio, controllare la sorgente) e dopo (scaricare in tempo, confermare dimensione, durata e audio, esportare il canvas esatto che la destinazione richiede).

La versione breve: fai l'upscaling del montaggio finale, una sola volta, al livello di cui la destinazione ha bisogno. SpicyAPI Video Upscaler accetta un MP4 da 3 a 60 secondi e un livello, e restituisce lo stesso clip con una risoluzione più alta mantenendo durata, rapporto d'aspetto, movimento e traccia audio. Non c'è alcun prompt. Prezzi: $0.006 per secondo sorgente a 720p o 1080p, $0.012 a 2K, $0.024 a 4K.

Cosa invii e cosa paghi

Invia video_url (un link diretto a un MP4 oppure un file caricato) e facoltativamente resolution: 720p, 1080p (predefinito), 2k o 4k. Gli MP4 caricati possono arrivare a 90 MB. La fatturazione è per secondo del clip sorgente, arrotondato per eccesso al secondo intero, con un minimo di tre secondi.

L'arrotondamento vale per ogni clip inviato, quindi tre clip da 5.2 secondi vengono fatturati come 18 secondi, non 16. La stima mostrata prima dell'invio presume un clip di 60 secondi ($0.36 a 1080p, $1.44 a 4K); la parte non utilizzata viene rilasciata quando l'attività viene regolata, così un clip di 6 secondi viene fatturato per 6 secondi. Un'attività fallita viene rimborsata.

L'argomento di costo dell'upscaling sta sul lato della generazione. Un clip di 10 secondi generato a 480p con Seedance 2.5 Spicy costa $2.16 per tentativo; a 1080p nativo costa $10.80. Fai la bozza a 480p, tieni la take che vuoi e aggiungi $0.06 per portarla a 1080p. L'upscaler ingrandisce ciò che è già nell'inquadratura, quindi un dettaglio assente dalla bozza non comparirà. Se un'etichetta piccola o un volto devono essere esatti, verificali nella bozza oppure fai la bozza a una risoluzione più alta.

Prepara la sorgente

Completa prima il montaggio. Taglia, riordina e mixa l'audio prima di fare l'upscaling. Ogni modifica successiva dovrebbe altrimenti essere rifatta su un file con molte volte più pixel, e paghi per elaborare secondi che getterai via. L'upscaler non può correggere una take sbagliata: una mano deformata o un logo che deriva torna più grande.

Controlla il file. ffprobe mostra cosa stai davvero inviando, inclusa una durata che sullo schermo arrotonda a «60 secondi» ma è 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

Tre cose da controllare. La durata deve stare fra 3 e 60 secondi. Un clip da telefono può riprodursi in verticale mentre il frame memorizzato è orizzontale più un flag di rotazione (ffprobe -show_streams lo elenca tra side data); applica la rotazione prima di caricare. E annota lo stream audio: lo confronterai con il risultato.

Salta i clip già abbastanza grandi. Un clip al livello richiesto o superiore torna all'incirca alla stessa dimensione e viene comunque addebitato: un clip da 786x1178 inviato a 720p è tornato a 784x1176. Se la sorgente soddisfa già la specifica di destinazione, esportala e basta.

Parti dal master più pulito. I blocchi di compressione e il rumore vengono ingranditi insieme a tutto il resto. Usa il master di generazione o di montaggio, non una copia riscaricata da un feed social.

Scegli il livello in base alla destinazione

Il livello è un budget di pixel con il rapporto d'aspetto mantenuto, quindi sorgenti insolite tornano con dimensioni insolite. Un clip da 832x480 è tornato a 1896x1094 a 1080p e a 3792x2188 a 4K; un clip da 854x480 è tornato a 1922x1080. Non aspettarti esattamente 1920x1080.

• 720p o 1080p per feed, landing page e annunci. Costano uguale, quindi scegli in base alla destinazione, non in base al prezzo. 1080p è il predefinito ed è di solito quello giusto.
• 2K o 4K per grandi display, presentazioni o quando ritaglierai in seguito. Costano due e quattro volte tanto e richiedono più tempo: circa 35 secondi per un lavoro di 5 secondi a 1080p e circa 100 secondi a 4K. Un file di 5 secondi a 4K pesa circa 19 MB.
• Se la destinazione richiede un canvas esatto, come 1080x1920 per un feed verticale, trattalo come un passaggio di esportazione separato dopo l'upscaling.

Fare l'upscaling di un clip orizzontale e ritagliarlo in verticale dopo paga dei pixel che scarterai. Decidi l'inquadratura prima dell'upscaling e invia la composizione finale.

Provalo prima nel Playground

1. Apri la pagina di Video Upscaler e rimani nella scheda Playground, in vista Form. Accedi con un account con credito per eseguire.
2. In Input video, trascina l'MP4 approvato (fino a 90 MB) oppure incolla un link diretto al file con Asset URL. Una pagina che riproduce il video restituisce HTML e la chiamata fallisce con l'addebito rimborsato; caricare il file è la via più affidabile.
3. Imposta Resolution su 720p, 1080p, 2K o 4K. Il campo è contrassegnato come influente sul prezzo e la stima si aggiorna con la tua scelta.
4. Esegui, riproduci il risultato a confronto con la sorgente (vedi i controlli qui sotto) e solo allora copialo nel tuo archivio.

Un clip di 5 secondi costa qualche centesimo anche a 4K, quindi prova il tuo clip reale al livello che prevedi di consegnare prima di scrivere codice.

Poi eseguilo dal codice

Installa l'SDK Python (pip install spicyapi), imposta SPICY_API_KEY nell'ambiente del tuo server ed esegui:

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

Creazione, attesa, tentativi, codici di errore e download sono trattati nella guida alle attività e nel riferimento dell'SDK Python; un file locale passa dal flusso di caricamento gratuito e viene passato come URI spicy://. Il link del risultato ha una durata breve e il file viene conservato per circa 14 giorni, quindi consulta conservazione e consegna prima di costruirci sopra. Un'attività succeeded significa solo che il servizio ha finito; segna il clip come consegnato dopo che i controlli qui sotto sono passati.

Oppure lascia che sia un agente a eseguirlo

Quando un assistente deve eseguire l'upscaling, tutti e tre gli strumenti ufficiali mostrano il prezzo e chiedono conferma prima di una chiamata a pagamento.

• CLI. Metti {"video_url": "https://example.com/approved-product-ad.mp4", "resolution": "1080p"} in input.json, poi:

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

Vedi la documentazione della CLI; npx @spicyapi/cli funziona senza installazione.

• Server MCP. Aggiungi il server MCP, poi chiedi: «Upscale approved-source.mp4 to 1080p with Video Upscaler.» Carica il file con spicyapi_upload_file, chiama spicyapi_task_create, che si ferma per la tua conferma del prezzo, e poi spicyapi_task_wait.
• Skill. npx skills add spicyapi-ai/spicy-skill installa l'Agent Skill, che fa leggere a un assistente di programmazione lo schema reale del modello invece di indovinare i campi.

Controlla il risultato rispetto alla sorgente

Esegui la stessa sonda su entrambi i file e confronta. Questo è uno script rapido che stampa una riga per 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

Cosa confermare:

1. Dimensione e forma. Il rapporto d'aspetto corrisponde alla sorgente e le dimensioni sono quelle che il livello dovrebbe dare. Annota larghezza e altezza reali; non copiarle dal nome del livello.
2. Durata. La durata corrisponde alla sorgente. Se la destinazione dipende da punti di taglio esatti, controlla il primo e l'ultimo frame, non solo un numero arrotondato.
3. Audio. Il file restituito ha uno stream audio con lo stesso numero di canali e la stessa lunghezza della sorgente. Che esista uno stream non prova che sia corretto, quindi riproduci entrambi i file negli stessi punti: la prima parola pronunciata, un taglio, l'ultima frase. Se la sorgente era muta di proposito, anche il risultato deve esserlo.
4. Immagine in movimento. Guarda l'intero clip a velocità normale prima di ispezionare fotogrammi fissi. Sfarfallio, texture scintillanti e aloni attorno ai bordi in movimento si vedono in riproduzione e raramente in una still.
5. Dettaglio che porta significato. Etichette di prodotto, loghi, testo e volti sono i punti in cui un upscaler può inventare dettagli plausibili invece di recuperare dettagli reali. Confrontali con la sorgente sullo stesso ritaglio. Un marchio alterato boccia il clip per quanto nitido appaia.

Per confrontare un istante fianco a fianco, con la sorgente ingrandita alla dimensione di uscita con il vicino più vicino così da vederne i pixel reali:

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

Imposta la scala sulla larghezza e sull'altezza restituite.

Esporta il file di consegna esatto

Quando la destinazione richiede un canvas fisso, finisci con un'esportazione locale. L'esempio presuppone una sorgente all'incirca verticale come 2:3; un orizzontale ingrandito e con bande fino a 1080x1920 lascia una striscia sottile di immagine. Le bande conservano l'intero fotogramma; il ritaglio lo riempie ma taglia i bordi, quindi guarda il prodotto dopo l'uno o l'altro.

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

Questo ricodifica l'audio. Se ti serve la traccia originale intatta, usa -c:a copy quando la destinazione lo accetta, poi riesegui la sonda sul file esportato. Incorpora sottotitoli e grafica dopo l'upscaling, così i bordi delle lettere vengono disegnati alla dimensione finale anziché ingranditi.

Conserva tre file: la sorgente approvata, l'upscaling intatto e ogni esportazione. Un ritaglio o una riesportazione successiva non costerà mai un secondo upscaling.

Quando qualcosa va storto

Correggi il passaggio che è fallito invece di rilanciare l'upscaling.

Un pilota prima di un lotto

Fai passare un clip con movimento reale e traccia audio per tutto il percorso: sonda, upscaling, download, confronto, esportazione, poi riproduci il file finale nella destinazione reale (il feed, il lettore, il grande display). Lettori locali e piattaforme decodificano e ricomprimono in modo diverso, quindi solo la destinazione mostra se il risultato regge. Per un lotto, includi una panoramica rapida, uno spot con molti tagli e un clip con texture fine, e annota per ogni clip la durata sorgente, i secondi addebitati, il livello, l'addebito finale e il motivo di qualsiasi rifiuto.

Se stai valutando i livelli, tieni costante il clip e confronta 1080p con 4K alla dimensione in cui sarà visto. Se 1080p soddisfa già la destinazione, i $0.018 in più al secondo non acquistano nulla di visibile.

La decisione

Tratta il file restituito come un master da controllare, non come una consegna finita. La chiamata costa qualche centesimo; i costi evitabili sono rifare il montaggio a risoluzione più alta, fare l'upscaling di un clip già abbastanza grande e spedire un file il cui audio o la cui etichetta di prodotto sono cambiati. Apri la pagina del modello Video Upscaler per provare un clip.