SDK de Python da Anthropic: instale, defina base_url, use streaming e trate erros

O anthropic é o pacote do cliente Python oficial da Anthropic para a API do Claude. Ele cuida da autenticação, das novas tentativas, do streaming e dos erros tipados, e funciona sem alterações com qualquer endpoint compatível com a Anthropic: defina base_url (ou ANTHROPIC_BASE_URL) e o restante do seu código permanece igual.

Instalação

pip install anthropic

As versões 1.x são executadas em httpx2 e exigem Python 3.10 ou mais recente. Se você passar seu próprio cliente HTTP, use DefaultHttpxClient do SDK para manter os tempos limite e os limites de conexão padrão.

Crie um cliente

import anthropic

client = anthropic.Anthropic(
    api_key="your_key",   # default: ANTHROPIC_API_KEY
    base_url="https://aiprimetech.io",    # default: ANTHROPIC_BASE_URL, else https://api.anthropic.com
)

base_url é a raiz do host. O SDK acrescenta /v1/messages automaticamente, portanto https://aiprimetech.io/v1 produziria /v1/v1/messages e um campo 404 page not found. Com ambas as variáveis definidas no ambiente, anthropic.Anthropic() não precisa de nenhum argumento:

export ANTHROPIC_API_KEY=your_key
export ANTHROPIC_BASE_URL=https://aiprimetech.io

Envie uma mensagem

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Summarise TCP slow start in two sentences."}],
)

for block in message.content:
    if block.type == "text":
        print(block.text)

print(message.usage.input_tokens, message.usage.output_tokens)
print(message._request_id)   # log this with any failure report

content é uma lista de blocos (texto, raciocínio, uso de ferramentas), portanto verifique block.type em vez de ler content[0].text sem verificar.

Receba respostas por streaming

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Write a short story about a lighthouse."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    final = stream.get_final_message()

Use streaming sempre que houver uma entrada longa, uma saída longa ou um valor alto de max_tokens: uma única requisição sem streaming precisa terminar dentro do tempo limite; com streaming, isso não é necessário. messages.create(..., stream=True) fornece o iterador de eventos bruto caso você não precise do auxiliar.

Cliente assíncrono

import asyncio, anthropic

client = anthropic.AsyncAnthropic(base_url="https://aiprimetech.io")
limit = asyncio.Semaphore(3)   # stay within your key's concurrency

async def ask(question: str) -> str:
    async with limit:
        msg = await client.messages.create(
            model="claude-haiku-4-5",
            max_tokens=512,
            messages=[{"role": "user", "content": question}],
        )
        return next(b.text for b in msg.content if b.type == "text")

async def main():
    answers = await asyncio.gather(*(ask(q) for q in ["What is DNS?", "What is BGP?"]))
    print(answers)

asyncio.run(main())

O semáforo é importante. Disparar centenas de requisições de uma vez com asyncio.gather é a causa mais comum dos erros de Concurrency limit exceeded que observamos em clientes Python.

Tempos limite e novas tentativas

Valores padrão: tempo limite de 10 minutos por requisição e 2 novas tentativas automáticas com espera exponencial. O SDK repete requisições em caso de erros de conexão, 408, 409, 429 e respostas 5xx. Como as requisições que excedem o tempo limite também são repetidas, o tempo total decorrido no pior caso é o tempo limite multiplicado pelo número de tentativas.

client = anthropic.Anthropic(base_url="https://aiprimetech.io", timeout=60.0, max_retries=4)

# override for one call only
client.with_options(timeout=300.0).messages.create(
    model="claude-opus-5-5",
    max_tokens=4000,
    messages=[{"role": "user", "content": "Review this design doc..."}],
)

Tratamento de erros

try:
    message = client.messages.create(model="claude-sonnet-5", max_tokens=1024,
                                      messages=[{"role": "user", "content": "Hi"}])
except anthropic.NotFoundError as e:
    print("Bad model ID or URL:", e.message)
except anthropic.RateLimitError as e:
    print("Rate limited, retry after", e.response.headers.get("retry-after"))
except anthropic.APIStatusError as e:
    print(e.status_code, e.type, e.message)
except anthropic.APIConnectionError:
    print("Network problem")

Capture primeiro as classes específicas e APIStatusError por último; um único except genérico oculta a diferença entre erros que justificam uma nova tentativa e erros que exigem uma alteração no código. e.type fornece a string do tipo de erro da API, como rate_limit_error ou overloaded_error.

IDs dos modelos

client.models.list() retorna os modelos disponibilizados por um endpoint, para que você possa verificar um ID antes de usá-lo. Use os IDs exatamente como estão escritos: sem sufixos de data.

Solução de problemas em um gateway

Mais sobre erros do lado do modelo: o guia de erros da API do Claude.

Perguntas frequentes

AI Prime Tech é um gateway de API independente. Não tem afiliação com a Anthropic, não é endossado por ela e não é seu revendedor. Claude e os nomes dos modelos relacionados são marcas comerciais de seus respectivos proprietários.