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 dar vida a cualquier idea a través del dominio de flujos de trabajo basados en agentes, la programació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.

Pensamiento dinámico/alto Pensamiento bajo

De forma predeterminada, Gemini 3 Pro usa el pensamiento dinámico para razonar a partir de las instrucciones. 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.

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents="Find the race condition in this multi-threaded C++ snippet: [code here]",
)

print(response.text)

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

const ai = new GoogleGenAI({});

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents="Find the race condition in this multi-threaded C++ snippet: [code here]",
  });

  console.log(response.text);
}

run();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "Find the race condition in this multi-threaded C++ snippet: [code here]"}]
    }]
  }'

Explorar

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

Presentamos Gemini 3

Gemini 3 Pro es el primer modelo de la nueva serie. gemini-3-pro-preview es el mejor para tus tareas complejas que requieren un amplio conocimiento del mundo y un razonamiento avanzado en todas las modalidades.

* Los precios son por cada 1 millón de tokens. Los precios indicados son para texto estándar; las tarifas de entrada multimodal pueden variar.

Para obtener información detallada sobre los límites de frecuencia, los precios por lotes y más, consulta la página de modelos.

Nuevas funciones de la API en Gemini 3

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

Nivel de pensamiento

El parámetro thinking_level 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 Pro usará high de forma predeterminada.

• low: Minimiza la latencia y el costo. Ideal para seguir instrucciones sencillas, chatear o aplicaciones de alto rendimiento
• medium: (Próximamente), no se admite en el lanzamiento
• 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.

Resolución de medios

Gemini 3 introduce un control detallado sobre el procesamiento de la visión multimodal a través del parámetro media_resolution. Las resoluciones más altas mejoran la capacidad del modelo para leer texto pequeño o identificar detalles, pero aumentan el uso de tokens y la latencia. El parámetro media_resolution determina la cantidad máxima de tokens asignados por imagen de entrada o fotograma de video.

Ahora puedes establecer la resolución en media_resolution_low, media_resolution_medium o media_resolution_high para cada parte de los medios individualmente o de forma global (a través de generation_config). Si no se especifica, el modelo usa la configuración predeterminada óptima según el tipo de medio.

Configuración recomendada

from google import genai
from google.genai import types
import base64

# The media_resolution parameter is currently only available in the v1alpha API version.
client = genai.Client(http_options={'api_version': 'v1alpha'})

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents=[
        types.Content(
            parts=[
                types.Part(text="What is in this image?"),
                types.Part(
                    inline_data=types.Blob(
                        mime_type="image/jpeg",
                        data=base64.b64decode("..."),
                    ),
                    media_resolution={"level": "media_resolution_high"}
                )
            ]
        )
    ]
)

print(response.text)

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

// The media_resolution parameter is currently only available in the v1alpha API version.
const ai = new GoogleGenAI({ apiVersion: "v1alpha" });

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents: [
      {
        parts: [
          { text: "What is in this image?" },
          {
            inlineData: {
              mimeType: "image/jpeg",
              data: "...",
            },
            mediaResolution: {
              level: "media_resolution_high"
            }
          }
        ]
      }
    ]
  });

  console.log(response.text);
}

run();

curl "https://generativelanguage.googleapis.com/v1alpha/models/gemini-3-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [
        { "text": "What is in this image?" },
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "..."
          },
          "mediaResolution": {
            "level": "media_resolution_high"
          }
        }
      ]
    }]
  }'

Temperatura

En el caso 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 están optimizadas 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

Gemini 3 usa 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. Para garantizar que el modelo mantenga sus capacidades de razonamiento, debes devolver estas firmas al modelo en tu solicitud exactamente como se recibieron:

• Llamadas a funciones (estricto): La API aplica una validación estricta en el "turno actual". Si faltan firmas, se generará un error 400.
• Texto/Chat: La validación no se aplica de forma estricta, pero omitir las firmas degradará la calidad del razonamiento y las respuestas del modelo.

Llamada a función (validación estricta)

Cuando Gemini genera un functionCall, se basa en el thoughtSignature para procesar correctamente el resultado de la herramienta en el siguiente turno. El "turno actual" incluye todos los pasos del modelo (functionCall) y del usuario (functionResponse) que ocurrieron desde el último mensaje text estándar del usuario.

• Llamada a una sola función: La parte functionCall contiene una firma. Debes devolverlo.
• Llamadas a funciones paralelas: Solo la primera parte de functionCall en la lista contendrá la firma. Debes devolver las piezas en el orden exacto en que las recibiste.
• De varios pasos (secuencial): Si el modelo llama a una herramienta, recibe un resultado y llama a otra herramienta (en el mismo turno), ambas llamadas a funciones tienen firmas. Debes devolver todas las firmas acumuladas en el historial.

Texto y transmisión

En el caso de la generación de texto o chat estándar, no se garantiza la presencia de una firma.

• Non-Streaming: La parte final del contenido de la respuesta puede contener un thoughtSignature, aunque no siempre está presente. Si se devuelve uno, debes devolverlo para mantener el mejor rendimiento.
• Transmisión: Si se genera una firma, puede llegar en un fragmento final que contiene una parte de texto vacía. Asegúrate de que tu analizador de transmisiones verifique las firmas incluso si el campo de texto está vacío.

Ejemplos de código

// Model Response (Turn 1, Step 1)
  {
    "role": "model",
    "parts": [
      {
        "functionCall": { "name": "check_flight", "args": {...} },
        "thoughtSignature": "<Sig_A>" // SAVE THIS
      }
    ]
  }

// User Request (Turn 1, Step 2)
[
  { "role": "user", "parts": [{ "text": "Check flight AA100..." }] },
  { 
    "role": "model", 
    "parts": [
      { 
        "functionCall": { "name": "check_flight", "args": {...} }, 
        "thoughtSignature": "<Sig_A>" // REQUIRED
      } 
    ]
  },
  { "role": "user", "parts": [{ "functionResponse": { "name": "check_flight", "response": {...} } }] }
]

// Model Response (Turn 1, Step 3)
{
  "role": "model",
  "parts": [
    {
      "functionCall": { "name": "book_taxi", "args": {...} },
      "thoughtSignature": "<Sig_B>" // SAVE THIS
    }
  ]
}

// User Request (Turn 1, Step 4)
[
  // ... previous history ...
  { 
    "role": "model", 
    "parts": [
       { "functionCall": { "name": "check_flight", ... }, "thoughtSignature": "<Sig_A>" } 
    ]
  },
  { "role": "user", "parts": [{ "functionResponse": {...} }] },
  { 
    "role": "model", 
    "parts": [
       { "functionCall": { "name": "book_taxi", ... }, "thoughtSignature": "<Sig_B>" } 
    ]
  },
  { "role": "user", "parts": [{ "functionResponse": {...} }] }
]

// User Request (Sending Parallel Results)
[
  {
    "role": "user",
    "parts": [
      { "text": "Check the weather in Paris and London." }
    ]
  },
  {
    "role": "model",
    "parts": [
      // 1. First Function Call has the signature
      {
        "functionCall": { "name": "check_weather", "args": { "city": "Paris" } },
        "thoughtSignature": "<Signature_A>" 
      },
      // 2. Subsequent parallel calls DO NOT have signatures
      {
        "functionCall": { "name": "check_weather", "args": { "city": "London" } }
      } 
    ]
  },
  {
    "role": "user",
    "parts": [
      // 3. Function Responses are grouped together in the next block
      {
        "functionResponse": { "name": "check_weather", "response": { "temp": "15C" } }
      },
      {
        "functionResponse": { "name": "check_weather", "response": { "temp": "12C" } }
      }
    ]
  }
]

// User Request (Follow-up question)
[
  { 
    "role": "user", 
    "parts": [{ "text": "What are the risks of this investment?" }] 
  },
  { 
    "role": "model", 
    "parts": [
      {
        "text": "I need to calculate the risk step-by-step. First, I'll look at volatility...",
        "thoughtSignature": "<Signature_C>" // Recommended to include
      }
    ]
  },
  { 
    "role": "user", 
    "parts": [{ "text": "Summarize that in one sentence." }] 
  }
]

Migración desde otros modelos

Si vas a transferir 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: "thoughtSignature": "context_engineering_is_the_way_to_go"

Resultados estructurados con herramientas

Gemini 3 te permite combinar salidas estructuradas con herramientas integradas, como fundamentación con la Búsqueda de Google, contexto de URL y ejecución de código.

from google import genai
from google.genai import types
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()

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents="Search for all details for the latest Euro.",
    config={
        "tools": [
            {"google_search": {}},
            {"url_context": {}}
        ],
        "response_mime_type": "application/json",
        "response_json_schema": MatchResult.model_json_schema(),
    },  
)

result = MatchResult.model_validate_json(response.text)
print(result)

import { GoogleGenAI } from "@google/genai";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const ai = new GoogleGenAI({});

const matchSchema = z.object({
  winner: z.string().describe("The name of the winner."),
  final_match_score: z.string().describe("The final score."),
  scorers: z.array(z.string()).describe("The name of the scorer.")
});

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents: "Search for all details for the latest Euro.",
    config: {
      tools: [
        { googleSearch: {} },
        { urlContext: {} }
      ],
      responseMimeType: "application/json",
      responseJsonSchema: zodToJsonSchema(matchSchema),
    },
  });

  const match = matchSchema.parse(JSON.parse(response.text));
  console.log(match);
}

run();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "Search for all details for the latest Euro."}]
    }],
    "tools": [
      {"googleSearch": {}},
      {"urlContext": {}}
    ],
    "generationConfig": {
        "responseMimeType": "application/json",
        "responseJsonSchema": {
            "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"]
        }
    }
  }'

Migración desde Gemini 2.5

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

• Consideración: 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 mensajes simplificados.
• 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 bucle o degradación del rendimiento en tareas complejas.
• Comprensión de documentos y archivos PDF: Se cambió la resolución predeterminada del OCR para archivos PDF. Si te basaste en 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 la configuración predeterminada de Gemini 3 Pro puede aumentar el uso de tokens para los archivos PDF, 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 muestran máscaras a nivel de píxel para los objetos) no son compatibles con Gemini 3 Pro. Para las cargas de trabajo que requieren segmentación de imágenes nativa, recomendamos seguir utilizando Gemini 2.5 Flash con el pensamiento desactivado o Gemini Robotics-ER 1.5.

Compatibilidad con OpenAI

En el caso de los usuarios que utilizan la capa de compatibilidad de OpenAI, los parámetros estándar se asignan automáticamente a sus equivalentes de Gemini:

• reasoning_effort (OAI) se asigna a thinking_level (Gemini). Ten en cuenta que el medio reasoning_effort se asigna al alto thinking_level.

Sugiere prácticas recomendadas

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 usan para los modelos más antiguos.
• 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 personaje 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 conversador").
• 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 el corte de conocimiento de Gemini 3 Pro? Gemini 3 tiene un corte 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? Gemini 3 Pro admite 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 Pro? Puedes probar el modelo de forma gratuita en Google AI Studio, pero, actualmente, no hay un nivel gratuito disponible para gemini-3-pro-preview en la API de Gemini.

4. ¿Mi código thinking_budget anterior seguirá funcionando? Sí, thinking_budget aún se admite para la retrocompatibilidad, 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. La cantidad mínima de tokens requerida para iniciar el almacenamiento en caché es de 2,048 tokens.

7. ¿Qué herramientas son compatibles con Gemini 3? Gemini 3 admite la Búsqueda de Google, la Búsqueda de archivos, la Ejecución de código y el Contexto de URL. También admite la llamada a funciones estándar para tus propias herramientas personalizadas. Ten en cuenta que, por el momento, no se admiten Google Maps ni el uso de la computadora.

Próximos pasos

• Comienza a usar el Recetario de Gemini 3
• Consulta la guía específica de Cookbook sobre los niveles de pensamiento y cómo migrar del presupuesto de pensamiento a los niveles de pensamiento.