Tutoriale
Come usare kling-4.0-flash image-to-video tramite l'API HiAPI: curl e Python
Esercitazione pratica sulle richieste: input immagine del primo fotogramma, polling dei task asincroni, audio sincrono e risoluzione degli errori
- Modello
- kling-4.0-flash
In questa pagina
Funzionamento dell'endpoint kling-4.0-flash image-to-video
kling-4.0-flash/image-to-video è un modello di generazione video condizionato da un'immagine. Gli fornisci un'immagine — il primo fotogramma — insieme a un prompt testuale, e restituisce un video generato che inizia da quel fotogramma e si evolve secondo la tua descrizione.
Il punto più importante da interiorizzare prima di scrivere codice: questa non è una chiamata request/response che restituisce i byte del video nello stesso scambio HTTP. La generazione richiede tempo, quindi l'endpoint segue un modello a task asincrono. La prima richiesta invia un task; successivamente si interroga lo stato del task fino a raggiungere uno stato terminale.
Tieni distinti questi tre concetti, perché corrispondono a tre parti diverse del client:
- Invio — il payload che trasmetti: immagine del primo fotogramma, prompt e opzioni di generazione.
- Riferimento al task — l'identificatore restituito all'invio, usato per interrogare il task in seguito.
- Recupero del risultato — il controllo ripetuto dello stato, che alla fine restituisce il video completato (o l'errore).
Una volta trattato l'endpoint come una coda di task anziché come un RPC, il resto dell'integrazione — intervallo di polling, timeout, retry — diventa una normale pipeline asincrona, non più un caso speciale. Se desideri consultare anche la documentazione più completa dell'endpoint oltre a questa procedura, aprila in un'altra scheda e usala come riferimento mentre segui i passaggi.
Prima di inviare la richiesta
Prima della prima chiamata servono tre cose.
1. Credenziali API
Ti serve una chiave API HiAPI. Ogni richiesta la invia come token bearer tramite l'header Authorization. Non inserirla nel controllo del codice sorgente: leggila da una variabile d'ambiente invece di incollarla nello script.
export HIAPI_API_KEY="your-api-key-here"
2. Percorso dell'endpoint
Tutte le chiamate passano dall'interfaccia unificata HiAPI. L'identificatore del modello che usi è kling-4.0-flash/image-to-video. La richiesta di invio e le successive interrogazioni dello stato puntano allo stesso namespace del modello, quindi conserva l'identificatore in una costante nel codice invece di spargere stringhe letterali ovunque.
3. Immagine del primo fotogramma pronta
Ti serve un'immagine come fotogramma iniziale. Prima di inviarla, stabilisci due cose:
- Come trasmetterla — come URL accessibile pubblicamente o come dati immagine codificati, a seconda di quale forma l'endpoint accetta nel tuo caso d'uso.
- Se è ben formata — formato corretto, leggibile e non così grande da appesantire il corpo della richiesta.
Una regola pratica: mantieni il corpo della richiesta piccolo ed esplicito. Se passi un URL, assicurati che il chiamante possa accedervi senza autenticazione. Se passi dati codificati, verifica che la codifica sia esattamente quella attesa dall'endpoint.
Prepara anche un prompt breve e specifico. I prompt image-to-video funzionano meglio quando descrivono movimento e cambiamento (cosa si muove, come si muove la camera) invece di ripetere ciò che è già visibile nel fotogramma.
Richiesta curl funzionante
Di seguito una chiamata di invio completa. Sostituisci i segnaposto con la tua chiave, la tua immagine e il tuo prompt.
curl -X POST "https://api.hiapi.ai/v1/models/kling-4.0-flash/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Slow dolly-in on the subject as light shifts across the scene",
"image": "https://your-host.example/first-frame.jpg"
}'
Analisi voce per voce:
-X POST— l'invio è un'operazione di scrittura, non una query.- URL — l'identificatore del modello fa parte del percorso dell'endpoint unificato. È l'unico punto in cui specifichi il modello.
Authorization: Bearer $HIAPI_API_KEY— header espanso dalla shell dalla tua variabile d'ambiente. Le virgolette doppie permettono l'espansione della variabile mantenendone il valore come singolo argomento.Content-Type: application/json— il corpo è JSON; senza questo header alcuni gateway rifiutano o interpretano male il payload.-d '{ ... }'— corpo JSON.promptdescrive il movimento;imagefornisce il primo fotogramma. Ogni campo è esplicito — nulla dipende da posizione o da valori predefiniti invisibili.
Un invio riuscito restituisce un corpo JSON contenente l'identificatore del task. Salvalo — quel valore è il riferimento per gestire il task. Se stai esplorando in modo interattivo, puoi passare la risposta a un formattatore JSON per copiare l'identificatore:
curl -s -X POST "https://api.hiapi.ai/v1/models/kling-4.0-flash/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt":"Slow dolly-in as light shifts","image":"https://your-host.example/first-frame.jpg"}' | python -m json.tool
Non dare per scontato che il video sia in questa risposta. Non c'è — questa risposta indica solo che il task è stato accettato.
La stessa richiesta in Python
Il client Python corrisponde esattamente al payload curl. Cambiare linguaggio non altera la semantica, cambia solo il meccanismo con cui vengono inviati i byte. Usa requests e leggi la chiave dalla variabile d'ambiente:
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "kling-4.0-flash/image-to-video"
BASE_URL = "https://api.hiapi.ai/v1/models"
def submit_job(prompt: str, image: str) -> dict:
response = requests.post(
f"{BASE_URL}/{MODEL}",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json={
"prompt": prompt,
"image": image,
},
timeout=30,
)
response.raise_for_status()
return response.json()
job = submit_job(
prompt="Slow dolly-in on the subject as light shifts across the scene",
image="https://your-host.example/first-frame.jpg",
)
print(job)
Punti chiave del porting:
json=al posto di-d— passare un dict fa sì cherequestsserializzi il corpo e imposti il content type. Ottieni lo stesso formato di rete dell'esempio curl senza scrivere JSON a mano.raise_for_status()— converte le risposte non 2xx in eccezioni, così non scambi per errore un corpo di errore per un riferimento al task.timeout=30— l'invio dovrebbe essere rapido. Un timeout generoso evita connessioni bloccate senza mascherare chiamate davvero lente.- Modello in un'unica costante — se in futuro cambi modello, modifichi solo una riga.
Il dict restituito contiene l'identificatore del task, che sarà sfruttato nella sezione successiva.
Gestire il ciclo di vita del task asincrono
Il pattern di integrazione è invia, poi interroga. Due fasi ben distinte.
Fase 1: invia e cattura il riferimento
La chiamata submit_job della sezione precedente restituisce un corpo JSON contenente l'identificatore del task. Salvalo. Ogni controllo di stato successivo ne ha bisogno; perderlo significa perdere il task.
Fase 2: interroga fino allo stato terminale
Il controllo di stato è una richiesta di lettura sullo stesso task. Ripeti a intervalli regolari finché il task raggiunge uno stato terminale — completato o fallito. Un semplice ciclo con limite di tentativi:
import time
def wait_for_job(task_id: str, attempts: int = 60, interval: float = 5.0) -> dict:
for _ in range(attempts):
response = requests.get(
f"{BASE_URL}/{MODEL}",
headers={"Authorization": f"Bearer {API_KEY}"},
params={"task_id": task_id},
timeout=30,
)
response.raise_for_status()
status = response.json()
state = status.get("status")
if state in ("succeeded", "failed"):
return status
time.sleep(interval)
raise TimeoutError(f"Job {task_id} did not finish in time")
Decisioni di progettazione da prendere deliberatamente:
- Limita il numero di cicli. Non fare mai polling infinito. Un numero massimo di tentativi con intervallo fisso garantisce un tempo di attesa massimo prevedibile.
- Dormi tra i controlli, non dentro le richieste. Un polling eccessivo spreca quota e può attivare limiti di frequenza.
- Tratta il fallimento come stato terminale. Un task fallito non diventerà riuscito al controllo successivo: fermati ed esponi l'errore.
- Distingui attesa da completamento. Solo gli stati terminali terminano il ciclo; qualsiasi altro stato significa continuare ad attendere.
- Persisti l'ID del task. Se il processo si blocca a metà polling, vuoi poter recuperare invece di rigenerare.
In produzione, sposta il polling fuori dal thread della richiesta — affidalo a un worker in background o a un consumer di coda — così le generazioni lunghe non tengono aperta una richiesta web.
Usare l'opzione audio sincrono
L'endpoint offre un'opzione audio sincrono. In pratica, per il client questo significa una cosa: se la abiliti, la chiamata blocca fino al completamento della generazione invece di restituire un riferimento al task da interrogare.
Questo cambia il tuo design in modi concreti:
- Il budget di timeout deve aumentare. Una chiamata di generazione bloccante può richiedere molto più tempo di una tipica richiesta API. Imposta il timeout del client per coprire l'intera durata prevista, non solo quella dell'invio.
- Nessun checkpoint intermedio. Con il polling puoi riprendere dopo un crash usando l'ID del task. Con una chiamata bloccante, la connessione che cade significa rifare il lavoro.
- Pressione su thread e connection pool. Una chiamata bloccante occupa un worker per tutta la sua durata. In un server web questo riduce rapidamente la tua capacità di concorrenza.
Quando è accettabile una chiamata bloccante? Quando esegui script one-shot, strumenti CLI o job batch, dove nient'altro attende il risultato e la semplicità conta più del throughput. In questi scenari la chiamata sincrona elimina del tutto il meccanismo di polling e il codice è più breve.
Quando evitarla? In qualsiasi percorso di richiesta rivolto all'utente, in servizi ad alta concorrenza, o ovunque il client possa andare in timeout e riprovare — una chiamata bloccante riprovata può raddoppiare il tuo carico di lavoro. In questi casi mantieni il pattern invio-e-polling asincrono della sezione precedente, disattivando l'opzione sincrona.
Diagnosticare i fallimenti comuni
Affronta i fallimenti per livelli. Il primo errore che vedi è di solito il più superficiale, quindi correggilo e riesegui, invece di indovinare più problemi insieme.
Errori di autenticazione
401 o 403 significano credenziali mancanti, malformate o rifiutate. Verifica che HIAPI_API_KEY sia effettivamente impostata nell'ambiente visto dal tuo processo — una variabile esportata in una shell non passa a un'altra shell o a un container. Conferma che l'header Authorization sia Bearer <key>, con un solo spazio e senza virgolette superflue dal copia-incolla.
Payload malformato
400 di solito significa che il corpo non è interpretabile o mancano campi obbligatori. Ricontrolla di aver inviato Content-Type: application/json, che il JSON sia valido (una virgola finale causa fallimento) e che prompt e image esistano entrambi e siano stringhe non vuote. Per il debug, stampa il corpo effettivamente inviato — non il dict che intendevi inviare.
Problemi con l'input immagine
Questi problemi di solito si manifestano come errori di validazione, non come errori evidenti sull'immagine. Verifica in ordine:
- Raggiungibilità — se passi un URL, recuperalo dallo stesso ambiente di rete da cui parte la richiesta. Un URL che funziona nel browser potrebbe essere bloccato da un firewall o protetto da autenticazione per l'API.
- Formato — conferma che l'immagine sia un file supportato e non corrotto. In caso di dubbi, riesportala.
- Dimensione — immagini troppo grandi possono causare errori di validazione o far superare i limiti al corpo della richiesta.
- Codifica — se invii dati codificati, assicurati che la codifica corrisponda esattamente a quella attesa dall'endpoint; prefissi non corrispondenti o spazi bianchi superflui causano fallimenti.
Fallimenti a livello di task
Se l'invio riesce ma il task termina in stato di fallimento, la richiesta è ben formata ma la generazione non è stata completata. Rileggi il prompt, verifica ambiguità o movimenti fisicamente implausibili, e conferma che l'immagine del primo fotogramma sia davvero utilizzabile come punto di partenza. Riprova una volta con un prompt semplificato prima di ipotizzare un problema sistemico — e registra l'ID del task e il messaggio di errore per correlarli in seguito.
Timeout del ciclo di polling
Il TimeoutError sollevato da wait_for_job significa che i tuoi limiti sono troppo stretti, non che il task sia morto. Aumenta il numero di tentativi o l'intervallo, e verifica se stai interrogando un task ID di un'esecuzione precedente già conclusa.
Parti dalla richiesta minima — un'immagine, un prompt breve, nessun campo opzionale — e aggiungi complessità solo dopo che la base funziona. Quando il payload è piccolo ed esplicito, la maggior parte dei problemi di integrazione scompare.
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