Gemini’de ajanlı video analizi: Varsayılan mod statik

Gemini API’de ajanlı video analizini açmak için desteklenen bir Flash modeli seçin ve ilgili video girdisine processing: "agentic" ekleyin. Bu alan gönderilmezse API videoyu varsayılan statik modda, saniyede bir kare çıkararak işler; yalnızca uyumlu modeli seçmek ajanlı modu açmaz.

Etkinleştirmeyi yanıt metninden çıkarsamayın: interaction.steps içinde processing_call ve processing_result adımlarını arayın. Gemini API video belgeleri, bu adımların dinamik gezinmeyi gösterdiğini ve özelliğin Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash ile 3.5 Flash Lite modellerinde desteklendiğini belirtiyor.

Desteklenen modeli ve modu birlikte seçin

Gemini API’de ajanlı işlemeyi destekleyen Flash modelleri ile statik modda kalan diğer model seçeneği

Ajanlı video işleme dört güncel modelde kullanılabiliyor: Gemini 3.8 Flash, Gemini 3.7 Flash, Gemini 3.6 Flash ve Gemini 3.5 Flash Lite. Statik işleme ise video kabul eden bütün Gemini modellerinde varsayılan seçenek.

Gemini 3.8 Flash: Ajanlı ve statik işleme desteklenir.
Gemini 3.7 Flash: Ajanlı ve statik işleme desteklenir.
Gemini 3.6 Flash: Ajanlı ve statik işleme desteklenir.
Gemini 3.5 Flash Lite: Ajanlı ve statik işleme desteklenir.
Diğer video uyumlu modeller: Statik mod kullanılabilir; ajanlı destek model adından tahmin edilmemelidir.

Üretimde model kimliğini izin verilen bir listeye göre denetleyin. Yeni bir sürüme geçerken aynı doğrulama videosunu yeniden çalıştırın; hem yanıt adımlarını hem de uygulamanın beklediği çıktı biçimini kontrol edin.

Python ve REST isteğinde ayar nereye yazılır?

Python ve REST isteklerinde video girdisine agentic işleme ayarının eklenmesi ve işlem adımlarının dönmesi

Python SDK ile uzun veya yeniden kullanılacak bir videoyu Files API’ye yükleyin. Dosya ACTIVE durumuna ulaşmadan analiz isteğini göndermeyin; FAILED durumunu ayrı bir hata olarak ele alın. Ardından client.interactions.create çağrısında modeli belirtin ve input dizisine önce video nesnesini, sonra metin sorgusunu yerleştirin.

Video nesnesinde type değerini video olarak ayarlayın.
uri ve mime_type alanlarına yüklenen dosyanın değerlerini yazın.
Aynı nesneye processing: "agentic" ekleyin.
Metin sorgusunu ayrı bir input nesnesi olarak videodan sonra gönderin.
Yanıtla birlikte steps ve usage alanlarını kaydedin.

REST karşılığı, v1beta/interactions uç noktasına gönderilen POST isteğidir. x-goog-api-key ve application/json başlıklarını kullanın; JSON gövdesindeki model alanına desteklenen modeli, video nesnesine ise type, uri, mime_type ve processing alanlarını koyun. Kritik nokta, processing değerinin genel istek ayarına değil doğrudan video girdisine ait olmasıdır.

Tek istekte birden fazla video varsa her girdinin modu ayrı seçilebilir. Örneğin uzun bir ders kaydı agentic, kısa bir deney klibi static olarak işaretlenebilir; böylece bütün istek için tek bir işleme davranışına bağlı kalmazsınız.

Statik moddan ne zaman ayrılmalı?

Ajanlı mod, uzun kayıtlarda belirli bir anı bulma, hızlı bir hareketi sayma, anomali arama veya görüntüyle konuşmayı birlikte inceleme gibi hedefli sorgulara uygundur. Model soruya göre zaman çizelgesinde gezinir; gerekli transkript, kare, ses ve video bölümlerini yükleyebilir, kare hızını veya çözünürlüğü inceleme sırasında değiştirebilir.

Statik mod kısa ve gecikmeye duyarlı kliplerde ya da bütün kayıt boyunca sabit örnekleme gereken işlerde daha öngörülebilir olabilir. Beş dakikanın altındaki videolarda ajanlı gezinmenin araç çağrıları ilk token süresini artırabilir. Başlangıç-bitiş kırpması ve özel FPS gibi elle belirlenen işleme ayarları da yalnızca static yapılandırmasında desteklenir.

Google’ın özellik duyurusu, ajanlı işlemenin standart Gemini API token fiyatlarını kullandığını ve ayrıca özellik ücreti alınmadığını açıklıyor. Duyurudaki yüzde 88’e kadar token, yüzde 66’ya kadar maliyet tasarrufu ve yüzde 7’ye kadar kalite artışı, Google’ın testlerindeki üst değerlerdir; her video ve sorgu için garanti değildir.

Statik geri dönüşü uygulama katmanında kurun

API’nin desteklenmeyen ya da başarısız bir agentic isteği sessizce static moda çevireceğini varsaymayın. Güvenli geri dönüş, uygulamanızın hata veya eksik işlem izi gördüğünde yeni bir isteği açıkça processing: "static" değeriyle göndermesidir. Hangi modun kullanıldığını sonuç kaydında saklayın; iki moddan gelen yanıtları aynı ölçüm kümesine karıştırmayın.

Ajanlı çağrı başarılı görünse bile processing_call ve processing_result adımları yoksa sonucu işaretleyin. Yanlış zaman aralığının veya eksik sayımın ciddi sonuç doğurduğu işlerde statik karşılaştırma, deterministik kare çıkarımı ya da insan incelemesi ekleyin.

Çok turlu görüşmelerde previous_interaction_id kullanılırsa sunucu video bağlamını korur. Durumsuz step_list akışında ise önceki yanıttaki processing_call ve processing_result dahil bütün adımlar sonraki isteğe taşınmalıdır; bunların atlanması API hatası vermeyebilir, ancak video bağlamını kaybettirerek takip yanıtının kalitesini düşürür.

Uzun videoda sonucu ve maliyeti doğrulayın

Uzun videoda ajanlı ve statik sonuçların zaman damgası, sayım, gecikme ve token kullanımıyla doğrulanması

Doğrulama kümesini, cevabı önceden bilinen kısa olaylar, hızlı kesmeler, tekrarlanan hareketler, zayıf transkript bölümleri ve uzun sessizlikler içerecek biçimde hazırlayın. Her çalıştırmada model kimliğini, işleme modunu, yanıtı, zaman damgalarını, işlem adımlarını ve gecikmeyi birlikte kaydedin.

processing_call ve processing_result adımlarının bulunduğunu doğrulayın.
Modelden iddiasını destekleyen MM:SS biçiminde zaman aralıkları isteyin.
Dönen aralıkların birkaç saniye öncesini ve sonrasını kaynak videodan kontrol edin.
Sayım sorularında başlangıç, bitiş ve tekrar ölçütünü açıkça tanımlayın; sonucu elle etiketlenmiş küçük bir örnekle karşılaştırın.
Aynı video ve sorguyu açık static ayarıyla çalıştırarak cevap, gecikme ve token kullanımını yan yana değerlendirin.
Hata maliyeti yüksekse otomatik kararı insan onayına bağlayın.

Gemini token belgelerine göre gerçek tüketim interaction.usage içinden izlenebilir: başlangıç girdisi total_input_tokens, gezinme akıl yürütmesi total_thought_tokens, yüklenen transkript, kare ve ses total_tool_use_tokens alanına yansır. Bu nedenle bütçeyi duyurulan azami tasarruftan değil, kendi video dağılımınız ve sorgularınız üzerinde ölçülen toplam kullanımdan çıkarın.

Ayrıca okuyun:

Gemini’de ajanlı video analizi: varsayılan mod hâlâ statik