Noções Básicas da API de Mensagens

7 exemplos para você começar com a API de Mensagens - 5 básicos e 2 intermediários.

Pré-requisitos

• Instale o SDK oficial: pip install anthropic.
• Defina uma chave de API em seu ambiente: export ANTHROPIC_API_KEY=sk-ant-... (ou construa anthropic.Anthropic(api_key=...) diretamente).
• Todos os exemplos usam claude-opus-4-8; troque por claude-sonnet-5 ou claude-haiku-4-5 se quiser um equilíbrio diferente entre velocidade e custo.

Exemplos Básicos

1. Uma Solicitação de Volta Única

A menor chamada possível: uma mensagem do usuário, sem histórico.

import anthropic
 
client = anthropic.Anthropic()
 
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Qual é a capital da França?"},
    ],
)
 
print(response.content[0].text)

• max_tokens é obrigatório em todas as solicitações e limita o comprimento da resposta do Claude.
• response.content é uma lista de blocos de conteúdo; para uma resposta de texto simples, o primeiro bloco .text contém a resposta.
• Nenhum prompt system é necessário - é opcional, não obrigatório.

2. Adicionando um Prompt do Sistema

O parâmetro system fica fora de messages e molda o tom, a persona ou as restrições para toda a conversa.

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    system="Você é um assistente conciso. Responda em uma frase.",
    messages=[
        {"role": "user", "content": "Por que o céu é azul?"},
    ],
)
 
print(response.content[0].text)

• system é um parâmetro de solicitação de nível superior, não uma mensagem com uma função.
• Ele se aplica a todas as voltas da conversa, não apenas à primeira.
• Mantenha-o estável entre as solicitações na mesma conversa - alterá-lo no meio da conversa afeta tanto o comportamento quanto o cache do prompt.

3. Uma Solicitação de Várias Voltas

Continue uma conversa incluindo a resposta anterior do Claude como uma volta de assistant antes da sua próxima pergunta.

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Qual é a capital da França?"},
        {"role": "assistant", "content": "A capital da França é Paris."},
        {"role": "user", "content": "Qual é a sua população?"},
    ],
)
 
print(response.content[0].text)

• As funções devem alternar estritamente user, assistant, user - a API rejeita solicitações que quebram esse padrão.
• A API é sem estado: Claude só sabe sobre "Paris" aqui porque está presente no histórico enviado, não porque se lembra da chamada anterior.
• Na prática, você constrói essa matriz programaticamente adicionando cada resposta antes da próxima solicitação, em vez de codificá-la diretamente.

4. Lendo o Objeto de Resposta

O objeto Message completo carrega mais do que apenas o texto da resposta - inspecione-o para construir aplicativos confiáveis.

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Nomeie três linguagens de programação."}],
)
 
print(response.stop_reason)     # por que a geração parou, por exemplo, "end_turn"
print(response.usage.input_tokens, response.usage.output_tokens)
print(response.model)           # o modelo que realmente atendeu à resposta

• stop_reason informa se o Claude terminou naturalmente (end_turn), atingiu o limite de tokens (max_tokens) ou parou por outro motivo.
• usage relata as contagens de tokens para a entrada e a saída gerada, que é pelo que você é cobrado.
• Sempre verifique stop_reason antes de confiar que response.content está completo - uma parada por max_tokens significa que a resposta foi cortada.

5. Lidando com Erros

Problemas de rede, limites de taxa e solicitações incorretas levantam exceções tipadas - capture-as explicitamente em vez de adivinhar a partir de um Exception genérico.

import anthropic
 
client = anthropic.Anthropic()
 
try:
    response = client.messages.create(
        model="claude-opus-4-8",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Olá, Claude"}],
    )
except anthropic.RateLimitError:
    print("Limite de taxa excedido - aguarde e tente novamente")
except anthropic.APIStatusError as e:
    print(f"Erro da API {e.status_code}: {e.message}")

• O SDK expõe uma classe de exceção distinta para cada status HTTP (RateLimitError, NotFoundError, AuthenticationError, etc.).
• Capture a exceção mais específica primeiro, depois retorne para APIStatusError para qualquer outra coisa.
• O SDK já tenta novamente respostas 429 e 5xx automaticamente com backoff, portanto, um RateLimitError capturado significa que as tentativas foram esgotadas.

Exemplos Intermediários

6. Construindo a Matriz de Mensagens em um Loop

A maioria das aplicações reais não codifica a conversa - elas adicionam a uma lista e a reenviam em cada volta.

import anthropic
 
client = anthropic.Anthropic()
messages = []
 
def ask(user_text: str) -> str:
    messages.append({"role": "user", "content": user_text})
 
    response = client.messages.create(
        model="claude-opus-4-8",
        max_tokens=1024,
        system="Você é um assistente prestativo que se lembra do contexto dentro deste chat.",
        messages=messages,
    )
 
    reply_text = response.content[0].text
    messages.append({"role": "assistant", "content": response.content})
    return reply_text
 
print(ask("Minha cor favorita é azul-petróleo."))
print(ask("Qual é a minha cor favorita?"))

• Adicione o response.content completo (não apenas o texto extraído) como a volta do assistente, para que quaisquer blocos não textuais sejam preservados para voltas posteriores.
• messages cresce em duas entradas por troca: sua nova volta user e a resposta assistant do Claude.
• Este é o padrão em que todas as interfaces de chat com várias voltas são construídas, seja um loop CLI ou um backend web.

7. Transmitindo uma Resposta

Para respostas mais longas, transmita tokens à medida que são gerados em vez de esperar pela resposta completa.

import anthropic
 
client = anthropic.Anthropic()
 
with client.messages.stream(
    model="claude-opus-4-8",
    max_tokens=2048,
    messages=[{"role": "user", "content": "Escreva um poema curto sobre o oceano."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
 
    final_message = stream.get_final_message()
    print("\n\nRazão da parada:", final_message.stop_reason)

• client.messages.stream() retorna um gerenciador de contexto; stream.text_stream produz blocos de texto incrementais à medida que chegam.
• Chame stream.get_final_message() após o loop para obter o objeto Message completo, incluindo usage e stop_reason.
• A transmissão é recomendada para qualquer solicitação onde max_tokens seja grande, pois solicitações não transmissíveis correm o risco de atingir tempos limite HTTP do lado do cliente.

Relacionado: Entendendo Funções e Voltas na API de Mensagens - o modelo conceitual por trás desses exemplos | Construindo Conversas de Várias Voltas com a Matriz de Mensagens - uma análise mais aprofundada do gerenciamento de estado da conversa

Versões da pilha: Escrito contra a linha de modelos Claude atual em aproximadamente 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.