API de Interactions

La API de Interactions es la mejor manera de compilar con modelos y agentes de Gemini. A partir de junio de 2026, estará disponible de forma general y se recomienda para todos los proyectos nuevos. Si bien ahora se considera heredada, la API original generateContent sigue siendo totalmente compatible.

¿Por qué usar la API de Interactions?

• Interfaz universal para todas las aplicaciones: Se diseñó como la interfaz estándar para cada caso de uso, incluida la generación de texto de un solo turno, la comprensión multimodal, las salidas estructuradas, la organización de herramientas y los Agentic Workflows.
• Una sola API para modelos y agentes: Un extremo y un patrón unificados para llamar a los modelos estándar de Gemini, así como a agentes especializados directamente (como Deep Research y agentes administrados personalizados).
• Nuevas capacidades listas para usar: Funciones como el estado de conversación opcional del servidor con previous_interaction_id, pasos de ejecución observables para la depuración y la renderización de la IU, y la ejecución en segundo plano para tareas de larga duración con background=true.
• Costo más bajo con tasas de aciertos de caché más altas: Cuando se usan conversaciones de varios turnos, la administración de estado opcional del servidor permite un almacenamiento en caché de contexto más eficiente en todos los turnos, lo que reduce los costos de tokens.
• Dónde se lanzan las funciones nuevas: En el futuro, todos los modelos nuevos, las capacidades multimodales , las herramientas y las funciones de agentes se lanzarán en la API de Interactions.

De forma predeterminada, la API de Interactions almacena solicitudes para que puedas aprovechar las funciones de administración de estado del servidor con previous_interaction_id. Puedes habilitar el comportamiento sin estado si configuras store=false. Consulta la sección de retención de datos para obtener más detalles.

Comenzar

• Configura tu agente de programación: Conéctate al MCP de Gemini Docs e instala la habilidad gemini-api-dev para otorgarle a tu asistente acceso directo a la documentación para desarrolladores y las prácticas recomendadas más recientes. Para obtener pasos detallados, consulta la guía Configura tu agente de programación.
• Migra desde generateContent: Si tienes una integración existente, sigue la guía de migración para realizar la transición a la API de Interactions.
• Comienza: Sigue los pasos de la guía Comienza a usar la API de Interactions guide.

Guías de funciones

Explora las capacidades específicas de la API de Interactions a través de estas guías. Puedes usar el botón de activación en estas páginas para cambiar entre generateContent y la API de Interactions:

• Generación de texto
• Generación de imágenes
• Comprensión de imágenes
• Realizar una comprensión de audio
• Comprensión de videos
• Procesamiento de documentos
• Llamada a función
• Salidas estructuradas
• Agente de Deep Research
• Inferencia flexible
• Inferencia de prioridad

Cómo funciona la API de Interactions

La API de Interactions se centra en un recurso principal: Interaction. Una Interaction representa un turno completo en una conversación o tarea. Actúa como un registro de sesión, que contiene todo el historial de una interacción como una secuencia cronológica de pasos de ejecución. Estos pasos incluyen las ideas del modelo, las llamadas y los resultados de herramientas del servidor o del cliente (como function_call y function_result) y la model_output final. El recurso almacenado (recuperado a través de interactions.get) también incluye pasos de user_input para obtener el contexto completo, aunque la respuesta interactions.create solo muestra los pasos generados por el modelo.

Cuando llamas a interactions.create, estás creando un nuevo Interaction recurso:

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

Administración de estado del servidor

Puedes usar el id de una interacción completada en una llamada posterior con el previous_interaction_id parámetro para continuar la conversación. El servidor usa este ID para recuperar el historial de conversaciones, lo que te evita tener que volver a enviar todo el historial de 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"
  }'

El parámetro previous_interaction_id conserva solo el historial de conversaciones (entradas y salidas) con previous_interaction_id. Los otros parámetros tienen alcance de interacción y se aplican solo a la interacción específica que estás generando en este momento:

• tools
• system_instruction
• generation_config (incluidos thinking_level, temperature, etc.)

Esto significa que debes volver a especificar estos parámetros en cada interacción nueva si deseas que se apliquen. Esta administración de estado del servidor es opcional. También puedes operar en modo sin estado enviando el historial de conversaciones completo en cada solicitud.

Almacenamiento y retención de datos

De forma predeterminada, la API almacena todos los objetos de Interaction (store=true) para simplificar el uso de las funciones de administración de estado del servidor (con previous_interaction_id), la ejecución en segundo plano (con background=true) y los fines de observabilidad.

• Nivel pagado: El sistema retiene las interacciones durante 55 días.
• Nivel gratuito: El sistema retiene las interacciones durante 1 día.

Si no quieres esto, puedes configurar store=false en tu solicitud. Este control es independiente de la administración de estado. Puedes inhabilitar el almacenamiento para cualquier interacción. Sin embargo, ten en cuenta que store=false no es compatible con la ejecución en segundo plano y evita el uso de previous_interaction_id para turnos posteriores.

Para los proyectos de nivel pagado, puedes configurar el período de retención en AI Studio para marcar automáticamente los registros para su eliminación del almacenamiento del proyecto después de 7, 14, 28 o 55 días. Una retención más corta puede afectar la recuperación de conversaciones anteriores.

Puedes borrar las interacciones almacenadas en cualquier momento con el delete método de forma programática, que requiere el ID de interacción. También puedes ver y administrar los registros de interacciones almacenadas, incluida la eliminación del almacenamiento del proyecto, en AI Studio.

Una vez que venza el período de retención, tus datos se borrarán automáticamente.

Los objetos de Interactions se procesan según las condiciones.

Cómo ver las interacciones en AI Studio

La API almacena las solicitudes a la API de Interactions ejecutadas con store=true para proyectos en el nivel pagado. Puedes verlas directamente desde la página Registros en Google AI Studio. Consulta la guía de registros para obtener más información.

Prácticas recomendadas

• Tasa de aciertos de caché: El almacenamiento en caché implícito se admite en los modos con y sin estado (consulta la guía de inicio rápido). El uso de previous_interaction_id (con estado) para continuar las conversaciones permite que el sistema utilice más fácilmente el almacenamiento en caché implícito para el historial de conversaciones, lo que mejora el rendimiento y reduce los costos.
• Combinación de interacciones: Tienes la flexibilidad de combinar interacciones de agente y modelo dentro de una conversación. Por ejemplo, puedes usar un agente especializado, como el agente de Deep Research, para la recopilación inicial de datos y, luego, usar un modelo estándar de Gemini para tareas de seguimiento, como resumir o cambiar el formato, y vincular estos pasos con previous_interaction_id.

Modelos y agentes compatibles

SDK

Puedes usar la versión más reciente de los SDK de IA generativa de Google para acceder a la API de Interactions.

• En Python, este es el paquete google-genai de la versión 2.3.0 en adelante.
• En JavaScript, este es el paquete @google/genai de la versión 2.3.0 en adelante.
• En Go, este es el paquete google.golang.org/genai.
• En Java, este es el paquete com.google.genai:google-genai.

Puedes obtener más información para instalar los SDK en la página de bibliotecas.

Limitaciones

• MCP remoto: Gemini 3 no admite el MCP remoto. Próximamente.
• Compatibilidad con modelos de varios turnos: Cuando se combinan diferentes modelos en una conversación (con o sin estado), los modelos posteriores deben admitir las modalidades de salida de los modelos anteriores como entrada. Por ejemplo, si generas una imagen con gemini-3.1-flash-image, no puedes continuar esa conversación con un modelo que no acepte entradas de imágenes (como un modelo de solo texto o un modelo de generación de música como Lyria).

La API de generateContent admite las siguientes funciones, pero aún no están disponibles en la API de Interactions:

• API por lotes
• Llamada a función automática (Python)
• Almacenamiento en caché explícito: Ten en cuenta que el almacenamiento en caché implícito del servidor está disponible en la API de Interactions a través de previous_interaction_id.
• Configuración de seguridad: La configuración de seguridad personalizada no es compatible con la API de Interactions.

Comentarios

Tus comentarios son fundamentales para el desarrollo de la API de Interactions. Comparte tus opiniones, informa errores o solicita funciones en nuestro Foro de la comunidad de desarrolladores de IA de Google.

¿Qué sigue?

• Prueba el notebook de inicio rápido de la API de Interactions.
• Obtén más información sobre el agente de Deep Research de Gemini.