Guia Prático da API Gemini: Do Zero aos Primeiros 10.000 Tokens

Se você acompanha o ecossistema de IA, já sabe que a Google entrou com tudo nessa corrida. O Gemini — inicialmente chamado de Bard — evoluiu de um chatbot de testes para uma família completa de modelos multimodais que, em 2026, é uma das opções mais fortes para empresas brasileiras que querem construir produtos com IA.

Este guia é prático. Vamos cobrir o que você precisa para sair do zero e criar a sua primeira aplicação com a API Gemini: como obter a chave, os conceitos essenciais (modelos, tokens, multimodalidade, streaming), exemplos reais em Python e JavaScript, boas práticas de custo e um pequeno projeto completo de análise de texto. Se você não escreve código, ainda assim vale a leitura: ao final você vai conseguir conversar com desenvolvedores e agências — como a TS Digitais — com a linguagem certa e saber exatamente o que pedir.

O que é a API Gemini

A API Gemini é a interface de programação que dá acesso aos modelos de linguagem grandes (LLMs) da Google. Em termos simples: em vez de usar o Gemini pelo site (gemini.google.com), você conecta o modelo diretamente aos seus sistemas — site, chatbot, planilha, aplicativo ou automação.

A evolução em 2026

Quando o Google lançou o Gemini 1.0 em dezembro de 2023, era um produto de "corrida para acompanhar". Em 2026, a situação se inverteu:

• Gemini 2.x Flash é um dos modelos com melhor relação custo-qualidade do mercado — rápido, barato e capaz de processar contexto gigante (1 milhão de tokens na versão full, o que equivale a livros inteiros).
• Multimodalidade nativa: texto, imagem, áudio, vídeo e até código são processados por um único modelo.
• Integração profunda com o Google: o Gemini alimenta os AI Overviews no Google Search, o Gmail, o Docs e o Sheets.
• Funções e ferramentas: o modelo consegue chamar APIs externas, executar código Python e buscar na web.

Modelos principais em 2026

# Exemplo de configuração de variável de ambiente (Linux/macOS)
export GEMINI_API_KEY="sua-chave-aqui"

# Windows PowerShell
$env:GEMINI_API_KEY = "sua-chave-aqui"

Conceitos essenciais que você precisa dominar

Tokens

Modelos de linguagem não leem palavras — leem tokens (fragmentos de texto). Em português, uma palavra média equivale a cerca de 1,5 a 2 tokens. O preço da API é calculado por token: tanto na entrada (prompt) quanto na saída (resposta).

• 1.000 tokens ≈ 700-800 palavras em português (aproximadamente).
• O contexto total é a soma de entrada + saída. Se o modelo tem janela de 1 milhão de tokens, você pode mandar um livro inteiro de uma vez.

Prompt e resposta estruturada

Você manda um prompt (instrução + conteúdo) e o modelo responde. Em 2026, o padrão para produção é pedir respostas estruturadas em JSON, para integrar com sistemas sem gambiarra:

{
  "model": "gemini-2.0-flash",
  "contents": [
    {
      "parts": [
        {
          "text": "Classifique o seguinte e-mail como POSITIVO, NEGATIVO ou NEUTRO e retorne JSON: {\"classificacao\": \"...\", \"motivo\": \"...\"} E-mail: O produto chegou quebrado, quero meu dinheiro de volta imediatamente."
        }
      ]
    }
  ]
}

Multimodalidade

O modelo recebe texto e arquivos. Você pode mandar:

• Imagens (para extrair texto, descrever, analisar)
• Áudio (transcrição, resumo de reunião)
• Vídeo (análise de conteúdo, geração de clipes)
• PDFs e documentos (análise, extração de dados)

Isso muda o jogo para automações: um relatório de vendas em PDF pode ser enviado direto ao modelo para gerar um resumo executivo, sem OCR manual.

Streaming

Em vez de esperar a resposta completa (que pode levar segundos), você recebe o texto token por token, como no ChatGPT. Isso melhora muito a experiência do usuário em chatbots.

Grounding e funções

O Gemini pode buscar na web (grounding with Google Search) para responder com informações atuais e citar fontes — ideal para chatbots de atendimento que precisam de dados recentes. Também pode chamar funções suas (API de estoque, CRM), permitindo que o chatbot consulte dados reais do seu negócio.

Exemplo 1: sua primeira chamada em Python

Vamos direto ao código. Instale o SDK:

pip install google-generativeai

Chamada básica

import google.generativeai as genai
import os

# Configuração
genai.configure(api_key=os.environ["GEMINI_API_KEY"])

# Modelo
model = genai.GenerativeModel("gemini-2.0-flash")

# Geração de resposta
resposta = model.generate_content(
    "Explique em 3 frases o que é SEO para um pequeno empresário brasileiro."
)

print(resposta.text)

Resposta estruturada (JSON)

Para produção, force o formato JSON:

import google.generativeai as genai
import json
import os

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

prompt = """
Analise este depoimento de cliente e retorne SOMENTE JSON:
{"sentimento": "positivo|negativo|neutro", "assunto": "string", "urgente": bool}

Depoimento: "Gostei do produto mas o frete demorou 2 semanas e quase perdi uma venda."
"""

resposta = model.generate_content(
    prompt,
    generation_config={"response_mime_type": "application/json"}
)

dados = json.loads(resposta.text)
print(dados["sentimento"])   # "positivo" ou similar
print(dados["urgente"])      # True

O parâmetro response_mime_type: "application/json" obriga o modelo a devolver JSON válido — essencial para integrar com sistemas sem quebrar o parse.

Multimodal: analisando uma imagem

from PIL import Image
import google.generativeai as genai
import os

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

img = Image.open("foto_produto.jpg")

resposta = model.generate_content(
    [
        "Descreva este produto com foco em pontos de venda para e-commerce. "
        "Sugira um título de até 60 caracteres e 3 bullets de benefícios.",
        img,
    ]
)

print(resposta.text)

Streaming (conversa fluida)

model = genai.GenerativeModel("gemini-2.0-flash")

resposta = model.generate_content(
    "Escreva um parágrafo sobre marketing digital.",
    stream=True
)

for chunk in resposta:
    print(chunk.text, end="")

Exemplo 2: sua primeira chamada em JavaScript (Node.js)

O SDK oficial em JS cobre tanto Node.js quanto React (via @google/generative-ai).

Instalação

npm install @google/generative-ai

Chamada básica (ES Modules)

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

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

const result = await model.generateContent(
  "Dê 3 ideias de nomes para uma cafeteria em Florianópolis com foco em café especial."
);

console.log(result.response.text());

Resposta estruturada em JSON

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

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);
const model = genAI.getGenerativeModel({
  model: "gemini-2.0-flash",
  generationConfig: {
    responseMimeType: "application/json",
  },
});

const result = await model.generateContent(`
  Analise o texto abaixo e retorne JSON:
  {"tema": "string", "sentimento": "positivo|negativo|neutro", "resumo": "string"}

  Texto: "O atendimento foi excelente, a entrega chegou antes do prazo e o
  produto superou a expectativa. Recomendo!"
`);

const dados = JSON.parse(result.response.text());
console.log(dados.sentimento); // positivo
console.log(dados.resumo);

Multimodal via upload de arquivo

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

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

const fs = require("fs");
const base64 = fs.readFileSync("nota_fiscal.pdf").toString("base64");

const result = await model.generateContent([
  {
    inlineData: {
      data: base64,
      mimeType: "application/pdf",
    },
  },
  "Extraia desta nota fiscal: número, valor total, CNPJ do emissor e a lista de itens. Retorne em JSON.",
]);

console.log(result.response.text());

Streaming em React (com hooks)

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

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

async function gerarResposta(prompt) {
  const result = await model.generateContentStream(prompt);
  let texto = "";
  for await (const chunk of result.stream) {
    texto += chunk.text();
    setResposta(texto); // atualiza a UI token por token
  }
}

Projeto completo: classificador de e-mails de suporte

Vamos juntar tudo em um exemplo real: um script que lê uma lista de e-mails, classifica por prioridade e assunto, e gera um resumo executivo.

import google.generativeai as genai
import json
import os

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

emails = [
    "Quero cancelar minha assinatura imediatamente, está caro demais.",
    "Onde está meu pedido? Paguei há 5 dias e nada de atualização.",
    "Adorei o novo site, ficou lindo! Parabéns à equipe.",
    "Meu cartão foi recusado mas a cobrança apareceu duas vezes na fatura.",
]

prompt = f"""
Classifique cada e-mail abaixo e retorne JSON:
{{"resumo": "string", "total": int, "emails": [{{"texto": "string", "prioridade": "alta|media|baixa", "assunto": "string"}}]}}

E-mails:
{json.dumps(emails, ensure_ascii=False)}
"""

resposta = model.generate_content(
    prompt,
    generation_config={"response_mime_type": "application/json"},
)

relatorio = json.loads(resposta.text)
print(f"Total analisado: {relatorio['total']}")
print(f"Resumo: {relatorio['resumo']}")
for item in relatorio["emails"]:
    print(f"  [{item['prioridade'].upper()}] {item['assunto']}")

Saída esperada (simplificada):

Total analisado: 4
Resumo: Há 2 e-mails de alta prioridade envolvendo cobrança duplicada e cancelamento.
  [ALTA] Cancelamento de assinatura
  [ALTA] Cobrança duplicada
  [MEDIA] Status de pedido
  [BAIXA] Elogio ao atendimento

Esse mesmo padrão — prompt + JSON + integração — serve para análise de avaliações, extração de dados de currículos, triagem de leads e dezenas de outros casos.

Boas práticas de custo e performance

Reduza tokens de entrada

O custo é dominado pela entrada. Técnicas que funcionam:

• Selecione antes de enviar: em vez de mandar 500 avaliações, mande as 50 mais recentes.
• Use o modelo certo: Flash-Lite para classificação simples, Flash para a maioria, Pro só para o que exige raciocínio profundo.
• Contexto enxuto: instruções claras e curtas. Instruções vagas geram respostas longas (e caras) desnecessárias.

Gerencie custo com limites

No Vertex AI você configura orçamentos e alertas. No AI Studio, acompanhe o painel de uso. Regra prática: monte o caso de uso no playground antes de ir para a API, para calibrar o tamanho das respostas.

Retry e erro

Sempre trate erros de rede e limite de cota. Padrão mínimo em Python:

from google.api_core import exceptions
import time

def chamar_com_retry(model, prompt, tentativas=3):
    for i in range(tentativas):
        try:
            return model.generate_content(prompt)
        except exceptions.ResourceExhausted as e:
            if i == tentativas - 1:
                raise
            time.sleep(2 ** i)  # backoff exponencial

Cache e embeddings

Para respostas repetidas (ex.: regras de negócio fixas), o Gemini oferece prompt caching — instruções grandes reutilizadas custam muito menos. E para busca em bases de conhecimento (RAG), use modelos de embedding para indexar conteúdo e buscar por similaridade.

Segurança: proteja sua chave e seus dados

• Variáveis de ambiente sempre. Nunca hardcode.
• Não exponha a chave no frontend de produção. Se precisa do modelo no navegador, use um backend que receba a chave e faça a chamada.
• Rate limiting: proteja sua API com limites de requisição para não estourar custo com abuso.
• Dados sensíveis: revise o que você envia. Em produção no Vertex AI, ative as opções de retenção e inspeção de dados da Google.

Quando usar AI Studio x Vertex AI