API de Mensajes (Messages API)

La API de Mensajes (Messages API) es la interfaz HTTP con la que cualquier aplicación habla con Claude: un único endpoint, POST /v1/messages, al que envías la conversación como una lista de turnos y del que recibes la siguiente respuesta del modelo. Es la base sobre la que se construyen chatbots, agentes, integraciones y también los SDK oficiales de Anthropic. Sustituyó a la antigua Text Completions API, que trabajaba con un único bloque de texto plano.

Cómo funciona

Cada petición es un JSON con unos pocos campos clave:

• model: el identificador del modelo Claude que quieres usar.
• max_tokens: obligatorio. Límite de tokens que puede generar la respuesta.
• messages: array de turnos alternos con role user o assistant. El contenido puede ser texto o una lista de bloques (texto, imágenes, documentos, resultados de herramientas).
• system: las instrucciones de sistema van en un parámetro aparte, no como un rol dentro de messages.
• Opcionales: temperature, stop_sequences, stream, tools, tool_choice o la configuración de razonamiento extendido, según el modelo.

La respuesta devuelve un objeto con role: "assistant", un array content de bloques tipados (text, tool_use, thinking...), un stop_reason que explica por qué paró (por ejemplo end_turn, max_tokens, stop_sequence o tool_use) y un objeto usage con los tokens de entrada y salida consumidos.

La autenticación se hace con la cabecera x-api-key y la cabecera anthropic-version, que fija la versión del contrato de la API.

Por qué importa

La API es sin estado: Claude no recuerda nada entre llamadas. Si quieres una conversación de varios turnos, tu aplicación guarda el historial y lo reenvía completo en cada petición. Esto tiene consecuencias directas: cada turno vuelve a facturar todo el contexto acumulado, el historial puede acabar chocando con la ventana de contexto y tú decides qué recortar, resumir o cachear.

El formato en bloques también condiciona tu código. No basta con leer content[0].text: si usas herramientas, la respuesta puede traer bloques tool_use que tu programa debe ejecutar y devolver como tool_result en un nuevo mensaje de usuario. Revisar stop_reason es la forma correcta de saber si la respuesta está completa, truncada o esperando una herramienta.

Ejemplo mínimo

import anthropic

client = anthropic.Anthropic()  # lee ANTHROPIC_API_KEY

msg = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    system="Eres un asistente técnico conciso.",
    messages=[
        {"role": "user", "content": "Explica qué es un índice en SQL."}
    ],
)

print(msg.stop_reason)
print(msg.content[0].text)
print(msg.usage.input_tokens, msg.usage.output_tokens)

Para continuar la conversación, añades la respuesta como turno assistant y la nueva pregunta como turno user, y vuelves a llamar. Si quieres pasar de este ejemplo a un producto real, merece la pena aprender a construir aplicaciones sobre esta API con manejo de errores, streaming y control de costes.

Errores comunes

• Meter el system prompt como un mensaje: no existe el rol system dentro de messages; va en el parámetro system.
• Asumir memoria: si no reenvías el historial, Claude no sabe qué se dijo antes.
• Ignorar max_tokens: un valor bajo corta respuestas a medias con stop_reason: "max_tokens".
• Confundirla con la app de Claude: claude.ai y sus planes de suscripción son un producto distinto; la API se factura por tokens en la consola de desarrolladores.
• Romper la alternancia de roles: el primer mensaje debe ser de user y los turnos deben tener sentido conversacional.