Maestro واجهة برمجة تطبيقات توليد الفيديو

​

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

📘 الوثائق الكاملة: واجهة برمجة تطبيقات توليد الفيديو Maestro →

​

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

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

• prompt: وصف الفيديو الذي تريد إنشاؤه بلغة طبيعية (الموضوع، ما يجب عرضه، الأسلوب، الجمهور).
• langs: مصفوفة اللغات الناتجة، مثل ["zh-cn", "en"]، الافتراضي هو ["zh-cn"].
• aspect: نسبة العرض إلى الارتفاع، 9:16 (افتراضي) / 16:9 / 1:1.
• duration: الطول المستهدف (بالثواني)، الافتراضي 30.

curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点",
  "langs": ["zh-cn", "en"],
  "aspect": "9:16",
  "duration": 20
}'

import requests

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

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

payload = {
    "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点",
    "langs": ["zh-cn", "en"],
    "aspect": "9:16",
    "duration": 20
}

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

{
  "success": true,
  "task_id": "f57e99c4f60f4373a15517742ce2357d",
  "trace_id": "70e1cb12-c619-4292-a416-90191205996b"
}

• success：هل تم تقديم هذه المهمة بنجاح.
• task_id：معرف مهمة إنشاء الفيديو هذه، سيتم استخدامه لاحقًا لاستعلام النتائج عبر API استعلام مهام Maestro.
• trace_id：معرف تتبع الطلب الحالي، يمكن تقديمه للدعم الفني لتحديد المشكلة.

​

تحديد نوع الفيديو والأسلوب (scenario / style)

• scenario：نوع الفيديو، هنا يتم تعيينه إلى drama (دراما قصيرة مع شخصيات + حوار).
• style：أسلوب بصري، هنا يتم تعيينه إلى cinematic (جودة سينمائية).

curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "اثنان من زملاء السكن يتشاجران بسبب قطة ثم يتصالحان، ثلاث مشاهد مع تحول، النهاية دافئة",
  "scenario": "drama",
  "style": "cinematic",
  "aspect": "9:16",
  "duration": 40
}'

• مقاطع قصيرة مع تعليق: scenario: "narrated"، تدعمها Lite / Standard / Pro.
• ترجمات تلقائية: scenario: "captions"، يجب استخدام file_urls لتمرير الفيديو المصدر، تدعمها Lite / Standard / Pro.
• شخصيات رقمية / تعليق صوتي: scenario: "avatar"، يجب استخدام file_urls لتمرير صورة شخصية، تدعمها Standard / Pro.
• دراما: scenario: "drama" (شخصيات + حوار)، تدعمها فقط Pro.
• style هو إعداد أسلوب بصري (مثل modern / neon / luxury)، لا يغير النوع، يؤثر فقط على التجربة البصرية.
• voice تستخدم لتحديد نغمة التعليق الصوتي (مثل warm-female / deep-male)، غير مرتبطة باللغة، وتعمل عبر اللغات.

​

إخراج متعدد اللغات

curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "تقديم منتج خدمة العملاء الذكي لدينا، مع تسليط الضوء على 3 نقاط رئيسية",
  "langs": ["zh-cn", "en", "ja"],
  "aspect": "16:9",
  "duration": 30
}'

​

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

curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "remix",
  "ref_task_id": "f57e99c4f60f4373a15517742ce2357d",
  "prompt": "تغيير عنوان البداية إلى جملة أكثر تأثيرًا، مع جعل الألوان أغمق قليلاً"
}'

• remix：إعادة تفسير الهيكل الأصلي للفيديو (مع الحفاظ على الموضوع، وتعديل العرض).
• edit：إجراء تحسينات دقيقة على جزء محدد (مثل تغيير العنوان، تغيير التعليق الصوتي، تعديل الألوان).
• extend：توسيع المحتوى بناءً على الفيديو الأصلي.

​

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

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"
}'

​

الفوترة

النقاط = طول الفيديو النهائي بالثواني × 0.60 × معامل المشهد + 6 × max(عدد اللغات - 1, 0)

​

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

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

​

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

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "فشل في جلب البيانات"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​

الاستنتاج

​

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

• إرشادات تكامل واجهة برمجة تطبيقات استعلام مهام Maestro: استخدم POST /maestro/videos لإرجاع task_id للاستعلام عن حالة المهمة ونتائجها، أو سحب قائمة المهام التاريخية (الاستطلاع مجاني).