La API de Claude para desarrolladores

La API de Mensajes

La API de Mensajes es el punto de acceso HTTP principal que permite a cualquier programa comunicarse con Claude. En lugar de abrir una ventana de chat, su código envía una solicitud JSON estructurada y recibe una respuesta JSON estructurada. JSON (JavaScript Object Notation) es un formato de texto estándar para el intercambio de datos.

Cada solicitud debe incluir tres elementos: el identificador del modelo (qué versión de Claude usar), max_tokens (el número máximo de tokens, o fragmentos de palabras, que Claude puede generar en la respuesta), y un arreglo messages (el historial de la conversación como lista de pares rol/contenido).

El SDK de Anthropic (kit de desarrollo de software) oficial para Node.js envuelve esta llamada HTTP en una simple función JavaScript. Instálelo con npm y luego escriba unas pocas líneas:

• Defina su clave API como variable de entorno con el nombre ANTHROPIC_API_KEY.
• Cree un cliente: const Anthropic = require("@anthropic-ai/sdk"); const client = new Anthropic();
• Llame a client.messages.create({ ... }) con su modelo, max_tokens y mensajes.
• Lea la respuesta desde response.content[0].text.

Los identificadores de modelo para junio de 2026 son claude-opus-4-8 (el más capaz), claude-sonnet-4-6 (equilibrado) y claude-haiku-4-5 (el más rápido). Comience con Haiku mientras aprende: es económico e instantáneo.

System, user, assistant en la API

Cada llamada a la API de Claude se construye a partir de una secuencia de mensajes, cada uno etiquetado con un rol. Los tres roles son system, user y assistant. El rol system es un parámetro especial de nivel superior (no forma parte del array de mensajes) que establece instrucciones persistentes para toda la conversación. Piense en él como el briefing que le da a Claude antes de que comience la conversación.

El array messages alterna entonces entre user (el turno humano) y assistant (la respuesta de Claude). Puede pre-rellenar este array con turnos anteriores para simular una conversación de múltiples turnos, o inyectar un turno assistant parcial para dirigir la primera palabra de la respuesta.

¿Por qué importa el orden de los roles? Claude está entrenado para respetar la jerarquía: las instrucciones system tienen el mayor peso, seguidas del historial de la conversación. Si un mensaje user entra en conflicto con el system prompt, Claude sigue el system prompt. Esto convierte al parámetro system en el lugar adecuado para reglas, personas, formatos de salida y salvaguardas de seguridad.

• system: cadena de texto de nivel superior, definida una vez por solicitud, nunca mostrada como burbuja de mensaje.
• user: un turno humano, obligatorio al menos una vez como último mensaje.
• assistant: las respuestas anteriores de Claude, o una cadena de pre-relleno para restringir la siguiente respuesta.
• Los mensajes deben alternar user/assistant; dos turnos user consecutivos son rechazados por la API.

Uso de herramientas a través de la API

La API de Claude le permite proporcionar al modelo una lista de herramientas (también llamadas definiciones de funciones) que puede invocar. Cada herramienta es un objeto JSON que describe un nombre, una descripción y un esquema de entrada (un objeto JSON Schema que indica a Claude qué parámetros acepta la herramienta). Claude nunca ejecuta la herramienta por sí mismo; devuelve un bloque estructurado tool_use que su código debe gestionar.

Un ciclo típico funciona de la siguiente manera:

1. Usted envía una solicitud messages que incluye un array tools.
2. Si Claude decide llamar a una herramienta, el stop_reason de la respuesta es "tool_use" y el contenido incluye un bloque tool_use con un id, el name de la herramienta y el objeto input.
3. Su código ejecuta la acción real (consulta a base de datos, llamada a API, cálculo) y luego agrega un bloque tool_result a la conversación usando el mismo tool_use_id.
4. Usted envía la conversación actualizada de vuelta a Claude, que lee el resultado y produce su respuesta final.

Dos decisiones de diseño clave afectan la fiabilidad. Primero, redacte la descripción de la herramienta como si estuviera explicando la función a un colega sin experiencia: Claude la usa para decidir si y cuándo llamar a la herramienta. Segundo, mantenga su esquema de entrada estricto: marque los campos obligatorios, use enum cuando los valores son fijos y evite campos string vagos cuando un número o booleano es más apropiado. Los esquemas vagos producen entradas vagas.

Cuando necesite que Claude llame exactamente a una herramienta específica, establezca tool_choice en {"type": "tool", "name": "your_tool_name"}. El valor predeterminado "auto" deja que Claude decida. Use "any" para forzar al menos una llamada a herramienta sin especificar cuál.

Respuestas en streaming

Por defecto, la API de Anthropic espera a que el modelo termine de generar antes de enviar cualquier respuesta. El streaming cambia esto: la API envía cada token (un fragmento de palabra, aproximadamente 3 o 4 caracteres) a su cliente en el momento en que se produce, de modo que el usuario ve el texto aparecer palabra por palabra en lugar de esperar la respuesta completa.

El streaming utiliza el protocolo Server-Sent Events (SSE). El servidor mantiene la conexión HTTP abierta y envía pequeños fragmentos de eventos. Cada fragmento contiene un delta, que es el nuevo texto incremental que se debe agregar. Su cliente acumula los deltas para reconstruir el mensaje completo.

Para activar el streaming con el SDK de Python o Node de Anthropic, pase stream=True (Python) o use el método .stream() (Node). El SDK expone un iterador asíncrono para procesar un fragmento a la vez sin almacenar toda la respuesta en memoria. Esto importa para salidas largas: una respuesta de 4000 tokens puede comenzar a renderizarse en menos de un segundo en lugar de esperar varios segundos.

• stream=True (Python): devuelve un gestor de contexto; itere text_stream para obtener fragmentos de texto sin procesar.
• .stream() (Node/TS): devuelve un iterable asíncrono; use for await para consumir los fragmentos.
• Tipos de eventos: message_start, content_block_delta, message_delta, message_stop.
• Las estadísticas de uso llegan en el último evento message_stop, no al principio.

Caché de prompts en la API

Cada llamada a la API reprocesa todos los tokens que se envían. El prompt caching permite marcar secciones estables de la solicitud para que Anthropic almacene una versión compilada en sus servidores. Las llamadas posteriores que coincidan con el mismo prefijo omiten el reprocesamiento y pagan una tarifa mucho menor: aproximadamente el 10 % del costo de entrada normal para los cache hits, frente al 125 % de la escritura inicial que rellena el caché.

Se marca un límite de caché añadiendo "cache_control": {"type": "breakpoint"} dentro de un bloque de contenido. Claude lee el prompt de arriba a abajo y almacena en caché todo lo que precede a ese marcador. Se pueden colocar hasta cuatro puntos de ruptura por solicitud. El patrón más habitual es un punto de ruptura después de un prompt de sistema largo o de un documento grande que se reutiliza en muchas llamadas.

Algunas reglas determinan si el caché se utiliza realmente:

• El prefijo debe tener al menos 1024 tokens (aproximadamente 750 palabras) para ser elegible para el almacenamiento en caché.
• Las entradas del caché expiran tras cinco minutos de inactividad; cada hit reinicia el temporizador.
• El modelo, la versión y todo el contenido anterior al punto de ruptura deben ser byte a byte idénticos entre llamadas.
• Modelos compatibles (junio de 2026): claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5.

La respuesta de la API incluye un objeto usage con cache_creation_input_tokens y cache_read_input_tokens, lo que permite verificar los hits y medir el ahorro en tiempo real.

La API Batch

La API Batch permite enviar hasta 10 000 solicitudes en una sola llamada y recibir todos los resultados de forma asíncrona (es decir, no se espera una respuesta en tiempo real: se consultan los resultados más adelante). A cambio de esta flexibilidad, Anthropic cobra un 50 % menos por token que la API estándar en tiempo real.

Se envía un archivo JSON con una lista de solicitudes, cada una con su propio custom_id único para poder relacionar los resultados con las entradas. Claude las procesa en segundo plano, normalmente en pocos minutos para cientos de solicitudes, aunque el SLA (Service Level Agreement, la garantía oficial de tiempo) permite hasta 24 horas.

La API Batch tiene su propio límite de velocidad independiente, separado de la API en tiempo real. Esto significa que un trabajo batch intensivo no consume la cuota interactiva. Es ideal para cualquier tarea sin conexión: generación de conjuntos de datos, evaluaciones, traducción de grandes catálogos o clasificación de miles de registros.

• Modelos compatibles: claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5
• Máximo de solicitudes por batch: 10 000
• Descuento: 50 % en tokens de entrada y salida frente al precio en tiempo real
• Formato de resultados: una línea JSONL por solicitud, identificada por custom_id
• Cancelación: es posible cancelar un batch en curso con una sola llamada a la API

Contar tokens

Antes de enviar una solicitud a Claude, puede pedirle a la API que cuente exactamente cuántos tokens (los fragmentos de texto que el modelo lee y escribe) consumirá esa solicitud. Para ello se utiliza el endpoint de conteo de tokens: POST /v1/messages/count_tokens. Acepta el mismo cuerpo que una solicitud de mensajes normal, pero devuelve solo un conteo, nunca una respuesta, y no tiene costo.

Los conteos de tokens importan por dos razones. Primero, cada modelo tiene una ventana de contexto (el máximo de tokens que puede procesar a la vez): 200 000 para Opus y Sonnet, 200 000 para Haiku. Segundo, la facturación se realiza por token de entrada y de salida, por lo que enviar de más es un desperdicio de dinero y enviar de menos puede truncar el prompt. Contar le permite mantenerse bajo el límite y estimar el costo antes de confirmar.

Lo que puede contar antes de enviar:

• El prompt de sistema solo, para entender su costo fijo.
• Las definiciones de herramientas, que a menudo sorprenden a los desarrolladores por su tamaño.
• El historial de conversación, para decidir cuándo resumir o descartar turnos anteriores.
• Archivos adjuntos o documentos largos, para verificar que caben en la ventana.

Para el presupuesto de tokens, establezca un límite suave en su código: si input_tokens devuelto por el endpoint de conteo supera, por ejemplo, 150 000, trunce o resuma antes de enviar. También puede combinar el conteo con el parámetro max_tokens (que limita la longitud de la salida) para controlar con precisión el gasto total por llamada.

Identificadores de modelo, precios y migración

Cada modelo Claude tiene un identificador de modelo, la cadena exacta que se pasa a la API para solicitar una versión específica. A partir de junio de 2026, los tres identificadores actuales son claude-opus-4-8 (el más capaz, el de mayor costo), claude-sonnet-4-6 (equilibrio entre rendimiento y costo) y claude-haiku-4-5 (el más rápido, el de menor costo). Utilice siempre el identificador completo con versión en el código de producción, nunca un alias como "claude-opus" sin sufijo de versión, porque Anthropic puede redirigir silenciosamente los alias a modelos más nuevos y cambiar sus costos o comportamientos.

Elegir el modelo correcto implica un equilibrio entre costo y rendimiento. Una regla práctica:

• Opus (claude-opus-4-8): decisiones de arquitectura, razonamiento complejo, análisis de documentos largos, bucles agentivos donde la calidad es lo más importante.
• Sonnet (claude-sonnet-4-6): tareas de codificación cotidianas, resumen, redacción, flujos de trabajo de múltiples pasos donde importan la velocidad y el costo.
• Haiku (claude-haiku-4-5): clasificación, enrutamiento, consultas rápidas, trabajos por lotes de alto volumen donde la latencia es crítica.

La migración consiste en cambiar en su base de código un identificador de modelo antiguo por uno nuevo. El patrón seguro es: actualizar la cadena del identificador de modelo, ejecutar su suite de evaluación o pruebas existente contra el nuevo modelo, comparar las salidas en una muestra de prompts reales y luego publicar. Dado que los modelos más nuevos pueden rechazar de forma diferente o formatear la salida de manera distinta, nunca migre sin un paso de comparación. Anthropic publica una guía de migración para cada generación; consúltela para detectar cambios que puedan romper los formatos de llamada a herramientas o los tamaños de ventana de contexto antes de cambiar.

El precio es por token (un token equivale aproximadamente a cuatro caracteres de texto en inglés). Se paga por separado por los tokens de entrada (lo que se envía) y los tokens de salida (lo que devuelve el modelo). Los tokens de salida cuestan más. Use el prompt caching para reutilizar un prompt de sistema extenso entre llamadas y reducir los costos de entrada hasta un 90 por ciento en la porción almacenada en caché. La API Batch de Anthropic ofrece un 50 por ciento de descuento en entrada y salida a cambio de mayor latencia, ideal para la generación de conjuntos de datos sin conexión.

Entradas de visión y PDF

La API de Claude acepta mucho más que texto. Puedes enviar imágenes y archivos PDF directamente en el arreglo messages, junto a un prompt de texto o en su lugar. El modelo lee el contenido visual y razona sobre él de la misma forma que lo haría con palabras escritas. Esta capacidad se llama entrada multimodal (multiformato, no solo texto).

Las imágenes se pasan como cadenas codificadas en base64 (una forma de representar datos binarios como texto ASCII puro) dentro de un bloque content con "type": "image". Se especifica el tipo de medio, como image/jpeg, image/png, image/gif o image/webp. También puedes pasar una URL pública usando "type": "image" con una fuente "url" en lugar de base64.

Los PDF usan "type": "document" con "media_type": "application/pdf" y el contenido del archivo en base64. Claude lee la capa de texto completa del PDF y, cuando las páginas contienen diagramas o gráficos, también los interpreta visualmente. Los PDF tienen un límite de 100 páginas y aproximadamente 32 MB por archivo.

• Formatos de imagen admitidos: JPEG, PNG, GIF, WebP.
• Tamaño máximo de imagen por solicitud: 20 MB (el peso codificado en base64 es aproximadamente un 33 por ciento mayor que el archivo original).
• Hasta 20 imágenes por solicitud en los modelos actuales.
• PDF: máximo 100 páginas, 32 MB en bruto. Se analiza tanto el contenido textual como el visual.
• La visión está disponible en claude-opus-4-8, claude-sonnet-4-6 y claude-haiku-4-5.