Consumindo Modelos de IA

APIs de LLM

Conceito de API REST, request/response, autenticação por chave e arquitetura básica de integração.

Intermediário 30 min 25 pontos Leitura 0%

Nesta aula você vai

  • Descrever endpoint, headers e body de uma API de LLM
  • Proteger API key no backend
  • Comparar provedores comuns (OpenAI, Anthropic, Google)

APIs de LLM

Objetivos

  • Entender arquitetura básica de integração
  • Nunca expor chave de API no frontend
  • Ler documentação de qualquer provedor com confiança

Desmistificando a integração

Muita gente trata API de LLM como algo místico. Na prática, é um POST com JSON — igual integrar pagamento, CRM ou qualquer serviço REST que você já consumiu.

A diferença está no payload: em vez de { "amount": 99.90 }, você envia { "messages": [...] } e recebe texto gerado. O resto — autenticação, timeout, retry, logs — é engenharia que você já conhece.

Nesta aula mapeamos o contrato da API. Na próxima, você escreve o código. Na terceira, aprende a não derrubar produção quando algo der errado.

Anatomia de uma chamada

Padrão comum (OpenAI-compatible, usado por dezenas de provedores):

POST https://api.openai.com/v1/chat/completions
Authorization: Bearer sk-...
Content-Type: application/json

{
  "model": "gpt-4o-mini",
  "messages": [
    { "role": "user", "content": "Olá" }
  ]
}

Response (200):

{
  "id": "chatcmpl-...",
  "choices": [
    {
      "message": { "role": "assistant", "content": "Olá! Como posso ajudar?" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 8,
    "completion_tokens": 12,
    "total_tokens": 20
  }
}

Campos que seu código sempre deve tratar:

  • choices[0].message.content — texto da resposta
  • usage — billing e métricas
  • error (4xx/5xx) — mensagem e código

Fluxo em linguagem humana:

Seu servidor monta o JSON → envia para o provedor → espera (pode levar segundos) → lê choices[0].message.content → devolve ao frontend em formato seu.

Provedores principais

Provedor Endpoint base Observação
OpenAI api.openai.com/v1 Referência de mercado
Anthropic api.anthropic.com/v1/messages Formato próprio, excelente em texto longo
Google Gemini generativelanguage.googleapis.com Integração Google Cloud
Groq / Together / OpenRouter Variados OpenAI-compatible, modelos open

Para este curso, exemplos usam formato OpenAI-compatible — portável entre provedores. Aprendeu um, adapta o endpoint e os headers.

Dica de professor: não escolha provedor por hype. Escolha por preço, latência, limite de contexto e política de dados para o seu caso.

Onde guardar a API key

❌ Frontend (React, HTML, app mobile compilado)
❌ Repositório Git
✅ Variável de ambiente no servidor (.env, secrets CI, Vault)
✅ Cloudflare Workers secrets / AWS Parameter Store

Fluxo correto:

Browser → POST /api/chat (seu domínio)
              ↓
         Backend lê process.env.OPENAI_API_KEY
              ↓
         Chama OpenAI

Por que isso importa tanto:

Um dev júnior colocou OPENAI_API_KEY no .env do Vite. O build empacotou a chave no JavaScript público. Em 20 minutos, bots drenaram o crédito.

A chave no frontend não é "atalho para testar" — é vazamento garantido. Teste sempre via backend ou script local com variável de ambiente.

Roles em messages

Role Função
system Regras fixas, persona, formato de saída
user Mensagem do usuário final
assistant Respostas anteriores do modelo (histórico)

Ordem importa: system primeiro, depois alternância user/assistant cronológica — como uma conversa real.

Exemplo de montagem:

system:   "Você é assistente da Loja Nova Era..."
user:     "Onde está meu pedido?"
assistant: "Informe o número do pedido, por favor."
user:     "8842"

O modelo usa todo esse contexto para gerar a próxima fala.

Headers úteis

  • Authorization: Bearer <key>
  • Content-Type: application/json
  • OpenAI-Organization (opcional, multi-org)
  • Timeout no cliente HTTP — 30–60s; LLM pode demorar

Não esqueça timeout. Sem ele, uma requisição travada segura worker, thread ou conexão do usuário indefinidamente.

Checklist antes da primeira chamada

  1. Conta criada + billing ativo
  2. Key gerada com escopo mínimo
  3. .env no .gitignore
  4. Endpoint de teste no backend (não no Postman com key exposta em screenshot)

Resumo

  • LLM via HTTP POST + JSON — igual qualquer REST
  • Key só no backend; frontend fala com seu API
  • messages[] + model + parâmetros = contrato padrão
  • Leia usage e error em toda resposta

Na próxima aula você deixa de ler documentação e executa a primeira chamada — em Node, Python ou PHP, no idioma que já usa no dia a dia.