Noções Básicas da API Claude

9 exemplos para você começar com os Fundamentos da API Claude - 6 básicos e 3 intermediários.

Pré-requisitos

• Instale o SDK oficial: pip install anthropic.
• Defina sua chave de API como uma variável de ambiente: export ANTHROPIC_API_KEY="sk-ant-...".
• Python 3.8 ou mais recente.

Exemplos Básicos

1. Sua Primeira Mensagem

A menor chamada possível para a API de Mensagens: um modelo, um prompt, uma resposta.

import anthropic
 
client = anthropic.Anthropic()  # lê ANTHROPIC_API_KEY do ambiente
 
response = client.messages.create(
    model="claude-sonnet-5-20260630",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Diga olá em uma frase."}],
)
 
print(response.content[0].text)

• model e max_tokens são os únicos dois parâmetros obrigatórios em todas as chamadas.
• messages é uma lista de turnos; um único turno do usuário é suficiente para um prompt único.
• O texto da resposta está em response.content[0].text, não diretamente em response.

Relacionado: Instalando e Configurando o SDK Python da Anthropic - guia completo de configuração.

2. Lendo o Objeto de Resposta Completo

A resposta carrega mais do que apenas texto, ela também informa como a geração terminou e quantos tokens foram usados.

import anthropic
 
client = anthropic.Anthropic()
 
response = client.messages.create(
    model="claude-sonnet-5-20260630",
    max_tokens=256,
    messages=[{"role": "user", "content": "Nomeie três números primos."}],
)
 
print("Texto:", response.content[0].text)
print("Razão de parada:", response.stop_reason)
print("Tokens de entrada:", response.usage.input_tokens)
print("Tokens de saída:", response.usage.output_tokens)

• stop_reason informa por que a geração parou, comumente "end_turn" ou "max_tokens".
• usage.input_tokens e usage.output_tokens são pelos quais você é cobrado.
• Uma stop_reason de "max_tokens" significa que a resposta foi cortada; aumente max_tokens se precisar de mais.

3. Controlando max_tokens

max_tokens é um limite rígido para o quanto o Claude pode gerar, não um comprimento alvo.

import anthropic
 
client = anthropic.Anthropic()
 
response = client.messages.create(
    model="claude-haiku-4-5-20260601",
    max_tokens=50,
    messages=[{"role": "user", "content": "Explique a fotossíntese."}],
)
 
print(response.content[0].text)
print(response.stop_reason)  # provavelmente "max_tokens" - a explicação foi cortada

• A geração para no momento em que max_tokens é atingido, no meio da frase, se necessário.
• Defina max_tokens generosamente para tarefas com comprimento de saída imprevisível, como resumos ou código.
• Um max_tokens muito baixo é uma fonte comum de respostas truncadas e inutilizáveis.

4. Ajustando a temperatura para Aleatoriedade

temperature controla o quão determinística ou variada é a saída.

import anthropic
 
client = anthropic.Anthropic()
 
response = client.messages.create(
    model="claude-sonnet-5-20260630",
    max_tokens=100,
    temperature=0.0,  # quase determinístico, bom para tarefas factuais/estruturadas
    messages=[{"role": "user", "content": "Qual é a capital do Japão?"}],
)
 
print(response.content[0].text)

• temperature mais baixa (próxima de 0) fornece respostas consistentes e repetíveis, melhor para fatos, classificação e código.
• temperature mais alta (próxima de 1) fornece frases mais variadas e criativas, melhor para brainstorming.
• temperature e top_p afetam a aleatoriedade; a maioria das chamadas só precisa ajustar um deles.

5. Usando um Prompt do Sistema

Um parâmetro system define instruções persistentes que se aplicam a toda a conversa.

import anthropic
 
client = anthropic.Anthropic()
 
response = client.messages.create(
    model="claude-sonnet-5-20260630",
    max_tokens=200,
    system="Você é um revisor de código conciso. Responda apenas em bullet points.",
    messages=[{"role": "user", "content": "Revise esta função: def add(a,b): return a+b"}],
)
 
print(response.content[0].text)

• system é um parâmetro de nível superior, separado da lista messages.
• Ele molda o tom, o papel e as restrições sem consumir um "turno" na conversa.
• Mantenha os prompts do sistema focados; prompts de sistema longos e vagos enfraquecem o seguimento de instruções.

6. Lidando com um Erro Básico

Envolva as chamadas em um try/except para lidar com requisições inválidas ou problemas de autenticação de forma graciosa.

import anthropic
 
client = anthropic.Anthropic()
 
try:
    response = client.messages.create(
        model="claude-sonnet-5-20260630",
        max_tokens=100,
        messages=[{"role": "user", "content": "Olá!"}],
    )
    print(response.content[0].text)
except anthropic.AuthenticationError:
    print("Verifique se ANTHROPIC_API_KEY está definida corretamente.")
except anthropic.APIStatusError as e:
    print(f"A API retornou um erro: {e.status_code} - {e.message}")

• anthropic.AuthenticationError cobre especificamente problemas de chave 401.
• anthropic.APIStatusError é a classe base para outras respostas não-2xx, útil como um "catch-all".
• Capturar tipos de exceção específicos é melhor do que capturar Exception genérico, pois informa o que realmente deu errado.

Relacionado: Referência de Códigos de Erro e Solução de Problemas da API Claude - catálogo completo de erros.

Exemplos Intermediários

7. Uma Conversa Multi-Turno

Como a API é sem estado, você reenvia os turnos anteriores para manter o contexto.

import anthropic
 
client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Minha cor favorita é azul-petróleo."}]
 
first = client.messages.create(
    model="claude-sonnet-5-20260630",
    max_tokens=100,
    messages=messages,
)
print("Claude:", first.content[0].text)
 
# Anexe a resposta do Claude, depois o próximo turno do usuário, antes de chamar novamente.
messages.append({"role": "assistant", "content": first.content[0].text})
messages.append({"role": "user", "content": "Qual é a minha cor favorita?"})
 
second = client.messages.create(
    model="claude-sonnet-5-20260630",
    max_tokens=100,
    messages=messages,
)
print("Claude:", second.content[0].text)

• Cada chamada reenvia todo o histórico; não há sessão no lado do servidor para referência.
• Os papéis alternam entre "user" e "assistant"; a lista deve começar com um turno "user".
• Históricos mais longos significam mais tokens de entrada cobrados por chamada; este é um custo real, não apenas uma formalidade.

8. Combinando Prompt do Sistema, temperature e top_p

Aplicações reais geralmente ajustam vários parâmetros juntos para uma tarefa específica.

import anthropic
 
client = anthropic.Anthropic()
 
response = client.messages.create(
    model="claude-opus-4-8-20260415",
    max_tokens=500,
    system="Você é um redator técnico preciso. Evite especulações.",
    temperature=0.2,
    top_p=0.9,
    messages=[{"role": "user", "content": "Esboce uma entrada de changelog de um parágrafo para uma nova opção de retentativa."}],
)
 
print(response.content[0].text)

• Uma temperature baixa combinada com um system prompt focado é adequada para tarefas de escrita precisas e de baixa variância.
• top_p restringe ainda mais o pool de amostragem; ajuste temperature ou top_p, geralmente não ambos agressivamente ao mesmo tempo.
• A escolha de claude-opus-4-8 aqui reflete uma tarefa que se beneficia de um raciocínio mais forte do que um modelo mais leve.

Relacionado: Selecionando um Modelo: Claude Fable 5, Opus 4.8, Sonnet 5 e Haiku 4.5 - como escolher entre os modelos.

9. Retentativa Básica em Limites de Taxa

max_retries no cliente lida automaticamente com erros transitórios 429/5xx com backoff.

import anthropic
 
client = anthropic.Anthropic(max_retries=3)  # tenta novamente 429s e 5xxs com backoff exponencial
 
response = client.messages.create(
    model="claude-haiku-4-5-20260601",
    max_tokens=200,
    messages=[{"role": "user", "content": "Resuma isto em uma frase: o céu é azul devido ao espalhamento de Rayleigh."}],
)
 
print(response.content[0].text)

• max_retries é uma opção construtora no nível do cliente, não um parâmetro por chamada.
• O SDK apenas retenta erros genuinamente transitórios (429, 5xx); ele não retenta erros de validação da classe 400.
• Escolher um modelo barato e rápido como claude-haiku-4-5 para resumos simples mantém o custo e a latência baixos.

Relacionado: Lidando com Limites de Taxa com Backoff Exponencial - estratégia de retentativa em profundidade.

Versões da pilha: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5 - e o SDK oficial anthropic para Python (última versão 0.x). Nomes de modelos, versões de SDK e preços mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.