> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Maestro AI Video Studio API guide - Ace Data Cloud

Maestro هو واجهة إنتاج الفيديو **المعتمدة على الوكيل**: يمكنك استخدام جملة طبيعية `prompt` لوصف الفيديو الذي تريده (يمكنك اختيار إرفاق صور / فيديوهات / صوتيات مرجعية باستخدام `file_urls`)، وسيقوم "مخرج الذكاء الاصطناعي" تلقائيًا بإكمال اختيار الموضوع، كتابة السيناريو، توليد المشاهد، التعليق الصوتي، الموسيقى، الدمج والتصيير، وفي النهاية إنتاج الفيديو مع الترجمة وتحميله على CDN.

ستتناول هذه الوثيقة تفاصيل واجهة برمجة تطبيقات توليد الفيديو Maestro، لمساعدتك على دمجها بسرعة واستغلال قدراتها بشكل كامل.

هذه واجهة **مهام غير متزامنة**: بعد الإرسال، سيتم إرجاع `task_id` على الفور، ثم يمكنك الاستعلام عن النتائج من خلال [واجهة برمجة تطبيقات استعلام مهام Maestro](/ar/guides/maestro/maestro_tasks) (`POST /maestro/tasks`) (الاستعلام مجاني ولا يتم احتساب رسوم). للاستمرار في التكرار على فيديو موجود، يمكنك استخدام `action: remix` / `edit` / `extend` مع `ref_task_id`.

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

لاستخدام واجهة برمجة تطبيقات توليد الفيديو Maestro، يجب أولاً الذهاب إلى [لوحة تحكم Ace Data Cloud](https://platform.acedata.cloud/console/applications) للحصول على رمز API الخاص بك، احتفظ به للاستخدام لاحقًا.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

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

**يمكن استخدام رمز API واحد لاستدعاء جميع خدمات المنصة، دون الحاجة لتقديم طلب منفصل لكل خدمة.** عند التقديم لأول مرة، ستحصل على رصيد مجاني لتجربته؛ وعند نفاد الرصيد، يمكنك إعادة شحن الرصيد العام في [لوحة التحكم](https://platform.acedata.cloud/console/coin).

> 📘 الوثائق الكاملة: [واجهة برمجة تطبيقات توليد الفيديو Maestro →](https://platform.acedata.cloud/documents/maestro-videos)

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

`POST https://api.acedata.cloud/maestro/videos`

أبسط استخدام يتطلب فقط تمرير جملة طبيعية `prompt`، وسيقوم مخرج الذكاء الاصطناعي بتحديد السيناريو، المشاهد، التعليق الصوتي والمونتاج تلقائيًا. هنا سنتعرف على رؤوس الطلب وجسم الطلب الذي يجب إعداده.

**رؤوس الطلب** تشمل:

* `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.

جميع حقول جسم الطلب موضحة في الجدول أدناه:

| الحقل | النوع | إلزامي | الشرح |
| - | - | - | - |
| `prompt` | string | نعم | وصف الفيديو الذي تريد إنشاؤه بلغة طبيعية (الموضوع، ما يجب عرضه، الأسلوب، الجمهور). السيناريو، المشاهد، التعليق الصوتي، والمونتاج يتم تحديدها بواسطة الذكاء الاصطناعي |
| `action` | string | لا | `generate` (افتراضي، إنشاء فيديو جديد) / `remix` / `edit` / `extend` (التكرار على فيديو موجود، يتطلب `ref_task_id`) |
| `ref_task_id` | string | لا | عند كون `action` هو remix / edit / extend، يجب ملؤه: كمعرف المهمة التاريخية `task_id` كنقطة انطلاق |
| `file_urls` | string\[] | لا | وسائل الإعلام المرجعية (صور / فيديوهات / صوتيات URL)، مثل صور المنتجات، الشعار، أو مقاطع المواد التي تحتاج إلى إضافة ترجمات |
| `langs` | string\[] | لا | اللغات الناتجة، مثل `["zh-cn", "en"]`، الافتراضي هو `["zh-cn"]`. الأولى هي اللغة الرئيسية؛ كلما زادت لغة، يتم إعادة استخدام المشاهد، فقط يتم إضافة التعليق الصوتي + التصيير، **كل لغة إضافية +6 نقاط** |
| `aspect` | string | لا | `9:16` (افتراضي) / `16:9` / `1:1`، يتم إخراجها بدقة 1080p/30fps موحدة |
| `duration` | int | لا | الطول المستهدف (بالثواني)، الافتراضي 30، يدعم **5–300 ثانية**. يتم احتساب الرسوم بناءً على الطول الفعلي للفيديو، ولكن لا يتجاوز الطول المطلوب |
| `scenario` | string | لا | نوع الفيديو: `auto` / `narrated` / `captions` / `avatar` / `drama`. `captions` يتطلب تقديم الفيديو المصدر، `avatar` يتطلب تقديم صورة شخصية |
| `style` | string | لا | إعدادات الأسلوب البصري: `auto` (افتراضي) / `cinematic` / `glass` / `luxury` / `swiss` / `modern` / `editorial` / `warm` / `vibrant` / `neon` / `mono` / `pastel` / `bold` / `industrial` / `futuristic` / `retro`، كما يقبل نصوص حرة كإشارات ناعمة. لا يغير التوجيه |
| `voice` | string | لا | نغمة التعليق الصوتي (غير مرتبطة باللغة، تعمل عبر اللغات): `auto` (افتراضي) / `warm-female` / `bright-female` / `anchor-female` / `clean-female` / `calm-male` / `deep-male` / `documentary-male` / `energetic-male` / `storyteller-male` |

دعونا نوضح ذلك من خلال مثال محدد. لنفترض أننا نريد إنشاء فيديو قصير علمي ثنائي اللغة (الصينية والإنجليزية)، عمودي، مدته 20 ثانية، كود CURL المقابل هو كما يلي:

```bash theme={null}
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
}'
```

الكود المقابل بلغة Python هو كما يلي:

```python theme={null}
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)
```

عند النقر على التشغيل، يمكنك أن ترى أنه سيتم الحصول على نتيجة على الفور، كما يلي:

```json theme={null}
{
  "success": true,
  "task_id": "f57e99c4f60f4373a15517742ce2357d",
  "trace_id": "70e1cb12-c619-4292-a416-90191205996b"
}
```

شرح حقول نتيجة الإرجاع كما يلي:

* `success`：هل تم تقديم هذه المهمة بنجاح.
* `task_id`：معرف مهمة إنشاء الفيديو هذه، سيتم استخدامه لاحقًا لاستعلام النتائج عبر [API استعلام مهام Maestro](/ar/guides/maestro/maestro_tasks).
* `trace_id`：معرف تتبع الطلب الحالي، يمكن تقديمه للدعم الفني لتحديد المشكلة.

نظرًا لأن إنتاج الفيديو يستغرق وقتًا طويلاً، فإن الواجهة **ترجع `task_id` على الفور**، ولن تنتظر حتى يكتمل عرض الفيديو. بعد ذلك، تحتاج إلى استخدام `task_id` لاستعلام النتائج، انظر قسم "استعلام النتائج".

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

عند عدم تمرير `scenario`، سيقوم الذكاء الاصطناعي بتحديده تلقائيًا (يعادل `auto`)؛ إذا كنت ترغب في تثبيت الفيديو على نوع معين، يمكنك تمرير ذلك بشكل صريح. على سبيل المثال، لإنشاء **دراما قصيرة عمودية**، يمكنك تحديد المحتوى كما يلي:

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

نموذج كود CURL كما يلي:

```bash theme={null}
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`)، غير مرتبطة باللغة، وتعمل عبر اللغات.

نتيجة العودة متوافقة مع "الاستخدام الأساسي"، حيث يتم إرجاع `task_id` على الفور.

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

يمكنك تمرير عدة لغات في `langs` لإنتاج نسخ متعددة اللغات مرة واحدة. الأولى هي اللغة الرئيسية، وكلما تمت إضافة لغة جديدة، سيتم **إعادة استخدام نفس مجموعة المشاهد**، مع إضافة التعليق الصوتي + العرض، لذلك **كل لغة إضافية تكلف +6 نقاط فقط**. مثال:

```bash theme={null}
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
}'
```

عند الانتهاء من المهمة، ستتوافق كل لغة مع `variant` في النتيجة (انظر [API استعلام مهام Maestro](/ar/guides/maestro/maestro_tasks)).

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

قم بتمرير `action` مع `ref_task_id` من المهمة السابقة، يمكنك إجراء تعديلات طفيفة على المشروع الأصلي (مثل "تغيير عنوان المشهد الثاني" أو "تغيير التعليق الصوتي" أو "تعتيم الصورة"). التعديلات الصغيرة سريعة، والتعديلات الكبيرة ستحتاج إلى إعادة العمل:

```bash theme={null}
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`：توسيع المحتوى بناءً على الفيديو الأصلي.

نتيجة العودة هي أيضًا إرجاع `task_id` جديد على الفور، يمكنك استخدامه لاستعلام النتيجة النهائية بعد التكرار.

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

نظرًا لأن إنتاج الفيديو يستغرق وقتًا طويلاً، فإن هذه الواجهة ترجع `task_id` على الفور بعد التقديم، تحتاج إلى استخدامه لاستعلام النتائج عبر [API استعلام مهام Maestro](/ar/guides/maestro/maestro_tasks):

```bash theme={null}
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"
}'
```

عند الانتهاء من المهمة، ستعود معلومات الفيديو (كل لغة تتوافق مع `variant`). ستشهد `status` مراحل `pending → planning → producing → succeeded` (أو `failed`)، **الاستعلام مجاني، ولا يستهلك النقاط**. يرجى الرجوع إلى [إرشادات تكامل API استعلام مهام Maestro](/ar/guides/maestro/maestro_tasks) للحصول على تنسيق الاستجابة الكامل واستعلام القائمة التاريخية.

## الفوترة

**يتم الفوترة بعد إكمال المهمة بناءً على الفيديو النهائي، ولا يتم خصم رسوم للمهمات الفاشلة.** يتم الفوترة بناءً على طول الفيديو النهائي الفعلي وعدد اللغات، ولن تتجاوز مدة الفوترة مدة الطلب. إذا لم يتم إنتاج لغة معينة في النهاية، فلن يتم فرض رسوم إضافية قدرها +6 لتلك اللغة. تقديم المهمة نفسها لا يتم فوترة بشكل منفصل، واستعلام `/maestro/tasks` مجاني.

يتم حساب النقاط للفيديو النهائي كما يلي:

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

تقوم Maestro بالفوترة بشكل موحد بمعدل **0.60 نقطة/ثانية من الفيديو النهائي الفعلي**، تدعم من 5 إلى 300 ثانية، وأقصى 4 لغات و1080p / 30fps للإخراج؛ جميع الإجراءات والمشاهد متاحة.

معامل المشهد: `drama` 1.35× / `avatar` 1.15× / الأخرى 1×.

| مثال | النقاط |
| - | -: |
| Lite 30 ثانية | 6 |
| Standard 30 ثانية | 18 |
| Standard 60 ثانية | 36 |
| Standard 120 ثانية | 72 |
| Pro 30 ثانية | 36 |
| Pro 300 ثانية | 360 |
| كل لغة إضافية يتم تسليمها | +6 |
| استعلام `/maestro/tasks` | مجاني |

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

عند استدعاء API، إذا واجهت خطأ، ستقوم API بإرجاع رمز الخطأ والمعلومات المناسبة. على سبيل المثال:

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

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

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

## الاستنتاج

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

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

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.