Instalando e Configurando o SDK Python da Anthropic

O pacote Python oficial anthropic é a maneira recomendada de chamar a API Claude a partir do Python.

Ele lida com cabeçalhos de autenticação, serialização de requisições, novas tentativas e análise de respostas para que você não precise construir essa infraestrutura sozinho.

Esta página cobre a instalação, a configuração de um cliente e a realização da sua primeira chamada real.

Resumo

O pacote anthropic é instalado com um único comando pip install anthropic em qualquer ambiente Python 3.8+.

Uma instância de cliente, anthropic.Anthropic(), é o objeto que você configura uma vez e reutiliza para cada chamada em sua aplicação.

Por padrão, ele lê sua chave de API de ANTHROPIC_API_KEY, mas você pode substituir a chave, o tempo limite, o número de novas tentativas e até mesmo a URL base através de argumentos do construtor.

Existe também um cliente assíncrono, anthropic.AsyncAnthropic, com a mesma interface para uso dentro de aplicações asyncio.

Obter a configuração correta uma vez, em um só lugar, evita espalhar instâncias de cliente ad-hoc com configurações inconsistentes por uma base de código.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

pip install anthropic
export ANTHROPIC_API_KEY="sk-ant-..."

import anthropic
 
client = anthropic.Anthropic()
 
response = client.messages.create(
    model="claude-sonnet-5-20260630",
    max_tokens=200,
    messages=[{"role": "user", "content": "Confirme se o SDK está instalado corretamente."}],
)
print(response.content[0].text)

Quando usar isso:

• Iniciando qualquer novo projeto Python que chama o Claude.
• Você deseja novas tentativas automáticas, respostas tipadas e suporte a streaming sem escrever código HTTP bruto.
• Você está construindo um script síncrono ou um serviço baseado em asyncio (use AsyncAnthropic para este último).

Exemplo de Trabalho

import os
import anthropic
 
# Um ambiente virtual recomendado primeiro:
#   python -m venv .venv && source .venv/bin/activate
#   pip install anthropic
 
def build_client() -> anthropic.Anthropic:
    return anthropic.Anthropic(
        api_key=os.environ["ANTHROPIC_API_KEY"],
        timeout=30.0,       # segundos, por requisição
        max_retries=2,      # novas tentativas automáticas para respostas 429/5xx
    )
 
 
def main() -> None:
    client = build_client()
    response = client.messages.create(
        model="claude-sonnet-5-20260630",
        max_tokens=150,
        messages=[
            {"role": "user", "content": "Liste três usos para o SDK Python da Anthropic."}
        ],
    )
    print(response.content[0].text)
    print(f"Tokens usados: {response.usage.input_tokens} entrada / {response.usage.output_tokens} saída")
 
 
if __name__ == "__main__":
    main()

O que isso demonstra:

• Construir o cliente uma vez, em uma função dedicada, em vez de construí-lo inline onde quer que seja usado.
• Definir timeout e max_retries explícitos em vez de confiar nos padrões, o que é importante quando você passa de um teste rápido.
• Ler usage da resposta para rastrear o consumo de tokens junto com o texto gerado.

Mergulho Profundo

Como Funciona

• pip install anthropic baixa o pacote (e suas dependências HTTP) do PyPI; ele suporta Python 3.8 e versões mais recentes.
• Gerenciadores de pacotes como poetry add anthropic ou uv add anthropic funcionam de forma idêntica e são recomendados para projetos que fixam dependências.
• anthropic.Anthropic() é um cliente síncrono: client.messages.create(...) bloqueia até que a resposta (ou o stream completo) seja recebida.
• anthropic.AsyncAnthropic() espelha os mesmos nomes de métodos, mas retorna objetos awaitable, para uso dentro de funções async def.
• Cada cliente pode ser construído uma vez e reutilizado em muitas chamadas; não há necessidade de construir um novo cliente por requisição.

Opções Úteis do Construtor

O Cliente Assíncrono

import asyncio
import anthropic
 
async def main() -> None:
    client = anthropic.AsyncAnthropic()
    response = await client.messages.create(
        model="claude-haiku-4-5-20260601",
        max_tokens=100,
        messages=[{"role": "user", "content": "Diga olá assincronamente."}],
    )
    print(response.content[0].text)
 
asyncio.run(main())

Notas Python

# Reutilize uma instância de cliente em um módulo ou aplicativo em vez de
# construir uma nova a cada chamada de função - conexões e
# a configuração de retentativas são configuradas uma vez, no momento da importação ou inicialização.
import anthropic
 
client = anthropic.Anthropic()  # nível de módulo, criado uma vez
 
def summarize(text: str) -> str:
    response = client.messages.create(
        model="claude-haiku-4-5-20260601",
        max_tokens=200,
        messages=[{"role": "user", "content": f"Resuma: {text}"}],
    )
    return response.content[0].text

Armadilhas

• Instalar no Python do sistema em vez de um ambiente virtual. Isso causa conflitos de versão entre projetos não relacionados ao longo do tempo. Correção: crie um ambiente virtual (venv, poetry ou uv) por projeto antes de instalar.
• Construir um novo cliente em cada chamada de função. Isso é um desperdício e pode contornar a reutilização de conexões. Correção: construa o cliente uma vez, na inicialização do módulo ou do aplicativo, e passe-o ou reutilize uma instância em nível de módulo.
• Usar o cliente síncrono dentro de uma função async def. client.messages.create(...) bloqueia o loop de eventos durante a chamada síncrona dentro de código assíncrono. Correção: use anthropic.AsyncAnthropic com await dentro de funções assíncronas.
• Não fixar a versão do SDK em produção. Uma dependência anthropic não fixada pode introduzir alterações que quebram em uma nova instalação. Correção: fixe um intervalo de versão específico em requirements.txt ou no seu arquivo de lock, e atualize deliberadamente.
• Substituir base_url acidentalmente copiando a configuração de exemplo. Apontar para a URL errada causa erros de conexão confusos que parecem não relacionados à configuração. Correção: defina base_url apenas intencionalmente (por exemplo, para um proxy) e remova-o se copiado de um exemplo não relacionado.
• Assumir que timeout cobre toda a resposta em streaming. Para gerações longas em streaming, um timeout muito curto pode interromper um stream legítimo em andamento. Correção: defina um timeout mais longo para casos de uso de streaming ou use substituições de timeout por requisição.

Alternativas

FAQs

Relacionados

• Noções Básicas de Fundamentos da API Claude - suas primeiras chamadas de trabalho.
• Autenticando Chamadas da API Claude com o Cabeçalho x-api-key - configuração de chave em profundidade.
• Construindo um Wrapper Reutilizável para a API Claude - envolvendo o cliente com padrões para toda a aplicação.
• Tratando Limites de Taxa com Backoff Exponencial - o que max_retries faz nos bastidores.

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 (último lançamento 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.