Vai al contenuto principale
Questo articolo introdurrà le istruzioni per l’integrazione dell’API Gemini Videos Generation, che può generare video Google Gemini (omni-flash) tramite l’inserimento di prompt testuali (e immagini di riferimento opzionali).

Processo di richiesta

Per utilizzare l’API Gemini Videos Generation, per prima cosa vai alla console Ace Data Cloud per ottenere il tuo API Token, da tenere come riserva. Se non hai ancora effettuato l’accesso o la registrazione, verrai reindirizzato automaticamente alla pagina di accesso per invitarti a registrarti e accedere; al termine, tornerai automaticamente alla pagina corrente. Un solo API Token può richiamare tutti i servizi della piattaforma, senza necessità di richiederne uno separato per ciascun servizio. Alla prima richiesta verrà assegnato un credito gratuito, per provare gratuitamente; quando il credito è insufficiente, puoi ricaricare il saldo universale nella console.
📘 Documentazione completa: Gemini Videos Generation API →

Utilizzo di base

Per prima cosa vediamo il metodo di utilizzo di base: inserendo il prompt prompt, il modello model e il rapporto d’aspetto aspect_ratio, è possibile generare il video corrispondente. Qui possiamo vedere che abbiamo impostato i Request Headers, tra cui:
  • accept: quale formato di risultato della risposta si desidera ricevere; qui è impostato su application/json, ovvero il formato JSON.
  • authorization: la chiave per chiamare l’API, che può essere selezionata direttamente dal menu a discesa dopo averla richiesta.
Sono inoltre impostati i Request Body, tra cui:
  • prompt: il prompt testuale che descrive il contenuto video da generare, obbligatorio.
  • model: il modello per generare video; attualmente è supportato solo omni-flash, e il valore predefinito è omni-flash.
  • aspect_ratio: il rapporto d’aspetto del video generato; è possibile scegliere 16:9 (orizzontale) o 9:16 (verticale), il valore predefinito è 16:9.
  • resolution: la risoluzione di output opzionale; è possibile scegliere 720p o 1080p, il valore predefinito è 720p.
  • image_urls: un array opzionale di collegamenti a immagini di riferimento, utilizzato per guidare la generazione del video; le voci vuote verranno ignorate. Quando si utilizza video_urls per l’editing video, questo parametro è obbligatorio (almeno un’immagine).
  • video_urls: un array opzionale di collegamenti a video di riferimento (massimo 1), utilizzato per editing video / riferimento video; quando fornito, deve essere fornita contemporaneamente almeno un’immagine in image_urls.
  • callback_url: indirizzo di callback asincrono; dopo l’impostazione, l’API restituirà immediatamente task_id e invierà il risultato tramite POST a tale indirizzo al completamento dell’attività.
  • async: opzionale; se impostato su true, l’interfaccia restituisce immediatamente task_id, senza necessità di fornire callback_url; successivamente, il risultato viene ottenuto tramite polling attraverso l’interfaccia di interrogazione dell’attività corrispondente.
Fai clic sul pulsante «Try» per eseguire il test; il risultato ottenuto è simile al seguente:
Il risultato restituito contiene diversi campi, descritti di seguito:
  • success: se questa richiesta di generazione video è riuscita.
  • task_id: l’ID dell’attività di generazione video corrente.
  • trace_id: l’ID di tracciamento della richiesta corrente, utilizzato per la risoluzione dei problemi.
  • data: elenco dei risultati video generati.
    • id: identificatore univoco del video generato.
    • video_url: indirizzo del collegamento del video generato (è null quando state è pending).
    • state: stato dell’attività di generazione video; può essere pending / succeeded / failed.
    • aspect_ratio: il rapporto d’aspetto di questo video, coerente con i parametri della richiesta.
    • prompt: il prompt utilizzato per generare questo video.
In caso di risposta sincrona, al livello superiore vengono inclusi anche campi come started_at, finished_at, elapsed (tempo impiegato, secondi) e cost (addebito corrente, unità Credit). Dobbiamo solo ottenere il video generato in base all’indirizzo del collegamento video_url in data nel risultato. Il codice CURL corrispondente è il seguente:
Il codice Python corrispondente è il seguente:

Generazione video da immagine

Se vuoi generare un video basato su immagini di riferimento, puoi passare uno o più collegamenti a immagini in image_urls, per guidare la generazione del video:

Modifica video / Video di riferimento (video in input, video generato)

È supportato direttamente il flusso «inserire un video e generarne uno nuovo»: fornire un link a un video di riferimento (massimo 1) in video_urls e, contemporaneamente, fornire almeno un’immagine di riferimento in image_urls, quindi usare prompt per descrivere l’effetto di modifica desiderato (cambiare stile, sostituire la scena, aggiungere o rimuovere elementi, ecc.). Di seguito è riportato un esempio reale completo: trasformare un video di una spiaggia soleggiata in una scena invernale con una fitta nevicata, mantenendo al contempo la disposizione della spiaggia, delle palme e della barca. La modifica video richiede più tempo (in questo esempio circa 6,5 minuti), pertanto viene inviata in modo asincrono tramite async: true:
Dopo l’invio, l’API restituisce immediatamente task_id:
Successivamente, utilizzare questo task_id come id per eseguire il polling della Gemini Tasks API. Al completamento dell’attività, sarà possibile ottenere il nuovo video generato (questo è il risultato reale restituito da questo esempio):
Per ottenere un risultato a risoluzione più alta, impostare resolution su 1080p (lasciando invariati gli altri parametri).
Suggerimento: i link ai media di input/output negli esempi sono risultati realmente generati. I link ai video e alle immagini generati dalla piattaforma hanno un periodo di conservazione e scadranno; dopo aver ottenuto i risultati, scaricali e salvali tempestivamente nel tuo spazio di archiviazione.
Nota: è consentito al massimo 1 video di riferimento; inoltre, quando viene fornito video_urls, è necessario fornire almeno un’immagine image_urls, altrimenti verrà restituito il seguente errore di parametro:

Callback asincrono

La generazione del video richiede un certo tempo di elaborazione. Se non si desidera mantenere una connessione lunga in attesa, è possibile passare callback_url; in questo caso l’API restituirà immediatamente task_id e, al completamento dell’attività, invierà il risultato finale tramite POST a questo indirizzo:
Il risultato restituito immediatamente è il seguente:

Consultazione del risultato dell’attività

Se viene utilizzato il callback asincrono o si desidera consultare attivamente lo stato dell’attività, è possibile interrogare lo stato e il risultato più recenti dell’attività in base al task_id tramite la Gemini Tasks API (POST https://api.acedata.cloud/gemini/tasks). Nel corpo della richiesta, passare il task_id restituito al momento della creazione del video come id:
Il risultato restituito al completamento dell’attività è simile al seguente; la struttura di response.data è coerente con quella della generazione sincrona (durante la generazione, state è pending e video_url è null):

Gestione degli errori

Quando si verifica un problema con una richiesta, l’API restituisce il codice di errore e la relativa descrizione. Alcuni errori comuni sono i seguenti:
  • 400: parametri della richiesta non validi, ad esempio prompt mancante o valore aspect_ratio non valido.
  • 401: autenticazione non riuscita; il token non è valido o non corrisponde all’API.
  • 403: saldo insufficiente oppure richiesta rifiutata perché il prompt ha attivato la moderazione dei contenuti.
  • 500: eccezione del servizio o generazione non riuscita.