La API de Interactions (beta) es una interfaz unificada para interactuar con modelos y agentes de Gemini. Como alternativa mejorada a la API de generateContent, simplifica la administración de estados, la organización de herramientas y las tareas de larga duración. Para obtener una vista completa del esquema de la API, consulta la referencia de la API. Durante la versión beta, las funciones y los esquemas están sujetos a cambios que pueden interrumpir el funcionamiento.
Para comenzar rápidamente, prueba el notebook de inicio rápido de la API de Interactions.
En el siguiente ejemplo, se muestra cómo llamar a la API de Interactions con una instrucción de texto.
Python
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input="Tell me a short joke about programming."
)
print(interaction.outputs[-1].text)
JavaScript
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: 'Tell me a short joke about programming.',
});
console.log(interaction.outputs[interaction.outputs.length - 1].text);
REST
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-flash-preview",
"input": "Tell me a short joke about programming."
}'
Interacciones básicas
La API de Interactions está disponible a través de nuestros SDKs existentes. La forma más sencilla de interactuar con el modelo es proporcionar una instrucción de texto. input puede ser una cadena, una lista que contiene objetos de contenido o una lista de turnos con roles y objetos de contenido.
Python
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input="Tell me a short joke about programming."
)
print(interaction.outputs[-1].text)
JavaScript
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: 'Tell me a short joke about programming.',
});
console.log(interaction.outputs[interaction.outputs.length - 1].text);
REST
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-flash-preview",
"input": "Tell me a short joke about programming."
}'
Conversación
Puedes crear conversaciones de varios turnos de dos maneras:
- Con estado, haciendo referencia a una interacción anterior
- Sin estado, proporcionando el historial de conversaciones completo
Conversación con estado
Para continuar una conversación, pasa el id de la interacción anterior al parámetro previous_interaction_id. La API recuerda el historial de la conversación, por lo que solo debes enviar la nueva entrada. Para obtener detalles sobre qué campos se heredan y cuáles se deben volver a especificar, consulta Administración del estado del servidor.
Python
from google import genai
client = genai.Client()
# 1. First turn
interaction1 = client.interactions.create(
model="gemini-3-flash-preview",
input="Hi, my name is Phil."
)
print(f"Model: {interaction1.outputs[-1].text}")
# 2. Second turn (passing previous_interaction_id)
interaction2 = client.interactions.create(
model="gemini-3-flash-preview",
input="What is my name?",
previous_interaction_id=interaction1.id
)
print(f"Model: {interaction2.outputs[-1].text}")
JavaScript
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
// 1. First turn
const interaction1 = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: 'Hi, my name is Phil.'
});
console.log(`Model: ${interaction1.outputs[interaction1.outputs.length - 1].text}`);
// 2. Second turn (passing previous_interaction_id)
const interaction2 = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: 'What is my name?',
previous_interaction_id: interaction1.id
});
console.log(`Model: ${interaction2.outputs[interaction2.outputs.length - 1].text}`);
REST
# 1. 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-flash-preview",
"input": "Hi, my name is Phil."
}'
# 2. Second turn (Replace INTERACTION_ID with the ID from the previous interaction)
# 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-flash-preview",
# "input": "What is my name?",
# "previous_interaction_id": "INTERACTION_ID"
# }'
Recupera interacciones anteriores con estado
Usar la interacción id para recuperar turnos anteriores de la conversación
Python
previous_interaction = client.interactions.get("<YOUR_INTERACTION_ID>")
print(previous_interaction)
JavaScript
const previous_interaction = await client.interactions.get("<YOUR_INTERACTION_ID>");
console.log(previous_interaction);
REST
curl -X GET "https://generativelanguage.googleapis.com/v1beta/interactions/<YOUR_INTERACTION_ID>" \
-H "x-goog-api-key: $GEMINI_API_KEY"
Incluir entrada original
De forma predeterminada, interactions.get() solo devuelve los resultados del modelo. Para incluir la entrada normalizada original en la respuesta, establece include_input en true.
Python
interaction = client.interactions.get(
"<YOUR_INTERACTION_ID>",
include_input=True
)
print(f"Input: {interaction.input}")
print(f"Output: {interaction.outputs}")
JavaScript
const interaction = await client.interactions.get(
"<YOUR_INTERACTION_ID>",
{ include_input: true }
);
console.log(`Input: ${JSON.stringify(interaction.input)}`);
console.log(`Output: ${JSON.stringify(interaction.outputs)}`);
REST
curl -X GET "https://generativelanguage.googleapis.com/v1beta/interactions/<YOUR_INTERACTION_ID>?include_input=true" \
-H "x-goog-api-key: $GEMINI_API_KEY"
Conversación sin estado
Puedes administrar el historial de conversaciones de forma manual en el cliente.
Python
from google import genai
client = genai.Client()
conversation_history = [
{
"role": "user",
"content": "What are the three largest cities in Spain?"
}
]
interaction1 = client.interactions.create(
model="gemini-3-flash-preview",
input=conversation_history
)
print(f"Model: {interaction1.outputs[-1].text}")
conversation_history.append({"role": "model", "content": interaction1.outputs})
conversation_history.append({
"role": "user",
"content": "What is the most famous landmark in the second one?"
})
interaction2 = client.interactions.create(
model="gemini-3-flash-preview",
input=conversation_history
)
print(f"Model: {interaction2.outputs[-1].text}")
JavaScript
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
const conversationHistory = [
{
role: 'user',
content: "What are the three largest cities in Spain?"
}
];
const interaction1 = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: conversationHistory
});
console.log(`Model: ${interaction1.outputs[interaction1.outputs.length - 1].text}`);
conversationHistory.push({ role: 'model', content: interaction1.outputs });
conversationHistory.push({
role: 'user',
content: "What is the most famous landmark in the second one?"
});
const interaction2 = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: conversationHistory
});
console.log(`Model: ${interaction2.outputs[interaction2.outputs.length - 1].text}`);
REST
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-flash-preview",
"input": [
{
"role": "user",
"content": "What are the three largest cities in Spain?"
},
{
"role": "model",
"content": "The three largest cities in Spain are Madrid, Barcelona, and Valencia."
},
{
"role": "user",
"content": "What is the most famous landmark in the second one?"
}
]
}'
Capacidades multimodales
Puedes usar la API de Interactions para casos de uso multimodales, como la comprensión de imágenes o la generación de videos.
Comprensión multimodal
Puedes proporcionar entrada multimodal como datos codificados en base64 intercalados, usar la API de Files para archivos más grandes o pasar un vínculo de acceso público en el campo URI. En las siguientes muestras de código, se muestra el método de URL pública.
Comprensión de imágenes
Python
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input=[
{"type": "text", "text": "Describe the image."},
{
"type": "image",
"uri": "YOUR_URL",
"mime_type": "image/png"
}
]
)
print(interaction.outputs[-1].text)
JavaScript
import {GoogleGenAI} from '@google/genai';
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: [
{type: 'text', text: 'Describe the image.'},
{
type: 'image',
uri: 'YOUR_URL',
mime_type: 'image/png'
}
]
});
console.log(interaction.outputs[interaction.outputs.length - 1].text);
REST
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3-flash-preview",
"input": [
{
"type": "text",
"text": "Describe the image."
},
{
"type": "image",
"uri": "YOUR_URL",
"mime_type": "image/png"
}
]
}'
Comprensión de audio
Python
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input=[
{"type": "text", "text": "What does this audio say?"},
{
"type": "audio",
"uri": "YOUR_URL",
"mime_type": "audio/wav"
}
]
)
print(interaction.outputs[-1].text)
JavaScript
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: [
{ type: 'text', text: 'What does this audio say?' },
{
type: 'audio',
uri: 'YOUR_URL',
mime_type: 'audio/wav'
}
]
});
console.log(interaction.outputs[interaction.outputs.length - 1].text);
REST
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-flash-preview",
"input": [
{"type": "text", "text": "What does this audio say?"},
{
"type": "audio",
"uri": "YOUR_URL",
"mime_type": "audio/wav"
}
]
}'
Comprensión de videos
Python
from google import genai
client = genai.Client()
print("Analyzing video...")
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input=[
{"type": "text", "text": "What is happening in this video? Provide a timestamped summary."},
{
"type": "video",
"uri": "YOUR_URL",
"mime_type": "video/mp4"
}
]
)
print(interaction.outputs[-1].text)
JavaScript
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
console.log('Analyzing video...');
const interaction = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: [
{ type: 'text', text: 'What is happening in this video? Provide a timestamped summary.' },
{
type: 'video',
uri: 'YOUR_URL',
mime_type: 'video/mp4'
}
]
});
console.log(interaction.outputs[interaction.outputs.length - 1].text);
REST
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-flash-preview",
"input": [
{"type": "text", "text": "What is happening in this video?"},
{
"type": "video",
"uri": "YOUR_URL",
"mime_type": "video/mp4"
}
]
}'
Comprensión de documentos (PDF)
Python
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input=[
{"type": "text", "text": "What is this document about?"},
{
"type": "document",
"uri": "YOUR_URL",
"mime_type": "application/pdf"
}
]
)
print(interaction.outputs[-1].text)
JavaScript
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: [
{ type: 'text', text: 'What is this document about?' },
{
type: 'document',
uri: 'YOUR_URL',
mime_type: 'application/pdf'
}
],
});
console.log(interaction.outputs[0].text);
REST
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-flash-preview",
"input": [
{"type": "text", "text": "What is this document about?"},
{
"type": "document",
"uri": "YOUR_URL",
"mime_type": "application/pdf"
}
]
}'
Generación multimodal
Puedes usar la API de Interactions para generar resultados multimodales.
Generación de imágenes
Python
import base64
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3-pro-image-preview",
input="Generate an image of a futuristic city.",
response_modalities=["IMAGE"]
)
for output in interaction.outputs:
if output.type == "image":
print(f"Generated image with mime_type: {output.mime_type}")
# Save the image
with open("generated_city.png", "wb") as f:
f.write(base64.b64decode(output.data))
JavaScript
import { GoogleGenAI } from '@google/genai';
import * as fs from 'fs';
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
model: 'gemini-3-pro-image-preview',
input: 'Generate an image of a futuristic city.',
response_modalities: ['IMAGE']
});
for (const output of interaction.outputs) {
if (output.type === 'image') {
console.log(`Generated image with mime_type: ${output.mime_type}`);
// Save the image
fs.writeFileSync('generated_city.png', Buffer.from(output.data, 'base64'));
}
}
REST
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-pro-image-preview",
"input": "Generate an image of a futuristic city.",
"response_modalities": ["IMAGE"]
}'
Configura el resultado de la imagen
Puedes personalizar las imágenes generadas con image_config dentro de generation_config para controlar la proporción de aspecto y la resolución.
| Parámetro | Opciones | Descripción |
|---|---|---|
aspect_ratio |
1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 |
Controla la proporción entre el ancho y la altura de la imagen de salida. |
image_size |
1k, 2k, 4k |
Establece la resolución de la imagen de salida. |
Python
import base64
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3-pro-image-preview",
input="Generate an image of a futuristic city.",
generation_config={
"image_config": {
"aspect_ratio": "9:16",
"image_size": "2k"
}
}
)
for output in interaction.outputs:
if output.type == "image":
print(f"Generated image with mime_type: {output.mime_type}")
# Save the image
with open("generated_city.png", "wb") as f:
f.write(base64.b64decode(output.data))
JavaScript
import { GoogleGenAI } from '@google/genai';
import * as fs from 'fs';
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
model: 'gemini-3-pro-image-preview',
input: 'Generate an image of a futuristic city.',
generation_config: {
image_config: {
aspect_ratio: '9:16',
image_size: '2k'
}
}
});
for (const output of interaction.outputs) {
if (output.type === 'image') {
console.log(`Generated image with mime_type: ${output.mime_type}`);
// Save the image
fs.writeFileSync('generated_city.png', Buffer.from(output.data, 'base64'));
}
}
REST
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-pro-image-preview",
"input": "Generate an image of a futuristic city.",
"generation_config": {
"image_config": {
"aspect_ratio": "9:16",
"image_size": "2k"
}
}
}'
Generación de voz
Generar voz con sonido natural a partir de texto con el modelo de texto a voz (TTS)
Configura los parámetros de voz, idioma y bocina con el parámetro speech_config.
Python
import base64
from google import genai
import wave
# Set up the wave file to save the output:
def wave_file(filename, pcm, channels=1, rate=24000, sample_width=2):
with wave.open(filename, "wb") as wf:
wf.setnchannels(channels)
wf.setsampwidth(sample_width)
wf.setframerate(rate)
wf.writeframes(pcm)
client = genai.Client()
interaction = client.interactions.create(
model="gemini-2.5-flash-preview-tts",
input="Say the following: WOOHOO This is so much fun!.",
response_modalities=["AUDIO"],
generation_config={
"speech_config": {
"language": "en-us",
"voice": "kore"
}
}
)
for output in interaction.outputs:
if output.type == "audio":
print(f"Generated audio with mime_type: {output.mime_type}")
# Save the audio as wave file to the current directory.
wave_file("generated_audio.wav", base64.b64decode(output.data))
JavaScript
import { GoogleGenAI } from '@google/genai';
import * as fs from 'fs';
import wav from 'wav';
async function saveWaveFile(
filename,
pcmData,
channels = 1,
rate = 24000,
sampleWidth = 2,
) {
return new Promise((resolve, reject) => {
const writer = new wav.FileWriter(filename, {
channels,
sampleRate: rate,
bitDepth: sampleWidth * 8,
});
writer.on('finish', resolve);
writer.on('error', reject);
writer.write(pcmData);
writer.end();
});
}
async function main() {
const GEMINI_API_KEY = process.env.GEMINI_API_KEY;
const client = new GoogleGenAI({apiKey: GEMINI_API_KEY});
const interaction = await client.interactions.create({
model: 'gemini-2.5-flash-preview-tts',
input: 'Say the following: WOOHOO This is so much fun!.',
response_modalities: ['AUDIO'],
generation_config: {
speech_config: {
language: "en-us",
voice: "kore"
}
}
});
for (const output of interaction.outputs) {
if (output.type === 'audio') {
console.log(`Generated audio with mime_type: ${output.mime_type}`);
const audioBuffer = Buffer.from(output.data, 'base64');
// Save the audio as wave file to the current directory
await saveWaveFile("generated_audio.wav", audioBuffer);
}
}
}
await main();
REST
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-2.5-flash-preview-tts",
"input": "Say the following: WOOHOO This is so much fun!.",
"response_modalities": ["AUDIO"],
"generation_config": {
"speech_config": {
"language": "en-us",
"voice": "kore"
}
}
}' | jq -r '.outputs[] | select(.type == "audio") | .data' | base64 -d > generated_audio.pcm
# You may need to install ffmpeg.
ffmpeg -f s16le -ar 24000 -ac 1 -i generated_audio.pcm generated_audio.wav
Generación de voz con varios interlocutores
Genera voz con varios oradores especificando sus nombres en la instrucción y haciéndolos coincidir en speech_config.
La instrucción debe incluir los nombres de los oradores:
TTS the following conversation between Alice and Bob:
Alice: Hi Bob, how are you doing today?
Bob: I'm doing great, thanks for asking! How about you?
Alice: Fantastic! I just learned about the Gemini API.
Luego, configura speech_config con los oradores correspondientes:
"generation_config": {
"speech_config": [
{"voice": "Zephyr", "speaker": "Alice", "language": "en-US"},
{"voice": "Puck", "speaker": "Bob", "language": "en-US"}
]
}
Capacidades de agente
La API de Interactions está diseñada para crear agentes y comunicarse con ellos, y es compatible con llamadas a funciones, herramientas integradas, resultados estructurados y el Protocolo de contexto del modelo (MCP).
Agentes
Puedes usar agentes especializados, como deep-research-pro-preview-12-2025, para tareas complejas. Para obtener más información sobre el agente de Deep Research de Gemini, consulta la guía de Deep Research.
Python
import time
from google import genai
client = genai.Client()
# 1. Start the Deep Research Agent
initial_interaction = client.interactions.create(
input="Research the history of the Google TPUs with a focus on 2025 and 2026.",
agent="deep-research-pro-preview-12-2025",
background=True
)
print(f"Research started. Interaction ID: {initial_interaction.id}")
# 2. Poll for results
while True:
interaction = client.interactions.get(initial_interaction.id)
print(f"Status: {interaction.status}")
if interaction.status == "completed":
print("\nFinal Report:\n", interaction.outputs[-1].text)
break
elif interaction.status in ["failed", "cancelled"]:
print(f"Failed with status: {interaction.status}")
break
time.sleep(10)
JavaScript
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
// 1. Start the Deep Research Agent
const initialInteraction = await client.interactions.create({
input: 'Research the history of the Google TPUs with a focus on 2025 and 2026.',
agent: 'deep-research-pro-preview-12-2025',
background: true
});
console.log(`Research started. Interaction ID: ${initialInteraction.id}`);
// 2. Poll for results
while (true) {
const interaction = await client.interactions.get(initialInteraction.id);
console.log(`Status: ${interaction.status}`);
if (interaction.status === 'completed') {
console.log('\nFinal Report:\n', interaction.outputs[interaction.outputs.length - 1].text);
break;
} else if (['failed', 'cancelled'].includes(interaction.status)) {
console.log(`Failed with status: ${interaction.status}`);
break;
}
await new Promise(resolve => setTimeout(resolve, 10000));
}
REST
# 1. Start the Deep Research Agent
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"input": "Research the history of the Google TPUs with a focus on 2025 and 2026.",
"agent": "deep-research-pro-preview-12-2025",
"background": true
}'
# 2. Poll for results (Replace INTERACTION_ID with the ID from the previous interaction)
# curl -X GET "https://generativelanguage.googleapis.com/v1beta/interactions/INTERACTION_ID" \
# -H "x-goog-api-key: $GEMINI_API_KEY"
Herramientas y llamadas a funciones
En esta sección, se explica cómo usar la llamada a funciones para definir herramientas personalizadas y cómo usar las herramientas integradas de Google en la API de Interactions.
Llamada a función
Python
from google import genai
client = genai.Client()
# 1. Define the tool
def get_weather(location: str):
"""Gets the weather for a given location."""
return f"The weather in {location} is sunny."
weather_tool = {
"type": "function",
"name": "get_weather",
"description": "Gets the weather for a given location.",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string", "description": "The city and state, e.g. San Francisco, CA"}
},
"required": ["location"]
}
}
# 2. Send the request with tools
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input="What is the weather in Paris?",
tools=[weather_tool]
)
# 3. Handle the tool call
for output in interaction.outputs:
if output.type == "function_call":
print(f"Tool Call: {output.name}({output.arguments})")
# Execute tool
result = get_weather(**output.arguments)
# Send result back
interaction = client.interactions.create(
model="gemini-3-flash-preview",
previous_interaction_id=interaction.id,
input=[{
"type": "function_result",
"name": output.name,
"call_id": output.id,
"result": result
}]
)
print(f"Response: {interaction.outputs[-1].text}")
JavaScript
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
// 1. Define the tool
const weatherTool = {
type: 'function',
name: 'get_weather',
description: 'Gets the weather for a given location.',
parameters: {
type: 'object',
properties: {
location: { type: 'string', description: 'The city and state, e.g. San Francisco, CA' }
},
required: ['location']
}
};
// 2. Send the request with tools
let interaction = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: 'What is the weather in Paris?',
tools: [weatherTool]
});
// 3. Handle the tool call
for (const output of interaction.outputs) {
if (output.type === 'function_call') {
console.log(`Tool Call: ${output.name}(${JSON.stringify(output.arguments)})`);
// Execute tool (Mocked)
const result = `The weather in ${output.arguments.location} is sunny.`;
// Send result back
interaction = await client.interactions.create({
model: 'gemini-3-flash-preview',
previous_interaction_id:interaction.id,
input: [{
type: 'function_result',
name: output.name,
call_id: output.id,
result: result
}]
});
console.log(`Response: ${interaction.outputs[interaction.outputs.length - 1].text}`);
}
}
REST
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-flash-preview",
"input": "What is the weather in Paris?",
"tools": [{
"type": "function",
"name": "get_weather",
"description": "Gets the weather for a given location.",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string", "description": "The city and state, e.g. San Francisco, CA"}
},
"required": ["location"]
}
}]
}'
# Handle the tool call and send result back (Replace INTERACTION_ID and CALL_ID)
# 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-flash-preview",
# "previous_interaction_id": "INTERACTION_ID",
# "input": [{
# "type": "function_result",
# "name": "get_weather",
# "call_id": "FUNCTION_CALL_ID",
# "result": "The weather in Paris is sunny."
# }]
# }'
Llamadas a funciones con estado del cliente
Si no quieres usar el estado del servidor, puedes administrarlo todo en el cliente.
Python
from google import genai
client = genai.Client()
functions = [
{
"type": "function",
"name": "schedule_meeting",
"description": "Schedules a meeting with specified attendees at a given time and date.",
"parameters": {
"type": "object",
"properties": {
"attendees": {"type": "array", "items": {"type": "string"}},
"date": {"type": "string", "description": "Date of the meeting (e.g., 2024-07-29)"},
"time": {"type": "string", "description": "Time of the meeting (e.g., 15:00)"},
"topic": {"type": "string", "description": "The subject of the meeting."},
},
"required": ["attendees", "date", "time", "topic"],
},
}
]
history = [{"role": "user","content": [{"type": "text", "text": "Schedule a meeting for 2025-11-01 at 10 am with Peter and Amir about the Next Gen API."}]}]
# 1. Model decides to call the function
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input=history,
tools=functions
)
# add model interaction back to history
history.append({"role": "model", "content": interaction.outputs})
for output in interaction.outputs:
if output.type == "function_call":
print(f"Function call: {output.name} with arguments {output.arguments}")
# 2. Execute the function and get a result
# In a real app, you would call your function here.
# call_result = schedule_meeting(**json.loads(output.arguments))
call_result = "Meeting scheduled successfully."
# 3. Send the result back to the model
history.append({"role": "user", "content": [{"type": "function_result", "name": output.name, "call_id": output.id, "result": call_result}]})
interaction2 = client.interactions.create(
model="gemini-3-flash-preview",
input=history,
)
print(f"Final response: {interaction2.outputs[-1].text}")
else:
print(f"Output: {output}")
JavaScript
// 1. Define the tool
const functions = [
{
type: 'function',
name: 'schedule_meeting',
description: 'Schedules a meeting with specified attendees at a given time and date.',
parameters: {
type: 'object',
properties: {
attendees: { type: 'array', items: { type: 'string' } },
date: { type: 'string', description: 'Date of the meeting (e.g., 2024-07-29)' },
time: { type: 'string', description: 'Time of the meeting (e.g., 15:00)' },
topic: { type: 'string', description: 'The subject of the meeting.' },
},
required: ['attendees', 'date', 'time', 'topic'],
},
},
];
const history = [
{ role: 'user', content: [{ type: 'text', text: 'Schedule a meeting for 2025-11-01 at 10 am with Peter and Amir about the Next Gen API.' }] }
];
// 2. Model decides to call the function
let interaction = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: history,
tools: functions
});
// add model interaction back to history
history.push({ role: 'model', content: interaction.outputs });
for (const output of interaction.outputs) {
if (output.type === 'function_call') {
console.log(`Function call: ${output.name} with arguments ${JSON.stringify(output.arguments)}`);
// 3. Send the result back to the model
history.push({ role: 'user', content: [{ type: 'function_result', name: output.name, call_id: output.id, result: 'Meeting scheduled successfully.' }] });
const interaction2 = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: history,
});
console.log(`Final response: ${interaction2.outputs[interaction2.outputs.length - 1].text}`);
}
}
Resultados de funciones multimodales
El campo result de un function_result acepta una cadena simple o un array de objetos TextContent y ImageContent. Esto te permite devolver imágenes, como capturas de pantalla o gráficos, junto con texto de las llamadas a funciones, de modo que el modelo pueda razonar sobre el resultado visual.
Python
import base64
from google import genai
client = genai.Client()
functions = [
{
"type": "function",
"name": "take_screenshot",
"description": "Takes a screenshot of a specified website.",
"parameters": {
"type": "object",
"properties": {
"url": {"type": "string", "description": "The URL to take a screenshot of."},
},
"required": ["url"],
},
}
]
# 1. Model decides to call the function
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input="Can you take a screenshot of https://google.com and tell me what you see?",
tools=functions
)
for output in interaction.outputs:
if output.type == "function_call":
print(f"Function call: {output.name}({output.arguments})")
# 2. Execute the function and load the image
# Replace with actual function call, pseudo code for reading image from disk
with open("screenshot.png", "rb") as f:
base64_image = base64.b64encode(f.read()).decode("utf-8")
# 3. Return a multimodal result (text + image)
call_result = [
{"type": "text", "text": "Screenshot captured successfully."},
{"type": "image", "mime_type": "image/png", "data": base64_image}
]
response = client.interactions.create(
model="gemini-3-flash-preview",
tools=functions,
previous_interaction_id=interaction.id,
input=[{
"type": "function_result",
"name": output.name,
"call_id": output.id,
"result": call_result
}]
)
print(f"Response: {response.outputs[-1].text}")
JavaScript
import { GoogleGenAI } from '@google/genai';
import * as fs from 'fs';
const client = new GoogleGenAI({});
const functions = [
{
type: 'function',
name: 'take_screenshot',
description: 'Takes a screenshot of a specified website.',
parameters: {
type: 'object',
properties: {
url: { type: 'string', description: 'The URL to take a screenshot of.' },
},
required: ['url'],
},
}
];
// 1. Model decides to call the function
let interaction = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: 'Can you take a screenshot of https://google.com and tell me what you see?',
tools: functions
});
for (const output of interaction.outputs) {
if (output.type === 'function_call') {
console.log(`Function call: ${output.name}(${JSON.stringify(output.arguments)})`);
// 2. Execute the function and load the image
// Replace with actual function call, pseudo code for reading image from disk
const base64Image = fs.readFileSync('screenshot.png').toString('base64');
// 3. Return a multimodal result (text + image)
const callResult = [
{ type: 'text', text: 'Screenshot captured successfully.' },
{ type: 'image', mime_type: 'image/png', data: base64Image }
];
const response = await client.interactions.create({
model: 'gemini-3-flash-preview',
tools: functions,
previous_interaction_id: interaction.id,
input: [{
type: 'function_result',
name: output.name,
call_id: output.id,
result: callResult
}]
});
console.log(`Response: ${response.outputs[response.outputs.length - 1].text}`);
}
}
REST
# 1. Send request with tools (will return a function_call)
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-flash-preview",
"input": "Can you take a screenshot of https://google.com and tell me what you see?",
"tools": [{
"type": "function",
"name": "take_screenshot",
"description": "Takes a screenshot of a specified website.",
"parameters": {
"type": "object",
"properties": {
"url": {"type": "string", "description": "The URL to take a screenshot of."}
},
"required": ["url"]
}
}]
}'
# 2. Send multimodal result back (Replace INTERACTION_ID, CALL_ID, and BASE64_IMAGE)
# 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-flash-preview",
# "tools": [{"type": "function", "name": "take_screenshot", "description": "Takes a screenshot of a specified website.", "parameters": {"type": "object", "properties": {"url": {"type": "string"}}, "required": ["url"]}}],
# "previous_interaction_id": "INTERACTION_ID",
# "input": [{
# "type": "function_result",
# "name": "take_screenshot",
# "call_id": "CALL_ID",
# "result": [
# {"type": "text", "text": "Screenshot captured successfully."},
# {"type": "image", "mime_type": "image/png", "data": "BASE64_IMAGE"}
# ]
# }]
# }'
Herramientas integradas
Gemini incluye herramientas integradas, como Fundamentación con la Búsqueda de Google, Fundamentación con la Búsqueda de imágenes de Google, Fundamentación con Google Maps, Ejecución de código, Contexto de URL y Uso de la computadora.
Fundamentación con la Búsqueda de Google
Python
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input="Who won the last Super Bowl?",
tools=[{"type": "google_search"}]
)
# Find the text output (not the GoogleSearchResultContent)
text_output = next((o for o in interaction.outputs if o.type == "text"), None)
if text_output:
print(text_output.text)
JavaScript
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: 'Who won the last Super Bowl?',
tools: [{ type: 'google_search' }]
});
// Find the text output (not the GoogleSearchResultContent)
const textOutput = interaction.outputs.find(o => o.type === 'text');
if (textOutput) console.log(textOutput.text);
REST
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-flash-preview",
"input": "Who won the last Super Bowl?",
"tools": [{"type": "google_search"}]
}'
Fundamentación con la Búsqueda de imágenes de Google (solo para imágenes Flash 3.1)
La fundamentación con la Búsqueda con imágenes de Google permite que los modelos usen imágenes web recuperadas a través de la Búsqueda con imágenes de Google como contexto visual para la generación de imágenes. La Búsqueda de imágenes es un nuevo tipo de búsqueda dentro de la herramienta existente de fundamentación con la Búsqueda de Google, que funciona junto con la Búsqueda web estándar.
Cómo habilitar la Búsqueda con imágenes
Solicita resultados de imágenes agregando "image_search" al array search_types de la herramienta google_search.
Python
interaction = client.interactions.create(
model="gemini-3.1-flash-image-preview",
input="Search for an image of a vintage gold bitcoin coin.",
tools=[{
"type": "google_search",
"search_types": ["web_search", "image_search"]
}]
)
JavaScript
const interaction = await client.interactions.create({
model: 'gemini-3.1-flash-image-preview',
input: 'Search for an image of a vintage gold bitcoin coin.',
tools: [{
type: 'google_search',
search_types: ['web_search', 'image_search']
}]
});
REST
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.1-flash-image-preview",
"input": "Search for an image of a vintage gold bitcoin coin.",
"tools": [{
"type": "google_search",
"search_types": ["web_search", "image_search"]
}]
}'
Requisitos de visualización obligatorios
Para cumplir con las Condiciones del Servicio de la Búsqueda de Google, tu IU debe implementar dos niveles distintos de atribución:
Atribución de la Búsqueda de Google
Debes mostrar las sugerencias de búsqueda de "Verificar en Google" que se proporcionan en el bloque
google_search_result.- Campo:
rendered_content(HTML/CSS) - Acción: Renderiza este chip tal como está cerca de la respuesta del modelo.
- Campo:
Atribución del publicador
Debes proporcionar un vínculo a la "página contenedora" (la página de destino) de cada imagen que se muestre.
- Campo:
url(se encuentra dentro del arrayresult) - Requisito: Debes proporcionar una ruta directa con un solo clic desde la imagen hasta la página web fuente que la contiene. No se permite usar visores de imágenes intermedios ni rutas de varios clics.
- Campo:
Cómo controlar la respuesta fundamentada
En el siguiente fragmento, se muestra cómo controlar los bloques de respuesta intercalados para los datos de imágenes sin procesar y la atribución obligatoria.
Python
for output in interaction.outputs:
# 1. Handle raw multimodal image data
if output.type == "image":
print(f"🖼️ Image received: {output.mime_type}")
# 'data' contains base64-encoded image content
display_image(output.data, output.mime_type)
# 2. Handle mandatory Search and Publisher attribution
elif output.type == "google_search_result":
# Display Google Search Attribution
if output.rendered_content:
render_html_chips(output.rendered_content)
# Provide Publisher Attribution
for source in output.result:
print(f"Source Page: {source['url']}")
JavaScript
for (const output of interaction.outputs) {
// 1. Handle raw multimodal image data
if (output.type === 'image') {
console.log(`🖼️ Image received: ${output.mimeType}`);
// 'data' contains base64-encoded image content
displayImage(output.data, output.mimeType);
}
// 2. Handle mandatory Search and Publisher attribution
else if (output.type === 'google_search_result') {
// Display Google Search Attribution
if (output.renderedContent) {
renderHtmlChips(output.renderedContent);
}
// Provide Publisher Attribution
for (const source of output.result) {
console.log(`Source Page: ${source.url}`);
}
}
}
Esquema de salida esperado
El bloque de imagen (tipo: "image") contiene los datos visuales sin procesar que generó o recuperó el modelo.
{
"type": "image",
"mime_type": "image/png",
"data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB..." // Base64 content
}
El bloque de resultados (tipo: "google_search_result") contiene los metadatos de atribución obligatorios vinculados a la búsqueda.
{
"type": "google_search_result",
"call_id": "search_002",
"rendered_content": "<div class=\"search-suggestions\">...</div>", // Google Search Attribution
"result": [
{
"url": "https://example.com/source-page", // Publisher Attribution
"title": "Source Page Title"
}
]
}
Fundamentación con Google Maps
La fundamentación con Google Maps permite que los modelos usen datos de Google Maps para el contexto visual, las marcas de mapa y el descubrimiento basado en la ubicación.
Python
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input="What's the best coffee shop near me?",
tools=[{"type": "google_maps"}]
)
JavaScript
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: 'What\'s the best coffee shop near me?',
tools: [{ type: 'google_maps' }]
});
REST
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-flash-preview",
"input": "What is the best coffee shop near me?",
"tools": [{"type": "google_maps"}]
}'
Requisitos de uso del servicio
Cuando presentes resultados de la fundamentación con Google Maps, debes cumplir con las Condiciones del Servicio de Google Maps. Debes informar a tus usuarios sobre lo siguiente y cumplir con estos requisitos de visualización:
- Informa al usuario: Después del contenido generado, incluye de inmediato las fuentes asociadas de Google Maps. Las fuentes deben poder verse en una sola interacción del usuario.
- Vínculos mostrados: Genera una vista previa del vínculo para cada fuente (incluidos los fragmentos de opiniones si están presentes).
- Atribución a "Google Maps": Sigue los lineamientos de atribución de texto.
- Mostrar el título de la fuente
- Vincula la fuente con la URL proporcionada.
- Lineamientos de atribución: No modifiques el texto "Google Maps" (uso de mayúsculas, ajuste de texto). Evita la traducción del navegador con
translate="no".
Cómo controlar la respuesta
En el siguiente fragmento, se muestra cómo controlar la respuesta extrayendo el texto y las citas intercaladas (incluidos los fragmentos de opiniones) para cumplir con los requisitos de visualización.
Python
for output in interaction.outputs:
if output.type == "text":
print(output.text)
if output.annotations:
print("\nSources:")
for annotation in output.annotations:
if annotation.get("type") == "place_citation":
# Display place citation
print(f"- {annotation['name']} (Google Maps): {annotation['url']}")
# Display review snippets if available
if "review_snippets" in annotation:
for snippet in annotation["review_snippets"]:
print(f" - Review: {snippet['title']} ({snippet['url']})")
elif output.type == "google_maps_result":
# You can also access the raw place data here if needed for map pins
pass
JavaScript
for (const output of interaction.outputs) {
if (output.type === 'text') {
console.log(output.text);
if (output.annotations) {
console.log('\nSources:');
for (const annotation of output.annotations) {
if (annotation.type === 'place_citation') {
console.log(`- ${annotation.name} (Google Maps): ${annotation.url}`);
if (annotation.review_snippets) {
for (const snippet of annotation.review_snippets) {
console.log(` - Review: ${snippet.title} (${snippet.url})`);
}
}
}
}
}
}
}
Esquema de salida esperado
Cuando uses la Fundamentación con Google Maps, espera el siguiente esquema de salida.
El bloque de resultados (tipo: "google_maps_result") contiene los datos estructurados del lugar.
{
"type": "google_maps_result",
"call_id": "maps_001",
"result": {
"places": [
{
"place_id": "ChIJ...",
"name": "Blue Bottle Coffee", // Google Maps Source
"url": "https://maps.google.com/?cid=...", // Google Maps Link
"review_snippets": [
{
"title": "Amazing single-origin selections",
"url": "https://maps.google.com/...",
"review_id": "def456"
}
]
}
],
"widget_context_token": "widgetcontent/..."
},
"signature": "..."
}
El bloque de texto (tipo: "text") contiene el contenido generado con anotaciones intercaladas.
{
"type": "text",
"text": "Blue Bottle Coffee (4.5★) on Mint Plaza was rated highly online...",
"annotations": [
{
"type": "place_citation",
"place_id": "ChIJ...",
"name": "Blue Bottle Coffee", // Google Maps Source
"url": "https://maps.google.com/?cid=...", // Google Maps Link
"review_snippets": [
{
"title": "Amazing single-origin selections",
"url": "https://maps.google.com/...",
"review_id": "def456"
}
],
"start_index": 0,
"end_index": 42
}
]
}
Ejecución de código
Python
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input="Calculate the 50th Fibonacci number.",
tools=[{"type": "code_execution"}]
)
print(interaction.outputs[-1].text)
JavaScript
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: 'Calculate the 50th Fibonacci number.',
tools: [{ type: 'code_execution' }]
});
console.log(interaction.outputs[interaction.outputs.length - 1].text);
REST
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-flash-preview",
"input": "Calculate the 50th Fibonacci number.",
"tools": [{"type": "code_execution"}]
}'
Contexto de URL
Python
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input="Summarize the content of https://www.wikipedia.org/",
tools=[{"type": "url_context"}]
)
# Find the text output (not the URLContextResultContent)
text_output = next((o for o in interaction.outputs if o.type == "text"), None)
if text_output:
print(text_output.text)
JavaScript
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: 'Summarize the content of https://www.wikipedia.org/',
tools: [{ type: 'url_context' }]
});
// Find the text output (not the URLContextResultContent)
const textOutput = interaction.outputs.find(o => o.type === 'text');
if (textOutput) console.log(textOutput.text);
REST
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-flash-preview",
"input": "Summarize the content of https://www.wikipedia.org/",
"tools": [{"type": "url_context"}]
}'
Uso de la computadora
Python
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-2.5-computer-use-preview-10-2025",
input="Search for highly rated smart fridges with touchscreen, 2 doors, around 25 cu ft, priced below 4000 dollars on Google Shopping. Create a bulleted list of the 3 cheapest options in the format of name, description, price in an easy-to-read layout.",
tools=[{
"type": "computer_use",
"environment": "browser",
"excludedPredefinedFunctions": ["drag_and_drop"]
}]
)
# The response will contain tool calls (actions) for the computer interface
# or text explaining the action
for output in interaction.outputs:
print(output)
JavaScript
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
model: 'gemini-2.5-computer-use-preview-10-2025',
input: 'Search for highly rated smart fridges with touchscreen, 2 doors, around 25 cu ft, priced below 4000 dollars on Google Shopping. Create a bulleted list of the 3 cheapest options in the format of name, description, price in an easy-to-read layout.',
tools: [{
type: 'computer_use',
environment: 'browser',
excludedPredefinedFunctions: ['drag_and_drop']
}]
});
// The response will contain tool calls (actions) for the computer interface
// or text explaining the action
interaction.outputs.forEach(output => console.log(output));
REST
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-2.5-computer-use-preview-10-2025",
"input": "Search for highly rated smart fridges with touchscreen, 2 doors, around 25 cu ft, priced below 4000 dollars on Google Shopping. Create a bulleted list of the 3 cheapest options in the format of name, description, price in an easy-to-read layout.",
"tools": [{
"type": "computer_use",
"environment": "browser",
"excludedPredefinedFunctions": ["drag_and_drop"]
}]
}'
Búsqueda de archivos
Python
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input="Tell me about the book 'I, Claudius'",
tools=[{"type": "file_search", "file_search_store_names": ["fileSearchStores/my-store-name"]}]
)
# Find the text output
text_output = next((o for o in interaction.outputs if o.type == "text"), None)
if text_output:
print(text_output.text)
JavaScript
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: "Tell me about the book 'I, Claudius'",
tools: [{ type: 'file_search', file_search_store_names: ['fileSearchStores/my-store-name'] }]
});
// Find the text output
const textOutput = interaction.outputs.find(o => o.type === 'text');
if (textOutput) console.log(textOutput.text);
REST
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-flash-preview",
"input": "Tell me about the book I, Claudius",
"tools": [{"type": "file_search", "file_search_store_names": ["fileSearchStores/my-store-name"]}]
}'
Combinación de herramientas integradas y llamadas a funciones
Puedes usar herramientas integradas y llamadas a funciones juntas en la misma solicitud.
Python
from google import genai
import json
client = genai.Client()
get_weather = {
"type": "function",
"name": "getWeather",
"description": "Gets the weather for a requested city.",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "The city and state, e.g. Utqiaġvik, Alaska",
},
},
"required": ["city"],
},
}
tools = [
{"type": "google_search"}, # Built-in tool
get_weather # Custom tool (callable)
]
# Turn 1: Initial request with both tools enabled
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input="What is the northernmost city in the United States? What's the weather like there today?",
tools=tools
)
for output in interaction.outputs:
if output.type == "function_call":
print(f"Function call: {output.name} (ID: {output.id})")
# Execute your custom function locally
result = {"response": "Very cold. 22 degrees Fahrenheit."}
# Turn 2: Provide the function result back to the model.
# Passing `previous_interaction_id` automatically circulates the
# built-in Google Search context (and thought signatures) from Turn 1
interaction_2 = client.interactions.create(
model="gemini-3-flash-preview",
previous_interaction_id=interaction.id,
tools=tools,
input=[{
"type": "function_result",
"name": output.name,
"call_id": output.id,
"result": json.dumps(result)
}]
)
for output in interaction_2.outputs:
if output.type == "text":
print(output.text)
JavaScript
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
const weatherTool = {
type: 'function',
name: 'get_weather',
description: 'Gets the weather for a given location.',
parameters: {
type: 'object',
properties: {
location: { type: 'string', description: 'The city and state, e.g. San Francisco, CA' }
},
required: ['location']
}
};
const tools = [
{type: 'google_search'}, // Built-in tool
weatherTool // Custom tool
];
// Turn 1: Initial request with both tools enabled
let interaction = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: "What is the northernmost city in the United States? What's the weather like there today?",
tools: tools
});
for (const output of interaction.outputs) {
if (output.type == "function_call") {
console.log(`Function call: ${output.name} (ID: ${output.id})`);
// Execute your custom function locally
const result = {response: "Very cold. 22 degrees Fahrenheit."};
// Turn 2: Provide the function result back to the model.
// Passing `previous_interaction_id` automatically circulates the
// built-in Google Search context (and thought signatures) from Turn 1
const interaction_2 = await client.interactions.create({
model: "gemini-3-flash-preview",
previous_interaction_id: interaction.id,
tools: tools,
input: [{
type: "function_result",
name: output.name,
call_id: output.id,
result: JSON.stringify(result)
}]
});
for (const output_2 of interaction_2.outputs) {
if (output_2.type == "text") {
console.log(output_2.text);
}
}
}
}
REST
# Turn 1: Initial request with both tools enabled
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-flash-preview",
"input": "What is the northernmost city in the United States? What is the weather like there today?",
"tools": [
{"type": "google_search"},
{
"type": "function",
"name": "get_weather",
"description": "Gets the weather for a given location.",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string", "description": "The city and state, e.g. San Francisco, CA"}
},
"required": ["location"]
}
}
]
}'
# Assuming Turn 1 returns a function_call for get_weather,
# replace INTERACTION_ID and CALL_ID with values from Turn 1 response.
# Turn 2: Provide the function result back to the model.
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-flash-preview",
"previous_interaction_id": "INTERACTION_ID",
"tools": [
{"type": "google_search"},
{
"type": "function",
"name": "get_weather",
"description": "Gets the weather for a given location.",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string", "description": "The city and state, e.g. San Francisco, CA"}
},
"required": ["location"]
}
}
],
"input": [{
"type": "function_result",
"name": "get_weather",
"call_id": "CALL_ID",
"result": "{\"response\": \"Very cold. 22 degrees Fahrenheit.\"}"
}]
}'
Cómo comprender la circulación del contexto de la herramienta
Los modelos de Gemini 3 y versiones posteriores admiten la circulación del contexto de herramientas para mantener una "memoria" confiable de las acciones del servidor. Cuando se activa una herramienta integrada (como la Búsqueda de Google), la API genera partes específicas de toolCall y toolResponse. Estas partes contienen el contexto preciso que el modelo necesita para razonar sobre esos resultados en el siguiente turno.
- Con estado (recomendado): Si usas
previous_interaction_id, la API administra esta circulación automáticamente. - Sin estado: Si administras el historial de forma manual, debes incluir estos bloques exactamente como los devolvió la API en tu array de entrada.
Protocolo de contexto del modelo (MCP) remoto
La integración de MCP remota simplifica el desarrollo de agentes, ya que permite que la API de Gemini llame directamente a herramientas externas alojadas en servidores remotos.
Python
import datetime
from google import genai
client = genai.Client()
mcp_server = {
"type": "mcp_server",
"name": "weather_service",
"url": "https://gemini-api-demos.uc.r.appspot.com/mcp"
}
today = datetime.date.today().strftime("%d %B %Y")
interaction = client.interactions.create(
model="gemini-2.5-flash",
input="What is the weather like in New York today?",
tools=[mcp_server],
system_instruction=f"Today is {today}."
)
print(interaction.outputs[-1].text)
JavaScript
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
const mcpServer = {
type: 'mcp_server',
name: 'weather_service',
url: 'https://gemini-api-demos.uc.r.appspot.com/mcp'
};
const today = new Date().toDateString();
const interaction = await client.interactions.create({
model: 'gemini-2.5-flash',
input: 'What is the weather like in New York today?',
tools: [mcpServer],
system_instruction: `Today is ${today}.`
});
console.log(interaction.outputs[interaction.outputs.length - 1].text);
REST
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-2.5-flash",
"input": "What is the weather like in New York today?",
"tools": [{
"type": "mcp_server",
"name": "weather_service",
"url": "https://gemini-api-demos.uc.r.appspot.com/mcp"
}],
"system_instruction": "Today is '"$(date +"%du%Bt%Y")"' YYYY-MM-DD>."
}'
Notas importantes:
- El MCP remoto solo funciona con servidores HTTP transmitibles (no se admiten servidores SSE).
- El MCP remoto no funciona con los modelos de Gemini 3 (esta función estará disponible pronto).
- Los nombres de los servidores de MCP no deben incluir el carácter "-" (en su lugar, usa nombres de servidor en formato snake_case).
Salida estructurada (esquema JSON)
Para aplicar un formato de salida JSON específico, proporciona un esquema JSON en el parámetro response_format. Esto es útil para tareas como moderación, clasificación o extracción de datos.
Python
from google import genai
from pydantic import BaseModel, Field
from typing import Literal, Union
client = genai.Client()
class SpamDetails(BaseModel):
reason: str = Field(description="The reason why the content is considered spam.")
spam_type: Literal["phishing", "scam", "unsolicited promotion", "other"]
class NotSpamDetails(BaseModel):
summary: str = Field(description="A brief summary of the content.")
is_safe: bool = Field(description="Whether the content is safe for all audiences.")
class ModerationResult(BaseModel):
decision: Union[SpamDetails, NotSpamDetails]
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input="Moderate the following content: 'Congratulations! You've won a free cruise. Click here to claim your prize: www.definitely-not-a-scam.com'",
response_format=ModerationResult.model_json_schema(),
)
parsed_output = ModerationResult.model_validate_json(interaction.outputs[-1].text)
print(parsed_output)
JavaScript
import { GoogleGenAI } from '@google/genai';
import { z } from 'zod';
const client = new GoogleGenAI({});
const moderationSchema = z.object({
decision: z.union([
z.object({
reason: z.string().describe('The reason why the content is considered spam.'),
spam_type: z.enum(['phishing', 'scam', 'unsolicited promotion', 'other']).describe('The type of spam.'),
}).describe('Details for content classified as spam.'),
z.object({
summary: z.string().describe('A brief summary of the content.'),
is_safe: z.boolean().describe('Whether the content is safe for all audiences.'),
}).describe('Details for content classified as not spam.'),
]),
});
const interaction = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: "Moderate the following content: 'Congratulations! You've won a free cruise. Click here to claim your prize: www.definitely-not-a-scam.com'",
response_format: z.toJSONSchema(moderationSchema),
});
console.log(interaction.outputs[0].text);
REST
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-flash-preview",
"input": "Moderate the following content: 'Congratulations! You've won a free cruise. Click here to claim your prize: www.definitely-not-a-scam.com'",
"response_format": {
"type": "object",
"properties": {
"decision": {
"type": "object",
"properties": {
"reason": {"type": "string", "description": "The reason why the content is considered spam."},
"spam_type": {"type": "string", "description": "The type of spam."}
},
"required": ["reason", "spam_type"]
}
},
"required": ["decision"]
}
}'
Combinación de herramientas y resultados estructurados
Combina herramientas integradas con resultados estructurados para obtener un objeto JSON confiable basado en la información recuperada por una herramienta.
Python
from google import genai
from pydantic import BaseModel, Field
from typing import Literal, Union
client = genai.Client()
class SpamDetails(BaseModel):
reason: str = Field(description="The reason why the content is considered spam.")
spam_type: Literal["phishing", "scam", "unsolicited promotion", "other"]
class NotSpamDetails(BaseModel):
summary: str = Field(description="A brief summary of the content.")
is_safe: bool = Field(description="Whether the content is safe for all audiences.")
class ModerationResult(BaseModel):
decision: Union[SpamDetails, NotSpamDetails]
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input="Moderate the following content: 'Congratulations! You've won a free cruise. Click here to claim your prize: www.definitely-not-a-scam.com'",
response_format=ModerationResult.model_json_schema(),
tools=[{"type": "url_context"}]
)
parsed_output = ModerationResult.model_validate_json(interaction.outputs[-1].text)
print(parsed_output)
JavaScript
import { GoogleGenAI } from '@google/genai';
import { z } from 'zod'; // Assuming zod is used for schema generation, or define manually
const client = new GoogleGenAI({});
const obj = z.object({
winning_team: z.string(),
score: z.string(),
});
const schema = z.toJSONSchema(obj);
const interaction = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: 'Who won the last euro?',
tools: [{ type: 'google_search' }],
response_format: schema,
});
console.log(interaction.outputs[0].text);
REST
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-flash-preview",
"input": "Who won the last euro?",
"tools": [{"type": "google_search"}],
"response_format": {
"type": "object",
"properties": {
"winning_team": {"type": "string"},
"score": {"type": "string"}
}
}
}'
Funciones avanzadas
También hay funciones avanzadas adicionales que te brindan más flexibilidad para trabajar con la API de Interactions.
Transmisión
Recibe respuestas de forma incremental a medida que se generan.
Cuando es stream=true, el evento interaction.complete final no contiene el contenido generado en el campo outputs. Solo contiene metadatos de uso y el estado final. Debes agregar eventos content.delta del cliente para reconstruir la respuesta completa o los argumentos de la llamada a la herramienta.
Python
from google import genai
client = genai.Client()
stream = client.interactions.create(
model="gemini-3-flash-preview",
input="Explain quantum entanglement in simple terms.",
stream=True
)
for chunk in stream:
if chunk.event_type == "content.delta":
if chunk.delta.type == "text":
print(chunk.delta.text, end="", flush=True)
elif chunk.delta.type == "thought":
print(chunk.delta.thought, end="", flush=True)
elif chunk.event_type == "interaction.complete":
print(f"\n\n--- Stream Finished ---")
print(f"Total Tokens: {chunk.interaction.usage.total_tokens}")
JavaScript
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
const stream = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: 'Explain quantum entanglement in simple terms.',
stream: true,
});
for await (const chunk of stream) {
if (chunk.event_type === 'content.delta') {
if (chunk.delta.type === 'text' && 'text' in chunk.delta) {
process.stdout.write(chunk.delta.text);
} else if (chunk.delta.type === 'thought' && 'thought' in chunk.delta) {
process.stdout.write(chunk.delta.thought);
}
} else if (chunk.event_type === 'interaction.complete') {
console.log('\n\n--- Stream Finished ---');
console.log(`Total Tokens: ${chunk.interaction.usage.total_tokens}`);
}
}
REST
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?alt=sse" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"model": "gemini-3-flash-preview",
"input": "Explain quantum entanglement in simple terms.",
"stream": true
}'
Tipos de eventos de transmisión
Cuando se habilita la transmisión, la API devuelve eventos enviados por el servidor (SSE). Cada evento tiene un campo event_type que indica su propósito. En la referencia de la API, se encuentra la lista completa de los tipos de eventos.
| Tipo de evento | Descripción |
|---|---|
interaction.start |
Es el primer evento. Contiene la interacción id y el status inicial (in_progress). |
interaction.status_update |
Indica cambios de estado (p.ej., in_progress). |
content.start |
Marca el inicio de un nuevo bloque de salida. Contiene index y contenido type (p.ej., text, thought). |
content.delta |
Actualizaciones de contenido incrementales Contiene los datos parciales con la clave delta.type. |
content.stop |
Marca el final de un bloque de salida en index. |
interaction.complete |
Es el evento final. Contiene id, status, usage y metadatos. Nota: outputs es None. Debes reconstruir los resultados a partir de los eventos content.*. |
error |
Indica que se produjo un error. Contiene error.code y error.message. |
Cómo reconstruir el objeto Interaction a partir de eventos de transmisión
A diferencia de las respuestas sin transmisión, las respuestas de transmisión no contienen un array outputs. Debes reconstruir los resultados acumulando contenido de los eventos content.delta.
Python
from google import genai
client = genai.Client()
stream = client.interactions.create(
model="gemini-3-flash-preview",
input="Write a haiku about Python programming.",
stream=True
)
# Accumulate outputs by index
outputs = {}
usage = None
for chunk in stream:
if chunk.event_type == "content.start":
outputs[chunk.index] = {"type": chunk.content.type}
elif chunk.event_type == "content.delta":
output = outputs[chunk.index]
if chunk.delta.type == "text":
output["text"] = output.get("text", "") + chunk.delta.text
elif chunk.delta.type == "thought_signature":
output["signature"] = chunk.delta.signature
elif chunk.delta.type == "thought_summary":
output["summary"] = output.get("summary", "") + getattr(chunk.delta.content, "text", "")
elif chunk.event_type == "interaction.complete":
usage = chunk.interaction.usage
# Final outputs list (sorted by index)
final_outputs = [outputs[i] for i in sorted(outputs.keys())]
print(f"\n\nOutputs: {final_outputs}")
JavaScript
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
const stream = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: 'Write a haiku about Python programming.',
stream: true,
});
// Accumulate outputs by index
const outputs = new Map();
let usage = null;
for await (const chunk of stream) {
if (chunk.event_type === 'content.start') {
outputs.set(chunk.index, { type: chunk.content.type });
} else if (chunk.event_type === 'content.delta') {
const output = outputs.get(chunk.index);
if (chunk.delta.type === 'text') {
output.text = (output.text || '') + chunk.delta.text;
process.stdout.write(chunk.delta.text);
} else if (chunk.delta.type === 'thought_signature') {
output.signature = chunk.delta.signature;
} else if (chunk.delta.type === 'thought_summary') {
output.summary = (output.summary || '') + (chunk.delta.content?.text || '');
}
} else if (chunk.event_type === 'interaction.complete') {
usage = chunk.interaction.usage;
}
}
// Final outputs list (sorted by index)
const finalOutputs = [...outputs.entries()]
.sort((a, b) => a[0] - b[0])
.map(([_, output]) => output);
console.log(`\n\nOutputs:`, finalOutputs);
Llamadas a herramientas de transmisión
Cuando se usan herramientas con transmisión, el modelo genera llamadas a funciones como una secuencia de eventos content.delta en la transmisión. A diferencia del texto, los argumentos de la herramienta se entregan como objetos JSON completos dentro de un solo evento content.delta. El array outputs está vacío en el evento interaction.complete durante la transmisión. Debes capturar las llamadas a herramientas de los deltas como se muestra a continuación.
Python
from google import genai
import json
client = genai.Client()
weather_tool = {
"type": "function",
"name": "get_weather",
"description": "Gets the weather for a given location.",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string", "description": "The city and state"}
},
"required": ["location"]
}
}
stream = client.interactions.create(
model="gemini-3-flash-preview",
input="What is the weather in Paris?",
tools=[weather_tool],
stream=True
)
# A map to capture tool calls by their ID as they arrive
function_calls = {}
for chunk in stream:
if chunk.event_type == "content.delta":
if chunk.delta.type == "text" and chunk.delta.text:
print(chunk.delta.text, end="", flush=True)
elif chunk.delta.type == "function_call":
print(f"\nExecuting {chunk.delta.name} immediately...")
# result = my_tools[chunk.delta.name](**chunk.delta.arguments)
function_calls[chunk.delta.id] = chunk.delta
elif chunk.event_type == "interaction.complete":
print("\n\nAll tools executed. Stream finished.")
JavaScript
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
const weatherTool = {
type: 'function',
name: 'get_weather',
description: 'Gets the weather for a given location.',
parameters: {
type: 'object',
properties: {
location: { type: 'string', description: 'The city and state' }
},
required: ['location']
}
};
const stream = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: 'What is the weather in Paris?',
tools: [weatherTool],
stream: true,
});
const toolCalls = new Map();
for await (const chunk of stream) {
if (chunk.event_type === 'content.delta') {
if (chunk.delta.type === 'text' && chunk.delta.text) {
process.stdout.write(chunk.delta.text);
} else if (chunk.delta.type === 'function_call') {
console.log(`\nExecuting ${chunk.delta.name} immediately...`);
// const result = myTools[chunk.delta.name](chunk.delta.arguments);
toolCalls.set(chunk.delta.id, chunk.delta);
}
} else if (chunk.event_type === 'interaction.complete') {
console.log('\n\nAll tools executed. Stream finished.');
}
}
REST
# When streaming via SSE, capture function_call data from content.delta events.
# The 'arguments' field arrives as a complete JSON object once generated.
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?alt=sse" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"model": "gemini-3-flash-preview",
"input": "What is the weather in Paris?",
"tools": [{
"type": "function",
"name": "get_weather",
"description": "Gets the weather for a given location.",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string", "description": "The city and state"}
},
"required": ["location"]
}
}],
"stream": true
}'
Configuración
Personaliza el comportamiento del modelo con generation_config.
Python
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input="Tell me a story about a brave knight.",
generation_config={
"temperature": 0.7,
"max_output_tokens": 500,
"thinking_level": "low",
}
)
print(interaction.outputs[-1].text)
JavaScript
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: 'Tell me a story about a brave knight.',
generation_config: {
temperature: 0.7,
max_output_tokens: 500,
thinking_level: 'low',
}
});
console.log(interaction.outputs[interaction.outputs.length - 1].text);
REST
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-flash-preview",
"input": "Tell me a story about a brave knight.",
"generation_config": {
"temperature": 0.7,
"max_output_tokens": 500,
"thinking_level": "low"
}
}'
Pensando
Los modelos de Gemini 2.5 y versiones posteriores utilizan un proceso de razonamiento interno llamado "pensamiento" antes de generar una respuesta. Esto ayuda al modelo a producir mejores respuestas para tareas complejas, como matemáticas, programación y razonamiento de varios pasos.
Nivel de pensamiento
El parámetro thinking_level te permite controlar la profundidad del razonamiento del modelo:
| Nivel | Descripción | Modelos compatibles |
|---|---|---|
minimal |
Coincide con el parámetro de configuración "sin pensar" para la mayoría de las búsquedas. En algunos casos, los modelos pueden pensar de forma muy mínima. Minimiza la latencia y el costo. | Solo modelos Flash (p.ej., Gemini 3 Flash) |
low |
Es un razonamiento ligero que prioriza la latencia y el ahorro de costos para seguir instrucciones y chatear de forma sencilla. | Todos los modelos de pensamiento |
medium |
Pensamiento equilibrado para la mayoría de las tareas. | Solo modelos Flash (p.ej., Gemini 3 Flash) |
high |
(Predeterminado) Maximiza la profundidad del razonamiento. Es posible que el modelo tarde mucho más en generar el primer token, pero la respuesta será más razonada. | Todos los modelos de pensamiento |
Resúmenes de pensamiento
El razonamiento del modelo se representa como bloques de pensamiento (type: "thought") en los resultados de la respuesta. Puedes controlar si deseas recibir resúmenes legibles del proceso de pensamiento con el parámetro thinking_summaries:
| Valor | Descripción |
|---|---|
auto |
(Predeterminado) Muestra resúmenes de pensamientos cuando están disponibles. |
none |
Inhabilita los resúmenes de pensamientos. |
Python
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input="Solve this step by step: What is 15% of 240?",
generation_config={
"thinking_level": "high",
"thinking_summaries": "auto"
}
)
for output in interaction.outputs:
if output.type == "thought":
print(f"Thinking: {output.summary}")
elif output.type == "text":
print(f"Answer: {output.text}")
JavaScript
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: 'Solve this step by step: What is 15% of 240?',
generation_config: {
thinking_level: 'high',
thinking_summaries: 'auto'
}
});
for (const output of interaction.outputs) {
if (output.type === 'thought') {
console.log(`Thinking: ${output.summary}`);
} else if (output.type === 'text') {
console.log(`Answer: ${output.text}`);
}
}
REST
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-flash-preview",
"input": "Solve this step by step: What is 15% of 240?",
"generation_config": {
"thinking_level": "high",
"thinking_summaries": "auto"
}
}'
Cada bloque de pensamiento contiene un campo signature (un hash criptográfico del estado de razonamiento interno) y un campo summary opcional (un resumen legible por humanos del razonamiento del modelo). El signature siempre está presente, pero un bloque de pensamiento puede contener solo una firma sin resumen en los siguientes casos:
- Solicitudes simples: El modelo no razonó lo suficiente para generar un resumen.
thinking_summaries: "none": Los resúmenes están inhabilitados de forma explícita.
Tu código siempre debe controlar los bloques de pensamiento en los que summary está vacío o no está presente. Cuando administras el historial de conversación de forma manual (modo sin estado), debes incluir bloques de pensamiento con sus firmas en las solicitudes posteriores para validar la autenticidad.
Trabaja con archivos
Cómo trabajar con archivos remotos
Accede a archivos con URLs remotas directamente en la llamada a la API.
Python
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input=[
{
"type": "image",
"uri": "https://github.com/<github-path>/cats-and-dogs.jpg",
},
{"type": "text", "text": "Describe what you see."}
],
)
for output in interaction.outputs:
if output.type == "text":
print(output.text)
JavaScript
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: [
{
type: 'image',
uri: 'https://github.com/<github-path>/cats-and-dogs.jpg',
},
{ type: 'text', text: 'Describe what you see.' }
],
});
for (const output of interaction.outputs) {
if (output.type === 'text') {
console.log(output.text);
}
}
REST
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-flash-preview",
"input": [
{
"type": "image",
"uri": "https://github.com/<github-path>/cats-and-dogs.jpg"
},
{"type": "text", "text": "Describe what you see."}
]
}'
Cómo trabajar con la API de Gemini Files
Sube archivos a la API de Files de Gemini antes de usarlos.
Python
from google import genai
import time
import requests
client = genai.Client()
# 1. Download the file
url = "https://github.com/philschmid/gemini-samples/raw/refs/heads/main/assets/cats-and-dogs.jpg"
response = requests.get(url)
with open("cats-and-dogs.jpg", "wb") as f:
f.write(response.content)
# 2. Upload to Gemini Files API
file = client.files.upload(file="cats-and-dogs.jpg")
# 3. Wait for processing
while client.files.get(name=file.name).state != "ACTIVE":
time.sleep(2)
# 4. Use in Interaction
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input=[
{
"type": "image",
"uri": file.uri,
},
{"type": "text", "text": "Describe what you see."}
],
)
for output in interaction.outputs:
if output.type == "text":
print(output.text)
JavaScript
import { GoogleGenAI } from '@google/genai';
import * as fs from 'fs';
import fetch from 'node-fetch';
const client = new GoogleGenAI({});
// 1. Download the file
const url = 'https://github.com/philschmid/gemini-samples/raw/refs/heads/main/assets/cats-and-dogs.jpg';
const filename = 'cats-and-dogs.jpg';
const response = await fetch(url);
const buffer = await response.buffer();
fs.writeFileSync(filename, buffer);
// 2. Upload to Gemini Files API
const myfile = await client.files.upload({ file: filename, config: { mimeType: 'image/jpeg' } });
// 3. Wait for processing
while ((await client.files.get({ name: myfile.name })).state !== 'ACTIVE') {
await new Promise(resolve => setTimeout(resolve, 2000));
}
// 4. Use in Interaction
const interaction = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: [
{ type: 'image', uri: myfile.uri, },
{ type: 'text', text: 'Describe what you see.' }
],
});
for (const output of interaction.outputs) {
if (output.type === 'text') {
console.log(output.text);
}
}
REST
# 1. Upload the file (Requires File API setup)
# See https://ai.google.dev/gemini-api/docs/files for details.
# Assume FILE_URI is obtained from the upload step.
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-flash-preview",
"input": [
{"type": "image", "uri": "FILE_URI"},
{"type": "text", "text": "Describe what you see."}
]
}'
Modelo de datos
Puedes obtener más información sobre el modelo de datos en la Referencia de la API. A continuación, se incluye una descripción general de alto nivel de los componentes principales.
Interacción
| Propiedad | Tipo | Descripción |
|---|---|---|
id |
string |
Es el identificador único de la interacción. |
model/agent |
string |
El modelo o agente que se usó. Solo se puede proporcionar uno. |
input |
Content[] |
Son las entradas proporcionadas. |
outputs |
Content[] |
Las respuestas del modelo. |
tools |
Tool[] |
Las herramientas que se usaron |
previous_interaction_id |
string |
Es el ID de la interacción anterior para el contexto. |
stream |
boolean |
Indica si la interacción es de transmisión. |
status |
string |
Estado: completed, in_progress, requires_action,failed, etc. |
background |
boolean |
Indica si la interacción se encuentra en modo en segundo plano. |
store |
boolean |
Indica si se debe almacenar la interacción. Valor predeterminado: true. Configúralo en false para inhabilitar la opción. |
usage |
Uso | Es el uso de tokens de la solicitud de interacción. |
Modelos y agentes compatibles
| Nombre del modelo | Tipo | ID de modelo |
|---|---|---|
| Versión preliminar de Gemini 3.1 Flash-Lite | Modelo | gemini-3.1-flash-lite-preview |
| Versión preliminar de Gemini 3.1 Pro | Modelo | gemini-3.1-pro-preview |
| Versión preliminar de Gemini 3 Flash | Modelo | gemini-3-flash-preview |
| Gemini 2.5 Pro | Modelo | gemini-2.5-pro |
| Gemini 2.5 Flash | Modelo | gemini-2.5-flash |
| Gemini 2.5 Flash-lite | Modelo | gemini-2.5-flash-lite |
| Versión preliminar de Deep Research | Agente | deep-research-pro-preview-12-2025 |
Cómo funciona la API de Interactions
La API de Interactions se diseñó en torno a un recurso central: Interaction.
Un 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, incluidas todas las entradas del usuario, las reflexiones del modelo, las llamadas a herramientas, los resultados de las herramientas y los resultados finales del modelo.
Cuando llamas a interactions.create, creas un nuevo recurso Interaction.
Administración del estado del servidor
Puedes usar el id de una interacción completada en una llamada posterior con el parámetro previous_interaction_id para continuar la conversación. El servidor usa este ID para recuperar el historial de conversación, lo que te evita tener que volver a enviar todo el historial de chat.
Solo se conserva el historial de conversaciones (entradas y salidas) con previous_interaction_id. Los demás parámetros son específicos de la interacción y se aplican solo a la interacción específica que estás generando:
toolssystem_instructiongeneration_config(incluidosthinking_level,temperature, etcétera)
Esto significa que debes volver a especificar estos parámetros en cada interacción nueva si quieres que se apliquen. Esta administración de estado del servidor es opcional. También puedes operar en modo sin estado enviando el historial de conversación completo en cada solicitud.
Almacenamiento y retención de datos
De forma predeterminada, todos los objetos Interaction se almacenan (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: Las interacciones se conservan durante 55 días.
- Nivel gratuito: Las interacciones se conservan durante 1 día.
Si no quieres esto, puedes establecer store=false en tu solicitud. Este control es independiente de la administración del estado. Puedes inhabilitar el almacenamiento para cualquier interacción. Sin embargo, ten en cuenta que store=false no es compatible con background=true y evita el uso de previous_interaction_id en turnos posteriores.
Puedes borrar las interacciones almacenadas en cualquier momento con el método de eliminación que se encuentra en la Referencia de la API. Solo puedes borrar interacciones si conoces su ID.
Una vez que venza el período de retención, tus datos se borrarán automáticamente.
Los objetos de interacciones se procesan según las condiciones.
Prácticas recomendadas
- Tasa de aciertos de caché: Usar
previous_interaction_idpara continuar las conversaciones permite que el sistema utilice con mayor facilidad 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 del agente y del modelo en 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 reformatear, y vincular estos pasos con
previous_interaction_id.
SDK
Puedes usar la versión más reciente de los SDKs de IA generativa de Google para acceder a la API de Interactions.
- En Python, este es el paquete
google-genaia partir de la versión1.55.0. - En JavaScript, este es el paquete
@google/genaia partir de la versión1.33.0.
Puedes obtener más información para instalar los SDKs en la página Libraries.
Limitaciones
- Estado beta: La API de Interactions está en versión beta o de vista previa. Las funciones y los esquemas pueden cambiar.
- MCP remoto: Gemini 3 no admite MCP remoto. Esta función estará disponible pronto.
Cambios rotundos
Actualmente, la API de Interactions se encuentra en una etapa de versión beta inicial. Estamos desarrollando y definiendo mejor de forma activa las capacidades de la API, los esquemas de recursos y las interfaces del SDK en función del uso en el mundo real y los comentarios de los desarrolladores.
Como resultado, pueden producirse cambios rotundos. Las actualizaciones pueden incluir cambios en lo siguiente:
- Esquemas de entrada y salida.
- Firmas de métodos y estructuras de objetos del SDK
- Comportamientos específicos de las funciones
Para las cargas de trabajo de producción, debes seguir usando la API de generateContent estándar. Sigue siendo la ruta recomendada para las implementaciones estables y se seguirá desarrollando y manteniendo de forma activa.
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.