Como Integrar a API do Claude no Seu App

Para integrar a API do Claude, crie uma chave de API no Claude Console da Anthropic, guarde-a como segredo do servidor (normalmente ANTHROPIC_API_KEY) e chame a Messages API a partir de uma rota no seu próprio servidor, usando um dos SDKs oficiais da Anthropic. Cada requisição indica um modelo, define o max_tokens (a resposta mais longa que você aceita) e envia a conversa como messages, com as suas instruções em um system prompt separado. Defina um limite de gasto, transmita respostas longas em streaming e trate os erros de limite de taxa (429) e de sobrecarga (529) com novas tentativas.

Este guia cobre a configuração, um fluxo de requisição seguro, prompts para um construtor de IA e os erros que você deve prever. Os detalhes da Anthropic são da documentação de setembro de 2026. Para entender como funcionam tokens e preços em geral, veja como usar APIs de LLM.

O que dá para construir com ela

• Assistentes de chat e widgets de ajuda (como criar um app de chatbot com IA)
• Resumos, reescritas e rascunhos de respostas
• Extração de campos de documentos, e-mails e formulários
• Respostas a perguntas com base no seu próprio conteúdo
• Agentes que chamam funções do seu app por meio de uso de ferramentas (tool use)

Para mais ideias, veja como adicionar recursos de IA ao seu app.

A Messages API em resumo

Segundo a referência da API da Anthropic, uma requisição é um POST para https://api.anthropic.com/v1/messages com:

A API não guarda estado: para continuar uma conversa, envie os turnos anteriores de novo a cada requisição. Por isso, chats longos custam mais por mensagem.

A Anthropic publica SDKs oficiais para Python, TypeScript, C#, Go, Java, PHP e Ruby. Eles configuram os cabeçalhos, processam as respostas e suportam streaming. Use um deles em vez de HTTP puro, a menos que tenha um motivo para não usar.

Escolhendo um modelo

A Anthropic oferece vários modelos Claude que equilibram capacidade, velocidade e preço, e a lista muda com o tempo. Escolha o menor modelo que faça bem a sua tarefa, teste com exemplos reais e mantenha o ID do modelo em configuração, para trocar sem mudar o código. Consulte as páginas de modelos e preços da Anthropic para ver as opções e tarifas atuais.

Configurando sua conta

1. Entre no Claude Console em platform.claude.com e adicione um método de pagamento.
2. Crie uma chave de API. Mantenha uma chave por ambiente (teste e produção), para poder revogar uma sem quebrar a outra.
3. Defina um limite de gasto. A página de erros da Anthropic observa que, quando o uso atinge um limite de gasto que você definiu, a API retorna um erro 400; por isso, seu app deve mostrar uma mensagem clara nesse caso.
4. Confira os limites de taxa da sua conta no Console; eles são medidos por organização.

O fluxo da requisição

1. O usuário age no seu app: envia uma mensagem, clica em "Resumir".
2. O navegador chama a sua rota no servidor, nunca a Anthropic diretamente.
3. Seu servidor verifica se o usuário está logado e se pode usar o recurso, e aplica um limite por usuário.
4. Ele monta a requisição: um system prompt com as suas regras, a entrada do usuário e os dados do seu banco de dados que a tarefa precisar.
5. Chama a Messages API com a chave vinda do ambiente e um max_tokens sensato.
6. Transmite a resposta para o navegador em streaming e registra o uso de tokens que vem na resposta.

Opções e trade-offs

Prompts para dar ao seu construtor de IA

Uma primeira funcionalidade:

Adicione um painel "Pergunte sobre este documento". Ele chama uma rota no servidor POST /api/ask que verifica se o usuário está logado e é dono do documento, depois chama a Messages API do Claude com o SDK oficial da Anthropic e o segredo ANTHROPIC_API_KEY. Leia o ID do modelo do segredo CLAUDE_MODEL. System prompt: "Responda apenas com base no documento fornecido. Se a resposta não estiver nele, diga isso." Envie o texto do documento e a pergunta, defina max_tokens como 800, transmita a resposta para a página em streaming e nunca exponha a chave ao navegador.

Limites e tratamento de erros:

Limite cada usuário a 20 perguntas por hora, registradas no banco de dados. Registre os tokens de entrada e saída de cada resposta com o ID do usuário e o ID da requisição. Em erros 429 ou 529, tente de novo com backoff exponencial até 3 vezes, respeitando qualquer cabeçalho retry-after; depois mostre "O assistente está ocupado, tente novamente em instantes." Se a API informar erro de limite de gasto, mostre "Os recursos de IA estão pausados" e avise o administrador.

Erros com que você deve contar

A partir da documentação de erros da Anthropic, os que o seu app realmente vai encontrar:

A documentação da Anthropic diz que os SDKs oficiais repetem automaticamente falhas transitórias (erros de conexão, limites de taxa e erros 5xx) duas vezes por padrão, com backoff exponencial, e que isso pode ser configurado. Toda resposta traz um cabeçalho request-id; registre-o para que o suporte consiga rastrear problemas.

Erros comuns

• Chamar a API a partir do navegador. Sua chave fica pública. Passe sempre pelo seu servidor. Veja como manter as chaves de API seguras.
• Esquecer que max_tokens é um teto, não uma meta. Defina o valor que a funcionalidade precisa; baixo demais corta respostas, alto demais arrisca respostas longas e caras.
• Colocar regras na mensagem do usuário. Instruções estáveis pertencem ao system prompt; permissões pertencem ao seu código.
• Enviar o chat inteiro para sempre. Corte ou resuma turnos antigos conforme as conversas crescem.
• Sem limite de gasto ou limite por usuário.
• Fixar o ID do modelo no código. Modelos são atualizados e descontinuados.
• Ignorar o motivo de parada. Se a resposta parou por ter atingido max_tokens, avise o usuário ou aumente o limite.

Checklist

• Chave de API criada no Claude Console e guardada como segredo do servidor
• Chaves separadas para teste e produção
• Limite de gasto definido; mensagem clara quando for atingido
• Todas as requisições passam pelo seu servidor com verificação de permissões
• O system prompt guarda as regras; o ID do modelo é configurável
• max_tokens definido por funcionalidade; respostas longas transmitidas em streaming
• Limite de taxa por usuário no seu app
• Erros 429 e 529 tratados com backoff; IDs de requisição registrados
• Estado de erro amigável que não quebra a página
• Testado com entradas vazias, muito longas e hostis

Usando a API do Claude na Mythex

Em apps que você constrói na Mythex, os recursos com Claude usam a sua própria chave da Anthropic e são cobrados na sua conta da Anthropic, não nos créditos de build da Mythex. Isso é separado do agente da Mythex que escreve o seu código. Adicione ANTHROPIC_API_KEY como segredo do projeto pelo /secrets, pelas configurações do projeto ou pelo cartão de segredos no chat, e depois descreva o recurso com prompts parecidos com os acima. Publique de novo depois de mudar segredos em um app no ar. Veja Adicionar recursos de IA com suas próprias chaves de API para um prompt inicial. Se você está escolhendo entre provedores, como integrar a API da OpenAI cobre o mesmo terreno para a OpenAI.

Perguntas