Interactions API

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

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

• Tüm uygulamalar için evrensel arayüz: Tek adımlı metin oluşturma, çok modlu anlama, yapılandırılmış çıkışlar, araç düzenleme ve temsilci tabanlı iş akışları dahil olmak üzere her kullanım alanı için standart arayüz olarak tasarlanmıştır.
• Modeller ve temsilciler için tek API: Standart Gemini modellerini ve özel temsilcileri (ör. Deep Research ve özel olarak yönetilen temsilciler) doğrudan çağırmak için tek bir birleşik uç nokta ve kalıp.
• Kullanıma hazır yeni özellikler: previous_interaction_id kullanarak isteğe bağlı sunucu tarafı sohbet durumu, hata ayıklama ve kullanıcı arayüzü oluşturma için gözlemlenebilir yürütme adımları ve background=true kullanarak 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 aşamalı etkileşimler kullanıldığında, isteğe bağlı sunucu tarafı durum yönetimi, aşamalar arasında daha verimli bağlam önbelleğe alma olanağı sunarak jeton maliyetlerini azaltır.
• Yeni özelliklerin kullanıma sunulduğu yer: Gelecekte tüm yeni modeller, çok formatlı özellikler, araçlar ve temsilci özellikleri Interactions API'de kullanıma sunulacak.

Interactions API, varsayılan olarak 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

• Kodlama temsilcinizi ayarlama: Gemini Docs MCP'ye bağlanın ve asistanınızın en yeni geliştirici belgelerine ve en iyi uygulamalara doğrudan erişebilmesi için gemini-api-dev becerisini yükleyin. Ayrıntılı adımlar için Kodlama aracınızı ayarlama kılavuzuna bakın.
• API'sinden geçiş yapmagenerateContent: Mevcut bir entegrasyonunuz varsa Interactions API'sine geçiş yapmak için Geçiş rehberi'ni inceleyin.
• Başlangıç: Interactions API başlangıç kılavuzundaki adımları uygulayın.

Özellik rehberleri

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

• Metin üretme
• Görüntü üretme
• Görsel yorumlama
• Ses yorumlama
• Video anlama
• Belge işleme
• İşlev çağrısı
• Yapılandırılmış çıkış
• Deep Research temsilcisi
• Flex çıkarımı
• Öncelik çıkarımı

Interactions API'nin işleyiş şekli

Interactions API, temel bir kaynak olan Interaction etrafında şekillenir. Interaction, bir görüşme veya görevdeki tam bir sırayı temsil eder. Bu, 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ı veya istemci tarafı araç çağrıları ve sonuçları (function_call ve function_result gibi) ve son 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 için bir çağrı yaptığınızda yeni bir Interaction kaynağı oluşturursunuz:

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Tell me a short story about a time-traveling lighthouse."
)

print(interaction.output_text)

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI();

const interaction = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "Tell me a short story about a time-traveling lighthouse.",
});

console.log(interaction.output_text);

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Tell me a short story about a time-traveling lighthouse."))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Tell me a short story about a time-traveling lighthouse."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Tell me a short story about a time-traveling lighthouse."
  }'

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:

from google import genai

client = genai.Client()

# 1. First turn
turn1 = client.interactions.create(
    model="gemini-3.8-flash",
    input="Hi, my name is Phil."
)

# 2. Second turn (chained using previous_interaction_id)
turn2 = client.interactions.create(
    model="gemini-3.8-flash",
    input="What is my name?",
    previous_interaction_id=turn1.id
)

print(turn2.output_text)

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI();

// 1. First turn
const turn1 = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "Hi, my name is Phil.",
});

// 2. Second turn (chained using previous_interaction_id)
const turn2 = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "What is my name?",
  previous_interaction_id: turn1.id,
});

console.log(turn2.output_text);

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

// 1. First turn
Interaction turn1 =
    client
        .interactions
        .create(
            CreateInteractionRequestBody.of(
                CreateModelInteraction.builder()
                    .model(Model.of("gemini-3.8-flash"))
                    .input(InteractionsInput.of("Hi, my name is Phil."))
                    .build()))
        .interaction()
        .get();

// 2. Second turn (chained using previousInteractionId)
Interaction turn2 =
    client
        .interactions
        .create(
            CreateInteractionRequestBody.of(
                CreateModelInteraction.builder()
                    .model(Model.of("gemini-3.8-flash"))
                    .input(InteractionsInput.of("What is my name?"))
                    .previousInteractionId(turn1.id().get())
                    .build()))
        .interaction()
        .get();

System.out.println(turn2.outputText().orElse(""));

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // 1. First turn
    turn1, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Hi, my name is Phil."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    // 2. Second turn (chained using PreviousInteractionID)
    turn2, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:                 interactions.Model("gemini-3.8-flash"),
            Input:                 interactions.NewInteractionsInput("What is my name?"),
            PreviousInteractionID: turn1.Interaction.ID,
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if turn2.Interaction.OutputText != nil {
        fmt.Println(*turn2.Interaction.OutputText)
    }
}

# Replace PREVIOUS_INTERACTION_ID with the id returned from the first turn
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "What is my name?",
    "previous_interaction_id": "PREVIOUS_INTERACTION_ID"
  }'

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

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

Bu nedenle, bu parametrelerin uygulanmasını istiyorsanız her yeni etkileşimde bunları yeniden belirtmeniz gerekir. Bu sunucu tarafı durum yönetimi isteğe bağlıdır. Her istekle birlikte tam sohbet geçmişini göndererek durum bilgisiz modda da çalışabilirsiniz.

Veri depolama ve saklama

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

• Ü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 depolama alanını 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 süresini AI Studio'da yapılandırarak günlükleri 7, 14, 28 veya 55 gün sonra proje depolama alanından silinecek şekilde otomatik olarak işaretleyebilirsiniz. Daha kısa bir saklama süresi, geçmiş sohbetlerin alınmasını etkileyebilir.

Saklanan etkileşimleri, etkileşim kimliğini gerektiren delete yöntemini programatik olarak kullanarak istediğiniz zaman 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 erdiğinde verileriniz otomatik olarak silinir.

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

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

API, Ücretli Katman'daki 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ılavuzu'na bakın.

En iyi uygulamalar

• Önbellek isabet oranı: Örtük önbelleğe alma, hem durum bilgisi olan hem de durum bilgisi olmayan modlarda desteklenir (Hızlı başlangıç bölümüne bakın). 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 sohbette temsilci ve model etkileşimlerini karıştırıp eşleştirebilirsiniz. Örneğin, ilk veri toplama işlemi için Deep Research temsilcisi gibi özel bir temsilci 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ıları

SDK'lar

Interactions API'ye erişmek için Google GenAI SDK'larının en yeni 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.
• Go'da bu, google.golang.org/genai paketidir.
• Java'da bu, com.google.genai: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 aşamalı etkileşim model uyumluluğu: Bir görüşmede farklı modelleri (durum bilgili veya durum bilgisiz) karıştırırken sonraki modeller, önceki modellerin çıkış biçimlerini giriş olarak desteklemelidir. Örneğin, gemini-3.1-flash-image kullanarak bir resim oluşturursanız bu sohbete, resim girişlerini kabul etmeyen bir modelle (ör. yalnızca metin içeren bir model veya Lyria gibi müzik üretme modeli) devam edemezsiniz.

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

• Batch API
• Otomatik işlev çağrısı (Python)
• Açık önbelleğe alma: Sunucu tarafında örtük önbelleğe alma, previous_interaction_id aracılığıyla Interactions API'de kullanılabilir.

Geri bildirim

Geri bildirimleriniz, Interactions API'nin geliştirilmesi açısından çok önemlidir. Google AI Geliştirici Topluluk Forumu'nda düşüncelerinizi paylaşabilir, hataları bildirebilir veya özellik isteğinde bulunabilirsiniz.

Sırada ne var?

• Interactions API hızlı başlangıç not defterini deneyin.
• Gemini Deep Research aracısı hakkında daha fazla bilgi edinin.