الانتقال إلى المحتوى الرئيسي
الوظيفة الرئيسية لواجهة برمجة تطبيقات مهام Sora هي استعلام حالة تنفيذ المهمة من خلال إدخال معرف المهمة الذي تم إنشاؤه بواسطة واجهة برمجة تطبيقات إنشاء مقاطع فيديو Sora. ستتناول هذه الوثيقة تفاصيل تكامل واجهة برمجة تطبيقات مهام Sora، لمساعدتك على دمجها بسهولة والاستفادة الكاملة من القوة الكبيرة لهذه الواجهة. من خلال واجهة برمجة تطبيقات مهام Sora، يمكنك بسهولة استعلام حالة تنفيذ المهام من واجهة برمجة تطبيقات إنشاء مقاطع فيديو Sora.

​
عملية التقديم

لاستخدام واجهة برمجة تطبيقات مهام Sora، يجب أولاً زيارة صفحة التقديم واجهة برمجة تطبيقات إنشاء مقاطع فيديو Sora لتقديم طلب الخدمة المناسبة، ثم نسخ معرف المهمة من واجهة برمجة تطبيقات إنشاء مقاطع فيديو Sora، كما هو موضح في الصورة:

أخيرًا، انتقل إلى صفحة واجهة برمجة تطبيقات المهام واجهة برمجة تطبيقات مهام Sora لتقديم طلب الخدمة المناسبة، بعد دخول الصفحة، انقر على زر “Acquire”، كما هو موضح في الصورة: صفحة التقديم إذا لم تكن قد قمت بتسجيل الدخول أو التسجيل بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، بعد تسجيل الدخول أو التسجيل، سيتم العودة تلقائيًا إلى الصفحة الحالية. عند التقديم لأول مرة، سيكون هناك حد مجاني متاح، يمكنك استخدام هذه الواجهة مجانًا.

​
مثال على الطلب

يمكن استخدام واجهة برمجة تطبيقات مهام Sora لاستعلام نتائج واجهة برمجة تطبيقات إنشاء مقاطع فيديو Sora. لمزيد من المعلومات حول كيفية استخدام واجهة برمجة تطبيقات إنشاء مقاطع فيديو Sora، يرجى الرجوع إلى الوثيقة واجهة برمجة تطبيقات إنشاء مقاطع فيديو Sora. سنأخذ مثالاً على معرف المهمة الذي تم إرجاعه من خدمة واجهة برمجة تطبيقات إنشاء مقاطع فيديو Sora، لنوضح كيفية استخدام هذه الواجهة. لنفترض أن لدينا معرف مهمة: b8976e18-32dc-4718-9ed8-1ea090fcb6ea، وسنوضح بعد ذلك كيفية تمرير معرف المهمة.

​
مثال على المهمة

​
إعداد رأس الطلب وجسم الطلب

Request Headers تشمل:
  • accept: تحديد استلام استجابة بتنسيق JSON، هنا يتم ملؤه بـ application/json.
  • authorization: مفتاح استدعاء الواجهة، يمكن اختياره مباشرة بعد التقديم.
Request Body تشمل:
  • 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)

​
مثال على الاستجابة

بعد نجاح الطلب، ستقوم الواجهة بإرجاع تفاصيل مهمة الفيديو هنا. على سبيل المثال: 
{
  "_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: معرف المهمة التي تم إنشاؤها لهذا الفيديو، يستخدم لتحديد هذه المهمة بشكل فريد.
  • request: استعلام معلومات الطلب في مهمة الفيديو.
  • response: استعلام معلومات الاستجابة في مهمة الفيديو.

​
عمليات الاستعلام الجماعي

هذا مخصص لاستعلام تفاصيل مهام الفيديو لعدة معرفات مهام، وما يميز ذلك هو أنه يجب اختيار action كـ retrieve_batch. Request Body تشمل:
  • ids: مصفوفة معرفات المهام المرفوعة.
  • 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": "قط يجري على النهر",
        "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": "قط يجري على النهر",
        "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)

​
معالجة الأخطاء

عند استدعاء واجهة برمجة التطبيقات، إذا واجهت خطأ، ستقوم واجهة برمجة التطبيقات بإرجاع رمز الخطأ والمعلومات المناسبة. على سبيل المثال:
  • 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 للاستعلام عن تفاصيل المهام الفردية أو دفعات الفيديو. نأمل أن تساعدك هذه الوثيقة في التوصيل والاستخدام الأفضل لهذه الواجهة. إذا كان لديك أي استفسارات، فلا تتردد في الاتصال بفريق الدعم الفني لدينا.