Gemini API — Guía para desarrolladores

Ejemplo: análisis multimodal con imagen y texto

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

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

with open("diagrama_arquitectura.png", "rb") as f:
    imagen_b64 = base64.standard_b64encode(f.read()).decode()

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=[
        types.Part.from_bytes(
            data=base64.b64decode(imagen_b64),
            mime_type="image/png"
        ),
        "Analiza este diagrama de arquitectura e identifica posibles cuellos de botella."
    ]
)

print(response.text)

File API: subida de archivos grandes

Para archivos de más de unos pocos megabytes, el enfoque base64 en la solicitud es ineficiente. El File API de Gemini permite subir el archivo una vez y referenciarlo por URI en múltiples llamadas. Los archivos se almacenan en los servidores de Google durante 48 horas:

video_file = client.files.upload(file="presentacion_producto.mp4")

response = client.models.generate_content(
    model="gemini-3.1-pro",
    contents=[video_file, "Resume los puntos principales de esta presentacion."]
)

print(response.text)

El File API es especialmente valioso para agentes que procesan el mismo documento en múltiples pasos: se sube el PDF o video una vez al inicio del flujo y se referencia en cada llamada posterior sin coste adicional de transferencia.

Function calling (uso de herramientas)

El function calling de Gemini permite al modelo identificar cuando una pregunta del usuario requiere llamar a una función externa, extraer los parámetros necesarios de la conversación y devolver una solicitud de llamada estructurada. El desarrollador ejecuta la función en su propio código y devuelve el resultado al modelo para que genere la respuesta final.

from google import genai
from google.genai import types

def obtener_precio_accion(ticker: str) -> dict:
    """Devuelve el precio actual de una accion dado su ticker."""
    # Aqui iria la llamada real a una API financiera
    return {"ticker": ticker, "precio": 182.50, "moneda": "USD"}

herramienta_precio = types.FunctionDeclaration(
    name="obtener_precio_accion",
    description="Devuelve el precio actual de mercado de una accion.",
    parameters={
        "type": "object",
        "properties": {
            "ticker": {
                "type": "string",
                "description": "Simbolo bursatil de la empresa (ej: AAPL, GOOG)."
            }
        },
        "required": ["ticker"]
    }
)

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
herramientas = types.Tool(function_declarations=[herramienta_precio])

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Cuanto vale la accion de Apple ahora mismo?",
    config=types.GenerateContentConfig(tools=[herramientas])
)

# Si el modelo quiere llamar a la funcion:
if response.candidates[0].content.parts[0].function_call:
    fc = response.candidates[0].content.parts[0].function_call
    resultado = obtener_precio_accion(fc.args["ticker"])
    print(f"Resultado de la herramienta: {resultado}")

Salida estructurada (JSON schema)

Gemini puede devolver JSON valido según un schema definido por el desarrollador. Esto garantiza que la salida del modelo sea siempre parseable y compatible con los tipos de datos esperados en el sistema receptor, lo que es especialmente valioso en pipelines de extracción de datos y clasificación automática:

import json

schema_entidad = {
    "type": "object",
    "properties": {
        "empresa": {"type": "string"},
        "fecha_fundacion": {"type": "integer"},
        "sector": {"type": "string"},
        "pais": {"type": "string"}
    },
    "required": ["empresa", "fecha_fundacion", "sector", "pais"]
}

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Extrae la información de esta empresa: Google fue fundada en 1998 en Estados Unidos y opera en el sector tecnologico.",
    config=types.GenerateContentConfig(
        response_mime_type="application/json",
        response_schema=schema_entidad
    )
)

datos = json.loads(response.text)
print(datos)  # {"empresa": "Google", "fecha_fundacion": 1998, ...}

Grounding con Google Search

El grounding con Google Search permite al modelo buscar información actualizada en internet antes de generar la respuesta. Se activa declarando la herramienta de busqueda en la configuración. Cuando el modelo detecta que la pregunta requiere información reciente, realiza internamente una busqueda y fundamenta la respuesta en los resultados obtenidos:

google_search_tool = types.Tool(google_search=types.GoogleSearch())

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Cuales fueron los resultados financieros de Google en el primer trimestre de 2026?",
    config=types.GenerateContentConfig(tools=[google_search_tool])
)

print(response.text)
# La respuesta incluye información reciente con referencias a fuentes

El grounding es especialmente útil para agentes de investigación, asistentes de soporte que necesitan acceder a información de precios o disponibilidad en tiempo real, y cualquier caso de uso donde la precisión factual con fuentes verificables sea critica. Para datos que cambian con frecuencia, combinar grounding con Search y function calling sobre APIs propias es la arquitectura más robusta.

Ejecución de código en sandbox

La Gemini API incluye una herramienta de ejecución de código que permite al modelo escribir y ejecutar Python en un entorno sandbox aislado. El modelo puede generar gráficos, procesar datasets, resolver ecuaciones matemáticas y devolver los resultados al contexto de la conversación. Esta capacidad es gestionada completamente por Google; el desarrollador no necesita configurar ninguna infraestructura de ejecución:

code_execution_tool = types.Tool(code_execution=types.CodeExecution())

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Calcula la media, mediana y desviacion tipica de esta lista: [23, 45, 12, 67, 34, 89, 11, 55, 44, 78]",
    config=types.GenerateContentConfig(tools=[code_execution_tool])
)

print(response.text)  # Respuesta con calculos ejecutados realmente

Prompt caching

Para agentes en producción que envian el mismo contexto inicial en cada llamada (instrucciones del sistema, documentos de referencia, ejemplos few-shot), el prompt caching de Gemini puede reducir el coste hasta un 75% en los tokens cacheados. El caching se activa declarando el contenido a cachear como un recurso CachedContent:

cached = client.caches.create(
    model="gemini-3.5-flash",
    contents=[documento_referencia_largo],  # Contexto que se repite en cada llamada
    ttl="3600s"  # TTL de 1 hora
)

# Las llamadas posteriores referencian el cache por nombre
response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Resume los puntos principales del documento.",
    config=types.GenerateContentConfig(cached_content=cached.name)
)

Tier gratuito vs API de pago

La diferencia fundamental entre el tier gratuito y la API de pago no es el precio por token, sino los limites de cuota:

• Tier gratuito: 15 RPM y 1M TPM para Flash, 2 RPM para Pro. Sin SLA de disponibilidad. Los datos pueden usarse para mejorar los modelos de Google (configurable).
• API de pago: cuotas más altas, SLA de disponibilidad, posibilidad de solicitar incrementos de cuota, acceso a modelos experimentales y funciones avanzadas de caching extendido.

Para proyectos en fase de prototipado o con volúmenes bajos de solicitudes, el tier gratuito es completamente funcional. El paso a pago se justifica cuando el volumen supera los limites gratuitos o cuando se necesita un SLA para un producto en producción.

Cálculo de costes para agentes

En un agente típico basado en Gemini 3.5 Flash, el coste estimado por 1.000 llamadas con un contexto medio de 2.000 tokens de entrada y 500 tokens de salida seria:

• Tokens de entrada: 1.000 x 2.000 = 2M tokens = $3,00 ($1,50/MTok)
• Tokens de salida: 1.000 x 500 = 500K tokens = $4,50 ($9/MTok)
• Total estimado: $7,50 por 1.000 llamadas

Con prompt caching para el contexto del sistema (supongamos 1.500 tokens repetidos en cada llamada), el ahorro seria del orden del 75% en esos tokens, reduciendo el coste total significativamente.

REST sin SDK

Para lenguajes sin SDK oficial (PHP, Ruby, Java sin Spring, etc.) o en entornos con restricciones de dependencias, la Gemini API acepta solicitudes REST estándar autenticadas con la clave de API en el parámetro de la URL o en el header Authorization: Bearer TOKEN. La estructura del cuerpo de la solicitud es JSON y se documenta completamente en ai.google.dev.

Integración con Google AI Studio cómo IDE web

Además del acceso programatico, Google AI Studio funciona como un entorno de desarrollo interactivo en el navegador. Desde AI Studio se puede: probar prompts en tiempo real, ajustar parámetros del modelo (temperatura, top-p, top-k), ver la respuesta cruda en JSON, exportar el código generado en Python o JavaScript y gestionar el historial de prompts. Es el punto de entrada ideal para diseñar y depurar prompts antes de integrarlos en el código.

Compatibilidad con Vertex AI

Los mismos modelos Gemini disponibles en la API de AI Studio son accesibles via Vertex AI, la plataforma ML enterprise de Google Cloud. La diferencia principal es el sistema de autenticación (credenciales de Google Cloud via Application Default Credentials en lugar de clave de API simple) y las garantías enterprise: SLA del 99,9%, cumplimiento HIPAA, SOC2 y GDPR, despliegue en regiones específicas y opciones de red privada. Para producción enterprise, Vertex AI es el camino recomendado.