Blog

Como Usar o SDK Google Gen AI TypeScript/JavaScript para Criar Aplicações Poderosas de IA Generativa

Mark Ponomarev

Mark Ponomarev

27 maio 2025

Como Usar o SDK Google Gen AI TypeScript/JavaScript para Criar Aplicações Poderosas de IA Generativa

O mundo da Inteligência Artificial está evoluindo rapidamente, e o Google está na vanguarda com seus poderosos modelos Gemini. Para desenvolvedores TypeScript e JavaScript que buscam aproveitar esse poder, o SDK Google Gen AI oferece uma solução abrangente e flexível. Este SDK permite que você construa facilmente aplicações impulsionadas pelos modelos Gemini 2.5 e outros modelos de ponta, oferecendo suporte robusto tanto para a API Gemini para Desenvolvedores quanto para o Vertex AI. Este artigo será seu guia para entender e utilizar este SDK, cobrindo seus principais recursos, desde interações live e em tempo real e processamento de conteúdo multimodal até Texto-para-Fala (TTS), geração de imagem e muito mais.

💡
Quer uma ótima ferramenta de Teste de API que gera bela Documentação de API?

Quer uma plataforma integrada e Tudo-em-Um para sua Equipe de Desenvolvedores trabalhar em conjunto com máxima produtividade?

Apidog entrega todas as suas demandas e substitui o Postman por um preço muito mais acessível!
button

Introdução: Unindo JavaScript e o Poder do Gemini

O SDK Google Gen AI para JavaScript é meticulosamente projetado para permitir que desenvolvedores integrem as avançadas capacidades de IA generativa do Google em suas aplicações web e Node.js. Seja você construindo um chatbot sofisticado, uma ferramenta inteligente de criação de conteúdo ou uma aplicação que entende e gera diversos tipos de mídia, este SDK fornece os blocos de construção necessários.

Um ponto forte central do SDK é sua abordagem unificada para acessar modelos Gemini, independentemente de estarem hospedados na plataforma Gemini para Desenvolvedores (via chaves de API do Google AI Studio) ou na plataforma Vertex AI do Google Cloud. Essa flexibilidade permite que os desenvolvedores escolham o ambiente que melhor se adapta às necessidades de seus projetos, desde prototipagem rápida com uma chave de API até implantações de nível de produção no Vertex AI com suas capacidades de MLOps.

O SDK foi projetado para funcionar perfeitamente com os recursos mais recentes do Gemini, incluindo os altamente esperados modelos Gemini 2.5, garantindo que os desenvolvedores tenham acesso à IA de ponta assim que estiver disponível.

Primeiros Passos: Instalação e Inicialização

Antes de mergulhar nos recursos avançados, vamos cobrir o básico da configuração do SDK.

Pré-requisitos:
Certifique-se de ter o Node.js versão 18 ou superior instalado em seu ambiente de desenvolvimento.

Instalação:
Instalar o SDK é simples usando npm:

npm install @google/genai

Inicialização - Sua Porta de Entrada para o Gemini:
Todas as interações com a API Gemini, seja através do Google AI Studio ou Vertex AI, começam instanciando a classe GoogleGenAI.

1. Usando a API Gemini para Desenvolvedores (com uma Chave de API):
Esta é frequentemente a maneira mais rápida de começar, especialmente para aplicações server-side ou projetos pessoais. Você precisará de uma chave de API do Google AI Studio.

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

const GEMINI_API_KEY = process.env.GEMINI_API_KEY; // Ou sua chave de API real
const ai = new GoogleGenAI({ apiKey: GEMINI_API_KEY });

async function run() {
  // Exemplo: Gerar conteúdo de texto
  const model = ai.models.generateContent({
    model: "gemini-pro", // Ou um modelo Gemini 2.5 específico como "gemini-2.5-flash-001"
    contents: [{ role: "user", parts: [{ text: "Explique a importância do SDK Google Gen AI." }] }]
  });
  const response = await model;
  console.log(response.text);
}

run();
Cuidado com a Segurança da Chave de API:

2. Usando o Vertex AI:
Para aplicações que exigem a robustez e escalabilidade do Google Cloud, inicializar o SDK para o Vertex AI é o caminho a seguir. Isso envolve especificar o ID do seu projeto Google Cloud e a localização.

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

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

async function runVertex() {
  // Exemplo: Gerar conteúdo de texto com Vertex AI
  const model = ai.models.generateContent({
    model: "gemini-1.5-pro-preview-0409", // Exemplo de modelo Vertex AI
    contents: [{ role: "user", parts: [{ text: "Quais são os benefícios de usar o Vertex AI com o SDK Gen AI?" }] }]
  });
  const response = await model;
  console.log(response.text);
}

runVertex();

Seleção da Versão da API:
Por padrão, o SDK utiliza os endpoints da API beta para fornecer acesso antecipado a recursos de pré-visualização. No entanto, para aplicações que exigem estabilidade, você pode selecionar explicitamente as versões de API v1 (estável) ou outras versões específicas (como v1alpha para certos recursos de pré-visualização na API Gemini) durante a inicialização:

Para Vertex AI (configurando para v1):

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

Para a API Gemini para Desenvolvedores (configurando para v1alpha para recursos como ai.live):

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

Estrutura Central do SDK: O Objeto GoogleGenAI

Uma vez inicializado, o objeto ai (uma instância de GoogleGenAI) é sua interface principal para as capacidades do SDK. Ele fornece acesso a vários submódulos, cada um atendendo a funcionalidades específicas:

Construindo Aplicações com Modelos Gemini 2.5

O SDK é sua linha direta para o poder dos modelos Gemini 2.5 (e versões anteriores como Gemini 1.0 Pro, 1.5 Pro e 1.5 Flash). Para usar um modelo específico, basta referenciar seu nome no parâmetro model de métodos como ai.models.generateContent() ou ao criar uma sessão de chat com ai.chats.create().

Por exemplo, para usar o modelo gemini-2.5-flash-001 (nome hipotético, substitua por identificadores de modelo reais conforme forem lançados):

const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash-001', // Use o identificador específico do modelo
  contents: [{ role: "user", parts: [{ text: "Fale sobre os principais avanços no Gemini 2.5." }] }]
});
console.log(response.text);

O SDK lida com as chamadas de API subjacentes, permitindo que você se concentre em criar seus prompts e processar o conteúdo gerado. Conforme o Google lança novos modelos e atualiza os existentes, você pode geralmente mudar para eles simplesmente alterando a string do identificador do modelo, tornando fácil manter suas aplicações na vanguarda.

Aprofundamento: Processamento de Conteúdo Multimodal (MCP)

Um dos aspectos mais poderosos dos modelos Gemini é sua capacidade de entender e gerar conteúdo em múltiplas modalidades (texto, imagens, áudio, vídeo). O SDK Google Gen AI suporta totalmente isso, permitindo construir aplicações multimodais ricas.

O MCP é alcançado principalmente através do parâmetro contents em métodos como generateContent e sendMessage (em chat). O array contents aceita uma série de objetos Content, cada um dos quais pode conter múltiplos objetos Part. Cada Part pode representar um tipo diferente de dado.

Estrutura do Conteúdo Multimodal:

Exemplo: Prompt Multimodal (Texto e Imagem):

import { GoogleGenAI } from '@google/genai';
// ... (Inicialização)

async function describeImage() {
  // Assuma que 'base64ImageData' é uma string codificada em Base64 de uma imagem JPEG
  const base64ImageData = "..."; // Seus dados de imagem em Base64

  const contents = [
    {
      role: "user",
      parts: [
        { text: "O que há nesta imagem?" },
        {
          inlineData: {
            mimeType: "image/jpeg",
            data: base64ImageData,
          },
        },
      ],
    },
  ];

  const response = await ai.models.generateContent({
    model: "gemini-pro-vision", // Ou um modelo Gemini 2.5 com capacidade de visão
    contents: contents,
  });
  console.log(response.text);
}

describeImage();

Essa capacidade de combinar perfeitamente diferentes tipos de dados em seus prompts abre um vasto leque de possibilidades de aplicação, desde sistemas de Q&A visuais até ferramentas que analisam e descrevem conteúdo de vídeo. Embora o SDK forneça métodos diretos para geração de imagens, a geração de vídeo não é explicitamente oferecida como um método direto do SDK. Em vez disso, o vídeo é principalmente tratado como uma modalidade de entrada. No entanto, modelos multimodais avançados acessados via generateContent podem ser capazes de processar e responder a entradas de vídeo de maneiras sofisticadas, como sumarização ou resposta a perguntas sobre o conteúdo do vídeo.

Interações em Tempo Real com a API Live (ai.live)

Para aplicações que exigem experiências interativas de baixa latência, o submódulo ai.live é um divisor de águas. Atualmente em Pré-visualização e exigindo a versão de API v1alpha para a API Gemini, ai.live estabelece uma conexão WebSocket para streaming bidirecional com modelos Gemini. Isso permite a transmissão em tempo real de texto, blocos de áudio e até mesmo quadros de vídeo como entrada, e o recebimento de texto ou áudio como saída.

Conceitos Chave de ai.live:

  1. ai.live.connect(params): Este é o ponto de entrada. Você fornece parâmetros como o nome do modelo (model), configuração de conexão (config) e funções de callback (callbacks) para vários eventos WebSocket (por exemplo, onopen, onmessage, onerror, onclose). Retorna uma Promise que resolve para um objeto Session.
  2. Objeto Session: Representa a conexão WebSocket ativa. Possui métodos para:

Configuração (LiveConnectParameters e LiveConnectConfig):

Callbacks (LiveCallbacks):

Exemplo: Configuração Básica de ai.live (Conceitual):

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

// Certifique-se de inicializar com apiVersion: 'v1alpha' para a API 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', // Ou um modelo específico que suporte live, verifique a documentação
      config: {
        responseModalities: [Modality.TEXT, Modality.AUDIO], // Espera texto e áudio de volta
        // speechConfig: { ... } // Para TTS, abordado abaixo
      },
      callbacks: {
        onopen: () => console.log('Sessão live conectada!'),
        onmessage: (serverMessage) => {
          // Processar mensagens do servidor
          // Isso pode ser texto, dados de áudio, chamadas de ferramentas, etc.
          console.log('Recebido do servidor:', serverMessage);
          if (serverMessage.speechUpdate?.audio) {
            // Lidar com dados de áudio recebidos (por exemplo, reproduzi-los)
            const audioBytes = serverMessage.speechUpdate.audio; // Isso é ArrayBuffer
            // ... sua lógica de reprodução de áudio ...
          }
          if (serverMessage.textUpdate?.text) {
             console.log("Texto: ", serverMessage.textUpdate.text);
          }
        },
        onerror: (error) => console.error('Erro na sessão live:', error),
        onclose: () => console.log('Sessão live fechada.'),
      },
    });

    // Agora você pode enviar mensagens
    session.sendClientContent({ turns: [{ role: 'user', parts: [{text: 'Olá, Gemini live!'}] }] });

    // Para entrada de áudio contínua:
    // 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 blocos de áudio a cada segundo
    // });

    // Lembre-se de fechar a sessão quando terminar
    // session.close();

  } catch (error) {
    console.error('Falha ao conectar sessão live:', error);
  }
}

startLiveSession();

O módulo ai.live é incrivelmente potente para construir aplicações que parecem verdadeiramente conversacionais e responsivas, reagindo em tempo real às entradas do usuário em diferentes modalidades.

Modelos e Capacidades de Texto-para-Fala (TTS)

O SDK facilita a geração de Texto-para-Fala (TTS), principalmente através da interface ai.live quando a saída de áudio é solicitada. Isso permite que os modelos Gemini respondam não apenas com texto, mas com áudio falado.

Configuração de TTS (SpeechConfig e VoiceConfig):

Quando você estabelece uma conexão live usando ai.live.connect(), você pode especificar um speechConfig dentro do parâmetro config.

Exemplo: Solicitando Saída de Áudio em uma Sessão Live:

// Dentro dos parâmetros de ai.live.connect:
// ...
config: {
  responseModalities: [Modality.AUDIO], // Crucial para TTS
  speechConfig: {
    voiceConfig: {
      // Substitua por um nome de voz pré-construído real disponível
      prebuiltVoice: 'aura-asteria-en',
    }
  }
},
callbacks: {
  onmessage: (serverMessage) => {
    if (serverMessage.speechUpdate?.audio) {
      const audioData = serverMessage.speechUpdate.audio; // Isso é ArrayBuffer
      // Lógica para reproduzir esses dados de áudio no navegador ou salvá-los no Node.js
      // Por exemplo, em um navegador:
      // const audioBlob = new Blob([audioData], { type: 'audio/mpeg' }); // Ou tipo MIME apropriado
      // const audioUrl = URL.createObjectURL(audioBlob);
      // new Audio(audioUrl).play();
      console.log('Recebido dados de áudio para TTS.');
    }
    if (serverMessage.textUpdate?.text) {
        console.log("Texto de acompanhamento (se houver):", serverMessage.textUpdate.text)
    }
  },
  // ... outros callbacks
},
// ...

Quando configurado para saída de áudio, o callback onmessage em sua sessão live receberá objetos ServerMessage. Se a mensagem contiver fala, o campo speechUpdate.audio conterá os dados de áudio (geralmente como um ArrayBuffer). Você pode então processar esses dados para reproduzi-los para o usuário ou salvá-los como um arquivo de áudio. O campo textUpdate.text também pode ser preenchido com a versão de texto da fala.

Essa integração de TTS diretamente no fluxo live e conversacional torna o SDK ideal para aplicações focadas em voz, assistentes interativos e recursos de acessibilidade.

Modelos de Geração de Imagem

O SDK fornece um método dedicado para gerar imagens usando modelos como Imagen: ai.models.generateImages(). Este método permite fornecer um prompt de texto e receber dados de imagem gerados.

Usando ai.models.generateImages():

Este método aceita GenerateImagesParameters, que incluem:

Exemplo: Gerando uma Imagem:

import { GoogleGenAI } from '@google/genai';
// ... (Inicialização para Vertex AI, já que Imagen é frequentemente um serviço do 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', // Verifique a documentação para o modelo mais recente
      prompt: 'Uma paisagem urbana futurista ao pôr do sol, com veículos voadores e luzes de neon.',
      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 é uma string codificada em Base64 da imagem
        console.log('Imagem gerada (codificada em Base64)!');
        // Você pode então exibir esta imagem em um navegador (por exemplo, <img src="data:image/png;base64,..." />)
        // ou salvá-la em um arquivo no Node.js
      }
    } else {
      console.log('Nenhuma imagem gerada ou filtrada por RAI:', response?.raiFilteredReason);
    }
  } catch (error) {
    console.error('Erro ao gerar imagem:', error);
  }
}

createImage();

A resposta (GenerateImagesResponse) conterá um array de objetos GeneratedImage. Cada objeto pode incluir os dados da imagem (geralmente como imageBytes em formato Base64), um raiFilteredReason se foi filtrada e outros metadados.

Processamento de Vídeo (como Entrada)

Conforme destacado anteriormente, o SDK trata o vídeo principalmente como uma modalidade de entrada, em vez de uma saída gerada. Você pode incluir dados de vídeo em seus prompts para modelos Gemini multimodais de algumas maneiras:

Upload de Arquivos de Vídeo (ai.files.upload() - API Gemini):
Você pode fazer upload de arquivos de vídeo (por exemplo, MP4) usando o submódulo ai.files. Uma vez carregado, você recebe um URI de arquivo que pode ser referenciado na parte fileData do seu objeto Content.

// Exemplo conceitual para upload de arquivo (API Gemini)
// const uploadedFile = await ai.files.upload({
//   file: pathToYourVideoFile, // Ou um Blob no navegador
//   mimeType: 'video/mp4',
//   displayName: 'my-cool-video.mp4'
// });
// const videoFileUri = uploadedFile.uri;

const contents = [{
  role: "user",
  parts: [
    { text: "Resuma este vídeo." },
    { fileData: { mimeType: "video/mp4", fileUri: "YOUR_UPLOADED_VIDEO_URI_HERE" } },
    // Opcionalmente, adicione VideoMetadata
    // { videoMetadata: { startOffset: "0s", endOffset: "30s" } } // Processar os primeiros 30s
  ]
}];

Usando URIs do Google Cloud Storage (Vertex AI):
Ao usar o Vertex AI, você pode referenciar diretamente arquivos de vídeo armazenados em buckets do Google Cloud Storage usando seu URI gs:// na parte fileData.

Quadros de Vídeo Live (ai.live):
Conforme discutido na seção ai.live, você pode enviar quadros de vídeo individuais (como objetos Blob, provavelmente mimetypes de imagem como image/jpeg ou image/png) usando session.sendRealtimeInput(). Isso permite análise ou interação em tempo real com base em um feed de vídeo live.

A interface VideoMetadata, com startOffset e endOffset, permite especificar qual segmento de um arquivo de vídeo o modelo deve focar, o que é útil para processar vídeos longos.

Suporte à API Gemini vs. Vertex AI: Uma Abordagem Dupla

Uma vantagem significativa do SDK Google Gen AI é seu suporte contínuo tanto para a API Gemini para Desenvolvedores (via Google AI Studio) quanto para o Vertex AI. Este suporte duplo oferece flexibilidade aos desenvolvedores e um caminho claro de atualização.

O SDK abstrai muitas das diferenças. Os métodos centrais como ai.models.generateContent() funcionam de forma semelhante para ambos, com a principal distinção sendo a inicialização (apiKey vs. vertexai: true, project, location). Isso permite que você comece com a API Gemini e migre para o Vertex AI conforme sua aplicação amadurece e escala, sem uma reescrita completa da sua lógica de IA. A documentação dos métodos frequentemente especifica se um recurso ou parâmetro é exclusivo de uma plataforma.

Conclusão: Seu Kit de Ferramentas para Aplicações de IA de Próxima Geração

O SDK Google Gen AI para TypeScript/JavaScript é um kit de ferramentas poderoso e versátil que traz as capacidades do Gemini 2.5 e outros modelos avançados diretamente para desenvolvedores JavaScript. Seu suporte a conteúdo multimodal, interações em tempo real via API Live, TTS integrado, geração de imagem e a flexibilidade de escolher entre a API Gemini para Desenvolvedores e o Vertex AI o tornam um recurso indispensável.

Ao entender a estrutura do SDK, seus módulos centrais (ai.models, ai.live, ai.chats, ai.files, ai.caches) e as nuances do prompting multimodal, você está bem equipado para construir aplicações inovadoras que podem ver, ouvir, falar e entender o mundo de maneiras mais ricas do que nunca. Conforme o Google continua a expandir os limites da IA, este SDK será sua chave para liberar esse potencial em seus projetos JavaScript e TypeScript. Mergulhe, experimente e construa o futuro das aplicações baseadas em IA hoje!

Gerei o artigo com base nas informações coletadas dos diretórios README.md e docs. Ele cobre todos os tópicos especificados e busca a contagem de palavras solicitada.

Pratique o design de API no Apidog

Descubra uma forma mais fácil de construir e usar APIs

Cadastre-se gratuitamenteBaixar