Hoppa till huvudinnehåll
Sora Tasks API:s huvudfunktion är att genom att ange det uppdrag ID som genererats av Sora Videos Generation API för att kontrollera statusen för det uppdraget. Detta dokument kommer att ge en detaljerad beskrivning av Sora Tasks API:s integrationsanvisningar, vilket hjälper dig att enkelt integrera och fullt utnyttja denna APIs kraftfulla funktioner. Genom Sora Tasks API kan du enkelt kontrollera statusen för uppdrag som utförs av Sora Videos Generation API.

​
Ansökningsprocess

För att använda Sora Tasks API måste du först gå till ansökningssidan Sora Videos Generation API för att ansöka om den aktuella tjänsten, och sedan kopiera Sora Videos Generation API:s uppdrag ID, som visas i bilden:

Slutligen går du till Tasks API-sidan Sora Tasks API för att ansöka om den aktuella tjänsten. När du kommer till sidan klickar du på knappen “Acquire”, som visas i bilden: Ansökningssidan Om du inte har loggat in eller registrerat dig kommer du automatiskt att omdirigeras till inloggningssidan för att registrera dig och logga in. Efter att du har loggat in eller registrerat dig kommer du automatiskt att återvända till den aktuella sidan. Vid första ansökan kommer det att finnas en gratis kvot som ges, så att du kan använda denna API gratis.

​
Begärningsexempel

Sora Tasks API kan användas för att kontrollera resultaten från Sora Videos Generation API. För information om hur man använder Sora Videos Generation API, se dokumentet Sora Videos Generation API. Vi tar ett exempel med ett uppdrag ID som returnerats av Sora Videos Generation API och visar hur man använder denna API. Anta att vi har ett uppdrag ID: b8976e18-32dc-4718-9ed8-1ea090fcb6ea, och vi visar hur man gör detta genom att skicka in ett uppdrag ID.

​
Uppdragsexempelbild

​
Ställ in begärningshuvuden och begärningskropp

Begärningshuvuden inkluderar:
  • accept: specificera att du tar emot svar i JSON-format, här anges som application/json.
  • authorization: nyckeln för att anropa API:t, som kan väljas direkt efter ansökan.
Begärningskropp inkluderar:
  • id: det uppladdade uppdrag ID:t.
  • action: hur uppdraget ska hanteras.
Inställningarna visas i bilden nedan:

​
Kodexempel

Det kan noteras att olika språkets kod redan har genererats automatiskt på höger sida av sidan, som visas i bilden:

Några kodexempel är som följer:

​
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)

​
Svarsexempel

När begäran lyckas kommer API:t att returnera detaljerad information om detta videouppdrag. Till exempel: 
{
  "_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": "cat running on the river",
    "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"
      }
    ]
  }
}
Det returnerade resultatet innehåller flera fält, där request-fältet är begärningskroppen som användes för att initiera uppdraget, medan response-fältet är svaret som returneras efter att uppdraget har slutförts. Fälten beskrivs nedan.
  • id, ID:t för att generera detta videouppdrag, används för att unikt identifiera detta videogenereringsuppdrag.
  • request, begärningsinformationen i videouppdraget.
  • response, svarsinformationen i videouppdraget.

​
Batchfrågeoperation

Detta är för att fråga detaljer om videouppdrag för flera uppdrag ID:n, och till skillnad från ovanstående måste action väljas som retrieve_batch. Begärningskropp inkluderar:
  • ids: en array av uppladdade uppdrag ID:n.
  • action: hur uppdraget ska hanteras.
Inställningarna visas i bilden nedan:

​
Kodexempel

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

部分代码示例如下：

​
响应示例

请求成功后，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": "cat running on the river",
        "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": "cat running on the river",
        "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)

​
Felhantering

När du anropar API:et, om du stöter på fel, kommer API:et att returnera motsvarande felkod och information. Till exempel:
  • 400 token_mismatched: Felaktig begäran, möjligtvis på grund av saknade eller ogiltiga parametrar.
  • 400 api_not_implemented: Felaktig begäran, möjligtvis på grund av saknade eller ogiltiga parametrar.
  • 401 invalid_token: Obefogad, ogiltig eller saknad auktoriseringstoken.
  • 429 too_many_requests: För många begärningar, du har överskridit hastighetsgränsen.
  • 500 api_error: Internt serverfel, något gick fel på servern.

​
Exempel på felrespons

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

​
Slutsats

Genom detta dokument har du fått en förståelse för hur du använder Sora Tasks API för att hämta detaljerad information om enskilda eller batchvideouppgifter. Vi hoppas att detta dokument kan hjälpa dig att bättre integrera och använda API:et. Om du har några frågor, tveka inte att kontakta vårt tekniska supportteam.