الانتقال إلى المحتوى الرئيسي
تتمثل الوظيفة الرئيسية لـ 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 ما يلي:

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

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

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

بعد نجاح الطلب، ستُرجع واجهة API حالة هذه المهمة الخاصة بالفيديو ونتيجتها. مثال على الاستجابة عند اكتمال المهمة كما يلي (تحتوي مصفوفة variants على فيديو نهائي واحد):
فيما يلي وصف لحقول النتيجة المعادة:
  • 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: مصفوفة أحداث التقدم المضافة حسب المراحل (سجل للإضافة فقط)، ويمكن استخدامها لعرض تقدم مفصل في الوقت الفعلي.
  • created_at: وقت إنشاء المهمة، طابع زمني لـ Unix (بالثواني).
  • started_at: وقت بدء تنفيذ المهمة، طابع زمني لـ Unix (بالثواني). تكون القيمة null إذا لم تبدأ المهمة بعد.
  • finished_at: وقت إكمال المهمة، طابع زمني Unix (بالثواني). يكون null عند عدم اكتمال المهمة.

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

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

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

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

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

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

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

الخلاصة

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

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