API do Claude: primeiros passos

Minha primeira chamada à API foi para classificar 400 respostas de formulário em "lead quente", "morno" e "frio". Levou vinte minutos para escrever o script e três minutos para rodar. O que eu não fiz foi registrar tokens, e a fatura do mês me ensinou a fazer. Este é o guia que eu queria ter lido antes: como fazer a primeira chamada, o que observar em custo e limites, e o que ter pronto antes de colocar algo em produção.

Não é um tutorial de programação linha a linha; é o mapa do que importa.

O que é a API e para que serve

A API é a forma de usar o Claude dentro do seu próprio sistema: um script, uma automação, um produto. Em vez de conversar no aplicativo, seu código envia mensagens e recebe respostas. Serve para tudo que é repetitivo e em volume: classificar, extrair dados de textos, gerar descrições, resumir, responder perguntas com base nos seus documentos.

É cobrada por consumo, em tokens, e independe da assinatura do aplicativo de chat.

A primeira chamada

Você cria uma chave de API no console, escolhe um modelo, e envia uma lista de mensagens (papel usuário e papel assistente) com um limite máximo de tokens de saída. A resposta volta com o texto e a contagem de tokens de entrada e saída. Há SDKs para as principais linguagens, e qualquer ferramenta que faça requisição HTTP funciona.

Comece com um modelo pequeno e barato. Suba para um maior só onde a qualidade da tarefa exigir; muitos sistemas usam dois modelos, um para triagem e outro para o que é difícil.

Custo: entenda antes de escalar

Custo por chamada é tokens de entrada vezes o preço de entrada mais tokens de saída vezes o preço de saída. A saída custa mais. O maior custo escondido é o que se repete em toda chamada: o prompt de sistema e o contexto fixo. O cache de prompt reduz isso reaproveitando o contexto por um período.

Antes de construir, estime: tokens médios por chamada, volume mensal, preço do modelo, mais 30% de margem. A calculadora deste site faz a conta.

Registre tudo

Cada chamada deve deixar registro de modelo, tokens de entrada e saída, tempo e erro. Sem isso, todo problema vira adivinhação e toda fatura vira surpresa.

Limites e erros

Há limites de requisições por minuto e de tokens por minuto, que crescem com o uso. Quando você bate neles, a API devolve erro e seu código deve esperar e tentar de novo com intervalo crescente, não insistir imediatamente. Trate também tempo limite e respostas incompletas: defina o que acontece quando a IA não responde, porque vai acontecer.

Segurança básica

A chave nunca vai para o navegador nem para o repositório. Fica em variável de ambiente no servidor. Conteúdo de terceiros (e-mails, páginas, arquivos) entra como dado, separado das instruções, porque pode conter comandos escondidos. Ações com efeito externo (enviar, apagar, pagar) exigem confirmação ou modo de simulação.

Ferramentas e conectores pela API

Além de texto, a API permite dar ferramentas ao modelo: funções do seu sistema que ele pode chamar, como consultar estoque ou criar uma tarefa. Você descreve cada ferramenta com nome, o que faz e parâmetros; o modelo decide quando usar e devolve a chamada para o seu código executar. É assim que se constrói um agente. Servidores MCP padronizam isso para serviços comuns.

Comece sem ferramentas. Adicione uma quando a tarefa realmente exigir ação, e sempre com as ferramentas de escrita atrás de confirmação. A maior parte dos sistemas úteis que conheço usa uma ou duas ferramentas, não vinte.

O que ter pronto antes de produção

Um conjunto de casos de teste com resposta esperada, para rodar a cada mudança de prompt ou modelo. Registro de chamadas e custos. Limite de uso por usuário. Tratamento de erro visível. Um plano para quando o modelo for descontinuado, o que acontece com regularidade. Com isso, você tem um sistema; sem isso, tem um experimento que pode custar caro.

Perguntas frequentes

Fontes e método

• Documentação da API da Anthropic (referência, preços, cache de prompt, limites)
• Automações próprias em produção desde 2025