gemini-omni-1.2-flash in pratica: 3 scenari aziendali di generazione video e una checklist di implementazione

Prima di tutto, confermare il formato di input e i limiti dei parametri

Il modello pubblico attualmente integrato in HiAPI, gemini-omni-1.2-flash, genera video e offre quattro modalità: testo a video, immagine di primo frame a video, transizione primo-ultimo frame e immagine di riferimento a video. Prima di scrivere il codice, è più efficace stabilire «cosa gli daremo in pasto questa volta» piuttosto che scegliere prima lo scenario.

Le capacità attualmente non disponibili includono: editing video, continuazione video, input video o audio, parametro seed. I flussi che dipendono da queste capacità non possono essere realizzati con questo modello.

Parametri della richiesta

• prompt: unico campo obbligatorio, deve essere una stringa non vuota, massimo 20000 caratteri.
• duration: intero, valori da 3 a 15 secondi, predefinito 10 secondi.
• resolution: 360p / 720p / 1080p / 4k, predefinito 720p. 1080p e 4k sono output ingranditi; 4k potrebbe non includere la traccia audio.
• aspect_ratio: 16:9 o 9:16, predefinito 16:9.

Parametri immagine e relazioni di mutua esclusione

• image_urls: da 1 a 10 immagini di riferimento HTTP(S) pubbliche, attiva la modalità immagine di riferimento a video. Anche con una sola immagine resta la modalità riferimento, non diventa automaticamente modalità primo frame.
• first_frame_url: specifica il fotogramma iniziale, utilizzabile da solo, formando la modalità immagine di primo frame a video.
• last_frame_url: deve essere usato insieme a first_frame_url, formando la transizione primo-ultimo frame. La modalità primo-ultimo frame dura al massimo 10 secondi e la richiesta non può includere negative_prompt o system_prompt.
• image_urls è mutuamente esclusivo con first_frame_url e last_frame_url: una richiesta può scegliere solo una di queste modalità.
• Tutti i parametri immagine accettano solo URL HTTP(S) pubblicamente accessibili; Base64 non è supportato.

Aspettative da stabilire in anticipo: non è garantito che ogni modalità includa audio, sincronizzazione labiale o testo accurato, né che soggetti o marchi nel risultato corrispondano esattamente al riferimento. Tutto ciò richiede verifica manuale.

Criterio di costo: prezzo al secondo per fasce di risoluzione

Il modello fattura in base alla durata della richiesta, con prezzo unitario a fasce di risoluzione. Alle tariffe predefinite attuali:

• 360p: $0.0229/secondo
• 720p: $0.0343/secondo
• 1080p: $0.0343/secondo
• 4k: $0.0800/secondo

Il calcolo del budget è: prezzo unitario della risoluzione scelta × durata della richiesta × numero di video. A parità di specifica e durata, ogni nuova attività completata con successo di solito aggiunge al budget l'importo di un'attività, non raddoppia il budget accumulato a ogni ciclo.

La fattura effettiva e il moltiplicatore applicabile fanno riferimento al pannello prezzi del sito. La fatturazione si basa sulla durata della richiesta e non può essere dedotta dai secondi decimali nel contenitore del file di output.

Due regole operative direttamente legate al budget: ricreare un'attività perché il risultato non soddisfa aggiunge il budget di un'attività; in caso di timeout di rete, consultare prima lo stato delle attività esistenti per verificare che non sia stata creata con successo prima di decidere se crearne una nuova.

Scenario uno: bozze creative testuali

Situazione applicabile: si dispone solo di un brief testuale e occorre confrontare più direzioni visive prima di entrare nella produzione ufficiale. È l'uso più diretto del testo a video.

Come fare

• Riscrivere il brief in una descrizione visualizzabile. «Una giovane donna cammina a passo svelto per una strada cittadina all'alba, tiene in mano un caffè, ripresa a seguire» è più eseguibile di «trasmettere uno stile di vita dinamico».
• Inviare solo il prompt, senza parametri immagine, e sottomettere un'attività per ciascuna direzione.
• Usare una duration più breve per controllare il budget per singolo video; in fase di bozza non servono video lunghi. Mantenere duration e resolution identiche nello stesso lotto per facilitare il confronto.
• Registrazione strutturata: archiviare insieme prompt, duration, resolution, ID dell'attività e indirizzo del risultato, per avere un riferimento nell'iterazione successiva.

Limiti

L'output delle bozze serve ad aiutare la scelta della direzione, non è materiale da pubblicazione; dettagli dello storyboard, loghi del marchio e sottotitoli conformi di solito richiedono ancora produzione professionale successiva. Se il fotogramma finale deve corrispondere a materiale esistente, si deve passare alla modalità immagine di primo frame a video o immagine di riferimento a video.

Scenario due: animazione di un'immagine di primo frame

Situazione applicabile: si dispone già di un'immagine statica di alta qualità — immagine di prodotto, copertina, illustrazione, poster — e si desidera animare la scena mantenendo il soggetto originale.

Come fare

• Usare first_frame_url per specificare il fotogramma iniziale; il prompt descrive solo movimento e inquadratura (leggero avvicinamento, lenta orbita, flusso di luci e ombre), non il soggetto.
• Quando occorre specificare il fotogramma finale, inviare insieme first_frame_url e last_frame_url per formare la transizione primo-ultimo frame; in questo caso duration non può superare 10 secondi e la richiesta non può includere negative_prompt o system_prompt.
• Caricare prima le immagini in una posizione pubblica: sono accettati solo URL HTTP(S) pubblicamente accessibili; indirizzi di rete interna o Base64 non sono utilizzabili.
• Salvare ogni record nel database: registrare URL dell'immagine sorgente, prompt, duration, resolution e ID dell'attività, per tracciabilità e riutilizzo.

Differenza rispetto alla modalità immagine di riferimento

first_frame_url determina «da dove iniziare», image_urls fornisce riferimento di stile e contenuto. Sono mutuamente esclusivi e non possono essere usati nella stessa richiesta; inviare una sola image_urls non attiva la modalità primo frame.

Scenario tre: vincolo visivo tramite immagini di riferimento

Situazione applicabile: si necessita di un lotto di materiali che, per tonalità, texture e abitudini compositive, si avvicini a una visuale stabilita, mentre la qualità del singolo video non è il problema principale.

Come fare

• Usare image_urls per inviare da 1 a 10 immagini di riferimento pubbliche, scegliendo pochi materiali che meglio rappresentano lo stile obiettivo; evitare di mescolare immagini di riferimento con obiettivi in conflitto e verificare i risultati effettivi.
• Essere consapevoli che si tratta della modalità immagini di riferimento: anche con una sola immagine resta immagine di riferimento a video, senza primo frame o primo-ultimo frame.
• Stabilire voci di verifica fisse: colore dominante, tendenza della luce, densità dell'immagine, area del testo, confrontando orizzontalmente i nuovi lotti.
• Se si nota deriva, controllare prima i materiali di riferimento e poi regolare il prompt, invece di rieseguire alla cieca: le riesecuzioni aggiungono attività fatturate al secondo.

Limiti

Le immagini di riferimento possono vincolare lo stile, ma non garantiscono che soggetto o marchio corrispondano esattamente; serve comunque un controllo a campione manuale. Intenderle come «baseline di stile» e non come «assicurazione di stile» avvicina le aspettative alla realtà.

Checklist di implementazione

Verificare voce per voce prima di iniziare aiuta a individuare presto problemi di input e budget.

Capacità e parametri

• È chiaro quale modalità si usa questa volta: testo a video, immagine di primo frame a video, transizione primo-ultimo frame, immagine di riferimento a video?
• Il prompt è non vuoto e non supera 20000 caratteri?
• duration è un intero da 3 a 15 secondi? Nella modalità primo-ultimo frame è stato ridotto entro 10 secondi?
• resolution e aspect_ratio sono stati scelti in base all'uso (predefiniti 720p, 16:9)?
• È stata usata una sola fonte immagine: image_urls oppure first_frame_url/last_frame_url?
• Tutte le immagini sono URL HTTP(S) pubblici, senza Base64?
• Nella richiesta primo-ultimo frame sono stati rimossi negative_prompt e system_prompt?
• Si fa uso di editing video, continuazione, input video/audio o seed? Questi non sono attualmente disponibili.

Costi

• Il budget è calcolato come prezzo unitario della risoluzione scelta × durata × numero di video, non a sensazione?
• Il budget è stimato sul «numero di candidati» e non sul «numero di consegne»?
• È chiaro che, a parità di specifica e durata, ogni nuova attività completata aggiunge il budget di un'attività?
• La fattura effettiva si basa sul pannello prezzi del sito e sul moltiplicatore applicabile, non sui secondi decimali del contenitore del file?

Ingegneria

• L'invio delle attività è asincrono, senza che il lato richiesta si blocchi in attesa del video?
• L'ID dell'attività è conservato e salvato nel database, includendo prompt, duration, resolution e indirizzo del risultato?
• Esiste una macchina a stati esplicita e una chiave di idempotenza per evitare invii duplicati?
• In caso di timeout di rete si consultano prima le attività esistenti invece di ricrearle direttamente?
• La concorrenza è limitata e le attività in batch attendono in coda?

Qualità e accettazione

• I criteri di accettazione sono definiti in anticipo: integrità del soggetto, elementi del marchio, area del testo, audio conformi alle aspettative?
• È mantenuta una percentuale di controllo a campione manuale, senza ridurla in fase di volume?
• Sono impostati interruttori di sicurezza e avvisi per il budget giornaliero o per lotto?

Le quattro modalità condividono la stessa forma di interfaccia; la differenza sta solo nei parametri di input. Scegliere la modalità giusta, inserire le relazioni di mutua esclusione nella validazione dei parametri, calcolare il budget per numero di video e poi passare al batch: il percorso di implementazione è chiaro.