Перейти до основного вмісту
Основна функція Sora Tasks API полягає в тому, щоб за допомогою введеного ID завдання, згенерованого Sora Videos Generation API, перевіряти стан виконання цього завдання. Цей документ детально описує інструкції з інтеграції Sora Tasks API, щоб допомогти вам легко інтегрувати та повністю використовувати потужні можливості цього API. За допомогою Sora Tasks API ви можете легко реалізувати запити на перевірку стану виконання завдань Sora Videos Generation API.

​
Процес подачі заявки

Щоб використовувати Sora Tasks API, спочатку потрібно перейти на сторінку подачі заявки Sora Videos Generation API та подати заявку на відповідну послугу, а потім скопіювати ID завдання Sora Videos Generation API, як показано на малюнку:

Нарешті, перейдіть на сторінку Tasks API Sora Tasks API та подайте заявку на відповідну послугу, після входу на сторінку натисніть кнопку «Acquire», як показано на малюнку: Сторінка подачі заявки Якщо ви ще не увійшли в систему або не зареєструвалися, вас автоматично перенаправлять на сторінку входу, щоб запросити вас зареєструватися та увійти. Після входу або реєстрації ви автоматично повернетеся на поточну сторінку. При першій подачі заявки вам буде надано безкоштовний ліміт, який дозволяє безкоштовно використовувати цей API.

​
Приклад запиту

Sora Tasks API можна використовувати для перевірки результатів Sora Videos Generation API. Щоб дізнатися, як використовувати Sora Videos Generation API, зверніться до документа Sora Videos Generation API. Розглянемо приклад з ID завдання, повернутим сервісом Sora Videos Generation API. Припустимо, у нас є ID завдання: b8976e18-32dc-4718-9ed8-1ea090fcb6ea, далі демонструємо, як передати цей ID.

​
Приклад завдання

​
Налаштування заголовків запиту та тіла запиту

Request Headers включає:
  • accept: вказує на прийняття відповіді у форматі JSON, тут вказується application/json.
  • authorization: ключ для виклику API, після подачі заявки можна вибрати з випадаючого списку.
Request Body включає:
  • id: ID завдання, яке потрібно завантажити.
  • action: спосіб виконання дії над завданням.
Налаштування, як показано на малюнку:

​
Приклад коду

Можна помітити, що на правій стороні сторінки автоматично згенеровано код на різних мовах, як показано на малюнку:

Деякі приклади коду наведені нижче:

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

​
Приклад відповіді

Після успішного запиту API поверне детальну інформацію про це відеозавдання. Наприклад: 
{
  "_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"
      }
    ]
  }
}
У відповіді є кілька полів, поле request - це тіло запиту, яке було надіслано для створення завдання, а поле response - це тіло відповіді, яке повертається після завершення завдання. Ось опис полів.
  • id, ID, що генерує це відеозавдання, використовується для унікальної ідентифікації цього завдання на створення відео.
  • request, інформація про запит у відеозавданні.
  • response, інформація про відповідь у відеозавданні.

​
Пакетний запит

Це запит для перевірки деталей відеозавдань для кількох ID завдань, на відміну від попереднього, тут потрібно вибрати action як retrieve_batch. Request Body включає:
  • ids: масив ID завдань, які потрібно завантажити.
  • action: спосіб виконання дії над завданнями.
Налаштування, як показано на малюнку:

​
Приклад коду

Можна помітити, що на правій стороні сторінки автоматично згенеровано код для різних мов, як показано на малюнку:

Приклади коду наведені нижче:

​
Приклад відповіді

Після успішного запиту 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)

​
Обробка помилок

При виклику API, якщо виникає помилка, API поверне відповідний код помилки та інформацію. Наприклад:
  • 400 token_mismatched: Неправильний запит, можливо, через відсутні або недійсні параметри.
  • 400 api_not_implemented: Неправильний запит, можливо, через відсутні або недійсні параметри.
  • 401 invalid_token: Неавторизовано, недійсний або відсутній токен авторизації.
  • 429 too_many_requests: Занадто багато запитів, ви перевищили ліміт запитів.
  • 500 api_error: Внутрішня помилка сервера, щось пішло не так на сервері.

​
Приклад відповіді на помилку

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

​
Висновок

За допомогою цього документа ви дізналися, як використовувати Sora Tasks API для запиту окремих або пакетних відеозавдань з усіма конкретними деталями. Сподіваємося, що цей документ допоможе вам краще інтегрувати та використовувати цей API. Якщо у вас є будь-які питання, будь ласка, звертайтеся до нашої команди технічної підтримки.