API do Claude: primeiros passos para fazer sua primeira chamada

Resposta rápidaA API do Claude permite que seus próprios sistemas, planilhas e automações conversem com o modelo por código. Você cria uma conta no Console da Anthropic, gera uma chave de API, instala o SDK e envia mensagens. A cobrança é por uso, separada da assinatura do app Claude.

A API do Claude é a porta para usar o modelo dentro dos seus próprios sistemas: uma planilha que classifica reclamações, um formulário que resume respostas, um fluxo de automação que redige e-mails. Em vez de abrir o app e conversar, seu programa envia o texto, recebe a resposta e continua o trabalho sozinho.

Este artigo explica como a API funciona, como dar os primeiros passos e quais cuidados evitam dor de cabeça com custo e segurança.

API, app e Claude Code: o que muda

São três formas de usar o mesmo tipo de modelo, com objetivos diferentes.

O ponto de atenção é que assinatura do app e API são cobranças independentes. Ter o Claude Pro não dá crédito de API. Para comparar planos do app, veja planos do Claude comparados.

Quando faz sentido usar a API

Use a API quando a tarefa precisa rodar sem você, em volume ou integrada a outro sistema:

• Classificar centenas de mensagens de clientes por assunto e urgência.
• Extrair campos de documentos (datas, valores, nomes) e gravar numa planilha.
• Gerar rascunhos de resposta dentro de um sistema de atendimento.
• Resumir automaticamente atas ou chamadas.

Se a tarefa é ocasional e feita por uma pessoa, o app resolve melhor e mais barato. Para automação sem programar, a ferramenta visual n8n costuma chamar a API por você; veja automação com n8n e IA.

Como é uma chamada

A API de mensagens funciona assim: você envia o modelo desejado, um limite de tokens para a resposta e uma lista de mensagens; recebe de volta o texto do modelo e a contagem de tokens usados. Esta é a estrutura do exemplo oficial em Python, descrito na documentação de início rápido da Anthropic:

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="NOME-DO-MODELO",
    max_tokens=1000,
    messages=[
        {"role": "user", "content": "Resuma em 3 linhas: ..."}
    ],
)

for block in message.content:
    if block.type == "text":
        print(block.text)

Troque NOME-DO-MODELO pelo identificador atual listado na página de modelos da documentação. Os nomes e as versões mudam com frequência, então copie sempre da fonte oficial. A mesma documentação traz exemplos em cURL, TypeScript, Go, Java, C#, PHP e Ruby, além de uma interface de linha de comando.

O cliente lê a chave da variável de ambiente ANTHROPIC_API_KEY, o que evita deixar o segredo escrito no código.

Os conceitos que você precisa entender

• Modelo: você escolhe qual usar a cada chamada. Modelos maiores raciocinam melhor e custam mais; os menores respondem rápido e mais barato. Veja Opus, Sonnet e Haiku.
• Tokens: unidade de leitura e escrita. Custo e limite de tamanho são medidos nela.
• Prompt de sistema: instruções gerais sobre papel, tom e regras, enviadas separadas das mensagens do usuário.
• Janela de contexto: quanto texto cabe numa chamada, somando entrada e saída. Detalhes em janela de contexto do Claude.
• Temperatura e outros parâmetros: controlam variação nas respostas. Para tarefas de extração, prefira respostas mais estáveis.
• Ferramentas (tool use): o modelo pode pedir que seu programa execute funções, como consultar um banco de dados, e continuar a partir do resultado. É a base dos agentes; leia agentes de IA.

Custos sem surpresa

O preço da API é por milhão de tokens, separado para entrada e saída, e muda por modelo. Como tabelas de preço e modelos mudam, consulte a página oficial de preços na hora de planejar. Algumas práticas simples:

1. Defina limite de gastos no Console antes dos testes.
2. Comece pequeno: teste com 10 casos antes de rodar 10 mil.
3. Escolha o modelo mais barato que resolve a tarefa, validando a qualidade com uma amostra.
4. Controle o tamanho da entrada: enviar o documento inteiro quando só um trecho importa custa mais.
5. Registre o consumo por tarefa para saber o custo por item processado.

Existem recursos de economia, como reaproveitar partes repetidas do prompt, mas confira na documentação como funcionam e em quais modelos estão disponíveis antes de contar com eles.

Segurança da chave e dos dados

• Nunca coloque a chave no código, em repositório público, em planilha ou em mensagem.
• Crie uma chave por projeto e revogue as que não usa mais.
• Não mande dados pessoais sem necessidade. Pense em LGPD desde o início; veja IA e LGPD e segurança e privacidade no Claude.
• Trate o texto que chega ao modelo como não confiável: e-mails e páginas podem conter instruções para manipular a resposta.

Prompts para a API são prompts de produto

Num app, você corrige o rumo na conversa seguinte. Numa API, o prompt roda sozinho, então precisa ser testado como qualquer componente. Defina formato de saída (por exemplo, JSON com campos fixos), diga o que fazer quando faltar informação e teste com casos difíceis. Para a base, leia engenharia de prompt.

Erros comuns nas primeiras semanas

Quem começa com a API costuma encontrar os mesmos problemas, e conhecê-los de antemão poupa tempo.

• Chave exposta. Subir o código para um repositório público com a chave dentro é o erro mais caro. Use variável de ambiente e arquivo de configuração ignorado pelo controle de versão.
• Resposta cortada. Se o limite de tokens de saída for baixo, o texto termina no meio. Aumente o limite ou peça respostas mais curtas.
• Formato imprevisível. Quando você precisa de dados estruturados, descreva o formato exato na instrução e valide a saída no código antes de gravar em qualquer lugar.
• Teste só com casos fáceis. Inclua entradas vazias, muito longas, em outro idioma e com erros de digitação.
• Falta de tratamento de falhas. Chamadas podem falhar por limite de uso ou instabilidade. Os SDKs oficiais incluem tentativas automáticas, mas seu programa também precisa decidir o que fazer quando não houver resposta.
• Custo sem monitoramento. Um laço de repetição com erro pode gerar milhares de chamadas. Limite de gastos e alertas no Console são a rede de proteção.

Documente também o que cada chamada faz, qual versão do prompt usa e quem é o responsável. Quando a resposta do modelo muda por uma atualização, esse registro permite comparar antes e depois e decidir se vale ajustar a instrução.

API ou ferramenta sem código

Nem toda automação exige escrever programas. Ferramentas visuais fazem a chamada à API por você, e isso costuma bastar para começar. Escreva código quando precisar de lógica própria, de integração com um sistema interno ou de controle fino sobre custo e erros. Se tiver dúvida, comece pela ferramenta visual, prove o valor com uma tarefa real e só migre para código quando a limitação aparecer.

Por onde começar

Faça a primeira chamada com a pergunta mais simples possível e confira o consumo no Console. Depois escolha uma tarefa pequena e repetitiva, como classificar 20 mensagens, rode em amostra e compare com a classificação humana. Se você prefere começar sem programar, o curso de Claude e IA presencial trabalha automação com n8n e agentes justamente para quem não escreve código.

Perguntas frequentes