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.
مثال على الكود
كود CURL المقابل كما يلي:مثال على الاستجابة
بعد نجاح الطلب، ستُرجع واجهة 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 هذه واستخدامها بشكل أفضل. إذا كانت لديك أي أسئلة، فيرجى الاتصال بفريق الدعم الفني لدينا في أي وقت.الواجهات ذات الصلة
- تعليمات التكامل مع واجهة API لإنشاء فيديو Maestro: استخدم مطالبة بلغة طبيعية واحدة لإنتاج فيديو مكتمل مع ترجمة تلقائياً، وستحصل على
task_idبعد الإرسال، ثم استخدم هذه الواجهة للاستعلام الدوري عن النتائج.

