Workflow API per video da immagine: Runway, Wan 2.7, Vidu e pattern API in produzione

Hai un'immagine statica tra le mani — un render di prodotto, un key visual approvato, una character sheet — e devi farla muovere. Non generare una nuova scena approssimativamente simile, ma animare quel frame stesso. È esattamente ciò che fa il video da immagine (i2v), ed è un approccio di integrazione profondamente diverso dal "inserisci un prompt e spera che il modello disegni ciò che hai in mente". Questo articolo è la versione operativa: preparare l'immagine sorgente, controllare dove inizia e finisce il movimento, scrivere prompt che guidano l'animazione invece di ridurre il quadro, e gestire polling e callback per evitare che un rendering di diversi minuti mandi in tilt il tuo backend.

Stai ancora valutando se usare i2v invece del video da testo? Questo articolo presuppone che tu abbia già deciso e voglia usare bene i2v.

Quando è adatto il video da immagine

Il i2v va usato quando il frame iniziale non è negoziabile. Il modello non crea il soggetto dal nulla; riceve la tua immagine e vi aggiunge movimento, quindi tutto ciò che deve restare coerente con il brand o con la forma ottiene una garanzia che il video da testo non può offrire — immagini di prodotto di SKU reali, trasformazione di un key visual approvato in un loop per l'header, character sheet che mantengono la coerenza del volto, oppure effetti before→after con frame iniziale e finale fissati in cui il modello riempie la transizione. Se il soggetto è flessibile, il video da testo di solito richiede meno lavoro. Il valore centrale del i2v è proprio che l'immagine statica è fissa.

Il panorama del video da immagine nel 2026

Il settore i2v è molto competitivo e con standard elevati. Vale la pena conoscerlo come contesto, anche se il workflow richiamabile qui sotto opera su un set selezionato di modelli:

• Runway Gen-4 / Gen-4.5. Successore di Gen-3 Alpha; ha spinto la "coerenza del mondo" tra le inquadrature, il movimento basato sulla fisica e le riprese di camera deliberate. Il i2v di Gen-4.5 è ampiamente considerato la scelta migliore per un controllo creativo serrato in ambito pubblicitario o per le consegne ai clienti (Runway Research, "Introducing Runway Gen-4," 2026; riepilogo modelli ZNIX, 2026). Anche il video da immagine di Gen-4.5 è disponibile su HiAPI con ID modello runway-gen-4.5/image-to-video; vedi Guida API Runway Gen-4.5.
• Vidu Q3. Costruito attorno al condizionamento di primo e ultimo frame — frame iniziale, frame finale target, prompt di cambiamento, e riempie la parte intermedia — fino a 16 secondi a 1080p con audio (Vidu, "AI Image to Video," 2026).
• Kling 3.0. Eccelle nel generare movimenti umani complessi da immagini di riferimento statiche, con supporto nativo 4K e lip-sync (TeamDay.ai, "Best AI Video Models 2026," 2026).
• Seedance 2.0. Il modello di ByteDance (12 febbraio 2026) mantiene stabili dettagli del prodotto, loghi e testo tra i frame — esattamente ciò che serve all'i2v per l'e-commerce (opencreator.io, "AI Video Models Comparison 2026," 2026).

Il pattern tra i modelli forti è coerente: il controllo del primo frame è il requisito di base, il controllo dell'ultimo frame non è più raro, e ancorare entrambe le estremità è il metodo più affidabile per evitare che la clip vada alla deriva nell'ultimo secondo. Il workflow qui sotto è costruito proprio attorno a questo principio. Su HiAPI, i due modelli i2v che puoi richiamare sono Seedance 2.0 (ByteDance) e Wan 2.7 Video da Immagine (Alibaba).

Passo 1 — Preparare l'immagine sorgente

È il passo che si tende a saltare, per poi dare la colpa al modello. Con l'i2v, il tuo primo frame è il tetto di qualità. Prima di inviare qualsiasi cosa, servono tre cose:

• Allinea le proporzioni all'output. Se renderizzi la sorgente in 4:3 ma richiedi una clip 16:9, il modello deve ritagliare o riempire — perdi il controllo su ciò che viene effettivamente mantenuto. Decidi prima le proporzioni dell'output, poi realizza l'immagine statica con quelle proporzioni. Seedance accetta anche il formato adaptive, che adatta automaticamente le dimensioni della sorgente.
• Renderizza alla risoluzione di output desiderata. Una sorgente a 480p non diventerà una clip nitida a 1080p; ingrandire un input sfocato rende solo sfocato il movimento.
• Inquadra il soggetto in modo pulito. Un soggetto nitido e non disordinato lascia meno spazio a interpretazioni errate del modello. Sfondi caotici e bordi sfocati sono la fonte di movimenti strani.

Poi ospitala. L'API riceve l'immagine sorgente come URL (first_frame_url), non come upload di file, quindi deve essere accessibile via HTTPS — il tuo bucket di storage, CDN, object storage firmato. Un percorso localhost o un link che l'API non riesce a recuperare fa fallire il task.

Passo 2 — Inviare il task con il primo frame

Su HiAPI, ogni modello (video inclusi) gira attraverso una singola API asincrona di task. Crei un task, ricevi subito un taskId, e il rendering avviene lato server. Per trasformare un video da testo in video da immagine basta un campo: aggiungi first_frame_url. Ecco la chiamata minima, con Seedance 2.0:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0",
    "input": {
      "prompt": "Slow cinematic push-in, a soft light sweep travels across the surface, the subject holds steady and in focus",
      "first_frame_url": "https://cdn.your-domain.com/assets/product-front.jpg",
      "aspect_ratio": "16:9",
      "duration": 5,
      "resolution": "720p",
      "generate_audio": false
    }
  }'

Questa è la richiesta completa di video da immagine. I campi di input importanti:

• first_frame_url — l'immagine statica da animare; la sua presenza è il punto chiave dell'i2v.
• aspect_ratio — deve corrispondere all'immagine sorgente (o usare adaptive).
• duration — secondi di output; più è lungo, più costa e più margine ha il movimento per andare alla deriva.
• resolution — 480p / 720p / 1080p; la principale leva di costo.
• generate_audio — disattivalo per loop silenziosi e immagini di prodotto.

La struttura completa di richiesta e risposta è nella documentazione. Wan 2.7 Video da Immagine segue lo stesso flusso crea-poll-scarica, ma i suoi input sono diversi — trasporta il frame sorgente nell'array media e produce output a 720p o 1080p — quindi consulta la documentazione per la sua struttura esatta invece di riutilizzare direttamente il body di Seedance.

Passo 3 — Aggiungere l'ultimo frame quando il finale conta

Il controllo del primo frame stabilisce dove inizia la clip e lascia al modello decidere come finisce — ed è qui che la deriva si insinua silenziosamente, perché il modello improvvisa la seconda metà. Se la continuità fino all'ultimo frame è importante, fissa anche quello:

{
  "model": "seedance-2-0",
  "input": {
    "prompt": "The product rotates a quarter turn and settles, light resolving to a clean studio key",
    "first_frame_url": "https://cdn.your-domain.com/assets/product-front.jpg",
    "last_frame_url": "https://cdn.your-domain.com/assets/product-three-quarter.jpg",
    "aspect_ratio": "16:9",
    "duration": 5,
    "resolution": "720p"
  }
}

Ora entrambe le estremità sono fissate e il modello riempie solo il movimento tra di esse. È il pattern di riferimento per reveal di prodotto e transizioni before→after, ed è la correzione singola più efficace per il problema "la clip è ottima fino all'ultimo secondo". Mantieni i due frame sullo stesso soggetto e con la stessa composizione — se le immagini iniziale e finale sono troppo diverse, il modello deve inventare un percorso tra loro e torni a indovinare.

Passo 4 — Scrivere prompt di movimento per immagini statiche

Il prompt nell'i2v ha un ruolo diverso, e sbagliarlo spreca rendering. Nel video da testo il prompt costruisce l'intera scena. Nel video da immagine il modello vede già la scena — è nel frame che gli hai dato — quindi il compito del prompt è il cambiamento nel tempo, non il contenuto:

• Inizia con un movimento di camera. "Slow dolly-in", "gentle pan left", "push-in then hold". I modelli di movimento seguono in modo affidabile i verbi di camera; forniscine uno esplicitamente.
• Descrivi come si muove il soggetto, non cosa è. "Steam begins to rise", "the fabric sways", "the screen wakes and glows". Stai coreografando l'animazione, non elencando di nuovo gli oggetti.
• Non ridurre di nuovo il quadro. Ripetere ciò che è ovvio nell'immagine sorgente va contro il modello e può spingerlo a rigenerare invece che ad animare.
• Mantieni il movimento plausibile per la durata. Una clip di 5 secondi non può contenere una storia di 20 secondi.

Un buon prompt i2v si legge come un'istruzione di azione per un operatore di camera, non come la descrizione di una scena per un pittore.

Passo 5 — Fare polling o ricevere callback

Il video consuma minuti di GPU, non millisecondi. Il rendering è progettato deliberatamente come asincrono, quindi non terrà mai aperta la connessione. Dopo aver creato il task, hai due modi per sapere quando è finito.

Polling fino allo stato terminale — adatto a script e prototipi:

curl https://api.hiapi.ai/v1/tasks/<taskId> \
  -H "Authorization: Bearer sk-<your-key>"
# data.status: queued -> handling -> archiving -> success (or fail)
# on success, read data.output[0].url and download it promptly — the URL expires

Callback per qualsiasi scenario oltre al prototipo. Invece di restare in un loop di polling, passa una callback e lascia che HiAPI ti invii lo stato terminale:

{
  "model": "seedance-2-0",
  "input": { "prompt": "...", "first_frame_url": "https://cdn.your-domain.com/assets/product-front.jpg", "aspect_ratio": "16:9", "duration": 5, "resolution": "720p" },
  "callback": { "url": "https://your-domain.com/hooks/hiapi", "when": "final" }
}

In entrambi i casi, l'URL di output ha una scadenza. Appena il task diventa success, scarica immediatamente data.output[0].url nel tuo storage — non collegarlo in hotlink nella pagina né consegnarlo a un cliente, perché scade.

Pattern di produzione collaudati

Alcune abitudini distinguono uno script dimostrativo da ciò che funziona su larga scala:

• Preferisci le callback al polling su larga scala. Un loop di polling per ogni task è uno spreco di calcolo e una pressione sui rate limit. Un endpoint di callback che scarica i risultati e aggiorna i tuoi record scala molto meglio di centinaia di poller.
• Rendi idempotente l'invio. Retry e callback at-least-once accadono. Assegna a ogni rendering un ID stabile (immagine sorgente + prompt + parametri, con hash) così i retry non producono — e fatturano — silenziosamente una clip duplicata.
• Il costo è risoluzione × durata. Il video si fattura al secondo, con tariffe che crescono con la risoluzione, quindi una clip da 10 secondi a 1080p costa molto più di una da 5 secondi a 480p. Itera a 480p, blocca prompt e movimento di camera, poi ri-renderizza solo le clip conservate alla risoluzione di consegna. Le tariffe in tempo reale sono nella pagina dei prezzi — cambiano, quindi non inserirle nel codice.
• Fai budget sulle clip utilizzabili, non sui rendering. Su tre clip ne conservi una, quindi il tuo costo reale per asset consegnabile è il triplo del prezzo indicato — è questo rapporto, non la tariffa al secondo, a determinare il tuo budget, ed è per questo che bloccare il prompt a 480p ripaga.
• Valida presto l'URL sorgente. Il primo frame che l'API non riesce a recuperare è il fallimento evitabile più comune — verifica che sia accessibile via HTTPS prima di inviare.

Domande frequenti

In cosa differisce il video da immagine dal video da testo in una richiesta? In un campo. La chiamata al task è identica per il resto; aggiungere first_frame_url (l'immagine sorgente) la trasforma da video da testo a video da immagine. Su HiAPI entrambi passano dallo stesso endpoint POST /v1/tasks.

Posso controllare sia il primo che l'ultimo frame? Sì. first_frame_url fissa il frame iniziale; aggiungendo last_frame_url fissi il frame finale, così il modello riempie solo il movimento tra i due estremi fissati. Fissare entrambe le estremità è il metodo più affidabile per controllare le transizioni ed evitare la deriva alla fine della clip.

Le API Runway Gen-3/Gen-4 supportano il video da immagine? Le serie Gen-3 e Gen-4 di Runway supportano il video da immagine ed eccellono nel controllo cinematografico — questo è il contesto più ampio. Il workflow richiamabile in questa guida opera su Seedance 2.0 e Wan 2.7 Video da Immagine, che HiAPI ospita dietro un'unica API di task. Il video da immagine di Runway Gen-4.5 gira sulla stessa API; nella Guida API Runway Gen-4.5 c'è un esempio di richiesta funzionante.

Quanto tempo richiede il rendering di un video da immagine? Minuti, non secondi — il video è calcolo reale. È per questo che l'API è asincrona: crei il task, poi fai polling o ricevi una callback, così un rendering lungo non blocca mai la tua richiesta.

Riepilogo

Il video da immagine serve quando una specifica immagine statica deve comparire sullo schermo esattamente com'è e poi mettersi in movimento. Il tetto di qualità è già deciso prima che tu scriva il primo prompt dalla risoluzione, dalle proporzioni e dalla composizione dell'immagine sorgente — quindi preparala prima e ospitala in una posizione stabile. Fissa il primo frame per controllare dove inizia la clip, aggiungi l'ultimo frame quando il finale deve essere preciso, e scrivi il prompt come indicazioni di movimento e di camera invece di ridurre ciò che il modello vede già. Poi trattalo per quello che è, un task asincrono: fai polling o, meglio, ricevi una callback; rendi idempotente l'invio; scarica prima che l'URL scada; fai budget sulle clip utilizzabili alla risoluzione di consegna.

Quando sei pronto, esegui l'immagine sorgente tramite la pagina del modello Seedance 2.0 o Wan 2.7 Video da Immagine, poi collega l'API di task qui sopra e, prima di scalare, controlla le tariffe al secondo in tempo reale nella pagina dei prezzi. (Cerchi prima un'opzione senza chiave? Vedi l'opzione video da testo gratuita.)