Interactions API

Etkileşimler API'si, yeni arayüzümüz ve Gemini modelleri ve aracılarıyla geliştirme yapmanın en basit yoludur. Haziran 2026 itibarıyla genel kullanıma sunulmuştur ve tüm yeni projeler için önerilen arayüzdür.

Artık eski bir API olarak kabul edilse de orijinal generateContent API'si tam olarak desteklenmeye devam etmektedir.

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

  • 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.
  • Daha yüksek önbellek isabet oranlarıyla daha düşük maliyet: Sunucu tarafında durum yönetimi, dönüşümler arasında daha verimli bağlam önbelleğe alma olanağı sağlayarak çok aşamalı etkileşim sohbetlerinde jeton maliyetlerini azaltır.
  • Yeni nesil modeller ve ajanlar için geliştirilmiştir: Düşünme modelleri, çok adımlı araç kullanımı ve karmaşık akıl yürütme akışları için özel olarak geliştirilmiştir. Bu sayede, ajan tabanlı uygulamaların oluşturulması, hata ayıklanması ve düzenlenmesi süreci basitleştirilir.
  • Modeller ve temsilciler için tek API: Deep Research ve özel olarak yönetilen temsilciler gibi Gemini modellerini ve temsilcilerini doğrudan çağırmak için tek bir birleştirilmiş arayüz. Öğrenilecek ayrı uç noktalar veya kalıplar yoktur.
  • Yeni özelliklerin kullanıma sunulduğu yer: Gelecekte, temel ana hat ailesinin ötesindeki yeni modeller ve özellikler ile yeni temsilci tabanlı özellikler ve araçlar 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 durum bilgisiz 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 Interactions 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:

Interactions 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, sohbet 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 sunucu tarafı durum yönetimi özelliklerinin (previous_interaction_id ile), arka planda yürütmenin (background=true kullanılarak) ve gözlemlenebilirlik amaçlarının kullanımını basitleştirmek için tüm Interaction nesnelerini (store=true) 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 ile background=true'nin uyumsuz olduğunu ve sonraki dönüşlerde previous_interaction_id'nin kullanılmasını engellediğini unutmayın.

API Referansı'nda bulunan silme yöntemini kullanarak depolanan etkileşimleri istediğiniz zaman silebilirsiniz. Yalnızca etkileşim kimliğini biliyorsanız etkileşimleri silebilirsiniz.

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

Sistem, Etkileşim nesnelerini şartlara göre işler.

En iyi uygulamalar

  • Önbellek isabet oranı: Sohbetlere devam etmek için previous_interaction_id kullanıldığında sistem, sohbet 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ç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.1 Flash-Lite Model gemini-3.1-flash-lite
Gemini 3.1 Flash-Lite Önizlemesi Model gemini-3.1-flash-lite-preview
Gemini 3.1 Pro Önizlemesi Model gemini-3.1-pro-preview
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
Lyria 3 Clip Preview Model lyria-3-clip-preview
Lyria 3 Pro Önizlemesi Model lyria-3-pro-preview
Deep Research Önizlemesi Temsilci deep-research-pro-preview-12-2025
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, 1.55.0 sürümünden itibaren google-genai paketidir.
  • JavaScript'te bu, 1.33.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.

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?