Tu primera llamada a la API de Claude en Python

En unos 15 minutos vas a tener un script de Python que habla con Claude a través de la API, con tu clave bien guardada, un tope de gasto puesto y la costumbre de mirar cuántos tokens consume cada llamada. Es el punto de partida de cualquier integración: un informe que se resume solo, un asistente interno o un proceso que lee exports de SAP.

Si antes quieres entender qué es un token o en qué se diferencia la API del chat, repasa la lección La API de Claude sin miedo. Aquí vamos directos al teclado.

Antes de empezar

• Python 3.10 o superior (es lo que exige hoy el SDK oficial).
• Una terminal y un editor de texto.
• Una tarjeta para cargar saldo en la Claude Console: la API se paga por uso, aparte de cualquier plan de claude.ai.
• Diez minutos sin prisas para leer los mensajes de error si algo sale mal.

1. Cuenta, clave y límite de gasto

Todo empieza en la Claude Console. Crea una cuenta o entra con la que tengas, y sigue estos pasos:

El límite de gasto no es opcional en la práctica: es tu red de seguridad si un bucle se desboca. Cuando se alcanza, la API responde con un error 400 que empieza por «You have reached your specified API usage limits» y te dice cuándo se reanuda el acceso.

2. Prepara el proyecto e instala el SDK

La clave nunca va dentro del código. El SDK la lee sola de la variable de entorno ANTHROPIC_API_KEY:

# Guarda la clave en una variable de entorno (sustituye por la tuya)
$ export ANTHROPIC_API_KEY=«sk-ant-api03-...»
# Carpeta del proyecto y entorno virtual
$ mkdir claude-quickstart && cd claude-quickstart
$ python3 -m venv .venv && source .venv/bin/activate
$ pip install anthropic
Successfully installed anthropic-...

3. La llamada mínima

Crea un archivo primera.py con esto:

import anthropic

client = anthropic.Anthropic()  # lee ANTHROPIC_API_KEY

message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1000,
    messages=[
        {"role": "user", "content": "Explícame en tres frases qué es un pedido de compra en SAP."}
    ],
)

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

print(message.usage)

Y ejecútalo con python primera.py. Tres detalles que conviene entender desde el primer día:

• model: claude-opus-5-5 es el modelo recomendado para empezar. Es un ID fijo, sin fecha.
• max_tokens: es un tope duro de salida. En Opus 5.5 el pensamiento adaptativo está siempre activo, y ese pensamiento cuenta dentro de max_tokens. Si lo pones muy bajo, la respuesta se corta.
• El bucle por tipo de bloque: la respuesta puede empezar con bloques thinking antes del texto. Por eso se recorre message.content y se imprime solo lo que es text. El típico message.content[0].text que verás en tutoriales antiguos falla con los modelos actuales.

4. Lee usage: ahí está tu factura

La última línea imprime algo parecido a Usage(input_tokens=..., output_tokens=..., cache_read_input_tokens=0, ...). Esos números son lo que pagas:

• input_tokens: lo que enviaste (tu pregunta, el prompt de sistema, el historial).
• output_tokens: lo que generó Claude, incluido el pensamiento, aunque no veas su texto.

Con los precios de Opus 5.5 a fecha de septiembre de 2026 (4 $ por millón de tokens de entrada y 20 $ por millón de salida), una llamada con 30 tokens de entrada y 400 de salida cuesta unos 0,008 $. Calcula siempre con usage, no a ojo.

Si algo falla

El SDK lanza excepciones con tipo propio. Estas son las que más verás al empezar:

• AuthenticationError (401): la clave está mal copiada, revocada o caducada, o la variable de entorno no está cargada en esa terminal. Comprueba con echo $ANTHROPIC_API_KEY que existe.
• BadRequestError (400): petición mal formada (un parámetro que el modelo no acepta, por ejemplo temperature en Opus 5.5) o has llegado a tu límite de gasto. Lee el mensaje: dice exactamente qué campo sobra.
• Error de facturación (402, billing_error): hay un problema con el pago o los datos de facturación. Revisa Settings → Billing.
• RateLimitError (429) o sobrecarga (529): demasiadas peticiones o la API está saturada. El SDK ya reintenta dos veces con espera exponencial; si persiste, baja el ritmo o usa max_retries para ajustarlo.

Para capturarlas sin mirar el texto del mensaje, usa las clases: except anthropic.RateLimitError: antes que except anthropic.APIStatusError:, siempre de lo más concreto a lo más general. La lista completa está en la página de errores de la API.