Gemini API ile video analizi: Mimari içerikler için adım adım rehber

Bu rehberde ne öğreneceksiniz?

Gemini API ile bir videoyu yalnızca özetletmekle kalmayıp içeriği hakkında soru sorabilir, belirli sahneleri tarif ettirebilir ve zaman damgalarıyla ilgili bilgi isteyebilirsiniz. Bu yetenekler; mimari proje sunumlarını, iç mekân gezilerini, saha kayıtlarını veya tasarım sürecini gösteren videoları incelemek için kullanılabilir. Aşağıdaki adımlar, videoyu uygun biçimde girdi olarak sunmaya ve soruyu netleştirmeye odaklanıyor.

Örnek istemler, mimarlık ve iç mekân iş akışlarına göre özgün olarak hazırlandı. Belgelerdeki temel yaklaşım ise video dosyasını bir istekle modele iletmek ve aynı istekte videoyla ilgili metin talimatı vermek.

Gereksinimler ve girdi seçimi

Başlamak için Gemini API’ye erişim, API istemcisinin yapılandırıldığı bir çalışma ortamı ve analiz edilecek video gerekir. Resmî kılavuzda Python, JavaScript, Go ve REST örnekleri yer alıyor. Python örneği google paketinden genai modülünü içe aktarıyor; belirli bir SDK sürümü belirtilmediğinden burada sürüm numarası vermiyoruz.

Girdi yöntemini dosyanın boyutu ve kullanım biçimine göre seçin:

• Files API: Büyük dosyalar, uzun videolar ve tekrar kullanılacak içerikler için öneriliyor. Kılavuzdaki tablo, üst sınırı ücretli kullanımda 20 GB, ücretsiz kullanımda 2 GB olarak veriyor. Yüklenen dosyanın işlenmesini bekleyip dönen dosya referansını içerik isteğinde kullanabilirsiniz.

• Satır içi veri: Küçük ve tek seferlik videolar için kullanılabiliyor. Kılavuzun farklı bölümlerinde sınır, tabloda 100 MB altı; uygulama açıklamasında ise toplam istek için 20 MB altı olarak geçiyor. Bu nedenle satır içi yöntem seçilecekse daha ihtiyatlı olan 20 MB toplam istek sınırını esas alın.

• YouTube URL’si: Herkese açık videolar doğrudan girdi olarak verilebiliyor. Bu özellik önizleme aşamasında; fiyatlandırma ve hız sınırlarının değişebileceği belirtiliyor. Ücretsiz katmanda günlük 8 saatten fazla YouTube videosu yüklenemiyor; ücretli katman için süreye dayalı bir sınır belirtilmiyor.

Cloud Storage kayıt yöntemi de dokümanda yer alıyor: dosya başına üst sınır 2 GB ve depolama için sınır belirtilmiyor. Bu yöntem, kalıcı ve yeniden kullanılabilir dosyalar için seçenek olarak sunulmuş.

Adım adım video analizi

1. Videoyu ve hedef soruyu belirleyin. Önce videonun tamamını mı özetlemek, yoksa belirli bir anı mı bulmak istediğinizi netleştirin. Örneğin, bir iç mekân turunda dolaşımın başladığı yeri aramak, genel bir özet istemekten farklı bir görevdir.

2. Uygun girdi yöntemini seçin. Küçük, kısa ve tek seferlik bir klipte satır içi veri düşünülebilir. Toplam istek 20 MB’ı aşacaksa, video uzun veya tekrar kullanılacaksa Files API kılavuzdaki tercih edilen yoldur. YouTube seçeneğinde videonun herkese açık olması gerekir.

3. Dosyayı isteğe ekleyin. Resmî Python örneğinde dosya client.files.upload(...) ile yükleniyor; ardından dönen dosya nesnesi ve metin talimatı birlikte client.models.generate_content(...) çağrısına veriliyor. Dosyanın işlenmesi için beklemek de örnekteki akışın parçası. YouTube girdisinde ise bağlantı, video dosyası olarak isteğe ekleniyor.

4. İstemi gözlemlenebilir bir göreve dönüştürün. “Videoyu analiz et” gibi geniş bir komut yerine, istenen bilgiyi ve yanıt biçimini tarif edin. İlk denemede genel özet, sonraki soruda belirli öğe ya da zaman damgası istemek sonuçları değerlendirmeyi kolaylaştırır.

Aşağıdaki istem, kısa bir mimari tanıtım videosundan genel bilgi çıkarmaya yöneliktir:

Bu mimari proje videosunu kısa bir özetle anlat. Görünen mekânları ve videoda açıkça seçilebilen tasarım özelliklerini ayrı maddelerde belirt. Görüntüde doğrulanamayan bilgileri tahmin etme.

Bu istem, videoyu tarif etme ve içeriğinden bilgi çıkarma yeteneklerine dayanır. Görüntüde olmayan proje adı, malzeme ya da ölçü gibi ayrıntıları modelin uydurmaması için sınır koyar.

Bir saha veya iç mekân turunda belirli bir olayın geçtiği anı bulmak için daha hedefli bir soru kullanın:

Videoda giriş mekânından ana yaşam alanına geçişin görüldüğü anı bul. Bu geçişin yaklaşık zaman damgasını ver ve görüntüde hangi mekânsal değişikliğin seçildiğini kısaca açıkla. Emin olmadığın bir zaman damgasını kesinmiş gibi sunma.

Kılavuz, videodaki belirli zaman damgalarına başvurulabileceğini belirtiyor. Bu nedenle soru içinde aranacak olayı açıkça tarif etmek, “önemli anları bul” gibi belirsiz bir isteğe göre daha kullanışlıdır.

Bir sunum videosunu tasarım incelemesine hazırlamak için şu soruyu kullanabilirsiniz:

Bu videoda görülen mekânsal düzenlemeleri sırayla incele. Dolaşım, gün ışığı ve yüzey malzemeleri hakkında yalnızca görüntüden desteklenebilen gözlemleri yaz; her gözlemi ilgili zaman damgasıyla eşleştir. Görünmeyen teknik özellikleri çıkarım olarak belirtme.

Bu istem; dolaşım, ışık ve malzeme başlıklarını bir kontrol listesi olarak kullanır. Modelin görüntüden doğrulayamayacağı teknik bilgileri kesin bilgi gibi aktarmamasını da ister. Çıktıyı proje kararı yerine ilk inceleme notu olarak değerlendirin.

Yaygın hatalar ve işlem modu seçimi

En sık karşılaşılan sorun, video boyutu veya uzunluğu için uygun olmayan girdi yolunu seçmektir. Kılavuz, toplam istek 20 MB’ı aşınca, video uzunsa ya da aynı içerik başka isteklerde kullanılacaksa Files API’yi öneriyor. Satır içi veri sınırları dokümanın farklı bölümlerinde aynı verilmediği için bu yöntemi büyük dosyalara zorlamayın.

İkinci konu, işleme modudur. Varsayılan statik yöntem videodan sabit hızda, saniyede bir kare çıkarır. Bu mod kısa klipler, bütün videoyu kapsayan genel özetler, gecikmeye duyarlı işler veya tüm klip boyunca kare düzeyinde inceleme için öneriliyor. Agentic işleme ise zaman çizelgesinde dinamik gezinir; uzun videolarda belirli bir olayı ararken ya da uzun kayıt içindeki tek bir bilgiyi bulurken kullanılabilir. Kılavuz bu seçeneği 5–10 dakikayı aşan uzun içerikler ve hedefli aramalar için uygun görüyor.

Agentic mod, Gemini 4 Argon, 3.8 Flash, 3.6 Flash ve 3.5 Flash Lite modelleri için listelenmiş. Google, uzun içeriklerde bu modun yüzde 88’e kadar daha az token kullanabildiğini ve kalitede yaklaşık yüzde 7 artış sağlayabildiğini belirtiyor; bu üretici açıklamasıdır, her video için garanti değildir. Başka bir hata kaynağı da görüntüden kesin olarak anlaşılamayan ölçü, malzeme türü veya proje bilgilerini istemin doğrulanmış olgular gibi sunmasıdır.

Sonraki adımlar ve mimari iş akışına etkisi

İlk denemeyi kısa, herkese açık olmayan bir çalışma videosuyla ve genel bir özet isteğiyle yapın; ardından belirli bir sahneye yönelik soruya geçin. Uzun videolarda agentic işleme seçeneğini ve yeniden kullanılacak dosyalarda Files API’yi değerlendirin. YouTube URL özelliğinin önizleme olduğunu, fiyat ve hız sınırlarının değişebileceğini hesaba katın. Video oluşturma farklı bir kullanım alanıdır: güncel Gemini API video kılavuzu üretim ve konuşmalı düzenleme için Gemini Omni Flash’ı gösteriyor; Veo 3.1 Preview’ın API’de 22 Ekim 2026’da kapatıldığı belirtiliyor.

Mimarlık ofisleri ve görselleştirme ekipleri için en somut kullanım, proje turu veya saha videosundan ilk özet ve aranabilir gözlem notları çıkarmaktır. Bu, tasarım kararının ya da ölçünün doğrulandığı anlamına gelmez; çıktılar görüntüyle karşılaştırılmalıdır. Kılavuz yerel donanım gereksinimi veya API fiyatı vermiyor. Bu yüzden iş akışını planlarken dosya boyutunu, yükleme sürecini, erişim ve lisans koşullarını ayrıca kontrol edin; yerel GPU gereksinimi varmış gibi varsayım yapmayın.

Kaynak ve lisans

Bu rehber, Google’ın Gemini API video anlama ve video üretme kılavuzlarından yararlanılarak Türkçeye uyarlanmıştır. Video anlama kılavuzu CC BY 4.0 lisanslıdır. Örnek istemler bu rehber için özgün yazılmıştır; kod örnekleri kaynak metinden aktarılmamıştır.