Cómo empezar con la API de Claude (Anthropic): guía paso a paso

Publicado el 3 de junio de 2026 · 14 min de lectura · Blog MasterEnClaude

La API de Claude de Anthropic te permite integrar el modelo en tus propias aplicaciones, scripts y flujos de trabajo automatizados. Si ya usas Claude a través de la interfaz web pero quieres ir más allá, esta guía te llevará desde cero hasta tener tu primera integración funcionando en Python, con ejemplos reales y sin dar nada por supuesto.

Paso 1: crear tu cuenta en Anthropic Console

El punto de partida es console.anthropic.com. Desde ahí gestionas tu API key, los límites de uso y el gasto. El registro es gratuito; pagas solo por los tokens consumidos (entrada y salida), sin cuota mensual fija.

Una vez dentro, ve a la sección API Keys y crea una nueva clave. Guárdala de inmediato porque solo se muestra una vez. Por seguridad, nunca la escribas directamente en el código fuente; usa en su lugar una variable de entorno:

# En tu terminal (o en tu fichero .env)
export ANTHROPIC_API_KEY="sk-ant-api03-XXXXXXXXXX"

Paso 2: instalar el SDK de Python

Anthropic mantiene un SDK oficial para Python (y otro para TypeScript/JavaScript). Para Python:

# Crea un entorno virtual primero (recomendado)
python -m venv venv
source venv/bin/activate   # En Windows: venv\Scripts\activate

# Instala el SDK
pip install anthropic

El SDK requiere Python 3.8 o superior. Es compatible con el ecosistema estándar de Python y no tiene dependencias pesadas.

Paso 3: tu primera llamada a la Messages API

La API principal de Claude se llama Messages API. Cada petición tiene como mínimo tres campos: el modelo a usar, el número máximo de tokens de respuesta y el array de mensajes de la conversación.

import anthropic

# El SDK coge la API key de la variable de entorno ANTHROPIC_API_KEY
cliente = anthropic.Anthropic()

mensaje = cliente.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Explícame qué es la API de Claude en dos párrafos, en español."
        }
    ]
)

# El texto de la respuesta está en el primer bloque de contenido
print(mensaje.content[0].text)

Si todo está bien configurado, deberías ver la respuesta de Claude en la terminal en pocos segundos. Así de sencillo es el flujo básico.

Los modelos disponibles: Haiku, Sonnet y Opus

Anthropic organiza sus modelos en tres niveles con distinto equilibrio entre velocidad, capacidad y coste:

Para empezar, claude-sonnet-4-5 es la elección correcta en la mayoría de casos: ofrece una capacidad excelente a un precio razonable.

Paso 4: conversaciones multi-turno

La Messages API es stateless: no guarda historial entre peticiones. Para implementar una conversación, tienes que enviar el historial completo en cada llamada:

import anthropic

cliente = anthropic.Anthropic()

# Historial de la conversación (lo gestionas tú)
historial = []

def chat(mensaje_usuario: str) -> str:
    historial.append({"role": "user", "content": mensaje_usuario})

    respuesta = cliente.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=2048,
        system="Eres un asistente experto en Python. Respondes siempre en español.",
        messages=historial
    )

    texto = respuesta.content[0].text
    historial.append({"role": "assistant", "content": texto})
    return texto

# Ejemplo de conversación
print(chat("¿Qué es un decorador en Python?"))
print(chat("¿Puedes mostrarme un ejemplo práctico?"))

Fíjate en el parámetro system: es el system prompt, las instrucciones que Claude recibirá antes del primer mensaje del usuario. Es donde defines el comportamiento, el tono y las restricciones de tu asistente.

Paso 5: tool use (llamadas a función)

Una de las capacidades más potentes de la API es el tool use, que permite a Claude decidir cuándo llamar a funciones externas. Defines las tools con un schema JSON y Claude devuelve una respuesta estructurada cuando quiere invocar alguna:

import anthropic, json

cliente = anthropic.Anthropic()

# Definimos una tool para consultar el tiempo
tools = [
    {
        "name": "obtener_tiempo",
        "description": "Devuelve el tiempo actual de una ciudad española",
        "input_schema": {
            "type": "object",
            "properties": {
                "ciudad": {
                    "type": "string",
                    "description": "Nombre de la ciudad (ej: Madrid, Barcelona)"
                }
            },
            "required": ["ciudad"]
        }
    }
]

respuesta = cliente.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "¿Qué tiempo hace en Sevilla?"}]
)

# Si Claude quiere usar la tool:
if respuesta.stop_reason == "tool_use":
    for bloque in respuesta.content:
        if bloque.type == "tool_use":
            print(f"Claude quiere llamar a: {bloque.name}")
            print(f"Con parámetros: {json.dumps(bloque.input, ensure_ascii=False)}")

Streaming: respuestas en tiempo real

Para mostrar la respuesta de forma progresiva (como en claude.ai), usa el método stream:

import anthropic

cliente = anthropic.Anthropic()

with cliente.messages.stream(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Escribe un poema corto sobre el mar."}]
) as stream:
    for fragmento in stream.text_stream:
        print(fragmento, end="", flush=True)
print()  # Salto de línea al terminar

Gestión de costes y límites de uso

La API de Claude cobra por tokens: por cada 1 000 tokens de entrada y por cada 1 000 tokens de salida (los precios exactos están en la web de Anthropic y varían por modelo). Para controlar el gasto:

• Configura un límite de gasto mensual en Anthropic Console.
• Usa max_tokens siempre para evitar respuestas innecesariamente largas.
• Usa Haiku para tareas de alto volumen y reserva Sonnet/Opus para las complejas.
• Activa prompt caching si envías el mismo system prompt en muchas peticiones: puedes reducir el coste en tokens de entrada hasta un 90%.

Si quieres profundizar en los aspectos más avanzados de la API (visión, documentos, prompt caching, batch API), te recomendamos empezar por nuestra guía gratuita de Claude y dar el salto al curso completo, donde tratamos todos estos temas con proyectos prácticos.

Errores comunes al empezar

• AuthenticationError: la API key no está bien configurada. Comprueba la variable de entorno con echo $ANTHROPIC_API_KEY.
• OverloadedError: los servidores de Anthropic están bajo carga alta. Implementa retry con backoff exponencial.
• max_tokens demasiado bajo: la respuesta se corta. Aumenta el valor o implementa streaming.
• Context window excedido: el historial de conversación es demasiado largo. Usa estrategias de resumen o ventana deslizante.

Para conectar la API con herramientas externas de forma estandarizada, lee también nuestro artículo sobre ¿Qué es MCP (Model Context Protocol)?. Y si quieres usar Claude directamente como agente de programación en tu terminal, consulta Qué es Claude Code.