Integração de APIs de IA: OpenAI, Claude e Gemini

1. Chaves e variáveis de ambiente

Nunca hardcode a API key. Use variáveis de ambiente e, em produção, um secret manager (GitHub Actions secrets, Doppler, AWS Secrets Manager, etc.).

# .env (nunca commitado)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=AIza...

No Node: dotenv ou variáveis nativas do runtime. No Python: python-dotenv ou o loader do framework.

2. OpenAI

Node.js

import OpenAI from "openai";

const client = new OpenAI(); // lê OPENAI_API_KEY

const completion = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [
    { role: "system", content: "Você é um assistente de engenharia de software." },
    { role: "user", content: "Explique este erro de TypeScript..." }
  ],
  temperature: 0.2,
});

console.log(completion.choices[0].message.content);

Python

from openai import OpenAI

client = OpenAI()  # OPENAI_API_KEY

resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "Você é um assistente de engenharia de software."},
        {"role": "user", "content": "Explique este erro de TypeScript..."}
    ],
    temperature=0.2,
)
print(resp.choices[0].message.content)

3. Anthropic Claude

Node.js

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic(); // ANTHROPIC_API_KEY

const msg = await client.messages.create({
  model: "claude-sonnet-4-20250514",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Revise este diff de segurança..." }],
});

console.log(msg.content[0].text);

Python

import anthropic

client = anthropic.Anthropic()

msg = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Revise este diff de segurança..."}],
)
print(msg.content[0].text)

Claude usa messages (não há role system separado no mesmo formato; use o parâmetro system no create quando precisar).

4. Google Gemini

Python (SDK oficial)

import google.generativeai as genai
import os

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

resp = model.generate_content("Gere um schema JSON para um pedido de e-commerce")
print(resp.text)

No Node, use @google/generative-ai com o mesmo fluxo: configurar a key e chamar generateContent.

5. Streaming no front-end

Para UX de “digitando…”, use streaming. Exemplo genérico com Server-Sent Events (backend Node):

// backend (express)
app.post("/api/chat", async (req, res) => {
  res.setHeader("Content-Type", "text/event-stream");
  res.setHeader("Cache-Control", "no-cache");
  res.flushHeaders();

  const stream = await client.chat.completions.create({
    model: "gpt-4o-mini",
    messages: req.body.messages,
    stream: true,
  });

  for await (const chunk of stream) {
    const delta = chunk.choices[0]?.delta?.content || "";
    if (delta) res.write(`data: ${JSON.stringify({ delta })}\n\n`);
  }
  res.write("data: [DONE]\n\n");
  res.end();
});

No front, consuma com EventSource ou fetch + ReadableStream e vá concatenando o texto na UI.

6. Checklist de produção

• Timeouts e retries com backoff (erros 429 e 5xx)
• Limite de tokens de entrada e saída
• Logging de custo (tokens in/out) por usuário ou feature
• Sanitização de prompt: não deixe o usuário injetar instruções que quebrem o system prompt
• Fallback: se um provedor cair, ter um segundo modelo configurado
• Observabilidade: latência p50/p95, taxa de erro, tokens médios

Com esses três clientes você cobre a maior parte dos casos. Escolha o modelo conforme a tarefa (código, raciocínio longo, custo) e mantenha a camada de aplicação desacoplada do provedor — facilita trocar depois.

7. Os parâmetros explicados

Streaming com Server-Sent Events

8. Erros comuns e como resolver

← Ollama local · hub de IA · RAG com pgvector →