Istruzioni per l'integrazione dell'API Veo Videos Generation

Questo documento presenterà un’istruzione per l’integrazione dell’API Veo Videos Generation, che consente di generare video ufficiali di Veo tramite l’immissione di parametri personalizzati.

Procedura di richiesta

Per utilizzare l’API Veo Videos Generation, prima di tutto vai al Pannello di controllo di Ace Data Cloud per ottenere il tuo API Token, da conservare per uso futuro.

Se non hai ancora effettuato il login o la registrazione, verrai automaticamente reindirizzato alla pagina di login che ti invita a registrarti e accedere; una volta completato, verrai riportato automaticamente alla pagina corrente. Un API Token è sufficiente per accedere a tutti i servizi della piattaforma, senza necessità di richiederne uno separato per ogni servizio. La prima richiesta riceverà un credito gratuito, per un’esperienza senza costi; quando il credito è insufficiente, puoi ricaricare il saldo generale nel pannello di controllo.

📘 Documentazione completa: Veo Videos Generation API →

Utilizzo di base

Iniziamo a comprendere il modo di utilizzo di base, che consiste nell’immettere la parola chiave prompt, l’azione action, l’array di immagini di riferimento image_urls e il modello model, per ottenere il risultato elaborato. Prima di tutto, è necessario passare un campo action, il cui valore è text2video, che include principalmente tre tipi di azioni: generazione di video da testo (text2video), generazione di video da immagini (image2video), e ottenere video in 1080p (get1080p). Dobbiamo anche inserire il modello model, attualmente disponibili i modelli veo31-fast, veo3, veo31, veo3-fast e veo31-fast-ingredients, i dettagli sono i seguenti:

Possiamo vedere che qui abbiamo impostato le intestazioni della richiesta, che includono:

accept: il formato della risposta desiderata, qui impostato su application/json, ovvero formato JSON.
authorization: la chiave per chiamare l’API, che può essere selezionata direttamente dopo la richiesta.

Inoltre, abbiamo impostato il corpo della richiesta, che include:

model: il modello per generare il video, principalmente veo31-fast, veo3, veo31, veo3-fast e veo31-fast-ingredients.
action: l’azione per il compito di generazione video, che include principalmente tre azioni: generazione di video da testo (text2video), generazione di video da immagini (image2video), e ottenere video in 1080p (get1080p).
image_urls: quando si sceglie l’azione di generazione video da immagini image2video, è necessario caricare i link delle immagini di riferimento. veo31-fast-ingredients supporta fino a 3 immagini (fusione di più immagini), mentre gli altri modelli supportano al massimo 2 immagini (modalità primo e ultimo fotogramma).
resolution: scegliere la risoluzione del video generato, dove il modello veo31 supporta la risoluzione 4k, mentre gli altri modelli non la supportano; tutti i modelli supportano 1080p e risoluzione gif, se non viene fornito questo valore, si utilizza per impostazione predefinita la risoluzione 720p, suddivisa in: 1080p, gif, 4k.
prompt: parola chiave.
callback_url: URL per ricevere il risultato.
async: opzionale, impostato su true per restituire immediatamente task_id, senza necessità di fornire callback_url, successivamente si può ottenere il risultato tramite l’interfaccia di query del compito corrispondente.

📌 Riepilogo delle descrizioni dei modelli

Nome del modello	Modalità supportate	Regole di input delle immagini
veo3-fast	Generazione video da testo (senza immagini) Generazione video da immagini (con immagini)	1 immagine → modalità primo fotogramma 2 immagini → modalità primo e ultimo fotogramma
veo31-fast	Generazione video da testo (senza immagini) Generazione video da immagini (con immagini)	1 immagine → modalità primo fotogramma 2 immagini → modalità primo e ultimo fotogramma
veo31-fast-ingredients	❌ Generazione video da testo (non supportata) ✅ Fusione di più immagini obbligatoria (deve essere fornita un’immagine)	1-3 immagini → modalità fusione di più immagini (fino a 3 immagini)
veo3	Generazione video da testo (senza immagini) Generazione video da immagini (con immagini)	1 immagine → modalità primo fotogramma 2 immagini → modalità primo e ultimo fotogramma
veo31	Generazione video da testo (senza immagini) Generazione video da immagini (con immagini)	1 immagine → modalità primo fotogramma 2 immagini → modalità primo e ultimo fotogramma

🔑 Spiegazione delle regole chiave

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

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

⚠️ Avvertenze

Modello obbligatorio per l’inserimento di immagini: veo31-fast-ingredients deve ricevere immagini (1-3 immagini), altrimenti non può funzionare.
Limiti sul numero di immagini:
- veo31-fast-ingredients supporta 1-3 immagini in input (modalità fusione di più immagini).
- Gli altri modelli supportano al massimo 2 immagini in input (modalità primo e ultimo fotogramma).

Dopo aver effettuato la selezione, puoi notare che a destra è stato generato il codice corrispondente, come mostrato nell’immagine:

Cliccando sul pulsante “Prova” puoi effettuare un test, come mostrato nell’immagine sopra, e qui abbiamo ottenuto 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://platform2.cdn.acedata.cloud/veo/f5389ec0-2eb5-4212-b4a8-04b513b0129a.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 come segue:

success，lo stato attuale del compito di generazione video.
task_id，l’ID del compito di generazione video attuale.
data，il risultato del compito di generazione video attuale.
- id，l’ID del video del compito di generazione video attuale.
- video_url，il link del video del compito di generazione video attuale.
- created_at，il tempo di creazione del compito di generazione video attuale.
- complete_at，il tempo di completamento del compito di generazione video attuale.
- state，lo stato del compito di generazione video attuale.

Possiamo vedere che abbiamo ottenuto informazioni soddisfacenti sul video, dobbiamo solo ottenere il video generato dal link video in data. Inoltre, se si desidera generare il codice di integrazione corrispondente, è possibile copiarlo direttamente, 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."
}'

Funzione di generazione video da immagini

Se si desidera generare un video in base alle immagini del primo e dell’ultimo fotogramma, è possibile impostare il parametro action su image2video e inserire un array di link delle immagini del primo e dell’ultimo fotogramma image_urls. Successivamente, dobbiamo compilare le parole chiave da espandere per personalizzare la generazione del video, specificando i seguenti contenuti:

model：il modello per la generazione del video, principalmente veo31-fast、veo3、veo31、veo3-fast e veo31-fast-ingredients.
image_urls：quando si sceglie l’azione di generazione video image2video, è necessario caricare i link delle immagini di riferimento.
prompt：parole chiave.

Esempio di compilazione:

Dopo aver completato la compilazione, il codice generato automaticamente è il seguente:

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)

Cliccando su esegui, possiamo vedere che otteniamo 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"
    }
  ]
}

Possiamo vedere che il contenuto del risultato è coerente con quanto sopra, il che realizza la funzione di generazione video da immagini.

Funzione per ottenere video in 1080p

Se si desidera ottenere un video Veo già generato in 1080p, è possibile impostare il parametro action su get1080p e inserire l’ID del video di cui si desidera ottenere il 1080p. L’ID del video può essere ottenuto in base all’uso di base, come mostrato nell’immagine seguente:

A questo punto, possiamo vedere che l’ID del video è:

"id": "59f12222b1fa4fbe9331ff2400ad1583"

Nota: l’ID del video qui è l’ID del video generato. Se non sai come generare un video, puoi fare riferimento all’uso di base sopra per generare un video.

Successivamente, dobbiamo compilare le parole chiave da espandere per personalizzare la generazione del video, specificando i seguenti contenuti:

model：il modello per la generazione del 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 in 1080p.

Esempio di compilazione:

Dopo aver completato la compilazione, il codice generato automaticamente è il seguente:

Cliccando su esegui, possiamo vedere che otteniamo 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"
    }
  ]
}

Possiamo vedere che il contenuto del risultato è coerente con quanto sopra, il che realizza la funzione di ottenere video in 1080p.

Generazione di video con dimensioni specifiche

Se si desidera generare un video Veo con dimensioni personalizzate, è possibile impostare il parametro aspect_ratio sulla dimensione desiderata. Successivamente, dobbiamo compilare le parole chiave da espandere per personalizzare la generazione del video, specificando i seguenti contenuti:

model：il modello per la generazione del 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. Esempio di compilazione:

Dopo aver completato la compilazione, il codice generato automaticamente è il seguente:

Cliccando su esegui, possiamo vedere che otteniamo 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 quanto sopra, il che realizza la funzionalità di generazione video di dimensioni specificate.

Callback asincrono

Poiché il tempo di generazione dell’API Veo Videos Generation è relativamente lungo, circa 1-2 minuti, se l’API non risponde per un lungo periodo, la richiesta HTTP manterrà la connessione, causando un consumo aggiuntivo di risorse di sistema. Pertanto, questa API offre anche supporto per callback asincroni. Il flusso complessivo è: quando il client invia una richiesta, specifica un campo callback_url aggiuntivo. Dopo che il client ha inviato la richiesta API, l’API restituirà immediatamente un risultato, contenente un campo task_id, che rappresenta l’ID del compito corrente. Quando il compito è completato, il risultato del video generato verrà inviato al callback_url specificato dal client in formato JSON POST, che include anche il campo task_id, in modo che il risultato del compito possa essere correlato tramite l’ID. Di seguito, vediamo un esempio per capire come operare concretamente. Innanzitutto, il callback Webhook è un servizio in grado di ricevere richieste HTTP, gli sviluppatori dovrebbero sostituirlo con l’URL del server HTTP che hanno costruito. Qui, per comodità di dimostrazione, utilizziamo un sito Web pubblico di esempio per Webhook https://webhook.site/, aprendo questo sito si ottiene un URL Webhook, come mostrato nell’immagine:

Copia questo URL e puoi usarlo come Webhook, l’esempio qui è https://webhook.site/aed5cd28-f8aa-4dca-9480-8ec9b42137dc. Successivamente, possiamo impostare il campo callback_url su questo URL Webhook, riempiendo i parametri corrispondenti, come mostrato nell’immagine:

Cliccando su Esegui, si può notare che si ottiene immediatamente un risultato, come segue:

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

Dopo 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 c’è un campo task_id, gli altri campi sono simili a quelli sopra, e tramite questo campo è possibile realizzare l’associazione dei compiti.

Gestione degli errori

Quando si chiama l’API, se si verifica un errore, l’API restituirà il codice di errore e le informazioni 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 appreso come utilizzare l’API Veo Videos Generation per generare video tramite input di parole chiave e immagini di riferimento del primo fotogramma. Speriamo che questo documento possa aiutarti a integrare e utilizzare meglio questa API. Se hai domande, non esitare a contattare il nostro team di supporto tecnico.

Inizia

Chat AI

Immagine AI

Video AI

Audio AI

Web e Dati

CAPTCHA

Identità

Proxy

Avanzato

Istruzioni per l'integrazione dell'API Veo Videos Generation

Procedura di richiesta

Utilizzo di base

📌 Riepilogo delle descrizioni dei modelli

🔑 Spiegazione delle regole chiave

⚠️ Avvertenze

Funzione di generazione video da immagini

Funzione per ottenere video in 1080p

Generazione di video con dimensioni specifiche

Callback asincrono

Gestione degli errori

Esempio di risposta di errore

Conclusione

​Procedura di richiesta

​Utilizzo di base

​📌 Riepilogo delle descrizioni dei modelli

​🔑 Spiegazione delle regole chiave

​⚠️ Avvertenze

​Funzione di generazione video da immagini

​Funzione per ottenere video in 1080p

​Generazione di video con dimensioni specifiche

​Callback asincrono

​Gestione degli errori

​Esempio di risposta di errore

​Conclusione

Procedura di richiesta

Utilizzo di base

📌 Riepilogo delle descrizioni dei modelli

🔑 Spiegazione delle regole chiave

⚠️ Avvertenze

Funzione di generazione video da immagini

Funzione per ottenere video in 1080p

Generazione di video con dimensioni specifiche

Callback asincrono

Gestione degli errori

Esempio di risposta di errore

Conclusione