La API de Claude sin miedo: tu primera llamada

En la app de Claude escribes, lees y copias. Es cómodo, pero todo pasa por tus manos. Cuando quieres que Claude trabaje dentro de un programa (que clasifique cien correos de proveedores, que resuma cada noche un log de interfaces, que alimente un agente como los de la lección anterior), necesitas la API.

La API de Claude impone más de lo que es. En el fondo es una sola petición: le mandas un mensaje por HTTP y te devuelve la respuesta en JSON. En esta lección vas a hacer esa petición, entender cada línea y saber cuánto cuesta antes de que llegue la factura.

Antes de la primera llamada: cuenta y clave

La API se gestiona desde la Claude Console, en platform.claude.com. Es un sitio distinto de la app de chat y se paga aparte, por uso: tu plan Pro o Team no incluye llamadas a la API.

Una clave de API es una credencial con dinero detrás: quien la tenga puede gastar a tu cuenta. Trátala como una contraseña de producción. Para trabajo compartido (un proceso en un servidor, un pipeline), la Console ofrece claves de service account, que no dependen de una persona concreta.

Qué modelo pedir y cuánto cuesta

La API cobra por tokens, los trocitos de texto en que el modelo parte lo que lee y escribe (en español, un token viene a ser una sílaba larga o una palabra corta). Hay un precio para lo que envías (entrada) y otro, más alto, para lo que Claude genera (salida). Estos son los modelos actuales, con precios a fecha de septiembre de 2026:

La regla que usamos en SaetaIA: Opus 5.5 para empezar, Fable 5.1 cuando lo difícil de verdad lo pide, Sonnet 5.5 para velocidad con calidad y Haiku 4.5 para volumen y coste. Los precios actualizados, siempre en la página oficial de precios.

Una cuenta rápida para perderle el miedo. Mandas a Opus 5.5 un extracto de pedidos pendientes que ocupa unos 1.250 tokens y recibes un análisis de 250 tokens:

• Entrada: 1.250 × 4 $ / 1.000.000 = 0,005 $
• Salida: 250 × 20 $ / 1.000.000 = 0,005 $
• Total: un céntimo de dólar. Con Haiku 4.5, la misma llamada costaría una cuarta parte.

El coste no asusta en una llamada; asusta en cien mil. Por eso importa elegir bien el modelo y conocer los ahorros que verás al final.

Tu primera llamada, línea a línea

Esta es la llamada mínima, tal como la da la documentación oficial, con la pregunta cambiada:

export ANTHROPIC_API_KEY="tu-clave"

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1000,
    "messages": [
      { "role": "user", "content": "Explica en tres frases qué es un pedido de compra en SAP." }
    ]
  }'

Qué hace cada parte:

• https://api.anthropic.com/v1/messages: la Messages API, la puerta única para hablar con Claude.
• x-api-key: tu clave, leída de la variable de entorno. Así no queda escrita en ningún sitio.
• anthropic-version: la versión de la API que esperas. Se pone tal cual.
• model: el ID exacto del modelo. Un ID mal escrito da error, no un modelo parecido.
• max_tokens: el tope de tokens que Claude puede generar. Es un límite de seguridad, no un objetivo.
• messages: la conversación. Cada mensaje tiene un role (user o assistant) y un content. La API no recuerda nada entre llamadas: si quieres seguir una conversación, reenvías los mensajes anteriores.

La respuesta es un JSON con el texto en content, el motivo por el que paró en stop_reason (end_turn si terminó con normalidad) y, muy útil, el consumo en usage: input_tokens y output_tokens. Con esos dos números calculas el coste exacto de cada llamada.

Lo mismo en Python, con el SDK oficial:

# Entorno virtual y SDK oficial de Anthropic
$ python3 -m venv .venv && source .venv/bin/activate
$ pip install anthropic
$ export ANTHROPIC_API_KEY=tu-clave
$ python primera_llamada.py
Un pedido de compra es el documento con el que la empresa pide formalmente material o servicios a un proveedor…
# Tokens: entrada y salida, para vigilar el coste

Y el fichero primera_llamada.py:

import anthropic

client = anthropic.Anthropic()  # lee ANTHROPIC_API_KEY del entorno

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

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

print("Tokens:", message.usage.input_tokens, "entrada /", message.usage.output_tokens, "salida")

Hay SDK oficiales para Python, TypeScript, Java, Go, C#, Ruby y PHP; todos hacen por debajo la misma petición que el curl.

Tres ajustes que ahorran dinero (y uno que abre la puerta a los agentes)

Cuando pases de probar a automatizar, estos son los mandos que más cambian la factura:

Y la cuarta pieza, en una línea: con tool use le describes a Claude herramientas (con un esquema JSON), Claude te pide usarlas cuando las necesita, tu código las ejecuta y le devuelve el resultado. Es exactamente el bucle agéntico de la lección 7, construido a mano sobre esta misma API.

Cuando tengas esto dominado, la guía de primeros pasos de la API y la de effort son las dos siguientes lecturas naturales.

Próxima lección: Claude y ABAP. Cómo usar Claude para entender código heredado, refactorizarlo sin sustos y escribir sus tests.