Blog

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

Nov 12, 2026
Immagine di copertina: una pila di fogli color bianco crema disposti in modo sfalsato, con i bordi delineati in nero carbone, tra cui è inserita una pagina di guardia color rosso ruggine, che proietta sotto di sé un'ombra netta.
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. prompt descrive il movimento; image fornisce 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ì che requests serializzi 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.

Inizia a creare con artefatti IA persistenti

Ottieni la tua chiave API e chiama modelli di immagini, video e audio tramite un'unica API basata sui task.

Leggi la documentazione API