Conceptos básicos de la API de Mensajes

7 ejemplos para empezar con la API de Mensajes: 5 básicos y 2 intermedios.

Prerrequisitos

• Instala el SDK oficial: pip install anthropic.
• Configura una clave API en tu entorno: export ANTHROPIC_API_KEY=sk-ant-... (o construye anthropic.Anthropic(api_key=...) directamente).
• Todos los ejemplos usan claude-opus-4-8; cambia a claude-sonnet-5 o claude-haiku-4-5 si deseas una compensación diferente entre velocidad y costo.

Ejemplos básicos

1. Una solicitud de un solo turno

La llamada más pequeña posible: un mensaje de usuario, sin historial.

import anthropic
 
client = anthropic.Anthropic()
 
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "¿Cuál es la capital de Francia?"},
    ],
)
 
print(response.content[0].text)

• max_tokens es obligatorio en cada solicitud y limita la longitud de la respuesta de Claude.
• response.content es una lista de bloques de contenido; para una respuesta de texto plano, el primer bloque .text contiene la respuesta.
• No se requiere un prompt system; es opcional, no obligatorio.

2. Añadir un prompt del sistema

El parámetro system se sitúa fuera de messages y da forma al tono, la personalidad o las restricciones de toda la conversación.

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    system="Eres un asistente conciso. Responde en una sola frase.",
    messages=[
        {"role": "user", "content": "¿Por qué el cielo es azul?"},
    ],
)
 
print(response.content[0].text)

• system es un parámetro de solicitud de nivel superior, no un mensaje con un rol.
• Se aplica a cada turno de la conversación, no solo al primero.
• Mantenlo estable en todas las solicitudes de la misma conversación; cambiarlo a mitad de la conversación afecta tanto al comportamiento como al caché del prompt.

3. Una solicitud de múltiples turnos

Continúa una conversación incluyendo la respuesta anterior de Claude como un turno de assistant antes de tu próxima pregunta.

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "¿Cuál es la capital de Francia?"},
        {"role": "assistant", "content": "La capital de Francia es París."},
        {"role": "user", "content": "¿Cuál es su población?"},
    ],
)
 
print(response.content[0].text)

• Los roles deben alternarse estrictamente: user, assistant, user; la API rechaza solicitudes que rompen este patrón.
• La API no tiene estado: Claude solo sabe de "París" aquí porque está presente en el historial reenviado, no porque recuerde la llamada anterior.
• En la práctica, construyes esta matriz programáticamente añadiendo cada respuesta antes de la siguiente solicitud, en lugar de codificarla de forma rígida.

4. Leer el objeto de respuesta

El objeto Message completo contiene más que solo el texto de la respuesta; examínalo para construir aplicaciones fiables.

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Nombra tres lenguajes de programación."}],
)
 
print(response.stop_reason)     # por qué se detuvo la generación, por ejemplo, "end_turn"
print(response.usage.input_tokens, response.usage.output_tokens)
print(response.model)           # el modelo que realmente sirvió la respuesta

• stop_reason te dice si Claude terminó de forma natural (end_turn), alcanzó el límite de tokens (max_tokens) o se detuvo por otra razón.
• usage informa los recuentos de tokens tanto para la entrada como para la salida generada, que es por lo que se te factura.
• Siempre verifica stop_reason antes de confiar en que response.content está completo; una parada por max_tokens significa que la respuesta fue cortada.

5. Manejar errores

Los problemas de red, los límites de tasa y las solicitudes incorrectas generan excepciones tipificadas; captúralas explícitamente en lugar de adivinar a partir de una Exception genérica.

import anthropic
 
client = anthropic.Anthropic()
 
try:
    response = client.messages.create(
        model="claude-opus-4-8",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Hola, Claude"}],
    )
except anthropic.RateLimitError:
    print("Límite de tasa alcanzado - espera y reintenta")
except anthropic.APIStatusError as e:
    print(f"Error de API {e.status_code}: {e.message}")

• El SDK expone una clase de excepción distinta para cada estado HTTP (RateLimitError, NotFoundError, AuthenticationError, etc.).
• Captura primero la excepción más específica, luego recurre a APIStatusError para cualquier otra cosa.
• El SDK ya reintenta automáticamente las respuestas 429 y 5xx con retroceso, por lo que una RateLimitError capturada significa que los reintentos se agotaron.

Ejemplos intermedios

6. Construir la matriz de mensajes en un bucle

La mayoría de las aplicaciones reales no codifican la conversación de forma rígida; añaden elementos a una lista y la reenvían en cada turno.

import anthropic
 
client = anthropic.Anthropic()
messages = []
 
def ask(user_text: str) -> str:
    messages.append({"role": "user", "content": user_text})
 
    response = client.messages.create(
        model="claude-opus-4-8",
        max_tokens=1024,
        system="Eres un asistente útil que recuerda el contexto dentro de este chat.",
        messages=messages,
    )
 
    reply_text = response.content[0].text
    messages.append({"role": "assistant", "content": response.content})
    return reply_text
 
print(ask("Mi color favorito es el verde azulado."))
print(ask("¿Cuál es mi color favorito?"))

• Añade el response.content completo (no solo el texto extraído) como turno del asistente, para que los bloques no textuales se conserven para turnos posteriores.
• messages crece en dos entradas por intercambio: tu nuevo turno de user y la respuesta de assistant de Claude.
• Este es el patrón sobre el que se construyen todas las interfaces de chat de múltiples turnos, ya sea un bucle CLI o un backend web.

7. Transmitir una respuesta

Para respuestas más largas, transmite los tokens a medida que se generan en lugar de esperar la respuesta completa.

import anthropic
 
client = anthropic.Anthropic()
 
with client.messages.stream(
    model="claude-opus-4-8",
    max_tokens=2048,
    messages=[{"role": "user", "content": "Escribe un poema corto sobre el océano."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
 
    final_message = stream.get_final_message()
    print("\n\nRazón de parada:", final_message.stop_reason)

• client.messages.stream() devuelve un gestor de contexto; stream.text_stream produce fragmentos de texto incrementales a medida que llegan.
• Llama a stream.get_final_message() después del bucle para obtener el objeto Message completo, incluyendo usage y stop_reason.
• Se recomienda la transmisión para cualquier solicitud donde max_tokens sea grande, ya que las solicitudes no transmitidas corren el riesgo de alcanzar los tiempos de espera HTTP del lado del cliente.

Relacionado: Entendiendo los roles y turnos en la API de Mensajes - el modelo conceptual detrás de estos ejemplos | Construyendo conversaciones de múltiples turnos con la matriz de mensajes - una mirada más profunda a la gestión del estado de la conversación

Versiones de Stack: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado), y Claude Haiku 4.5 - y el SDK oficial de Python anthropic (última versión 0.x). Los nombres de los modelos, las versiones del SDK y los precios cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.