Veo 3.1 da immagine a video: trasforma un fotogramma fermo in un breve annuncio video tramite API

La creazione di video brevi ha un problema di aritmetica produttiva spietato: TikTok e Reels vincono per volume di pubblicazione, ma un singolo video di prodotto curato può costare un intero pomeriggio tra riprese, montaggio e sound design. Il modello di generazione video da immagine di Google Veo 3.1 (veo-3.1/image-to-video) comprime questa pipeline in due chiamate API: un fotogramma fermo economico, un'attività video, e restituisce un breve video verticale già con audio nativo mixato.

Ecco l'output completo generato da questa pipeline per l'articolo. Un'immagine di origine da $0,03, una chiamata API, 115 secondi di attesa:

Attiva l'audio: il tonfo sordo dell'atterraggio, il basso impulso ambientale e il sibilo della nebbia sono tutti generati dal modello. Qui nulla è passato per montaggio manuale, color grading o sound design. In questa guida costruiremo questo breve video end-to-end tramite l'API delle attività di hiapi, poi estenderemo lo stesso flusso di lavoro in una pipeline batch per produrre varianti in formato breve.

Perché la generazione da immagine è lo strumento giusto per il formato breve

La generazione da testo è ottima per esplorare, ma i contenuti commerciali in formato breve di solito partono da materiale che già controlli: foto di prodotto, immagini di packaging, fotogrammi di poster. La generazione da immagine aggiunge movimento mantenendo questa identità visiva invariata. Per il formato TikTok/Reels, tre caratteristiche di veo-3.1/image-to-video sono particolarmente importanti:

1. L'output segue il formato dell'immagine di input. Non esiste un parametro aspect_ratio: il modello eredita la composizione dall'immagine che fornisci. Dagli un fotogramma fermo verticale 9:16 e ottieni un video verticale 9:16. Entrambi i video brevi di questo articolo sono stati emessi esattamente in 1080×1920 e 720×1280, perché i fotogrammi di origine sono 9:16. Le tue decisioni di composizione si prendono una sola volta, in fase di immagine.
2. Audio nativo. Ogni video breve include una traccia AAC a 48 kHz generata dal tuo prompt: foley, suoni ambientali e texture musicali. Per il formato breve, l'autoplay silenzioso converte meno dei contenuti con audio, e questo elimina un intero passaggio di montaggio.
3. Risoluzioni adatte alla piattaforma. 720p per le bozze, 1080p per il verticale di qualità da feed, 4k quando il video breve deve fungere anche da master per altri posizionamenti.

Struttura dei parametri di input (verificata sull'API live)

Prima di scrivere questa guida abbiamo sondato l'endpoint live. La struttura dei parametri è rigorosa: i campi sconosciuti vengono rifiutati con un 400, quindi non tirare a indovinare:

Campo	Obbligatorio	Tipo	Valori
prompt	Consigliato	string	Indicazioni su movimento, camera e audio
image_url	Sì	string	Un URL immagine accessibile pubblicamente
resolution	Sì	string	720p, 1080p, 4k
duration	Sì	integer	4, 6 o 8 (secondi)

Due problemi da conoscere in anticipo: image_url è singolare — questo è un modello a riferimento singolo, non un mixer multi-immagine — e l'URL deve essere recuperabile pubblicamente (ospitato sul tuo CDN o object storage; i link firmati su localhost non funzionano).

Passo 1 — Generare il fotogramma fermo di origine

Qualsiasi immagine 9:16 va bene, incluse vere foto di prodotto. Abbiamo generato la nostra immagine di origine con gpt-image-2 a $0,03, mantenendo l'intera pipeline all'interno di un'unica API:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2/text-to-image",
    "input": {
      "prompt": "Vertical product hero shot of a chunky retro basketball sneaker in wolf-gray suede with volt yellow laces, floating at a slight tilt above a wet concrete pedestal, dramatic teal-to-amber gradient backdrop, fine mist and dust particles suspended in hard rim light, ultra-sharp commercial product photography, no text, no logos",
      "aspect_ratio": "9:16",
      "resolution": "1K"
    }
  }'

Le regole di composizione per un buon fotogramma di origine i2v sono le stesse che daresti a un fotografo di still life, più una: lascia margine di movimento. Le nostre sneaker sono sospese sopra il piedistallo proprio per dare al modello video un'azione fisica evidente da compiere: far atterrare la scarpa sulla pietra. Un soggetto congelato a metà azione offre a Veo una storia da completare; un'immagine di packaging statica e centrata non gli offre nulla, e otterrai solo ripieni di ripresa alla deriva.

Passo 2 — Inviare l'attività video

Stesso endpoint /v1/tasks, modello diverso. Il prompt dovrebbe guidare tre canali contemporaneamente: movimento del soggetto, camera e audio.

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1/image-to-video",
    "input": {
      "prompt": "The sneaker slowly rotates about 90 degrees as the camera pushes in from a low angle. Dust particles drift through the rim light. The shoe settles onto the wet stone pedestal with a deep, satisfying thud, sending a soft ring of mist rolling off the edges. A warm light sweep travels across the suede texture. Subtle bass-heavy electronic pulse builds in the background with a low whoosh on the landing. Cinematic product commercial, smooth stabilized motion, no text overlays.",
      "image_url": "https://your-cdn.example.com/stills/sneaker-916.jpg",
      "resolution": "1080p",
      "duration": 6
    }
  }'

La risposta restituisce immediatamente un ID attività:

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

Nota che il prompt è scritto nell'ordine di riproduzione del video breve: rotazione → avvicinamento → atterraggio → passaggio di luce, con i suggerimenti audio attaccati ai momenti a cui appartengono (il "tonfo sordo" all'atterraggio e il pulsare sottostante). Veo segue l'ordine degli eventi nel prompt in modo molto letterale: è proprio questo che lo rende scriptabile.

Passo 3 — Eseguire il polling e scaricare

Le attività video sono asincrone. Esegui il polling dell'attività finché status passa a success, poi scarica l'output immediatamente: tale URL è un link temporaneo con timestamp expireAt, non un archivio permanente:

import os, time, requests

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

def wait_and_download(task_id: str, out_path: str, timeout_s: int = 900):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        task = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        if task["status"] == "success":
            url = task["output"][0]["url"]          # temp link — expires!
            clip = requests.get(url, timeout=120).content
            with open(out_path, "wb") as f:
                f.write(clip)                        # persist to your own storage now
            return out_path
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(10)
    raise TimeoutError(task_id)

Nella nostra esecuzione, il video breve da 6 secondi a 1080p ha impiegato 115 secondi dall'invio al completamento. È abbastanza veloce da inserirlo in una pipeline di contenuti senza dover aggiungere una coda in testa.

Bozza economica, rifinitura finale: il flusso di lavoro a due livelli

Veo 3.1 ha una modalità veloce — veo-3.1-fast/image-to-video — con una struttura di input identica e un prezzo al secondo inferiore alla metà. Questo abilita un flusso di lavoro mutuato dalla fotografia: scatta una Polaroid prima di bruciare la pellicola. Itera il tuo prompt di movimento sulla modalità veloce a 720p, e ri-renderizza il prompt vincente solo sulla modalità standard.

Ecco la bozza in modalità veloce con lo stesso identico prompt e fotogramma di origine (6 secondi, 720p, $1,50, completata in 58 secondi):

La bozza cattura gli stessi battiti — rotazione, atterraggio, nebbia — ma i dettagli delle texture sono visibilmente più semplici e il mix audio è più piatto. Per l'iterazione del prompt, questo è tutto ciò che ti serve: stai verificando la regia, non la rifinitura finale. Entrambi i video brevi di questo articolo sono stati ottenuti al primo colpo; la modalità veloce è come ti assicuri che il ciak in modalità standard sia l'unico che paghi.

Scalare alla produzione in batch

La strategia per il formato breve è un gioco di volume: vuoi 5–10 varianti per prodotto per testare gli hook. Poiché tutto passa da un unico endpoint asincrono, l'elaborazione batch è solo un ciclo: invia prima tutte le attività, poi raccoglile.

STILLS = [
    ("sneaker-916.jpg",  "rotates and lands on the pedestal with a deep thud..."),
    ("bottle-916.jpg",   "condensation beads race down the glass as camera orbits..."),
    ("headphones-916.jpg","earcup unfolds in slow motion, soft click, synth swell..."),
]

task_ids = []
for still, motion in STILLS:
    r = requests.post(API, headers=HEADERS, json={
        "model": "veo-3.1-fast/image-to-video",   # draft tier for the first sweep
        "input": {
            "prompt": motion,
            "image_url": f"https://your-cdn.example.com/stills/{still}",
            "resolution": "720p",
            "duration": 6,
        },
    }, timeout=60).json()
    task_ids.append(r["data"]["taskId"])

for i, tid in enumerate(task_ids):
    wait_and_download(tid, f"draft-{i}.mp4")

Inviare prima e raccogliere dopo è importante: i video brevi vengono generati in parallelo lato piattaforma, quindi dieci bozze richiedono circa il tempo di una sola bozza, non dieci volte tanto.

Quanto costa

Secondo i prezzi di hiapi, entrambi i livelli sono fatturati sui secondi di video in output:

Modello	Prezzo	Video breve da 4 s	Video breve da 6 s	Video breve da 8 s
veo-3.1/image-to-video	$0,57/s	$2,28	$3,42	$4,56
veo-3.1-fast/image-to-video	$0,25/s	$1,00	$1,50	$2,00

Tutto ciò che è mostrato in questo articolo — un fotogramma fermo di origine, un'immagine di copertina, una bozza veloce e una versione finale 1080p — è costato $4,98 in API. Il flusso di lavoro con tre bozze veloci più una finale standard costa circa $8 per verticale finito, un ordine di grandezza completamente diverso da una giornata di riprese.

Domande frequenti

Come si controlla il rapporto d'aspetto? Non si controlla: l'output eredita il formato dell'immagine di input. Per TikTok/Reels, genera o ritaglia il fotogramma di origine in 9:16 prima dell'invio. Il nostro fotogramma 9:16 ha prodotto esattamente un output 1080×1920.

L'audio è davvero generato? Sì. Entrambi i video brevi qui sopra includono una traccia AAC a 48 kHz generata dal modello: foley (il tonfo dell'atterraggio), suoni ambientali e texture musicali, tutti guidati dal prompt. Nel prompt descrivi i suoni nel momento in cui devono avvenire.

Quanto tempo richiede la generazione? Nelle nostre esecuzioni misurate: 58 secondi per un video breve da 6 s/720p in modalità veloce, 115 secondi per un video breve da 6 s/1080p in modalità standard. Preventiva qualche minuto per video breve; per l'elaborazione batch usa lo schema invia-tutto-poi-raccogli.

Si possono usare vere foto di prodotto invece di fotogrammi generati? Certamente: è il caso d'uso principale. L'immagine deve solo essere recuperabile pubblicamente via URL. Mantieni il soggetto nitido, lascia margine di movimento e descrivi nel prompt il movimento che desideri.

Quando vale la pena pagare per il 4k? Quando il verticale deve fungere anche da asset master: ritaglia la sorgente 4k per annunci nel feed, hero image web e unità a pagamento. Per la sola consegna nel feed, 1080p è la risoluzione a cui la piattaforma transcodifica comunque.

Pubblica il tuo primo video breve

L'intera pipeline è due POST più un polling: entra un fotogramma fermo, esce un annuncio verticale con audio in circa due minuti. Ottieni la tua API key, punta gli snippet qui sopra sulla tua migliore foto di prodotto, esegui una bozza in modalità veloce a 720p: sei secondi a $1,50, il provino più economico che tu possa commissionare. Parametri completi ed esempi live sono nella pagina del modello veo-3.1/image-to-video; se stai confrontando motori i2v, le nostre ricette di prompt per la generazione da immagine di Hailuo 2.3 sono ottime per un confronto affiancato.