Integração com a API Gemini

Visão Geral

Esta habilidade orienta agentes de IA na integração da API Google Gemini em aplicações — desde a geração básica de texto até casos de uso avançados multimodais, chamadas de função e streaming. Ela cobre todo o ciclo de vida do SDK Gemini com padrões de nível de produção.

Quando Usar Esta Habilidade

• Use ao configurar a API Gemini pela primeira vez em um projeto Node.js, Python ou de navegador
• Use ao implementar entradas multimodais (texto + imagem/áudio/vídeo)
• Use ao adicionar respostas em streaming para melhorar a latência percebida
• Use ao implementar chamadas de função / uso de ferramentas com Gemini
• Use ao otimizar a seleção de modelos (Flash vs Pro vs Ultra) para custo e desempenho
• Use ao depurar erros da API Gemini, limites de taxa ou problemas de cota

Guia Passo a Passo

1. Instalação e Configuração

Node.js / TypeScript:

npm install @google/generative-ai

Python:

pip install google-generativeai

Defina sua chave de API com segurança:

read -rsp "Gemini API key: " GEMINI_API_KEY
echo
export GEMINI_API_KEY

2. Geração Básica de Texto

Node.js:

import { GoogleGenerativeAI } from "@google/generative-ai";

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

const result = await model.generateContent("Explain async/await in JavaScript");
console.log(result.response.text());

Python:

import google.generativeai as genai
import os

genai.configure(api_key=os.environ["GEMINI_API_KEY"])
model = genai.GenerativeModel("gemini-1.5-flash")

response = model.generate_content("Explain async/await in JavaScript")
print(response.text)

3. Respostas em Streaming

const result = await model.generateContentStream("Write a detailed blog post about AI");

for await (const chunk of result.stream) {
  process.stdout.write(chunk.text());
}

4. Entrada Multimodal (Texto + Imagem)

import fs from "fs";

const imageData = fs.readFileSync("screenshot.png");
const imagePart = {
  inlineData: {
    data: imageData.toString("base64"),
    mimeType: "image/png",
  },
};

const result = await model.generateContent(["Describe this image:", imagePart]);
console.log(result.response.text());

5. Chamada de Função / Uso de Ferramentas

const tools = [{
  functionDeclarations: [{
    name: "get_weather",
    description: "Get current weather for a city",
    parameters: {
      type: "OBJECT",
      properties: {
        city: { type: "STRING", description: "City name" },
      },
      required: ["city"],
    },
  }],
}];

const model = genAI.getGenerativeModel({ model: "gemini-1.5-pro", tools });
const result = await model.generateContent("What's the weather in Mumbai?");

const call = result.response.functionCalls()?.[0];
if (call) {
  // Execute the actual function
  const weatherData = await getWeather(call.args.city);
  // Send result back to model
}

6. Chat Multi-turn

const chat = model.startChat({
  history: [
    { role: "user", parts: [{ text: "You are a helpful coding assistant." }] },
    { role: "model", parts: [{ text: "Sure! I'm ready to help with code." }] },
  ],
});

const response = await chat.sendMessage("How do I reverse a string in Python?");
console.log(response.response.text());

7. Guia de Seleção de Modelos

Melhores Práticas

• ✅ Faça: Use gemini-1.5-flash para a maioria das tarefas — é rápido e econômico
• ✅ Faça: Sempre transmita respostas para UIs de chat voltadas para o usuário para reduzir a latência percebida
• ✅ Faça: Armazene chaves de API em variáveis de ambiente, nunca as codifique diretamente
• ✅ Faça: Implemente backoff exponencial para erros de limite de taxa (429)
• ✅ Faça: Use systemInstruction para definir o comportamento persistente do modelo
• ❌ Não Faça: Use gemini-pro para tarefas simples — Flash é mais barato e rápido
• ❌ Não Faça: Envie imagens base64 grandes em linha para arquivos > 20MB — use a API de Arquivos em vez disso
• ❌ Não Faça: Ignore as classificações de segurança nas respostas para aplicativos de produção

Tratamento de Erros

try {
  const result = await model.generateContent(prompt);

…