عملية التقديم
لاستخدام 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 لتوجيه إنشاء الفيديو:
تحرير الفيديو / فيديو مرجعي (إدخال فيديو، إنشاء فيديو)
يدعم مباشرة 「إدخال مقطع فيديو، وإنشاء مقطع فيديو جديد」: مرّر رابط فيديو مرجعيًا واحدًا (بحد أقصى 1) في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: خطأ داخلي في الخادم أو فشل الإنشاء من المصدر العلوي.

