Gemini 3.1 Pro API: Guía para desarrolladores con ejemplos de código (2026)

Resumen

Gemini 3.1 Pro es el último modelo frontier de Google, lanzado en marzo 2026. Es la API frontier más barata por token, tiene contexto nativo de 1M, e introduce herramientas personalizadas — una nueva forma de dar al modelo acceso a funciones externas con esquemas estructurados.

IDs de modelo

Google ofrece dos variantes de Gemini 3.1 Pro:

La variante preview customtools tiene mejor confiabilidad para cadenas complejas de llamadas a funciones — úsala si tu app hace uso intensivo de llamadas a herramientas. Para uso general, se recomienda el estable gemini-3.1-pro.

# Google AI Studio
model = "gemini-3.1-pro"

# Vertex AI
model = "gemini-3.1-pro@001"

Inicio rápido: Python

Instalación

pip install google-genai

Generación básica de texto

from google import genai

client = genai.Client(api_key="YOUR_API_KEY")

response = client.models.generate_content(
    model="gemini-3.1-pro",
    contents="Explain quantum computing in 3 sentences."
)

print(response.text)

Streaming

for chunk in client.models.generate_content_stream(
    model="gemini-3.1-pro",
    contents="Write a Python function to merge two sorted arrays."
):
    print(chunk.text, end="")

Inicio rápido: JavaScript

Instalación

npm install @google/genai

Generación básica de texto

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

const ai = new GoogleGenAI({ apiKey: "YOUR_API_KEY" });

const response = await ai.models.generateContent({
  model: "gemini-3.1-pro",
  contents: "Explain quantum computing in 3 sentences.",
});

console.log(response.text);

Precios

Gemini 3.1 Pro es la API de modelo frontier más barata a marzo 2026.

A escala, Gemini 3.1 Pro cuesta aproximadamente 45% menos que GPT-5.2 y 27% menos que Sonnet 4.6 por sesión.

Nivel gratuito

Google AI Studio ofrece un nivel gratuito:

• 60 solicitudes por minuto


• 1M tokens por minuto


• Sin tarjeta de crédito requerida

Características clave

Ventana de contexto de 1M tokens

Gemini 3.1 Pro soporta nativamente 1 millón de tokens de contexto — suficiente para ~700,000 palabras de texto, ~30,000 líneas de código, ~1 hora de video, ~11 horas de audio.

Herramientas personalizadas (llamadas a funciones)

Las herramientas personalizadas te permiten definir funciones externas que Gemini puede llamar durante la generación. El modelo decide cuándo llamar una herramienta, estructura los argumentos e incorpora el resultado en su respuesta.

Grounding con Google Search

Gemini puede anclar sus respuestas en resultados de Google Search en tiempo real. Activa grounding para reducir alucinaciones y asegurar que el modelo use información actual.

Multimodal nativo

Procesa texto, imágenes, audio y video en una sola solicitud. Sin modelos separados de visión o audio — Gemini maneja todas las modalidades nativamente.

Ejemplo de código: Herramientas personalizadas / Llamadas a funciones

Python

from google import genai
from google.genai import types

client = genai.Client(api_key="YOUR_API_KEY")

weather_tool = types.Tool(
    function_declarations=[
        types.FunctionDeclaration(
            name="get_weather",
            description="Get the current weather for a city",
            parameters=types.Schema(
                type=types.Type.OBJECT,
                properties={
                    "city": types.Schema(type=types.Type.STRING, description="City name, e.g. 'San Francisco'"),
                    "unit": types.Schema(type=types.Type.STRING, enum=["celsius", "fahrenheit"], description="Temperature unit"),
                },
                required=["city"],
            ),
        )
    ]
)

response = client.models.generate_content(
    model="gemini-3.1-pro-preview-customtools",
    contents="What's the weather like in Tokyo?",
    config=types.GenerateContentConfig(tools=[weather_tool]),
)

for part in response.candidates[0].content.parts:
    if part.function_call:
        print(f"Function: {part.function_call.name}")
        print(f"Arguments: {part.function_call.args}")

JavaScript

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

const ai = new GoogleGenAI({ apiKey: "YOUR_API_KEY" });

const weatherTool = {
  functionDeclarations: [{
    name: "get_weather",
    description: "Get the current weather for a city",
    parameters: {
      type: "OBJECT",
      properties: {
        city: { type: "STRING", description: "City name, e.g. 'San Francisco'" },
        unit: { type: "STRING", enum: ["celsius", "fahrenheit"], description: "Temperature unit" },
      },
      required: ["city"],
    },
  }],
};

const response = await ai.models.generateContent({
  model: "gemini-3.1-pro-preview-customtools",
  contents: "What's the weather like in Tokyo?",
  config: { tools: [weatherTool] },
});

for (const part of response.candidates[0].content.parts) {
  if (part.functionCall) {
    console.log(`Function: ${part.functionCall.name}`);
    console.log(`Arguments:`, part.functionCall.args);
  }
}

Comparación de APIs: Gemini 3.1 Pro vs GPT-5.2 vs Claude Sonnet 4.6

Cuándo elegir cada API

Integración con tu app

Uso con Y Build

Si construyes un producto con Y Build, puedes integrar la Gemini API directamente en tu backend. Los proyectos Y Build se deployan en Cloudflare Workers, que pueden llamar la Gemini API con baja latencia.

// In a Y Build project (Cloudflare Worker)
export async function onRequest(context) {
  const response = await fetch(
    "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-pro:generateContent",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-goog-api-key": context.env.GEMINI_API_KEY,
      },
      body: JSON.stringify({
        contents: [{ parts: [{ text: "Your prompt here" }] }],
      }),
    }
  );
  const data = await response.json();
  return new Response(JSON.stringify(data));
}

Preguntas frecuentes

¿Qué es gemini-3.1-pro-preview-customtools?

Es una variante preview de Gemini 3.1 Pro optimizada para herramientas personalizadas y llamadas a funciones. Tiene mejor confiabilidad cuando el modelo necesita encadenar múltiples llamadas a herramientas. Úsala si tu app depende fuertemente de llamadas a funciones. Para generación de texto general, usa el ID de modelo estable gemini-3.1-pro.

¿Es Gemini 3.1 Pro mejor que GPT-5.2?

Depende de la tarea. Gemini 3.1 Pro es más barato, tiene mayor ventana de contexto y soporta más modalidades (video, audio). GPT-5.2 puntúa más alto en benchmarks de coding y razonamiento matemático. Para apps multimodales con presupuesto, Gemini gana. Para tareas de razonamiento puro, GPT-5.2 lidera.

¿Puedo usar Gemini 3.1 Pro gratis?

Sí. Google AI Studio proporciona un nivel gratuito con 60 solicitudes por minuto y 1 millón de tokens por minuto. Sin tarjeta de crédito requerida.

Conclusión

Gemini 3.1 Pro es la mejor API frontier por su precio en marzo 2026. A $2/$12 por millón de tokens, cuesta aproximadamente la mitad que GPT-5.2 y un tercio menos que Claude Sonnet 4.6 — con contexto nativo de 1M y el soporte multimodal más amplio.

Para desarrolladores construyendo productos con IA, el consejo práctico es: usa Gemini para tareas multimodales y sensibles al costo, Claude para coding y agentes, y GPT-5.2 para razonamiento matemático pesado. Enrutamiento de modelos entre los tres te da lo mejor de cada uno.

• Google: Gemini 3.1 Pro Announcement
• Google AI Studio: Model Documentation
• Google: Gemini API Pricing
• Vertex AI: Gemini Models
• Anthropic: Claude Sonnet 4.6 Benchmarks
• OpenAI: GPT-5.2 Model Card