تحليل الفيديو المعماري باستخدام Gemini API: دليل تطبيقي خطوة بخطوة

ما الذي ستتعلمه في هذا الدليل؟

يمكن استخدام Gemini API لاستخراج المعلومات من مقاطع الفيديو والإجابة عن الأسئلة المتعلقة بمحتواها. يتناول هذا الدليل خطوات اختيار طريقة الإرسال المناسبة لتحليل فيديوهات مثل عروض المشاريع المعمارية، وتسجيلات مواقع البناء، والجولات في المساحات، إلى جانب انتظار معالجة الملف وإعداد مطالبات مناسبة للمهمة. تستطيع نماذج Gemini وصف الفيديو واستخراج المعلومات منه والإشارة إلى طوابع زمنية محددة. وبذلك يمكن طلب ملخص أو إجابة مركّزة للمراجعة بدلًا من مشاهدة تسجيل طويل يدويًا من بدايته إلى نهايته.

الأمثلة هنا مخصصة لفهم الفيديوهات الموجودة، لا لإنشائها. يعرّف دليل Google لإنشاء الفيديوهات Gemini Omni Flash لهذه المهمة، أما فهم الفيديو فهو استخدام منفصل. ويساعد الحفاظ على هذا التمييز في تقليل احتمال اختيار نموذج أو سير عمل غير مناسب عند طلب التحليل.

المتطلبات

يتطلب سير العمل إمكانية الوصول إلى Gemini API، وملف فيديو أو فيديو متاحًا للجميع على YouTube، ومطالبة نصية. يستخدم المثال الرسمي عميل Python ‏google-genai وFiles API وInteractions API. ولأن المصدر لا يحدد إصدارًا معينًا من SDK أو خطوات إنشاء الحساب، فلن نذكر رقم إصدار أو شروط تسجيل. أكمل مصادقة عميل API بما يتناسب مع بيئتك؛ يستخدم مثال REST في المصدر المتغير GEMINI_API_KEY.

اختر طريقة الإرسال بناءً على حجم الملف والحاجة إلى إعادة استخدامه:

• Files API: يوصي المصدر بهذه الطريقة للملفات التي يتجاوز حجمها 100 MB، ومقاطع الفيديو الطويلة، والمحتوى الذي سيُستخدم مجددًا. وتبلغ السعة المذكورة في الوثائق 20 GB للاستخدام المدفوع و2 GB للاستخدام المجاني.

• Cloud Storage Registration: يذكر المصدر حدًا يبلغ 2 GB لكل ملف، من دون حد للتخزين؛ وهي طريقة مخصصة للمحتوى الكبير الذي سيُخزّن مدة طويلة ويُستخدم مجددًا.

• البيانات المضمّنة: تشير الوثائق إلى ملاءمتها للملفات الصغيرة. وتوصي التعليمات التفصيلية بإرسال مقاطع الفيديو القصيرة بهذه الطريقة عندما يقل الحجم الإجمالي للطلب عن 20 MB؛ لذا اعتمد عمليًا حد 20 MB الأكثر تقييدًا.

• رابط YouTube: طريقة إدخال مدعومة لمقاطع الفيديو المتاحة للجميع.

تحليل الفيديو خطوة بخطوة

1. حدّد هدف المراجعة

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

على سبيل المثال، يمكن استخدام المطالبة التالية للحصول على ملخص قصير ومنظم لملاحظات مستخلصة من فيديو لمساحة داخلية:

Analyze this interior architecture video. Summarize the visible spaces, circulation, lighting, and materials. Use only details that can be observed in the video, and organize the response by topic.

تجمع هذه المطالبة عناصر المساحة والحركة والإضاءة والمواد التي يمكن رؤيتها في الفيديو ضمن عناوين منفصلة. كما تطلب الاستناد إلى التفاصيل القابلة للملاحظة فقط، بدلًا من الجزم باسم مادة لا يمكن تمييزها في الصورة.

2. اختر طريقة الإرسال المناسبة للملف

إذا كان الفيديو كبيرًا أو طويلًا أو سيُعاد استخدامه في مطالبات لاحقة، ففضّل Files API. ويمكن التفكير في الإرسال المضمّن للملفات القصيرة، مع الانتباه إلى بقاء إجمالي الطلب دون 20 MB. أما إذا كان الفيديو متاحًا للجميع على YouTube، فضع طريقة الرابط في الحسبان. تحقّق من أحجام الملفات وشروط الاستخدام قبل الإرسال؛ فالمصدر يورد معلومات السعة بشكل منفصل للاستخدام المجاني والمدفوع.

3. ارفع الملف باستخدام Files API وانتظر معالجته

يرفع مثال Python الرسمي الملف عبر client.files.upload ويتحقق من حالته إلى أن تصبح ACTIVE. لا يعني اكتمال رفع الملف أنه جاهز للتحليل فورًا؛ انتظر حتى تنتهي معالجته. في المثال أدناه، يجري الاستعلام عن الحالة بفواصل زمنية مدتها خمس ثوانٍ. يستند هذا الكود إلى مثال متاح بموجب ترخيص مفتوح في المصدر:

from google import genai
import time

client = genai.Client()
myfile = client.files.upload(file="path/to/sample.mp4")

while not myfile.state or myfile.state.name != "ACTIVE":
    print("Processing video...")
    time.sleep(5)
    myfile = client.files.get(name=myfile.name)

استبدل path/to/sample.mp4 بمسار الملف المراد تحليله. يوضح مثال المصدر استخدام مرجع الملف كمدخل فيديو بعد أن يصبح جاهزًا. وإذا أخفقت المعالجة، فلا تعتبر الملف جاهزًا للتحليل؛ تحقّق من تقدم الحالة.

4. أرسل الفيديو مع المطالبة إلى Interactions API

بعد أن تصبح حالة الملف ACTIVE، أضف URI الفيديو والمطالبة النصية إلى مدخلات التفاعل نفسه. يستخدم المثال في المصدر اسم النموذج gemini-3.8-flash. وتوجّه المطالبة التالية التحليل إلى التسلسل المكاني والانتقالات في فيديو عرض تقديمي:

Review this architectural walkthrough in chronological order. Describe how the spaces connect, identify visible transitions, and refer to relevant moments with timestamps when possible. Do not infer dimensions or design intent that the video does not show.

يساعد طلب الطوابع الزمنية على ربط الملاحظات بأجزاء محددة من التسجيل. كما أن التصريح بوضوح بعدم استنتاج نتائج لا يمكن التحقق منها عبر الفيديو، مثل القياسات أو نية التصميم، يبقي الإجابة ضمن حدود المراجعة البصرية.

5. ضيّق نطاق النتائج بما يخدم المشروع

إذا كانت الإجابة الأولى عامة، فاجعل سؤال المتابعة يركّز على موضوع محدد بدلًا من إعادة وصف الفيديو. يشرح دليل Google للفيديوهات التحرير عبر محادثة متعددة الجولات في سياق إنشاء الفيديو، بينما تذكر وثيقة فهم الفيديو إمكانية طرح الأسئلة عن الفيديوهات والإشارة إلى الطوابع الزمنية. في سيناريو التحليل هذا، قيّد السؤال بالقسم أو نوع الملاحظة المطلوب مراجعته.

From the video, list only the visible changes in lighting and material appearance between the main spaces. For each observation, include a timestamp when available and mark anything uncertain as unclear.

تقصر هذه المطالبة الإجابة على التغييرات في الإضاءة ومظهر المواد. ويساعد طلب وضع علامة «غير واضح» على التفاصيل غير المؤكدة في تجنب عرضها على أنها معلومات قاطعة عندما تكون جودة الصورة منخفضة أو تكون التفاصيل خارج إطار الفيديو.

أخطاء شائعة

• إرسال فيديو كبير بطريقة البيانات المضمّنة: ترى التعليمات التفصيلية في المصدر أن الإرسال المضمّن مناسب لمقاطع الفيديو القصيرة التي يقل إجمالي طلبها عن 20 MB. استخدم Files API للملفات الكبيرة.

• طلب التحليل قبل معالجة الملف: تحقّق من وصول الحالة إلى ACTIVE بعد الرفع؛ إذ يستعلم المثال عن حالة الملف بانتظام.

• صياغة مطالبة عامة أو مبهمة: بدلًا من طلب مثل «حلّل الفيديو»، ركّز على هدف واحد، كالتلخيص أو الانتقالات المكانية أو المواد الظاهرة.

• توقع معلومات غير موجودة في الصورة: يفيد فهم الفيديو في مراجعة المعلومات المرئية في المحتوى؛ ولا ينبغي افتراض أنه يؤكد قياسات المشروع أو قرارات التصميم غير الواردة في التسجيل.

• الخلط بين دليل إنشاء الفيديو ودليل تحليله: لفهم فيديو موجود، اتبع وثائق فهم الفيديو. وتفيد Google بأن Veo 3.1 Preview سيُغلق في Gemini API بتاريخ 22 أكتوبر 2026، وبالانتقال إلى Gemini Omni Flash لإنشاء الفيديو؛ ولا يحل هذا التغيير محل خطوات التحليل.

الاستخدام في سير عمل العمارة والتصميم الداخلي وarchviz

يمكن لفرق العمارة والتصميم الداخلي تجربة هذه الطريقة لاستخلاص ملخص أولي للملاحظات من جولة مشروع أو تسجيل لمساحة، والعثور على المقاطع المهمة باستخدام الطوابع الزمنية، والإجابة عن أسئلة متعلقة بالتسجيل. كما يمكن لفرق archviz مراجعة سير عمل الأسئلة والأجوبة حول محتوى عرض فيديو موجود. لكن ينبغي حصر النتائج بما يعرضه الفيديو، والتحقق على نحو منفصل من المسائل التي لا يمكن تأكيدها عبر التسجيل، مثل القياسات والملاءمة التقنية وإمكانية التطبيق في المشروع.

نظرًا إلى اختلاف حدود Files API بين الاستخدام المجاني والمدفوع، ينبغي للفرق مراجعة حجم ملف المشروع وشروط الوصول التي تستخدمها قبل إرساله. لا يوضح المصدر متطلبات الأجهزة أو تفاصيل الأسعار أو التكامل مع البرامج المحلية؛ لذا لا تفترض أن سير العمل مرتبط بأدوات النمذجة أو التصيير الحالية.

الخطوات التالية

ابدأ بفيديو قصير لمشروع مصرح باستخدامه، وجرّب مطالبة التلخيص؛ ثم أضف أسئلة متابعة تطلب طوابع زمنية أو أنواعًا محددة من الملاحظات. إذا كان الملف كبيرًا أو سيُستخدم مجددًا، فضع خيار Files API في الحسبان. وقبل نقل النتائج إلى ملاحظات المشروع، افتح الفيديو عند الأوقات ذات الصلة وتحقق من ملاحظات النموذج. للتفاصيل التطبيقية المتعلقة برفع الملفات أو اختيار النموذج، ارجع إلى وثائق Gemini API الرسمية لفهم الفيديو وإنشائه.

المصدر والترخيص

أُعد هذا الدليل باللغة التركية استنادًا إلى المعلومات الواردة في وثائق Google الخاصة بفهم الفيديوهات وإنشائها عبر Gemini API. كلا المصدرين مرخّص بموجب CC BY 4.0. ومثال كود Python مقتبس من وثيقة فهم الفيديو المتاحة بموجب ترخيص مفتوح.