Tutorial de Claude API para Principiantes: Guía Completa de Introducción

TL;DR: La API de Claude le permite integrar los modelos de IA de Anthropic en sus propias aplicaciones. Esta guía lo lleva de cero a código funcional, cubriendo autenticación, su primera llamada API, respuestas en tiempo real, gestión de conversaciones, uso de herramientas y mejores prácticas de producción, con ejemplos listos para copiar y pegar en Python y JavaScript.

¿Qué es la API de Claude?

La API de Claude es la interfaz programática de Anthropic para integrar los modelos de lenguaje de Claude directamente en sus aplicaciones, scripts, flujos de trabajo y productos. En lugar de usar la interfaz web Claude.ai, la API le brinda control programático completo: envía texto, obtiene texto (o datos estructurados) de vuelta, y usted decide exactamente cómo su aplicación lo utiliza.

La API impulsa desde chatbots simples hasta sistemas sofisticados multiagente. Los desarrolladores la utilizan para construir automatización de servicio al cliente, tuberías de análisis de documentos, herramientas de generación de código, sistemas de moderación de contenido, flujos de trabajo de extracción de datos, y mucho más. Cualquier tarea que Claude pueda hacer en un navegador, puede hacerla a través de la API, integrada dentro de su propio producto.

A partir de 2026, la API proporciona acceso a tres familias de modelos principales: Claude Opus 4.7 (más capaz, contexto de 1M de tokens, ideal para razonamiento complejo), Claude Sonnet 4.6 (rendimiento equilibrado y velocidad, mejor para la mayoría de cargas de trabajo de producción), y Claude Haiku 4.5 (más rápido y barato, perfecto para tareas de alto volumen sensibles a la latencia). Cada modelo está disponible a través de un único punto de entrada de API unificado con un formato de solicitud/respuesta consistente.

Los precios se basan en tokens, aproximadamente 750 palabras equivalen a unos 1.000 tokens. Los tokens de entrada (lo que envía) y los tokens de salida (lo que Claude genera) tienen precios separados, siendo la entrada más económica. Una llamada API típica podría usar 500 tokens de entrada y generar 300 tokens de salida, costando fracciones de centavo. La API de Claude es significativamente más rentable para cargas de trabajo de producción que el modelo de precios por asiento a escala.

Si desea experimentar con las capacidades de Claude antes de comprometerse con los costos de la API, FreeClaude proporciona acceso gratuito a Claude Max x20, la misma inteligencia de modelo subyacente, a través de un programa de referidos que no requiere tarjeta de crédito.

Configurando su Entorno

Antes de escribir cualquier código, necesita tres cosas: una cuenta de Anthropic, una clave API e instalar el SDK en su proyecto.

Paso 1: Crear una Cuenta de Anthropic

Visite console.anthropic.com e regístrese. Las cuentas nuevas reciben un saldo de crédito pequeño para pruebas iniciales, típicamente suficiente para cientos de llamadas de prueba. Una vez que se consumen los créditos, agregue un método de pago. Los precios de la API son de pago por uso sin compromiso mínimo.

Paso 2: Generar una Clave API

En la Consola de Anthropic, navegue a Configuración → Claves API → Crear Clave. Asígnele un nombre descriptivo (p. ej., "dev-local"). Copie la clave inmediatamente, se muestra solo una vez. Guárdela en un administrador de contraseñas o administrador de secretos como AWS Secrets Manager. Nunca codifique una clave API en el código fuente.

Paso 3: Instalar el SDK

Anthropic proporciona SDK oficiales para Python y TypeScript/JavaScript. Ambos se mantienen activamente y se sincronizan con los lanzamientos de nuevos modelos.

# Python
pip install anthropic

# Node.js / TypeScript
npm install @anthropic-ai/sdk

Paso 4: Establecer su Clave API como Variable de Entorno

El SDK lee automáticamente la variable de entorno ANTHROPIC_API_KEY:

export ANTHROPIC_API_KEY="sk-ant-..."

Para proyectos usando un archivo .env, instale python-dotenv (Python) o dotenv (Node) y cárguelo al inicio. Agregue .env a .gitignore inmediatamente, nunca confirme credenciales al control de versiones.

Haciendo su Primera Llamada API

Con su entorno configurado, aquí está el código mínimo para hacer una llamada API funcional, el "Hola Mundo" del desarrollo de la API de Claude.

Python

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Explain what an API is in two sentences."}
    ]
)

print(message.content[0].text)

JavaScript / Node.js

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();

const message = await client.messages.create({
  model: 'claude-sonnet-4-6',
  max_tokens: 1024,
  messages: [
    { role: 'user', content: 'Explain what an API is in two sentences.' }
  ]
});

console.log(message.content[0].text);

Desglosando los parámetros clave: model especifica qué modelo de Claude usar. max_tokens limita la longitud de la respuesta, demasiado bajo trunca respuestas, demasiado alto no desperdicia nada a menos que Claude use esos tokens. messages es un array de turnos de conversación, cada uno con un role (user o assistant) y content.

El objeto de respuesta contiene un array de bloques de contenido. Para respuestas de texto estándar, el texto está en message.content[0].text. La respuesta también incluye datos de uso: message.usage.input_tokens y message.usage.output_tokens, útiles para monitorear costos desde el primer día.

Gestión de Conversaciones Multiturno

La API de Claude no tiene estado, no almacena el historial de conversación en el servidor. Su aplicación debe rastrear la conversación y enviar el historial completo con cada solicitud.

import anthropic

client = anthropic.Anthropic()
conversation = []

def chat(user_message):
    conversation.append({"role": "user", "content": user_message})
    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        messages=conversation
    )
    assistant_message = response.content[0].text
    conversation.append({"role": "assistant", "content": assistant_message})
    return assistant_message

print(chat("My name is Alex and I'm learning Python."))
print(chat("What's a good first project for someone like me?"))
print(chat("How long will that take to build?"))

La lista de conversation crece con cada turno, y la lista completa se envía con cada solicitud. Claude recibe el contexto completo y puede hacer referencia a cualquier cosa dicha anteriormente. Para sesiones muy largas, implemente resumir: periódicamente pida a Claude que resuma la conversación, luego reemplace el historial con ese resumen para mantenerse dentro de los límites de ventana de contexto.

Transmisión de Respuestas en Tiempo Real

Por defecto, la API espera hasta que se genera la respuesta completa antes de enviarla. La transmisión en tiempo real resuelve esto, recibe tokens a medida que se generan, habilitando el efecto de máquina de escribir que ve en Claude.ai y mejorando dramáticamente el rendimiento percibido.

Transmisión en Python

import anthropic

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Write a detailed explanation of machine learning."}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
print()

Transmisión en JavaScript

const stream = await client.messages.stream({
  model: 'claude-sonnet-4-6',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Write a detailed explanation of machine learning.' }]
});

for await (const chunk of stream.textStream) {
  process.stdout.write(chunk);
}
console.log();

Una respuesta de 500 palabras tarda aproximadamente 5–8 segundos en generarse. Sin transmisión en tiempo real, los usuarios ven una pantalla en blanco todo el tiempo. Con transmisión en tiempo real, comienzan a leer dentro del primer segundo. El tiempo de generación total es idéntico, pero la experiencia del usuario se transforma. La transmisión en tiempo real es esencial para cualquier aplicación que enfrenta al usuario.

Uso de Herramientas y Llamadas de Función

El uso de herramientas permite que Claude solicite datos de sistemas externos durante la conversación, bases de datos, APIs, sistemas de archivos, permitiéndole trabajar con información en tiempo real y tomar acciones en el mundo.

import anthropic, json

client = anthropic.Anthropic()

tools = [{
    "name": "get_weather",
    "description": "Get current weather for a city",
    "input_schema": {
        "type": "object",
        "properties": {
            "city": {"type": "string", "description": "City name"},
            "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
        },
        "required": ["city"]
    }
}]

def get_weather(city, unit="celsius"):
    return {"temperature": 22, "condition": "sunny", "city": city}

messages = [{"role": "user", "content": "What's the weather in Paris?"}]
response = client.messages.create(
    model="claude-sonnet-4-6", max_tokens=1024, tools=tools, messages=messages
)

if response.stop_reason == "tool_use":
    tool_use = next(b for b in response.content if b.type == "tool_use")
    result = get_weather(**tool_use.input)
    messages.append({"role": "assistant", "content": response.content})
    messages.append({"role": "user", "content": [
        {"type": "tool_result", "tool_use_id": tool_use.id, "content": json.dumps(result)}
    ]})
    final = client.messages.create(
        model="claude-sonnet-4-6", max_tokens=1024, tools=tools, messages=messages
    )
    print(final.content[0].text)

El uso de herramientas permite consultar bases de datos, llamar a API externas, leer y escribir archivos, ejecutar código e integrar con sistemas empresariales. Claude decide cuándo llamar a una herramienta basándose en la solicitud del usuario y la descripción de la herramienta, el texto descriptivo es crucial, ya que Claude lo lee para determinar la relevancia.

Seleccionar el Modelo Claude Correcto

La selección de modelo impacta significativamente tanto el costo como la calidad. Cada modelo tiene un perfil de rendimiento distinto adecuado para casos de uso específicos.

Claude Haiku 4.5 — Más rápido y barato. Mejor para: clasificación, preguntas y respuestas simples, moderación, extracción de datos de texto estructurado, procesamiento por lotes de alto volumen. Tiempo de respuesta bajo 1 segundo para salidas cortas.

Claude Sonnet 4.6 — Mejor equilibrio de capacidad y costo. Maneja: escritura compleja, generación de código, análisis detallado, razonamiento multietapa, chat orientado al cliente. El predeterminado correcto para la mayoría de aplicaciones de producción, calidad casi Opus a costo significativamente menor.

Claude Opus 4.7 — Más capaz, contexto de 1M de tokens. Usar para: síntesis de investigación en documentos muy largos, arquitectura de código compleja, escritura de alto riesgo y tareas donde la calidad del resultado importa más que el costo o la latencia. Cuesta aproximadamente 15 veces más que Haiku, resérvelo para tareas que genuinamente lo necesiten.

Una estrategia práctica de producción: usar Sonnet de forma predeterminada para todas las solicitudes, implementar una capa de enrutamiento que actualice a Opus para solicitudes por encima de un umbral de complejidad (longitud de solicitud, tipo de tarea, solicitud explícita del usuario). Esto optimiza el costo mientras asegura calidad donde más importa.

Mejores Prácticas de Producción

Manejar Errores con Retroceso Exponencial

import anthropic, time

client = anthropic.Anthropic()

def call_with_retry(messages, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.messages.create(
                model="claude-sonnet-4-6",
                max_tokens=1024,
                messages=messages
            )
        except anthropic.RateLimitError:
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)
            else:
                raise
        except anthropic.APIError as e:
            if e.status_code >= 500:
                time.sleep(1)
            else:
                raise

Usar Indicadores del Sistema a través del Parámetro system

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system="You are a concise technical assistant. Respond in plain text, no markdown unless explicitly asked. Keep answers under 200 words.",
    messages=[{"role": "user", "content": user_input}]
)

Rastrear el Uso de Tokens desde el Primer Día

Registre usage.input_tokens y usage.output_tokens de cada respuesta. Esto le permite identificar solicitudes costosas, detectar intentos de inyección de solicitud y pronosticar con precisión el gasto de API mensual. El monitoreo de tokens es mucho más fácil de implementar desde el principio que adaptarlo posteriormente.

Habilitar Almacenamiento en Caché de Solicitudes para Contexto Repetido

Para cargas de trabajo donde un indicador del sistema grande o documento de contexto se reutiliza en muchas solicitudes, habilite el almacenamiento en caché de solicitudes agregando "cache_control": {"type": "ephemeral"} a los bloques de contenido relevantes. Los tokens en caché cuestan significativamente menos que reprocesar el mismo contenido repetidamente, un ahorrador de costos importante para aplicaciones con indicadores del sistema largos.

Implementar Manejo de Límites de Velocidad a Nivel de Aplicación

Incluso con lógica de reintentos, las aplicaciones sostenidas de alto rendimiento necesitan gestión de límites de velocidad basada en colas. Implementar un limitador de tasa de token bucket o ventana deslizante en su capa de aplicación para que nunca llegue a los límites de velocidad de la API en primer lugar, en lugar de confiar completamente en la lógica de reintentos después de ser rechazado.

Preguntas Frecuentes

¿Necesito un plan de pago para usar la API de Claude?

Las cuentas nuevas de Anthropic reciben créditos gratuitos para pruebas iniciales. Más allá de esos créditos, la API es de pago por uso, agregue un método de pago y pague solo por lo que use. No hay suscripción mensual requerida para acceso a la API.

¿Cuál es la diferencia entre la API de Claude y Claude.ai?

Claude.ai es la interfaz web y móvil del consumidor. La API es para desarrolladores que construyen sus propias aplicaciones. Tienen facturación separada. Si desea Claude sin escribir código, FreeClaude proporciona acceso gratuito a Claude Max x20 a través de referidos.

¿Cómo manejo documentos que exceden los límites de contexto?

Para documentos dentro de la ventana de contexto (hasta 1M de tokens con Opus 4.7), incluya el texto completo en la solicitud. Para colecciones más grandes, use generación aumentada por recuperación (RAG): divida documentos, incruste con una base de datos vectorial, y recupere solo secciones relevantes para cada consulta.

¿Puedo usar la API de Claude para aplicaciones comerciales?

Sí. Las políticas de uso de Anthropic permiten el uso comercial sujeto a sus directrices de uso aceptable. Puede construir y vender productos impulsados por la API de Claude siempre que su aplicación cumpla con las políticas de Anthropic y las leyes aplicables.

¿Qué lenguajes de programación admite la API de Claude?

SDK oficiales existen para Python y TypeScript/JavaScript. La API subyacente es una API REST estándar con JSON, por lo que cualquier lenguaje que pueda hacer solicitudes HTTP funciona, Ruby, Go, Java, PHP, Rust y más.

¿Cómo prevengo ataques de inyección de solicitudes?

Las defensas incluyen: separación clara entre instrucciones y contenido de usuario usando etiquetas XML, instrucciones explícitas en el indicador del sistema para ignorar contenido conflictivo en entrada de usuario