Como Integrar a API do Claude na Sua App

Para integrar a API do Claude, crie uma chave de API na 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 SDK oficiais da Anthropic. Cada pedido indica um modelo, define max_tokens (a resposta mais longa que aceita) e envia a conversa como messages, com as instruções num prompt de sistema separado. Defina um limite de gastos, faça streaming das respostas longas e trate os erros de limite de pedidos (429) e de sobrecarga (529) com novas tentativas.

Este guia cobre a configuração, um fluxo de pedido seguro, prompts para um construtor de IA e os erros a prever. Os detalhes da Anthropic são da sua documentação em setembro de 2026. Para perceber como funcionam os tokens e a faturação em geral, veja como usar APIs de LLM.

O que pode construir com ela

• Assistentes de conversa e widgets de ajuda (como criar uma app de chatbot com IA)
• Resumos, reescritas e respostas redigidas
• Extração de campos de documentos, e-mails e formulários
• Respostas a perguntas sobre os seus próprios conteúdos
• Agentes que chamam funções da sua app através de uso de ferramentas (tool use)

Para mais ideias, veja como adicionar funcionalidades de IA à sua app.

A Messages API em resumo

Segundo a referência da API da Anthropic, um pedido é um POST para https://api.anthropic.com/v1/messages com:

A API não guarda estado: para continuar uma conversa, envie novamente os turnos anteriores em cada pedido. É por isso que as conversas longas custam mais por mensagem.

A Anthropic publica SDK oficiais para Python, TypeScript, C#, Go, Java, PHP e Ruby. Definem os cabeçalhos, interpretam as respostas e suportam streaming. Use um deles em vez de HTTP direto, a menos que tenha um motivo para não o fazer.

Escolher um modelo

A Anthropic oferece vários modelos Claude que trocam capacidade por velocidade e preço, e a gama muda. Escolha o modelo mais pequeno que faça bem a sua tarefa, teste-o com exemplos reais e mantenha o ID do modelo na configuração para o poder trocar sem alterar o código. Consulte as páginas de modelos e preços da Anthropic para ver as opções e tarifas atuais.

Configurar a sua conta

1. Inicie sessão na Claude Console em platform.claude.com e adicione a faturação.
2. Crie uma chave de API. Mantenha uma chave por ambiente (testes e produção) para poder revogar uma sem afetar a outra.
3. Defina um limite de gastos. A página de erros da Anthropic indica que, quando o consumo atinge um limite de gastos definido por si, a API devolve um erro 400; por isso, a sua app deve mostrar uma mensagem clara quando isso acontecer.
4. Consulte os limites de pedidos da sua conta na Console; são medidos por organização.

O fluxo do pedido

1. O utilizador age na sua app: envia uma mensagem, clica em "Resumir".
2. O navegador chama o seu servidor, nunca a Anthropic diretamente.
3. O seu servidor verifica se o utilizador tem sessão iniciada e se pode usar a funcionalidade, e aplica um limite por utilizador.
4. Constrói o pedido: um prompt de sistema com as suas regras, o que o utilizador escreveu e os dados que a tarefa precisa da sua base de dados.
5. Chama a Messages API com a chave do ambiente e um max_tokens adequado.
6. Envia a resposta em streaming para o navegador e regista o consumo de tokens indicado na resposta.

Opções e compromissos

Prompts para dar ao seu construtor de IA

Uma primeira funcionalidade:

Adicione um painel "Pergunte sobre este documento". Chama uma rota do servidor POST /api/ask que verifica se o utilizador tem sessão iniciada e é dono do documento, e 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. Prompt de sistema: "Responda apenas com base no documento fornecido. Se a resposta não estiver lá, diga-o." Envie o texto do documento e a pergunta, defina max_tokens como 800, envie a resposta em streaming para a página e nunca exponha a chave ao navegador.

Proteções e erros:

Limite cada utilizador a 20 perguntas por hora, registadas na base de dados. Registe os tokens de entrada e de saída de cada resposta com o ID do utilizador e o ID do pedido. Em erros 429 ou 529, tente novamente com recuo exponencial até 3 vezes, respeitando o cabeçalho retry-after, e depois mostre "O assistente está ocupado, tente novamente dentro de instantes." Se a API indicar um erro de limite de gastos, mostre "As funcionalidades de IA estão em pausa" e avise o administrador.

Erros a prever

Segundo a documentação de erros da Anthropic, estes são os que a sua app vai realmente encontrar:

A documentação da Anthropic indica que os SDK oficiais repetem automaticamente as falhas transitórias (erros de ligação, limites de pedidos e erros 5xx) duas vezes por defeito, com recuo exponencial, e que pode configurar esse comportamento. Cada resposta traz um cabeçalho request-id; registe-o para que o suporte consiga rastrear os problemas.

Erros comuns

• Chamar a API a partir do navegador. A sua chave fica pública. Passe sempre pelo seu servidor. Veja como manter as chaves de API seguras.
• Esquecer que max_tokens é um limite, não um objetivo. Defina o valor que a funcionalidade precisa; se for baixo, as respostas são cortadas; se for alto, arrisca respostas longas e caras.
• Colocar regras na mensagem do utilizador. As instruções estáveis pertencem ao prompt de system; as permissões pertencem ao seu código.
• Enviar o chat completo para sempre. Corte ou resuma as mensagens antigas à medida que as conversas crescem.
• Não definir limite de gastos nem limite por utilizador.
• Fixar o ID do modelo no código. Os modelos são atualizados e descontinuados.
• Ignorar o motivo de paragem. Se a resposta parou por ter atingido max_tokens, avise o utilizador ou aumente o limite.

Lista de verificação

• Chave de API criada na Claude Console e guardada como segredo do servidor
• Chaves separadas para testes e produção
• Limite de gastos definido; mensagem clara quando é atingido
• Todos os pedidos passam pelo seu servidor com verificação de permissões
• As regras estão no prompt de sistema; o ID do modelo é configurável
• max_tokens definido por funcionalidade; respostas longas em streaming
• Limite de utilização por utilizador na sua app
• Erros 429 e 529 tratados com recuo; IDs de pedido registados
• Estado de erro amigável que não parte a página
• Testado com entradas vazias, muito longas e hostis

Usar a API do Claude na Mythex

Nas apps que constrói na Mythex, as funcionalidades do Claude usam a sua própria chave da Anthropic e são faturadas na sua conta Anthropic, e não aos créditos de construção da Mythex. Isto é separado do agente Mythex que escreve o seu código. Adicione ANTHROPIC_API_KEY como segredo do projeto através de /secrets, das definições do projeto ou do cartão de segredos no chat, e depois descreva a funcionalidade com prompts como os acima. Publique novamente depois de alterar segredos numa app em produção. Veja Adicionar funcionalidades de IA com as suas próprias chaves de API para um prompt inicial. Se está a escolher entre fornecedores, como integrar a API da OpenAI cobre o mesmo terreno para a OpenAI.

Perguntas