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

