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

​
Processo di Richiesta

Per utilizzare l’API, è necessario prima andare alla pagina corrispondente Sora Videos Generation API per richiedere il servizio corrispondente. Una volta entrati nella pagina, fare clic sul pulsante “Acquire”, come mostrato nell’immagine: Se non si è ancora effettuato il login o la registrazione, si verrà automaticamente reindirizzati alla pagina di accesso per invitare a registrarsi e accedere. Dopo aver effettuato il login o la registrazione, si tornerà automaticamente alla pagina corrente. Alla prima richiesta, verrà offerto un credito gratuito, che consente di utilizzare gratuitamente l’API.

​
Utilizzo di Base

Per prima cosa, è importante comprendere il modo di utilizzo di base, che consiste nell’immettere 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:

Si può notare che abbiamo impostato le intestazioni della richiesta, tra cui:
  • 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 sora-2, sora-2-pro. Attualmente, sora-2 e sora-2-pro consentono di scegliere autonomamente i parametri size e duration, dove sora-2-pro supporta video di 25s, mentre sora-2 supporta solo video di 10 e 15 secondi.
  • size: la chiarezza del compito di generazione video, che può essere small o large.
  • image_urls: l’array di link a immagini di riferimento o codifiche Base64 da caricare.
  • duration: la durata del compito di generazione video, che può essere 10s, 15s o 25s; attualmente solo sora-2-pro supporta 25s.
  • character_start/character_end: la posizione di inizio e fine del personaggio nell’immagine (0-1), utilizzata per controllare la posizione del soggetto.
  • orientation: l’orientamento dell’immagine, supporta landscape, portrait, square.
  • prompt: la parola chiave.
  • callback_url: l’URL per ricevere il risultato.
Dopo aver effettuato le scelte, si può notare che a destra è stato generato il codice corrispondente, come mostrato nell’immagine:

Facendo clic sul pulsante “Try” è possibile effettuare un test, come mostrato nell’immagine sopra, e si ottiene 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 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 del compito di generazione video attuale.
    • video_url, il link al video del compito di generazione video attuale.
    • state, lo stato del compito di generazione video attuale.
Si può notare che abbiamo ottenuto informazioni soddisfacenti sul video; dobbiamo solo ottenere il video Sora generato dall’indirizzo del 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/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"
}'

​
Compito di Generazione Video da Immagine

Se si desidera generare un compito di video da immagine, il parametro image_urls deve essere fornito con i link delle immagini di riferimento, per specificare i seguenti contenuti:
  • image_urls: l’array di link delle immagini di riferimento utilizzate per questo compito di generazione video.
Esempio di compilazione:

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

Il 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)
Facendo clic 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://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"
    }
  ]
}
Si può vedere che l’effetto generato è un video creato da immagini, il risultato è simile a quanto sopra.

​
Compito di generazione video del personaggio

Se si desidera un compito di generazione video del personaggio, 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à, quindi si possono specificare i seguenti contenuti:
  • 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:

Il 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ò scoprire 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://filesystem.site/cdn/20251101/bee4eeeb4c4660b46dac4548a1ffbc.mp4",
      "state": "succeeded"
    }
  ]
}
Si può vedere che l’effetto generato è un video di generazione del personaggio, il risultato è simile a quanto sopra.

​
Callback asincrona

Poiché il tempo di generazione dell’API Sora Videos Generation è relativamente lungo, circa 1-2 minuti, se l’API non risponde per lungo tempo, la richiesta HTTP manterrà la connessione, causando un consumo aggiuntivo di risorse di sistema, quindi questa API offre anche supporto per callback asincroni. Il flusso complessivo è: quando il client avvia la richiesta, specifica un campo callback_url aggiuntivo, dopo che il client ha avviato 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 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 Webhook https://webhook.site/, aprendo questo sito si ottiene un URL Webhook, come mostrato nell’immagine: Copia questo URL e può essere utilizzato come Webhook, l’esempio qui è https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa. Successivamente, possiamo impostare il campo callback_url su questo URL Webhook, mentre inseriamo i parametri corrispondenti, i contenuti specifici sono mostrati nell’immagine:

Cliccando su esegui, si può scoprire che si ottiene immediatamente un risultato, come segue: 
{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}
Dopo un momento, possiamo osservare il risultato della generazione della canzone su https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa, come mostrato nell’immagine: Il contenuto è il seguente: 
```json
{
    "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"
        }
    ]
}
Si può vedere che nel risultato c’è un campo task_id, gli altri campi sono simili a quelli sopra, e attraverso 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 compreso come utilizzare l’API Sora Videos Generation per generare video tramite input 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.