Como integrar a API do Claude à sua aplicação

Uma integração da API Claude é pequena no primeiro dia — a instalação de um SDK e uma chamada autenticada —, mas estar pronta para produção depende das partes ao redor dessa chamada: streaming, novas tentativas, orçamentos de tokens e observabilidade. Este guia abrange todo o percurso, com código funcional que você pode adaptar diretamente.

Autenticação e sua primeira solicitação

Instale o SDK oficial (pip install anthropic ou npm install @anthropic-ai/sdk), defina sua chave em uma variável de ambiente — nunca no código-fonte — e faça uma chamada à Messages API para validar o fluxo. A API é versionada por meio de um cabeçalho anthropic-version que os SDKs definem para você.

As chaves funcionam da mesma forma, sejam elas da Anthropic Console ou de um gateway compatível com a Anthropic, como o AI Prime Tech (um serviço independente, sem afiliação com a Anthropic): a única diferença é o base_url usado para construir seu cliente.

Escolha de modelos por tarefa

Integrações que fixam um único modelo no código gastam demais ou entregam desempenho insuficiente. Direcione por tarefa: Haiku 4.5 para classificação, extração e roteamento; Sonnet 4.6 para a maioria dos recursos de produto e programação; Opus 4.8 quando a profundidade do raciocínio é o produto; Fable 5 quando você precisa da janela de contexto de 1M — comparação completa em <a href="/pt/learn/claude-api-models-compared/">Comparação dos modelos Claude</a>.

Faça do modelo um valor de configuração, não uma constante — os nomes dos modelos mudam a cada poucos meses, e você vai querer fazer testes A/B de novas versões sem uma implantação.

Streaming, tempos limite e novas tentativas

Use streaming em tudo que uma pessoa acompanha: eventos enviados pelo servidor entregam os tokens à medida que são gerados, reduzindo a latência percebida de vários segundos para menos de um. Chamadas sem streaming com max_tokens elevado também têm maior probabilidade de atingir o tempo limite de leitura do proxy — uma classe de bug que só aparece em produção.

Repita as chamadas que retornarem respostas 429 e 5xx com espera exponencial e variação aleatória, respeite os cabeçalhos retry-after quando presentes e limite o total de tentativas. Trate respostas 400 como falhas permanentes — o próprio payload está incorreto (muitas vezes por uma entrada grande demais; veja <a href="/pt/learn/claude-api-errors-troubleshooting/">Erros da API do Claude</a>) e repetir a chamada só consome cota.

Lista de verificação para produção

Antes do lançamento: limites de tokens aplicados tanto à entrada quanto à saída; registro de custos por requisição (o uso é retornado em todas as respostas); cache de prompts habilitado para prompts de sistema repetidos; um modelo ou endpoint alternativo para incidentes; e análise de injeção de prompt caso a entrada do usuário chegue ao prompt.

A maior parte dos problemas de integração não está na própria API — está no crescimento ilimitado do contexto e na falta de observabilidade. Registre os tokens de entrada e saída desde o primeiro dia, e as surpresas com custos desaparecem.

import os, anthropic

client = anthropic.Anthropic(
    api_key=os.environ["ANTHROPIC_API_KEY"],
    base_url=os.environ.get("ANTHROPIC_BASE_URL", "https://aiprimetech.io"),
)

with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Summarize our launch plan in 3 bullets."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Perguntas frequentes

AI Prime Tech é um gateway de API independente. Não tem afiliação com a Anthropic, não é endossado por ela e não é seu revendedor. Claude e os nomes dos modelos relacionados são marcas comerciais de seus respectivos proprietários.