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

> Dreamina API guide - Ace Data Cloud

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

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

توليد فيديوهات لشخصيات رقمية مدفوعة بالصوت (OmniHuman 1.5). قدم صورة لشخص ما ومقطع صوتي مدفوع، لتوليد فيديو يظهر الشخص وهو يتحدث مع تزامن في حركة الشفاه.

### رأس الطلب

| الرأس | القيمة |
| - | - |
| `Authorization` | `Bearer <مفتاح API الخاص بك>` |
| `Content-Type` | `application/json` |

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

| المعلمة | النوع | مطلوب | الوصف |
| - | - | - | - |
| `model` | string | لا | النموذج، الافتراضي `omnihuman-1.5` |
| `image_url` | string | نعم | عنوان URL عام لصورة الشخص، يفضل أن تكون واضحة وواجهة أمامية |
| `audio_url` | string | نعم | عنوان URL عام للصوت المدفوع (mp3/wav)، يفضل أن يكون \< 60 ثانية |
| `prompt` | string | لا | التحكم في التعبيرات، المشاعر، الاستقرار والأسلوب |
| `mask_url` | string\[] | لا | عنوان URL لقناع الموضوع، لتحديد الكائن المدفوع في صورة متعددة الأشخاص |
| `callback_url` | string | لا | إذا تم تمريره، سيتم إرجاع `task_id` على الفور، وسيتم استدعاء هذا العنوان بعد إنشاء النتيجة |
| `async` | boolean | لا | إذا تم تعيينه إلى `true`، سيتم إرجاع `task_id` على الفور، دون الحاجة إلى `callback_url`، من خلال `/dreamina/tasks` لاستعلام النتائج |

### نصائح الإدخال

* **الصورة**: صورة شخصية واضحة، بإضاءة جيدة، هي الأفضل؛ يجب أن تكون الوجه غير محجوب، ويجب أن تشغل نسبة مناسبة من الصورة.
* **الصوت**: mp3/wav، يجب أن يكون متاحًا على الإنترنت. يفضل أن تكون مدة الصوت أقل من 60 ثانية (1080p يفضل ≤30 ثانية، 720p ≤60 ثانية).
* يجب أن يكون كل من `image_url` و `audio_url` قابلين للوصول عبر الإنترنت.

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

```json theme={null}
{
  "success": true,
  "task_id": "0c0b4d3a-2f1e-4a6b-9c2d-2b3c4d5e6f70",
  "trace_id": "a9063166-26ed-4451-85b5-54e896817c69",
  "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"
  }
}
```

### الوضع غير المتزامن والاستعلام

تقوم الواجهة بشكل افتراضي بإرجاع الفيديو النهائي بشكل متزامن. بالنسبة للمهام الطويلة، يمكن استخدام أحد وضعي التشغيل غير المتزامن:

* تمرير `callback_url`: ستقوم الواجهة بإرجاع `task_id` على الفور، وسيتم استدعاء هذا العنوان بعد إنشاء النتيجة.
* تمرير `async: true`: ستقوم الواجهة بإرجاع `task_id` على الفور، ثم من خلال `POST /dreamina/tasks` (مجاني) لاستعلام النتائج حسب `task_id` أو `trace_id`.

تفاصيل استعلام النتائج متاحة في [واجهة برمجة تطبيقات مهام Dreamina](https://platform.acedata.cloud/documents/dreamina-tasks-integration).

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

| رمز الحالة | code | المعنى |
| - | - | - |
| 400 | `bad_request` | معلمات مفقودة أو غير صالحة (مثل `image_url` / `audio_url`) |
| 401 | `authorization_missing` / `invalid_token` | مفقود أو غير صالح رمز التفويض |
| 403 | `forbidden` | رصيد/حصة غير كافية، أو عدم تفويض من المصدر |
| 429 | `too_many_requests` | عدد الطلبات كبير جدًا، تجاوز حد المعدل |
| 500 | `api_error` | خطأ داخلي في الخادم |

```json theme={null}
{
  "error": {
    "code": "bad_request",
    "message": "image_url is required (a public URL of a portrait image)"
  },
  "trace_id": "2efa9340-b21b-4e26-9e14-4aac95f343ab"
}
```

### الفوترة

يتم احتساب الرسوم بناءً على مدة الفيديو المولد، الحد الأقصى للباقة حوالي **¥1/ثانية** (مثل فيديو مدته 10 ثوانٍ حوالي ¥10).


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