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

# Development Dreamina Tasks

> Dreamina API guide - Ace Data Cloud

## واجهة برمجة تطبيقات Dreamina Tasks والتكامل والاستخدام

تُستخدم واجهة برمجة تطبيقات Dreamina Tasks للاستعلام عن نتائج تنفيذ مهام فيديوهات الشخصيات الرقمية التي تم إنشاؤها بواسطة [واجهة برمجة تطبيقات Dreamina Video Generation](https://platform.acedata.cloud/documents/dreamina-videos-integration). عند تمرير `callback_url` أو `async: true` في واجهة التوليد، ستعيد الواجهة على الفور `task_id`، يمكنك من خلال هذه الواجهة الاستعلام عن حالة المهمة وعنوان الفيديو النهائي باستخدام `task_id` أو `trace_id`. **هذه الواجهة مجانية.**

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

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

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

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

## معلمات الطلب

**رؤوس الطلب**

* `accept`: تحديد استلام استجابة بتنسيق JSON، املأ بـ `application/json`.
* `authorization`: مفتاح استدعاء API، بالتنسيق `Bearer {token}`.
* `content-type`: املأ بـ `application/json`.

**جسم الطلب**

| المعلمة | النوع | مطلوب | الشرح |
| - | - | - | - |
| `action` | string | لا | نوع العملية، `retrieve` (افتراضي، استعلام فردي) أو `retrieve_batch` (استعلام جماعي) |
| `id` | string | لا | معرف المهمة المراد الاستعلام عنها (الذي تم إرجاعه عند إنشاء الفيديو) |
| `trace_id` | string | لا | معرف تتبع المهمة المراد الاستعلام عنها، يمكن استخدامه بدلاً من `id` |
| `ids` | string\[] | لا | قائمة معرفات المهام للاستعلام الجماعي، تستخدم مع `retrieve_batch` |

> عند الاستعلام عن مهمة فردية، يجب تقديم إما `id` أو `trace_id`.

## استعلام عن مهمة فردية

### CURL

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/dreamina/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "retrieve",
  "id": "362b4fed-67bd-11f1-ad11-00163e57d510"
}'
```

### بايثون

```python theme={null}
import requests

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

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

payload = {
    "action": "retrieve",
    "id": "362b4fed-67bd-11f1-ad11-00163e57d510"
}

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

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

بعد نجاح الطلب، تعيد واجهة برمجة التطبيقات تفاصيل تلك المهمة. `request` هو جسم الطلب عند إنشاء المهمة، و`response` هو جسم الاستجابة بعد إكمال المهمة، حيث `data.video_url` هو عنوان الفيديو الناتج:

```json theme={null}
{
  "id": "362b4fed-67bd-11f1-ad11-00163e57d510",
  "trace_id": "a9063166-26ed-4451-85b5-54e896817c69",
  "request": {
    "model": "omnihuman-1.5",
    "image_url": "https://cdn.acedata.cloud/4hfydw.jpg",
    "audio_url": "https://cdn.acedata.cloud/6f7d62b18b.wav"
  },
  "response": {
    "success": true,
    "data": {
      "task_id": "362b4fed67bd11f1ad1100163e57d510",
      "status": "done",
      "video_url": "https://cdn.acedata.cloud/634d760216.mp4",
      "image_url": "https://cdn.acedata.cloud/4hfydw.jpg",
      "audio_url": "https://cdn.acedata.cloud/6f7d62b18b.wav"
    }
  }
}
```

شرح الحقول:

* `id`: المعرف الفريد لمهمة إنشاء الفيديو هذه.
* `trace_id`: معرف تتبع الطلب الحالي، يستخدم لاستكشاف الأخطاء.
* `request`: محتوى الطلب المقدم عند إنشاء المهمة.
* `response`: محتوى الاستجابة الذي يتم إرجاعه بعد إكمال المهمة. عندما يكون `response.data.status` هو `done`، فإن `response.data.video_url` هو عنوان الفيديو النهائي.
* `created_at`: وقت إنشاء المهمة، طابع زمني Unix (ثوانٍ، عائم).
* `started_at`: وقت بدء تنفيذ المهمة، طابع زمني Unix (ثوانٍ، عائم).
* `finished_at`: وقت إكمال المهمة، طابع زمني Unix (ثوانٍ، عائم). لا يتم إرجاع هذا الحقل إذا لم تكتمل المهمة.
* `elapsed`: الوقت المستغرق لتنفيذ المهمة، بوحدة الثواني (عائم، يحتفظ بـ 3 أرقام عشرية). لا يتم إرجاع هذا الحقل إذا لم تكتمل المهمة.

> إذا كانت المهمة لم تكتمل بعد، قد يكون `status` في حالة غير `done`؛ إذا كانت المهمة غير موجودة أو لم يتم إنتاج النتائج بعد، ستعيد الواجهة كائنًا فارغًا `{}`، يرجى المحاولة لاحقًا.

## استعلام جماعي عن المهام

قم بتعيين `action` إلى `retrieve_batch`، ومرر مصفوفة `ids`:

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/dreamina/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "retrieve_batch",
  "ids": [
    "362b4fed-67bd-11f1-ad11-00163e57d510",
    "0c0b4d3a-2f1e-4a6b-9c2d-2b3c4d5e6f70"
  ]
}'
```

في نتيجة الإرجاع، `items` هو مصفوفة تفاصيل المهام الجماعية (كل عنصر يتوافق مع تنسيق نتيجة الاستعلام الفردي)، و`count` هو عدد المهام التي تم إرجاعها في هذه المرة.

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

عند مواجهة أخطاء عند استدعاء واجهة برمجة التطبيقات، ستعيد رمز الخطأ والمعلومات المقابلة:

* `400 bad_request`: خطأ في الطلب، قد يكون هناك نقص في المعلمات الضرورية مثل `id` / `trace_id`.
* `401 invalid_token`: غير مصرح، رمز التفويض غير صالح أو مفقود.
* `429 too_many_requests`: عدد الطلبات كبير جدًا، تم تجاوز حد السرعة.
* `500 api_error`: خطأ داخلي في الخادم.

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

```json theme={null}
{
  "error": {
    "code": "bad_request",
    "message": "id or trace_id is required to retrieve a task"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## الخاتمة

من خلال هذه الوثيقة، أصبحت على دراية بكيفية استخدام واجهة برمجة تطبيقات Dreamina Tasks للاستعلام عن نتائج مهام فيديوهات الشخصيات الرقمية الفردية أو الجماعية. بالاشتراك مع واجهة التوليد باستخدام `callback_url` / `async` في وضع غير المتزامن، يمكنك تحقيق سحب مستقر. إذا كان لديك أي استفسارات، لا تتردد في الاتصال بفريق الدعم الفني لدينا.


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