La API de Claude para quienes construyen
- 01La petición, una única puerta de entrada6 min
La API de Claude tiene una única puerta de entrada, la petición POST de la API Messages: cada intercambio pasa por ella, con un array messages y un modelo elegido. El campo max_tokens es obligatorio, sin valor por defecto, y la respuesta sigue siempre la misma forma, con un stop_reason que indica por qué se detuvo la generación.
- 02Roles que se sostienen, no un prerrellenado que rompe7 min
Completar uno mismo el inicio de la respuesta de Claude, el prerrellenado del turno assistant, ya no funciona en los modelos actuales: el servidor devuelve un error, salvo un caso particular de gestión de los rechazos. Una instrucción system estable produce el mismo resultado sin tocar el array messages, y el campo output_config.format restringe la forma de la salida.
- 03Las herramientas, Claude propone, el código dispone7 min
Claude nunca ejecuta una herramienta él mismo: devuelve una solicitud de uso, el código del desarrollador la ejecuta realmente y devuelve el resultado para que la conversación continúe. Este ciclo se apoya en un único contrato, el esquema declarado por input_schema. Una herramienta se declara con name, description e input_schema.
- 04Recibir la respuesta en streaming6 min
El modo de streaming mantiene abierta la conexión HTTP y entrega el texto por fragmentos, a medida que el modelo lo produce, sin esperar al final de la generación. El recuento de tokens vive en el campo usage del último evento message_delta, nunca en message_stop: un código que lo busca ahí no lo encuentra.
- 05Dos palancas de coste, la memoria en caché y el procesamiento por lotes8 min
Un prefijo de petición marcado como reutilizable cuesta una fracción reducida del precio normal cuando se relee desde la caché, y un conjunto de peticiones no urgentes tratado por lotes cuesta menos que un tratamiento inmediato, dos reducciones que se acumulan entre sí y con los demás modificadores de precio.
- 06Contar antes de enviar, la ventana de contexto6 min
Un punto de conteo dedicado devuelve el número de tokens de una petición antes de enviarla, y la ventana de contexto con la que comparar esa cifra ya no es un valor común a toda una gama de modelos, ahora varía fuertemente de una familia a otra.
- 07Elegir un modelo, cambiarlo, encajar un rechazo9 min
La elección de un modelo es un compromiso entre calidad, velocidad y coste que se revisa en cada nueva generación, y un rechazo devuelto por un clasificador de seguridad se trata como un caso normal del protocolo, no como una avería.
- 08Pasar a Opus 5.5 sin romper tu código8 min
Pasar de Claude Opus 5 a Claude Opus 5.5 no se resume en cambiar el identificador: cuatro ajustes antiguos devuelven ahora un error 400, y las notas escritas entre dos llamadas a herramientas llegan vacías mientras el código no configure thinking.display.