Guía para desarrolladores de Gemini 3

Gemini 3 es nuestra familia de modelos más inteligente hasta la fecha, creada sobre una base de razonamiento de vanguardia. Está diseñado para hacer realidad cualquier idea, ya que domina los flujos de trabajo basados en agentes, la codificación autónoma y las tareas multimodales complejas. En esta guía, se describen las funciones clave de la familia de modelos Gemini 3 y cómo aprovecharlas al máximo.

Explora nuestra colección de apps de Gemini 3 para ver cómo el modelo maneja el razonamiento avanzado, la programación autónoma y las tareas multimodales complejas.

Comienza con algunas líneas de código:

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.1-pro-preview",
    input="Find the race condition in this multi-threaded C++ snippet: [code here]",
)

print(interaction.steps[-1].content[0].text)

JavaScript

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

const client = new GoogleGenAI({});

async function run() {
  const interaction = await client.interactions.create({
    model: "gemini-3.1-pro-preview",
    input: "Find the race condition in this multi-threaded C++ snippet: [code here]",
  });

  console.log(interaction.steps.at(-1).content[0].text);
}

run();

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.1-pro-preview",
    "input": "Find the race condition in this multi-threaded C++ snippet: [code here]"
  }'

Conoce la serie Gemini 3

Gemini 3.1 Pro es el mejor modelo para tareas complejas que requieren un amplio conocimiento del mundo y un razonamiento avanzado en todas las modalidades.

Gemini 3 Flash es nuestro modelo más reciente de la serie 3, con inteligencia de nivel Pro a la velocidad y el precio de Flash.

Nano Banana Pro (también conocido como Gemini 3 Pro Image) es nuestro modelo de generación de imágenes de mayor calidad, y Nano Banana 2 (también conocido como Gemini 3.1 Flash Image) es el equivalente de alto volumen, alta eficiencia y menor precio.

Gemini 3.1 Flash-Lite es nuestro modelo de trabajo diseñado para ser rentable y realizar tareas de gran volumen.

Actualmente, todos los modelos de Gemini 3 están en versión preliminar.

ID de modelo Ventana de contexto (entrada / salida) Fecha límite de conocimiento Precios (entrada y salida)*
gemini-3.1-flash-lite-preview 1 millón / 64,000 Enero de 2025 USD 0.25 (texto, imagen, video), USD 0.50 (audio) / USD 1.50
gemini-3.1-flash-image-preview 128 k / 32 k Enero de 2025 USD 0.25 (entrada de texto) / USD 0.067 (salida de imagen)**
gemini-3.1-pro-preview 1 millón / 64,000 Enero de 2025 USD 2 / USD 12 (menos de 200,000 tokens)
USD 4 / USD 18 (más de 200,000 tokens)
gemini-3-flash-preview 1 millón / 64,000 Enero de 2025 USD 0.50 / USD 3
gemini-3-pro-image-preview 65,000 / 32,000 Enero de 2025 USD 2 (entrada de texto) / USD 0.134 (salida de imagen)**

* Los precios son por 1 millón de tokens, a menos que se indique lo contrario. ** El precio de las imágenes varía según la resolución. Consulta la página de precios para obtener más detalles.

Para obtener información detallada sobre los límites, los precios y otros datos, consulta la página de modelos.

Nuevas funciones de la API en Gemini 3

Gemini 3 introduce nuevos parámetros diseñados para brindar a los desarrolladores más control sobre la latencia, el costo y la fidelidad multimodal.

Nivel de pensamiento

De forma predeterminada, los modelos de la serie Gemini 3 usan el pensamiento dinámico para razonar las instrucciones. Puedes usar el parámetro thinking_level, que controla la profundidad máxima del proceso de razonamiento interno del modelo antes de que produzca una respuesta. Gemini 3 trata estos niveles como asignaciones relativas para el pensamiento en lugar de garantías estrictas de tokens.

Si no se especifica thinking_level, Gemini 3 usará high de forma predeterminada. Para obtener respuestas más rápidas y con menor latencia cuando no se requiere un razonamiento complejo, puedes restringir el nivel de pensamiento del modelo a low.

Nivel de pensamiento Gemini 3.1 Pro Gemini 3.1 Flash-Lite Gemini 3 Flash Descripción
minimal No compatible Supported (predeterminado) Admitido Coincide con el parámetro de configuración "sin pensar" para la mayoría de las búsquedas. El modelo puede pensar de forma muy mínima para tareas de programación complejas. Minimiza la latencia para aplicaciones de chat o de alta capacidad de procesamiento. Ten en cuenta que minimal no garantiza que el pensamiento esté desactivado.
low Admitido Admitido Admitido Minimiza la latencia y el costo. Es ideal para seguir instrucciones simples, chatear o usar aplicaciones de alta capacidad de procesamiento.
medium Admitido Admitido Admitido Pensamiento equilibrado para la mayoría de las tareas.
high Admitida (predeterminada, dinámica) Compatible (dinámico) Admitida (predeterminada, dinámica) Maximiza la profundidad del razonamiento. El modelo puede tardar mucho más en generar el primer token de salida (sin pensar), pero la salida se razonará con más cuidado.

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.1-pro-preview",
    input="How does AI work?",
    generation_config={"thinking_level": "low"},
)

print(interaction.steps[-1].content[0].text)

JavaScript

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3.1-pro-preview",
    input: "How does AI work?",
    generationConfig: {
      thinking_level: "low",
    },
  });

console.log(interaction.steps.at(-1).content[0].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.1-pro-preview",
    "input": "How does AI work?",
    "config": {
      "thinking_level": "low"
    }
  }'

Temperatura

Para todos los modelos de Gemini 3, te recomendamos que mantengas el parámetro de temperatura en su valor predeterminado de 1.0.

Si bien los modelos anteriores a menudo se beneficiaban de ajustar la temperatura para controlar la creatividad en comparación con el determinismo, las capacidades de razonamiento de Gemini 3 se optimizaron para el parámetro de configuración predeterminado. Cambiar la temperatura (establecerla por debajo de 1.0) puede generar un comportamiento inesperado, como bucles o un rendimiento degradado, en especial en tareas complejas de razonamiento o matemáticas.

Firmas de pensamiento

Los modelos de Gemini 3 usan firmas de pensamiento para mantener el contexto de razonamiento en las llamadas a la API. Estas firmas son representaciones encriptadas del proceso de pensamiento interno del modelo.

  • Modo con estado (recomendado): Cuando se usa la API de Interactions en modo con estado (proporcionando previous_interaction_id), el servidor administra automáticamente el historial de conversaciones y las firmas de pensamiento.
  • Modo sin estado: Si administras el historial de conversación de forma manual, debes incluir bloques de pensamiento con sus firmas en las solicitudes posteriores para validar la autenticidad.

Para obtener información detallada, consulta la página Firmas de pensamiento.

Generación y edición de imágenes

En el caso de gemini-3-pro-image-preview y gemini-3.1-flash-image-preview, las firmas de pensamiento son fundamentales para la edición conversacional. Cuando le pides al modelo que modifique una imagen, se basa en el signature del turno anterior para comprender la composición y la lógica de la imagen original.

  • Edición: Las firmas se garantizan en la primera parte después de las reflexiones de la respuesta (text o inlineData) y en cada parte inlineData posterior. Debes devolver todas estas firmas para evitar errores.

Ejemplos de código

Llamada a funciones de varios pasos (secuencial)

El usuario hace una pregunta que requiere dos pasos separados (verificar el vuelo -> reservar un taxi) en un solo turno.

Paso 1: El modelo llama a la herramienta de vuelos.
El modelo devuelve una firma <Sig_A>.

// Model Response (Turn 1, Step 1)
  {
    "id": "interaction-123",
    "steps": [
      {
        "type": "function_call",
        "name": "check_flight",
        "arguments": {"flight": "AA100"},
        "signature": "<Sig_A>" // SAVE THIS
      }
    ]
  }

Paso 2: El usuario envía el resultado de vuelo
Debemos enviar <Sig_A> para mantener el hilo de pensamiento del modelo.

// User Request (Turn 1, Step 2)
  {
    "model": "gemini-3-flash-preview",
    "previous_interaction_id": "interaction-123",
    "input": [
      {
        "type": "function_result",
        "call_id": "fc_check_flight",
        "name": "check_flight",
        "result": [{ "type": "text", "text": "{\"status\": \"delayed\", \"departure_time\": \"12 PM\"}" }]
      }
    ]
  }

Paso 3: El modelo llama a la herramienta Taxi
El modelo recuerda la demora del vuelo con <Sig_A> y ahora decide reservar un taxi. Genera una nueva firma <Sig_B>.

// Model Response (Turn 1, Step 3)
  {
    "id": "interaction-123",
    "steps": [
      {
        "type": "function_call",
        "name": "book_taxi",
        "arguments": {"time": "10 AM"},
        "signature": "<Sig_B>" // SAVE THIS
      }
    ]
  }

Paso 4: El usuario envía el resultado de Taxi
Para completar el turno, debes enviar toda la cadena: <Sig_A> Y <Sig_B>.

// User Request (Turn 1, Step 4)
  {
    "model": "gemini-3-flash-preview",
    "previous_interaction_id": "interaction-123",
    "input": [
      {
        "type": "function_result",
        "call_id": "fc_book_taxi",
        "name": "book_taxi",
        "result": [{ "type": "text", "text": "{\"booking_status\": \"success\"}" }]
      }
    ]
  }

Llamada a función paralela

El usuario pregunta: "Consulta el clima en París y Londres". El modelo devuelve dos llamadas a funciones en una respuesta.

// Model Response
  {
    "id": "interaction-456",
    "steps": [
      {
        "type": "function_call",
        "name": "check_weather",
        "arguments": { "city": "Paris" },
        "signature": "<Signature_A>" // INCLUDED on First FC
      },
      {
        "type": "function_call",
        "name": "check_weather",
        "arguments": { "city": "London" }
      }
    ]
  }

// User Request (Sending Parallel Results)
  {
    "model": "gemini-3-flash-preview",
    "previous_interaction_id": "interaction-456",
    "input": [
      {
        "type": "function_result",
        "call_id": "fc_paris",
        "name": "check_weather",
        "result": [{ "type": "text", "text": "15C" }]
      },
      {
        "type": "function_result",
        "call_id": "fc_london",
        "name": "check_weather",
        "result": [{ "type": "text", "text": "12C" }]
      }
    ]
  }

Migración desde otros modelos

Si transfieres un registro de conversación de otro modelo (p.ej., Gemini 2.5) o insertas una llamada a función personalizada que no generó Gemini 3, no tendrás una firma válida.

Para omitir la validación estricta en estas situaciones específicas, completa el campo con esta cadena de texto ficticia específica: "signature": "context_engineering_is_the_way to_go"

Resultados estructurados con herramientas

Los modelos de Gemini 3 te permiten combinar salidas estructuradas con herramientas integradas, como la fundamentación con la Búsqueda de Google, el contexto de URL, la ejecución de código y las llamadas a funciones.

Python

from google import genai
from pydantic import BaseModel, Field
from typing import List

class MatchResult(BaseModel):
    winner: str = Field(description="The name of the winner.")
    final_match_score: str = Field(description="The final match score.")
    scorers: List[str] = Field(description="The name of the scorer.")

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.1-pro-preview",
    input="Search for all details for the latest Euro.",
    tools=[
        {"type": "google_search"},
        {"type": "url_context"}
    ],
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": MatchResult.model_json_schema()
    },
)

result = MatchResult.model_validate_json(interaction.steps[-1].content[0].text)
print(result)

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as z from "zod";

const matchJsonSchema = {
  type: "object",
  properties: {
    winner: { type: "string", description: "The name of the winner." },
    final_match_score: { type: "string", description: "The final score." },
    scorers: {
      type: "array",
      items: { type: "string" },
      description: "The name of the scorer."
    }
  },
  required: ["winner", "final_match_score", "scorers"]
};

const matchSchema = z.fromJSONSchema(matchJsonSchema);

const client = new GoogleGenAI({});

async function run() {
  const interaction = await client.interactions.create({
    model: "gemini-3.1-pro-preview",
    input: "Search for all details for the latest Euro.",
    tools: [
      { type: "google_search" },
      { type: "url_context" }
    ],
    response_format: {
        type: "text",
        mime_type: "application/json",
        schema: matchJsonSchema
    },
  });

  const match = matchSchema.parse(JSON.parse(interaction.steps.at(-1).content[0].text));
  console.log(match);
}

run();

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.1-pro-preview",
    "input": "Search for all details for the latest Euro.",
    "tools": [
      {"type": "google_search"},
      {"type": "url_context"}
    ],
    "response_format": {
        "type": "text",
        "mime_type": "application/json",
        "schema": {
            "type": "object",
            "properties": {
                "winner": {"type": "string", "description": "The name of the winner."},
                "final_match_score": {"type": "string", "description": "The final score."},
                "scorers": {
                    "type": "array",
                    "items": {"type": "string"},
                    "description": "The name of the scorer."
                }
            },
            "required": ["winner", "final_match_score", "scorers"]
        }
    }
  }'

Generación de imágenes

Gemini 3.1 Flash Image y Gemini 3 Pro Image te permiten generar y editar imágenes a partir de instrucciones de texto. Utiliza el razonamiento para "pensar" en una instrucción y puede recuperar datos en tiempo real, como pronósticos del clima o gráficos de acciones, antes de usar la fundamentación de la Búsqueda de Google para generar imágenes de alta fidelidad.

Capacidades nuevas y mejoradas:

  • Renderización de texto y 4K: Genera texto y diagramas nítidos y legibles con resoluciones de hasta 2K y 4K.
  • Generación fundamentada: Usa la herramienta google_search para verificar hechos y generar imágenes basadas en información del mundo real. La fundamentación con la Búsqueda de Imágenes de Google está disponible para Gemini 3.1 Flash Image.
  • Edición conversacional: Edición de imágenes de varios turnos con solo pedir cambios (p.ej., "Haz que el fondo sea un atardecer"). Este flujo de trabajo se basa en las firmas de pensamiento para conservar el contexto visual entre turnos.

Para obtener detalles completos sobre las relaciones de aspecto, los flujos de trabajo de edición y las opciones de configuración, consulta la guía de generación de imágenes.

Python

from google import genai
import base64

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-pro-image-preview",
    input="Generate an infographic of the current weather in Tokyo.",
    tools=[{"type": "google_search"}],
    response_format={
        "type": "image",
        "aspect_ratio": "16:9",
        "image_size": "4K"
    }
)

from PIL import Image
import io

image_blocks = [content_block for content_block in interaction.steps[-1].content if content_block.type == "image"]
if image_blocks:
    image_data = base64.b64decode(image_blocks[0].data)
    image = Image.open(io.BytesIO(image_data))
    image.save('weather_tokyo.png')
    image.show()

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

const client = new GoogleGenAI({});

async function run() {
  const interaction = await client.interactions.create({
    model: "gemini-3-pro-image-preview",
    input: "Generate a visualization of the current weather in Tokyo.",
    tools: [{ googleSearch: {} }],
    responseFormat: {
      type: "image",
      aspectRatio: "16:9",
      imageSize: "4K"
    }
  });

  for (const contentBlock of interaction.steps.at(-1).content) {
    if (contentBlock.type === "image") {
      const buffer = Buffer.from(contentBlock.data, "base64");
      fs.writeFileSync("weather_tokyo.png", buffer);
    }
  }
}

run();

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-pro-image-preview",
    "input": "Generate a visualization of the current weather in Tokyo.",
    "tools": [{"type": "google_search"}],
    "response_format": {
        "type": "image",
        "aspect_ratio": "16:9",
        "image_size": "4K"
    }
  }'

Ejemplo de respuesta

Clima en Tokio

Ejecución de código con imágenes

Gemini 3 Flash puede tratar la visión como una investigación activa, no solo como una mirada estática. Al combinar el razonamiento con la ejecución de código, el modelo formula un plan y, luego, escribe y ejecuta código de Python para acercar, recortar, anotar o manipular imágenes de otra manera paso a paso para fundamentar visualmente sus respuestas.

Casos de uso:

  • Acercar y examinar: El modelo detecta de forma implícita cuando los detalles son demasiado pequeños (p.ej., leer un medidor o un número de serie distantes) y escribe código para recortar y volver a examinar el área con una resolución más alta.
  • Cálculos y gráficos visuales: El modelo puede ejecutar cálculos de varios pasos con código (p.ej., sumar los artículos de una factura o generar un gráfico de Matplotlib a partir de los datos extraídos).
  • Anotación de imágenes: El modelo puede dibujar flechas, cuadros delimitadores o cualquier otra anotación directamente en las imágenes para responder preguntas espaciales como "¿Dónde debería ir este elemento?".

Para habilitar el pensamiento visual, configura Ejecución de código como herramienta. El modelo usará código automáticamente para manipular imágenes cuando sea necesario.

Python

from google import genai
from google.genai import types
import requests
from PIL import Image
import io
import base64

image_path = "https://goo.gle/instrument-img"
image_bytes = requests.get(image_path).content
image = types.Part.from_bytes(data=image_bytes, mime_type="image/jpeg")

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input=[
        image,
        "Zoom into the expression pedals and tell me how many pedals are there?"
    ],
    tools=[{"code_execution": {}}],
)

from IPython.display import display
from PIL import Image
import io

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
            elif content_block.type == "image":
                 display(Image.open(io.BytesIO(base64.b64decode(content_block.data))))
    elif step.type == "code_execution_call":
        print(step.code)
    elif step.type == "code_execution_result":
        print(step.output)

JavaScript

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

const client = new GoogleGenAI({});

async function main() {
  const imageUrl = "https://goo.gle/instrument-img";
  const response = await fetch(imageUrl);
  const imageArrayBuffer = await response.arrayBuffer();
  const base64ImageData = Buffer.from(imageArrayBuffer).toString("base64");

  const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: [
      {
        inlineData: {
          mime_type: "image/jpeg",
          data: base64ImageData,
        },
      },
      {
        text: "Zoom into the expression pedals and tell me how many pedals are there?",
      },
    ],
    tools: [{ codeExecution: {} }],
  });

  for (const step of interaction.steps) {
    if (step.type === "model_output") {
      for (const contentBlock of step.content) {
        if (contentBlock.type === "text") {
          console.log("Text:", contentBlock.text);
        }
      }
    } else if (step.type === "code_execution_call") {
      console.log("Code:", step.code);
    } else if (step.type === "code_execution_result") {
      console.log("Output:", step.output);
    }
  }
}

main();

REST

IMG_URL="https://goo.gle/instrument-img"
MODEL="gemini-3-flash-preview"

MIME_TYPE=$(curl -sIL "$IMG_URL" | grep -i '^content-type:' | awk -F ': ' '{print $2}' | sed 's/\r$//' | head -n 1)
if [[ -z "$MIME_TYPE" || ! "$MIME_TYPE" == image/* ]]; then
  MIME_TYPE="image/jpeg"
fi

if [[ "$(uname)" == "Darwin" ]]; then
  IMAGE_B64=$(curl -sL "$IMG_URL" | base64 -b 0)
elif [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  IMAGE_B64=$(curl -sL "$IMG_URL" | base64)
else
  IMAGE_B64=$(curl -sL "$IMG_URL" | base64 -w0)
fi

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "'$MODEL'",
      "input": [{
        "parts":[
            {
              "inline_data": {
                "mime_type":"'"$MIME_TYPE"'",
                "data": "'"$IMAGE_B64"'"
              }
            },
            {"text": "Zoom into the expression pedals and tell me how many pedals are there?"}
        ]
      }],
      "tools": [{"code_execution": {}}]
    }'

Para obtener más detalles sobre la ejecución de código con imágenes, consulta Ejecución de código.

Respuestas de funciones multimodales

La llamada a función multimodal permite que los usuarios obtengan respuestas de funciones que contienen objetos multimodales, lo que mejora el uso de las capacidades de llamada a función del modelo. Las llamadas a funciones estándar solo admiten respuestas de funciones basadas en texto:

Python 

from google import genai
import requests
import base64

client = genai.Client()

# 1. Define the tool
get_image_tool = {
    "type": "function",
    "name": "get_image",
    "description": "Retrieves the image file reference for a specific order item.",
    "parameters": {
        "type": "object",
        "properties": {
            "item_name": {
                "type": "string",
                "description": "The name or description of the item ordered (e.g., 'instrument')."
            }
        },
        "required": ["item_name"],
    },
}

# 2. Send the request with tools
interaction_1 = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Show me the instrument I ordered last month.",
    tools=[get_image_tool],
)

# 3. Find the function call step
fc_step = next(s for s in interaction_1.steps if s.type == "function_call")
print(f"Tool Call: {fc_step.name}({fc_step.arguments})")

# Execute tool (fetch image)
image_path = "https://goo.gle/instrument-img"
image_bytes = requests.get(image_path).content
image_b64 = base64.b64encode(image_bytes).decode("utf-8")

# 4. Send multimodal function result back
interaction_2 = client.interactions.create(
    model="gemini-3-flash-preview",
    previous_interaction_id=interaction_1.id,
    input=[{
        "type": "function_result",
        "name": fc_step.name,
        "call_id": fc_step.id,
        "result": [
            {"type": "text", "text": "instrument.jpg"},
            {
                "type": "image",
                "mime_type": "image/jpeg",
                "data": image_b64,
            }
        ]
    }],
    tools=[get_image_tool]
)

print(f"\nFinal model response: {interaction_2.steps[-1].content[0].text}")

JavaScript 

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

const client = new GoogleGenAI({});

// 1. Define the tool
const getImageTool = {
    type: 'function',
    name: 'get_image',
    description: 'Retrieves the image file reference for a specific order item.',
    parameters: {
        type: 'object',
        properties: {
            item_name: {
                type: 'string',
                description: "The name or description of the item ordered (e.g., 'instrument').",
            },
        },
        required: ['item_name'],
    },
};

// 2. Send the request with tools
const interaction1 = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Use the get_image tool to show me the instrument I ordered last month.',
    tools: [getImageTool],
});

// 3. Find the function call step
const fcStep = interaction1.steps.find(s => s.type === 'function_call');
console.log(`Tool Call: ${fcStep.name}(${JSON.stringify(fcStep.arguments)})`);

// Execute tool (fetch image)
const imageUrl = 'https://goo.gle/instrument-img';
const response = await fetch(imageUrl);
const imageArrayBuffer = await response.arrayBuffer();
const base64ImageData = Buffer.from(imageArrayBuffer).toString('base64');

// 4. Send multimodal function result back
const interaction2 = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    previous_interaction_id: interaction1.id,
    input: [{
        type: 'function_result',
        name: fcStep.name,
        call_id: fcStep.id,
        result: [
            { type: 'text', text: 'instrument.jpg' },
            {
                type: 'image',
                mime_type: 'image/jpeg',
                data: base64ImageData,
            }
        ]
    }],
    tools: [getImageTool]
});

console.log(`\nFinal model response: ${interaction2.steps.at(-1).content[0].text}`);

REST 

IMG_URL="https://goo.gle/instrument-img"

MIME_TYPE=$(curl -sIL "$IMG_URL" | grep -i '^content-type:' | awk -F ': ' '{print $2}' | sed 's/\r$//' | head -n 1)
if [[ -z "$MIME_TYPE" || ! "$MIME_TYPE" == image/* ]]; then
  MIME_TYPE="image/jpeg"
fi

# Check for macOS
if [[ "$(uname)" == "Darwin" ]]; then
  IMAGE_B64=$(curl -sL "$IMG_URL" | base64 -b 0)
elif [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  IMAGE_B64=$(curl -sL "$IMG_URL" | base64)
else
  IMAGE_B64=$(curl -sL "$IMG_URL" | base64 -w0)
fi

# 1. First interaction (triggers function call)
# 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": "Show me the instrument I ordered last month.", "tools": [...] }'

# 2. Send multimodal function result back (Replace INTERACTION_ID and CALL_ID)
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",
    "previous_interaction_id": "INTERACTION_ID",
    "input": [{
      "type": "function_result",
      "name": "get_image",
      "call_id": "CALL_ID",
      "result": [
        { "type": "text", "text": "instrument.jpg" },
        {
          "type": "image",
          "mime_type": "'"$MIME_TYPE"'",
          "data": "'"$IMAGE_B64"'"
        }
      ]
    }]
  }'

Combina herramientas integradas y llamadas a funciones

Gemini 3 permite el uso de herramientas integradas (como la Búsqueda de Google, el contexto de URL y más) y herramientas personalizadas de llamada a funciones en la misma llamada a la API, lo que permite flujos de trabajo más complejos.

Python

from google import genai
from google.genai import types

client = genai.Client()

getWeather = {
    "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"],
    },
}

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=[
        {"type": "google_search"},
        getWeather
    ],
)

# Find the function call step
fc_step = next((s for s in interaction.steps if s.type == "function_call"), None)

if fc_step:
    # Simulate a function result
    result = {"response": "Very cold. 22 degrees Fahrenheit."}

    final_interaction = client.interactions.create(
        model="gemini-3-flash-preview",
        input=[
            {"type": "function_result", "name": fc_step.name, "call_id": fc_step.id, "result": result}
        ],
        tools=[
            {"type": "google_search"},
            getWeather
        ],
        previous_interaction_id=interaction.id,
    )

    print(final_interaction.steps[-1].content[0].text)

JavaScript

import { GoogleGenAI, Type } from '@google/genai';

const client = new GoogleGenAI({});

const getWeatherDeclaration = {
  type: 'function',
  name: 'getWeather',
  description: 'Gets the weather for a requested city.',
  parameters: {
    type: Type.OBJECT,
    properties: {
      city: {
        type: Type.STRING,
        description: 'The city and state, e.g. Utqiaġvik, Alaska',
      },
    },
    required: ['city'],
  },
};

const 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: [
    { type: "google_search" },
    getWeatherDeclaration
  ],
});

// Find the function call step
const fcStep = interaction.steps.find(s => s.type === 'function_call');

if (fcStep) {
  const result = { response: "Very cold. 22 degrees Fahrenheit." };

  const finalInteraction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: [
      { type: 'function_result', name: fcStep.name, call_id: fcStep.id, result: result }
    ],
    tools: [
      { type: "google_search" },
      getWeatherDeclaration
    ],
    previous_interaction_id: interaction.id,
  });

  console.log(finalInteraction.steps.at(-1).content[0].text);
}

Migración desde Gemini 2.5

Gemini 3 es nuestra familia de modelos más potente hasta la fecha y ofrece una mejora gradual en comparación con Gemini 2.5. Cuando realices la migración, ten en cuenta lo siguiente:

  • Pensar: Si antes usabas ingeniería de instrucciones compleja (como la cadena de pensamiento) para obligar a Gemini 2.5 a razonar, prueba Gemini 3 con thinking_level: "high" y con instrucciones simplificadas.
  • Parámetros de configuración de temperatura: Si tu código existente establece explícitamente la temperatura (en especial, en valores bajos para obtener resultados determinísticos), te recomendamos que quites este parámetro y uses el valor predeterminado de Gemini 3, que es 1.0, para evitar posibles problemas de bucles o degradación del rendimiento en tareas complejas.
  • Comprensión de documentos y PDFs: Si dependías de un comportamiento específico para el análisis de documentos densos, prueba el nuevo parámetro de configuración media_resolution_high para garantizar la precisión continua.
  • Consumo de tokens: La migración a los valores predeterminados de Gemini 3 puede aumentar el uso de tokens para los PDFs, pero disminuir el uso de tokens para los videos. Si las solicitudes ahora superan la ventana de contexto debido a resoluciones predeterminadas más altas, te recomendamos que reduzcas explícitamente la resolución de los medios.
  • Segmentación de imágenes: Las capacidades de segmentación de imágenes (que devuelven máscaras a nivel de píxel para los objetos) no son compatibles con Gemini 3 Pro ni Gemini 3 Flash. Para las cargas de trabajo que requieren segmentación de imágenes integrada, recomendamos seguir utilizando Gemini 2.5 Flash con el pensamiento desactivado o Gemini Robotics-ER 1.6.
  • Uso de la computadora: Gemini 3 Pro y Gemini 3 Flash admiten el uso de la computadora. A diferencia de la serie 2.5, no necesitas usar un modelo independiente para acceder a la herramienta Uso del equipo.
  • Compatibilidad con herramientas: Ahora se admite la combinación de herramientas integradas con llamadas a funciones para los modelos de Gemini 3. También se admite la fundamentación en Maps para los modelos de Gemini 3.

Compatibilidad con OpenAI

Para los usuarios que utilizan la capa de compatibilidad de OpenAI, los parámetros estándar (reasoning_effort de OpenAI) se asignan automáticamente a los equivalentes de Gemini (thinking_level).

Prácticas recomendadas para escribir instrucciones

Gemini 3 es un modelo de razonamiento, lo que cambia la forma en que debes darle instrucciones.

  • Instrucciones precisas: Sé conciso en tus instrucciones. Gemini 3 responde mejor a las instrucciones directas y claras. Es posible que analice en exceso las técnicas de ingeniería de instrucciones detalladas o demasiado complejas que se usaban para modelos anteriores.
  • Nivel de detalle de la respuesta: De forma predeterminada, Gemini 3 es menos detallado y prefiere proporcionar respuestas directas y eficientes. Si tu caso de uso requiere un asistente más conversacional o "parlanchín", debes dirigir explícitamente el modelo en la instrucción (p.ej., "Explica esto como un asistente amigable y parlanchín").
  • Administración del contexto: Cuando trabajes con conjuntos de datos grandes (p.ej., libros completos, bases de código o videos largos), coloca tus instrucciones o preguntas específicas al final de la instrucción, después del contexto de los datos. Ancla el razonamiento del modelo a los datos proporcionados comenzando tu pregunta con una frase como "Según la información anterior…".

Obtén más información sobre las estrategias de diseño de instrucciones en la guía de ingeniería de instrucciones.

Preguntas frecuentes

  1. ¿Cuál es la fecha límite de conocimiento de Gemini 3? Los modelos de Gemini 3 tienen una fecha límite de conocimiento de enero de 2025. Para obtener información más reciente, usa la herramienta Search Grounding.

  2. ¿Cuáles son los límites de la ventana de contexto? Los modelos de Gemini 3 admiten una ventana de contexto de entrada de 1 millón de tokens y hasta 64,000 tokens de salida.

  3. ¿Existe un nivel gratuito para Gemini 3? Gemini 3 Flash gemini-3-flash-preview tiene un nivel gratuito en la API de Gemini. Puedes probar Gemini 3.1 Pro y 3 Flash sin costo en Google AI Studio, pero no hay un nivel gratuito disponible para gemini-3.1-pro-preview en la API de Gemini.

  4. ¿Mi código thinking_budget anterior seguirá funcionando? Sí, thinking_budget sigue siendo compatible con versiones anteriores, pero recomendamos migrar a thinking_level para obtener un rendimiento más predecible. No uses ambos en la misma solicitud.

  5. ¿Gemini 3 admite la API de Batch? Sí, Gemini 3 admite la API de Batch.

  6. ¿Se admite el almacenamiento en caché de contexto? Sí, Context Caching es compatible con Gemini 3.

  7. ¿Qué herramientas son compatibles con Gemini 3? Gemini 3 admite Búsqueda de Google, Fundamentación con Google Maps, Búsqueda de archivos, Ejecución de código y Contexto de URL. También admite la Llamada a funciones estándar para tus propias herramientas personalizadas y en combinación con herramientas integradas.

  8. ¿Qué es gemini-3.1-pro-preview-customtools? Si usas gemini-3.1-pro-preview y el modelo ignora tus herramientas personalizadas en favor de los comandos de bash, prueba el modelo gemini-3.1-pro-preview-customtools. Obtén más información aquí.

Próximos pasos