Fundamentos de la API de Claude: Nociones básicas

9 ejemplos para empezar con los Fundamentos de la API de Claude: 6 básicos y 3 intermedios.

Prerrequisitos

• Instala el SDK oficial: pip install anthropic.
• Establece tu clave API como variable de entorno: export ANTHROPIC_API_KEY="sk-ant-...".
• Python 3.8 o superior.

Ejemplos básicos

1. Tu primer mensaje

La llamada más pequeña posible a la API de Mensajes: un modelo, un prompt, una respuesta.

import anthropic
 
client = anthropic.Anthropic()  # lee ANTHROPIC_API_KEY del entorno
 
response = client.messages.create(
    model="claude-sonnet-5-20260630",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Saluda en una frase."}],
)
 
print(response.content[0].text)

• model y max_tokens son los únicos dos parámetros requeridos en cada llamada.
• messages es una lista de turnos; un único turno de usuario es suficiente para un prompt único.
• El texto de la respuesta se encuentra en response.content[0].text, no directamente en response.

Relacionado: Instalación y configuración del SDK de Python de Anthropic - guía completa de configuración.

2. Lectura del objeto de respuesta completo

La respuesta contiene más que solo texto; también informa cómo finalizó la generación y cuántos tokens se utilizaron.

import anthropic
 
client = anthropic.Anthropic()
 
response = client.messages.create(
    model="claude-sonnet-5-20260630",
    max_tokens=256,
    messages=[{"role": "user", "content": "Nombra tres números primos."}],
)
 
print("Texto:", response.content[0].text)
print("Razón de parada:", response.stop_reason)
print("Tokens de entrada:", response.usage.input_tokens)
print("Tokens de salida:", response.usage.output_tokens)

• stop_reason te dice por qué se detuvo la generación, comúnmente "end_turn" o "max_tokens".
• usage.input_tokens y usage.output_tokens son por lo que se te factura.
• Una stop_reason de "max_tokens" significa que la respuesta fue cortada; aumenta max_tokens si necesitas más.

3. Control de max_tokens

max_tokens es un límite estricto sobre cuánto puede generar Claude, no una longitud objetivo.

import anthropic
 
client = anthropic.Anthropic()
 
response = client.messages.create(
    model="claude-haiku-4-5-20260601",
    max_tokens=50,
    messages=[{"role": "user", "content": "Explica la fotosíntesis."}],
)
 
print(response.content[0].text)
print(response.stop_reason)  # probablemente "max_tokens" - la explicación fue cortada

• La generación se detiene en el momento en que se alcanza max_tokens, incluso a mitad de frase si es necesario.
• Establece max_tokens generosamente para tareas con longitud de salida impredecible, como resúmenes o código.
• Un max_tokens demasiado bajo es una fuente común de respuestas truncadas e inútiles.

4. Ajuste de la temperatura para la aleatoriedad

temperature controla cuán determinista o variada es la salida.

import anthropic
 
client = anthropic.Anthropic()
 
response = client.messages.create(
    model="claude-sonnet-5-20260630",
    max_tokens=100,
    temperature=0.0,  # casi determinista, bueno para tareas fácticas/estructuradas
    messages=[{"role": "user", "content": "¿Cuál es la capital de Japón?"}],
)
 
print(response.content[0].text)

• Una temperature más baja (cerca de 0) produce respuestas consistentes y repetibles, ideal para hechos, clasificación y código.
• Una temperature más alta (más cerca de 1) produce un lenguaje más variado y creativo, mejor para la lluvia de ideas.
• temperature y top_p afectan la aleatoriedad; la mayoría de las llamadas solo necesitan ajustar uno de ellos.

5. Uso de un prompt del sistema

Un parámetro system establece instrucciones persistentes que se aplican a toda la conversación.

import anthropic
 
client = anthropic.Anthropic()
 
response = client.messages.create(
    model="claude-sonnet-5-20260630",
    max_tokens=200,
    system="Eres un revisor de código conciso. Responde solo con puntos.",
    messages=[{"role": "user", "content": "Revisa esta función: def add(a,b): return a+b"}],
)
 
print(response.content[0].text)

• system es un parámetro de nivel superior, separado de la lista messages.
• Da forma al tono, rol y restricciones sin consumir un "turno" en la conversación.
• Mantén los prompts del sistema enfocados; los prompts del sistema largos y vagos debilitan el seguimiento de instrucciones.

6. Manejo de un error básico

Envuelve las llamadas en un try/except para manejar solicitudes inválidas o problemas de autenticación de forma elegante.

import anthropic
 
client = anthropic.Anthropic()
 
try:
    response = client.messages.create(
        model="claude-sonnet-5-20260630",
        max_tokens=100,
        messages=[{"role": "user", "content": "¡Hola!"}],
    )
    print(response.content[0].text)
except anthropic.AuthenticationError:
    print("Verifica que ANTHROPIC_API_KEY esté configurada correctamente.")
except anthropic.APIStatusError as e:
    print(f"La API devolvió un error: {e.status_code} - {e.message}")

• anthropic.AuthenticationError cubre específicamente problemas de clave de estilo 401.
• anthropic.APIStatusError es la clase base para otras respuestas no 2xx, útil como captura general.
• Capturar tipos de excepción específicos es mejor que capturar Exception sin formato; te dice qué salió mal realmente.

Relacionado: Referencia de códigos de error y solución de problemas de la API de Claude - catálogo completo de errores.

Ejemplos intermedios

7. Una conversación de varios turnos

Dado que la API no tiene estado, debes reenviar los turnos anteriores tú mismo para mantener el contexto.

import anthropic
 
client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Mi color favorito es el verde azulado."}]
 
first = client.messages.create(
    model="claude-sonnet-5-20260630",
    max_tokens=100,
    messages=messages,
)
print("Claude:", first.content[0].text)
 
# Añade la respuesta de Claude, luego el siguiente turno del usuario, antes de volver a llamar.
messages.append({"role": "assistant", "content": first.content[0].text})
messages.append({"role": "user", "content": "¿Cuál es mi color favorito?"})
 
second = client.messages.create(
    model="claude-sonnet-5-20260630",
    max_tokens=100,
    messages=messages,
)
print("Claude:", second.content[0].text)

• Cada llamada reenvía el historial completo; no hay sesión en el servidor a la que hacer referencia.
• Los roles se alternan entre "user" y "assistant"; la lista debe comenzar con un turno de "user".
• Historiales más largos significan más tokens de entrada facturados por llamada; esto es un costo real, no solo una formalidad.

8. Combinación de prompt del sistema, temperature y top_p

Las aplicaciones reales suelen ajustar varios parámetros juntos para una tarea específica.

import anthropic
 
client = anthropic.Anthropic()
 
response = client.messages.create(
    model="claude-opus-4-8-20260415",
    max_tokens=500,
    system="Eres un escritor técnico preciso. Evita la especulación.",
    temperature=0.2,
    top_p=0.9,
    messages=[{"role": "user", "content": "Redacta una entrada de registro de cambios de un párrafo para una nueva opción de reintento."}],
)
 
print(response.content[0].text)

• Una temperature baja combinada con un system enfocado es adecuada para tareas de escritura precisas y de baja varianza.
• top_p limita aún más el conjunto de muestreo; ajusta temperature o top_p, no ambos agresivamente a la vez.
• La elección de claude-opus-4-8 aquí refleja una tarea que se beneficia de un razonamiento más sólido que un modelo más ligero.

Relacionado: Selección de un modelo: Claude Fable 5, Opus 4.8, Sonnet 5 y Haiku 4.5 - cómo elegir entre modelos.

9. Reintento básico ante límites de tasa

max_retries en el cliente maneja automáticamente errores transitorios 429/5xx con retroceso.

import anthropic
 
client = anthropic.Anthropic(max_retries=3)  # reintenta 429s y 5xxs con retroceso exponencial
 
response = client.messages.create(
    model="claude-haiku-4-5-20260601",
    max_tokens=200,
    messages=[{"role": "user", "content": "Resume esto en una frase: el cielo es azul debido a la dispersión de Rayleigh."}],
)
 
print(response.content[0].text)

• max_retries es una opción del constructor a nivel de cliente, no un parámetro por llamada.
• El SDK solo reintenta errores genuinamente transitorios (429, 5xx); no reintenta errores de validación de clase 400.
• Elegir un modelo barato y rápido como claude-haiku-4-5 para resúmenes simples mantiene bajos los costos y la latencia.

Relacionado: Manejo de límites de tasa con retroceso exponencial - estrategia de reintento en profundidad.

Versiones de la pila: 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.