API Gemini con Node.js: guía práctica 2026

La API de Gemini en Node.js se conecta vía el paquete @google/genai o directamente por HTTP al endpoint generativelanguage.googleapis.com. Con una clave de Google AI Studio y tres líneas de setup, ya podés generar texto, analizar imágenes y armar conversaciones multiturno desde cualquier aplicación Node.js.

Qué es la API de Gemini y por qué usarla con Node.js

La API de Gemini es la interfaz programática de Google para acceder a sus modelos de lenguaje multimodal de la familia Gemini. Con ella podés procesar texto, imágenes, video, audio y documentos desde tu backend, sin levantar infraestructura propia de ML.

Ponele que tenés una app Node.js que recibe PDFs de clientes y necesita extraer información estructurada. O un chatbot de soporte que tiene que entender screenshots adjuntos. O simplemente un generador de descripciones SEO que procesa 500 productos por noche. Para todos esos casos, la API de Gemini es una opción concreta y con buena relación precio/capacidad frente a alternativas del mercado.

Lo que la diferencia de otros modelos es la multimodalidad nativa: el mismo endpoint que genera texto también acepta imágenes y audio en el body del request, sin conversiones raras ni APIs separadas. Según la documentación oficial, los modelos Gemini 2.5 soportan una ventana de contexto de hasta 1 millón de tokens, algo que abre casos de uso que con ventanas de 128k ni se podían plantear.

Requisitos previos y configuración inicial

Necesitás Node.js v18 o superior (por el soporte nativo de fetch) y npm. El resto del setup es en Google Cloud.

El flujo es este: creás un proyecto en Google Cloud Console, habilitás la “Generative Language API” (el nombre exacto importa, fijate bien en el buscador), y generás una clave API desde Google AI Studio. La clave no es del proyecto GCP directamente, sino de AI Studio, que internamente la vincula a tu cuenta. Ojo con esto: muchos errores 403 vienen de confundir ambas.

La clave va en un archivo .env y se accede como process.env.GEMINI_API_KEY. NUNCA la expongas en código cliente ni en repos públicos. Si usás un servidor Node.js con frontend, la clave solo vive en el backend.

Instalación del SDK Google Gen AI para Node.js

Un solo comando:

npm i @google/genai

Setup básico en JavaScript:

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

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);
const model = genAI.getGenerativeModel({ model: "gemini-2.5-flash" });

Si usás TypeScript, el paquete incluye los tipos. La importación es idéntica. Eso sí: el SDK usa ESM, así que si tu proyecto todavía está en CommonJS vas a tocar package.json o usar el wrapper de require. Más sobre eso en la sección de errores. Esto se conecta con lo que analizamos en cómo se compara Claude con Gemini.

Primer request: generar contenido de texto con API Gemini Node.js

Un ejemplo mínimo funcional:

const result = await model.generateContent("Explicá qué es un transformer en una oración");
console.log(result.response.text());

La respuesta es un objeto con varios campos, pero result.response.text() te da el string directamente. Si necesitás tokens usados, candidatos alternativos o el finish reason, están en result.response.

Para afinar el comportamiento del modelo podés pasar generationConfig:

const model = genAI.getGenerativeModel({
 model: "gemini-2.5-flash",
 generationConfig: {
 temperature: 0.7,
 topP: 0.9,
 maxOutputTokens: 1024,
 },
});

temperature controla la aleatoriedad (0 = determinista, 1 = creativo). maxOutputTokens limita el largo de la respuesta. topP y topK son filtros de probabilidad acumulada; en la mayoría de los casos no necesitás tocarlos.

Solicitudes HTTP directas sin SDK (REST API)

Si por alguna razón no querés depender del SDK (microservicio minimalista, restricciones de bundle size, o simplemente preferís el control), podés hacer el request directo con fetch:

const response = await fetch(
 `https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key=${process.env.GEMINI_API_KEY}`,
 {
 method: "POST",
 headers: { "Content-Type": "application/json" },
 body: JSON.stringify({
 contents: [{ parts: [{ text: "Resumí este texto en 3 puntos" }] }],
 }),
 }
);

const data = await response.json();
console.log(data.candidates.content.parts.text);

La clave va como query param ?key=, no en el header Authorization. Eso diferencia esta API de otras donde va Bearer token. Si lo confundís, recibís 401 aunque la clave sea correcta. Cubrimos ese tema en detalle en diferencias entre Gemini y GPT.

Para imágenes, el body cambia: en lugar de solo texto, agregás un part con inlineData que contiene el base64 y el mimeType. La estructura multimodal es lo más verbose del formato REST, pero el SDK te lo abstrae bastante.

Modelos disponibles y diferencias en 2026

La recomendación concreta para proyectos Node.js es arrancar con Gemini 2.5 Flash. Tiene el equilibrio correcto entre velocidad, costo y capacidad. Si te encontrás con tareas de razonamiento multi-paso (análisis legal, código complejo, resolución de problemas matemáticos), probá con 2.5 Pro antes de asumir que el modelo es el cuello de botella.

¿Alguien migró Gemini 2.0 Flash a tiempo? Los que dejaron la migración para último momento están con el agua al cuello esta semana.

Errores comunes y soluciones

403 PERMISSION_DENIED

El más frecuente. Dos causas distintas: la clave API es inválida (copiaste mal, tiene espacios, expiró), o la “Generative Language API” no está habilitada en el proyecto GCP. Verificá las dos antes de buscar otra causa. La guía de troubleshooting oficial tiene el checklist exacto.

429 RESOURCE_EXHAUSTED

Rate limiting. El tier gratuito tiene límites generosos para desarrollo (15 RPM en 2.5 Flash), pero si procesás lotes grandes los vas a tocar. La solución simple: agregá un delay entre requests con setTimeout. La solución correcta: implementá exponential backoff. Si lo que necesitás es volumen real, migrá al tier pago donde los límites son por cuota de proyecto.

ERR_REQUIRE_ESM

El SDK @google/genai es un módulo ESM puro. Si tu proyecto usa CommonJS (require()), tenés dos opciones: agregar "type": "module" en tu package.json (lo cual cambia toda la base del proyecto a ESM), o usar dynamic import: const { GoogleGenerativeAI } = await import("@google/genai"). La segunda opción es la menos invasiva si no querés tocar todo el proyecto. Más contexto en Opus 4.7 frente a Gemini 3.1.

400 INVALID_ARGUMENT

Casi siempre es la estructura del body cuando usás REST directo. El array contents tiene que tener al menos un objeto con parts. Si mandás el texto como string directo en vez de [{ parts: [{ text: "..." }] }], recibís este error. Leé el mensaje de error completo en el JSON de respuesta, no solo el status code (el mensaje describe exactamente qué campo falta o está mal formado).

Casos de uso prácticos y ejemplos reales

Chatbot con historial de conversación

El SDK tiene startChat() para manejar historial de forma nativa:

const chat = model.startChat({
 history: [
 { role: "user", parts: [{ text: "Hola, soy Martín" }] },
 { role: "model", parts: [{ text: "Hola Martín, ¿en qué te puedo ayudar?" }] },
 ],
});

const result = await chat.sendMessage("¿Cómo me llamé antes?");
console.log(result.response.text()); // "Te llamaste Martín"

El historial se mantiene en memoria durante la sesión. Para persistencia entre sesiones tenés que guardarlo en base de datos y reconstruirlo al iniciar el chat.

Análisis de imágenes

Subís la imagen como base64 junto con el prompt:

import fs from "fs";

const imageData = fs.readFileSync("producto.jpg");
const base64Image = imageData.toString("base64");

const result = await model.generateContent([
 { inlineData: { mimeType: "image/jpeg", data: base64Image } },
 { text: "Describí este producto en 2 oraciones para una tienda online" },
]);
console.log(result.response.text());

Sirve también para leer facturas, analizar capturas de pantalla de errores, o procesar gráficos. Usás la misma API, mismo modelo, mismo endpoint.

Procesamiento de PDFs y generación masiva

Para flujos de producción donde procesás muchos documentos, la clave está en el manejo de errores y el rate limiting. Un patrón que funciona: procesá en lotes de 10, con un delay de 1 segundo entre lotes, y reintentos con backoff exponencial en 429. Si alojás tu backend en un VPS, donweb.com tiene opciones con IP dedicada que ayudan cuando los rate limits son por IP de origen.

Preguntas Frecuentes

¿Cómo integro la API de Google Gemini en mi aplicación Node.js?

Instalás @google/genai con npm, generás una clave API en Google AI Studio, la guardás en .env como GEMINI_API_KEY, y creás el cliente con new GoogleGenerativeAI(process.env.GEMINI_API_KEY). Con tres líneas más ya podés llamar a model.generateContent() y recibir respuestas. El proceso completo desde zero tarda menos de 15 minutos.

¿Qué SDK uso para la API de Gemini en Node.js?

El paquete oficial es @google/genai (versión 1.x en 2026). Es ESM puro, soporta TypeScript de forma nativa, y cubre texto, imágenes, audio y conversaciones multiturno. Hay un SDK anterior llamado @google-ai/generativelanguage que está deprecado; si ves tutoriales que lo mencionan, son viejos. Complementá con modelos alternativos fuera de EE.UU..

¿Cómo hago solicitudes HTTP a Gemini API desde Node.js sin SDK?

Usás fetch() nativo de Node.js 18+ con un POST a https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key=TU_CLAVE. El body es JSON con la estructura { contents: [{ parts: [{ text: "tu prompt" }] }] }. La respuesta llega en data.candidates.content.parts.text.

¿Por qué obtengo error 429 al usar la API de Gemini con Node.js?

El 429 es rate limiting: superaste el límite de requests por minuto del tier gratuito. Gemini 2.5 Flash tiene un límite de 15 RPM en el plan free. La solución inmediata es agregar delays entre requests; la solución de producción es pasar al tier de pago donde los límites son por cuota mensual de tokens, no por RPM. También podés implementar exponential backoff para reintentar automáticamente cuando llegue el 429.

¿Cuál es la forma correcta de configurar la clave API de Gemini en Node.js?

La clave va en un archivo .env en la raíz del proyecto como GEMINI_API_KEY=tu_clave_aqui, se carga con dotenv o con las variables de entorno del sistema, y se accede como process.env.GEMINI_API_KEY. NUNCA la hardcodeés en el código ni la incluyas en el repositorio. Agregá .env al .gitignore antes de hacer el primer commit.

Conclusión

La integración de la API de Gemini con Node.js bajó bastante la barrera de entrada en 2026. El SDK @google/genai es maduro, la documentación es decente, y los modelos Gemini 2.5 tienen capacidades reales (ventana de 1M tokens, multimodalidad nativa) que justifican el cambio para muchos proyectos que hoy usan otras APIs.

Eso sí: la migración desde Gemini 2.0 Flash no es opcional, es urgente. El cierre es el 1 de junio de 2026. Si tenés código en producción con ese modelo, es lo primero que tenés que resolver antes de cualquier feature nueva.

Para proyectos nuevos, el camino es claro: @google/genai, Gemini 2.5 Flash para el caso general, 2.5 Pro si necesitás razonamiento avanzado, y REST directo solo si tenés una razón concreta para evitar el SDK. La flexibilidad de poder elegir entre ambos enfoques es uno de los puntos fuertes de esta API.

Fuentes

• Google AI for Developers — Quickstart oficial de la API de Gemini
• npm — Paquete @google/genai (SDK oficial Node.js)
• Google AI — Modelos disponibles y capacidades en 2026
• Google AI — Guía de troubleshooting y errores comunes
• Rootstrap — Cómo usar Google Gemini con Node.js y TypeScript