Vai al contenuto principale
Questo documento illustra le istruzioni per l’integrazione con l’API di Generazione Video Sora, tramite la quale è possibile generare video ufficiali Sora inserendo parametri personalizzati. Questa API supporta due modalità di versione:
  • Versione 1 (modalità classica): supporta i parametri duration (10/15/25 secondi), orientation (orizzontale/verticale), size (small/large qualità), immagini di riferimento image_urls, link del personaggio character_url e altri.
  • Versione 2 (modalità partner): supporta i parametri seconds (4/8/12 secondi), risoluzione a livello di pixel size (ad esempio 1280x720), immagini di riferimento input_reference e altri.

​
Procedura di richiesta

Per utilizzare l’API, è necessario prima richiedere il servizio corrispondente sulla pagina Sora Videos Generation API. Dopo aver aperto la pagina, cliccare sul pulsante “Acquire”, come mostrato nell’immagine: Se non si è ancora effettuato l’accesso o la registrazione, si verrà automaticamente reindirizzati alla pagina di login per registrarsi e accedere; dopo il login si tornerà automaticamente alla pagina corrente. Alla prima richiesta viene offerto un credito gratuito per utilizzare l’API senza costi.

​
Uso base (Versione 1)

Per prima cosa, vediamo il modo base di utilizzo della Versione 1: inserire il prompt prompt, un array di URL di immagini di riferimento image_urls e il modello model per ottenere il risultato elaborato. Il contenuto specifico è il seguente:

Qui impostiamo gli header della richiesta, tra cui:
  • accept: indica il formato di risposta desiderato, qui impostato su application/json (formato JSON).
  • authorization: la chiave API per chiamare l’API, selezionabile direttamente dopo la richiesta.
Inoltre, impostiamo il corpo della richiesta (Request Body), che include:
  • model: modello per generare il video, supporta sora-2 (modalità standard) e sora-2-pro (modalità HD). sora-2-pro supporta video di 25 secondi, mentre sora-2 solo 10 o 15 secondi.
  • size: qualità del video, small per qualità standard, large per HD (solo Versione 1).
  • duration: durata del video, supporta 10, 15, 25 secondi; 25 secondi è supportato solo da sora-2-pro (solo Versione 1).
  • orientation: orientamento del video, supporta landscape (orizzontale), portrait (verticale) (solo Versione 1).
  • image_urls: array di URL di immagini di riferimento per generare video da immagini (solo Versione 1).
  • character_url: link del personaggio, il video non deve contenere persone reali (solo Versione 1).
  • character_start/character_end: secondi di inizio e fine comparsa del personaggio, intervallo 1-3 secondi (solo Versione 1).
  • prompt: prompt testuale (obbligatorio).
  • callback_url: URL per callback asincrono.
  • version: versione API, "1.0" (default) o "2.0".
Dopo la selezione, si genera automaticamente il codice corrispondente a destra, come mostrato:

Cliccando il pulsante “Try” si può testare la chiamata; come nell’immagine, otteniamo il seguente risultato: 
{
  "success": true,
  "task_id": "6bf7fb83-5814-4e3e-a4ad-bfa0c26c0b33",
  "trace_id": "96166698-4b66-478d-a26b-77a7269c9e01",
  "data": [
    {
      "id": "sora-2:task_01k7770rgsevxsmtpbn7xnm5gh",
      "video_url": "https://filesystem.site/gptimage/vg-assets/assets%2Ftask_01k7770rgsevxsmtpbn7xnm5gh%2Ftask_01k7770rgsevxsmtpbn7xnm5gh_genid_0bf958d3-cae7-4298-b7b6-99ae439a1ea6_25_10_10_14_06_975715%2Fvideos%2F00000%2Fsrc.mp4?st=2025-10-10T12%3A30%3A38Z&se=2025-10-16T13%3A30%3A38Z&sks=b&skt=2025-10-10T12%3A30%3A38Z&ske=2025-10-16T13%3A30%3A38Z&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skoid=8ebb0df1-a278-4e2e-9c20-f2d373479b3a&skv=2019-02-02&sv=2018-11-09&sr=b&sp=r&spr=https%2Chttp&sig=jigY6Z5qp8%2BTXYobaW0EAJ4%2Fbx6G7t6V1P0iyDeUq48%3D&az=oaivgprodscus",
      "state": "succeeded"
    }
  ]
}
Il risultato restituito contiene vari campi, descritti di seguito:
  • success: stato del task di generazione video.
  • task_id: ID del task di generazione video.
  • trace_id: ID di tracciamento della richiesta.
  • data: lista dei risultati del task di generazione video.
    • id: ID del video generato.
    • video_url: URL del video generato.
    • state: stato del task.
Come si vede, abbiamo ottenuto le informazioni del video desiderato; basta usare l’URL contenuto in data per scaricare il video Sora generato. Se si desidera generare il codice di integrazione corrispondente, è possibile copiarlo direttamente, ad esempio il codice CURL è: 
curl -X POST 'https://api.acedata.cloud/sora/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "size": "large",
  "duration": 15,
  "orientation": "landscape",
  "prompt": "cat running on the river",
  "model": "sora-2"
}'

​
Task di generazione video da immagine (Versione 1)

Per generare un video da immagine, è necessario passare il parametro image_urls con gli URL delle immagini di riferimento, specificando:
  • image_urls: array di URL delle immagini di riferimento per il task di generazione video da immagine. Non inviare immagini con volti reali, altrimenti il task potrebbe fallire.
Esempio di compilazione:

Dopo la compilazione si genera automaticamente il codice:

Codice corrispondente: 
import requests

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

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

payload = {
    "size": "large",
    "duration": 15,
    "orientation": "landscape",
    "prompt": "cat running on the river",
    "model": "sora-2",
    "image_urls": ["https://cdn.acedata.cloud/11wfp4.png"]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
Eseguendo la chiamata si ottiene subito un risultato: 
{
  "success": true,
  "task_id": "dd392ff0-dcb7-4c7a-afd0-9bd4f65c803a",
  "trace_id": "04fd151c-e942-4c1c-a6ab-9a1b1fe54172",
  "data": [
    {
      "id": "sora-2:task_01k777af4hfmg9g7yfvwsc6zws",
      "video_url": "https://filesystem.site/gptimage/vg-assets/assets%2Ftask_01k777af4hfmg9g7yfvwsc6zws%2Ftask_01k777af4hfmg9g7yfvwsc6zws_genid_92bae0c5-1703-4a5f-9d9f-c9ed2f9e7176_25_10_10_14_12_924695%2Fvideos%2F00000%2Fsrc.mp4?st=2025-10-10T12%3A37%3A32Z&se=2025-10-16T13%3A37%3A32Z&sks=b&skt=2025-10-10T12%3A37%3A32Z&ske=2025-10-16T13%3A37%3A32Z&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skoid=aa5ddad1-c91a-4f0a-9aca-e20682cc8969&skv=2019-02-02&sv=2018-11-09&sr=b&sp=r&spr=https%2Chttp&sig=5j4dibeaSsDmEka5c%2B9CKHZhRPdqfClQ0tIh03TWXsM%3D&az=oaivgprodscus",
      "state": "succeeded"
    }
  ]
}
Come si vede, il risultato è un video generato da immagine, simile a quanto mostrato sopra.

​
Task di generazione video con personaggio (Versione 1)

Per generare un video con personaggio, è necessario passare il parametro character_url con il link video per creare il personaggio; il video non deve contenere persone reali, altrimenti il task fallirà. Si possono specificare i seguenti parametri:
  • character_url: link video per creare il personaggio, senza persone reali.
Esempio di compilazione:

Dopo la compilazione si genera automaticamente il codice:

Codice corrispondente: 
import requests

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

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

payload = {
    "size": "small",
    "duration": 10,
    "orientation": "landscape",
    "prompt": "cat running on the river",
    "character_url": "https://cdn.acedata.cloud/pdidf5.mp4",
    "model": "sora-2",
    "character_end": 3,
    "character_start": 1
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
Eseguendo la chiamata si ottiene subito un risultato: 
{
  "success": true,
  "task_id": "d9bf5461-29b5-47fd-be90-1fe9197df259",
  "trace_id": "b7992643-9207-40d6-956b-7577728acc67",
  "data": [
    {
      "id": "sora-2:task_01k8ykrztefavaypw6xanw305b",
      "video_url": "https://filesystem.site/cdn/20251101/bee4eeeb4c4660b46dac4548a1ffbc.mp4",
      "state": "succeeded"
    }
  ]
}
Come si vede, il risultato è un video generato con personaggio, simile a quanto mostrato sopra.

​
Modalità Versione 2.0

Oltre alla modalità Versione 1.0 sopra descritta, questa API supporta anche la modalità Versione 2.0, attivabile impostando il parametro version a "2.0". La modalità 2.0 supporta video di durata più breve e controllo della risoluzione a livello di pixel.

​
Descrizione parametri Versione 2.0

ParametroTipoObbligatorioDescrizione
versionstringSìImpostare a "2.0"
promptstringSìPrompt per generare il video
modelstringNosora-2 (default) o sora-2-pro
durationintegerNoDurata video: 4 (default), 8, 12 secondi
sizestringNoRisoluzione: 720x1280 (default), 1280x720, 1024x1792, 1792x1024
image_urlsarrayNoArray di URL immagini di riferimento, viene usata solo la prima immagine, dimensioni devono corrispondere a size
callback_urlstringNoURL per callback asincrono

​
Esempio base

curl -X POST 'https://api.acedata.cloud/sora/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "version": "2.0",
  "prompt": "cat running on the river",
  "model": "sora-2",
  "duration": 8,
  "size": "1280x720"
}'
Codice Python corrispondente: 
import requests

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

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

payload = {
    "version": "2.0",
    "prompt": "cat running on the river",
    "model": "sora-2",
    "seconds": 8,
    "size": "1280x720"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
Codice JavaScript corrispondente: 
const response = await fetch('https://api.acedata.cloud/sora/videos', {
  method: 'POST',
  headers: {
    'accept': 'application/json',
    'authorization': 'Bearer {token}',
    'content-type': 'application/json'
  },
  body: JSON.stringify({
    version: '2.0',
    prompt: 'cat running on the river',
    model: 'sora-2',
    seconds: 8,
    size: '1280x720'
  })
});
const data = await response.json();
console.log(data);
Il formato del risultato restituito è identico a quello della Versione 1: 
{
  "success": true,
  "task_id": "6bf7fb83-5814-4e3e-a4ad-bfa0c26c0b33",
  "trace_id": "96166698-4b66-478d-a26b-77a7269c9e01",
  "data": [
    {
      "id": "c0cc8dad-0954-421f-be8d-02eb063b3263",
      "video_url": "https://platform.cdn.acedata.cloud/sora/xxxxx.mp4",
      "state": "succeeded"
    }
  ]
}

​
Uso di immagini di riferimento (Versione 2.0)

Nella modalità Versione 2.0 è possibile passare immagini di riferimento tramite il parametro image_urls per guidare la generazione video (viene usata solo la prima immagine): 
import requests

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

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

payload = {
    "version": "2.0",
    "prompt": "a person walking through a beautiful garden",
    "model": "sora-2",
    "duration": 4,
    "size": "1280x720",
    "image_urls": ["https://cdn.acedata.cloud/11wfp4.png"]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
Nota: la dimensione dell’immagine di riferimento deve corrispondere al parametro size. Ad esempio, se size è 1280x720, l’immagine deve avere dimensioni 1280×720.

​
Confronto parametri Versione 1.0 e 2.0

ParametroVersione 1.0Versione 2.0
version1.0 (default)2.0
prompt✅✅
model✅ sora-2 / sora-2-pro✅ sora-2 / sora-2-pro
duration✅ 10/15/25 secondi✅ 4/8/12 secondi
orientation✅ landscape/portrait❌
size✅ small/large✅ 720x1280/1280x720/1024x1792/1792x1024
image_urls✅ più immagini✅ solo la prima immagine
character_url✅❌
callback_url✅✅

​
Callback asincrono

Poiché la generazione video tramite Sora Videos Generation API richiede un tempo relativamente lungo (circa 1-2 minuti), se l’API non risponde rapidamente la connessione HTTP rimane aperta, causando un consumo aggiuntivo di risorse di sistema. Per questo motivo l’API supporta anche callback asincroni. Il flusso è: il client invia la richiesta specificando un campo callback_url; l’API risponde immediatamente con un risultato contenente il campo task_id che identifica il task. Quando il task è completato, il risultato della generazione video viene inviato tramite POST JSON all’URL callback_url specificato dal client, includendo anche il campo task_id per associare il risultato al task. Vediamo un esempio pratico. Innanzitutto, il webhook callback è un servizio che può ricevere richieste HTTP; lo sviluppatore deve sostituire con l’URL del proprio server HTTP. Per comodità, qui usiamo un sito pubblico di esempio per webhook https://webhook.site/, aprendo il sito si ottiene un URL webhook, come mostrato: Copiare questo URL per usarlo come webhook, ad esempio https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa. Poi impostiamo il campo callback_url con questo URL e inseriamo gli altri parametri, come mostrato:

Cliccando “Run” si ottiene subito un risultato: 
{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}
Dopo qualche istante, su https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa si può osservare il risultato della generazione video, come mostrato: Contenuto: 
{
    "success": true,
    "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea",
    "trace_id": "fb751e1e-4705-49ea-9fd4-5024b7865ea2",
    "data": [
        {
            "id": "sora-2:task_01k777hjrbfrgs2060q5zvf2a5",
            "video_url": "https://filesystem.site/gptimage/vg-assets/assets%2Ftask_01k777hjrbfrgs2060q5zvf2a5%2Ftask_01k777hjrbfrgs2060q5zvf2a5_genid_b8e2e5d1-a579-49ca-a21c-cb3869685cce_25_10_10_14_15_147334%2Fvideos%2F00000%2Fsrc.mp4?st=2025-10-10T12%3A38%3A49Z&se=2025-10-16T13%3A38%3A49Z&sks=b&skt=2025-10-10T12%3A38%3A49Z&ske=2025-10-16T13%3A38%3A49Z&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skoid=aa5ddad1-c91a-4f0a-9aca-e20682cc8969&skv=2019-02-02&sv=2018-11-09&sr=b&sp=r&spr=https%2Chttp&sig=p4aMqXqkP%2FI1IhOVGCB9JL8vUUvfNBBF12ESpKhKXOk%3D&az=oaivgprodscus",
            "state": "succeeded"
        }
    ]
}
Come si vede, il risultato contiene il campo task_id e altri campi simili a quelli sopra, permettendo di associare il risultato al task tramite ID.

​
Gestione errori

In caso di errore durante la chiamata API, l’API restituisce un codice e un messaggio di errore corrispondenti. Ad esempio:
  • 400 token_mismatched: richiesta errata, probabilmente parametri mancanti o non validi.
  • 400 api_not_implemented: richiesta errata, probabilmente parametri mancanti o non validi.
  • 401 invalid_token: non autorizzato, token di autorizzazione mancante o non valido.
  • 429 too_many_requests: troppe richieste, superato il limite di velocità.
  • 500 api_error: errore interno del server.

​
Esempio di risposta di errore

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

​
Conclusione

Con questo documento avete appreso come utilizzare l’API di Generazione Video Sora per generare video inserendo prompt e immagini di riferimento. Speriamo che questa guida vi aiuti a integrare e utilizzare al meglio l’API. Per qualsiasi domanda, non esitate a contattare il nostro team di supporto tecnico.