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

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

لاستخدام Gemini Videos Generation API، انتقل أولاً إلى وحدة تحكم Ace Data Cloud للحصول على API Token الخاص بك، واحتفظ به للاستخدام لاحقًا. إذا لم تكن قد سجلت الدخول أو أنشأت حسابًا بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك إلى التسجيل وتسجيل الدخول، وبعد الإكمال ستعود تلقائيًا إلى الصفحة الحالية. يمكن لـ API Token واحد استدعاء جميع خدمات المنصة، ولا حاجة للتقديم بشكل منفصل لكل خدمة. ستتلقى رصيدًا مجانيًا عند أول تقديم، ويمكنك التجربة مجانًا؛ وعند عدم كفاية الرصيد، يمكنك شحن الرصيد العام في وحدة التحكم.
📘 الوثائق الكاملة: Gemini Videos Generation API →

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

لنتعرف أولاً على طريقة الاستخدام الأساسية، بإدخال نص المطالبة 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」 لإجراء الاختبار، وستكون النتيجة التي تحصل عليها مشابهة لما يلي:
تحتوي نتيجة الإرجاع على عدة حقول، وهي كما يلي:
  • 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 المقابل كما يلي:
كود Python المقابل كما يلي:

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

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

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

يدعم إدخال مقطع فيديو مباشرةً لإنشاء مقطع فيديو جديد: مرّر رابط فيديو مرجعيًا واحدًا (بحد أقصى) في video_urls، وقدّم في الوقت نفسه صورة مرجعية واحدة على الأقل في image_urls، ثم استخدم prompt لوصف تأثير التحرير المطلوب (تغيير النمط، تبديل المشهد، إضافة العناصر أو حذفها، وغير ذلك). فيما يلي مثال حقيقي كامل: تحويل فيديو لشاطئ مشمس إلى مشهد شتوي تتساقط فيه الثلوج بكثافة، مع الحفاظ على توزيع الشاطئ وأشجار النخيل والقارب الصغير. يستغرق تحرير الفيديو وقتًا أطول (نحو 6.5 دقائق في هذا المثال)، لذا يُرسل بشكل غير متزامن عبر async: true:
بعد الإرسال، تعيد الواجهة فورًا task_id:
بعد ذلك، استخدم task_id باعتباره id للاستعلام الدوري عن Gemini Tasks API. بعد اكتمال المهمة، يمكنك الحصول على الفيديو الجديد المُنشأ (هذه هي النتيجة الفعلية المعادة لهذا المثال):
للحصول على نتيجة بدقة أعلى، اضبط resolution على 1080p (مع إبقاء بقية المعلمات دون تغيير).
تنبيه: روابط وسائط الإدخال/الإخراج في الأمثلة هي نتائج مُولَّدة حقيقية. تحتوي روابط الفيديوهات والصور التي تُنشئها المنصة على مدة صلاحية، وستصبح غير صالحة بعد انتهائها. يُرجى تنزيل النتائج وحفظها في مساحة التخزين الخاصة بك فور الحصول عليها.
ملاحظة: الحد الأقصى لمقاطع الفيديو المرجعية هو مقطع واحد؛ وعند توفير video_urls، يجب توفير صورة واحدة على الأقل من image_urls، وإلا فسيُرجع خطأ المعلمات التالي:

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

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

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

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

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

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