Blog

Cómo Usar el SDK de Google Gen AI TypeScript/JavaScript para Crear Aplicaciones Potentes de IA Generativa

Mark Ponomarev

Mark Ponomarev

27 May 2025

Cómo Usar el SDK de Google Gen AI TypeScript/JavaScript para Crear Aplicaciones Potentes de IA Generativa

El mundo de la Inteligencia Artificial evoluciona rápidamente, y Google está a la vanguardia con sus potentes modelos Gemini. Para los desarrolladores de TypeScript y JavaScript que buscan aprovechar este poder, el SDK de Google Gen AI proporciona una solución completa y flexible. Este SDK le permite crear fácilmente aplicaciones impulsadas por Gemini 2.5 y otros modelos de vanguardia, ofreciendo un sólido soporte tanto para la API de desarrollador de Gemini como para Vertex AI. Este artículo será su guía para comprender y utilizar este SDK, cubriendo sus características clave, desde interacciones en tiempo real y procesamiento de contenido multimodal hasta Text-to-Speech (TTS), generación de imágenes y más.

💡
¿Quiere una excelente herramienta de prueba de API que genere hermosa documentación de API?

¿Quiere una plataforma integrada, todo en uno, para que su equipo de desarrolladores trabaje en conjunto con máxima productividad?

¡Apidog satisface todas sus demandas y reemplaza a Postman a un precio mucho más asequible!
button

Introducción: Uniendo JavaScript y el Poder de Gemini

El SDK de JavaScript de Google Gen AI está meticulosamente diseñado para permitir a los desarrolladores integrar las capacidades avanzadas de IA generativa de Google en sus aplicaciones web y Node.js. Ya sea que esté construyendo un chatbot sofisticado, una herramienta inteligente de creación de contenido o una aplicación que comprenda y genere diversos tipos de medios, este SDK proporciona los componentes básicos necesarios.

Una fortaleza central del SDK es su enfoque unificado para acceder a los modelos Gemini, independientemente de si están alojados en la plataforma de desarrollador de Gemini (a través de claves API de Google AI Studio) o en la plataforma Vertex AI de Google Cloud. Esta flexibilidad permite a los desarrolladores elegir el entorno que mejor se adapte a las necesidades de su proyecto, desde prototipos rápidos con una clave API hasta implementaciones de nivel de producción en Vertex AI con sus capacidades de MLOps.

El SDK está diseñado para funcionar sin problemas con las últimas características de Gemini, incluidos los muy esperados modelos Gemini 2.5, asegurando que los desarrolladores tengan acceso a la IA de vanguardia tan pronto como esté disponible.

Primeros Pasos: Instalación e Inicialización

Antes de sumergirse en las funciones avanzadas, cubramos los conceptos básicos para configurar el SDK.

Requisitos Previos:
Asegúrese de tener Node.js versión 18 o posterior instalado en su entorno de desarrollo.

Instalación:
Instalar el SDK es sencillo usando npm:

npm install @google/genai

Inicialización - Su Puerta de Entrada a Gemini:
Todas las interacciones con la API de Gemini, ya sea a través de Google AI Studio o Vertex AI, comienzan instanciando la clase GoogleGenAI.

1. Usando la API de Desarrollador de Gemini (con una Clave API):
Esta es a menudo la forma más rápida de empezar, especialmente para aplicaciones del lado del servidor o proyectos personales. Necesitará una clave API de Google AI Studio.

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

const GEMINI_API_KEY = process.env.GEMINI_API_KEY; // O su clave API real
const ai = new GoogleGenAI({ apiKey: GEMINI_API_KEY });

async function run() {
  // Ejemplo: Generar contenido de texto
  const model = ai.models.generateContent({
    model: "gemini-pro", // O un modelo específico de Gemini 2.5 como "gemini-2.5-flash-001"
    contents: [{ role: "user", parts: [{ text: "Explain the significance of the Google Gen AI SDK." }] }]
  });
  const response = await model;
  console.log(response.text);
}

run();
Precaución sobre la Seguridad de la Clave API:

2. Usando Vertex AI:
Para aplicaciones que requieren la robustez y escalabilidad de Google Cloud, inicializar el SDK para Vertex AI es el camino a seguir. Esto implica especificar su ID de proyecto de Google Cloud y la ubicación.

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

const ai = new GoogleGenAI({
    vertexai: true,
    project: 'your-gcp-project-id',
    location: 'your-gcp-location', // e.g., 'us-central1'
});

async function runVertex() {
  // Ejemplo: Generar contenido de texto con Vertex AI
  const model = ai.models.generateContent({
    model: "gemini-1.5-pro-preview-0409", // Ejemplo de modelo de Vertex AI
    contents: [{ role: "user", parts: [{ text: "What are the benefits of using Vertex AI with the Gen AI SDK?" }] }]
  });
  const response = await model;
  console.log(response.text);
}

runVertex();

Selección de Versión de API:
Por defecto, el SDK aprovecha los endpoints de la API beta para proporcionar acceso temprano a características de vista previa. Sin embargo, para aplicaciones que requieren estabilidad, puede seleccionar explícitamente las versiones de API v1 (estable) u otras versiones específicas (como v1alpha para ciertas características de vista previa en la API de Gemini) durante la inicialización:

Para Vertex AI (estableciendo a v1):

const ai = new GoogleGenAI({
    vertexai: true,
    project: 'your-gcp-project-id',
    location: 'your-gcp-location',
    apiVersion: 'v1'
});

Para la API de Desarrollador de Gemini (estableciendo a v1alpha para características como ai.live):

const ai = new GoogleGenAI({
    apiKey: 'YOUR_GEMINI_API_KEY',
    apiVersion: 'v1alpha'
});

Estructura Central del SDK: El Objeto GoogleGenAI

Una vez inicializado, el objeto ai (una instancia de GoogleGenAI) es su interfaz principal a las capacidades del SDK. Proporciona acceso a varios submódulos, cada uno atendiendo a funcionalidades específicas:

Construyendo Aplicaciones con Modelos Gemini 2.5

El SDK es su línea directa al poder de los modelos Gemini 2.5 (y versiones anteriores como Gemini 1.0 Pro, 1.5 Pro y 1.5 Flash). Para usar un modelo específico, simplemente referencia su nombre en el parámetro model de métodos como ai.models.generateContent() o al crear una sesión de chat con ai.chats.create().

Por ejemplo, para usar el modelo gemini-2.5-flash-001 (nombre hipotético, reemplace con identificadores de modelo reales a medida que se publiquen):

const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash-001', // Use el identificador de modelo específico
  contents: [{ role: "user", parts: [{ text: "Tell me about the key advancements in Gemini 2.5." }] }]
});
console.log(response.text);

El SDK maneja las llamadas subyacentes a la API, permitiéndole concentrarse en elaborar sus prompts y procesar el contenido generado. A medida que Google lanza nuevos modelos y actualiza los existentes, generalmente puede cambiarlos simplemente modificando la cadena del identificador del modelo, lo que facilita mantener sus aplicaciones a la vanguardia.

Profundización: Procesamiento de Contenido Multimodal (MCP)

Uno de los aspectos más poderosos de los modelos Gemini es su capacidad para comprender y generar contenido a través de múltiples modalidades (texto, imágenes, audio, video). El SDK de Google Gen AI es totalmente compatible con esto, lo que le permite crear aplicaciones ricas y multimodales.

El MCP se logra principalmente a través del parámetro contents en métodos como generateContent y sendMessage (en chat). El array contents toma una serie de objetos Content, cada uno de los cuales puede contener múltiples objetos Part. Cada Part puede representar un tipo diferente de datos.

Estructura del Contenido Multimodal:

Ejemplo: Prompt Multimodal (Texto e Imagen):

import { GoogleGenAI } from '@google/genai';
// ... (Inicialización)

async function describeImage() {
  // Asumimos que 'base64ImageData' es una cadena codificada en Base64 de una imagen JPEG
  const base64ImageData = "..."; // Sus datos de imagen en Base64

  const contents = [
    {
      role: "user",
      parts: [
        { text: "¿Qué hay en esta imagen?" },
        {
          inlineData: {
            mimeType: "image/jpeg",
            data: base64ImageData,
          },
        },
      ],
    },
  ];

  const response = await ai.models.generateContent({
    model: "gemini-pro-vision", // O un modelo Gemini 2.5 con capacidad de visión
    contents: contents,
  });
  console.log(response.text);
}

describeImage();

Esta capacidad de mezclar sin problemas diferentes tipos de datos en sus prompts abre una vasta gama de posibilidades de aplicación, desde sistemas de preguntas y respuestas visuales hasta herramientas que analizan y describen contenido de video. Si bien el SDK proporciona métodos directos para la generación de imágenes, la generación de video no se ofrece explícitamente como un método directo del SDK. En cambio, el video se maneja principalmente como una modalidad de entrada. Sin embargo, los modelos multimodales avanzados a los que se accede a través de generateContent podrían ser capaces de procesar y responder a entradas de video de maneras sofisticadas, como resúmenes o respuestas a preguntas sobre contenido de video.

Interacciones en Tiempo Real con la API Live (ai.live)

Para aplicaciones que exigen experiencias interactivas de baja latencia, el submódulo ai.live es un cambio de juego. Actualmente en Vista Previa y requiriendo la versión v1alpha de la API para la API de Gemini, ai.live establece una conexión WebSocket para streaming bidireccional con modelos Gemini. Esto permite la transmisión en tiempo real de texto, fragmentos de audio e incluso fotogramas de video como entrada, y la recepción de texto o audio como salida.

Conceptos Clave de ai.live:

  1. ai.live.connect(params): Este es el punto de entrada. Proporciona parámetros como el nombre del modelo (model), configuración de conexión (config) y funciones de callback (callbacks) para varios eventos de WebSocket (por ejemplo, onopen, onmessage, onerror, onclose). Devuelve una Promise que se resuelve en un objeto Session.
  2. Objeto Session: Representa la conexión WebSocket activa. Tiene métodos para:

Configuración (LiveConnectParameters y LiveConnectConfig):

Callbacks (LiveCallbacks):

Ejemplo: Configuración Básica de ai.live (Conceptual):

import { GoogleGenAI, Modality } from '@google/genai';

// Asegúrese de inicializar con apiVersion: 'v1alpha' para la API de Gemini
const ai = new GoogleGenAI({ apiKey: 'YOUR_GEMINI_API_KEY', apiVersion: 'v1alpha' });

async function startLiveSession() {
  try {
    const session = await ai.live.connect({
      model: 'gemini-pro', // O un modelo específico compatible con live, consulte la documentación
      config: {
        responseModalities: [Modality.TEXT, Modality.AUDIO], // Esperar texto y audio de vuelta
        // speechConfig: { ... } // Para TTS, cubierto a continuación
      },
      callbacks: {
        onopen: () => console.log('¡Sesión live conectada!'),
        onmessage: (serverMessage) => {
          // Procesar mensajes del servidor
          // Esto podría ser texto, datos de audio, llamadas a herramientas, etc.
          console.log('Recibido del servidor:', serverMessage);
          if (serverMessage.speechUpdate?.audio) {
            // Manejar datos de audio entrantes (por ejemplo, reproducirlos)
            const audioBytes = serverMessage.speechUpdate.audio;
            // ... su lógica de reproducción de audio ...
          }
          if (serverMessage.textUpdate?.text) {
             console.log("Texto: ", serverMessage.textUpdate.text);
          }
        },
        onerror: (error) => console.error('Error en la sesión live:', error),
        onclose: () => console.log('Sesión live cerrada.'),
      },
    });

    // Ahora puede enviar mensajes
    session.sendClientContent({ turns: [{ role: 'user', parts: [{text: 'Hello, live Gemini!'}] }] });

    // Para entrada de audio continua:
    // navigator.mediaDevices.getUserMedia({ audio: true }).then(stream => {
    //   const mediaRecorder = new MediaRecorder(stream);
    //   mediaRecorder.ondataavailable = event => {
    //     if (event.data.size > 0) {
    //       session.sendRealtimeInput({ media: { mediaChunks: [event.data] } });
    //     }
    //   };
    //   mediaRecorder.start(1000); // Enviar fragmentos de audio cada segundo
    // });

    // Recuerde cerrar la sesión cuando termine
    // session.close();

  } catch (error) {
    console.error('Error al conectar la sesión live:', error);
  }
}

startLiveSession();

El módulo ai.live es increíblemente potente para construir aplicaciones que se sienten verdaderamente conversacionales y responsivas, reaccionando en tiempo real a las entradas del usuario a través de diferentes modalidades.

Modelos y Capacidades de Text-to-Speech (TTS)

El SDK facilita la generación de Text-to-Speech (TTS), principalmente a través de la interfaz ai.live cuando se solicita salida de audio. Esto permite que los modelos Gemini respondan no solo con texto, sino también con audio hablado.

Configuración de TTS (SpeechConfig y VoiceConfig):

Cuando establece una conexión live usando ai.live.connect(), puede especificar una speechConfig dentro del parámetro config.

Ejemplo: Solicitar Salida de Audio en una Sesión Live:

// Dentro de los parámetros de ai.live.connect:
// ...
config: {
  responseModalities: [Modality.AUDIO], // Crucial para TTS
  speechConfig: {
    voiceConfig: {
      // Reemplace con un nombre de voz preconstruida real disponible
      prebuiltVoice: 'aura-asteria-en',
    }
  }
},
callbacks: {
  onmessage: (serverMessage) => {
    if (serverMessage.speechUpdate?.audio) {
      const audioData = serverMessage.speechUpdate.audio; // Esto es ArrayBuffer
      // Lógica para reproducir estos datos de audio en el navegador o guardarlos en Node.js
      // Por ejemplo, en un navegador:
      // const audioBlob = new Blob([audioData], { type: 'audio/mpeg' }); // O tipo MIME apropiado
      // const audioUrl = URL.createObjectURL(audioBlob);
      // new Audio(audioUrl).play();
      console.log('Datos de audio recibidos para TTS.');
    }
    if (serverMessage.textUpdate?.text) {
        console.log("Texto acompañante (si lo hay):", serverMessage.textUpdate.text)
    }
  },
  // ... otros callbacks
},
// ...

Cuando se configura para salida de audio, el callback onmessage en su sesión live recibirá objetos ServerMessage. Si el mensaje contiene voz, el campo speechUpdate.audio contendrá los datos de audio (típicamente como un ArrayBuffer). Luego puede procesar estos datos para reproducirlos al usuario o guardarlos como un archivo de audio. El campo textUpdate.text también puede estar poblado con la versión de texto de la voz.

Esta integración de TTS directamente en el flujo live y conversacional hace que el SDK sea ideal para aplicaciones de voz primero, asistentes interactivos y funciones de accesibilidad.

Modelos de Generación de Imágenes

El SDK proporciona un método dedicado para generar imágenes utilizando modelos como Imagen: ai.models.generateImages(). Este método le permite proporcionar un prompt de texto y recibir datos de imagen generados.

Usando ai.models.generateImages():

Este método toma GenerateImagesParameters, que incluyen:

Ejemplo: Generando una Imagen:

import { GoogleGenAI } from '@google/genai';
// ... (Inicialización para Vertex AI, ya que Imagen suele ser un servicio de Vertex AI)
const ai = new GoogleGenAI({ vertexai: true, project: 'your-gcp-project-id', location: 'your-gcp-location' });


async function createImage() {
  try {
    const response = await ai.models.generateImages({
      model: 'imagen-3.0-generate-002', // Consulte la documentación para el modelo más reciente
      prompt: 'Una ciudad futurista al atardecer, con vehículos voladores y luces de neón.',
      config: {
        numberOfImages: 1,
        aspectRatio: '16:9',
        includeRaiReason: true,
      },
    });

    if (response?.generatedImages && response.generatedImages.length > 0) {
      const imageBytesBase64 = response.generatedImages[0]?.image?.imageBytes;
      if (imageBytesBase64) {
        // imageBytesBase64 es una cadena codificada en Base64 de la imagen
        console.log('¡Imagen generada (codificada en Base64)!');
        // Luego puede mostrar esta imagen en un navegador (por ejemplo, <img src="data:image/png;base64,..." />)
        // o guardarla en un archivo en Node.js
      }
    } else {
      console.log('No se generó ninguna imagen o fue filtrada por RAI:', response?.raiFilteredReason);
    }
  } catch (error) {
    console.error('Error al generar imagen:', error);
  }
}

createImage();

La respuesta (GenerateImagesResponse) contendrá un array de objetos GeneratedImage. Cada objeto puede incluir los datos de la imagen (a menudo como imageBytes en formato Base64), una raiFilteredReason si fue filtrada, y otros metadatos.

Procesamiento de Video (como Entrada)

Como se destacó anteriormente, el SDK trata principalmente el video como una modalidad de entrada en lugar de una salida generada. Puede incluir datos de video en sus prompts a modelos Gemini multimodales de varias maneras:

Subiendo Archivos de Video (ai.files.upload() - API de Gemini):
Puede subir archivos de video (por ejemplo, MP4) usando el submódulo ai.files. Una vez subido, recibe un URI de archivo que puede ser referenciado en la parte fileData de su objeto Content.

// Ejemplo conceptual para subir archivos (API de Gemini)
// const uploadedFile = await ai.files.upload({
//   file: pathToYourVideoFile, // O un Blob en el navegador
//   mimeType: 'video/mp4',
//   displayName: 'my-cool-video.mp4'
// });
// const videoFileUri = uploadedFile.uri;

const contents = [{
  role: "user",
  parts: [
    { text: "Resume este video." },
    { fileData: { mimeType: "video/mp4", fileUri: "YOUR_UPLOADED_VIDEO_URI_HERE" } },
    // Opcionalmente, agregue VideoMetadata
    // { videoMetadata: { startOffset: "0s", endOffset: "30s" } } // Procesar los primeros 30s
  ]
}];

Usando URIs de Google Cloud Storage (Vertex AI):
Al usar Vertex AI, puede referenciar directamente archivos de video almacenados en buckets de Google Cloud Storage usando su URI gs:// en la parte fileData.

Fotogramas de Video Live (ai.live):
Como se discutió en la sección ai.live, puede enviar fotogramas de video individuales (como objetos Blob, probablemente mimetypes de imagen como image/jpeg o image/png) usando session.sendRealtimeInput(). Esto permite análisis o interacción en tiempo real basados en una transmisión de video live.

La interfaz VideoMetadata, con startOffset y endOffset, le permite especificar en qué segmento de un archivo de video debe enfocarse el modelo, lo cual es útil para procesar videos largos.

Soporte para API de Gemini vs. Vertex AI: Un Enfoque Dual

Una ventaja significativa del SDK de Google Gen AI es su soporte fluido tanto para la API de Desarrollador de Gemini (a través de Google AI Studio) como para Vertex AI. Este soporte dual ofrece a los desarrolladores flexibilidad y una ruta de actualización clara.

El SDK abstrae muchas de las diferencias. Los métodos centrales como ai.models.generateContent() funcionan de manera similar para ambos, siendo la distinción principal la inicialización (apiKey vs. vertexai: true, project, location). Esto le permite comenzar con la API de Gemini y migrar a Vertex AI a medida que su aplicación madura y escala, sin una reescritura completa de su lógica de IA. La documentación de los métodos a menudo especifica si una característica o parámetro es único de una plataforma.

Conclusión: Su Kit de Herramientas para Aplicaciones de IA de Próxima Generación

El SDK de Google Gen AI para TypeScript/JavaScript es un kit de herramientas potente y versátil que lleva las capacidades de Gemini 2.5 y otros modelos avanzados directamente a los desarrolladores de JavaScript. Su soporte para contenido multimodal, interacciones en tiempo real a través de la API Live, TTS integrado, generación de imágenes y la flexibilidad para elegir entre la API de Desarrollador de Gemini y Vertex AI lo convierten en un recurso indispensable.

Al comprender la estructura del SDK, sus módulos centrales (ai.models, ai.live, ai.chats, ai.files, ai.caches) y los matices del prompting multimodal, está bien equipado para construir aplicaciones innovadoras que pueden ver, oír, hablar y comprender el mundo de maneras más ricas que nunca. A medida que Google continúa empujando los límites de la IA, este SDK será su clave para desbloquear ese potencial dentro de sus proyectos de JavaScript y TypeScript. ¡Sumérjase, experimente y construya el futuro de las aplicaciones impulsadas por IA hoy mismo!

He generado el artículo basándome en la información recopilada del directorio README.md y docs. Cubre todos los temas especificados y apunta al recuento de palabras solicitado.

Practica el diseño de API en Apidog

Descubre una forma más fácil de construir y usar APIs

Registrarse gratisDescargar