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

# تعليمات تكامل Gemini Videos Generation API

> Gemini AI API guide - Ace Data Cloud

ستعرض هذه المقالة تعليمات تكامل Gemini Videos Generation API، الذي يمكنه إنشاء فيديوهات Google Gemini (omni-flash) من خلال إدخال مطالبات نصية (وصور مرجعية اختيارية).

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

لاستخدام Gemini Videos Generation API، انتقل أولاً إلى [وحدة تحكم 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).

> 📘 الوثائق الكاملة: [Gemini Videos Generation API →](https://platform.acedata.cloud/documents/gemini-videos)

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

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

يمكنك أن ترى أننا قمنا هنا بتعيين Request Headers، وتشمل:

* `accept`: صيغة نتيجة الاستجابة التي تريد تلقيها، املأ هنا `application/json`، أي صيغة JSON.
* `authorization`: مفتاح استدعاء API، وبعد التقديم يمكنك اختياره مباشرة من القائمة المنسدلة.

كما تم تعيين Request Body، ويشمل:

* `prompt`: نص المطالبة الذي يصف محتوى الفيديو الذي تريد إنشاؤه، **مطلوب**.
* `model`: نموذج إنشاء الفيديو، يدعم حاليًا `omni-flash` فقط، والقيمة الافتراضية هي `omni-flash`.
* `aspect_ratio`: نسبة العرض إلى الارتفاع للفيديو المُنشأ، يمكن اختيار `16:9` (أفقي) أو `9:16` (عمودي)، والقيمة الافتراضية هي `16:9`.
* `resolution`: دقة الإخراج الاختيارية، يمكن اختيار `720p` أو `1080p`، والقيمة الافتراضية هي `720p`.
* `image_urls`: مصفوفة روابط صور مرجعية اختيارية، تُستخدم لتوجيه إنشاء الفيديو، وسيتم تجاهل العناصر الفارغة. عند استخدام `video_urls` لتحرير الفيديو، تكون هذه المعلمة مطلوبة (صورة واحدة على الأقل).
* `video_urls`: مصفوفة روابط فيديوهات مرجعية اختيارية (بحد أقصى 1)، تُستخدم في **تحرير الفيديو / مرجع الفيديو**؛ عند تقديمها، يجب أيضًا تقديم صورة واحدة على الأقل في `image_urls`.
* `callback_url`: عنوان الاستدعاء غير المتزامن، بعد تعيينه ستُرجع API فورًا `task_id`، وعند اكتمال المهمة سترسل النتيجة عبر POST إلى هذا العنوان.
* `async`: اختياري، عند تعيينه إلى `true` تُرجع الواجهة فورًا `task_id`، ولا حاجة لتقديم `callback_url`، ثم يتم الحصول على النتيجة عبر الاستعلام الدوري من خلال واجهة الاستعلام عن المهمة المقابلة.

انقر على زر 「Try」 لإجراء الاختبار، وستكون النتيجة التي تحصل عليها مشابهة لما يلي:

```json theme={null}
{
  "success": true,
  "task_id": "9258c45f-bed9-4dde-81c2-a70a710a6904",
  "trace_id": "862d6aae-cec0-407f-9524-bc1be2291bcb",
  "data": [
    {
      "id": "dc4b7292-070c-49a8-8183-919bdf8ad59e",
      "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/9258c45f-bed9-4dde-81c2-a70a710a6904-418c13e0605f.mp4",
      "state": "succeeded",
      "aspect_ratio": "16:9",
      "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden"
    }
  ],
  "started_at": 1784112953.856,
  "finished_at": 1784113021.328,
  "elapsed": 67.472,
  "cost": {
    "amount": 1.932,
    "currency": "credit",
    "list_amount": 2.1
  }
}
```

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

* `success`: ما إذا كان طلب إنشاء الفيديو هذا ناجحًا.
* `task_id`: معرّف مهمة إنشاء الفيديو هذه.
* `trace_id`: معرّف التتبع لهذا الطلب، ويُستخدم لاستكشاف المشكلات وإصلاحها.
* `data`: قائمة نتائج الفيديوهات المُنشأة.
  * `id`: المعرّف الفريد للفيديو المُنشأ.
  * `video_url`: عنوان رابط الفيديو المُنشأ (يكون `null` عندما تكون `state` هي `pending`).
  * `state`: حالة مهمة إنشاء الفيديو، ويمكن أن تكون `pending` / `succeeded` / `failed`.
  * `aspect_ratio`: نسبة العرض إلى الارتفاع لهذا الفيديو، وتتوافق مع معلمات الطلب.
  * `prompt`: نص المطالبة المستخدم لإنشاء هذا الفيديو.

عند الإرجاع المتزامن، ستتضمن الطبقة العليا أيضًا حقولًا مثل `started_at` و`finished_at` و`elapsed` (المدة المستغرقة، بالثواني) و`cost` (الرسوم المخصومة هذه المرة، بوحدة Credit).

نحتاج فقط إلى الحصول على الفيديو المُنشأ وفقًا لعنوان رابط `video_url` في `data` ضمن النتيجة.

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

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/gemini/videos' \
-H 'authorization: Bearer ${bearer_token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
  "model": "omni-flash",
  "aspect_ratio": "16:9"
}'
```

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

```python theme={null}
import requests

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

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

payload = {
    "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
    "model": "omni-flash",
    "aspect_ratio": "16:9"
}

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

## إنشاء فيديو من صورة

إذا كنت تريد إنشاء فيديو استنادًا إلى صور مرجعية، يمكنك تمرير رابط صورة واحد أو عدة روابط صور في `image_urls` لتوجيه إنشاء الفيديو:

```json theme={null}
{
  "prompt": "The woman slowly turns around and smiles at the camera, gentle breeze",
  "model": "omni-flash",
  "aspect_ratio": "9:16",
  "image_urls": [
    "https://cdn.acedata.cloud/assets/examples/nanobanana/e44bfceb-1458-4b4b-9d10-21024678f1a3-5ccb6e83b402.png"
  ]
}
```

## تحرير الفيديو / فيديو مرجعي (إدخال فيديو، إنشاء فيديو)

يدعم مباشرة 「إدخال مقطع فيديو، وإنشاء مقطع فيديو جديد」: مرّر رابط فيديو مرجعيًا واحدًا (بحد أقصى 1) في `video_urls`، وقدّم **في الوقت نفسه** صورة مرجعية واحدة على الأقل في `image_urls` (متطلب إلزامي من المصدر)، ثم استخدم `prompt` لوصف تأثير التحرير المطلوب (تغيير النمط، تغيير المشهد، إضافة العناصر أو حذفها، إلخ).

فيما يلي مثال حقيقي كامل — تحويل فيديو لشاطئ مشمس إلى مشهد شتوي تتساقط فيه الثلوج بكثافة، مع الحفاظ في الوقت نفسه على تخطيط الشاطئ وأشجار جوز الهند والقارب الصغير. يستغرق تحرير الفيديو وقتًا أطول (حوالي 6.5 دقائق في هذا المثال)، لذلك يتم الإرسال بشكل غير متزامن باستخدام `async: true`:

```json theme={null}
{
  "prompt": "Turn this sunny tropical beach into a snowy winter scene with heavy falling snow and overcast sky; keep the same beach, palm trees and boat layout.",
  "model": "omni-flash",
  "aspect_ratio": "9:16",
  "resolution": "720p",
  "image_urls": [
    "https://cdn.acedata.cloud/99289603bd.png"
  ],
  "video_urls": [
    "https://cdn.acedata.cloud/assets/examples/seedance/dd3dc063-3383-4f29-bedc-e771a096758c-044e05281a2a.mp4"
  ],
  "async": true
}
```

بعد الإرسال، تُرجع الواجهة فورًا `task_id`:

```json theme={null}
{
  "task_id": "cd68b4ee-de70-4c94-ac69-997a3fed0284"
}
```

بعد ذلك، استخدم `task_id` هذا كـ `id` للاستعلام الدوري عن [Gemini Tasks API](https://platform.acedata.cloud/documents/gemini-tasks)، وبعد اكتمال المهمة يمكنك الحصول على الفيديو الجديد المُنشأ (هذه هي نتيجة الإرجاع الفعلية لهذا المثال):

```json theme={null}
{
  "success": true,
  "task_id": "cd68b4ee-de70-4c94-ac69-997a3fed0284",
  "trace_id": "5b22104b-5a6d-4a4f-8063-69acae1dc1c6",
  "data": [
    {
      "id": "e125d316-3d26-4c65-9413-55baf6be46b8",
      "video_url": "https://cdn.acedata.cloud/assets/examples/sora/cd68b4ee-de70-4c94-ac69-997a3fed0284-c5603ef983da.mp4",
      "state": "succeeded",
      "aspect_ratio": "9:16",
      "prompt": "Turn this sunny tropical beach into a snowy winter scene with heavy falling snow and overcast sky; keep the same beach, palm trees and boat layout."
    }
  ],
  "started_at": 1784084482.914,
  "finished_at": 1784084877.09,
  "elapsed": 394.176,
  "cost": {
    "amount": 1.932,
    "currency": "credit",
    "list_amount": 2.1
  }
}
```

إذا كنت بحاجة إلى نتائج بدقة أعلى، يمكنك ضبط `resolution` إلى `1080p` (مع بقاء المعلمات الأخرى دون تغيير).

> تلميح: روابط الوسائط المُدخلة / المُخرجة في المثال هي جميعها نتائج إنشاء حقيقية. **روابط الفيديوهات والصور التي تُنشئها المنصة لها مدة حفظ، وستصبح غير صالحة بعد انتهائها**، يُرجى تنزيلها وحفظها في مساحة التخزين الخاصة بك في الوقت المناسب بعد الحصول على النتائج.

> تنبيه: الحد الأقصى لمقاطع الفيديو المرجعية هو مقطع واحد؛ وعند توفير `video_urls` يجب توفير صورة واحدة على الأقل في `image_urls`، وإلا فسيتم إرجاع خطأ المعلمات التالي:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "bad_request",
    "message": "image_urls (at least one reference image) is required when video_urls is provided."
  }
}
```

## الاستدعاء غير المتزامن

يتطلب إنشاء الفيديو وقتًا معينًا للمعالجة. إذا كنت لا ترغب في إبقاء اتصال طويل مفتوحًا للانتظار، يمكنك تمرير `callback_url`، وعندها ستُرجع API فورًا `task_id`، وبعد اكتمال المهمة سترسل النتيجة النهائية عبر POST إلى هذا العنوان:

```json theme={null}
{
  "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
  "model": "omni-flash",
  "aspect_ratio": "16:9",
  "callback_url": "https://your-domain.com/callback/gemini"
}
```

تكون النتيجة المُرجعة فورًا كما يلي:

```json theme={null}
{
  "task_id": "04a043bd-6b23-4b4e-945c-ce48158c3eee"
}
```

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

إذا استخدمت الاستدعاء غير المتزامن أو رغبت في الاستعلام بشكل استباقي عن حالة المهمة، يمكنك استخدام [Gemini Tasks API](https://platform.acedata.cloud/documents/gemini-tasks) (`POST https://api.acedata.cloud/gemini/tasks`) للاستعلام عن أحدث حالة ونتيجة للمهمة استنادًا إلى `task_id`. مرّر `task_id` المُعاد عند إنشاء الفيديو في نص الطلب كـ `id`:

```json theme={null}
{
  "id": "04a043bd-6b23-4b4e-945c-ce48158c3eee"
}
```

تكون النتيجة المُرجعة بعد اكتمال المهمة مشابهة لما يلي، ويكون هيكل `response.data` متسقًا مع هيكله عند الإنشاء المتزامن (أثناء الإنشاء تكون قيمة `state` هي `pending` و`video_url` هي `null`):

```json theme={null}
{
  "id": "04a043bd-6b23-4b4e-945c-ce48158c3eee",
  "type": "videos",
  "request": {
    "model": "omni-flash",
    "prompt": "A time-lapse of clouds over snow mountains at sunrise",
    "aspect_ratio": "16:9",
    "async": true
  },
  "response": {
    "success": true,
    "task_id": "04a043bd-6b23-4b4e-945c-ce48158c3eee",
    "data": [
      {
        "id": "486ebd5a-6a4b-406c-84ae-33835de4fe19",
        "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
        "state": "succeeded",
        "aspect_ratio": "16:9",
        "prompt": "A time-lapse of clouds over snow mountains at sunrise"
      }
    ],
    "elapsed": 96.716,
    "cost": {
      "amount": 1.932,
      "currency": "credit",
      "list_amount": 2.1
    }
  }
}
```

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

عند حدوث مشكلة في الطلب، ستُرجع API رمز الخطأ والوصف المقابلين، ومن الأخطاء الشائعة ما يلي:

* `400`: معلمات الطلب غير صحيحة، مثل غياب `prompt` أو أن قيمة `aspect_ratio` غير صالحة.
* `401`: فشل المصادقة، الرمز المميز غير صالح أو لا يتطابق مع API.
* `403`: الرصيد غير كافٍ، أو تم رفض الطلب لأن النص التوجيهي طابق مراجعة المحتوى.
* `500`: خطأ داخلي في الخادم أو فشل الإنشاء من المصدر العلوي.


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