Istruzioni per l'integrazione dell'API Gemini Videos Generation

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:

{
  "success": true,
  "task_id": "9258c45f-bed9-4dde-81c2-a70a710a6904",
  "trace_id": "862d6aae-cec0-407f-9524-bc1be2291bcb",
  "data": [
    {
      "id": "dc4b7292-070c-49a8-8183-919bdf8ad59e",
      "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/9258c45f-bed9-4dde-81c2-a70a710a6904-418c13e0605f.mp4",
      "state": "succeeded",
      "aspect_ratio": "16:9",
      "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden"
    }
  ],
  "started_at": 1784112953.856,
  "finished_at": 1784113021.328,
  "elapsed": 67.472,
  "cost": {
    "amount": 1.932,
    "currency": "credit",
    "list_amount": 2.1
  }
}

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:

curl -X POST 'https://api.acedata.cloud/gemini/videos' \
-H 'authorization: Bearer ${bearer_token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
  "model": "omni-flash",
  "aspect_ratio": "16:9"
}'

Il codice Python corrispondente è il seguente:

import requests

url = "https://api.acedata.cloud/gemini/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
    "model": "omni-flash",
    "aspect_ratio": "16:9"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

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:

{
  "prompt": "The woman slowly turns around and smiles at the camera, gentle breeze",
  "model": "omni-flash",
  "aspect_ratio": "9:16",
  "image_urls": [
    "https://cdn.acedata.cloud/assets/examples/nanobanana/e44bfceb-1458-4b4b-9d10-21024678f1a3-5ccb6e83b402.png"
  ]
}

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

È supportato direttamente «inserire un video e generare un nuovo video»: passa un collegamento a un video di riferimento in video_urls (massimo 1) e contemporaneamente fornisci almeno un’immagine di riferimento in image_urls (requisito obbligatorio a monte), quindi utilizza prompt per descrivere l’effetto di editing desiderato (cambiare stile, cambiare 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 forte nevicata, mantenendo al contempo la disposizione della spiaggia, delle palme e della barca. L’editing video richiede più tempo (circa 6,5 minuti in questo esempio), pertanto viene inviato in modo asincrono con async: true:

{
  "prompt": "Turn this sunny tropical beach into a snowy winter scene with heavy falling snow and overcast sky; keep the same beach, palm trees and boat layout.",
  "model": "omni-flash",
  "aspect_ratio": "9:16",
  "resolution": "720p",
  "image_urls": [
    "https://cdn.acedata.cloud/99289603bd.png"
  ],
  "video_urls": [
    "https://cdn.acedata.cloud/assets/examples/seedance/dd3dc063-3383-4f29-bedc-e771a096758c-044e05281a2a.mp4"
  ],
  "async": true
}

Dopo l’invio, l’API restituisce immediatamente task_id:

{
  "task_id": "cd68b4ee-de70-4c94-ac69-997a3fed0284"
}

Successivamente, utilizzare questo task_id come id per effettuare il polling della Gemini Tasks API; al completamento dell’attività, sarà possibile ottenere il nuovo video generato (questo è il risultato restituito reale dell’esempio):

{
  "success": true,
  "task_id": "cd68b4ee-de70-4c94-ac69-997a3fed0284",
  "trace_id": "5b22104b-5a6d-4a4f-8063-69acae1dc1c6",
  "data": [
    {
      "id": "e125d316-3d26-4c65-9413-55baf6be46b8",
      "video_url": "https://cdn.acedata.cloud/assets/examples/sora/cd68b4ee-de70-4c94-ac69-997a3fed0284-c5603ef983da.mp4",
      "state": "succeeded",
      "aspect_ratio": "9:16",
      "prompt": "Turn this sunny tropical beach into a snowy winter scene with heavy falling snow and overcast sky; keep the same beach, palm trees and boat layout."
    }
  ],
  "started_at": 1784084482.914,
  "finished_at": 1784084877.09,
  "elapsed": 394.176,
  "cost": {
    "amount": 1.932,
    "currency": "credit",
    "list_amount": 2.1
  }
}

Se è necessario un risultato a maggiore definizione, è possibile impostare resolution su 1080p (gli altri parametri rimangono invariati).

Suggerimento: i link ai contenuti multimediali di input/output nell’esempio sono tutti risultati generati reali. I link a video e immagini generati dalla piattaforma hanno un periodo di conservazione e diventeranno non validi dopo la scadenza, quindi scaricarli e salvarli tempestivamente nel proprio archivio dopo aver ottenuto il risultato.

Nota: è consentito al massimo 1 video di riferimento; inoltre, quando viene fornito video_urls, è necessario fornire almeno un image_urls, altrimenti verrà restituito il seguente errore di parametro:

{
  "success": false,
  "error": {
    "code": "bad_request",
    "message": "image_urls (at least one reference image) is required when video_urls is provided."
  }
}

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:

{
  "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
  "model": "omni-flash",
  "aspect_ratio": "16:9",
  "callback_url": "https://your-domain.com/callback/gemini"
}

Il risultato restituito immediatamente è il seguente:

{
  "task_id": "04a043bd-6b23-4b4e-945c-ce48158c3eee"
}

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:

{
  "id": "04a043bd-6b23-4b4e-945c-ce48158c3eee"
}

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):

{
  "id": "04a043bd-6b23-4b4e-945c-ce48158c3eee",
  "type": "videos",
  "request": {
    "model": "omni-flash",
    "prompt": "A time-lapse of clouds over snow mountains at sunrise",
    "aspect_ratio": "16:9",
    "async": true
  },
  "response": {
    "success": true,
    "task_id": "04a043bd-6b23-4b4e-945c-ce48158c3eee",
    "data": [
      {
        "id": "486ebd5a-6a4b-406c-84ae-33835de4fe19",
        "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
        "state": "succeeded",
        "aspect_ratio": "16:9",
        "prompt": "A time-lapse of clouds over snow mountains at sunrise"
      }
    ],
    "elapsed": 96.716,
    "cost": {
      "amount": 1.932,
      "currency": "credit",
      "list_amount": 2.1
    }
  }
}

Gestione degli errori

Quando si verifica un problema con la richiesta, l’API restituirà il codice di errore e la relativa descrizione; quelli comuni sono i seguenti:

400: parametri della richiesta errati, ad esempio prompt mancante o valore di aspect_ratio non valido.
401: autenticazione non riuscita, token non valido o non corrispondente all’API.
403: saldo insufficiente, oppure rifiuto perché il prompt ha attivato la revisione dei contenuti.
500: errore interno del server o generazione upstream non riuscita.

Inizia

Chat AI

Immagine AI

Video AI

Audio AI

Web e Dati

CAPTCHA

Identità

Coding

Altre guide

Istruzioni per l'integrazione dell'API Gemini Videos Generation

Processo di richiesta

Utilizzo di base

Generazione video da immagine

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

Callback asincrono

Consultazione del risultato dell’attività

Gestione degli errori

​Processo di richiesta

​Utilizzo di base

​Generazione video da immagine

​Editing video / Video di riferimento (video in input, video generato)

​Callback asincrono

​Consultazione del risultato dell’attività

​Gestione degli errori

Processo di richiesta

Utilizzo di base

Generazione video da immagine

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

Callback asincrono

Consultazione del risultato dell’attività

Gestione degli errori