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 promptprompt, 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 suapplication/json, ovvero il formato JSON.authorization: la chiave per chiamare l’API, che può essere selezionata direttamente dal menu a discesa dopo averla richiesta.
prompt: il prompt testuale che descrive il contenuto video da generare, obbligatorio.model: il modello per generare video; attualmente è supportato soloomni-flash, e il valore predefinito èomni-flash.aspect_ratio: il rapporto d’aspetto del video generato; è possibile scegliere16:9(orizzontale) o9:16(verticale), il valore predefinito è16:9.resolution: la risoluzione di output opzionale; è possibile scegliere720po1080p, 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 utilizzavideo_urlsper 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 inimage_urls.callback_url: indirizzo di callback asincrono; dopo l’impostazione, l’API restituirà immediatamentetask_ide invierà il risultato tramite POST a tale indirizzo al completamento dell’attività.async: opzionale; se impostato sutrue, l’interfaccia restituisce immediatamentetask_id, senza necessità di fornirecallback_url; successivamente, il risultato viene ottenuto tramite polling attraverso l’interfaccia di interrogazione dell’attività corrispondente.
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 (ènullquandostateèpending).state: stato dell’attività di generazione video; può esserepending/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.
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:
Generazione video da immagine
Se vuoi generare un video basato su immagini di riferimento, puoi passare uno o più collegamenti a immagini inimage_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) invideo_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:
task_id:
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):
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 fornitovideo_urls, è necessario fornire almeno un’immagineimage_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 passarecallback_url; in questo caso l’API restituirà immediatamente task_id e, al completamento dell’attività, invierà il risultato finale tramite POST a questo indirizzo:
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 altask_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:
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 esempiopromptmancante o valoreaspect_rationon 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.

