Sora Videos Generation API Integrazione Istruzioni

Questo documento presenterà le istruzioni per l’integrazione dell’API Sora Videos Generation, attraverso la quale è possibile inserire parametri personalizzati per generare video ufficiali di Sora. Questa API supporta due modalità di versione:

Versione 1 (Modalità Classica): supporta duration (10/15/25 secondi), orientation (orizzontale/verticale), size (bassa/alta definizione), immagini di riferimento image_urls, link ### character_url e altri parametri.
Versione 2 (Modalità Partner): supporta seconds (4/8/12 secondi), risoluzione a livello di pixel size (ad esempio 1280x720), immagini di riferimento input_reference e altri parametri.

Procedura di Richiesta

Per utilizzare l’API Sora Videos Generation, prima di tutto vai al Pannello di Controllo 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 inviterà 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 ti darà un credito gratuito, per un’esperienza senza costi; quando il credito è esaurito, puoi ricaricare il saldo generale nel pannello di controllo.

📘 Documentazione Completa: Sora Videos Generation API →

Utilizzo di Base (Versione 1)

Per prima cosa, è importante comprendere il modo di utilizzo di base della Versione 1, che consiste nell’inserire la parola chiave prompt, un array di link a immagini di riferimento image_urls e il modello model, per ottenere il risultato elaborato; i dettagli specifici sono i seguenti:

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

accept: il formato di risposta desiderato, 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, supporta sora-2 (modalità standard) e sora-2-pro (modalità HD). Il sora-2-pro supporta video con duration di 25 secondi, mentre il sora-2 supporta solo 10 e 15 secondi.
size: la qualità del video, small per qualità standard, large per qualità HD (solo Versione 1).
duration: la durata del video, supporta 10, 15, 25 secondi, dove 25 secondi è supportato solo da sora-2-pro (solo Versione 1).
orientation: l’orientamento del video, supporta landscape (orizzontale), portrait (verticale) (solo Versione 1).
image_urls: array di link a immagini di riferimento, utilizzato per generare video (solo Versione 1).
character_url: link ###, non possono apparire persone reali nel video (solo Versione 1).
character_start/character_end: secondi di inizio e fine dell’apparizione del personaggio, con un intervallo di differenza di 1-3 secondi (solo Versione 1).
prompt: parola chiave (obbligatoria).
callback_url: URL per il callback asincrono dei risultati.
async: opzionale, impostato su true per restituire immediatamente task_id, senza necessità di fornire callback_url, successivamente puoi ottenere i risultati tramite polling dell’interfaccia di query del compito corrispondente.
version: versione API, "1.0" (predefinita) o "2.0".

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

Cliccando sul pulsante “Try” puoi effettuare un test, come mostrato nell’immagine sopra, e abbiamo ottenuto 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://platform.cdn.acedata.cloud/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 diversi campi, descritti come segue:

success, lo stato attuale del compito di generazione video.
task_id, l’ID del compito di generazione video attuale.
trace_id, l’ID di tracciamento del compito di generazione video attuale.
data, l’elenco dei risultati del compito di generazione video attuale.
- id, l’ID del video generato dal compito di generazione video attuale.
- video_url, il link al video generato dal compito di generazione video attuale.
- state, lo stato attuale del compito di generazione video.

Possiamo vedere che abbiamo ottenuto informazioni soddisfacenti sul video, e dobbiamo solo utilizzare l’indirizzo del link video in data per ottenere il video Sora generato. Inoltre, se desideri generare il codice di integrazione corrispondente, puoi semplicemente copiarlo, ad esempio il codice CURL è il seguente:

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": "gatto che corre sul fiume",
  "model": "sora-2"
}'

Compito di Generazione Video da Immagini (Versione 1)

Se desideri eseguire un compito di generazione video da immagini, prima di tutto il parametro image_urls deve contenere i link delle immagini di riferimento, in modo da specificare i seguenti contenuti:

image_urls: array di link delle immagini di riferimento utilizzate per il compito di generazione video. Nota che non è possibile inviare immagini di persone reali con volti, altrimenti il compito potrebbe fallire.

Esempio di compilazione:

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

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": "gatto che corre sul fiume",
    "model": "sora-2",
    "image_urls": ["https://cdn.acedata.cloud/11wfp4.png"]
}

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

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

{
  "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://platform.cdn.acedata.cloud/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"
    }
  ]
}

Si può vedere che l’effetto generato è un video creato da immagini, il risultato è simile a quanto sopra.

Compito di generazione video di personaggi (Versione 1)

Se si desidera eseguire un compito di generazione video di personaggi, prima il parametro character_url deve essere fornito con il link video necessario per creare il personaggio, si prega di notare che nel video non devono apparire persone reali, altrimenti fallirà, si può specificare il seguente contenuto:

character_url: link video necessario per creare il personaggio, si prega di notare che nel video non devono apparire persone reali, altrimenti fallirà.

Esempio di compilazione:

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

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": "gatto che corre sul fiume",
    "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)

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

{
  "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://platform.cdn.acedata.cloud/20251101/bee4eeeb4c4660b46dac4548a1ffbc.mp4",
      "state": "succeeded"
    }
  ]
}

Si può vedere che l’effetto generato è un video di generazione di personaggi, il risultato è simile a quanto sopra.

Modalità Versione 2.0

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

Descrizione dei parametri della Versione 2.0

Parametro	Tipo	Obbligatorio	Descrizione
`version`	string	Sì	Impostato su `"2.0"`
`prompt`	string	Sì	Parola chiave per generare il video
`model`	string	No	`sora-2` (predefinito) o `sora-2-pro`
`duration`	integer	No	Durata video: `4` (predefinito), `8`, `12` secondi
`size`	string	No	Risoluzione: `720x1280` (predefinito), `1280x720`, `1024x1792`, `1792x1024`
`image_urls`	array	No	Array di URL di immagini di riferimento, utilizzare solo la prima immagine, le dimensioni dell’immagine devono corrispondere al parametro `size`
`callback_url`	string	No	URL di callback asincrono

Esempio di 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": "gatto che corre sul fiume",
  "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": "gatto che corre sul fiume",
    "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: 'gatto che corre sul fiume',
    model: 'sora-2',
    seconds: 8,
    size: '1280x720'
  })
});
const data = await response.json();
console.log(data);

Il formato del risultato restituito è lo stesso 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"
    }
  ]
}

Utilizzo di immagini di riferimento (Versione 2.0)

In modalità Versione 2.0, è possibile passare immagini di riferimento tramite il parametro image_urls per guidare la generazione del video (utilizzando 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": "una persona che cammina attraverso un bellissimo giardino",
    "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: Le dimensioni delle immagini di riferimento devono essere coerenti con il parametro size, ad esempio se size è 1280x720, le dimensioni dell’immagine di riferimento devono essere 1280×720.

Confronto dei parametri tra Versione 1.0 e Versione 2.0

Parametro	Versione 1.0	Versione 2.0
`version`	1.0 (predefinito)	2.0
`prompt`	✅	✅
`model`	✅ sora-2 / sora-2-pro	✅ sora-2 / sora-2-pro
`duration`	✅ 10/15/25 secondi	✅ 4/8/12 secondi
`orientation`	✅ paesaggio/ritratto	❌
`size`	✅ piccolo/grande	✅ 720x1280/1280x720/1024x1792/1792x1024
`image_urls`	✅ più immagini di riferimento	✅ utilizza solo la prima
`character_url`	✅	❌
`callback_url`	✅	✅

Callback asincrona

Poiché il tempo di generazione dell’API Sora 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, includendo anche il campo task_id, in modo che il risultato del compito possa essere associato 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/eb238c4f-da3b-47a5-a922-a93aa5405daa. Successivamente, possiamo impostare il campo callback_url su questo URL Webhook, riempiendo i parametri corrispondenti, come mostrato nell’immagine:

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

{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}

Dopo un momento, possiamo osservare il risultato del video generato su https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa, come mostrato nell’immagine:

Il contenuto è il seguente:

{
    "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://platform.cdn.acedata.cloud/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"
        }
    ]
}

Possiamo vedere che nel risultato c’è un campo task_id, gli altri campi sono simili a quelli sopra, tramite questo campo è possibile realizzare l’associazione del compito.

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 già compreso come utilizzare l’API di generazione video Sora per generare video tramite l’inserimento di parole chiave e immagini di riferimento. 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

Coding

Sora Videos Generation API Integrazione Istruzioni

Procedura di Richiesta

Utilizzo di Base (Versione 1)

Compito di Generazione Video da Immagini (Versione 1)

Compito di generazione video di personaggi (Versione 1)

Modalità Versione 2.0

Descrizione dei parametri della Versione 2.0

Esempio di base

Utilizzo di immagini di riferimento (Versione 2.0)

Confronto dei parametri tra Versione 1.0 e Versione 2.0

Callback asincrona

Gestione degli errori

Esempio di risposta di errore

Conclusione

​Procedura di Richiesta

​Utilizzo di Base (Versione 1)

​Compito di Generazione Video da Immagini (Versione 1)

​Compito di generazione video di personaggi (Versione 1)

​Modalità Versione 2.0

​Descrizione dei parametri della Versione 2.0

​Esempio di base

​Utilizzo di immagini di riferimento (Versione 2.0)

​Confronto dei parametri tra Versione 1.0 e Versione 2.0

​Callback asincrona

​Gestione degli errori

​Esempio di risposta di errore

​Conclusione

Procedura di Richiesta

Utilizzo di Base (Versione 1)

Compito di Generazione Video da Immagini (Versione 1)

Compito di generazione video di personaggi (Versione 1)

Modalità Versione 2.0

Descrizione dei parametri della Versione 2.0

Esempio di base

Utilizzo di immagini di riferimento (Versione 2.0)

Confronto dei parametri tra Versione 1.0 e Versione 2.0

Callback asincrona

Gestione degli errori

Esempio di risposta di errore

Conclusione