API Interactions

L'API Interactions è il modo migliore per creare con i modelli e gli agenti Gemini. A partire da giugno 2026, è disponibile a livello generale ed è consigliata per tutti i nuovi progetti. Sebbene ora sia considerata legacy, l'API originale generateContent rimane completamente supportata.

Perché utilizzare l'API Interactions?

• Interfaccia universale per tutte le applicazioni: progettata come interfaccia standard per ogni caso d'uso, inclusi la generazione di testo a turno singolo, la comprensione multimodale, gli output strutturati, l'orchestrazione degli strumenti e i flussi di lavoro agentici.
• Singola API per modelli e agenti: un endpoint e un pattern unificati per chiamare direttamente i modelli Gemini standard e gli agenti specializzati (come Deep Research e gli agenti gestiti personalizzati).
• Nuove funzionalità predefinite: funzionalità come lo stato della conversazione lato server facoltativo utilizzando previous_interaction_id, passaggi di esecuzione osservabili per il debug e il rendering dell'interfaccia utente ed esecuzione in background per le attività a lunga esecuzione utilizzando background=true.
• Costo inferiore con tassi di successo della cache più elevati: quando si utilizzano conversazioni multi-turno, la gestione dello stato lato server facoltativa consente una memorizzazione nella cache del contesto più efficiente tra i turni, riducendo i costi dei token.
• Dove vengono lanciate le nuove funzionalità: in futuro, tutti i nuovi modelli, le funzionalità multimodali , gli strumenti e le funzionalità agentiche verranno lanciati sull'API Interactions.

Per impostazione predefinita, l'API Interactions memorizza le richieste in modo che tu possa sfruttare le funzionalità di gestione dello stato lato server utilizzando previous_interaction_id. Puoi attivare il comportamento stateless impostando store=false. Per maggiori dettagli, consulta la sezione sulla conservazione dei dati.

Inizia

• Configura l'agente di programmazione: connettiti a Gemini Docs MCP e installa la skill gemini-api-dev per consentire all'assistente di accedere direttamente a documentazione per gli sviluppatori e best practice più recenti. Per la procedura dettagliata, consulta la guida Configurare l'agente di programmazione
• Esegui la migrazione da generateContent: se hai un'integrazione esistente, segui la Guida alla migrazione per passare all'API Interactions.
• Inizia: segui i passaggi descritti nella guida Inizia a utilizzare l'API Interactions.

Guide alle funzionalità

Esplora le funzionalità specifiche dell'API Interactions tramite queste guide. Puoi utilizzare l'opzione di attivazione/disattivazione in queste pagine per passare da generateContent all'API Interactions:

• Generazione di testo
• Generazione di immagini
• Comprensione delle immagini
• Comprensione dell'audio
• Comprensione dei video
• Elaborazione dei documenti
• Chiamata di funzione
• Output strutturato
• Agente Deep Research
• Inferenza Flex
• Inferenza di priorità

Come funziona l'API Interactions

L'API Interactions è incentrata su una risorsa principale: Interaction. Un'interazione Interaction rappresenta un turno completo in una conversazione o un'attività. Funge da record di sessione, contenente l'intera cronologia di un'interazione come sequenza cronologica di passaggi di esecuzione. Questi passaggi includono i pensieri del modello, le chiamate e i risultati degli strumenti lato server o lato client (come function_call e function_result) e l'elemento model_output finale. La risorsa archiviata (recuperata tramite interactions.get) include anche i passaggi user_input per il contesto completo, anche se la risposta interactions.create restituisce solo i passaggi generati dal modello.

Quando effettui una chiamata a interactions.create, stai creando una nuova risorsa Interaction:

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."
  }'

Gestione dello stato lato server

Puoi utilizzare l'elemento id di un'interazione completata in una chiamata successiva utilizzando il previous_interaction_id parametro per continuare la conversazione. Il server utilizza questo ID per recuperare la cronologia delle conversazioni, evitando di dover inviare di nuovo l'intera cronologia della chat:

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"
  }'

Il parametro previous_interaction_id conserva solo la cronologia delle conversazioni (input e output) utilizzando previous_interaction_id. Gli altri parametri sono ambito di interazione e si applicano solo all'interazione specifica che stai generando:

• tools
• system_instruction
• generation_config (inclusi thinking_level, temperature e così via)

Ciò significa che devi specificare di nuovo questi parametri in ogni nuova interazione se vuoi che vengano applicati. Questa gestione dello stato lato server è facoltativa; puoi anche operare in modalità stateless inviando la cronologia completa delle conversazioni in ogni richiesta.

Archiviazione e conservazione dei dati

Per impostazione predefinita, l'API archivia tutti gli oggetti Interaction (store=true) per semplificare l'utilizzo delle funzionalità di gestione dello stato lato server (con previous_interaction_id), l'esecuzione in background (utilizzando background=true) e per scopi di osservabilità.

• Livello a pagamento: il sistema conserva le interazioni per 55 giorni.
• Livello senza costi: il sistema conserva le interazioni per 1 giorno.

Se non vuoi che ciò accada, puoi impostare store=false nella richiesta. Questo controllo è separato dalla gestione dello stato; puoi disattivare l'archiviazione per qualsiasi interazione. Tuttavia, tieni presente che store=false non è compatibile con l'esecuzione in background e impedisce l'utilizzo di previous_interaction_id per i turni successivi.

Per i progetti di livello a pagamento, puoi configurare la finestra di conservazione in AI Studio per contrassegnare automaticamente i log per l'eliminazione dallo spazio di archiviazione del progetto dopo 7, 14, 28 o 55 giorni. Un periodo di conservazione più breve potrebbe influire sul recupero delle conversazioni passate.

Puoi eliminare le interazioni archiviate in qualsiasi momento utilizzando il delete metodo a livello di programmazione, che richiede l'ID interazione. Puoi anche visualizzare e gestire i log delle interazioni archiviate, inclusa l'eliminazione dallo spazio di archiviazione del progetto, in AI Studio.

Al termine del periodo di conservazione, i dati verranno eliminati automaticamente.

Gli oggetti Interactions vengono elaborati in base ai termini.

Visualizzare le interazioni in AI Studio

L'API archivia le richieste dell'API Interactions eseguite con store=true per i progetti di livello a pagamento. Puoi visualizzarli direttamente dalla pagina Log in Google AI Studio. Per saperne di più, consulta la guida Log.

Best practice

• Tasso di successo della cache: la memorizzazione nella cache implicita è supportata sia in modalità stateful che stateless (vedi Guida rapida). L'utilizzo di previous_interaction_id (stateful) per continuare le conversazioni consente al sistema di utilizzare più facilmente la memorizzazione nella cache implicita per la cronologia delle conversazioni, il che migliora le prestazioni e riduce i costi.
• Combinazione di interazioni: hai la flessibilità di combinare le interazioni di agenti e modelli all'interno di una conversazione. Ad esempio, puoi utilizzare un agente specializzato, come l'agente Deep Research, per la raccolta iniziale dei dati e poi utilizzare un modello Gemini standard per le attività di follow-up, come il riepilogo o la riformattazione, collegando questi passaggi con previous_interaction_id.

Modelli e agenti supportati

SDK

Puoi utilizzare l'ultima versione degli SDK Google GenAI per accedere all'API Interactions.

• In Python, questo è il pacchetto google-genai dalla versione 2.3.0 in poi.
• In JavaScript, questo è il pacchetto @google/genai dalla versione 2.3.0 in poi.
• In Go, questo è il pacchetto google.golang.org/genai.
• In Java, questo è il pacchetto com.google.genai:google-genai.

Puoi scoprire di più su come installare gli SDK nella pagina Librerie.

Limitazioni

• MCP remoto: Gemini 3 non supporta MCP remoto, ma questa funzionalità sarà disponibile a breve.
• Compatibilità dei modelli a più turni: quando si combinano modelli diversi in una conversazione (stateful o stateless), i modelli successivi devono supportare le modalità di output dei modelli precedenti come input. Ad esempio, se generi un'immagine utilizzando gemini-3.1-flash-image, non puoi continuare la conversazione con un modello che non accetta input di immagini (ad esempio un modello solo di testo o un modello di generazione di musica come Lyria).

Le seguenti funzionalità sono supportate dall' generateContent API, ma non sono ancora disponibili nell'API Interactions:

• API batch
• Chiamata di funzione automatica (Python)
• Memorizzazione nella cache esplicita: tieni presente che la memorizzazione nella cache implicita lato server è disponibile nell'API Interactions tramite previous_interaction_id.
• Impostazioni di sicurezza: le impostazioni di sicurezza personalizzate non sono supportate nell'API Interactions.

Feedback

Il tuo feedback è fondamentale per lo sviluppo dell'API Interactions. Condividi le tue opinioni, segnala bug o richiedi funzionalità nel nostro forum della community degli sviluppatori di Google AI.

Passaggi successivi

• Prova il notebook di avvio rapido dell'API Interactions.
• Scopri di più sull'agente Deep Research di Gemini.