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.
prompt: وصف الفيديو المطلوب بلغة طبيعية (الموضوع، ما الذي سيُعرض، الأسلوب، والجمهور المستهدف).langs: مصفوفة لغات الفيديو النهائي؛ مرّر لغة واحدة فقط في كل مرة، مثل["zh-cn"]، والقيمة الافتراضية هي["zh-cn"].aspect: نسبة أبعاد الصورة،9:16(افتراضي) /16:9/1:1.duration: المدة المستهدفة (بالثواني)، والقيمة الافتراضية هي 30.
فيما يلي توضيح عبر مثال محدد. لنفترض أننا نريد إنشاء فيديو علمي قصير باللغة الصينية، بتنسيق عمودي، ومدته 20 ثانية. يكون رمز CURL المقابل كما يلي:
success: ما إذا تم إرسال هذه المهمة بنجاح.task_id: معرّف مهمة إنشاء الفيديو هذه، ويُستخدم لاحقًا للاستعلام عن النتائج بشكل دوري عبر واجهة API للاستعلام عن مهام Maestro.trace_id: معرّف التتبع لهذا الطلب، ويمكن تقديمه إلى الدعم الفني عند مواجهة مشكلة للمساعدة في تحديدها.
task_id فورًا، ولن تنتظر حتى يكتمل تصيير الفيديو. بعد ذلك، يجب استخدام task_id للاستعلام عن النتيجة بشكل دوري. راجع قسم «الحصول على النتيجة» للتفاصيل.
تحديد نوع الفيديو ونمطه (scenario / style)
عند عدم تمريرscenario، يحدد الذكاء الاصطناعي ذلك تلقائيًا (يساوي auto)؛ إذا أردت تثبيت الفيديو على نوع معين، فمرّره صراحةً. على سبيل المثال، لإنشاء دراما قصيرة عمودية، يمكن تحديد المحتوى التالي:
scenario: نوع الفيديو، ويُضبط هنا علىdrama(دراما قصيرة بشخصيات + حوار).style: النمط البصري، ويُضبط هنا علىcinematic(إحساس سينمائي).
- مقطع شرح قصير:
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 مجاني.
معالجة الأخطاء
عند استدعاء API، إذا واجهت خطأً، فستُرجع API رمز الخطأ والمعلومات المقابلة. على سبيل المثال:400 invalid_request: طلب غير صالح، ربما بسبب فقدانpromptأو معلمات غير صالحة.401 invalid_token: غير مصرح به، رمز تفويض غير صالح أو مفقود.403 forbidden: محظور، رصيد أو صلاحية وصول غير كافيين.429 too_many_requests: طلبات كثيرة جدًا، لقد تجاوزت حد المعدل.500 api_error: خطأ داخلي في الخادم، حدث خطأ ما على الخادم.
مثال على استجابة خطأ
الخلاصة
من خلال هذا المستند، أصبحت تعرف بالفعل كيفية استخدام Maestro Video Generation API: كل ما تحتاجه هوprompt واحد بلغة طبيعية لإكمال النص والمواد والتعليق الصوتي والموسيقى والمونتاج والترجمة وتصييّر الفيديو النهائي تلقائيًا، كما يدعم تحديد نوع الفيديو ونمطه ونبرة الصوت ولغة الفيديو النهائي والتكرار على الفيديوهات الموجودة. نأمل أن يساعدك هذا المستند على التكامل مع API واستخدامها بشكل أفضل. إذا كانت لديك أي أسئلة، فيرجى الاتصال بفريق الدعم الفني لدينا في أي وقت.
الواجهات ذات الصلة
- تعليمات تكامل واجهة برمجة تطبيقات الاستعلام عن مهام Maestro: استخدم
task_idالمعاد بواسطةPOST /maestro/videosللاستعلام عن حالة المهمة ونتيجتها، أو لجلب قائمة المهام التاريخية (الاستطلاع مجاني).

