Blog

Tutoriale

Come usare gemini-omni-flash/text-to-video tramite l'API HiAPI: guida con curl e Python

Nov 12, 2026
Immagine di copertina: fogli beige sovrapposti disposti in modo sfalsato, con una pagina color ocra rossiccia come accento, in un ritmo stratificato misurato.
In questa pagina

Cosa fa questo endpoint e quando usarlo

gemini-omni-flash/text-to-video è un endpoint di generazione su HiAPI che trasforma un prompt testuale — facoltativamente ancorato a un'immagine di primo frame — in un breve video. Invii una richiesta, HiAPI restituisce un task interrogabile e, al termine, ottieni l'URL di un video che puoi scaricare o riprodurre in streaming.

Questo endpoint è adatto nei seguenti scenari:

  • Clip concettuali rapide. Genera teaser marketing brevi, anteprime di storyboard o contenuti di transizione per i social direttamente da una o due frasi descrittive.
  • Movimento guidato da un'immagine. Hai già un fotogramma statico — una foto prodotto, un design di personaggio, un'illustrazione — e vuoi animarlo invece di generare da zero.
  • Generazione in batch all'interno di una pipeline. Poiché la generazione è asincrona, puoi inviare molti task in una sola volta da un worker backend e raccogliere i risultati in seguito, senza mantenere aperta la connessione della richiesta.

Non è adatto per video lunghi, montaggi precisi fotogramma per fotogramma o per la riproduzione deterministica di inquadrature specifiche. Consideralo come una bozza generativa rapida: economica da iterare, sufficiente per la revisione e scriptabile end-to-end.

Tutto ciò che segue passa dalla stessa interfaccia HiAPI — una API key, un URL di base, una struttura di richiesta — quindi il codice che scrivi qui può essere trasferito ad altri endpoint di generazione senza dover reimparare autenticazione o polling.

Prima di inviare la prima richiesta

Servono quattro cose prima che la prima chiamata vada a buon fine.

1. API key

Crea una key nel tuo account HiAPI e conservala in una variabile d'ambiente, non nel codice sorgente:

export HIAPI_API_KEY="your_key_here"

2. URL di base e percorso dell'endpoint

Tutte le richieste vanno all'URL di base di HiAPI, con l'identificatore del modello nel percorso. Tratta l'URL di base come un'unica costante nel codice, così da poterlo modificare in un solo punto:

export HIAPI_BASE_URL="https://api.hiapi.ai"

3. Corpo della richiesta JSON

La richiesta è un POST con Content-Type: application/json e il bearer token nell'header Authorization. Salvo quando fornisci un'immagine di primo frame tramite URL, non c'è form encoding né upload multipart.

4. Immagine di primo frame (facoltativa)

Se intendi guidare la generazione con un'immagine, assicurati prima che sia raggiungibile tramite un URL HTTPS pubblico. I percorsi del file system locale non funzionano — l'API recupera l'immagine lato server.

Un suggerimento pratico per la consapevolezza dei costi: questo endpoint viene fatturato in base all'output che generi — sia il livello di risoluzione sia la durata della clip contribuiscono. Controlla il pannello prezzi di HiAPI per il prezzo unitario attuale, quindi verificalo lì prima di espandere i batch di job. L'abitudine importante è questa: prototipa con le impostazioni minime e alza le impostazioni solo dopo che il prompt produce il risultato desiderato.

Costruire la richiesta di generazione

Una richiesta è concettualmente composta da tre parti: il percorso del modello, il prompt (e facoltativamente l'immagine) e le opzioni di generazione. La struttura è la seguente:

{
  "prompt": "Una lenta carrellata in avanti su una tazza di caffè in vetro mentre il vapore sale verso l'alto, luce del mattino, profondità di campo ridotta",
  "image": "https://your-bucket.example.com/first-frame.jpg",
  "resolution": "720p",
  "duration": 5,
  "audio": false
}

Prompt

Il campo prompt contiene la descrizione dell'inquadratura. Scrivilo come note di regia: soggetto, comportamento del movimento di camera, luce e atmosfera. Verbi di movimento concreti ("lenta carrellata in avanti", "la camera panoramica verso sinistra", "il vapore sale verso l'alto") guidano i risultati in modo più affidabile rispetto al semplice accumulo di aggettivi.

Primo frame facoltativo

Il campo image è facoltativo. Se lo ometti, il modello genera l'intera clip basandosi solo sul testo. Se lo includi, la clip parte da quel frame e il prompt descrive cosa deve accadere dopo. Questo è il fattore che più influenza la coerenza: un prompt puramente testuale reimmagina la scena a ogni esecuzione, mentre un primo frame fisso mantiene stabile la composizione tra le iterazioni.

Se fornisci entrambi, assicurati che siano coerenti. Un primo frame di un paesaggio desertico accompagnato da un prompt su una strada urbana sotto la pioggia produce risultati confusi — il modello deve conciliare due istruzioni contraddittorie.

Dove inserire le opzioni

resolution, duration e audio si trovano allo stesso livello di prompt e image nel corpo JSON. Non serve memorizzare un oggetto options annidato. Mantieni il corpo piatto e leggibile — questo rende il logging e il confronto tra richieste molto più semplici durante il debug dei batch.

Scegliere risoluzione e durata

Due parametri dominano sia l'aspetto dell'output sia il costo del job: il livello di risoluzione e la durata della clip.

Livelli di risoluzione

HiAPI espone questo endpoint con diversi livelli di risoluzione. I livelli inferiori sono un default sensato durante la fase di sviluppo del prompt — rendering più veloce, così puoi iterare sulla formulazione senza pagare per dettagli che finirai per scartare. Una volta che il prompt produce in modo affidabile la composizione desiderata, passa a un livello superiore per il rendering finale.

Un flusso di lavoro pratico:

  1. Abbozza il prompt al livello più basso.
  2. Genera due o tre varianti e confrontale.
  3. Blocca il prompt, poi renderizza di nuovo a un livello superiore.

Durata della clip

La durata è specificata in secondi e questo endpoint è pensato per clip brevi. Mantieni la durata contenuta: le clip brevi rendono ogni job più veloce, i tentativi falliti costano meno e, se in seguito ti serve una sequenza più lunga, puoi concatenare più clip. Se un'inquadratura richiede otto secondi di tempo sullo schermo, due generazioni da quattro secondi sono di solito più facili da controllare rispetto a un'unica generazione lunga.

Come si traduce nel budget

Questo endpoint viene fatturato in base all'output che produci — risoluzioni più alte e durate più lunghe aumentano l'output fatturabile di ogni singolo job. Poiché i prezzi sono calcolati per unità di generazione e i livelli cambiano nel tempo, leggi i dati aggiornati sul pannello prezzi di HiAPI invece di codificare a priori le aspettative. La regola di pianificazione che vale a qualsiasi variazione di prezzo: moltiplica il numero previsto di job per la scala dell'output, prototipa con le impostazioni minime e scala la risoluzione solo alla fine.

Controllare l'audio nativo

Il flag audio determina se il video restituito include una traccia audio nativa generata insieme alle immagini.

{
  "prompt": "Pioggia che batte su un tetto di lamiera, una porta che scricchiola mentre si apre lentamente",
  "audio": true
}

Cosa cambia quando è attivo

Con audio: true il modello genera suoni coerenti con la scena descritta nel prompt — ambienza, texture ambientali ed eventi sonori impliciti nell'azione. Il video di output include un flusso audio, quindi il file che scarichi è già completo, senza bisogno di un trattamento separato degli effetti sonori.

Cosa cambia quando è disattivato

Con audio: false ottieni un video muto. Questo è adatto quando:

  • Vuoi sovrapporre nel tuo editor musica o voce fuori campo alla clip.
  • La clip è un elemento di sfondo all'interno di un montaggio più ampio.
  • Stai iterando solo sulle immagini e non vuoi che la generazione audio entri nel ciclo.

Scrivere prompt per l'audio

Se attivi l'audio, descrivi il paesaggio sonoro come descrivi le immagini. Gli indizi sonori nel prompt — pioggia, passi, rumori meccanici, l'atmosfera specifica di una stanza — danno un fondamento al modello audio. Un prompt puramente visivo produrrà comunque audio, ma sarà un'ambienza generica anziché un suono coerente con l'inquadratura.

Un'avvertenza da testare presto: l'audio cambia sensibilmente il carattere della clip. Genera lo stesso prompt una volta con il flag attivo e una volta con il flag disattivato, guarda entrambi e decidi quale modalità serva davvero al progetto prima di costruirci sopra dei batch.

Gestire il ciclo di vita dei task asincroni

La generazione video richiede più tempo di quanto una tipica richiesta HTTP dovrebbe restare aperta, quindi l'endpoint è asincrono. Ogni chiamata segue lo stesso ciclo in tre passaggi.

Passaggio 1: invio

Invia il corpo JSON con POST all'endpoint. Un invio riuscito restituisce immediatamente un identificatore del task — di solito l'id del task — e uno stato che indica che il task è in coda o in elaborazione. A questo punto non è ancora stato renderizzato nulla.

Passaggio 2: polling

Con l'id del task, interroga l'endpoint di stato del task a intervalli regolari. Ogni polling restituisce lo stato corrente: queued, processing, completed o failed. Devi gestire tutti e quattro gli stati. Un semplice backoff esponenziale — partendo da circa due secondi, con un tetto sull'intervallo — evita di martellare l'API sui task lunghi e allo stesso tempo intercetta rapidamente i task brevi.

Passaggio 3: recupero

Quando lo stato riporta completed, la risposta contiene l'URL del video completato e i metadati del task. Scaricalo, archivialo oppure passa l'URL al frontend. Se lo stato riporta failed, recupera il messaggio di errore dalla risposta e decidi se riprovare dopo aver modificato il prompt o esporre il fallimento.

Protezioni da integrare

  • Limite di timeout. Limita il tempo totale di polling (ad esempio a pochi minuti) e contrassegna il task come fallito nel tuo codice, invece di entrare in un ciclo infinito.
  • Numero massimo di polling. Previeni cicli fuori controllo quando lo stato non diventa mai definitivo.
  • Persistenza dell'id del task. Scrivilo su un database o nei log non appena lo ricevi. Se il processo si blocca durante il polling, puoi riprendere invece di rigenerare e pagare due volte.
  • Invii idempotenti. Non reinviare per un problema di rete prima di aver verificato che la prima richiesta sia fallita; i task duplicati consumano output reale.

Se implementi correttamente questo ciclo una volta, funzionerà per tutti gli endpoint asincroni di HiAPI.

Esempi eseguibili con curl e Python

curl: invio, polling, recupero

Imposta la key e l'URL di base dalle variabili d'ambiente, poi invia:

curl -sS -X POST "$HIAPI_BASE_URL/v1/models/gemini-omni-flash/text-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Una lenta carrellata in avanti su una tazza di caffè in vetro mentre il vapore sale verso l'alto, luce del mattino, profondità di campo ridotta",
    "image": "https://your-bucket.example.com/first-frame.jpg",
    "resolution": "720p",
    "duration": 5,
    "audio": false
  }'

La risposta contiene l'id del task. Recupera l'endpoint di stato dalla risposta e interroga:

curl -sS "$HIAPI_BASE_URL/v1/tasks/<TASK_ID>" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Ripeti finché lo stato non è completed, poi estrai l'URL del video dal corpo della risposta e scaricalo:

curl -sS -o clip.mp4 "<VIDEO_URL>"

Python: lo stesso ciclo, incapsulato

import os
import time
import requests

BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}


def generate_video(prompt, image_url=None, resolution="720p",
                   duration=5, audio=False, timeout=300):
    payload = {
        "prompt": prompt,
        "resolution": resolution,
        "duration": duration,
        "audio": audio,
    }
    if image_url:
        payload["image"] = image_url

    resp = requests.post(
        f"{BASE}/v1/models/gemini-omni-flash/text-to-video",
        headers=HEADERS, json=payload, timeout=30,
    )
    resp.raise_for_status()
    task_id = resp.json()["id"]
    print(f"submitted: {task_id}")

    deadline = time.time() + timeout
    interval = 2
    while time.time() < deadline:
        status_resp = requests.get(
            f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30
        )
        status_resp.raise_for_status()
        data = status_resp.json()
        state = data.get("status")

        if state == "completed":
            return data["video_url"]
        if state == "failed":
            raise RuntimeError(f"job failed: {data}")

        time.sleep(interval)
        interval = min(interval * 1.5, 10)

    raise TimeoutError(f"job {task_id} did not finish in {timeout}s")


if __name__ == "__main__":
    url = generate_video(
        "Una lenta carrellata in avanti su una tazza di caffè in vetro "
        "mentre il vapore sale verso l'alto, luce del mattino, "
        "profondità di campo ridotta",
    )
    print("video ready:", url)

Questo script invia un task puramente testuale, esegue il polling con backoff, applica un limite di timeout e restituisce l'URL del video completato. Passa image_url= per ancorare la generazione a un primo frame, oppure imposta audio=True per includere il suono nativo. Da qui puoi inserire generate_video in una coda di worker, in una rotta FastAPI o in un ciclo batch — la funzione è autocontenuta e senza stato, a parte l'id del task che crea.

Punti di fallimento comuni e come evitarli

La maggior parte delle integrazioni fallite inciampa in uno di questi cinque problemi.

Invio rifiutato per parametri non validi

La causa più comune è che l'API non riesce a interpretare il corpo della richiesta: prompt mancante, durata fuori dall'intervallo supportato o stringa di risoluzione non supportata. Consulta il riferimento dell'endpoint per i valori accettati e validali prima localmente. Un piccolo strumento che verifica i valori consentiti prima della chiamata risparmia un round trip e un errore confuso.

Immagine di primo frame non accessibile

L'API recupera image lato server, quindi un URL che funziona nel browser può comunque fallire — bucket privati, link firmati che scadono e hotlink protection causano questo problema. Usa un URL HTTPS leggibile pubblicamente e verifica che si risolva dall'esterno della tua rete prima di inviare.

Abbandonare il polling

Due varianti dello stesso errore: arrendersi alla prima risposta processing e presumere un fallimento, oppure interrogare in modo troppo aggressivo e raggiungere i limiti di frequenza. Risolvi entrambe con il ciclo di backoff con tetto mostrato sopra: interroga secondo la pianificazione, tratta gli stati non definitivi come normali e lancia un'eccezione solo in caso di fallimento esplicito o timeout.

Perdere l'id del task

Se il processo muore dopo l'invio ma prima del salvataggio del risultato, il task è stato pagato ma è inaccessibile. Scrivi l'id del task in uno storage persistente subito dopo l'invio e controlla all'avvio se ci sono ancora id in corso prima di inviare nuovi task.

Output troppo grande su larga scala

Generare grandi batch ad alta risoluzione e con durate lunghe amplifica rapidamente il volume di output, e i file generati sono costosi da archiviare e lenti da servire. Prototipa su piccola scala, renderizza in finale una sola volta e mantieni attive le regole del ciclo di vita dello storage. Poiché la fatturazione è legata all'output generato, la soluzione più economica è quasi sempre un ciclo di iterazione di prototipi più piccolo.

Percorri questa checklist in un ambiente di pre-rilascio e il tuo percorso in produzione sarà fluido.

Inizia a creare con artefatti IA persistenti

Ottieni la tua chiave API e chiama modelli di immagini, video e audio tramite un'unica API basata sui task.

Leggi la documentazione API