API Kling 4.0 da immagine a video: riferimento per le richieste e un'esecuzione reale

Kling 4.0 da immagine a video trasforma un'immagine del primo fotogramma in una clip di 3–30 secondi con audio sincronizzato. Questa guida fornisce esempi di richiesta pronti all'uso su hiapi, i campi che l'API accetta e rifiuta, e i risultati di un'esecuzione reale. Devi ottenere una chiave API dalla console hiapi; l'ID del modello è kling-4.0/image-to-video, e la pagina del modello elenca le specifiche attuali.

Se stai ancora usando Kling 3.0, la panoramica dell'API Kling 4.0 è stata scritta prima del rilascio e descrive il suo annuncio; questa pagina è invece il riferimento attualmente valido.

Richiesta minima (curl)

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": {
      "prompt": "Lei gira leggermente la testa verso la fotocamera, i capelli ondeggiano nel vento, la fotocamera avanza lentamente, suono delle onde in sottofondo",
      "image_urls": ["https://example.com/first-frame.jpg"],
      "duration": 3,
      "resolution": "720p"
    }
  }'

La risposta restituisce immediatamente un ID attività:

{"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

Esegui il polling di GET /v1/tasks/<taskId> finché data.status non diventa success, poi leggi data.output[0].url.

Python: invio e polling

import os, time, requests

BASE = "https://api.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

def kling4_i2v(image_url, prompt, duration=5, resolution="720p"):
    r = requests.post(f"{BASE}/v1/tasks", headers=HEADERS, json={
        "model": "kling-4.0/image-to-video",
        "input": {
            "prompt": prompt,
            "image_urls": [image_url],   # esattamente un'immagine del primo fotogramma
            "duration": duration,        # intero, 3-30
            "resolution": resolution,    # "720p" o "1080p"
        },
    })
    body = r.json()
    if body["code"] != 200:
        raise RuntimeError(body["message"])
    task_id = body["data"]["taskId"]

    while True:
        d = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d)
        time.sleep(10)

Scarica subito il file MP4 restituito. L'URL di output ha un timestamp expireAt (nella nostra esecuzione circa sette giorni dopo) ed è ospitato su un dominio temporaneo, quindi copialo nel tuo storage invece di usare hotlink diretto.

Campi accettati dall'API

Abbiamo testato l'endpoint con valori volutamente non validi (questi restituiscono HTTP 400 INVALID_REQUEST e non creano alcuna attività):

Campo	Regola osservata
image_urls	array obbligatorio, esattamente un elemento (due → maxItems: got 2, want 1)
duration	intero, minimo 3, massimo 30. Le stringhe come "5" vengono rifiutate (got string, want integer)
resolution	720p o 1080p
aspect_ratio	opzionale: 16:9, 9:16, 1:1, 21:9. La pagina del modello afferma che, se omesso, la composizione segue l'immagine di origine
prompt	descrizione del movimento; nelle nostre prove di validazione abbiamo inviato solo richieste senza questo campo, quindi consideralo un campo consigliato

Quando si migra il codice da altri modelli video, ci sono due cose che facilmente causano errori:

• Il campo è image_urls, non image_url. Inviare image_url fa comparire sia "campo obbligatorio mancante image_urls" sia "proprietà aggiuntiva non consentita image_url".
• Non esiste un interruttore audio. audio, generate_audio e sound vengono tutti rifiutati come proprietà aggiuntive. L'audio viene sempre generato insieme al video; guidalo nel prompt (l'esempio sopra richiede il suono delle onde in sottofondo).

I campi sconosciuti vengono rifiutati anziché ignorati, quindi gli errori di battitura emergono come 400 anziché come impostazioni ignorate silenziosamente.

Note per la produzione

• Preferisci i callback al polling. La generazione delle clip richiede diversi minuti, quindi passa un callback (con url e when: "final") al momento della creazione dell'attività e gestisci il risultato nel webhook; usa il polling solo come fallback.
• Verifica prima di pagare. Poiché gli input non validi restituiscono 400 e non creano attività, controlla prima nel tuo codice durata e risoluzione; le richieste errate non costano nulla, ma quelle corrette vengono fatturate per ogni secondo richiesto.
• La fatturazione è al secondo e dipende dalla risoluzione. Clip più lunghe e 1080p costano di più; consulta la pagina dei prezzi per le tariffe attuali invece di affidarti ai numeri dell'articolo.
• Salva l'ID attività. Se il polling fallisce per un errore di rete temporaneo, esegui di nuovo il polling dello stesso ID invece di reinviare, altrimenti verrà creata e fatturata una seconda clip.

Esecuzione misurata

Abbiamo inviato la richiesta sopra: un'immagine verticale del primo fotogramma, duration: 3, resolution: "720p", senza aspect_ratio.

• Sequenza di stati osservata con polling ogni circa 10 secondi: handling → archiving → success.
• Tempo reale totale: circa 274 secondi per una clip di 3 secondi. handling occupa circa 255 secondi; pianifica in minuti, non in secondi, e progetta intorno ai callback.
• File di output (verificato con ffprobe): video H.264, 1280×720, 3,04 secondi, più una traccia audio AAC della stessa durata. Quindi l'audio è realmente incorporato nell'MP4 e la composizione segue l'immagine di origine 16:9.

Non abbiamo testato: 1080p, durate superiori a 3 secondi e valori di aspect_ratio diversi da quello predefinito. Questi limiti derivano dai messaggi di validazione dell'API e dalla pagina del modello, non dagli output generati.

Pagine correlate

• Pagina del modello Kling 4.0 da immagine a video
• Pagina del modello Kling 4.0 da testo a video, per quando non hai un'immagine di origine
• Pagina del modello Kling 3.0 da immagine a video
• Come usare Kling 3.0 Turbo da immagine a video
• Prezzi hiapi
• Documentazione hiapi

Domande frequenti

Posso disattivare l'audio in Kling 4.0 da immagine a video?

Non tramite un campo della richiesta. audio, generate_audio e sound vengono tutti rifiutati dal validatore. Descrivi nel prompt il suono che vuoi (o che non vuoi).

Quante immagini di input posso inviare?

Una. image_urls deve contenere esattamente un'immagine del primo fotogramma.

Quanto tempo richiede una richiesta?

La nostra clip di 3 secondi in 720p ha richiesto circa 274 secondi end-to-end. Per i carichi di produzione usa i callback.

Qual è la clip più lunga possibile?

L'API accetta duration fino a 30 (secondi interi) e rifiuta valori superiori; noi stessi abbiamo generato solo clip di 3 secondi.