Tutoriale
Come generare video con gemini-omni-flash tramite l'API HiAPI
I percorsi di richiesta per text-to-video e image-to-video, la scelta del modello e una checklist di integrazione utilizzabile
In questa pagina
Perché gemini-omni-flash ha due endpoint video
Prima di scrivere la prima riga di codice, la decisione più importante è: quale dei due endpoint video ti serve davvero. Su HiAPI, gemini-omni-flash è disponibile come due modelli separati, non come un unico endpoint con un flag di modalità:
gemini-omni-flash/text-to-video— genera video solo da un prompt testuale.gemini-omni-flash/image-to-video— usa l'immagine sorgente fornita come ancoraggio visivo e genera il video guidato da un prompt testuale.
La separazione esiste perché i due task hanno input diversi, regole di validazione diverse e modalità di errore diverse. Il text-to-video richiede solo la validazione di una stringa di prompt. L'image-to-video deve anche recuperare e decodificare la tua immagine sorgente, aggiungendo un'intera classe di errori che sul percorso testuale non si presenta mai (URL irraggiungibile, formato non supportato, risorsa troppo grande).
Regola pratica: se hai già un'immagine statica — una foto prodotto, un fotogramma di storyboard, una fotografia — usa image-to-video, perché il modello parte dal tuo contenuto visivo invece di inventarlo da zero. Se hai solo un'idea e nessun materiale di riferimento, usa text-to-video.
Distingui i due ID modello nel tuo codebase fin dal primo giorno. Trattarli come un unico concetto "video" e aggiungere poi un flag if has_image è proprio ciò che porta a payload confusi e bug incomprensibili.
Cosa resta invariato
Entrambi gli endpoint condividono lo stesso schema di autenticazione, lo stesso URL di base, le stesse convenzioni generali di richiesta/risposta e lo stesso modello di fatturazione (i video sono fatturati sull'output generato, non sul numero di richieste). Sono proprio queste parti condivise a rendere praticabile un unico builder di richieste — come descritto più avanti.
Cosa cambia
Cambiano solo la struttura del payload e la validazione dell'input. Le differenze sono abbastanza ridotte da permetterti di supportare entrambi gli endpoint senza duplicare l'intera integrazione.
Prerequisiti e configurazione dell'API
Prima della prima chiamata ti servono tre cose.
1. Chiave API
Crea una chiave nel tuo account HiAPI e salvala come variabile d'ambiente, non hardcoded:
export HIAPI_API_KEY="your_key_here"
Ogni richiesta si autentica tramite un bearer token nell'header Authorization. Non c'è un passaggio di firma separato né un nonce per richiesta.
2. URL di base e convenzione di naming dei modelli
Tutte le chiamate vanno allo stesso URL di base HiAPI, e il modello è scelto dal campo model nel corpo della richiesta. Gli ID modello seguono lo schema family/variant, quindi i modelli video si scrivono gemini-omni-flash/text-to-video e gemini-omni-flash/image-to-video. Per cambiare endpoint basta cambiare una stringa, non l'host.
3. Gli strumenti per inviare richieste
curl basta per verificare la connettività, Python (con requests) basta per costruire un'integrazione reale. Nessuno dei due richiede SDK specifici del fornitore — l'API è semplice JSON su HTTPS.
Verifica della connettività
Prima di generare qualsiasi video, raggiungi un endpoint leggero (ad esempio l'elenco dei modelli disponibili) per confermare che la chiave funzioni e il percorso di rete sia corretto. Se fallisce già quel passaggio, stai debuggando credenziali o connettività, non la generazione video — capire quale dei due fa risparmiare molto tempo.
Checklist rapida:
- La chiave è esportata nella shell che eseguirà la richiesta.
- L'URL di base è annotato e usato in modo coerente ovunque (nessuna barra finale che va e viene tra gli script).
- Ogni POST imposta
Content-Type: application/json. - Hai un modo per vedere la risposta JSON grezza senza troncamenti.
Inviare una richiesta text-to-video
Inizia con la richiesta minima che abbia qualche possibilità di successo. Non riempire subito tutti i parametri opzionali — se la richiesta minima fallisce sai che il problema è strutturale; se riesce, ogni parametro aggiunto dopo è una modifica attribuibile singolarmente.
Struttura minima
Una richiesta text-to-video invia l'ID modello e il prompt:
{
"model": "gemini-omni-flash/text-to-video",
"prompt": "Carrellata lenta in avanti su una strada al neon bagnata dalla pioggia di notte, riflessi sull'asfalto bagnato, cinematografico"
}
Questo è il payload completo. Invialo, conferma di ricevere un oggetto di risposta positivo e solo allora arricchisci il contenuto.
Evolvere la richiesta passo dopo passo
Dopo che la chiamata minima riesce, aggiungi un parametro alla volta e rivalida dopo ogni aggiunta. Aggiunte tipiche sul percorso testuale:
- Dettaglio del prompt — soggetto, movimento, comportamento della camera, illuminazione e atmosfera. Prompt vaghi producono movimenti vaghi; descrivi cosa si muove e come si muove la camera.
- Durata / lunghezza dell'output — i video sono fatturati sull'output generato, quindi la lunghezza influisce direttamente sul costo. Fissala esplicitamente invece di affidarti a valori predefiniti che non hai verificato.
- Aspect ratio o risoluzione (se supportati dal modello), per allinearti al player o al formato social a valle.
Come scrivere prompt che contano davvero
La qualità del text-to-video dipende principalmente dalla specificità del prompt. Tre buone abitudini:
- Descrivi il movimento, non solo il contenuto. "Una barchetta di carta che scende galleggiando lungo un canale di scolo" dà al modello qualcosa da animare; "una barchetta di carta" no.
- Specifica la camera. Fissa, panoramica, carrellata in avanti, a mano — il linguaggio della camera elimina molta ambiguità.
- Resta su una sola scena. Descrivere più inquadrature in un singolo breve video produce spesso risultati confusi e sovrapposti.
Quando il risultato text-to-video è scarso, modifica prima il prompt e solo dopo tocca i parametri tecnici.
Inviare una richiesta image-to-video
Il percorso immagine è strutturalmente identico a quello testuale, con una sola cosa in più: l'immagine sorgente. Il metodo di test "prima il minimo" che hai imparato vale anche qui.
Struttura minima
{
"model": "gemini-omni-flash/image-to-video",
"prompt": "Leggera deriva a mano libera, il soggetto si gira leggermente verso la camera, luce morbida dalla finestra",
"image": "https://your-cdn.example.com/source-frame.jpg"
}
Qui il prompt descrive il movimento e il comportamento della camera rispetto all'immagine, non il contenuto della scena — il contenuto lo fornisce già l'immagine. Questo è l'errore concettuale più comune: si scrive una descrizione completa della scena e poi ci si chiede perché l'output ignori il fotogramma sorgente.
Come fornire l'immagine sorgente
L'immagine viene passata come riferimento e il servizio deve poterla recuperare. Due conseguenze pratiche:
- La risorsa deve essere pubblicamente accessibile al servizio, non dietro il tuo localhost, una VPN o un bucket con autenticazione. Un URL firmato con scadenza breve va bene, purché sia ancora valido al momento dell'esecuzione della richiesta.
- Formato e dimensione devono essere supportati. Attieniti ai formati web comuni e a dimensioni ragionevoli. Un TIFF da 40 MB è un debug in attesa di accadere.
Se le tue immagini stanno in uno storage privato, genera un URL firmato a breve scadenza al momento della richiesta invece di provare a rendere pubblico il bucket.
Differenze reali rispetto al percorso testuale
- Il ruolo del prompt passa da descrivere la scena a descrivere il movimento.
- La validazione include un passaggio in più di recupero risorsa, da cui un'intera nuova classe di errori (vedi la sezione sul debug).
- La composizione dell'output è vincolata dall'aspect ratio dell'immagine sorgente, il che influisce sulla pianificazione del layout a valle.
Prova l'URL dell'immagine prima nel browser. Se non si carica in modo pulito nemmeno per te, non si caricherà nemmeno per il servizio.
Chiamare l'API con curl e Python
Fai funzionare la stessa richiesta in due posti: il terminale (per iterazioni rapide e visibilità grezza) e il tuo codebase (per l'uso reale).
curl
curl -sS https://api.hiapi.ai/v1/chat/completions \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-omni-flash/text-to-video",
"prompt": "Carrellata lenta in avanti su una strada al neon bagnata dalla pioggia di notte, cinematografico"
}'
Sostituisci la stringa model con gemini-omni-flash/image-to-video e aggiungi il campo image per colpire l'altro endpoint — nient'altro da cambiare.
Usa -sS così gli errori non vengono inghiottiti silenziosamente; quando esamini la risposta, inviala a un formattatore JSON per rendere leggibili i campi annidati.
Python
import os
import requests
BASE_URL = "https://api.hiapi.ai/v1/chat/completions"
HEADERS = {
"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
"Content-Type": "application/json",
}
payload = {
"model": "gemini-omni-flash/text-to-video",
"prompt": "Carrellata lenta in avanti su una strada al neon bagnata dalla pioggia di notte, cinematografico",
}
resp = requests.post(BASE_URL, headers=HEADERS, json=payload, timeout=300)
resp.raise_for_status()
print(resp.json())
Due dettagli da copiare: leggi la chiave dalla variabile d'ambiente e imposta un timeout sufficientemente ampio. La generazione video non è una richiesta istantanea — un timeout predefinito di 10 secondi produce falsi fallimenti che sembrano errori API ma sono solo il tuo client che rinuncia in anticipo.
Per l'image-to-video, aggiungi una riga:
payload["model"] = "gemini-omni-flash/image-to-video"
payload["image"] = "https://your-cdn.example.com/source-frame.jpg"
In caso di codici di stato non 2xx, stampa o registra sempre il corpo della risposta grezza prima di sollevare l'eccezione. Il testo dell'errore di solito indica direttamente il campo problematico.
Organizzare il codice dell'integrazione
Una volta che entrambi i percorsi funzionano, è tentante lasciare nel codebase due funzioni quasi identiche. Una struttura leggermente migliore costa quasi nulla e si ripaga nel momento stesso in cui aggiungi un secondo modello video.
Due componenti condivisi
Un builder di richieste. Una funzione che riceve parametri a livello di intento e restituisce il dizionario del payload:
def build_video_payload(prompt, image_url=None, duration=None):
if image_url:
payload = {
"model": "gemini-omni-flash/image-to-video",
"prompt": prompt,
"image": image_url,
}
else:
payload = {
"model": "gemini-omni-flash/text-to-video",
"prompt": prompt,
}
if duration:
payload["duration"] = duration
return payload
La scelta dell'endpoint diventa il risultato di "ho un'immagine?", che corrisponde alla decisione di prodotto reale. Il chiamante non tocca mai direttamente l'ID modello.
Un gestore di risposte. Una funzione che separa gli errori di trasporto, di payload e a livello di modello e restituisce un oggetto risultato normalizzato (stato, riferimento al video, corpo grezzo della risposta per i log). Tutti i chiamanti passano di lì, così la semantica degli errori resta coerente tra i due endpoint.
Perché conviene
- L'ID modello si cambia in un solo punto. Quando passi a un modello video diverso, modifichi solo il builder, non quindici punti di chiamata.
- Gestione degli errori coerente. Un fallimento nel recupero dell'immagine e un errore di validazione del prompt arrivano alla tua UI allo stesso modo.
- Testabile senza rete. Il builder è una funzione pura; puoi testare unitariamente la struttura del payload a basso costo.
- Visibilità della fatturazione. Poiché i video sono fatturati sull'output generato, un unico gestore è il posto naturale per registrare durata e dimensione dell'output per tracciare i costi.
Mantieni il builder snello. La logica di business su cosa generare spetta al chiamante; il builder deve solo sapere come esprimere quell'intento nella forma dell'API.
Fare debug dei fallimenti di richiesta comuni
Quasi tutti i fallimenti iniziali ricadono in una di tre categorie. Individua prima la categoria, poi correggi.
Categoria 1: struttura della richiesta
Sintomo: 4xx immediato, messaggio di errore che cita campi mancanti o sconosciuti, oppure lamentela su JSON malformato.
Controlla in ordine:
- Il JSON è valido? Incolla il corpo della richiesta in un linter. Una virgola finale lasciata dalla modifica manuale del payload è un classico.
- L'ID modello è esattamente quello giusto?
gemini-omni-flash/text-to-videoegemini-omni-flash-text-to-videonon sono la stessa stringa. Un refuso qui produce un errore "modello non trovato" che sembra un problema di autenticazione. - Gli header sono completi? Sia
AuthorizationcheContent-Type: application/jsonsono impostati. - Modello ed endpoint corrispondono? Inviare il campo
imageall'endpoint testuale non dà il risultato che vuoi — il campo viene rifiutato o ignorato, e in entrambi i casi ottieni un risultato errato.
Categoria 2: risorsa di input (solo percorso immagine)
Sintomo: la richiesta viene accettata ma fallisce durante l'elaborazione, oppure l'errore cita il recupero o la decodifica dell'immagine.
Controlla:
- Apri l'URL dell'immagine in una finestra in incognito senza cookie. Se non si carica lì, non si caricherà nemmeno per il servizio.
- Verifica che l'URL non sia un indirizzo localhost, un host di rete privata o un link firmato scaduto.
- Verifica che il formato sia un formato web comune e che la dimensione del file sia ragionevole.
- Verifica che la risposta sia davvero un'immagine — una CDN che restituisce 200 con una pagina di errore HTML è un tranello sorprendentemente comune.
Categoria 3: la chiamata al modello stessa
Sintomo: la richiesta è valida, la risorsa è raggiungibile, ma la generazione fallisce o viene rifiutata — di solito per policy sui contenuti o capacità.
Controlla:
- Riduci al prompt minimo e riprova. Se funziona, il tuo prompt è la variabile.
- Verifica che il timeout del client sia abbastanza lungo — nei log, un timeout del client sembra identico a un fallimento del server, a meno che tu non controlli se è mai arrivata una risposta.
- Abilita i log completi di richiesta/risposta (con la chiave oscurata), così distingui le tre categorie a colpo d'occhio.
Ordine di debug efficace
Payload minimo → verifica → aggiungi immagine → verifica → aggiungi i parametri opzionali uno alla volta → verifica. Quando qualcosa si rompe, l'ultima modifica che hai fatto è il colpevole. Se insisti nel debuggare una variabile alla volta, gran parte del dolore dell'integrazione svanisce.
Inizia dalla chiamata minima funzionante di ogni endpoint, avvolgila in un builder e in un gestore condivisi, poi espandi gradualmente — questo percorso mantiene prevedibili sia il text-to-video che l'image-to-video man mano che l'integrazione cresce.
Articoli correlati
Vedi tutti gli articoli →-
Tutoriale
Guida pratica a gpt-6.2-sol: 5 utilizzi ad alto valore dei modelli testuali nel business
-
Tutoriale
Guida pratica a gpt-6.2-astra: integrazione e punti chiave per 5 scenari testuali ad alto valore
Checklist dal punto di vista dello sviluppatore, dalla selezione degli scenari all'implementazione ingegneristica
-
Tutoriale
Scenari pratici di Tripo H3.1: 5 utilizzi ad alto valore e punti di implementazione
Da text-to-3D alla ricostruzione multi-view: scegliere modalità e parametri giusti per ogni scenario di business