تعليمات تكامل واجهة API للاستعلام عن مهام Maestro

تتمثل الوظيفة الرئيسية لواجهة API للاستعلام عن مهام Maestro في الاستعلام عن حالة تنفيذ المهمة ونتيجتها النهائية من خلال معرّف المهمة الذي تُرجعه واجهة API لإنشاء فيديو Maestro (POST /maestro/videos). ستقدم هذه الوثيقة تعليمات تكامل واجهة API للاستعلام عن مهام Maestro بالتفصيل. نظرًا لأن إنشاء الفيديو مهمة غير متزامنة، يجب استخدام هذه الواجهة للاستعلام الدوري عن التقدم والفيديو النهائي بعد الإرسال، والاستعلام الدوري مجاني ولا يستهلك النقاط. POST https://api.acedata.cloud/maestro/tasks

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

لاستخدام واجهة API للاستعلام عن مهام Maestro، انتقل أولاً إلى وحدة تحكم Ace Data Cloud للحصول على API Token الخاص بك، واحتفظ به للاستخدام لاحقًا.

إذا لم تكن قد سجلت الدخول أو أنشأت حسابًا بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك إلى التسجيل وتسجيل الدخول، وستعود تلقائيًا إلى الصفحة الحالية بعد الإكمال. يمكن لـ API Token واحد استدعاء جميع خدمات المنصة، ولا حاجة للتقديم بشكل منفصل لكل خدمة. سيُمنح رصيد مجاني عند التقديم لأول مرة لتجربة الخدمة مجانًا؛ وعندما لا يكون الرصيد كافيًا، يمكنك شحن الرصيد العام من وحدة التحكم.

📘 الوثائق الكاملة: واجهة API للاستعلام عن مهام Maestro →

الاستعلام عن مهمة واحدة

لمعرفة كيفية إنشاء مهمة فيديو، يرجى الرجوع إلى وثيقة واجهة API لإنشاء فيديو Maestro. سنأخذ أحد معرّفات المهام التي تُرجعها كمثال: f57e99c4f60f4373a15517742ce2357d، لعرض كيفية الاستعلام عن حالتها ونتيجتها.

إعداد ترويسات الطلب وجسم الطلب

تشمل Request Headers ما يلي:

accept: يحدد تلقي نتائج الاستجابة بتنسيق JSON، وهنا يتم تعبئته بـ application/json.
authorization: مفتاح استدعاء API، ويمكن اختياره مباشرةً من القائمة المنسدلة بعد التقديم.
content-type: تنسيق جسم الطلب، وهنا يتم تعبئته بـ application/json.

تشمل Request Body ما يلي:

الحقل	النوع	مطلوب	الوصف
`id`	string	مطلوب عند الاستعلام عن مهمة واحدة	قيمة `task_id` التي يُرجعها `POST /maestro/videos`
`action`	string	لا	`retrieve` (افتراضي، للاستعلام عن مهمة واحدة)؛ وعند الاستعلام عن قائمة السجل تكون القيمة ثابتة `retrieve_batch`

مثال على الكود

كود CURL المقابل كما يلي:

curl -X POST 'https://api.acedata.cloud/maestro/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "f57e99c4f60f4373a15517742ce2357d",
  "action": "retrieve"
}'

كود Python المقابل كما يلي:

import requests

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

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

payload = {
    "id": "f57e99c4f60f4373a15517742ce2357d",
    "action": "retrieve"
}

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

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

بعد نجاح الطلب، ستُرجع API حالة ونتيجة مهمة الفيديو هذه. مثال على الاستجابة عند اكتمال المهمة كما يلي (يقابل كل لغة variant واحد):

{
  "id": "f57e99c4f60f4373a15517742ce2357d",
  "started_at": 1769262721.823,
  "finished_at": 1769264698.3,
  "elapsed": 1976.477,
  "status": "succeeded",
  "progress": {
    "percent": 100,
    "stage": "producing",
    "message": "rendering scene 2"
  },
  "request": {
    "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点",
    "langs": [
      "zh-cn",
      "en"
    ],
    "aspect": "9:16",
    "duration": 20
  },
  "response": {
    "success": true,
    "data": {
      "variants": [
        {
          "lang": "zh-cn",
          "aspect": "9:16",
          "kind": "video",
          "title": "什么是向量数据库",
          "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-001"
        },
        {
          "lang": "en",
          "aspect": "9:16",
          "kind": "video",
          "title": "What is a vector database",
          "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-002"
        }
      ],
      "project": {
        "tarball_url": null,
        "outputs": [
          "https://…/zh.mp4",
          "https://…/en.mp4"
        ]
      },
      "percent": 100,
      "stage": "producing",
      "progress": [
        {
          "stage": "producing",
          "message": "rendering scene 2",
          "pct": 60,
          "t": 1750000000
        }
      ]
    }
  }
}

يتم تقديم الحقول في نتيجة الإرجاع كما يلي:

id: معرّف مهمة الفيديو هذه، ويُستخدم لتمييز مهمة إنشاء الفيديو هذه بشكل فريد.
status: حالة المهمة، وقيمها هي pending → planning → producing → succeeded (أو failed). يُعتمد على status هذا في المستوى الأعلى لتحديد ما إذا كانت المهمة قد اكتملت.
elapsed: الوقت المنقضي للمهمة (بالثواني).
progress: كائن التقدم في المستوى الأعلى، يتم تعيين percent (0–100) إلى 100 كقيمة احتياطية بعد نجاح المهمة؛ ويعكس stage وmessage أحدث حدث تقدم من مخرج الذكاء الاصطناعي (لذلك قد يظل stage بعد النجاح في آخر مرحلة تنفيذ مثل producing)، ويمكن استخدامه مباشرةً لعرض شريط التقدم.
request: جسم الطلب عند بدء المهمة.
response: معلومات الإرجاع الخاصة بالمهمة.
- success: ما إذا كانت المهمة ناجحة.
- data.variants: يقابل كل لغة كائن فيديو نهائي واحد، ويتضمن lang وaspect وtitle وoutput_url (عنوان تنزيل الفيديو النهائي) وغيرها.
- data.project: مخرجات المشروع بالكامل، وتتضمن tarball_url (حزمة المشروع) وoutputs (جميع روابط الفيديوهات النهائية).
- data.progress: مصفوفة أحداث التقدم التي تُضاف حسب المراحل (سجل append-only)، ويمكن استخدامها لعرض التقدم التفصيلي في الوقت الفعلي.
created_at: وقت إنشاء المهمة، طابع زمني Unix (بالثواني).
started_at: وقت بدء تنفيذ المهمة، طابع زمني Unix (بالثواني). تكون null عندما لا تكون المهمة قد بدأت بعد.
finished_at: وقت اكتمال المهمة، طابع زمني Unix (بالثواني). تكون null عندما لا تكتمل المهمة.

الاستعلام عن قائمة السجل

يمكنك تمرير action: retrieve_batch للحصول على أحدث مهام المنفذ المسجل دخوله حاليًا (مرتبة تنازليًا حسب وقت الإنشاء)، ويمكن استخدامها لصفحة قائمة «فيديوهاتي». يتم عزل قائمة السجل حسب هوية تسجيل الدخول. تشمل Request Body ما يلي:

الحقل	النوع	مطلوب	الوصف
`action`	string	نعم	ثابت بقيمة `retrieve_batch`
`limit`	int	لا	عدد النتائج المُعادة، الافتراضي 20؛ النطاق الفعّال هو 1–100
`created_at_max`	int	لا	يُرجع فقط المهام التي تسبق بشكل صارم طابع Unix الزمني هذا (لا يشمل القيمة الحدّية، للاستخدام في التصفح)
`created_at_min`	int	لا	يُرجع فقط المهام التي تأتي بعد بشكل صارم طابع Unix الزمني هذا (لا يشمل القيمة الحدّية)

مثال على الكود

كود CURL المقابل كما يلي:

curl -X POST 'https://api.acedata.cloud/maestro/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "retrieve_batch",
  "limit": 20
}'

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

بعد نجاح الطلب، ستُرجع API قائمة المهام السابقة للمستخدم الحالي:

{
  "count": 2,
  "items": [
    {
      "id": "f57e99c4f60f4373a15517742ce2357d",
      "started_at": 1769262721.823,
      "finished_at": 1769264698.3,
      "elapsed": 1976.477,
      "status": "succeeded",
      "progress": {
        "percent": 100,
        "stage": "producing",
        "message": "rendering scene 2"
      },
      "request": {
        "prompt": "…",
        "langs": [
          "zh-cn",
          "en"
        ],
        "aspect": "9:16",
        "duration": 20
      },
      "response": {
        "success": true,
        "data": {
          "variants": [
            {
              "lang": "zh-cn",
              "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-003"
            }
          ]
        }
      }
    }
  ]
}

تعريف حقول نتيجة الإرجاع كما يلي:

count: إجمالي عدد المهام المرئية للمنفّذ الذي سجل الدخول حاليًا، ولا يتأثر بشروط الوقت أو limit.
items: مصفوفة المهام التي تمت تصفيتها وفقًا لشروط الوقت وlimit، مرتبة تنازليًا حسب وقت الإنشاء؛ يتطابق تنسيق كل عنصر مع نتيجة الإرجاع الخاصة بـ«الاستعلام عن مهمة واحدة».

توصيات الاستعلام الدوري

نظرًا لأن إنتاج الفيديو يستغرق وقتًا طويلًا، سيمر status عبر pending → planning → producing → succeeded (أو failed). يُوصى بالاستعلام الدوري مرة كل 5–10 ثوانٍ، حتى يصبح status هو succeeded أو failed. يمكن استخدام progress.percent في المستوى الأعلى لعرض شريط التقدم في الوقت الفعلي. الاستعلام الدوري عن هذه الواجهة مجاني ولا يستهلك نقاطًا.

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

عند استدعاء API، إذا واجهت خطأً، فستُرجع API رمز الخطأ والمعلومات المقابلة. على سبيل المثال:

401 invalid_token: غير مصرح به، رمز التفويض غير صالح أو مفقود.
404 not_found: المهمة غير موجودة، لا يوجد task_id المحدد.
429 too_many_requests: طلبات كثيرة جدًا، لقد تجاوزت حد المعدل.
500 api_error: خطأ داخلي في الخادم، حدث خطأ ما على الخادم.

مثال على استجابة خطأ

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

الخلاصة

من خلال هذا المستند، تعرفت بالفعل على كيفية استخدام API الاستعلام عن مهام Maestro للاستعلام عن حالة ونتيجة مهمة واحدة، وكذلك جلب قائمة المهام السابقة للمستخدم الحالي. نأمل أن يساعدك هذا المستند على التكامل مع API واستخدامها بشكل أفضل. إذا كانت لديك أي أسئلة، يرجى الاتصال بفريق الدعم الفني لدينا في أي وقت.

الواجهات ذات الصلة

دليل التكامل مع API إنشاء فيديو Maestro: استخدم مطالبة بلغة طبيعية واحدة لإنتاج فيديو نهائي مزود بترجمات تلقائيًا، ويُرجع task_id بعد الإرسال، ثم استخدم هذه الواجهة للاستعلام الدوري عن النتائج.

البداية

دردشة الذكاء الاصطناعي

صورة الذكاء الاصطناعي

فيديو الذكاء الاصطناعي

الصوت الذكي

الويب والبيانات

CAPTCHA

الهوية

Coding

المزيد من الأدلة

تعليمات تكامل واجهة API للاستعلام عن مهام Maestro

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

الاستعلام عن مهمة واحدة

إعداد ترويسات الطلب وجسم الطلب

مثال على الكود

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

الاستعلام عن قائمة السجل

مثال على الكود

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

توصيات الاستعلام الدوري

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

مثال على استجابة خطأ

الخلاصة

الواجهات ذات الصلة

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

​الاستعلام عن مهمة واحدة

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

​مثال على الكود

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

​الاستعلام عن قائمة السجل

​مثال على الكود

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

​توصيات الاستعلام الدوري

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

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

​الخلاصة

​الواجهات ذات الصلة

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

الاستعلام عن مهمة واحدة

إعداد ترويسات الطلب وجسم الطلب

مثال على الكود

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

الاستعلام عن قائمة السجل

مثال على الكود

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

توصيات الاستعلام الدوري

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

مثال على استجابة خطأ

الخلاصة

الواجهات ذات الصلة