Qué es la API de Claude y cuándo usarla en lugar de claude.ai

La API de Claude es la API REST de Anthropic, con base en https://api.anthropic.com. Consigues tu key en la Console, la guardas como ANTHROPIC_API_KEY y haces un POST a /v1/messages con tres headers (x-api-key, anthropic-version, content-type) enviando model, max_tokens y messages. Los SDK oficiales de Python y TypeScript la envuelven y manejan headers, reintentos y streaming por ti.

La diferencia con claude.ai es de propósito. claude.ai es el chat para humanos: abres el navegador, escribes y lees. La API es para tu código: tu backend, un cron, un worker que procesa miles de documentos sin que nadie esté frente a la pantalla. Si quieres meter a Claude dentro de un producto —clasificar tickets, extraer datos de un PDF, responder un webhook— necesitas la API. Si solo quieres platicar o iterar un prompt a mano, usa el chat. Una regla práctica: en cuanto la palabra “automático” aparece en el requerimiento, es API.

Consigue tu API key en la Console y guárdala como variable de entorno

Entra a la Console en platform.claude.com, ve a Account Settings y luego a API Keys. Antes de escribir código, prueba tu prompt en el Workbench del navegador: ahí ves la respuesta y el conteo de tokens sin gastar una línea de código. Cuando el prompt funcione, genera la key.

La key es un secreto. Nunca la pongas en el código ni la subas a git. Guárdala en una variable de entorno:

export ANTHROPIC_API_KEY="sk-ant-..."

Para producción usa el gestor de secretos de tu plataforma (Vault, AWS Secrets Manager, las env vars del proveedor) y nunca la imprimas en logs. Los SDK leen ANTHROPIC_API_KEY automáticamente, así que con exportarla ya está.

Crea la keyConsole, Account Settings, API Keys
Prueba en WorkbenchItera el prompt en el navegador antes de codear
Exporta la env varANTHROPIC_API_KEY, nunca en git
POST a /v1/messagesTres headers y el body con model, max_tokens y messages

Tu primera llamada: la petición curl cruda

Antes de tocar un SDK, vale la pena ver la petición desnuda. Así entiendes exactamente qué hace el SDK por debajo. Son tres headers obligatorios en cada request: x-api-key con tu key, anthropic-version con 2023-06-01, y content-type en application/json. El body lleva model, max_tokens y messages.

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-sonnet-5",
    "max_tokens": 1000,
    "messages": [
      {
        "role": "user",
        "content": "Dame tres ideas para nombrar un microservicio de facturacion."
      }
    ]
  }'

El header anthropic-version fija el contrato de la API: con 2023-06-01 te aseguras de que la forma de la respuesta no cambie debajo de tus pies cuando Anthropic publique versiones nuevas. Es obligatorio, no lo omitas. Si tu key es inválida obtienes un 401; si te falta un campo del body, un 400 con un mensaje claro de qué falló.

La misma llamada en Python y TypeScript

En producción no usas curl, usas un SDK. Hacen lo mismo —arman esos tres headers, mandan el body— pero además te dan reintentos con backoff, tipos y helpers de streaming. Instala anthropic para Python o @anthropic-ai/sdk para TypeScript. Ambos leen ANTHROPIC_API_KEY del entorno solos.

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1000,
    messages=[
        {"role": "user", "content": "Dame tres ideas para nombrar un microservicio de facturacion."}
    ],
)
print(message.content[0].text)

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const message = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1000,
  messages: [
    { role: "user", content: "Dame tres ideas para nombrar un microservicio de facturacion." }
  ]
});
console.log(message.content[0].text);

Anthropic también publica SDK para C#, Go, Java, PHP y Ruby. El patrón es idéntico en todos: cliente, messages.create, los mismos tres campos.

Leer la respuesta: content blocks, stop_reason y usage

La respuesta no es un string plano. content es un arreglo de bloques, cada uno con su type. Para texto normal el bloque es de tipo text y tu texto está en content[0].text. Esto importa porque cuando agregas tool use vas a recibir bloques de tipo tool_use en ese mismo arreglo.

{
  "id": "msg_013mHbppMPd2PrVJzGMZPt2D",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5",
  "content": [
    { "type": "text", "text": "1. Cobratron\n2. Facturoo\n3. ..." }
  ],
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 21, "output_tokens": 305 }
}

Dos campos que vas a leer en cada integración seria. stop_reason te dice por qué Claude paró: end_turn significa que terminó normal; max_tokens que se quedó sin presupuesto de salida (sube max_tokens y reintenta); tool_use que quiere que ejecutes una herramienta. usage trae input_tokens y output_tokens reales: con esos dos números calculas el costo exacto de cada request, sin estimar.

Elegir modelo: Sonnet 5 vs Haiku 4.5 vs Opus 4.8

Tres modelos cubren casi todo. El default sensato es Claude Sonnet 5 (claude-sonnet-5): la mejor combinación de velocidad e inteligencia, ventana de contexto de 1M de tokens y hasta 128k de salida. Cuesta $3 de entrada y $15 de salida por millón de tokens, con precio introductorio de $2 / $10 hasta el 31 de agosto de 2026.

Para volumen alto y tareas simples (clasificar, extraer, resumir corto), Claude Haiku 4.5 (claude-haiku-4-5, fijado en claude-haiku-4-5-20251001) es el más rápido y barato: $1 / $5 por millón, contexto de 200k y salida de 64k. Para razonamiento duro y flujos agénticos largos, Claude Opus 4.8 (claude-opus-4-8) es el más capaz: $5 / $25 por millón, contexto de 1M y salida de 128k.

Haiku 4.55

Sonnet 5 (intro)10

Sonnet 515

Opus 4.825

La estrategia de costo es enrutar por dificultad: Haiku para el grueso del tráfico barato, Sonnet 5 para la mayoría de la carga de producción, y Opus solo donde el problema lo justifique. Si quieres profundizar en cómo afinar Sonnet 5, lee ajustar Claude Sonnet 5: costo, calidad, effort y batch y qué cambia y cómo migrar a Sonnet 5.

System prompts y mensajes multi-turno

El system prompt va aparte de messages. Es donde defines el rol, el tono y las reglas que aplican a toda la conversación. No es un mensaje más del usuario: es la instrucción de fondo.

Para una conversación con memoria, la API no guarda estado por ti. Tú mandas el historial completo en cada llamada, alternando user y assistant. Acumulas los turnos en el arreglo messages y los reenvías:

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system="Eres un asistente de soporte tecnico. Responde en espanol, breve y con pasos concretos.",
    messages=[
        {"role": "user", "content": "Mi factura no se genero."},
        {"role": "assistant", "content": "Reviso. Cual es el RFC del receptor?"},
        {"role": "user", "content": "XAXX010101000"},
    ],
)

Cada turno que agregas suma tokens de entrada. Por eso, cuando el system o el historial son grandes y se repiten, conviene el prompt caching.

Streaming de salidas largas con Server-Sent Events

Si esperas una respuesta larga, no dejes al usuario viendo una pantalla en blanco diez segundos. Activa el streaming con "stream": true y la API te manda la respuesta por Server-Sent Events, token a token. Los SDK exponen un helper que te oculta el parseo de los eventos.

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explica que es un complemento de pago del CFDI."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

El streaming no baja el costo —pagas los mismos tokens— pero mejora muchísimo la latencia percibida. Para los detalles de manejarlo en producción junto con reintentos y errores, está Claude Sonnet 5 en producción: streaming, reintentos y errores.

Un loop mínimo de tool use

El tool use es lo que convierte a Claude de chat a agente. Le das un arreglo tools describiendo funciones que tu código sabe ejecutar. Cuando Claude decide usar una, la respuesta llega con stop_reason en tool_use y un bloque de tipo tool_use con el nombre y los argumentos. Tú ejecutas la función real, devuelves el resultado como un tool_result, y repites el ciclo hasta que stop_reason sea end_turn.

user

stop_reason: tool_use

ejecutas la tool

tool_result

stop_reason: end_turn

tools = [{
    "name": "get_weather",
    "description": "Clima actual de una ciudad",
    "input_schema": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"],
    },
}]

messages = [{"role": "user", "content": "Que clima hace en Monterrey?"}]
resp = client.messages.create(model="claude-sonnet-5", max_tokens=1024, tools=tools, messages=messages)

while resp.stop_reason == "tool_use":
    tool_use = next(b for b in resp.content if b.type == "tool_use")
    result = str(get_weather(tool_use.input["city"]))  # tu función real
    messages.append({"role": "assistant", "content": resp.content})
    messages.append({"role": "user", "content": [{
        "type": "tool_result", "tool_use_id": tool_use.id, "content": result,
    }]})
    resp = client.messages.create(model="claude-sonnet-5", max_tokens=1024, tools=tools, messages=messages)

Si quieres el fundamento conceptual, está qué es un agente de IA, y para armar uno completo, crear un agente autónomo con Claude Sonnet 5.

Controlar el costo: Batch -50%, prompt caching y conteo de tokens

Tres palancas reducen la factura sin tocar la calidad. La Message Batches API (POST /v1/messages/batches) procesa lotes de requests de forma asíncrona con 50% de descuento en entrada y salida. Si tu trabajo no necesita respuesta en el segundo —reportes nocturnos, backfills, clasificación masiva—, es dinero gratis. El prompt caching guarda la parte repetida de tu prompt (un system prompt grande, un documento de referencia) y las lecturas de caché cuestan apenas 0.1x del precio de entrada estándar. Y el conteo de tokens (POST /v1/messages/count_tokens) te deja medir el tamaño de un prompt antes de mandarlo, para presupuestar.

Un ejemplo concreto con Sonnet 5 a precio estándar ($3 entrada, $15 salida por millón). Procesas 100,000 documentos, cada uno con 2,000 tokens de entrada y 500 de salida:

Sin trucos: 100000 × (2000 × $3 + 500 × $15) / 1,000,000 = $1,350.
Con Batch (-50%): $675.
Si además 1,500 de esos 2,000 tokens de entrada son contexto fijo cacheado (lectura a 0.1x), pagas casi solo la salida y la entrada nueva: la factura baja aún más.

Batch -50%POST /v1/messages/batches, asíncrono, mitad de precio en entrada y salida

Prompt caching 0.1xLas lecturas de caché cuestan una décima del precio de entrada estándar

count_tokensMide el tamaño del prompt antes de mandarlo y presupuesta

Batch y caching se combinan. Para el detalle de implementar caché bien, está prompt caching en Claude: baja costos de tokens.

Seguridad y siguientes pasos

Lo no negociable: la key nunca toca el repositorio. Va en variables de entorno o en un gestor de secretos, fuera de logs y fuera del cliente —si tu app es frontend, las llamadas pasan por tu backend, jamás expongas la key en el navegador. Rota la key si sospechas que se filtró; en la Console se revoca en un clic. Maneja los errores HTTP de forma explícita: 429 significa rate limit (reintenta con backoff, los SDK ya lo hacen), los 5xx son transitorios y los 4xx son tu bug. Recuerda que el tamaño máximo de un request a la Messages API es de 32 MB.

Con esto ya hiciste tu primera llamada y sabes leer la respuesta, elegir modelo y controlar el costo. El siguiente paso natural es salir de producción básica hacia respuestas estructuradas y robustez: revisa structured outputs en producción y el hub de agentes de IA para el panorama completo. La referencia siempre viva es la documentación de la API de Claude y la página de precios.

API de Claude: tu primera llamada en cURL, Python y TS