Developer Platform y API

§1 ¿Qué es una API?

La diferencia con lo que ya conoces: cuando abres la web de Claude, eres tú hablando con él. Cuando usas la API, es tu programa el que habla con Claude, solito y automáticamente. (Las siglas significan Application Programming Interface; tradúcelo como «la ventanilla por la que un programa le habla a otro».)

¿Y dónde está esa ventanilla? En una dirección de internet. A la dirección exacta donde mandas tu pedido se le llama endpoint («punto final»). El de Claude para conversar es:

https://api.anthropic.com/v1/messages

§2 JSON, el idioma

Las personas hablamos español (o inglés, o chino). Los programas, cuando se pasan datos, usan un formato ordenadito para no liarse. El más común se llama JSON, y es solo texto con unas reglas muy simples que pueden leer tanto las máquinas como tú.

• Unas llaves { } envuelven una «ficha» de datos (un objeto).
• Dentro van pares "clave": valor — la clave (entre comillas) es el nombre del dato; el valor, su contenido.
• El valor puede ser texto (entre comillas), un número (sin comillas), una lista entre corchetes [ ], o incluso otra ficha.
• Los pares se separan con comas.

Un ejemplo de andar por casa, una ficha de contacto:

{
  "nombre": "Ada",
  "edad": 36,
  "ciudad": "Madrid",
  "aficiones": ["ajedrez", "senderismo"]
}

Se lee solo: una ficha con cuatro datos — nombre es texto, edad es número, ciudad es texto y aficiones es una lista con dos cosas. Eso es JSON.

§3 Las piezas de una petición

Antes de la llamada, conozcamos las cuatro piezas que la forman. Piensa en enviar un paquete por mensajería:

• La API key es tu carné: una contraseña larga y secreta que demuestra que eres tú quien pide. La sacas en la consola de Anthropic y nunca se enseña a nadie (si se filtra, pueden gastar en tu nombre).
• La dirección es el endpoint que ya vimos.
• Las cabeceras (headers) son la etiqueta del paquete: datos de servicio que van «por fuera» — tu carné (x-api-key), la versión de la API (anthropic-version) y en qué formato va el contenido (content-type: application/json).
• El cuerpo (body) es lo que va dentro del paquete: el JSON con tu pedido de verdad.

§4 Tu primera llamada a Claude

Esta es la llamada completa. No te asustes: debajo la partimos en trozos.

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "system": "Responde en español, claro y directo.",
    "messages": [
      { "role": "user", "content": "Dame 3 ideas para un curso de IA." }
    ]
  }'

• curl — un programita que envía paquetes por internet desde la terminal. Es nuestro mensajero.
• La línea siguiente es la dirección (el endpoint).
• Las tres -H son las cabeceras (la etiqueta): carné, versión y «esto es JSON».
• -d es el cuerpo (los datos): justo después viene el JSON que ya sabes leer.

Dentro del cuerpo:

• model — qué cerebro quieres (aquí Sonnet 4.6).
• max_tokens — el tope de lo que puede responder. Obligatorio. (Un token ≈ ¾ de palabra.)
• system — las instrucciones de fondo: cómo quieres que se comporte.
• messages — la conversación: lista de turnos, cada uno con quién habla (role) y qué dice (content).

¿Y qué te devuelve? Otro JSON. Lo importante está en dos sitios:

{
  "content": [ { "type": "text", "text": "1. ...  2. ...  3. ..." } ],
  "usage": { "input_tokens": 22, "output_tokens": 130 }
}

content es la respuesta de Claude (el texto está dentro del bloque "text"); usage es la cuenta: cuántos tokens entraron y salieron. Eso es lo que pagas.

§5 Tool use: darle herramientas a Claude

El baile tiene cuatro pasos:

1. Le presentas la herramienta en la petición.
2. Claude, si la necesita, dice: «pulsa el botón get_weather con ciudad = Manzanares» (no la ejecuta él).
3. Tú ejecutas esa función en tu programa y consigues el dato.
4. Le devuelves el resultado y entonces Claude redacta la respuesta final.

Así se describe una herramienta (un JSON dentro de la petición):

"tools": [
  {
    "name": "get_weather",
    "description": "Devuelve el tiempo actual de una ciudad.",
    "input_schema": {
      "type": "object",
      "properties": {
        "ciudad": { "type": "string", "description": "Nombre de la ciudad" }
      },
      "required": ["ciudad"]
    }
  }
]

Tradúcelo: «tienes una herramienta get_weather, sirve para el tiempo, y para usarla necesitas una ciudad (texto), que es obligatoria». El input_schema es solo la lista de ingredientes que la herramienta pide.

§6 Streaming: la respuesta en directo

Cuando le pides algo a Claude, por defecto esperas a que termine y te llega todo de golpe. Con el streaming te llega palabra a palabra, según la va escribiendo — igual que ves el texto aparecer en la web del chat. Se activa añadiendo una línea al cuerpo: "stream": true.

• Que no se haga eterno a la vista: si la respuesta es larga, el usuario ve que «algo pasa» desde el primer segundo, en vez de mirar una pantalla congelada.
• Empezar a trabajar antes: tu programa puede ir procesando lo que llega sin esperar al final.

¿Cuándo da igual? En una tarea automática que nadie mira en directo (un proceso de noche). Mismo endpoint, solo cambias ese interruptor. (Por debajo usa una técnica llamada SSE —el servidor te va mandando trocitos según los tiene—; no necesitas saber más para empezar.)

§7 Gastar menos: Batch y caché

Dos trucos para que la factura no se dispare:

• Batch API (procesar por lotes). Si tienes muchas tareas que no corren prisa —resumir 5.000 reseñas—, las mandas todas juntas en un «lote». Claude las hace cuando puede (hasta 24 h) y, a cambio de esa paciencia, pagas la mitad (50 % de descuento). Ideal para trabajos de madrugada.
• Prompt caching (memoria temporal). Si en cada llamada le mandas el mismo manual de 50 páginas como contexto, pagarlo entero cada vez es tirar dinero. Con la caché le dices «esta parte guárdatela un rato», y las siguientes llamadas la pagan muchísimo más barata (las relecturas rondan el 10 % → hasta un 90 % de ahorro). Guardarla la primera vez cuesta un pelín más.

En la respuesta lo ves en usage, con dos contadores: cache_creation_input_tokens (lo que guardaste) y cache_read_input_tokens (lo que releíste barato).

§8 Imágenes y PDF: más que texto

Hasta ahora le mandábamos texto, pero el content de un mensaje admite bloques de distintos tipos. Puedes meterle una imagen o un PDF y preguntarle por ellos.

"content": [
  {
    "type": "image",
    "source": { "type": "base64", "media_type": "image/jpeg", "data": "/9j/4AAQ..." }
  },
  { "type": "text", "text": "¿Qué hay en esta imagen?" }
]

Aquí el content ya no es una frase suelta, sino una lista con dos bloques: primero una imagen, luego la pregunta.

• Imagen → bloque "image". El data es la foto convertida a texto (un formato llamado base64: «una imagen escrita como una ristra larguísima de caracteres»). Hay que indicar el tipo (media_type).
• PDF → bloque "document" (Claude lee tanto el texto como lo visual del documento).

Mezclas bloques en el mismo mensaje y le preguntas lo que quieras. max_tokens sigue siendo obligatorio, como siempre.

§9 Chuleta del módulo

§10 Examen del módulo

Marca una respuesta y te digo al instante si va bien, con el porqué. Al final, tu nota.