Interactions API

Interactions API, Gemini modelleri ve temsilcileriyle 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.

Interactions API'yi 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ış çıkış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şik uç nokta ve kalıp.
• Kullanıma hazır yeni özellikler: previous_interaction_id kullanılarak isteğe bağlı sunucu tarafında dönüşüm 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 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: Bundan sonra tüm yeni modeller, çok formatlı özellikler, araçlar ve aracı ö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 temsilcinizi ayarlama kılavuzuna bakın.
• generateContent sürümünden geçiş: Mevcut bir entegrasyonunuz varsa Interactions API'ye geçiş yapmak için geçiş rehberini inceleyin.
• Başlangıç: Interactions API ile çalışmaya başlama 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. Bir etkileşimin tüm geçmişini kronolojik bir yürütme adımları sırası olarak içeren bir oturum kaydı görevi görür. Bu adımlar arasında model düşünceleri, sunucu tarafı veya istemci tarafı 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 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

Tamamlanan bir etkileşimin id değerini, sonraki bir çağrıda previous_interaction_id parametresiyle kullanarak sohbete devam edebilirsiniz. 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 sohbet 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 nedenle, geçerli olmalarını istiyorsanız bu parametreleri her yeni etkileşimde 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), arka planda yürütme (background=true kullanılarak) ve gözlemlenebilirlik amaçlarıyla kullanımını basitleştirmek için tüm Etkileşim nesnelerini (store=true) varsayılan olarak 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 depolamayı devre dışı bırakabilirsiniz. Ancak store=false, arka planda yürütme ile uyumlu değildir ve sonraki turlarda previous_interaction_id kullanılmasını engeller.

Ü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 erdikten sonra 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ülü önbelleğe alma, hem durum bilgisi olan hem de durum bilgisi olmayan modlarda desteklenir (bkz. Hızlı Başlangıç). Sohbetlere devam etmek için previous_interaction_id (durum bilgili) kullanmak, sistemin sohbet geçmişi için örtük önbelleğe almayı daha kolay kullanmasını sağlar. Bu da performansı artırır ve maliyetleri azaltı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 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

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 üretirseniz bu sohbeti, görüntü girişlerini kabul etmeyen bir modelle (yalnızca metin modeli veya Lyria gibi bir müzik üretimi modeli) devam ettiremezsiniz.

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

• Batch API
• Otomatik işlev çağırma (Python)
• Açıkça önbelleğe alma: Sunucu tarafında örtülü önbelleğe almanın, Etkileşimler API'sinde previous_interaction_id aracılığıyla kullanılabildiğini unutmayın.
• Güvenlik ayarları: Özel güvenlik ayarları, Interactions API'de desteklenmez.

Geri bildirim

Geri bildirimleriniz, Etkileşimler API'sinin geliştirilmesi için çok önemlidir. Google AI Geliştirici Topluluk Forumu'nda düşüncelerinizi paylaşabilir, hataları bildirebilir veya özellik isteğinde bulunabilirsiniz.

Sırada ne var?

• Etkileşimler API'si hızlı başlangıç not defterini deneyin.
• Gemini Deep Research temsilcisi hakkında daha fazla bilgi edinin.