الانتقال إلى المحتوى الرئيسي
Maestro هو واجهة إنتاج فيديو أصلية للـ Agent: تستخدم prompt بلغة طبيعية من جملة واحدة لوصف الفيديو الذي تريده (ويمكنك اختياريًا إرفاق صور / فيديوهات / صوتيات مرجعية باستخدام file_urls)، وسيتولى «مخرج AI» بلا واجهة تلقائيًا إتمام اختيار الموضوع، وكتابة النص، وإنشاء المشاهد، والتعليق الصوتي، والموسيقى التصويرية، والتركيب والعرض، لينتج في النهاية فيديو مكتملًا مع ترجمة ويرفعه إلى CDN. ستعرض هذه المقالة بالتفصيل تعليمات تكامل API لإنشاء فيديو Maestro، لمساعدتك على التكامل بسرعة والاستفادة الكاملة من قدرات API. هذه واجهة مهام غير متزامنة: بعد الإرسال ستعيد فورًا task_id، ثم يمكنك استطلاع النتيجة عبر Maestro Task Query API (POST /maestro/tasks) (الاستطلاع مجاني ولا يُحتسب ضمن الفوترة). لمتابعة التكرار على فيديو موجود، يمكنك استخدام action: remix / edit / extend مع ref_task_id.

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

لاستخدام API لإنشاء فيديو Maestro، انتقل أولًا إلى وحدة تحكم Ace Data Cloud للحصول على API Token الخاص بك، واحتفظ به للاستخدام لاحقًا. إذا لم تقم بتسجيل الدخول أو التسجيل بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك إلى التسجيل وتسجيل الدخول، وبعد الإكمال ستعود تلقائيًا إلى الصفحة الحالية. يمكن لـ API Token واحد استدعاء جميع خدمات المنصة، ولا حاجة إلى التقديم بشكل منفصل لكل خدمة. سيُمنحك رصيد مجاني عند أول تقديم، ويمكنك التجربة مجانًا؛ وعندما يكون الرصيد غير كافٍ، يمكنك إعادة شحن الرصيد العام من وحدة التحكم.
📘 الوثائق الكاملة: Maestro Video Generation API →

الاستخدام الأساسي

POST https://api.acedata.cloud/maestro/videos يتطلب الاستخدام الأساسي فقط تمرير prompt بلغة طبيعية، وسيقرر مخرج الذكاء الاصطناعي تلقائيًا النص والصور والتعليق الصوتي والمونتاج. لنتعرّف أولًا على رؤوس الطلب ونصّه المطلوب إعدادها. رؤوس الطلب (Request Headers) تشمل:
  • accept: تنسيق نتيجة الاستجابة التي تريد تلقيها؛ أدخل هنا application/json، أي تنسيق JSON.
  • authorization: مفتاح استدعاء واجهة API، ويمكن اختياره مباشرةً من القائمة المنسدلة بعد التقديم عليه.
  • content-type: تنسيق نص الطلب؛ أدخل هنا application/json.
نص الطلب (Request Body) يتضمن بشكل أساسي:
  • prompt: وصف الفيديو المطلوب بلغة طبيعية (الموضوع، ما الذي سيُعرض، الأسلوب، والجمهور المستهدف).
  • langs: مصفوفة لغات الفيديو النهائي؛ مرّر لغة واحدة فقط في كل مرة، مثل ["zh-cn"]، والقيمة الافتراضية هي ["zh-cn"].
  • aspect: نسبة أبعاد الصورة، 9:16 (افتراضي) / 16:9 / 1:1.
  • duration: المدة المستهدفة (بالثواني)، والقيمة الافتراضية هي 30.
جميع حقول نص الطلب موضحة في الجدول التالي: فيما يلي توضيح عبر مثال محدد. لنفترض أننا نريد إنشاء فيديو علمي قصير باللغة الصينية، بتنسيق عمودي، ومدته 20 ثانية. يكون رمز CURL المقابل كما يلي:
رمز Python المقابل كما يلي:
انقر على «تشغيل»، وستلاحظ الحصول على نتيجة فورًا، كما يلي:
فيما يلي وصف لحقول النتيجة المعادة:
  • success: ما إذا تم إرسال هذه المهمة بنجاح.
  • task_id: معرّف مهمة إنشاء الفيديو هذه، ويُستخدم لاحقًا للاستعلام عن النتائج بشكل دوري عبر واجهة API للاستعلام عن مهام Maestro.
  • trace_id: معرّف التتبع لهذا الطلب، ويمكن تقديمه إلى الدعم الفني عند مواجهة مشكلة للمساعدة في تحديدها.
نظرًا لأن إنتاج الفيديو يستغرق وقتًا طويلًا، تُرجع الواجهة هنا task_id فورًا، ولن تنتظر حتى يكتمل تصيير الفيديو. بعد ذلك، يجب استخدام task_id للاستعلام عن النتيجة بشكل دوري. راجع قسم «الحصول على النتيجة» للتفاصيل.

تحديد نوع الفيديو ونمطه (scenario / style)

عند عدم تمرير scenario، يحدد الذكاء الاصطناعي ذلك تلقائيًا (يساوي auto)؛ إذا أردت تثبيت الفيديو على نوع معين، فمرّره صراحةً. على سبيل المثال، لإنشاء دراما قصيرة عمودية، يمكن تحديد المحتوى التالي:
  • scenario: نوع الفيديو، ويُضبط هنا على drama (دراما قصيرة بشخصيات + حوار).
  • style: النمط البصري، ويُضبط هنا على cinematic (إحساس سينمائي).
فيما يلي مثال على كود CURL المكتمل:
طرق الاقتران الشائعة:
  • مقطع شرح قصير: scenario: "narrated".
  • ترجمة تلقائية: scenario: "captions"، يجب تمرير فيديو المصدر باستخدام file_urls.
  • إنسان رقمي / حديث مباشر: scenario: "avatar"، يجب تمرير صورة شخصية باستخدام file_urls.
  • دراما قصيرة: scenario: "drama" (شخصيات + حوار).
  • style هو إعداد مسبق للنمط البصري (مثل modern / neon / luxury)، ولا يغير النوع، بل يؤثر فقط على المظهر.
  • يُستخدم voice لتحديد نبرة صوت التعليق الصوتي (مثل warm-female / deep-male)، وهو غير مرتبط باللغة وعام بين اللغات.
تتوافق النتيجة المعادة مع «الاستخدام الأساسي»، إذ تُرجع أيضًا task_id فورًا.

لغة الفيديو النهائي

تُسلَّم لكل مهمة نسخة فيديو نهائية واحدة بلغة واحدة فقط. يمكن أن يحتوي langs على رمز لغة واحد فقط، مثل ["zh-cn"] أو ["en"]؛ سيؤدي تمرير لغات متعددة إلى إرجاع 400. إذا كنت بحاجة إلى فيديوهات بلغات مختلفة، فيرجى إنشاء مهام منفصلة. لا يؤثر اختيار اللغة على السعر لكل ثانية.

التكرار على فيديو موجود (remix / edit / extend)

مرّر action وref_task_id للمهمة السابقة، ويمكنك إجراء تعديلات تدريجية على أساس المشروع الأصلي (مثل «تغيير عنوان المشهد الثاني»، «تبديل التعليق الصوتي»، «تعتيم الفيديو بالكامل»). التعديلات الصغيرة سريعة، أما التعديلات الكبيرة فستُعاد معالجتها:
  • remix: إعادة تقديم على بنية الفيديو الأصلية (مع الحفاظ على الفكرة وتعديل العرض).
  • edit: إجراء تنقيح دقيق على جزء محدد (مثل تغيير العنوان أو التعليق الصوتي أو تدرج الألوان).
  • extend: توسيع المحتوى على أساس الفيديو الأصلي.
تُرجع النتيجة أيضًا task_id جديدًا فورًا، ويمكنك استخدامه للاستطلاع والحصول على الفيديو النهائي بعد التكرار.

الحصول على النتائج

نظرًا لأن إنتاج الفيديو يستغرق وقتًا طويلًا، تُرجع هذه الواجهة task_id فورًا بعد الإرسال، وتحتاج إلى استخدامه لاستطلاع النتائج عبر واجهة برمجة تطبيقات الاستعلام عن مهام Maestro:
عند اكتمال المهمة، ستُرجع معلومات فيديو نهائي واحدة (توجد في مصفوفة variants). سيمر status بالمراحل pending → planning → producing → succeeded (أو failed)، والاستطلاع مجاني ولا يستهلك نقاطًا. راجع تعليمات تكامل واجهة برمجة تطبيقات الاستعلام عن مهام Maestro للحصول على تنسيق الاستجابة الكامل والاستعلام عن القائمة التاريخية.

الفوترة

بعد نجاح المهمة، تُحتسب الرسوم بناءً على المدة الفعلية للفيديو النهائي المُسلَّم، ولا تُفرض رسوم عند الفشل. تُحتسب مدة الفوترة بالثواني الصحيحة، ولا تتجاوز المدة المطلوبة؛ وعند تعذر قراءة مدة الفيديو النهائي، يتم الرجوع إلى المدة المطلوبة. لا يتم احتساب رسوم منفصلة على إرسال المهمة نفسه، واستطلاع /maestro/tasks مجاني.
تستخدم جميع السيناريوهات والإجراءات واللغات السعر نفسه، دون معاملات مضاعفة للسيناريو أو رسوم إضافية للغة. تُسلَّم لكل مهمة نسخة فيديو نهائية واحدة بلغة واحدة فقط. تدعم مدة الهدف المطلوبة من 5 إلى 300 ثانية، ويكون الإخراج الموحد بدقة 1080p / 30fps.

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

عند استدعاء API، إذا واجهت خطأً، فستُرجع API رمز الخطأ والمعلومات المقابلة. على سبيل المثال:
  • 400 invalid_request: طلب غير صالح، ربما بسبب فقدان prompt أو معلمات غير صالحة.
  • 401 invalid_token: غير مصرح به، رمز تفويض غير صالح أو مفقود.
  • 403 forbidden: محظور، رصيد أو صلاحية وصول غير كافيين.
  • 429 too_many_requests: طلبات كثيرة جدًا، لقد تجاوزت حد المعدل.
  • 500 api_error: خطأ داخلي في الخادم، حدث خطأ ما على الخادم.

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

الخلاصة

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

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