Tutoriale
Come usare topaz-upscale/video tramite l'API HiAPI: esempi curl e Python
In questa pagina
Cosa fa topaz-upscale/video e quando usarlo
topaz-upscale/video è l'endpoint di miglioramento video su HiAPI. Gli invii un video sorgente e delle istruzioni, e restituisce un video migliorato: risoluzione più alta, dettagli fini ricostruiti e, facoltativamente, movimento più fluido tramite interpolazione dei fotogrammi. Questo endpoint va usato quando il materiale esiste già e il problema è la qualità, non la generazione di contenuti.
Scenari d'uso
Attività tipiche che si abbinano naturalmente a questo endpoint:
- Materiale d'archivio e vecchio — vecchie registrazioni, cattura schermo compresse o media ereditati che devono apparire presentabili a risoluzioni moderne.
- Pipeline di rendering — sequenze finite renderizzate a bassa risoluzione per velocità, poi migliorate per la consegna.
- Pulizia del movimento — sorgenti a basso frame rate che necessitano di fotogrammi interpolati per evitare scatti in riproduzione.
- Varianti di consegna — un master, più livelli di output, con miglioramento applicato per livello.
Quando sceglierlo rispetto alle alternative
La decisione si riduce di solito a tre domande:
- Il problema è risoluzione e dettaglio, o contenuto? Se devi inventare nuovi pixel (scene mai riprese), questo non è lo strumento giusto. Il miglioramento presuppone che ci siano fotogrammi sorgente reali alla base.
- La tua pipeline tollera un lavoro asincrono? Le attività video non sono istantanee. Se l'esperienza utente richiede risposte inferiori al secondo, questo endpoint va inserito in un'attività in background, non nel gestore della richiesta.
- Ti servono sia interpolazione dei fotogrammi che upscaling? Se la fluidità del movimento è importante, vuoi entrambe le capacità in un'unica elaborazione, non una catena di strumenti separati.
topaz-upscale/videocopre entrambe.
Se la sorgente è una singola immagine statica, usa invece l'upscaler per immagini. Se la sorgente va bene ma la codifica è scarsa, correggi prima la codifica: il miglioramento non può recuperare i dettagli che una compressione pesante ha già distrutto, e pagherai il calcolo senza guadagnare qualità.
Preparare la richiesta prima della prima chiamata
La maggior parte dei fallimenti alla prima chiamata deriva da elementi mancanti, non da prompt scadenti. Prepara questi prima di scrivere qualsiasi codice.
Account e credenziali
Ti serve una chiave API HiAPI con accesso a topaz-upscale/video. Conserva la chiave in una variabile d'ambiente, non nel codice sorgente: ogni esempio sotto legge HIAPI_API_KEY dall'ambiente.
export HIAPI_API_KEY="your-key-here"
Media sorgente accessibile
Il modello deve poter recuperare il tuo input. Due modalità affidabili:
- URL pubblico o firmato — un URL che il servizio possa scaricare senza autenticazione interattiva. Se il tuo storage richiede link firmati, genera un link con scadenza ampia e ricorda di rigenerarlo in caso di retry, altrimenti le attività lunghe falliranno a metà.
- Carica prima — invia il file tramite il meccanismo di upload della piattaforma e fai riferimento all'identificatore restituito. Per file grandi e per qualsiasi cosa dietro una rete privata, questa è la scelta più sicura.
Caratteristiche della sorgente da verificare
Prima di spendere una chiamata, verifica:
- Durata. Video lunghi significano attività lunghe. Se stai testando, prendi una clip di 5–10 secondi dal centro della sorgente: il centro è di solito più rappresentativo dei fotogrammi iniziali.
- Codec e contenitore. Codec rari a volte non si decodificano. In caso di dubbio, rimuxa in un contenitore comune.
- Frame rate. Registralo con precisione: ti servirà per ragionare sull'interpolazione dei fotogrammi.
- Risoluzione. Annota le dimensioni esatte della sorgente, così il tuo confronto prima/dopo sarà onesto.
Definisci chiaramente l'obiettivo di output
Decidi risoluzione e frame rate di output prima della prima chiamata, non dopo. Impostazioni di miglioramento ragionevoli per portare una sorgente 720p a 1080p sono diverse da quelle per portare una sorgente 480p a 4K. Scrivi l'obiettivo: lo riutilizzerai in ogni richiesta successiva.
Effettuare la chiamata con curl
La richiesta è un POST con corpo JSON verso l'endpoint topaz-upscale/video. Ecco un esempio completo ed eseguibile: sostituisci con il tuo URL media.
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": "Recupera le texture fini su tessuti e pelle, mantieni la grana naturale, interpola a 60fps senza ghosting"
}'
Interpretare la risposta
La risposta immediata conferma l'attività. Riceverai un identificatore dell'attività e un campo di stato. Il lavoro video è asincrono, quindi il modello reale è:
# 1. Invia e acquisisci l'id dell'attività
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. Esegui polling fino allo stato terminale
curl -sS "https://api.hiapi.ai/v1/jobs/$JOB_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY" | jq '.status, .output'
Quando leggi il risultato, tre campi sono importanti:
status— passa da in coda a in esecuzione a stato terminale. Tratta qualsiasi stato non riconosciuto come "continua ad attendere", non come successo.output— presente in caso di successo, contiene l'URL o l'identificatore del video migliorato.error— presente in caso di fallimento. Leggi il messaggio alla lettera; di solito indica il campo problematico.
Se stai iterando sui prompt, metti il corpo della richiesta in un file (request.json) e usa -d @request.json. Questo mantiene pulita la cronologia della shell e ti permette di confrontare diverse versioni della stessa richiesta.
Chiamare lo stesso endpoint da Python
La versione Python è un sottile wrapper sullo stesso contratto HTTP. Usa requests, conserva la chiave nell'ambiente e avvolgi invio e ciclo di polling in una funzione, così chi chiama non deve sapere che è asincrono.
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", "Miglioramento fallito"))
time.sleep(poll_interval)
raise TimeoutError(f"L'attività {job_id} non è stata completata entro il tempo previsto")
Note per usarlo in una pipeline reale
- Usa backoff esponenziale nel polling. Un intervallo fisso di cinque secondi va bene per uno script shell; in produzione aumenta l'attesa con un limite massimo. I video lunghi possono richiedere tempo e interrogare più spesso non li velocizza.
- Idempotenza. Se la chiamata di invio va in timeout, potresti non sapere se l'attività è partita. Registra il corpo della richiesta insieme all'id dell'attività per riconoscere i duplicati, invece di reinviare alla cieca.
- Persisti l'id dell'attività. Salvalo nel database appena lo ricevi. Se il processo muore durante il polling, puoi riprendere per id senza pagare un secondo miglioramento.
Ricette di prompt per l'interpolazione dei fotogrammi
L'interpolazione dei fotogrammi è il punto in cui i prompt sbagliano più facilmente: o sono troppo vaghi per guidare qualcosa, o sono così prescrittivi che il modello insegue obiettivi contraddittori. I prompt convivono con i parametri strutturati; lascia che le parole riguardino l'intento e le caratteristiche del movimento, e che i parametri portino gli obiettivi numerici.
Schema: descrivi il movimento, non la matematica
Scarso:
interpolate
Migliore:
Interpola a 60fps fluidi. Mantieni il ritmo originale del movimento, senza cambiare la velocità. Le panoramiche e i movimenti di camera devono essere lineari e stabili; evita distorsioni ai bordi dei fotogrammi.
Hai già indicato il frame rate di destinazione nelle parameters. Il prompt deve descrivere come appare il movimento fluido per questo materiale.
Schema: nomina gli artefatti da evitare
Rendi fluido da 24p a 60fps. Evita il ghosting sulle mani in movimento rapido, evita strascichi attorno a oggetti sottili come ringhiere e capelli. Lo sfondo statico deve rimanere perfettamente immobile.
Nominare modalità di fallimento specifiche è molto più efficace di "alta qualità". Il modello può verificare il proprio output rispetto a istruzioni concrete.
Schema: separa movimento e texture
In questo passaggio concentrati solo sulla fluidità del movimento. Mantieni i dettagli e la grana esistenti invariati: il ripristino delle texture è gestito separatamente.
Utile quando concateni due fasi di elaborazione, così ogni prompt ha una sola responsabilità.
Schema: gestire materiale con movimento misto
Per clip di interviste con camera fissa ma soggetto in movimento, dire esplicitamente che la camera è statica funziona bene:
Interpola a 60fps. La camera è fissa: lo sfondo deve rimanere completamente immobile o sfarfallare. Solo la testa e le mani di chi parla devono mostrare movimento fluido.
Resisti alla tentazione di scrivere lunghi saggi. Tre frasi che coprono il movimento desiderato, gli artefatti da evitare e ciò che deve rimanere statico coprono quasi tutti i casi.
Ricette di prompt per la ricostruzione dei dettagli
La ricostruzione dei dettagli è la metà del lavoro che inventa strutture fini plausibili. La modalità di fallimento è la texture allucinata: la pelle sembra plastica, la vegetazione diventa rumore, il testo diventa illeggibile. Il prompt deve porre un limite all'invenzione.
Schema: ancorati alla sorgente
Ricostruisci i dettagli coerenti con i fotogrammi sorgente. Non inventare texture che i pixel originali non suggeriscono. Dove i dettagli sono davvero persi, preferisci un risultato morbido ma credibile a un rumore nitidizzato.
Questa singola istruzione previene la maggior parte delle patologie di nitidezza eccessiva.
Schema: nomina i materiali nell'inquadratura
Recupera i dettagli fini delle texture dei tessuti, dei capelli e dei pori della pelle. Mantieni l'incarnato naturale e i pori irregolari: evita l'aspetto liscio e ritoccato. Le superfici metalliche devono conservare i riflessi esistenti senza generarne di nuovi.
Le istruzioni specifiche per materiale danno al modello vincoli operativi, senza bisogno di un intero paragrafo di generalità.
Schema: proteggi testo e grafica
Questa clip contiene sottotitoli a schermo e loghi. Il testo deve rimanere nitido, leggibile e non distorto. Non ridisegnare né cambiare lo stile di qualsiasi elemento grafico.
Il testo è il dettaglio a più alto rischio: sottotitoli illeggibili sono peggio di sottotitoli leggermente sfocati. Se la leggibilità è cruciale, verificala in fase di confronto invece di fidarti del prompt.
Schema: modulare intenzionalmente la nitidezza
Applica una quantità contenuta di recupero dei dettagli. L'obiettivo è materiale dall'aspetto naturale a 1080p, non un fotogramma nitidizzato. Una leggera morbidezza è accettabile; ringing e aloni non lo sono.
Combinare entrambi
Quando interpoli e ricostruisci nella stessa elaborazione, scrivi un prompt che copra entrambi, ma con ogni proposizione dedicata a un solo aspetto:
Ricostruisci le texture fini — tessuti, capelli, pelle — in coerenza con la sorgente, evitando una levigatezza plastica. Interpola a 60fps con movimento stabile, senza ghosting sulle mani e con lo sfondo completamente immobile.
Confrontare l'output prima e dopo
Un video migliorato che sembra straordinario su un singolo fotogramma può crollare in movimento. Stabilisci un flusso di confronto fisso ed eseguilo ogni volta che cambi parametri o prompt; altrimenti stai indovinando, e le ipotesi costano care.
Costruisci un set standard di clip di test
Scegli tre brevi clip (5–10 secondi ciascuna) che non cambierai mai:
- Facile — buona illuminazione, movimento lento, sorgente pulita. Dovrebbe apparire quasi perfetta; se non lo è, qualcosa è configurato male.
- Difficile — movimento rapido, dettagli fini o tipi di movimento misti. Qui appariranno gli artefatti di interpolazione.
- Avversariale — testo a schermo, strutture sottili o compressione pesante preesistente. Qui si manifesteranno le allucinazioni.
Esegui ogni modifica di prompt o parametri su tutte e tre. Una modifica che aiuta la clip facile ma danneggia quella avversariale non è un miglioramento.
Confronta in questo ordine
- Confronto affiancato al 100%. Non usare l'adattamento alla finestra: gli artefatti si nascondono. Controlla le stesse aree ritagliate: volti, aree con testo e aree ad alto movimento.
- Scorrimento fotogramma per fotogramma. Avanza fotogramma per fotogramma nelle parti ad alto movimento, cercando ghosting, distorsioni e sfarfallii.
- Riproduzione a velocità reale. Molti artefatti scompaiono scorrendo fotogramma per fotogramma e appaiono in movimento, e viceversa. Guarda entrambi.
- Verifica della leggibilità del testo. Leggi ogni sottotitolo nella versione migliorata confrontandolo con la sorgente. È il controllo oggettivo passa/non passa più rapido a tua disposizione.
Qualità e costo insieme
La fatturazione segue il lavoro svolto dall'endpoint: durata e risoluzione dell'output sono i fattori determinanti; consulta il pannello dei prezzi del sito per le tariffe attuali. Conseguenza pratica: clip più lunghe con miglioramenti marginali di qualità sono di solito un affare peggiore di clip più brevi con miglioramenti evidenti. Per ogni configurazione candidata, registra durata e risoluzione dell'output prodotte e chiediti se il miglioramento visibile vale la spesa. Conserva i vincitori, scarta gli altri e, prima di collegare l'endpoint a una pipeline automatizzata, congela una configurazione e documentala — prompt, parametri e risultati dei test — così le modifiche future potranno essere misurate rispetto ad essa.
Risolvere i problemi comuni delle richieste
La maggior parte degli attriti di integrazione con topaz-upscale/video rientra in poche categorie. Affrontale in questo ordine.
Autenticazione e accesso
401 significa che la chiave manca, è malformata o non è stata inviata: verifica che la variabile d'ambiente sia effettivamente impostata nella shell che esegue il comando, non solo nell'editor. 403 di solito significa che la chiave è valida ma all'account manca l'accesso a questo modello. Verifica che il nome del modello sia scritto esattamente topaz-upscale/video.
Il servizio non riesce a recuperare il tuo video
Questo è il fallimento più comune. Sintomo: l'attività fallisce presto con un errore di download o di input. Cause:
- L'URL è privato o richiede un login interattivo.
- L'URL firmato scade prima che l'attività raggiunga la fase di download: soprattutto nelle code lunghe.
- L'host blocca le richieste automatiche o è così lento da andare in timeout.
Soluzione: carica il file tramite la piattaforma e fai riferimento all'identificatore restituito, oppure genera un URL firmato con scadenza ampia al momento dell'invio.
Fallimento della decodifica
Se l'errore menziona il media invece della richiesta, rimuxa la sorgente in un contenitore comune e riprova. Prova prima il file in locale: se il tuo stesso player fatica, anche il servizio farà fatica.
L'attività continua a girare o va in timeout
Le sorgenti lunghe richiedono molto tempo e alcune richieste impiegano in modo sproporzionato. Prima di reinviare, controlla lo stato dell'attività per id: potresti vedere un'attività in coda, non un'attività fallita. Reinviare alla cieca può raddoppiare il costo. Se fai polling da uno script, assicurati che il timeout del tuo client sia più lungo della durata prevista dell'attività, altrimenti abbandonerai un'attività che sta ancora funzionando correttamente.
L'output sembra peggiore della sorgente
La richiesta è andata a buon fine ma il risultato è troppo nitido, plastico o con ghosting. Questo è un problema di prompt, non dell'API: torna alle ricette per la ricostruzione dei dettagli e l'interpolazione, aggiungi limiti espliciti — "coerente con la sorgente", "nessun ghosting", "lo sfondo deve rimanere immobile". Poi riesegui il tuo set di confronto standard.
Fallimenti intermittenti e non riproducibili
Registra insieme il corpo completo della richiesta e l'id dell'attività per ogni chiamata. Senza entrambi, non puoi capire se il fallimento derivi da un payload diverso o da un problema temporaneo del servizio. Con una dozzina di fallimenti registrati, il pattern di solito emerge in pochi minuti.
Articoli correlati
Vedi tutti gli articoli →-
Tutoriale
Guida pratica a gpt-6.2-sol: 5 utilizzi ad alto valore dei modelli testuali nel business
-
Tutoriale
Guida pratica a gpt-6.2-astra: integrazione e punti chiave per 5 scenari testuali ad alto valore
Checklist dal punto di vista dello sviluppatore, dalla selezione degli scenari all'implementazione ingegneristica
-
Tutoriale
Scenari pratici di Tripo H3.1: 5 utilizzi ad alto valore e punti di implementazione
Da text-to-3D alla ricostruzione multi-view: scegliere modalità e parametri giusti per ogni scenario di business