Come chiamare kling-4.0/image-to-video su HiAPI: curl, Python e polling

Cosa fa l'endpoint kling-4.0/image-to-video

kling-4.0/image-to-video trasforma una singola immagine statica in un breve video generato. Su HiAPI è disponibile come endpoint basato su attività: si invia un'immagine e una descrizione in stile prompt che spiega come si dovrebbe muovere l'inquadratura, e l'API restituisce immediatamente un handle dell'attività, anziché il video finale completato.

A livello di richiesta, chi chiama deve fornire:

• l'identificatore del modello (kling-4.0/image-to-video),
• l'immagine di origine (di solito un URL immagine accessibile pubblicamente),
• una descrizione testuale che guidi il movimento dell'immagine o ciò che dovrebbe accadere nella scena,
• tutte le opzioni di generazione aggiuntive documentate per questo modello da questo endpoint.

Ciò che viene restituito non è il video stesso. La risposta di invio contiene un identificatore di attività e uno stato iniziale. La clip video vera e propria diventa disponibile solo dopo il completamento dell'attività di generazione, e a quel punto puoi recuperarla facendo riferimento a quell'identificatore.

Questa separazione è l'intero modello mentale dell'endpoint: invia → ottieni l'id dell'attività → esegui il polling dello stato → scarica il risultato. Ogni sezione che segue è una variante di questo ciclo.

Poiché l'endpoint è asincrono, il tuo codice di integrazione ha due responsabilità anziché una: deve inviare una richiesta di invio ben formata e deve gestire il flusso successivo finché l'attività non raggiunge uno stato terminale. Se gestisci bene questi due punti, il resto è solo normale lavoro di collegamento.

Prerequisiti e autenticazione

Prima di qualsiasi chiamata servono due cose: un account HiAPI con accesso a questo modello e una chiave API emessa dalla console.

L'autenticazione avviene per richiesta. Ogni chiamata API include la tua chiave in un header HTTP — il modello standard è un header di autorizzazione in stile bearer:

Authorization: Bearer <YOUR_HIAPI_API_KEY>

Non far finire mai la chiave nel sistema di controllo versione. Le pratiche abituali sono:

• Conservarla in una variabile d'ambiente (ad esempio HIAPI_API_KEY) e leggerla a runtime.
• Non incollarla mai nel codice client, né in un comando curl che poi finirà in un repository.
• Se la chiave viene esposta, ruotala dalla console.

Esportala nella shell, così che gli esempi curl e Python che seguono possano leggerla:

export HIAPI_API_KEY="your-key-here"

Ti serve anche un URL immagine accessibile. L'endpoint usa le immagini per riferimento, quindi un percorso di file locale sul tuo laptop non funziona — ospita l'immagine dove ha un URL HTTPS stabile oppure, se la piattaforma offre un meccanismo di risorse, carica l'immagine e usa il riferimento restituito.

Una volta esportata la chiave e resa accessibile l'immagine, puoi inviare l'attività.

Analisi passo passo della richiesta curl

Una richiesta di invio completa ha questo aspetto:

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-4.0/image-to-video",
    "input": {
      "image": "https://example.com/your-image.jpg",
      "prompt": "Una lenta carrellata in avanti mentre il soggetto si volta verso la luce; ombre morbide del pomeriggio"
    }
  }'

Analisi parte per parte:

• -X POST — la creazione dell'attività è POST, non GET. La richiesta trasporta un corpo che descrive il lavoro.
• URL — l'endpoint unificato delle attività HiAPI. Per i modelli basati su attività questa è l'unica rotta; il modello si sceglie nel corpo, non nel percorso.
• Authorization — la tua chiave, come descritto nella sezione precedente.
• Content-Type: application/json — il corpo è JSON; se ometti o sbagli questo header, il server di solito rifiuta la richiesta prima ancora che raggiunga il modello.
• model — la stringa letterale kling-4.0/image-to-video. Considerala esatta e sensibile al maiuscolo/minuscolo; un errore di battitura produce un errore di modello non trovato, non un messaggio utile.
• input.image — l'immagine statica di origine, fornita come URL. È il fotogramma che il modello deve animare, quindi scegli un'immagine nitida e ben composta.
• input.prompt — indicazioni in linguaggio naturale. Descrivi il movimento e il comportamento della camera (push-in, pan, movimento del soggetto) e l'atmosfera generale. Prompt vaghi producono movimenti vaghi.

La risposta immediata è un oggetto attività, non un video. Contiene l'identificatore del lavoro e un campo di stato — subito dopo l'invio di solito è qualcosa come in coda o in attesa. Salva quell'identificatore; è l'unica informazione che ti serve per controllare il lavoro in seguito.

A questo punto la clip video non esiste ancora. È il comportamento previsto; la sezione successiva mostra come gestirlo.

La stessa chiamata in Python

La versione Python fa esattamente la stessa cosa — stesso endpoint, stessi header, stesso corpo — quindi lo strumento che scegli non cambia il protocollo.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]

payload = {
    "model": "kling-4.0/image-to-video",
    "input": {
        "image": "https://example.com/your-image.jpg",
        "prompt": "Una lenta carrellata in avanti mentre il soggetto si volta verso la luce; "
                  "ombre morbide del pomeriggio",
    },
}

resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=60,
)

resp.raise_for_status()
task = resp.json()
task_id = task["id"]
print("submitted:", task_id, task.get("status"))

Alcuni punti da tenere presenti nella pratica:

• Usa json=payload invece di serializzare manualmente una stringa. Imposta il content type per te ed evita errori di virgolette.
• Mantieni la richiesta di invio e le operazioni successive nella stessa funzione o classe, così l'id dell'attività non si perde tra un passaggio e l'altro.
• Imposta timeout espliciti. La chiamata di invio deve tornare rapidamente; crea solo il lavoro, non attende il video.
• Non chiamare raise_for_status() e poi presumere che l'attività esista — una risposta non 2xx significa che nessuna attività è stata creata, e il corpo dell'errore di solito ti dice quale campo è sbagliato.

Se stai costruendo un servizio, racchiudi questa chiamata in un piccolo client, con un metodo per l'invio e uno per il controllo dello stato. Così retry, logging e gestione della chiave restano in un solo punto invece di essere sparsi tra i vari punti di chiamata.

Polling dell'attività asincrona fino al completamento

La generazione video da immagine richiede molto più tempo di un completamento chat — il modello deve sintetizzare molti fotogrammi, codificarli e archiviare il risultato. Non è possibile restituire la clip senza tenere aperta la connessione a lungo nella risposta di invio, perciò l'endpoint è asincrono per progetto.

Come controllare lo stato

Esegui il polling dell'attività per identificatore con una richiesta GET:

curl "https://api.hiapi.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

La risposta descrive il lavoro: il suo stato e, una volta completato, l'output. Lo stato di solito passa da uno stato in coda a uno in esecuzione e poi a uno terminale — ad esempio riuscito, oppure fallito con un messaggio di errore.

Ciclo di polling semplice in Python

import time

def wait_for_task(session, base_url, task_id, timeout=900):
    deadline = time.time() + timeout
    delay = 2.0
    while time.time() < deadline:
        r = session.get(f"{base_url}/tasks/{task_id}", timeout=30)
        r.raise_for_status()
        data = r.json()
        status = data.get("status")

        if status in ("succeeded", "failed"):
            return data

        time.sleep(delay)
        delay = min(delay * 1.5, 15.0)  # backoff graduale, con limite massimo

    raise TimeoutError(f"task {task_id} did not finish in time")

Indicazioni sul backoff

• Inizia con intervalli brevi e aumentali gradualmente. La generazione non termina nel primo secondo, quindi chiamare l'endpoint con troppa frequenza spreca solo quota e attiva i limiti di frequenza.
• Limita l'intervallo in modo da notare tempestivamente i lavori completati — in stato stabile bastano pochi secondi.
• Imposta sempre una scadenza rigida. Senza un limite, un'attività che non finirà mai è indistinguibile da una che impiega insolitamente tanto.
• Esegui il polling da un processo in background o da un job pianificato, non bloccando una richiesta web. Se l'utente attende nell'interfaccia, fai interrogare al frontend il tuo endpoint di stato.
• Riprova in caso di errori di rete transitori nelle chiamate di stato, ma non riprovare attività già segnalate come failed — in quel caso l'azione corretta è inviare una nuova attività.

Recupero e archiviazione della clip video restituita

Quando il polling restituisce uno stato terminale di successo, l'oggetto attività contiene il riferimento all'output del video generato — un URL di risorsa o riferimento equivalente che punta al video completato.

result = wait_for_task(session, "https://api.hiapi.ai/v1", task_id)
if result["status"] != "succeeded":
    raise RuntimeError(result.get("error") or "generation failed")

video_url = result["output"]["video_url"]

with session.get(video_url, stream=True, timeout=120) as r:
    r.raise_for_status()
    with open(f"{task_id}.mp4", "wb") as f:
        for chunk in r.iter_content(chunk_size=1 << 16):
            f.write(chunk)

Qui di solito emergono due decisioni di progettazione.

Scarica tempestivamente. Gli URL di output di solito hanno una scadenza. Se intendi conservare la clip, copiala nel tuo storage anziché passare all'utente l'URL grezzo sperando che resti valido.

Archivia i metadati insieme al file. Persisti l'id dell'attività, il prompt, il riferimento all'immagine di origine e l'ora di creazione insieme al video. Quando in futuro qualcuno chiederà perché la clip appare così, quel registro è la risposta.

Per offrire un servizio, il modello comune è: genera nel backend, archivia il file nell'object storage e restituisci al client un tuo URL stabile. Così la tua applicazione controlla accesso, scadenza e cache, invece di dipendere dal ciclo di vita della risorsa generata.

Se vuoi rigenerare con un movimento diverso, invia una nuova attività con un prompt modificato — ogni attività è indipendente, senza bisogno di modificare quella completata.

Diagnosi delle richieste fallite

Quando qualcosa non va, parti dalla struttura della richiesta e procedi verso l'esterno. La maggior parte dei fallimenti si riduce a poche cause.

La chiamata di invio restituisce un errore

• Stringa del modello errata. kling-4.0/image-to-video deve corrispondere esattamente, maiuscole e barra incluse. Stampa la stringa che stai effettivamente inviando, invece di fidarti del file di origine.
• Autenticazione rifiutata. Verifica che l'header sia Authorization: Bearer <key> — non la chiave nuda, non un parametro di query — e che la variabile d'ambiente sia impostata nella stessa shell o processo che esegue la richiesta.
• Immagine non accessibile. L'immagine deve essere raggiungibile dalla piattaforma via HTTPS. URL localhost, bucket privati o host con hotlink protection falliranno. Apri l'URL in una finestra in incognito per verificare che si risolva senza autenticazione.
• Campo mancante o con nome errato. Il corpo annida gli input del modello sotto input. Mettere prompt o image al livello superiore invece che dentro input è un errore comune; gli errori di validazione di solito indicano il nome del campo.
• Content type. Inviare un corpo JSON senza Content-Type: application/json porta a un rifiuto prima ancora che il modello venga coinvolto.

L'attività è stata creata ma non è mai riuscita

• Polling troppo scarso o assente. Controlla che il tuo ciclo stia effettivamente girando e che i valori di stato confrontati corrispondano a quelli restituiti dall'API. Un errore di battitura nel controllo dello stato terminale provoca un ciclo infinito.
• L'attività diventa failed. Leggi il messaggio di errore nell'oggetto attività; di solito punta all'input — ad esempio un'immagine che non può essere decodificata.
• Hai raggiunto la scadenza. Se il lavoro è ancora in esecuzione vicino al timeout, alza il limite invece di reinviare ripetutamente, cosa che aumenta solo carico e costi.
• Il link di output è scaduto. Se l'attività è riuscita ma il download restituisce 404, è passato troppo tempo tra completamento e recupero. Scarica subito dopo il successo.

Un'abitudine diagnostica rapida: nelle prime integrazioni, registra verbatim il corpo della risposta di invio. Ti dice l'id dell'attività, lo stato iniziale e i nomi esatti dei campi restituiti da questo endpoint, eliminando le congetture da ogni fallimento successivo.