> ## 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.

# تعليمات تكامل واجهة API للاستعلام عن مهام Maestro

> Maestro AI Video Studio API guide - Ace Data Cloud

تتمثل الوظيفة الرئيسية لواجهة API للاستعلام عن مهام Maestro في الاستعلام عن حالة تنفيذ المهمة ونتيجتها النهائية من خلال معرّف المهمة الذي تُرجعه [واجهة API لإنشاء فيديو Maestro](/ar/guides/maestro/maestro_videos) (`POST /maestro/videos`).

ستقدم هذه الوثيقة تعليمات تكامل واجهة API للاستعلام عن مهام Maestro بالتفصيل. نظرًا لأن إنشاء الفيديو مهمة غير متزامنة، يجب استخدام هذه الواجهة للاستعلام الدوري عن التقدم والفيديو النهائي بعد الإرسال، **والاستعلام الدوري مجاني ولا يستهلك النقاط.**

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

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

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

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

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

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

> 📘 الوثائق الكاملة: [واجهة API للاستعلام عن مهام Maestro →](https://platform.acedata.cloud/documents/maestro-tasks)

## الاستعلام عن مهمة واحدة

لمعرفة كيفية إنشاء مهمة فيديو، يرجى الرجوع إلى وثيقة [واجهة API لإنشاء فيديو Maestro](/ar/guides/maestro/maestro_videos). سنأخذ أحد معرّفات المهام التي تُرجعها كمثال: `f57e99c4f60f4373a15517742ce2357d`، لعرض كيفية الاستعلام عن حالتها ونتيجتها.

### إعداد ترويسات الطلب وجسم الطلب

تشمل **Request Headers** ما يلي:

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

تشمل **Request Body** ما يلي:

| الحقل | النوع | مطلوب | الوصف |
| - | - | - | - |
| `id` | string | مطلوب عند الاستعلام عن مهمة واحدة | قيمة `task_id` التي يُرجعها `POST /maestro/videos` |
| `action` | string | لا | `retrieve` (افتراضي، للاستعلام عن مهمة واحدة)؛ وعند الاستعلام عن قائمة السجل تكون القيمة ثابتة `retrieve_batch` |

### مثال على الكود

كود CURL المقابل كما يلي:

```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",
  "action": "retrieve"
}'
```

كود Python المقابل كما يلي:

```python theme={null}
import requests

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

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

payload = {
    "id": "f57e99c4f60f4373a15517742ce2357d",
    "action": "retrieve"
}

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

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

بعد نجاح الطلب، ستُرجع API حالة ونتيجة مهمة الفيديو هذه. مثال على الاستجابة عند اكتمال المهمة كما يلي (يقابل كل لغة `variant` واحد):

```json theme={null}
{
  "id": "f57e99c4f60f4373a15517742ce2357d",
  "started_at": 1769262721.823,
  "finished_at": 1769264698.3,
  "elapsed": 1976.477,
  "status": "succeeded",
  "progress": {
    "percent": 100,
    "stage": "producing",
    "message": "rendering scene 2"
  },
  "request": {
    "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点",
    "langs": [
      "zh-cn",
      "en"
    ],
    "aspect": "9:16",
    "duration": 20
  },
  "response": {
    "success": true,
    "data": {
      "variants": [
        {
          "lang": "zh-cn",
          "aspect": "9:16",
          "kind": "video",
          "title": "什么是向量数据库",
          "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-001"
        },
        {
          "lang": "en",
          "aspect": "9:16",
          "kind": "video",
          "title": "What is a vector database",
          "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-002"
        }
      ],
      "project": {
        "tarball_url": null,
        "outputs": [
          "https://…/zh.mp4",
          "https://…/en.mp4"
        ]
      },
      "percent": 100,
      "stage": "producing",
      "progress": [
        {
          "stage": "producing",
          "message": "rendering scene 2",
          "pct": 60,
          "t": 1750000000
        }
      ]
    }
  }
}
```

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

* `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`: مصفوفة أحداث التقدم التي تُضاف حسب المراحل (سجل append-only)، ويمكن استخدامها لعرض التقدم التفصيلي في الوقت الفعلي.
* `created_at`: وقت إنشاء المهمة، طابع زمني Unix (بالثواني).
* `started_at`: وقت بدء تنفيذ المهمة، طابع زمني Unix (بالثواني). تكون null عندما لا تكون المهمة قد بدأت بعد.
* `finished_at`: وقت اكتمال المهمة، طابع زمني Unix (بالثواني). تكون null عندما لا تكتمل المهمة.

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

يمكنك تمرير `action: retrieve_batch` للحصول على أحدث مهام المنفذ المسجل دخوله حاليًا (مرتبة تنازليًا حسب وقت الإنشاء)، ويمكن استخدامها لصفحة قائمة «فيديوهاتي». يتم عزل قائمة السجل حسب هوية تسجيل الدخول.

تشمل **Request Body** ما يلي:

| الحقل | النوع | مطلوب | الوصف |
| - | - | - | - |
| `action` | string | نعم | ثابت بقيمة `retrieve_batch` |
| `limit` | int | لا | عدد النتائج المُعادة، الافتراضي 20؛ النطاق الفعّال هو 1–100 |
| `created_at_max` | int | لا | يُرجع فقط المهام التي تسبق بشكل صارم طابع Unix الزمني هذا (لا يشمل القيمة الحدّية، للاستخدام في التصفح) |
| `created_at_min` | int | لا | يُرجع فقط المهام التي تأتي بعد بشكل صارم طابع Unix الزمني هذا (لا يشمل القيمة الحدّية) |

### مثال على الكود

كود CURL المقابل كما يلي:

```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 '{
  "action": "retrieve_batch",
  "limit": 20
}'
```

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

بعد نجاح الطلب، ستُرجع API قائمة المهام السابقة للمستخدم الحالي:

```json theme={null}
{
  "count": 2,
  "items": [
    {
      "id": "f57e99c4f60f4373a15517742ce2357d",
      "started_at": 1769262721.823,
      "finished_at": 1769264698.3,
      "elapsed": 1976.477,
      "status": "succeeded",
      "progress": {
        "percent": 100,
        "stage": "producing",
        "message": "rendering scene 2"
      },
      "request": {
        "prompt": "…",
        "langs": [
          "zh-cn",
          "en"
        ],
        "aspect": "9:16",
        "duration": 20
      },
      "response": {
        "success": true,
        "data": {
          "variants": [
            {
              "lang": "zh-cn",
              "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-003"
            }
          ]
        }
      }
    }
  ]
}
```

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

* `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`: خطأ داخلي في الخادم، حدث خطأ ما على الخادم.

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

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## الخلاصة

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

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

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


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