Interactions API

Etkileşimler API'si, Gemini modelleri ve aracılarıyla uygulama geliştirmenin en basit ve en iyi yoludur. Haziran 2026 itibarıyla genel kullanıma sunulmuş olup tüm yeni projeler için önerilir. Artık eski olarak kabul edilse de orijinal generateContent API'si tam olarak desteklenmeye devam etmektedir.

Etkileşimler API'sini neden kullanmalısınız?

  • Tüm uygulamalar için evrensel arayüz: Tek turlu metin oluşturma, çok formatlı anlama, yapılandırılmış çıktılar, araç düzenleme ve aracı tabanlı iş akışları dahil olmak üzere her kullanım alanı için standart arayüz olarak tasarlanmıştır.
  • Modeller ve ajanlar için tek API: Standart Gemini modellerinin yanı sıra doğrudan özel ajanları (ör. Deep Research ve özel olarak yönetilen ajanlar) çağırmak için tek bir birleştirilmiş uç nokta ve kalıp.
  • Kullanıma hazır yeni özellikler: previous_interaction_id kullanılarak isteğe bağlı sunucu tarafı görüşme durumu, hata ayıklama ve kullanıcı arayüzü oluşturma için gözlemlenebilir yürütme adımları ve background=true kullanılarak uzun süren görevler için arka planda yürütme gibi özellikler.
  • Daha yüksek önbellek isabet oranlarıyla daha düşük maliyet: Çok turlu sohbetler kullanılırken isteğe bağlı sunucu tarafı durum yönetimi, turlar arasında daha verimli bağlam önbelleğe alma olanağı sağlayarak jeton maliyetlerini düşürür.
  • Yeni özelliklerin kullanıma sunulacağı yer: Bundan sonra tüm yeni modeller, çok formatlı özellikler, araçlar ve aracı özellikleri Interactions API'de kullanıma sunulacak.

Varsayılan olarak Interactions API, istekleri depolar. Böylece previous_interaction_id kullanarak sunucu tarafı durum yönetimi özelliklerinden yararlanabilirsiniz. store=false ayarını yaparak durumsuz davranışı etkinleştirebilirsiniz. Ayrıntılar için Veri saklama bölümüne bakın.

Başlayın

Özellik rehberleri

Bu kılavuzlar aracılığıyla Etkileşimler API'sinin belirli özelliklerini keşfedin. generateContent ve Interactions API arasında geçiş yapmak için bu sayfalardaki açma/kapatma düğmesini kullanabilirsiniz:

Etkileşimler API'sinin işleyiş şekli

Etkileşimler API'si, temel bir kaynak olan Interaction etrafında şekillenir. Interaction, bir görüşme veya görevdeki tam bir dönüşü temsil eder. Bir etkileşimin tüm geçmişini yürütme adımlarının kronolojik sırası olarak içeren bir oturum kaydı görevi görür. Bu adımlar arasında model düşünceleri, sunucu tarafında veya istemci tarafında araç çağrıları ve sonuçları (ör. function_call ve function_result) ve nihai model_output yer alır. Depolanan kaynak (interactions.get aracılığıyla alınan) tam bağlam için user_input adımlarını da içerir ancak interactions.create yanıtı yalnızca model tarafından oluşturulan adımları döndürür.

interactions.create adresine çağrı yaptığınızda yeni bir Interaction kaynağı oluşturursunuz.

Sunucu tarafı durum yönetimi

Sohbete devam etmek için previous_interaction_id parametresini kullanarak sonraki bir çağrıda tamamlanmış bir etkileşimin id değerini kullanabilirsiniz. Sunucu, görüşme geçmişini almak için bu kimliği kullanır. Böylece, tüm sohbet geçmişini yeniden göndermeniz gerekmez.

previous_interaction_id parametresi yalnızca previous_interaction_id kullanılarak yapılan görüşme geçmişini (girişler ve çıkışlar) korur. Diğer parametreler etkileşim kapsamlıdır ve yalnızca şu anda oluşturduğunuz etkileşim için geçerlidir:

  • tools
  • system_instruction
  • generation_config (thinking_level, temperature vb. dahil)

Bu, geçerli olmasını istediğiniz takdirde bu parametreleri her yeni etkileşimde yeniden belirtmeniz gerektiği anlamına gelir. Bu sunucu tarafı durum yönetimi isteğe bağlıdır. Her isteğe tam görüşme geçmişini göndererek durum bilgisiz modda da çalışabilirsiniz.

Veri depolama ve saklama

API, varsayılan olarak tüm Interaction nesnelerini (store=true) sunucu tarafı durum yönetimi özelliklerinin (previous_interaction_id ile), arka planda yürütme (background=true kullanılarak) ve gözlemlenebilirlik amaçlarıyla kullanımını basitleştirmek için saklar.

  • Ücretli katman: Sistem, etkileşimleri 55 gün boyunca saklar.
  • Ücretsiz katman: Sistem, etkileşimleri 1 gün boyunca saklar.

Bunu istemiyorsanız isteğinizde store=false ayarlayabilirsiniz. Bu kontrol, durum yönetiminden ayrıdır. Herhangi bir etkileşim için depolamayı devre dışı bırakabilirsiniz. Ancak store=false öğesinin arka planda yürütme ile uyumlu olmadığını ve sonraki dönüşlerde previous_interaction_id öğesinin kullanılmasını engellediğini unutmayın.

Ücretli katman projelerinde, saklama penceresini AI Studio'da yapılandırarak günlüklerin 7, 14, 28 veya 55 gün sonra proje depolama alanından silinmek üzere otomatik olarak işaretlenmesini sağlayabilirsiniz. Daha kısa bir saklama süresi, geçmiş sohbetlerin alınmasını etkileyebilir.

Depolanan etkileşimleri, etkileşim kimliği gerektiren delete yöntemini kullanarak istediğiniz zaman programatik olarak silebilirsiniz. Ayrıca, proje depolama alanından silme işlemi de dahil olmak üzere depolanan etkileşim günlüklerini AI Studio'da görüntüleyebilir ve yönetebilirsiniz.

Saklama süresi sona erdikten sonra verileriniz otomatik olarak silinir.

Etkileşim nesneleri, şartlara uygun şekilde işlenir.

AI Studio'da Etkileşimleri Görüntüleme

API, ücretli katmandaki projeler için store=true ile yürütülen Interactions API isteklerini depolar. Bunları doğrudan Google AI Studio'daki Günlükler sayfasından görüntüleyebilirsiniz. Daha fazla bilgi için Günlükler kılavuzuna bakın.

En iyi uygulamalar

  • Önbellek isabet oranı: Örtülü önbelleğe alma, hem durum bilgisi olan hem de durum bilgisi olmayan modlarda desteklenir (bkz. Hızlı Başlangıç). Konuşmalara devam etmek için previous_interaction_id (durumlu) kullanıldığında sistem, konuşma geçmişi için örtülü önbelleğe almayı daha kolay kullanabilir. Bu da performansı artırır ve maliyetleri düşürür.
  • Etkileşimleri karıştırma: Bir görüşmede Agent ve Model etkileşimlerini karıştırıp eşleştirebilirsiniz. Örneğin, ilk veri toplama işlemi için Deep Research aracısı gibi özel bir aracı kullanabilir, ardından özetleme veya yeniden biçimlendirme gibi takip görevleri için standart bir Gemini modeli kullanabilirsiniz. Bu adımları previous_interaction_id ile bağlayabilirsiniz.

Desteklenen modeller ve aracı

Model Adı Tür Model Kimliği
Gemini 3.5 Flash Model gemini-3.5-flash
Gemini 3.1 Pro Önizlemesi Model gemini-3.1-pro-preview
Gemini 3.1 Flash-Lite Model gemini-3.1-flash-lite
Gemini 3 Flash Önizlemesi Model gemini-3-flash-preview
Gemini 2.5 Pro Model gemini-2.5-pro
Gemini 2.5 Flash Model gemini-2.5-flash
Gemini 2.5 Flash-lite Model gemini-2.5-flash-lite
Gemini 3 Pro Image Model gemini-3-pro-image
Gemini 3.1 Flash Görüntüsü Model gemini-3.1-flash-image
Gemini 3.1 Flash TTS Önizlemesi Model gemini-3.1-flash-tts-preview
Gemma 4 31B IT Model gemma-4-31b-it
Gemma 4 26B MoE IT Model gemma-4-26b-a4b-it
Lyria 3 Clip Preview Model lyria-3-clip-preview
Lyria 3 Pro Önizlemesi Model lyria-3-pro-preview
Deep Research Önizlemesi Temsilci deep-research-preview-04-2026
Deep Research Önizlemesi Temsilci deep-research-max-preview-04-2026
Antigravity önizlemesi Temsilci antigravity-preview-05-2026

SDK'lar

Etkileşimler API'sine erişmek için Google GenAI SDK'larının en son sürümünü kullanabilirsiniz.

  • Python'da bu, 2.3.0 sürümünden itibaren google-genai paketidir.
  • JavaScript'te bu, 2.3.0 sürümünden itibaren @google/genai paketidir.

SDK'ları nasıl yükleyeceğiniz hakkında daha fazla bilgiyi Kitaplıklar sayfasında bulabilirsiniz.

Sınırlamalar

  • Uzak MCP: Gemini 3, uzak MCP'yi desteklemez. Bu özellik yakında kullanıma sunulacaktır.
  • Çok turlu model uyumluluğu: Bir sohbette (durumlu veya durumsuz) farklı modeller karıştırıldığında sonraki modeller, önceki modellerin çıkış biçimlerini giriş olarak desteklemelidir. Örneğin, gemini-3.1-flash-image kullanarak bir resim oluşturduysanız bu sohbete, resim girişlerini kabul etmeyen bir modelle (ör. yalnızca metin içeren bir model veya Lyria gibi müzik oluşturma modeli) devam edemezsiniz.

Aşağıdaki özellikler generateContent API tarafından desteklenir ancak Interactions API'de henüz kullanılamaz:

Geri bildirim

Geri bildiriminiz, Etkileşimler API'sinin geliştirilmesi açısından büyük önem taşır. Düşüncelerinizi paylaşmak, hataları bildirmek veya özellik isteğinde bulunmak için Google Yapay Zeka Geliştirici Topluluğu Forumu'nu kullanabilirsiniz.

Sırada ne var?