Controllo del primo e dell'ultimo fotogramma nei video AI: guida al movimento preciso tra modelli su hiapi

La maggior parte delle API di image-to-video riceve una sola immagine statica e genera il movimento in modo improvvisato. Solo pochi modelli ti permettono di bloccare il punto di arrivo dell'inquadratura, non solo quello di partenza: fornisci il primo e l'ultimo fotogramma, e il modello interpola il movimento tra i due. È esattamente la differenza tra "fai muovere questa foto" e "realizza con precisione questa transizione".

Il problema è che il supporto al controllo dell'ultimo fotogramma non è uniforme tra i modelli, e anche all'interno della stessa linea di prodotto di un fornitore può variare tra la fascia flagship e quella fast/turbo. Questo tutorial chiarisce esplicitamente quali modelli video di hiapi supportano solo il controllo del primo fotogramma e quali supportano primo + ultimo fotogramma, indicando per ciascuno i campi di input reali (e tutt'altro che uniformi), così non scoprirai dopo mille tentativi che il modello scelto ha ignorato silenziosamente il tuo ultimo fotogramma.

1. Cosa ti serve

Una API key di hiapi dalla console (sk-...) e due URL di immagini che il modello di destinazione possa recuperare (URL HTTPS pubblici — l'endpoint dei task non supporta il caricamento di file locali). Ogni modello qui sotto viene chiamato tramite la stessa API task unificata, quindi se la tua key funziona con uno dei modelli, funziona con tutti.

2. Esempio minimo funzionante

Tutta la generazione video di hiapi passa dallo stesso endpoint: crea il task, poi esegui il polling (oppure usa un callback — vedi Pattern di produzione) finché non raggiunge lo stato terminale.

# 1. Create the task
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0-omni/image-to-video",
    "input": {
      "prompt": "the subject turns toward the camera and smiles",
      "image_urls": [
        "https://your-cdn.example.com/first-frame.jpg",
        "https://your-cdn.example.com/last-frame.jpg"
      ],
      "resolution": "720p",
      "duration": 5,
      "sound": false
    }
  }'
# -> {"data": {"id": "task_...", "status": "pending"}}

# 2. Poll until terminal
curl -s https://api.hiapi.ai/v1/tasks/task_... \
  -H "Authorization: Bearer sk-<your-key>"
# -> {"data": {"id": "task_...", "status": "succeeded",
#              "output": [{"url": "https://...mp4", "expireAt": "..."}]}}

kling-3.0-omni/image-to-video è l'esempio più tipico di questo schema: input.image_urls accetta uno o due URL di immagini. Se ne passi uno, il modello ancora solo il primo fotogramma e improvvisa il resto; se ne passi due, il secondo URL diventa l'ultimo fotogramma vincolante — al modello viene detto dove deve terminare l'inquadratura. La durata è un intero da 3 a 15 (secondi), resolution è 720p / 1080p / 4k, e il booleano opzionale sound aggiunge audio ambientale generato. Qui non c'è alcun campo aspect_ratio — il formato di output segue i fotogrammi che fornisci.

Non tutti i modelli hanno questa struttura. seedance-2.5/image-to-video ottiene lo stesso effetto tramite due campi con nomi distinti anziché un array:

{
  "model": "seedance-2.5/image-to-video",
  "input": {
    "prompt": "smooth camera push toward the subject",
    "first_frame_url": "https://your-cdn.example.com/first-frame.jpg",
    "last_frame_url": "https://your-cdn.example.com/last-frame.jpg",
    "resolution": "720p",
    "duration": 6,
    "aspect_ratio": "adaptive",
    "generate_audio": false
  }
}

last_frame_url ha senso solo se abbinato a first_frame_url — puoi inviare solo first_frame_url per un'inquadratura con solo primo fotogramma, ma non il contrario. La durata di questo modello va da 4 a 30 s, la risoluzione arriva al massimo a 720p/1080p (nessuna opzione 4K), e aspect_ratio è impostato di default su adaptive, cioè segue il primo fotogramma anziché valori espliciti come 16:9/9:16.

I nomi dei campi variano davvero da modello a modello — image_urls rispetto a first_frame_url/last_frame_url — quindi ogni cambio di modello va trattato come un cambio di schema, non come una sostituzione diretta.

Non tutti i modelli lo supportano

veo-3.1/image-to-video accetta una singola stringa image_url e non ha alcun parametro per l'ultimo fotogramma — puoi impostare aspect_ratio (auto/16:9/9:16), resolution e un enume fisso di duration (4, 6 o 8 secondi), ma non puoi bloccare il fotogramma finale. Lo stesso vale per il gradino inferiore della linea Kling: kling-3.0-turbo/image-to-video (la versione fast/economica di kling-3.0-omni) accetta al massimo un elemento in image_urls — niente ultimo fotogramma e niente risoluzione 4K. Se ti serve il controllo dell'ultimo fotogramma, scegli la fascia flagship o un modello creato appositamente per questo (come seedance-2.5), invece di darlo per scontato in base al nome della famiglia di modelli.

3. Pattern di produzione

Su larga scala, usa i callback invece del polling. Passa un oggetto callback nello stesso corpo della richiesta, anziché eseguire il polling in un ciclo:

{
  "model": "kling-3.0-omni/image-to-video",
  "input": { "...": "..." },
  "callback": { "url": "https://your-service.example.com/hooks/hiapi", "when": "final" }
}

when: "final" scatta una sola volta, quando il task raggiunge uno qualsiasi degli stati terminali — succeeded e failed sono entrambi terminali, quindi il tuo handler webhook deve deduplicare per taskId anziché presumere che il callback significhi solo successo. Il polling con GET /v1/tasks/:id è più adatto al debug locale, a chiamate una tantum a bassa frequenza, o come rete di sicurezza di riconciliazione quando il callback non arriva mai (fluttuazioni di rete, il tuo endpoint temporaneamente offline).

Idempotenza. I retry dopo un timeout o un'interruzione della connessione possono creare task duplicati se non stai attento — registra l'id del task restituito dalla chiamata di creazione e, prima di considerare l'invio di un nuovo task, esegui un GET su quell'id come retry.

Gli URL di output scadono. Il campo expireAt presente su ogni voce di output non è decorativo — che tu abbia saputo del successo del task tramite callback o polling, scarica il video e rendilo persistente (salvalo nel tuo storage) il prima possibile.

Errori di autenticazione. Una key errata o mancante restituisce HTTP 401 e {"error": {"code": "permission_denied", ...}}. Controlla esplicitamente quello stato/codice di errore, anziché presumere che qualsiasi risposta non-2xx significhi che la generazione stessa è fallita — nella gestione degli errori è prezioso distinguere tra "la mia key è sbagliata" e "il modello ha rifiutato il mio input", perché le soluzioni sono completamente diverse.

4. Pagine correlate

• Pagina del modello Kling 3.0 Omni image-to-video — prezzi, prova online e riferimento completo dei parametri del modello usato negli esempi sopra.
• Pagina del modello Seedance 2.5 image-to-video — la variante first_frame_url/last_frame_url.
• Documentazione sull'autenticazione — come funzionano l'header Authorization: Bearer sk-... e lo scoping delle key.
• Documentazione sulla creazione dei task — riferimento completo di richiesta/risposta per /v1/tasks, incluse le opzioni di callback.
• Prezzi di hiapi — tariffe attuali per secondo e per risoluzione (la fatturazione varia per modello e risoluzione, consulta la pagina aggiornata anziché numeri fissi).

5. Domande frequenti

Quali modelli video di hiapi supportano il controllo dell'ultimo fotogramma? kling-3.0-omni/image-to-video (tramite l'array image_urls con 2 elementi) e seedance-2.5/image-to-video (tramite first_frame_url + last_frame_url) attualmente lo supportano entrambi. veo-3.1/image-to-video e kling-3.0-turbo/image-to-video non lo supportano — accettano solo un singolo fotogramma iniziale.

Posso specificare solo l'ultimo fotogramma senza fornire un prompt? Entrambi i modelli accettano ancora (e di solito si aspettano) un prompt oltre ai fotogrammi — guida il movimento tra i due fotogrammi, non solo il contenuto. Non tutti i modelli rifiutano direttamente un prompt vuoto o assente, ma descrivere esplicitamente la transizione rende il movimento più prevedibile.

I due fotogrammi devono avere lo stesso aspect ratio? Né kling-3.0-omni/image-to-video né seedance-2.5/image-to-video offrono un aspect_ratio esplicito indipendente dalle impostazioni dell'immagine — il formato di output segue i fotogrammi di input, quindi aspect ratio incoerenti tra primo e ultimo fotogramma producono risultati visibilmente sgradevoli anziché un errore. Prima di inviare, ritaglia o aggiungi bordi a entrambi i fotogrammi per portarli allo stesso rapporto.

Cosa succede se invio solo l'ultimo fotogramma senza il primo? Nessuno dei due modelli lo supporta — su seedance-2.5, last_frame_url può essere usato solo insieme a first_frame_url; l'array di kling-3.0-omni viene letto per posizione (primo elemento = primo fotogramma). Non esiste una modalità "inversa" in cui si specifica solo il fotogramma finale.

Il controllo dell'ultimo fotogramma equivale al trasferimento di movimento video-to-video? No — è una capacità diversa (su hiapi seedance-2.5/reference-to-video, che accetta un video di riferimento per guidare il movimento o il movimento di camera, anziché due immagini statiche). Il controllo primo/ultimo fotogramma interpola tra due immagini; il video-to-video di riferimento imita il pattern di movimento di una clip esistente.

Aggiungere l'ultimo fotogramma costa più che generare solo con il primo? Entrambi i modelli fatturano per secondo/per risoluzione, non per immagine di input, quindi aggiungere l'ultimo fotogramma non aumenta di per sé il costo — consulta la pagina dei prezzi per le tariffe attuali.