Como usar a API da Anthropic pela primeira vez
Para usar a API da Anthropic pela primeira vez, crie conta no Console da Anthropic, gere uma chave, instale o SDK oficial em Python ou TypeScript e chame o endpoint messages com model, max_tokens e messages. O system prompt fica em campo separado, e o streaming usa eventos enviados um a um pelo servidor.
Monte o seu agente e veja ele respondendo com as informações do seu negócio.
Criar meu agente de graça Montar é livre, sem cadastro e sem cartão.O que você vai encontrar neste artigo
Em resumo
- Crie a chave no Console da Anthropic e instale o SDK Python ou TypeScript.
- Chame o endpoint messages com model, max_tokens, messages e, se quiser, system.
- Ative stream para receber a resposta aos poucos em vez de esperar o texto todo.
Como criar uma chave da API da Anthropic
A primeira etapa é criar uma conta no Console da Anthropic, o painel onde você gerencia chaves e cobrança. Sem essa chave, nenhuma chamada funciona.
- Crie uma conta em console.anthropic.com e confirme o e-mail.
- Entre na seção de billing e adicione um método de pagamento com crédito.
- Vá em API Keys e gere uma nova chave.
- Copie a chave e guarde em uma variável de ambiente, nunca dentro do código.
Nunca coloque a chave direto no código nem suba ela para o Git. Use um arquivo .env e adicione ele ao .gitignore.
Como fazer a primeira chamada à API da Anthropic
O endpoint principal é o /v1/messages. Ele pede três campos: model (qual modelo Claude vai responder), max_tokens (limite de tokens da resposta) e messages (lista de mensagens trocadas até agora, cada uma com role user ou assistant).
- model define a versão do Claude, por exemplo um modelo Haiku, Sonnet ou Opus.
- max_tokens é obrigatório na Anthropic. Quem vem da OpenAI costuma esquecer disso.
- messages é sempre uma lista, mesmo com uma única pergunta do usuário.
Instale o SDK oficial com pip install anthropic em Python ou npm install @anthropic-ai/sdk em Node. O SDK monta a chamada HTTP e trata erros comuns por você.
Como funciona o system prompt na API da Anthropic
Na Anthropic, o system prompt é um campo separado, chamado system, fora da lista de messages. Ele define o comportamento do modelo antes de qualquer troca com o usuário.
System e messages são a mesma coisa?
Não. Na OpenAI, o system entra como uma mensagem dentro do array. Na Anthropic, ele fica no topo da chamada, ao lado de model e max_tokens.
Essa separação também importa para o cache de prompt (prompt caching): um system prompt grande e fixo pode ser reaproveitado entre chamadas, reduzindo o custo de repetir o mesmo texto toda vez.
Como usar streaming na API da Anthropic
Com stream=true, a resposta chega aos poucos, em eventos, em vez de vir tudo de uma vez no final. O modelo manda pedaços como message_start, vários content_block_delta e por fim message_stop.
Isso é o que faz o texto aparecer palavra por palavra numa interface de chat. O usuário vê a resposta nascendo, em vez de olhar para uma tela parada esperando o texto todo.
O SDK oficial já entrega um iterador pronto para o streaming. Na maioria dos casos você não precisa entender o formato bruto dos eventos, só percorrer o iterador.
Quais são os erros mais comuns de quem está começando
| Erro | Causa provável |
|---|---|
| 401 Unauthorized | Chave errada, expirada, ou não carregada como variável de ambiente |
| Erro dizendo que falta max_tokens | Esqueceu esse campo, que é obrigatório na Anthropic |
| Aviso de saldo baixo | Conta sem crédito ativo na seção de billing do Console |
| System prompt parece ignorado | O texto do sistema foi colocado dentro de messages, em vez do campo system |
| Erro de limite de requisições | Chamadas por minuto passaram do limite do plano |
Os dois erros mais comuns são justamente o 401 e o max_tokens ausente. Ambos aparecem em quem migra da API da OpenAI e assume que o comportamento é idêntico.
Quanto custa usar a API da Anthropic
O custo é cobrado por token, e varia de acordo com o modelo escolhido: modelos menores como um da linha Haiku custam menos por token do que os maiores, como Sonnet ou Opus. Consulte a página de preços oficial da Anthropic antes de escolher o modelo do projeto.
Se o system prompt for grande e repetir em quase toda chamada, veja também a documentação sobre prompt caching. Ela pode cortar boa parte do custo de reenviar o mesmo texto de sistema.
Para testar e prototipar, comece com o modelo mais barato da linha. Suba para um modelo maior só quando notar que a qualidade da resposta não é suficiente para o seu caso.
Leia também
Perguntas frequentes
- Preciso de cartão de crédito para testar a API da Anthropic?
- Sim. Em geral é preciso cadastrar um método de pagamento e ter crédito ativo no Console antes de fazer qualquer chamada.
- Qual SDK devo usar, Python ou TypeScript?
- Os dois são mantidos oficialmente pela Anthropic. Use o mesmo idioma do resto do seu projeto.
- A API da Anthropic segue os mesmos parâmetros da API da OpenAI?
- Não totalmente. Na Anthropic, max_tokens é obrigatório e o system prompt fica em campo separado, fora da lista de messages.
- Como uso o streaming da API da Anthropic num site?
- Chame a API com stream ativado no seu servidor e repasse os pedaços de texto para o navegador, por exemplo com WebSocket ou eventos enviados pelo servidor.
