Interactions API

Etkileşimler API'si, Gemini ile geliştirme yaparken kullanabileceğiniz yeni standart temel öğedir ve tüm yeni projeler için önerilir. Ajan tabanlı iş akışları, sunucu tarafı durum yönetimi ve karmaşık çok formatlı, çok adımlı sohbetler için optimize edilmiştir. Orijinal generateContent API'si tam olarak desteklenmeye devam eder.

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

  • Sunucu tarafı geçmiş yönetimi: previous_interaction_id aracılığıyla basitleştirilmiş çok turlu akışlar. Sunucu, durumu varsayılan olarak etkinleştirir (store=true), ancak store=false'yi ayarlayarak durumsuz davranışı etkinleştirebilirsiniz.
  • Gözlemlenebilir yürütme adımları: Yazılan adımlar, karmaşık akışlarda hata ayıklamayı ve ara etkinlikler (ör. düşünceler veya arama widget'ları) için kullanıcı arayüzü oluşturmayı kolaylaştırır.
  • Temsilci tabanlı iş akışları için tasarlandı: Çok adımlı araç kullanımı, düzenleme ve karmaşık muhakeme akışları için yerel destek.
  • Uzun süren ve arka plan görevleri: background=true kullanarak Deep Think ve Deep Research gibi zaman alan işlemlerin arka plan süreçlerine aktarılmasını destekler.
  • Yeni modellere ve yeteneklere erişim: Gelecekte, temel ana hat ailesinin ötesindeki yeni modellerin yanı sıra yeni ajan tabanlı yetenekler ve araçları yalnızca Interactions API'de kullanıma sunulacak.

Yeni bir projeye başlıyorsanız, etkileşimli uygulamalar geliştiriyorsanız veya sunucu tarafında görüşme yönetimine ihtiyacınız varsa Etkileşimler API'sini kullanın. İhtiyaçlarınızı karşılayan mevcut bir entegrasyonunuz varsa veya etkileşimler API'sinde henüz kullanılamayan bir özelliğe (ör. Batch API veya açık önbelleğe alma) ihtiyacınız varsa generateContent'yi kullanın.

Başlayın

  • Kodlama aracınızı ayarlayın: Gemini Docs MCP'ye bağlanın ve gemini-interactions-api becerisini yükleyerek asistanınıza en son geliştirici belgelerine ve en iyi uygulamalara doğrudan erişim izni verin. Kodlama temsilcinizi ayarlama →
  • generateContent'den geçiş yapma: Mevcut bir entegrasyonunuz varsa Etkileşimler API'sine geçiş yapmak için Taşıma Rehberi'ni inceleyin.
  • Hızlı başlangıç kılavuzunu deneyin: Etkileşimler API'si hızlı başlangıç kılavuzundaki minimum çalışma örneğiyle başlayın.

Özellik rehberleri

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

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 dönüşü ifade eder. Bir oturum kaydı olarak işlev görür ve bir etkileşimin tüm geçmişini yürütme adımlarının kronolojik sırası olarak içerir. 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ınır) 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, bu kimliği kullanarak görüşme geçmişini alı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 istekte 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ütmenin (background=true kullanılarak) ve gözlemlenebilirlik amaçlarının 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 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ı: Konuşmalara devam etmek için previous_interaction_id 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 Aracı 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 temsilciler

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

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

  • Beta durumu: Etkileşimler API'si beta/önizleme sürümündedir. Özellikler ve şemalar değişebilir.
  • 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:

Zarar veren değişiklikler

Etkileşimler API'si şu anda erken beta aşamasındadır. API özelliklerini, kaynak şemalarını ve SDK arayüzlerini gerçek hayattaki kullanıma ve geliştirici geri bildirimlerine göre aktif olarak geliştirip iyileştiriyoruz.

Bu nedenle, uyumluluğu bozan değişiklikler olabilir. Güncellemeler şunlarda değişiklikler içerebilir:

  • Giriş ve çıkış şemaları.
  • SDK yöntemi imzaları ve nesne yapıları.
  • Belirli özelliklerin davranışları.

Üretim iş yükleri için standart generateContent API'yi kullanmaya devam etmelisiniz. Kararlı dağıtımlar için önerilen yol olmaya devam ediyor ve bu yolu aktif olarak geliştirmeye ve sürdürmeye devam edeceğiz.

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 AI Geliştirici Topluluğu Forumu'nu kullanabilirsiniz.

Sırada ne var?