SDK de Python de Anthropic: instalación, configuración de base_url, streaming y gestión de errores

El anthropic es el paquete del cliente oficial de Python de Anthropic para la API de Claude. Gestiona la autenticación, los reintentos, el streaming y los errores tipados, y funciona sin modificaciones con cualquier endpoint compatible con Anthropic: configura base_url (o ANTHROPIC_BASE_URL) y el resto de tu código permanece igual.

Instalación

pip install anthropic

Las versiones 1.x funcionan con httpx2 y requieren Python 3.10 o posterior. Si proporcionas tu propio cliente HTTP, usa DefaultHttpxClient del SDK para conservar sus tiempos de espera y límites de conexión predeterminados.

Crear un 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 es la raíz del host. El SDK añade /v1/messages automáticamente, por lo que https://aiprimetech.io/v1 produciría /v1/v1/messages y un 404 page not found. Con ambas variables definidas en el entorno, anthropic.Anthropic() no necesita ningún argumento:

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

Enviar un mensaje

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 es una lista de bloques (texto, razonamiento, uso de herramientas), así que comprueba block.type en lugar de leer content[0].text a ciegas.

Recibir respuestas en 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()

Usa streaming para cualquier solicitud con una entrada larga, una salida larga o un valor elevado de max_tokens: una solicitud sin streaming debe completarse dentro del tiempo de espera; una con streaming no. messages.create(..., stream=True) te proporciona el iterador de eventos sin procesar si no necesitas la función auxiliar.

Cliente así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())

El semáforo es importante. Lanzar cientos de solicitudes a la vez con asyncio.gather es la causa más habitual de los errores Concurrency limit exceeded que observamos en clientes de Python.

Tiempos de espera y reintentos

Valores predeterminados: un tiempo de espera de 10 minutos por solicitud y 2 reintentos automáticos con espera exponencial. El SDK reintenta los errores de conexión, 408, 409, 429 y las respuestas 5xx. Como también se reintentan las solicitudes cuyo tiempo de espera se agota, el tiempo total transcurrido en el peor caso es el tiempo de espera multiplicado por el número de intentos.

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..."}],
)

Gestión de errores

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")

Captura primero las clases específicas y APIStatusError al final; una captura genérica con except oculta la diferencia entre los errores que conviene reintentar y los que requieren un cambio en el código. e.type proporciona la cadena del tipo de error de la API, como rate_limit_error o overloaded_error.

ID de modelos

client.models.list() devuelve los modelos que ofrece un endpoint, para que puedas comprobar un ID antes de usarlo. Usa los ID exactamente como aparecen: sin sufijos de fecha.

Resolución de problemas en una pasarela

Más información sobre los errores del modelo: la guía de errores de la API de Claude.

Preguntas frecuentes

AI Prime Tech es una pasarela de API independiente. No está afiliada a Anthropic, no cuenta con su respaldo ni es un distribuidor de Anthropic. Claude y los nombres de los modelos relacionados son marcas comerciales de sus respectivos propietarios.