Gemini Agentic Video Understanding API Rehberi

İki saatlik bir konferans kaydıyla 20 saniyelik ürün videosunu aynı yöntemle analiz etmek mantıklı değil. Gemini’nin yeni agentic video understanding modu, uzun videolarda veya belirli anları bulmaya yönelik sorularda iyi bir başlangıç noktası. Ancak Google’ın açıkladığı “en fazla” tasarruf oranları benchmark sonuçları; her API faturasını otomatik olarak %66 azaltacağı anlamına gelmiyor.

İşleme modunu videonun süresine göre değil, göreve göre seçin

Gemini agentic video understanding, videodaki belirli anları bulmayı veya yeniden incelemeyi gerektiren sorular için tasarlanmış. Kısa bir klibin hızlı yanıt vermesi gerekiyorsa ya da örneklenen her aralıkta tutarlı kapsama istiyorsanız statik işleme daha basit bir seçenek olmaya devam ediyor.

Google, lansman için dört kullanım alanı öne çıkarıyor: saniyenin altındaki anları bulma, uzun videolarda “samanlıkta iğne arama” tipi arama, anomali tespiti ve hareketleri veya nesneleri sayma. Resmî duyuruda 10 dakikalık nasıl yapılır videolarından 90 dakikalık derslere ve birkaç saatlik kayıtlara kadar farklı örnekler yer alıyor.

Google tarafından yayımlanmış bir süre eşiği bulunmuyor. İçinde gizli tek bir olay olan beş dakikalık bir video agentic işlemeyi gerektirebilirken, uzun ve tekdüze bir kayıt için buna ihtiyaç olmayabilir.

Aynı özellik, iki farklı API istek yapısı

“Agentic” her yerde kullanılan tek bir JSON alanı değil. Google’ın lansman örneği Interactions API’yi kullanıyor ve processing: "agentic" ayarını video girdisinin içine yerleştiriyor. GenerateContent yolunda ise medya işleme ayarı media part üzerinde sunuluyor.

Interactions API: processing ayarını video girdisine ekleyin

Google’ın lansman yazısında bir YouTube videosu için şu Python yapısı gösteriliyor:

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.7-flash",
    input=[
        {
            "type": "video",
            "uri": "https://youtu.be/7Z5Vy9JBANs",
            "processing": "agentic"
        },
        {
            "type": "text",
            "text": "What are the 3 most important announcements in this keynote?",
        },
    ],
)

print(interaction.output_text)

Bu ayarı ilgisiz bir üst seviye alana değil, video nesnesinin üzerine ekleyin.

GenerateContent: medya işleme ayarını media part üzerinde tanımlayın

Gemini video-understanding dokümantasyonu, GenerateContent biçimini ayrı olarak açıklıyor. Bu istek yapısında medya girdisi media_processing: "AGENTIC" kullanıyor. JavaScript tarafında bunun karşılığı camelCase biçimindeki mediaProcessing özelliği.

En temel Python yapısı şöyle:

from google import genai
from google.genai import types

client = genai.Client()
video_uri = "YOUR_VIDEO_FILE_URI"

response = client.models.generate_content(
    model="gemini-3.7-flash",
    contents=[
        types.Part.from_uri(
            file_uri=video_uri,
            mime_type="video/mp4",
            media_processing="AGENTIC",
        ),
        "Find the first product announcement and return its timestamp.",
    ],
)

print(response.text)

Yerel bir video kullanıyorsanız YOUR_VIDEO_FILE_URI değerini Gemini dosya yükleme akışından dönen URI ile değiştirin ve medya bölümünü göndermeden önce dosyanın hazır olmasını bekleyin. Kullandığınız istemci sürümüne ait SDK ayrıntılarını doğrulamak için güncel resmî video-understanding rehberine bakın.

Agentic video understanding gerçekte nasıl çalışıyor?

Statik video işleme, videodan sabit bir kare hızıyla örnek alır. Google, varsayılan değerin saniyede 1 kare olduğunu, bu hızın API üzerinden değiştirilebildiğini ve alınan karelerin analiz edilmek üzere modele gönderildiğini belirtiyor.

Agentic iş akışında Gemini zaman akışını arayıp tarayabilir, işe yarayan bir hız seçebilir ve kaydın tamamını eşit biçimde yüklemek yerine görsel karelerden, sesten veya transkriptlerden yararlanabilir:

1. Soruyla ilgili segmenti veya veri türünü isteyin.
2. Dönen kareleri, sesi veya transkripti inceleyin.
3. Daha yüksek zamansal hassasiyet gerekiyorsa daha dar bir aralığı yeniden kontrol edin.

Statik örnekleme, geliştiricilere açık ve kolay uygulanabilir bir kapsama kuralı sunar. Agentic işleme ise nereye bakılacağı konusunda daha fazla sorumluluğu modele bırakır. Bu nedenle üretim sistemleri, zaman damgalarını ve sayımları temsili videolarla doğrulamalı.

Tasarruf iddiası %66 indirim anlamına gelmiyor

Google, standart video analiz benchmark’ları genelinde aşağıdaki sonuçları paylaşıyor. En büyük kazanımların uzun videolarda görüldüğü özellikle vurgulanıyor:

Google’ın lansman duyurusuna göre agentic video understanding, standart Gemini API token fiyatlandırmasını kullanıyor ve bu özellik için ek ücret alınmıyor. Bununla birlikte gerçek maliyet; modele, getirilen içeriğe, isteğe ve çıktıya göre değişir. Token ve model fiyatlandırması hakkında daha geniş bir çerçeve için Gemini 3.7 Flash API fiyatlandırma rehberine bakabilirsiniz.

Aynı kayıt hakkında tekrarlanan sorular soruyorsanız API iş akışının desteklediği durumlarda video bağlamını önbelleğe alın. Google Cloud’un pratik video analizi notlarında bağlam önbellekleme, tekrarlı analizlerde maliyeti düşürmenin başlıca yollarından biri olarak gösteriliyor.

Kullanılabilirlik ve dağıtım sınırları

Agentic video understanding, ayrı bir video modeli olarak duyurulmuş bir ürün değil; üç Flash ailesi modelinde sunulan bir işleme özelliği. Google, özelliğin bu modeller ve yüzeyler için 1 Eylül 2026’da kullanıma açıldığını belirtiyor:

Tüketici uygulaması ve YouTube için planlanan dağıtımlar, özelliğin şu anda her hesapta kullanılabildiğini göstermiyor.

Varsayılanı değiştirmeden önce yapmanız gereken dört test

Lansman duyurusu özellik iddialarını ortaya koyuyor, ancak modun sizin videolarınızda nasıl davranacağını söylemiyor. Mevcut statik iş akışınızı değiştirmeden önce küçük bir değerlendirme seti oluşturun.

1. Zaman damgası bulma: Sahne geçişleri, kısa süreli görünümler ve tam başlangıç-bitiş zamanı önemli olan tek bir olay içeren klipler ekleyin. Dönen zaman damgalarını insan tarafından kontrol edilmiş bir referansla karşılaştırın.
2. Hızlı hareketleri sayma: Tekrarlanan hareketlerin veya kareden geçen nesnelerin bulunduğu görüntüler kullanın. Toplam sayıyı ve yanıtın hangi sayım aralığını temel aldığını açıklayıp açıklamadığını kontrol edin.
3. Ses ve transkript temellendirmesi: Söylenenlerle ekranda görülenlerin birbirinden farklı olduğu sorular sorun. Yanıtın bir veri türünü sessizce diğerinin yerine kullanmadığını doğrulayın.
4. Operasyonel davranış: Aynı dosyaları iki modda da çalıştırın; giriş/çıkış token’larını, toplam gecikmeyi, yeniden denemeleri, boş yanıtları, kaçırılan olayları ve statik moddaki geri dönüş sonucunu kaydedin. Seçici veri getirme kanıtı kaçırıyorsa veya kabul edilemez bir gecikme yaratıyorsa statik geri dönüş yolunu koruyun.

Lansman yazısından yola çıkarak “X dakikadan uzun videolarda agentic kullan” şeklinde katı bir kural oluşturmayın. Yayımlanan bilgiler, evrensel bir süre eşiğini değil, göreve göre seçim yapılmasını destekliyor.

Gemini agentic video understanding API hakkında sık sorulanlar

Agentic video understanding yeni bir Gemini modeli mi?

Hayır. Google bunu Gemini 3.7 Flash, Gemini 3.6 Flash ve Gemini 3.5 Flash-Lite genelinde sunulan bir video anlama özelliği olarak tanımlıyor.

YouTube URL’si yerine yüklediğim bir videoyu kullanabilir miyim?

Evet. Google, yüklenen video dosyalarını ve YouTube videolarını desteklenen API girdileri arasında listeliyor. Yerel bir dosya için önce yükleme yapın, ardından işlem hazır olduğunda dönen dosya URI’sini medya bölümünde kullanın.

Agentic video işleme ek ücretli mi?

Google, bu özellik için ek ücret alınmadığını söylüyor. Standart Gemini API token fiyatlandırması geçerli ve nihai fatura getirilen içeriğe ve isteğin geri kalanına göre değişiyor.

Temsili bir veri setini iki modda da çalıştırın. Ardından agentic işlemeyi yalnızca ölçtüğünüz kanıt kalitesi ve token maliyeti uygulamanızın hedefleriyle örtüşüyorsa varsayılan olarak kullanın.