Ray 3.2 image-to-video: trasforma immagini statiche in brevi clip verticali

TL;DR

• Di cosa si tratta: un flusso di lavoro ripetibile che usa ray-3.2/image-to-video sull'API asincrona di task di hiapi per trasformare immagini statiche già esistenti (ad esempio foto di prodotto o ritratti) in brevi clip verticali.
• Il fatto chiave che determina tutto: ray-3.2 i2v non ha il campo aspect_ratio né duration. La forma della clip deriva dall'immagine di input e la durata è sempre di circa 5 secondi. Per ottenere un verticale 9:16, basta inserire un'immagine statica 9:16. Qui sta tutto il trucco.
• Le novità rispetto al nostro tutorial precedente: lo schema ora accetta il campo opzionale end_image_url (ultimo frame). Se si usa la stessa immagine sia come primo che come ultimo frame, si ottiene una clip che termina dove era iniziata, esattamente ciò che serve per un loop senza interruzioni.
• Verifica: ogni clip qui sotto è stata generata per questo articolo in un unico batch fan-out. Tre clip a 540p, $0.2145 ciascuna ($0.6435 in totale), con tempi lato server tra 41 e 58 secondi per clip. Tutte e tre sono tornate come MP4 540×960, 24fps, 5.04s, senza audio.

La maggior parte dei team di contenuti brevi non è a corto di idee. Ha pile di foto di prodotto, statici pubblicitari e ritratti di creator che però non si muovono mai. L'image-to-video risolve il problema: la tua immagine resta il punto di ancoraggio e il modello aggiunge il movimento. Questa guida copre l'intero processo con Ray 3.2: preparare l'immagine statica, scrivere il prompt di movimento, gestire i batch, il trucco del loop e cosa correggere in montaggio.

Image-to-video o text-to-video: quale ti serve?

Ray 3.2 su hiapi ha due endpoint separati, adatti a compiti diversi nel mondo dei video brevi:

• Image-to-video (questa pagina): hai già l'immagine. Il modello deve preservare il tuo prodotto, il tuo modello e la tua luce, animandoli soltanto. Adatto a showcase di prodotto, cataloghi per Reels, statici di creator e in generale a ogni clip in cui la fedeltà al brand conta più della novità.
• Text-to-video: hai l'idea ma non il materiale. Il modello compone l'intera inquadratura. Se è il tuo caso, il nostro flusso di lavoro Ray 3.2 text-to-video per video brevi spiega come generare concetti in batch usando solo i prompt.

I due flussi sono davvero diversi. Nel text-to-video scegli il formato verticale passando aspect_ratio: "9:16". Nell'image-to-video quel campo non esiste, quindi la composizione si decide prima della chiamata API, quando prepari l'immagine statica.

La richiesta: tre campi obbligatori o di uso comune, uno nuovo opzionale

Abbiamo verificato campo per campo lo schema contro l'API live il 2026-11-01. È chiuso, quindi le chiavi sconosciute restituiscono un 400:

Campo	Obbligatorio	Valori	Note
prompt	Sì	Testo	Descrive il movimento, non la scena. La scena è già nella tua immagine
image_url	Sì	URL pubblico	Primo frame. Determina l'aspect ratio dell'output
resolution	No	540p, 720p, 1080p	L'unica cosa per cui paghi (vedi sotto)
end_image_url	No	URL pubblico	Ultimo frame opzionale. Aggiunto dopo la stesura della nostra guida pratica

duration e aspect_ratio vengono ancora rifiutati direttamente (additional properties 'duration' not allowed). Anche altri nomi plausibili per l'ultimo frame, come last_frame_url, tail_image_url o end_frame_url, vengono rifiutati allo stesso modo. Il campo è end_image_url, nient'altro.

Una singola clip verticale:

curl -s https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ray-3.2/image-to-video",
    "input": {
      "prompt": "Slow cinematic push-in toward the serum bottle, a single water droplet slides down the amber glass...",
      "image_url": "https://your-cdn.example.com/serum-9x16.jpg",
      "resolution": "540p"
    }
  }'

Otterrai data.taskId. Interroga GET /v1/tasks/{taskId} finché data.status non è success (o fail), poi scarica subito output[0].url, perché è un link temporaneo con expireAt. La guida pratica contiene lo script Python completo per invio, polling e download e i payload di errore, mentre la guida rapida copre le basi su chiavi e API dei task.

Prezzi: la risoluzione è l'unica leva

Prezzi live di ray-3.2/image-to-video (dal listino hiapi al momento della stesura; ricontrolla sempre lì):

Risoluzione	Prezzo per clip
540p	$0.2145
720p	$0.429
1080p	$1.7145

La durata della clip è fissa e l'aspect ratio deriva dalla tua immagine, quindi non paghi mai un sovrapprezzo per il verticale e non esiste un'opzione "clip più lunga" che ti faccia salire di livello da solo. Una clip a 1080p costa quanto otto clip a 540p. Il modello per i video brevi è quindi lo stesso di qualsiasi modello video a prezzo per clip: testa il movimento a 540p, poi renderizza di nuovo a 720p o 1080p solo il prompt + immagine statica vincenti, per la versione da pubblicare. Per il quadro completo dei costi Ray 3.2 sui due endpoint, vedi il dettaglio dei prezzi delle API Ray 3.2.

Passo 1: prepara un'immagine statica 9:16 (è qui che nasce il verticale)

Il modello non può ricomporre la tua inquadratura, quindi l'immagine statica deve essere corretta prima dell'invio:

• Rendila 9:16. Abbiamo usato immagini statiche 720×1280. A 540p tornano come 540×960, verticale nativo, senza bisogno di ritagliare dopo. Un'immagine di prodotto orizzontale ti darà una clip orizzontale, quindi ritagliala o estendila a 9:16 prima.
• Lascia margine per il movimento. Il movimento di camera spinge dentro l'inquadratura. La nostra immagine statica del siero aveva molto sfondo vuoto sopra la boccetta, e il push-in ha sfruttato quello spazio senza tagliare il tappo.
• Metti l'aggancio nell'immagine stessa. Il primo frame della clip è la tua immagine, quindi qualsiasi cosa che fermi lo scroll (prodotto, volto, luce) deve essere già nello statico.

Entrambe le immagini statiche di questo articolo sono state generate con gpt-image-2 come immagini native 9:16. Nell'uso reale ci metterai le tue foto di prodotto o i tuoi ritratti:

Passo 2: descrivi il movimento, non la scena

L'immagine dice già cosa c'è nell'inquadratura. Al prompt basta dire come si muove. Tre cose che hanno funzionato in questo batch:

1. Specifica un movimento di camera (push-in, deriva delicata, camera fissa) e indica cosa deve restare immobile.
2. Dai al soggetto uno o due battiti fisici, come una goccia che scivola, una luce che spazza o i capelli mossi dal vento. È questo che fa sembrare vivo un clip da 5 secondi invece di un pan alla Ken Burns.
3. Scegli un movimento adatto al tipo di materiale. I prodotti richiedono variazioni di luce lente e controllate. Le persone possono sopportare movimenti più ampi e caldi.

Clip di prodotto (la clip di copertina qui sopra). Prompt:

Slow cinematic push-in toward the serum bottle, a single water droplet slides
down the amber glass, a band of warm light sweeps across the bottle from left
to right and makes the gold cap glint, the background stays dark and still,
premium skincare commercial

Il push-in e la passata di luce hanno funzionato bene, e la forma della boccetta e il tappo dorato sono stati preservati. Un avvertimento onesto: quando la luce spazza, il bulbo di gomma nera del contagocce diventa di un colore più chiaro, quasi metallico. Per uno SKU reale, questo è il tipo di deriva nei dettagli che un team di brand farebbe notare. Controlla i dettagli del prodotto frame per frame prima di pubblicare; se un componente continua a derivare, prova un'istruzione di passata di luce più debole o mantieni il movimento sullo sfondo.

Ritratto / statico di creator. Prompt:

The wind lifts her curls, she turns her head slightly toward the camera and
her half-smile widens into a warm smile, the golden-hour backlight flickers
through her hair, the camera holds steady with a very gentle drift, natural
lifestyle feel

Il volto, il maglione e la luce dell'ora d'oro sono rimasti coerenti, e la rotazione della testa e il sorriso sono arrivati. Però il movimento di camera di Ray 3.2 è più ampio di quanto suggerisca "deriva molto delicata": all'ultimo frame si era spostata dall'altra parte dell'inquadratura e anche l'orizzonte dietro di lei si era spostato. Per le inquadrature con persone, aspettati che il modello interpreti in modo ampio il tuo prompt di movimento. Se ti serve un'inquadratura ferma, dichiaralo esplicitamente, come abbiamo fatto nel prompt del loop qui sotto.

Passo 3: il trucco del loop con end_image_url

I loop funzionano molto bene nei feed dei video brevi. Una clip che ricomincia senza interruzioni viene riprodotta più volte, e può anche fare da sfondo per sottotitoli o etichette di prodotto. L'end_image_url opzionale di Ray 3.2 rende tutto semplice: usa la stessa immagine statica sia come primo che come ultimo frame, e il modello deve tornare al punto di partenza.

{
  "model": "ray-3.2/image-to-video",
  "input": {
    "prompt": "Seamless loop: the warm light slowly brightens and dims across the serum bottle, water droplets glisten, a faint wisp of mist drifts past the stone and fades out, the camera stays locked off, the bottle does not move",
    "image_url": "https://your-cdn.example.com/serum-9x16.jpg",
    "end_image_url": "https://your-cdn.example.com/serum-9x16.jpg",
    "resolution": "540p"
  }
}

Abbiamo misurato, non valutato a occhio. Abbiamo estratto il primo e l'ultimo frame di ogni clip e li abbiamo confrontati con SSIM (1.0 significa identici):

Clip	end_image_url	SSIM primo frame vs ultimo frame
Loop (stessa statica come ultimo frame)	Sì	0.958
Push-in prodotto	No	0.654
Ritratto	No	0.410

Con l'ultimo frame fissato, la clip finisce quasi esattamente dove era iniziata, abbastanza vicino da permettere una semplice ripetizione nell'editor o nella riproduzione automatica della piattaforma senza salti evidenti. Senza il frame fissato, la clip finisce in una posizione nuova, il che va bene per un taglio ma non per un loop. Due cose da tenere a mente:

• Mantieni periodico il movimento del loop. Luce che si accende e si spegne, nebbia che entra ed esce, camera fissa: tutto va bene. Un push-in non può "tornare indietro" in modo convincente in cinque secondi.
• Abbiamo testato solo loop con la stessa immagine. Passare un ultimo frame diverso (ad esempio, primo frame con la scatola chiusa e ultimo frame con la scatola aperta) è esattamente lo scopo del campo, ma non abbiamo verificato quei risultati qui, quindi testali prima di costruirci sopra una campagna.

Passo 4: batch: prima fan out, poi raccogli

L'API dei task è asincrona, quindi non renderizzare una clip alla volta. Invia prima tutte le coppie immagine statica + prompt, salva su disco ogni taskId nel momento in cui lo ricevi, e poi interroga:

for each (still, prompt) pair:
    taskId = POST /v1/tasks  (model=ray-3.2/image-to-video, input={...})
    persist taskId immediately        # the task is billed at submit

for each saved taskId:
    poll GET /v1/tasks/{taskId} until status in ("success", "fail")
    on success: download output[0].url now (it expires)

Il nostro batch di tre clip è stato inviato in sequenza, con tempi lato server di 44 secondi (prodotto), 41 secondi (loop) e 58 secondi (ritratto). Dato che giravano in parallelo, il batch intero ha impiegato circa quanto la clip più lenta, e con l'intervallo di polling di 8 secondi il tempo reale è stato poco più di un minuto. Se il polling fallisce per un problema di rete, riprova con lo stesso id. Un nuovo invio crea e fattura una seconda clip.

Passo 5: rifinitura in editor

L'API ti dà materiale grezzo, non un post finito:

• Nessun audio. Tutte e tre le clip hanno solo un flusso video H.264, senza traccia audio. Aggiungi in editor suoni di tendenza, voce fuori campo o sottotitoli.
• 5 secondi sono un battito. Impila tre o quattro clip (ad esempio push-in prodotto → loop come sfondo per sottotitoli → reazione del creator), montale in una versione da 15–20 secondi e taglia sui battiti.
• Ingrandisci solo i vincenti. Esegui di nuovo a 720p o 1080p l'immagine statica + prompt scelti, per l'esportazione finale, invece di renderizzare l'intero batch ad alta risoluzione.

FAQ

Come si ottiene una clip verticale 9:16 da ray-3.2 image-to-video? Fornisci un'immagine di input 9:16. Non c'è un parametro aspect_ratio, e l'output segue la forma dell'input. Un'immagine statica 720×1280 a 540p torna come clip 540×960.

Posso ottenere una clip più lunga di 5 secondi? Con questo endpoint no. Non esiste il campo duration, e inviarlo restituisce un 400. Ogni clip che abbiamo generato dura 5.04 secondi (121 frame a 24fps). Impila le clip in montaggio per ottenere versioni più lunghe.

Ray 3.2 i2v supporta l'ultimo frame? Sì. Il campo opzionale end_image_url imposta il frame finale. Passando la stessa immagine come image_url si ottiene una clip riproducibile in loop (nei nostri test, SSIM primo frame vs ultimo frame 0.958).

Genera audio? No, l'MP4 di output è muto.

Mantiene esattamente il mio prodotto? Nei nostri test forma, colore e composizione generale sono stati preservati bene, ma piccoli componenti possono derivare sotto movimenti di luce intensa (il colore del bulbo del nostro contagocce è cambiato). Controlla i dettagli del prodotto prima di pubblicare.

Quanto costa un batch? Si paga solo per risoluzione e numero di clip: $0.2145 per 540p, $0.429 per 720p, $1.7145 per 1080p. Il nostro batch di test con tre clip è costato $0.6435.

Inizia a dare movimento alle tue immagini statiche

Ray 3.2 image-to-video è ora disponibile sull'API asincrona dei task. Apri la pagina del modello ray-3.2/image-to-video per vedere i parametri e i prezzi attuali, poi prendi tre immagini statiche 9:16 che hai già e falle girare a 540p. Otterrai un batch di test molto sotto il dollaro. Stai confrontando modelli per lo stesso compito? Guarda come Kling 3.0 gestisce i video brevi con image-to-video.