Cómo integrar la API de Google Gemini en tu proyecto (tutorial completo)

La API de Google Gemini te permite integrar modelos de inteligencia artificial multimodal en cualquier proyecto con pocas líneas de código. Podés generar texto, analizar imágenes, procesar audio y video, y conectar herramientas externas usando el SDK oficial de Python, JavaScript, Go o Dart, con un tier gratuito que no requiere tarjeta de crédito.

Google es una empresa tecnológica fundada en 1998 por Larry Page y Sergey Brin, subsidiaria de Alphabet Inc., que desarrolla productos y servicios de internet como su motor de búsqueda, servicios de computación en la nube, software y hardware.

La API de Google Gemini (Gemini Developer API) es la interfaz programática que te permite usar los modelos de IA de Google — Gemini 2.5 Pro, 2.5 Flash, y anteriores — directamente desde tu código, sin depender de la interfaz web de gemini.google.com.

Qué es la API de Google Gemini y para qué sirve

Una confusión habitual: Gemini como producto (la interfaz de chat en gemini.google.com) y la API de Gemini son cosas distintas. El producto es para usuarios finales. La API es para desarrolladores que quieren meter inteligencia artificial dentro de sus aplicaciones, scripts, bots o flujos de trabajo.

La Gemini Developer API te da acceso a capacidades multimodales completas. Podés enviarle texto, imágenes, audio y video en una misma llamada, y el modelo responde combinando su comprensión de todos esos formatos. Según la documentación oficial, las capacidades principales incluyen generación de texto, análisis visual, procesamiento de audio, comprensión de video largo, function calling y ejecución de código.

Los modelos disponibles actualmente a través de la API son:

• Gemini 2.5 Pro: el modelo más capaz, con ventana de contexto de 1 millón de tokens. Pensado para razonamiento complejo, análisis de código extenso y tareas que requieren seguir instrucciones largas.
• Gemini 2.5 Flash: equilibrio entre velocidad y calidad. Ventana de 1 millón de tokens, con respuestas más rápidas y más baratas que Pro. Es el que más te conviene para la mayoría de los casos de uso en producción.
• Gemini 2.0 Flash: la generación anterior del modelo rápido, todavía disponible y funcional. Útil si ya tenés integraciones armadas con este modelo.

Lo interesante de Gemini frente a otros proveedores es la ventana de contexto de 1 millón de tokens en todos los modelos principales. Eso te permite procesar documentos completos, repositorios de código enteros o videos de varias horas en una sola llamada. OpenAI ofrece 128K tokens en GPT-4o y Anthropic llega a 200K en Claude Sonnet, así que la diferencia en contexto es significativa.

Requisitos previos y cómo obtener tu API key gratis

Lo único que necesitás es una cuenta de Google. No hace falta tarjeta de crédito, no hay proceso de aprobación y no tenés que crear una cuenta empresarial. Según la guía de inicio rápido, el proceso toma menos de un minuto.

Seguí estos pasos:

• Paso 1: Andá a aistudio.google.com y logueate con tu cuenta de Google.
• Paso 2: Hacé clic en “Get API Key” en el menú lateral. Si es la primera vez, se te pide crear o seleccionar un proyecto de Google Cloud (se crea automáticamente si no tenés uno).
• Paso 3: Copiá la API key generada. Es una cadena alfanumérica larga que empieza con AIza....
• Paso 4: Guardala como variable de entorno. Nunca la hardcodees en tu código.

Para setear la variable de entorno en Linux/macOS:

export GEMINI_API_KEY="tu-api-key-aquí"

En Windows (PowerShell):

$env:GEMINI_API_KEY="tu-api-key-aquí"

Eso sí: el tier gratuito tiene restricciones regionales. Desde Argentina y la mayoría de países de Latinoamérica funciona sin problemas, pero hay algunos territorios donde la API no está disponible. Si te da error 403 al hacer la primera llamada, puede ser un tema de región. Verificá la lista de países soportados en la documentación. Si te interesa, podes leer mas sobre nuestra guía completa sobre Google.

Instalación del SDK y primera llamada a la API de Google Gemini

Google ofrece un SDK unificado llamado google-genai que reemplazó al anterior google-generativeai. Si encontrás tutoriales que usan el SDK viejo, todavía funciona, pero el nuevo tiene una interfaz más limpia y soporte para las últimas features.

Instalá el SDK con pip:

pip install google-genai

Tu primera llamada a la API en Python se ve así:

from google import genai

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

response = client.models.generate_content(
 model="gemini-2.5-flash",
 contents="Explicame qué es una API REST en 3 oraciones"
)

print(response.text)

Son 6 líneas. Importás el módulo, creás el cliente con tu key, llamás a generate_content() con el modelo y el prompt, e imprimís la respuesta. Así de directo.

Ahora bien, en producción no querés tener la API key en el código. Usá la variable de entorno:

import os
from google import genai

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

Además de Python, hay SDKs oficiales para JavaScript/TypeScript (npm), Go, Dart/Flutter y Java/Kotlin (Android). La estructura es similar en todos: creás un cliente, elegís un modelo y llamás a generateContent(). El equipo de Google mantiene un repositorio de ejemplos (Cookbook) con notebooks para cada caso de uso.

Capacidades multimodales: texto, imágenes, audio y video

Donde Gemini se diferencia es en lo multimodal. No es solo un modelo de texto que acepta imágenes como extra — fue diseñado desde el inicio para procesar múltiples formatos de entrada de forma nativa.

Análisis de imágenes

Podés enviar una imagen junto con un prompt de texto y pedirle al modelo que la describa, extraiga datos, identifique objetos o responda preguntas sobre ella: Si te interesa, podes leer mas sobre el entorno Google Antigravity para desarrolladores.

from google import genai
from google.genai import types
import pathlib

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

image = types.Part.from_bytes(
 data=pathlib.Path("factura.jpg").read_bytes(),
 mime_type="image/jpeg"
)

response = client.models.generate_content(
 model="gemini-2.5-flash",
 contents=["Extraé el monto total, fecha y CUIT de esta factura", image]
)

print(response.text)

Ejemplo concreto: una fintech en Buenos Aires usa este enfoque para procesar facturas escaneadas. Envían la imagen de la factura, el modelo extrae los campos estructurados (monto, CUIT, fecha, número de factura) y los devuelve en JSON. Antes tardaban 2 minutos por factura con OCR tradicional + reglas. Con Gemini Flash lo resuelven en 3 segundos por factura, a un costo menor a USD 0.001 por llamada.

Procesamiento de audio y video

Para audio, podés subir archivos de hasta 9.5 horas de duración. El modelo los transcribe, resume o responde preguntas sobre el contenido. Para video, Gemini acepta archivos subidos a través de la File API y puede analizar tanto el contenido visual como el audio del video. Con la ventana de 1 millón de tokens, podés procesar videos de aproximadamente 1 hora de duración.

El conteo de tokens para contenido multimodal varía: una imagen ocupa alrededor de 258 tokens, un segundo de audio aproximadamente 32 tokens, y un segundo de video cerca de 263 tokens (incluyendo los frames visuales). Tené esto en cuenta para estimar costos.

Function calling y herramientas: conectar Gemini con tus datos

Function calling es la feature que convierte a Gemini de un modelo que genera texto a un agente que puede interactuar con sistemas externos. Le declarás funciones disponibles, el modelo decide cuándo usarlas y te devuelve los parámetros que tenés que pasar a tu función.

El flujo es: vos definís la función con su descripción y parámetros, el modelo recibe la consulta del usuario, decide que necesita llamar a tu función, te devuelve un JSON con los argumentos, vos ejecutás la función en tu backend y le pasás el resultado al modelo para que genere la respuesta final. Si te interesa, podes leer mas sobre los modelos de lenguaje y razonamiento actuales.

from google import genai
from google.genai import types

# Definir la función
get_weather = types.FunctionDeclaration(
 name="get_weather",
 description="Obtiene el clima actual de una ciudad",
 parameters={
 "type": "object",
 "properties": {
 "city": {"type": "string", "description": "Nombre de la ciudad"},
 "country": {"type": "string", "description": "Código de país ISO"}
 },
 "required": ["city"]
 }
)

tool = types.Tool(function_declarations=[get_weather])

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

response = client.models.generate_content(
 model="gemini-2.5-flash",
 contents="¿Cómo está el clima en Córdoba, Argentina?",
 config=types.GenerateContentConfig(tools=[tool])
)

# El modelo responde con function_call en vez de texto
print(response.candidates.content.parts.function_call)

El caso de uso más potente: un chatbot de atención al cliente que puede consultar tu base de datos de pedidos, verificar stock y generar tickets de soporte, todo a través de function calling. El modelo entiende la intención del usuario y orquesta las llamadas a tus APIs sin que tengas que programar la lógica de decisión.

Me parece que function calling es donde Gemini más se destaca frente a implementaciones anteriores. La precisión para elegir la función correcta y extraer los parámetros del lenguaje natural mejoró mucho con 2.5 Pro.

Cuánto cuesta: tier gratuito vs. pago y límites de uso

El tier gratuito de la API de Gemini es, por lejos, el más generoso entre los proveedores principales de modelos de IA. No requiere tarjeta de crédito y te da acceso a todos los modelos, incluyendo 2.5 Pro. Según la página de precios oficial, los límites y costos son:

Mirá los números de Flash: USD 0.15 por millón de tokens de entrada. Para ponerlo en perspectiva, procesar un libro entero de 300 páginas te cuesta menos de 2 centavos de dólar. Y en el tier gratuito tenés 500 requests por día, que para desarrollo y prototipado sobra.

El tema es que el tier gratuito tiene una limitación que pocos mencionan: Google se reserva el derecho de usar tus datos de la API gratuita para mejorar sus modelos. Si manejás datos sensibles, necesitás el tier pago donde tus datos no se usan para entrenamiento. Para un proyecto personal o un MVP, el tier gratuito está perfecto. Para producción con datos de clientes, pagá.

Google también ofrece Batch API con un descuento del 50% sobre los precios estándar. Subís un archivo con múltiples prompts, los procesás en lote y recibís los resultados en hasta 24 horas. Ideal para procesamiento masivo donde no necesitás respuesta en tiempo real. Si te interesa, podes leer mas sobre la guía sobre Claude como alternativa.

Ejemplo práctico: armar un chatbot con memoria conversacional

Vamos a armar un chatbot completo con historial de conversación usando FastAPI. Este ejemplo funciona tal cual, lo podés copiar, instalar las dependencias y correrlo.

Primero, instalá las dependencias:

pip install google-genai fastapi uvicorn

El código del chatbot:

import os
from google import genai
from google.genai import types
from fastapi import FastAPI
from pydantic import BaseModel

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

# Almacén simple de historiales por sesión
chat_histories: dict[str, list] = {}

class ChatRequest(BaseModel):
 session_id: str
 message: str

class ChatResponse(BaseModel):
 response: str

SYSTEM_INSTRUCTION = """Sos un asistente de soporte técnico para una 
empresa de hosting. Respondé en español rioplatense. Sé conciso y 
técnico pero accesible. Si no sabés algo, decilo."""

@app.post("/chat", response_model=ChatResponse)
async def chat(req: ChatRequest):
 # Obtener o crear historial
 if req.session_id not in chat_histories:
 chat_histories[req.session_id] = []
 
 history = chat_histories[req.session_id]
 
 # Agregar mensaje del usuario
 history.append(
 types.Content(
 role="user",
 parts=[types.Part.from_text(req.message)]
 )
 )
 
 # Llamar a Gemini con historial completo
 response = client.models.generate_content(
 model="gemini-2.5-flash",
 contents=history,
 config=types.GenerateContentConfig(
 system_instruction=SYSTEM_INSTRUCTION,
 temperature=0.7,
 max_output_tokens=1024
 )
 )
 
 assistant_text = response.text
 
 # Agregar respuesta al historial
 history.append(
 types.Content(
 role="model",
 parts=[types.Part.from_text(assistant_text)]
 )
 )
 
 return ChatResponse(response=assistant_text)

Correlo con: uvicorn main:app --reload

Después podés probarlo con curl:

curl -X POST http://localhost:8000/chat \
 -H "Content-Type: application/json" \
 -d '{"session_id": "user123", "message": "Mi sitio WordPress da error 500"}'

El detalle clave acá es cómo se maneja el historial. Cada vez que hacés una llamada, le mandás al modelo toda la conversación previa. Gemini no recuerda conversaciones anteriores por sí solo — vos tenés que mantener el estado. En este ejemplo usamos un diccionario en memoria, que funciona para desarrollo. En producción, reemplazalo por Redis o una base de datos.

Las system_instructions le dan personalidad y restricciones al bot. Acá le decimos que es un asistente de soporte técnico que habla en rioplatense. Podés ajustar la temperatura (0.0 para respuestas más determinísticas, 1.0 para más creativas) y limitar los tokens de salida para controlar costos.

Qué significa para empresas y equipos en Latinoamérica

El tier gratuito de Gemini baja la barrera de entrada a casi cero para startups y desarrolladores independientes en la región. No necesitás tarjeta de crédito internacional (un problema real para muchos developers argentinos) para empezar a prototipar con IA.

Dicho esto, cuando pasás a producción necesitás el tier pago, y ahí sí necesitás una forma de pago internacional. Hay un workaround: podés usar Gemini a través de Google Cloud (Vertex AI), que acepta facturación en pesos en algunos países de Latinoamérica. Los modelos son exactamente los mismos, cambia el endpoint y la autenticación. Si te interesa, podes leer mas sobre nuestra comparativa entre Gemini, ChatGPT y Claude.

Para equipos chicos, la combinación de Gemini 2.5 Flash (barato y rápido) + la ventana de contexto de 1 millón de tokens abre casos de uso que antes requerían infraestructura compleja. Podés procesar documentos legales enteros, analizar repositorios de código completos o hacer summarization de llamadas grabadas sin tener que fragmentar el contenido.

Buenas prácticas y errores frecuentes al usar la API

Después de trabajar bastante con la API de Gemini, estos son los errores que veo repetirse:

Errores comunes

1. Hardcodear la API key en el código. Es el error más básico y el más peligroso. Si subís tu código a GitHub con la key, bots automáticos la detectan y la usan en minutos. Usá siempre variables de entorno o un gestor de secretos. Si ya la expusiste, revocala inmediatamente desde AI Studio y generá una nueva.

2. Usar 2.5 Pro para todo. Es tentador usar el modelo más capaz, pero para la mayoría de las tareas (clasificación de texto, extracción de datos, respuestas simples) Flash da resultados equivalentes a una fracción del costo. Pro tiene sentido para razonamiento complejo, análisis de código largo o tareas que requieren seguir instrucciones muy específicas. Para todo lo demás, Flash. Tu factura te lo va a agradecer.

3. No manejar los rate limits. En el tier gratuito tenés 5 RPM para Pro. Si hacés un loop que manda 20 requests seguidos, te van a botar con error 429. Implementá retry con backoff exponencial: Si te interesa, podes leer mas sobre qué ofrece Claude frente a Gemini.

import time
import random

def call_with_retry(func, max_retries=5):
 for attempt in range(max_retries):
 try:
 return func()
 except Exception as e:
 if "429" in str(e):
 wait = (2 ** attempt) + random.uniform(0, 1)
 time.sleep(wait)
 else:
 raise
 raise Exception("Max retries exceeded")

4. Ignorar los safety settings. Gemini tiene filtros de seguridad que pueden bloquear respuestas legítimas si tu caso de uso toca temas sensibles (salud, legal, contenido adulto educativo). Si te llegan respuestas vacías o errores de safety, revisá y ajustá los safety settings en la configuración de la llamada. No los desactivés por completo — calibralos para tu caso de uso.

5. No cachear respuestas repetidas. Si tu aplicación hace las mismas preguntas frecuentemente (FAQs, clasificaciones sobre categorías fijas), estás quemando tokens y plata al pedo. Implementá una capa de cache. Gemini también ofrece Context Caching nativo para prompts con un prefijo largo que se repite — reduce el costo del prefijo en un 75%.

Errores HTTP más frecuentes

• 429 (Resource Exhausted): superaste el rate limit. Esperá y reintentá con backoff exponencial.
• 403 (Permission Denied): API key inválida, expirada o restricción regional. Verificá la key y tu ubicación.
• 503 (Service Unavailable): el servicio está temporalmente sobrecargado. Reintentá en unos segundos. Si persiste, revisá el dashboard de estado.
• 400 (Invalid Argument): prompt demasiado largo, formato de archivo no soportado o parámetros inválidos. Revisá los límites del modelo que estás usando.

Preguntas Frecuentes

¿Cómo consigo una API key de Google Gemini gratis?

Andá a aistudio.google.com, logueate con tu cuenta de Google y hacé clic en “Get API Key”. Se genera al instante, sin tarjeta de crédito ni proceso de aprobación. El tier gratuito te da acceso a todos los modelos, incluyendo Gemini 2.5 Pro, con límites de 5 a 15 requests por minuto según el modelo.

¿Cómo integro la API de Gemini en Python?

Instalá el SDK con pip install google-genai, creá un cliente con tu API key y llamá a client.models.generate_content() pasando el modelo y tu prompt. Con el SDK unificado google-genai tenés acceso a texto, imágenes, audio, video y function calling con la misma interfaz. Todo el setup lleva menos de 5 minutos.

¿Cuánto cuesta usar la API de Google Gemini en producción?

Gemini 2.5 Flash (el modelo recomendado para producción) cuesta USD 0.15 por millón de tokens de entrada y USD 0.60 por millón de tokens de salida (sin thinking). Gemini 2.5 Pro sale USD 1.25/2.50 por millón de entrada y USD 10 por millón de salida. La Batch API ofrece un 50% de descuento sobre estos precios para procesamiento asincrónico.

¿Qué modelo de Gemini me conviene usar para mi proyecto?

Para la mayoría de los proyectos, Gemini 2.5 Flash es la mejor opción por su relación costo-rendimiento. Usá 2.5 Pro solo para tareas de razonamiento complejo, análisis extenso de código o cuando Flash no te dé la calidad que necesitás. Si estás prototipando, arrancá con Flash en el tier gratuito (500 requests/día) y escalá desde ahí.

Conclusión

Google democratizó el acceso a modelos multimodales de primera línea con la API de Gemini. El tier gratuito sin tarjeta de crédito, la ventana de contexto de 1 millón de tokens y los precios agresivos de Flash (un orden de magnitud más barato que GPT-4o para muchas tareas) hacen que no haya excusa para no experimentar.

Lo que tenés que hacer ahora es concreto: creá tu API key en AI Studio, instalá el SDK de Python, corré el ejemplo mínimo de este artículo y después probá con tu caso de uso real. Empezá con Flash, no con Pro. Y si vas a producción, invertí tiempo en implementar retry con backoff, cachear respuestas repetidas y elegir el modelo correcto para cada tarea — esas tres cosas te van a ahorrar más plata que cualquier optimización de prompts.

El ecosistema de Gemini está evolucionando rápido. Google viene actualizando modelos y bajando precios de forma agresiva, así que lo que conviene hoy tal vez cambie en tres meses. Mantené la documentación oficial en tus bookmarks y revisala antes de arrancar un proyecto nuevo.

Fuentes

• Documentación oficial de la API de Google Gemini – Guía completa para desarrolladores
• Guía de inicio rápido de Gemini API – Primeros pasos y configuración
• Precios y límites de la API de Gemini – Tabla comparativa de modelos y tiers
• Modelos disponibles en Gemini API – Especificaciones y capacidades
• Google Gemini Cookbook – Repositorio oficial con ejemplos y notebooks