Vai al contenuto principale
La principale funzionalità dell’API Sora Tasks è quella di interrogare lo stato di esecuzione di un’attività utilizzando l’ID dell’attività generato dall’API Sora Videos Generation. Questo documento fornirà una descrizione dettagliata dell’integrazione dell’API Sora Tasks, aiutandoti a integrare facilmente e sfruttare appieno le potenti funzionalità di questa API. Con l’API Sora Tasks, puoi facilmente interrogare lo stato di esecuzione delle attività dell’API Sora Videos Generation.

​
Processo di richiesta

Per utilizzare l’API Sora Tasks, è necessario prima andare alla pagina di richiesta Sora Videos Generation API per richiedere il servizio corrispondente, quindi copiare l’ID dell’attività dell’API Sora Videos Generation, come mostrato nell’immagine:

Infine, accedi alla pagina dell’API Tasks Sora Tasks API per richiedere il servizio corrispondente. Una volta entrato nella pagina, fai clic sul pulsante “Acquire”, come mostrato nell’immagine: Pagina di richiesta Se non hai ancora effettuato il login o la registrazione, verrai automaticamente reindirizzato alla pagina di login che ti invita a registrarti e accedere. Dopo aver effettuato il login o la registrazione, verrai automaticamente riportato alla pagina corrente. Alla prima richiesta, verrà offerto un credito gratuito, che ti consente di utilizzare gratuitamente questa API.

​
Esempio di richiesta

L’API Sora Tasks può essere utilizzata per interrogare i risultati dell’API Sora Videos Generation. Per informazioni su come utilizzare l’API Sora Videos Generation, fare riferimento al documento Sora Videos Generation API. Prendiamo come esempio un ID di attività restituito dal servizio Sora Videos Generation API e dimostriamo come utilizzare questa API. Supponiamo di avere un ID di attività: b8976e18-32dc-4718-9ed8-1ea090fcb6ea, e ora dimostriamo come passare un ID di attività.

​
Esempio di attività

​
Impostazione dell’intestazione della richiesta e del corpo della richiesta

Request Headers includono:
  • accept: specifica di ricevere la risposta in formato JSON, qui impostato su application/json.
  • authorization: la chiave per chiamare l’API, che può essere selezionata direttamente dopo la richiesta.
Request Body include:
  • id: l’ID dell’attività caricata.
  • action: il modo in cui operare sull’attività.
Impostato come mostrato nell’immagine seguente:

​
Esempio di codice

Si può notare che sul lato destro della pagina sono già stati generati automaticamente vari codici in diverse lingue, come mostrato nell’immagine:

Alcuni esempi di codice sono i seguenti:

​
CURL

curl -X POST 'https://api.acedata.cloud/sora/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea",
  "action": "retrieve"
}'

​
Python

import requests

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

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

payload = {
    "id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea",
    "action": "retrieve"
}

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

​
Esempio di risposta

Se la richiesta ha successo, l’API restituirà i dettagli di questa attività video. Ad esempio: 
{
  "_id": "68e914aa550a4144a5788305",
  "id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea",
  "api_id": "54aed96c-0346-4227-8c99-9780247a7ffd",
  "application_id": "f10c04c2-2273-4463-bd3f-593d71b75ac8",
  "created_at": 1760105642.045,
  "credential_id": "4e6e181d-f320-4874-8d80-fc2253b40b7e",
  "request": {
    "size": "large",
    "duration": 15,
    "orientation": "landscape",
    "prompt": "gatto che corre sul fiume",
    "model": "sora-2",
    "image_urls": [
      "https://cdn.acedata.cloud/11wfp4.png"
    ],
    "callback_url": "https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa"
  },
  "trace_id": "fb751e1e-4705-49ea-9fd4-5024b7865ea2",
  "type": "videos",
  "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
  "response": {
    "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"
      }
    ]
  }
}
Il risultato restituito contiene diversi campi, il campo request è il corpo della richiesta inviato per avviare l’attività, mentre il campo response è il corpo della risposta restituito dopo il completamento dell’attività. La descrizione dei campi è la seguente.
  • id, l’ID dell’attività video generata, utilizzato per identificare univocamente questa attività di generazione video.
  • request, informazioni sulla richiesta nell’attività video.
  • response, informazioni sulla risposta nell’attività video.

​
Operazione di query in batch

Questa è per interrogare i dettagli delle attività video per più ID di attività, a differenza di quanto sopra, è necessario selezionare l’azione come retrieve_batch. Request Body include:
  • ids: array degli ID delle attività caricate.
  • action: il modo in cui operare sull’attività.
Impostato come mostrato nell’immagine seguente:

​
Esempio di codice

可以发现，在页面右侧已经自动生成了各种语言的代码，如图所示：

部分代码示例如下：

​
响应示例

请求成功后，API 将返回此次所有批量视频任务的具体详情信息。例如： 
{
  "items": [
    {
      "_id": "68e914aa550a4144a5788305",
      "id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea",
      "api_id": "54aed96c-0346-4227-8c99-9780247a7ffd",
      "application_id": "f10c04c2-2273-4463-bd3f-593d71b75ac8",
      "created_at": 1760105642.045,
      "credential_id": "4e6e181d-f320-4874-8d80-fc2253b40b7e",
      "request": {
        "size": "large",
        "duration": 15,
        "orientation": "landscape",
        "prompt": "gatto che corre sul fiume",
        "model": "sora-2",
        "image_urls": [
          "https://cdn.acedata.cloud/11wfp4.png"
        ],
        "callback_url": "https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa"
      },
      "trace_id": "fb751e1e-4705-49ea-9fd4-5024b7865ea2",
      "type": "videos",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "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"
          }
        ]
      }
    },
    {
      "_id": "68e914aa550a4144a5788305",
      "id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea",
      "api_id": "54aed96c-0346-4227-8c99-9780247a7ffd",
      "application_id": "f10c04c2-2273-4463-bd3f-593d71b75ac8",
      "created_at": 1760105642.045,
      "credential_id": "4e6e181d-f320-4874-8d80-fc2253b40b7e",
      "request": {
        "size": "large",
        "duration": 15,
        "orientation": "landscape",
        "prompt": "gatto che corre sul fiume",
        "model": "sora-2",
        "image_urls": [
          "https://cdn.acedata.cloud/11wfp4.png"
        ],
        "callback_url": "https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa"
      },
      "trace_id": "fb751e1e-4705-49ea-9fd4-5024b7865ea2",
      "type": "videos",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "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"
          }
        ]
      }
    }
  ],
  "count": 2
}
返回结果一共有多个字段，其中items是包含了批量视频任务的具体详情信息，每个视频任务的具体信息与上文的字段一样，字段信息如下。
  • items，批量视频任务的所有具体详情信息。它是一个数组，每个数组的元素和上文查询单个任务的返回结果格式是一样的。
  • count，此处批量查询视频任务的个数。

​
CURL

curl -X POST 'https://api.acedata.cloud/sora/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "ids": ["b8976e18-32dc-4718-9ed8-1ea090fcb6ea","b8976e18-32dc-4718-9ed8-1ea090fcb6ea"],
  "action": "retrieve_batch"
}'

​
Python

import requests

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

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

payload = {
    "ids": ["b8976e18-32dc-4718-9ed8-1ea090fcb6ea","b8976e18-32dc-4718-9ed8-1ea090fcb6ea"],
    "action": "retrieve_batch"
}

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

​
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 Tasks per interrogare informazioni dettagliate su singoli o batch di compiti video. 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.