Tutoriale
Come chiamare kling-4.0-flash Reference-to-Video tramite l'API HiAPI: pratica con curl e Python
Pratica eseguibile per la generazione video con più immagini di riferimento, polling asincrono e guida alla risoluzione dei problemi
- Modello
- kling-4.0-flash
In questa pagina
Quando usare la generazione video da immagini di riferimento invece della generazione da testo
La generazione video da testo è lo strumento dello sceneggiatore: descrivi una scena e il modello crea tutto dal nulla. La generazione video da immagini di riferimento è lo strumento del regista: fornisci al modello una o più immagini e gli chiedi di generare un movimento in cui quei soggetti, quello stile o quella composizione restino riconoscibili. Su HiAPI questa distinzione si riflette a livello di endpoint: kling-4.0-flash/reference-to-video è una rotta separata rispetto alla normale chiamata di generazione video da testo; scegliere l'endpoint giusto fin dall'inizio evita di cadere nell'ingegneria dei prompt che non riesce mai a riprodurre appieno un aspetto specifico.
Scegli la generazione video da immagini di riferimento quando vale una qualsiasi delle seguenti condizioni:
- L'identità o la coerenza del prodotto è fondamentale. Hai un turnaround di un personaggio, una foto di prodotto o una mascotte, e l'output non deve trasformarsi in una figura simile generica.
- Devi combinare più fonti. Una scena può richiedere un'immagine per definire il personaggio e un'altra per definire l'ambiente o l'abbigliamento. Più immagini di riferimento ti permettono di esprimere questa composizione in modo esplicito, invece di affidarti alla prosa.
- Il trasferimento di stile è l'obiettivo. Vuoi portare nella scena in movimento la tonalità, l'illuminazione o lo stile di rendering dell'immagine fornita.
- Stai iterando su un'inquadratura. Le immagini di riferimento rendono confrontabili più riesecuzioni, perché l'ancoraggio visivo resta fisso e devi regolare solo i parametri legati al movimento.
Continua a usare la generazione video da testo quando stai esplorando concetti, non hai immagini con diritti chiari da usare come ancoraggio, oppure la richiesta è astratta ("una lenta ripresa aerea attraverso la nebbia all'alba") e qualsiasi interpretazione ragionevole va bene. Le immagini di riferimento vincolano il modello, e i vincoli sono utili solo quando ne hai davvero bisogno.
Una regola pratica: se ti accorgi di scrivere un intero paragrafo per descrivere l'aspetto esatto di un oggetto specifico, è il segnale per passare a questo endpoint e fornire direttamente l'immagine. Le descrizioni consumano token e possono comunque andare fuori strada; le immagini di riferimento ancorano.
Struttura della richiesta: immagini di riferimento e parametri principali
L'endpoint accetta un corpo JSON. Le parti con cui avrai realmente a che fare si dividono in tre categorie: immagini di riferimento, prompt e parametri che modellano l'output.
Immagini di riferimento
Le immagini di riferimento vengono passate come array, così lo stesso campo può passare naturalmente da una a più immagini. Ogni voce è un URL che il servizio deve poter recuperare. Vincoli pratici da considerare in fase di progettazione:
- Usa URL HTTPS accessibili pubblicamente, o URL a cui il tuo account ha accesso. Percorsi di file locali e URI
file://non possono essere recuperati da un servizio remoto. - Preferisci un hosting stabile agli URL firmati che scadono dopo pochi minuti: le attività di lunga durata potrebbero recuperarli in un momento che non avevi previsto.
- Mantieni ogni immagine focalizzata. Un'immagine pulita del soggetto è più utile di un collage confuso, perché il modello deve distinguere ciò che vede.
- L'ordine può influire su come vengono interpretate le immagini di riferimento, quindi nel codice rendi deterministico l'ordine dell'array invece di affidarti all'ordine di iterazione del dizionario.
Prompt
Dopo aver fornito le immagini di riferimento, il prompt deve descrivere movimento, inquadratura e atmosfera, non l'aspetto. Spiega come si muove il soggetto, come si muove la camera, quale ritmo si percepisce. Ridiscrivere le immagini di riferimento spreca il budget del prompt e può entrare in conflitto con l'ancoraggio che hai appena fornito.
Parametri che modellano l'output
Oltre a prompt e all'array delle immagini di riferimento, il corpo della richiesta contiene di solito campi che controllano il formato dell'output e il comportamento della generazione. Considerali come le manopole da regolare per ultime: prima fai funzionare la chiamata con i valori predefiniti, verifica che le immagini di riferimento siano effettivamente rispettate, poi ritocca le impostazioni dell'output. I nomi dei campi e i valori ammessi sono definiti nella documentazione di riferimento dell'endpoint; inviare campi non riconosciuti è una causa comune di rifiuto del corpo della richiesta, quindi convalida rispetto allo schema della documentazione invece di andare a tentativi.
Il modello mentale è semplice: le immagini di riferimento dicono cosa, il prompt dice come si muove, i parametri dicono cosa ricevi indietro.
Richiesta curl funzionante
Prima di scrivere il codice client, il modo più affidabile per verificare il corpo della richiesta è una chiamata curl. Imposta credenziali e input come variabili di shell, mantieni il JSON leggibile, poi invia la richiesta.
API_KEY="$HIAPI_API_KEY"
BASE_URL="https://api.hiapi.ai" # usa l'URL di base mostrato nella tua console
curl -sS -X POST "$BASE_URL/v1/kling-4.0-flash/reference-to-video" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Il personaggio si gira verso la finestra, la camera si avvicina lentamente; luce mattutina morbida, ritmo calmo.",
"reference_images": [
"https://your-cdn.example.com/refs/character-front.png",
"https://your-cdn.example.com/refs/location-window.jpg"
]
}'
Prima di eseguire, controlla tre cose:
- Percorso e prefisso di versione. Verifica la rotta esatta con la documentazione dell'endpoint del tuo account; il percorso include il numero di versione e un prefisso obsoleto restituisce un non trovato anziché un errore di convalida.
- Header di autenticazione. La chiave va nell'header
Authorizationcome bearer token. Non inserirla mai nel corpo della richiesta né nella stringa di query, altrimenti finirà nei log. - Segnaposto. Ogni valore da sostituire è chiaramente un segnaposto: il commento dell'URL di base, i due URL CDN, il prompt. Prima di dichiarare il tutto pronto per la produzione, cerca
example.comnella richiesta.
Un invio riuscito restituisce un identificatore di attività, non il video completato. Cattura quell'identificatore dal corpo della risposta; servirà nel passaggio successivo di polling. Passare la risposta a un formattatore JSON (| jq .) rende l'ID attività immediatamente visibile ed è una buona abitudine.
La stessa chiamata in versione Python
La differenza principale nella versione Python sta nel modo di costruire il corpo della richiesta: crea un dict, serializzalo una volta e separa la funzione di invio dalla logica di polling, così puoi testarle in modo indipendente.
import os
import requests
BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai")
API_KEY = os.environ["HIAPI_API_KEY"]
REFERENCE_IMAGES = [
"https://your-cdn.example.com/refs/character-front.png",
"https://your-cdn.example.com/refs/location-window.jpg",
]
def submit_reference_video(prompt: str) -> str:
payload = {
"prompt": prompt,
"reference_images": REFERENCE_IMAGES,
}
response = requests.post(
f"{BASE_URL}/v1/kling-4.0-flash/reference-to-video",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=30,
)
response.raise_for_status()
return response.json()["task_id"]
if __name__ == "__main__":
task_id = submit_reference_video(
"Il personaggio si gira verso la finestra, la camera si avvicina lentamente."
)
print("inviato:", task_id)
Le seguenti accortezze evitano sofferenze inutili:
- Leggi la chiave dalle variabili d'ambiente. Le chiavi codificate finiscono prima o poi nella cronologia git e negli screenshot.
- Usa
json=invece didata=, così il client imposta correttamente il content type ed effettua l'escape del corpo della richiesta. - Imposta un
timeoutesplicito. L'attesa infinita predefinita trasforma una connessione bloccata in un processo in stallo. - Chiama
raise_for_status()prima di analizzare la risposta, così un corpo 4xx viene segnalato come errore HTTP anziché causare un confusoKeyErrorsulla risposta JSON. - Verifica sulla documentazione il nome del campo della risposta che contiene l'identificatore di attività, invece di dare per scontato
task_id; adatta di conseguenza la riga di estrazione.
Lascia che submit_reference_video restituisca solo l'ID. Il polling è una responsabilità separata e va collocato in una propria funzione.
Gestire il ciclo di vita delle attività asincrone
La generazione video richiede tempo, quindi l'endpoint è asincrono per progettazione. La chiamata di invio restituisce rapidamente un identificatore di attività; il lavoro vero avviene dopo. La tua integrazione deve modellarlo, e il modello corretto più semplice prevede tre stati: pending o processing (continua ad attendere), succeeded (recupera l'output), failed (leggi l'errore e fermati).
Esegui il polling dell'endpoint delle attività a intervalli e imposta un limite al tempo di attesa totale:
import time
def wait_for_task(task_id: str, interval: float = 5.0, max_wait: float = 600.0) -> dict:
deadline = time.monotonic() + max_wait
url = f"{BASE_URL}/v1/tasks/{task_id}"
while time.monotonic() < deadline:
r = requests.get(url, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30)
r.raise_for_status()
data = r.json()
status = data.get("status")
if status in ("succeeded", "failed"):
return data
time.sleep(interval)
raise TimeoutError(f"l'attività {task_id} non è terminata entro {max_wait}s")
Adatta le stringhe di stato e il percorso delle attività a quanto specificato nella documentazione: la struttura sopra è solo un modello, e la maggior parte degli errori in questo ambito deriva dall'aver dato per scontata un'etichetta di stato inesistente.
Buone abitudini di polling da adottare presto:
- Backoff progressivo. Un intervallo fisso e breve martella l'API senza alcun beneficio. Parti da un valore moderato e aumenta il tempo di sospensione tra un tentativo e l'altro.
- Limita sempre il ciclo. Un
while Trueattorno a un'attività remota è solo un guasto in attesa di accadere. Il limite sopra lancia un'eccezione anziché bloccarsi. - Persisti l'ID attività. Se il processo va in crash dopo l'invio, quell'ID è l'unico modo per recuperare il risultato senza pagare una seconda generazione.
- Tratta
failedcome stato terminale. Non ritentare un'attività fallita continuando a interrogarla; leggi l'errore e, se opportuno, invia di nuovo un corpo della richiesta corretto. - Gestisci esplicitamente la scadenza. I risultati delle attività potrebbero non essere disponibili per sempre, quindi scarica e archivia l'output non appena l'attività ha successo.
Errori comuni e come risolverli
La maggior parte dei fallimenti di prima integrazione rientra in poche categorie. Prima di modificare il codice, associa il sintomo alla causa.
Errori di autenticazione e autorizzazione
401 o 403 significano quasi sempre credenziali errate, mancanti o con scope errato. Verifica che l'header sia esattamente Authorization: Bearer <key>, controlla che la variabile d'ambiente sia effettivamente popolata nel processo che effettua la chiamata (le esportazioni della shell non si propagano alle unit systemd) e controlla che la chiave non sia stata ruotata o revocata.
Problemi con le immagini di riferimento
Se la richiesta viene rifiutata per un'immagine, o la generazione ignora un'immagine di riferimento, il sospetto ricade sull'URL. Verifica che il link sia risolvibile dall'esterno della tua macchina: nomi host interni o indirizzi localhost non sono raggiungibili dal servizio. Controlla la scadenza degli URL firmati, verifica che il file sia davvero un'immagine e non una pagina di errore HTML restituita con stato 200, e controlla i limiti di dimensione e formato. Una singola voce errata in un array di più immagini può far fallire l'intera richiesta, quindi in fase di debug testa le immagini di riferimento una alla volta.
Corpo della richiesta non valido
Un 400 con messaggio di convalida di solito significa che il corpo della richiesta è malformato: il livello superiore è un array anziché un oggetto, manca un campo obbligatorio, reference_images viene inviato come stringa tra virgolette anziché come array, oppure un nome di parametro non è riconosciuto. Confronta campo per campo il tuo corpo della richiesta con lo schema della documentazione e registra il corpo esatto che invii: il difetto è spesso una differenza di serializzazione tra il percorso di test e quello di produzione.
Errori di rotta o di metodo
Un 404 di solito indica un percorso errato, non un modello non disponibile. Ricontrolla sulla documentazione il prefisso di versione e il nome dell'endpoint, e verifica che l'invio utilizzi POST e la query dello stato dell'attività GET.
Timeout ed errori di polling
Se l'invio stesso va in timeout, aumenta moderatamente il timeout del client e riprova; ma se l'attività è già stata accettata, non reinviare alla cieca, altrimenti pagherai una generazione duplicata. Se il polling non termina mai, è probabile che il controllo dello stato confronti la stringa sbagliata; registra il valore di stato grezzo nelle prime iterazioni di polling per vedere cosa viene effettivamente restituito.
Limiti di frequenza
429 significa che devi rallentare. Rispetta l'intervallo indicato anziché riprovare subito, e applica un backoff esponenziale con jitter per evitare che processi worker paralleli ritentino in sincrono.
Checklist di produzione prima del lancio
Codice che funziona in un notebook non equivale a un'integrazione affidabile. Prima di esporre questo endpoint agli utenti, stringi i margini operativi.
- Configurazione. Conserva l'URL di base e la chiave API in variabili d'ambiente o in un gestore di segreti, mai nel codice sorgente. Imposta il percorso dell'endpoint come costante, così un aggiornamento di versione richiede una sola riga.
- Retry con backoff. Per i guasti transitori (reset di connessione, 429, 5xx) usa retry con backoff esponenziale e jitter. Non ritentare gli errori di convalida 4xx: falliranno allo stesso modo.
- Disciplina di idempotenza. Registra ogni ID attività inviato insieme ai suoi input. Al riavvio, riprendi il polling delle attività esistenti anziché inviarne di nuove.
- Attesa limitata. Imposta timeout espliciti sia per il client HTTP sia per il ciclo di polling, e instrada i timeout verso un percorso di messaggi non recapitabili verificabile da una persona, anziché scartarli silenziosamente.
- Log strutturati. Registra ID attività, transizioni di stato con timestamp, tempi di invio e completamento, e il corpo dell'errore in caso di fallimento. Oscura i segreti e tronca i prompt quando contengono dati utente.
- Gestione dell'output. Non appena l'attività ha successo, scarica il media generato nel tuo storage e verifica il risultato prima di mostrarlo all'utente.
- Visibilità dei costi. La fatturazione varia con l'utilizzo, quindi traccia quante attività sono state inviate per funzionalità e per utente. I cicli di retry che reinviano in condizioni di incertezza sono la causa più comune di spese impreviste.
- Igiene degli input. Convalida gli URL di riferimento e la lunghezza dei prompt già dalla tua parte. Intercettare localmente un URL errato è più rapido ed economico di un round trip.
Fatto questo, l'integrazione è uno strato leggero e prevedibile: costruisci il corpo della richiesta, invia, esegui il polling, archivia. Parti dalla documentazione di riferimento dell'endpoint, esegui una volta l'esempio curl, poi trasferisci lo stesso corpo della richiesta in Python: una richiesta che funziona nella shell funzionerà anche nel tuo servizio.
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