> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Istruzioni per l'integrazione dell'API Gemini Videos Generation > Gemini AI API guide - Ace Data Cloud 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](https://platform.acedata.cloud/console/applications) per ottenere il tuo API Token, da tenere come riserva. ![](https://cdn.acedata.cloud/dvc3cg.jpg) 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](https://platform.acedata.cloud/console/coin). > 📘 Documentazione completa: [Gemini Videos Generation API →](https://platform.acedata.cloud/documents/gemini-videos) ## 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: ```json theme={null} { "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: ```shell theme={null} 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: ```python theme={null} 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: ```json theme={null} { "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`: ```json theme={null} { "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`: ```json theme={null} { "task_id": "cd68b4ee-de70-4c94-ac69-997a3fed0284" } ``` Successivamente, utilizzare questo `task_id` come `id` per effettuare il polling della [Gemini Tasks API](https://platform.acedata.cloud/documents/gemini-tasks); al completamento dell'attività, sarà possibile ottenere il nuovo video generato (questo è il risultato restituito reale dell'esempio): ```json theme={null} { "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: ```json theme={null} { "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: ```json theme={null} { "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: ```json theme={null} { "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](https://platform.acedata.cloud/documents/gemini-tasks) (`POST https://api.acedata.cloud/gemini/tasks`). Nel corpo della richiesta, passare il `task_id` restituito al momento della creazione del video come `id`: ```json theme={null} { "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`): ```json theme={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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.