Istruzioni per l'integrazione dell'API Veo Videos Generation

Questo articolo presenterà un metodo di integrazione dell’API Veo Videos Generation, che consente di generare video ufficiali Veo inserendo parametri personalizzati.

Processo di richiesta

Per utilizzare l’API Veo Videos Generation, ottieni innanzitutto il tuo API Token dalla Console Ace Data Cloud e conservalo per un utilizzo successivo.

Se non hai ancora effettuato l’accesso o non ti sei registrato, verrai automaticamente reindirizzato alla pagina di accesso per invitarti a registrarti e ad accedere; al termine, tornerai automaticamente alla pagina corrente. Un solo API Token può chiamare tutti i servizi della piattaforma, senza necessità di richiederne uno separatamente per ciascun servizio. Alla prima richiesta verrà assegnato un credito gratuito, utilizzabile per una prova gratuita; quando il credito è insufficiente, puoi ricaricare il saldo universale dalla console.

📘 Documentazione completa: Veo Videos Generation API →

Utilizzo di base

Comprendiamo innanzitutto il metodo di utilizzo di base: inserendo il prompt prompt, l’azione di generazione action, l’array di immagini di riferimento per il primo e l’ultimo fotogramma image_urls e il modello model, è possibile ottenere il risultato elaborato. Innanzitutto, è necessario passare semplicemente un campo action, il cui valore è text2video; esso contiene principalmente tre comportamenti: testo in video (text2video), immagine in video (image2video), ottenimento del video 1080p (get1080p). Quindi dobbiamo anche inserire il modello model; attualmente sono disponibili principalmente i modelli veo31-fast, veo3, veo31, veo3-fast e veo31-fast-ingredients, i cui dettagli sono i seguenti:

Qui possiamo vedere che sono stati impostati i Request Headers, inclusi:

accept: il formato del risultato di risposta che 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 la richiesta.

Sono inoltre impostati i Request Body, inclusi:

model: il modello per generare video, principalmente i modelli veo31-fast, veo3, veo31, veo3-fast e veo31-fast-ingredients.
action: il comportamento di questa attività di generazione video, che contiene principalmente tre comportamenti: testo in video (text2video), immagine in video (image2video), ottenimento del video 1080p (get1080p).
image_urls: quando si seleziona il comportamento immagine in video image2video, è obbligatorio fornire i link delle immagini di riferimento da caricare. veo31-fast-ingredients supporta fino a 3 immagini (fusione multi-immagine), mentre gli altri modelli supportano fino a 2 immagini (modalità primo e ultimo fotogramma).
resolution: seleziona la risoluzione del video generato; tra questi, il modello veo31 supporta la risoluzione 4k, gli altri modelli non la supportano. Tutti i modelli supportano le risoluzioni 1080p e gif; se questo valore non viene passato, viene utilizzata per impostazione predefinita la risoluzione 720p. Le opzioni principali sono: 1080p, gif, 4k.
prompt: il prompt.
callback_url: l’URL a cui restituire il risultato tramite callback.
async: opzionale; quando impostato su true, l’interfaccia restituisce immediatamente task_id, senza la necessità di fornire callback_url; successivamente, il risultato viene ottenuto tramite polling attraverso l’interfaccia di query dell’attività corrispondente.

📌 Riepilogo della descrizione dei modelli

Nome del modello	Modalità supportate	Regole per l’input delle immagini
veo3-fast	Testo in video (senza immagini) Modalità immagine in video (con immagini)	1 immagine → Modalità primo fotogramma 2 immagini → Modalità primo e ultimo fotogramma
veo31-fast	Testo in video (senza immagini) Modalità immagine in video (con immagini)	1 immagine → Modalità primo fotogramma 2 immagini → Modalità primo e ultimo fotogramma
veo31-fast-ingredients	❌ Testo in video (non supportato) ✅ Fusione multi-immagine obbligatoria (è necessario passare immagini)	1-3 immagini → Modalità fusione multi-immagine (massimo 3 immagini)
veo3	Testo in video (senza immagini) Modalità immagine in video (con immagini)	1 immagine → Modalità primo fotogramma 2 immagini → Modalità primo e ultimo fotogramma
veo31	Testo in video (senza immagini) Modalità immagine in video (con immagini)	1 immagine → Modalità primo fotogramma 2 immagini → Modalità primo e ultimo fotogramma

🔑 Descrizione delle regole chiave

Logica generale:
- Nessun input di immagini → attiva automaticamente la modalità testo in video.
- Con input di immagini → attiva la modalità immagine in video (il comportamento specifico è determinato dal numero di immagini).
Tipi di modalità immagine in video:
- Modalità primo fotogramma (1 immagine): il primo fotogramma è fissato all’immagine di input.
- Modalità primo e ultimo fotogramma (2 immagini): il primo e l’ultimo fotogramma sono fissati alle immagini di input.
- Modalità fusione multi-immagine (1-3 immagini): supportata solo da veo31-fast-ingredients, fonde il contenuto di più immagini per generare il video.
Classificazione delle modalità:

Modalità Fast: veo3-fast, veo31-fast, veo31-fast-ingredients.
Modalità Quality: veo3, veo31 (qualità di generazione superiore).

⚠️ Note

Unico modello che richiede obbligatoriamente immagini: veo31-fast-ingredients deve ricevere immagini (1-3), altrimenti non può funzionare.
Limiti sul numero di immagini:
- veo31-fast-ingredients supporta input di 1-3 immagini (modalità fusione multi-immagine).
- Gli altri modelli supportano al massimo l’input di 2 immagini (modalità primo e ultimo fotogramma).

Dopo la selezione, si può notare che sul lato destro viene generato anche il codice corrispondente, come mostrato nell’immagine:

Fai clic sul pulsante «Try» per eseguire il test; come mostrato nell’immagine sopra, qui otteniamo il seguente risultato:

{
  "success": true,
  "task_id": "697ea2fc-58fd-48c8-8191-29041ff23c3c",
  "trace_id": "70e1cb12-c619-4292-a416-90191205996b",
  "data": [
    {
      "id": "24ac06a5-9cc7-448f-802e-0b4db19f6e96",
      "video_url": "https://cdn.acedata.cloud/assets/examples/veo/f5389ec0-2eb5-4212-b4a8-04b513b0129a-0b0c3113d691.mp4",
      "created_at": "2026-06-30T04:01:50.364Z",
      "complete_at": "2026-06-30T04:03:20.495Z",
      "state": "succeeded"
    }
  ]
}

Il risultato restituito contiene diversi campi, descritti di seguito:

success, lo stato dell’attività di generazione video in questo momento.
task_id, l’ID dell’attività di generazione video in questo momento.
data, il risultato dell’attività di generazione video in questo momento.
- id, l’ID del video dell’attività di generazione video in questo momento.
- video_url, il link del video dell’attività di generazione video in questo momento.
- created_at, l’ora di creazione dell’attività di generazione video in questo momento.
- complete_at, l’ora di completamento dell’attività di generazione video in questo momento.
- state, lo stato dell’attività di generazione video in questo momento.

Si può vedere che abbiamo ottenuto informazioni video soddisfacenti, dobbiamo solo ottenere il video Veo generato in base all’indirizzo del link video in data nel risultato. Inoltre, se si desidera generare il codice di integrazione corrispondente, è possibile copiarlo direttamente per generarlo, ad esempio il codice CURL è il seguente:

curl -X POST 'https://api.acedata.cloud/veo/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "veo31-fast",
  "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle."
}'

Funzionalità da immagine a video

Se si desidera generare un video in base alle immagini dei fotogrammi iniziale e finale, è possibile impostare il parametro action su image2video e inserire l’array di link delle immagini dei fotogrammi iniziale e finale image_urls. Successivamente dobbiamo compilare le parole chiave che devono essere estese nel passaggio successivo per personalizzare la generazione del video, quindi è possibile specificare il seguente contenuto:

model: il modello per generare video, principalmente veo31-fast, veo3, veo31, veo3-fast e veo31-fast-ingredients.
image_urls: quando si seleziona l’azione da immagine a video image2video, sono necessari i link delle immagini di riferimento da caricare.
prompt: parole chiave.

Un esempio di compilazione è il seguente:

Dopo aver compilato, il codice viene generato automaticamente come segue:

Il codice Python corrispondente:

import requests

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

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

payload = {
    "action": "image2video",
    "model": "veo31-fast",
    "prompt": "Let it dance",
    "image_urls": ["https://cdn.acedata.cloud/7p1jhy.png"]
}

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

Facendo clic su esegui, si può notare che si ottiene un risultato, come segue:

{
  "success": true,
  "task_id": "98e309f3-35bc-438d-8cb3-4015fc864b87",
  "trace_id": "8bc68066-36de-41ef-ae5e-b7d61ff6aee8",
  "data": [
    {
      "id": "59f12222b1fa4fbe9331ff2400ad1583",
      "video_url": "https://platform.cdn.acedata.cloud/veo/98e309f3-35bc-438d-8cb3-4015fc864b87.mp4",
      "created_at": "2025-07-25 16:13:07",
      "complete_at": "2025-07-25 16:16:12",
      "state": "succeeded"
    }
  ]
}

Si può vedere che il contenuto del risultato è coerente con quello sopra, realizzando così la funzionalità da immagine a video.

Funzionalità per ottenere video a 1080p

Se si desidera ottenere una versione a 1080p di un video Veo già generato, è possibile impostare il parametro action su get1080p e inserire l’ID del video di cui si desidera ottenere la versione a 1080p; l’ID del video viene ottenuto in base all’utilizzo di base, come mostrato nell’immagine seguente:

A questo punto si può vedere che l’ID del video è:

"id": "59f12222b1fa4fbe9331ff2400ad1583"

Nota, qui video_id nel video è l’ID del video generato, se non sai come generare un video, puoi fare riferimento all’utilizzo di base sopra per generare un video.

Successivamente dobbiamo compilare le parole chiave che devono essere estese nel passaggio successivo per personalizzare la generazione del video, quindi è possibile specificare il seguente contenuto:

model: il modello per generare video, principalmente veo31-fast, veo3, veo31, veo3-fast e veo31-fast-ingredients.
video_id: l’ID del video di riferimento, utilizzato per ottenere il video a 1080p.

Un esempio di compilazione è il seguente:

Dopo aver compilato, il codice viene generato automaticamente come segue:

Facendo clic su esegui, si può notare che si ottiene un risultato, come segue:

{
  "success": true,
  "task_id": "47a51cfe-2e24-4aba-93b3-546c2dc52984",
  "trace_id": "a8922eec-6f50-4f77-8104-00ded071d59d",
  "data": [
    {
      "id": "59f12222b1fa4fbe9331ff2400ad1583",
      "video_url": "https://platform.cdn.acedata.cloud/veo/47a51cfe-2e24-4aba-93b3-546c2dc52984.mp4",
      "created_at": "2025-07-25 16:13:07",
      "complete_at": "2025-07-25 16:16:12",
      "state": "succeeded"
    }
  ]
}

Si può vedere che il contenuto del risultato è coerente con quello sopra, realizzando così la funzionalità per ottenere video a 1080p.

Generazione specificando le dimensioni del video

Se si desidera specificare la generazione di un video Veo con dimensioni personalizzate, è possibile impostare il parametro aspect_ratio sulle dimensioni desiderate, successivamente dobbiamo compilare le parole chiave che devono essere estese nel passaggio successivo per personalizzare la generazione del video, quindi è possibile specificare il seguente contenuto:

model: il modello per generare video, principalmente veo31-fast, veo3, veo31, veo3-fast e veo31-fast-ingredients.
aspect_ratio: la dimensione del video, attualmente supporta: 16:9, 16:9, 3:4, 4:3, 1:1, il valore predefinito è 16:9.
translation: se abilitare la traduzione automatica delle parole chiave, il valore predefinito è false. Un esempio di compilazione è il seguente:

Dopo aver compilato, il codice viene generato automaticamente come segue:

Facendo clic su esegui, si può notare che si ottiene un risultato, come segue:

{
  "success": true,
  "task_id": "d2b93290-ab0e-4d20-ae45-60c062a32687",
  "trace_id": "9834e64d-c8fe-43ae-8114-ee2b5f93d886",
  "data": [
    {
      "id": "fc667e7d3b8f44beaa61a3c339af0e50",
      "video_url": "https://platform.cdn.acedata.cloud/veo/d2b93290-ab0e-4d20-ae45-60c062a32687.mp4",
      "created_at": "2025-08-24 20:09:06",
      "complete_at": "2025-08-24 20:10:45",
      "state": "succeeded"
    }
  ]
}

Si può notare che il contenuto del risultato è coerente con quello sopra, realizzando così la funzionalità di generazione di video con dimensioni specificate.

Callback asincrono

Poiché il tempo di generazione di Veo Videos Generation API è relativamente lungo, richiedendo circa 1-2 minuti, se l’API non risponde per un lungo periodo, la richiesta HTTP manterrà continuamente la connessione, causando un consumo aggiuntivo di risorse di sistema, pertanto questa API fornisce anche il supporto per callback asincroni. Il flusso complessivo è: quando il client avvia una richiesta, specifica inoltre un campo callback_url, dopo che il client ha avviato la richiesta API, l’API restituirà immediatamente un risultato, contenente le informazioni di un campo task_id, che rappresenta l’ID dell’attività corrente. Quando l’attività è completata, il risultato del video generato verrà inviato tramite POST JSON al callback_url specificato dal client, includendo anch’esso il campo task_id, in questo modo i risultati dell’attività possono essere associati tramite l’ID. Di seguito comprendiamo come operare nello specifico attraverso un esempio. Innanzitutto, il callback Webhook è un servizio che può ricevere richieste HTTP, gli sviluppatori dovrebbero sostituirlo con l’URL del server HTTP che hanno configurato autonomamente. Per comodità di dimostrazione, qui viene utilizzato un sito di esempio Webhook pubblico https://webhook.site/; aprendo questo sito è possibile ottenere un URL Webhook, come mostrato nell’immagine:

Copiare questo URL, quindi può essere utilizzato come Webhook; l’esempio qui è https://webhook.site/aed5cd28-f8aa-4dca-9480-8ec9b42137dc. Successivamente, possiamo impostare il campo callback_url come l’URL Webhook sopra indicato, inserendo contemporaneamente i parametri corrispondenti; il contenuto specifico è mostrato nell’immagine:

Fare clic su Esegui, e si può notare che si otterrà immediatamente un risultato, come segue:

{
  "task_id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed"
}

Attendere un momento, possiamo osservare il risultato del video generato su https://webhook.site/aed5cd28-f8aa-4dca-9480-8ec9b42137dc, come mostrato nell’immagine:

Il contenuto è il seguente:

{
  "success": true,
  "task_id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed",
  "trace_id": "d1d53c04-58c5-4c40-bb63-f00188540e56",
  "data": [
    {
      "id": "2f43ceed37944b4d836e1a1899dad0a1",
      "video_url": "https://platform.cdn.acedata.cloud/veo/1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed.mp4",
      "created_at": "2025-07-25 17:19:20",
      "complete_at": "2025-07-25 17:21:45",
      "state": "succeeded"
    }
  ]
}

Si può vedere che nel risultato è presente un campo task_id, tutti gli altri campi sono simili a quelli sopra, attraverso questo campo è possibile realizzare l’associazione dell’attività.

Gestione degli errori

Quando si chiama l’API, se si verifica un errore, l’API restituirà il codice e il messaggio di errore corrispondenti. Ad esempio:

400 token_mismatched：Richiesta non valida, probabilmente a causa di parametri mancanti o non validi.
400 api_not_implemented：Richiesta non valida, probabilmente a causa di parametri mancanti o non validi.
401 invalid_token：Non autorizzato, token di autorizzazione non valido o mancante.
429 too_many_requests：Troppe richieste, hai superato il limite di frequenza.
500 api_error：Errore interno del server, qualcosa è andato storto sul server.

Esempio di risposta di errore

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Conclusione

Attraverso questo documento, hai già appreso come utilizzare Veo Videos Generation API per generare video inserendo prompt e immagini di riferimento del primo fotogramma. Speriamo che questo documento possa aiutarti a integrare e utilizzare meglio questa API. Per qualsiasi domanda, non esitare a contattare il nostro team di supporto tecnico.

Inizia

Chat AI

Immagine AI

Video AI

Audio AI

Web e Dati

CAPTCHA

Identità

Coding

Altre guide

Istruzioni per l'integrazione dell'API Veo Videos Generation

Processo di richiesta

Utilizzo di base

📌 Riepilogo della descrizione dei modelli

🔑 Descrizione delle regole chiave

⚠️ Note

Funzionalità da immagine a video

Funzionalità per ottenere video a 1080p

Generazione specificando le dimensioni del video

Callback asincrono

Gestione degli errori

Esempio di risposta di errore

Conclusione

​Processo di richiesta

​Utilizzo di base

​📌 Riepilogo della descrizione dei modelli

​🔑 Descrizione delle regole chiave

​⚠️ Note

​Funzionalità da immagine a video

​Funzionalità per ottenere video a 1080p

​Generazione specificando le dimensioni del video

​Callback asincrono

​Gestione degli errori

​Esempio di risposta di errore

​Conclusione

Processo di richiesta

Utilizzo di base

📌 Riepilogo della descrizione dei modelli

🔑 Descrizione delle regole chiave

⚠️ Note

Funzionalità da immagine a video

Funzionalità per ottenere video a 1080p

Generazione specificando le dimensioni del video

Callback asincrono

Gestione degli errori

Esempio di risposta di errore

Conclusione