API do Claude com Python: guia prático com o Claude Opus 5
Este tutorial mostra como usar a API do Claude em Python com o SDK oficial da Anthropic, do primeiro request até uma conversa com histórico. Todos os exemplos usam o Claude Opus 5 (claude-opus-5) e funcionam com a API da open33 trocando só a URL base e a chave.
Instalação
pip install anthropic
Configuração da chave e da URL
O SDK lê a chave e a URL base de variáveis de ambiente. Defina as duas antes de rodar o seu código:
export ANTHROPIC_BASE_URL="https://api.open33.tech"
export ANTHROPIC_API_KEY="SUA_CHAVE"
No Windows (PowerShell), use $env:ANTHROPIC_BASE_URL = "..." e $env:ANTHROPIC_API_KEY = "...".
Se preferir deixar explícito no código, passe a URL ao criar o cliente e mantenha a chave fora do código:
import os
import anthropic
client = anthropic.Anthropic(
base_url="https://api.open33.tech",
api_key=os.environ["ANTHROPIC_API_KEY"],
)
Não coloque a chave direto no código-fonte nem suba para o Git.
A primeira chamada
import anthropic
client = anthropic.Anthropic()
resposta = client.messages.create(
model="claude-opus-5",
max_tokens=16000,
messages=[
{"role": "user", "content": "Escreva uma função Python que valida CPF."}
],
)
for bloco in resposta.content:
if bloco.type == "text":
print(bloco.text)
print(resposta.usage) # tokens de entrada e de saída desta requisição
Três pontos importantes:
modelé o identificador do modelo:claude-opus-5.max_tokensé o teto de tokens da resposta. Se ele for baixo demais, a resposta é cortada no meio estop_reasonvem como"max_tokens".resposta.contenté uma lista de blocos. O Claude Opus 5 pode devolver outros blocos antes do texto, como os de raciocínio, então filtre pelos de tipotextem vez de ler sempre o primeiro.
Prompt de sistema
O prompt de sistema define o papel e as regras do assistente. Ele vai no parâmetro system, separado das mensagens:
resposta = client.messages.create(
model="claude-opus-5",
max_tokens=16000,
system="Você é um revisor de código sênior. Responda em português, de forma direta.",
messages=[{"role": "user", "content": "Revise: def soma(a,b): return a+b"}],
)
Conversa com histórico
A API não guarda o histórico: a cada chamada você envia a conversa inteira. Um jeito simples de organizar:
import anthropic
client = anthropic.Anthropic()
historico = []
def perguntar(texto: str) -> str:
historico.append({"role": "user", "content": texto})
resposta = client.messages.create(
model="claude-opus-5",
max_tokens=16000,
system="Você é um assistente de programação.",
messages=historico,
)
# guarda a resposta completa (todos os blocos) no histórico
historico.append({"role": "assistant", "content": resposta.content})
return "".join(b.text for b in resposta.content if b.type == "text")
print(perguntar("Meu nome é Ana e eu programo em Django."))
print(perguntar("Qual é o meu nome e qual framework eu uso?"))
Guardar resposta.content inteiro, e não só o texto, mantém no histórico todos os blocos que o modelo devolveu.
Tratando erros
O SDK já repete sozinho, por padrão duas vezes, os erros temporários: falhas de conexão, 429 e erros 5xx. Para os demais, trate as exceções da mais específica para a mais geral:
import anthropic
try:
resposta = client.messages.create(
model="claude-opus-5",
max_tokens=16000,
messages=[{"role": "user", "content": "Olá!"}],
)
except anthropic.AuthenticationError:
print("Chave inválida: confira ANTHROPIC_API_KEY.")
except anthropic.NotFoundError:
print("Endpoint ou modelo não encontrado: confira a URL base e o nome do modelo.")
except anthropic.RateLimitError:
print("Limite atingido (429): aguarde a próxima janela do plano.")
except anthropic.APIStatusError as e:
print(f"Erro da API ({e.status_code}): {e.message}")
except anthropic.APIConnectionError:
print("Falha de rede: confira sua conexão.")
O guia de erros da API do Claude explica cada código.
Próximos passos
- Mostrar a resposta enquanto ela é gerada: streaming.
- Deixar o Claude chamar funções do seu código: tool use.
- Gastar menos com prompts repetidos: cache de prompt.
- Receber a resposta em JSON, validada com Pydantic: respostas em JSON.
- Trazer um código que usa o SDK da OpenAI: migrar da OpenAI para o Claude.
Perguntas frequentes
Preciso mudar meu código para usar a open33?
Não. Basta apontar ANTHROPIC_BASE_URL para https://api.open33.tech e usar a sua chave em ANTHROPIC_API_KEY. O restante do código é o mesmo da documentação oficial.
Qual valor usar em max_tokens?
Para respostas comuns sem streaming, algo em torno de 16000 evita cortes. Para respostas muito longas, use streaming: o Claude Opus 5 aceita até 128 mil tokens de saída, e o SDK exige streaming para valores altos.
O SDK funciona com async?
Sim. Use anthropic.AsyncAnthropic() e await client.messages.create(...) dentro de uma função async.
Por que o texto não está em resposta.content[0]?
Porque a resposta pode ter mais de um bloco, e o primeiro nem sempre é o de texto. Filtre pelos blocos com type == "text".