Creare video brevi con Kling 3.0 image-to-video tramite l'API di HiAPI

I video brevi sono un formato che prima o poi ogni pipeline di contenuti deve supportare, e il modo più economico per produrli in modo affidabile su larga scala è l'image-to-video: prendi un fotogramma statico che hai già sotto controllo — una foto di prodotto, un design di personaggio, un keyframe generato — e lascia che un modello video lo animi. L'endpoint image-to-video di Kling 3.0 su HiAPI eccelle in questo, e offre una funzionalità che la maggior parte dei modelli i2v salta: puoi fornire sia il primo che l'ultimo fotogramma, così il modello anima tra i due stati invece di estrapolare semplicemente il movimento da un singolo fotogramma.

Questo tutorial costruisce un flusso di lavoro completo e scriptabile: generare il primo fotogramma, inviarlo all'API asincrona di Kling 3.0, eseguire il polling fino al completamento e scaricare una clip finita con audio sincronizzato nativo — tutto tramite normali chiamate HTTP che puoi inserire direttamente in un job batch.

Perché image-to-video invece di text-to-video

Il text-to-video ti sorprende ogni volta. L'image-to-video ti dà un punto di partenza che hai già approvato — il che conta quando quel fotogramma è una foto di prodotto, un personaggio di brand o qualsiasi cosa che deve apparire in un certo modo prima di muoversi. Il modello image-to-video di Kling 3.0 spinge questo concetto oltre con il controllo primo+ultimo fotogramma: passi un'immagine di riferimento e il modello la tratta solo come punto di partenza; ne passi due e la seconda diventa lo stato finale di destinazione, con il modello che interpola il movimento tra le due. In pratica è animazione con keyframe programmabile tramite una singola chiamata API, senza bisogno di alcun editor di timeline.

Struttura della richiesta

Kling 3.0 image-to-video gira sull'endpoint unificato per task asincroni di HiAPI — POST /v1/tasks, poi polling di GET /v1/tasks/{id} finché non è completato. Lo schema di input del modello è volutamente essenziale:

{
  "model": "kling-3.0/image-to-video",
  "input": {
    "prompt": "a lantern slowly lighting up as the camera pushes in, warm cinematic glow",
    "image_urls": ["https://static.hiapi.ai/blog/kling-3-0-image-to-video-short-form-workflow/first-frame-v2.jpg"],
    "duration": 3,
    "resolution": "720p",
    "sound": true
  }
}

Prima di costruirci sopra, ci sono alcune cose da sapere:

• image_urls accetta 1 o 2 elementi. Un'immagine significa "anima partendo da questo fotogramma". Due immagini significano "anima dalla prima verso la seconda" — è il controllo primo+ultimo fotogramma menzionato sopra. Non c'è un campo separato tail_image_url; tutto si esprime tramite la posizione nell'array.
• duration è un intero da 3 a 15 secondi. Le piattaforme di video brevi vogliono per lo più clip nell'intervallo 3–8 secondi, quindi per una singola scena di solito conviene stare sul valore basso di questo intervallo.
• resolution arriva fino a 4K, più del modello fratello kling-3.0-turbo (che si ferma a 1080p). Il costo è il prezzo da pagare — vedi il listino qui sotto — quindi 720p o 1080p coprono la maggior parte dei casi d'uso per video brevi senza pagare per una risoluzione che nessuno noterà sullo schermo di un telefono.
• sound è un booleano, e si tratta di vera generazione audio sincronizzata, non di una clip muta a cui viene aggiunta musica in un secondo momento. Attivalo quando il movimento nella tua scena produrrebbe ragionevolmente un suono (una porta che si chiude, il vento, dei passi): il risultato sarà decisamente più credibile di un render silenzioso.
• Non c'è un campo aspect_ratio — l'inquadratura dell'output corrisponde al rapporto d'aspetto dell'immagine che fornisci.

Script end-to-end

Ecco il flusso completo in Python: creare il task, eseguire il polling fino al completamento, scaricare il risultato.

import requests
import time

API_KEY = "YOUR_HIAPI_KEY"
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def submit_i2v(image_url, prompt, duration=3, resolution="720p", sound=True):
    payload = {
        "model": "kling-3.0/image-to-video",
        "input": {
            "prompt": prompt,
            "image_urls": [image_url],
            "duration": duration,
            "resolution": resolution,
            "sound": sound,
        },
    }
    resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]

def wait_for_result(task_id, poll_interval=5, timeout_s=600):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        if task["status"] == "success":
            return task["output"][0]["url"]
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

task_id = submit_i2v(
    image_url="https://static.hiapi.ai/blog/kling-3-0-image-to-video-short-form-workflow/first-frame-v2.jpg",
    prompt="a lantern slowly lighting up as the camera pushes in, warm cinematic glow",
)
video_url = wait_for_result(task_id)
print(video_url)  # temporary signed URL — download immediately, don't store it as a permanent link

Quando lo integri in una pipeline reale, c'è un dettaglio che può facilmente ingannarti: il valore output[0].url che ricevi è un link temporaneo che scade. Scarica subito i byte e spostali nel tuo storage, invece di salvare da nessuna parte l'URL di output del task come riferimento permanente.

Ecco il primo fotogramma usato in questo esempio, e la clip che Kling 3.0 genera a partire da esso con sound: true:

Una clip come quella qui sopra — 3 secondi, 720p, con audio — costa poco più di $0.40, abbastanza poco da permetterti di iterare alcune volte sul prompt prima di decidere la versione che vuoi consegnare.

Prezzi: risoluzione e audio incidono entrambi sul costo

Kling 3.0 image-to-video viene fatturato al secondo di durata dell'output, e sia la risoluzione sia l'interruttore audio influenzano la tariffa:

Risoluzione	Senza audio	Con audio
720p	$0.10/s	$0.143/s
1080p	$0.129/s	$0.193/s
4K	$0.479/s	—

Esempio di calcolo: una clip di 3 secondi, 720p, con audio costa circa $0.43. Una clip di 5 secondi, 1080p, senza audio costa $0.645; la stessa clip con audio costa $0.965. Per contenuti video brevi in cui la maggior parte delle clip finite rientra nell'intervallo 3–8 secondi, 720p o 1080p è quasi sempre la scelta giusta — il prezzo del 4K ha senso solo se devi comporre il risultato in qualcosa a valle che trae davvero beneficio dalla risoluzione extra. Prima di eseguire qualsiasi cosa su larga scala, consulta il listino attuale, perché dettagli come le tariffe al secondo meritano di essere verificati sulla pagina live piuttosto che memorizzati a memoria.

Mettere tutto in batch in un flusso di lavoro reale

Per contenuti video brevi di qualsiasi volume, non vuoi inviare un task e restare a fissarlo — vuoi lanciare un batch di task tutti insieme e raccogliere i risultati man mano che arrivano. Poiché ogni task è indipendente ed è identificato dal proprio taskId, il pattern è semplice: invia tutte le richieste image-to-video, salva gli ID dei task restituiti, poi cicla sul polling e agisci solo quando ogni task diventa success o fail. Così la tua pipeline procede alla reale capacità della piattaforma invece di serializzarsi sul singolo task più lento.

Alcune abitudini che vale la pena adottare fin da subito:

• Verifica che l'immagine di origine sia raggiungibile prima di inviare. L'API dei task accetta senza problemi un URL e poi il task fallisce più tardi se l'immagine non è recuperabile — un controllo con una richiesta HEAD in anticipo evita una generazione sprecata.
• Tratta lo stato fail come un esito normale, non come un'eccezione. A volte l'output del modello rifiuta una specifica combinazione di prompt e immagine; registra il fallimento e passa al successivo invece di interrompere l'intero batch.
• Riutilizza le clip tra le varianti quando puoi. Se stai testando più sottotitoli o colonne sonore sulla stessa animazione generata, non c'è bisogno di rigenerare il video — è puramente una fase di editing a valle.

Se è la prima volta che configuri chiavi API e autenticazione, la guida rapida di HiAPI copre le basi per ottenere una chiave e fare la tua prima chiamata autenticata, dopodiché puoi costruirci sopra l'intera pipeline di batch.

In sintesi

Il modello image-to-video di Kling 3.0 trasforma un singolo fotogramma statico — o due, se vuoi il controllo primo+ultimo fotogramma — in una clip video breve con audio sincronizzato tramite una singola chiamata HTTP, con un prezzo che scala in modo prevedibile in base a durata, risoluzione e necessità o meno dell'audio. Per le pipeline di video brevi, la combinazione di questo livello di controllo, del basso costo per clip a 720p/1080p e di un'API asincrona lineare ti permette di passare facilmente da "un'immagine statica" a "un batch di clip finite" senza toccare un editor video.