Guía de la API de Claude: Construye Apps con IA usando Claude de Anthropic en 2026

¿Por Qué Elegir la API de Claude?

En 2026, Claude de Anthropic se ha establecido como uno de los modelos de lenguaje más capaces del mercado, especialmente reconocido por su razonamiento complejo, generación de código de calidad y seguimiento preciso de instrucciones. Si estás construyendo una aplicación que necesita procesar lenguaje natural, generar código, analizar documentos o mantener conversaciones inteligentes, la API de Claude es una opción de primer nivel.

Esta guía te lleva desde la configuración inicial hasta la construcción de features avanzadas como streaming, tool use y procesamiento de imágenes.

Modelos Disponibles (Marzo 2026)

Modelo	Velocidad	Costo	Mejor para
claude-opus-4-6	Media	Alto	Razonamiento complejo, código avanzado, análisis profundo
claude-sonnet-4-6	Alta	Medio	Balance ideal: calidad y velocidad para producción
claude-haiku-3-5	Muy alta	Bajo	Clasificación, respuestas cortas, alto volumen

Ventana de contexto: Todos los modelos soportan hasta 200,000 tokens (~150,000 palabras).

Configuración Inicial

Obtener tu API Key

Ve a console.anthropic.com
Crea una cuenta o inicia sesión
En el menú lateral, selecciona API Keys
Haz clic en Create Key y guárdala en un lugar seguro

Nunca incluyas la API key directamente en tu código. Úsala siempre como variable de entorno.

# En tu terminal (o en tu archivo .bashrc/.zshrc)
export ANTHROPIC_API_KEY="sk-ant-api03-..."

# Si usas un archivo .env
echo "ANTHROPIC_API_KEY=sk-ant-api03-..." >> .env
# Y asegúrate de que .env esté en tu .gitignore

Instalación de SDKs

# Python
pip install anthropic

# TypeScript/JavaScript
npm install @anthropic-ai/sdk

# Verificar instalación
python -c "import anthropic; print(anthropic.__version__)"

Primer Request: Mensaje Básico

Python

import anthropic

# El cliente lee ANTHROPIC_API_KEY del entorno automáticamente
client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Explica qué es un closure en JavaScript con un ejemplo práctico."
        }
    ]
)

# Acceder al texto de la respuesta
print(response.content[0].text)

# Información de uso (tokens)
print(f"Tokens de entrada: {response.usage.input_tokens}")
print(f"Tokens de salida: {response.usage.output_tokens}")

TypeScript

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

const client = new Anthropic();
// También lee ANTHROPIC_API_KEY del entorno

const response = await client.messages.create({
  model: "claude-opus-4-6",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: "Explica qué es un closure en JavaScript con un ejemplo práctico.",
    },
  ],
});

const text = response.content[0];
if (text.type === "text") {
  console.log(text.text);
}

System Prompt: Definiendo el Comportamiento

El system prompt establece el contexto, el rol y las instrucciones permanentes para Claude.

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    system="""Eres el asistente técnico de ToolBox Hub, una plataforma para desarrolladores.

Tu función:
- Responder preguntas técnicas sobre herramientas de desarrollo
- Proporcionar ejemplos de código cuando sea útil
- Ser directo y conciso; los desarrolladores valoran la eficiencia
- Si no sabes algo, decirlo claramente en lugar de inventar
- Responder siempre en español

Restricciones:
- No dar consejos que puedan comprometer la seguridad
- No escribir código malicioso bajo ninguna circunstancia""",
    messages=[
        {"role": "user", "content": "¿Cómo configuro rate limiting en FastAPI?"}
    ]
)

Conversaciones Multi-turno

Mantén el historial de la conversación pasándolo en cada request:

from anthropic import Anthropic
from typing import TypedDict

class Message(TypedDict):
    role: str
    content: str

client = Anthropic()

class Chatbot:
    def __init__(self, system_prompt: str = ""):
        self.system = system_prompt
        self.history: list[Message] = []

    def chat(self, user_message: str) -> str:
        # Añadir mensaje del usuario al historial
        self.history.append({
            "role": "user",
            "content": user_message
        })

        response = client.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=2048,
            system=self.system,
            messages=self.history
        )

        assistant_message = response.content[0].text

        # Añadir respuesta al historial
        self.history.append({
            "role": "assistant",
            "content": assistant_message
        })

        return assistant_message

    def clear_history(self):
        self.history = []


# Uso
bot = Chatbot(system_prompt="Eres un experto en Python. Responde en español.")
print(bot.chat("¿Qué son los decoradores en Python?"))
print(bot.chat("¿Puedes mostrarme cómo crear uno personalizado?"))
print(bot.chat("¿Y cómo se combina con functools.wraps?"))

Streaming: Respuestas en Tiempo Real

Para mejorar la experiencia de usuario en interfaces de chat, el streaming muestra las respuestas a medida que se generan:

# Python: Streaming síncrono
import anthropic

client = anthropic.Anthropic()

print("Respuesta de Claude: ", end="", flush=True)

with client.messages.stream(
    model="claude-opus-4-6",
    max_tokens=2048,
    messages=[
        {
            "role": "user",
            "content": "Escribe un tutorial paso a paso sobre Docker Compose."
        }
    ]
) as stream:
    for text_chunk in stream.text_stream:
        print(text_chunk, end="", flush=True)

print()  # Nueva línea al final
final_message = stream.get_final_message()
print(f"\nTokens totales: {final_message.usage.input_tokens + final_message.usage.output_tokens}")

// TypeScript: Streaming con Server-Sent Events (ideal para APIs web)
import Anthropic from "@anthropic-ai/sdk";
import { NextResponse } from "next/server";

const client = new Anthropic();

export async function POST(request: Request) {
  const { message } = await request.json();

  const encoder = new TextEncoder();
  const stream = new ReadableStream({
    async start(controller) {
      const anthropicStream = client.messages.stream({
        model: "claude-sonnet-4-6",
        max_tokens: 2048,
        messages: [{ role: "user", content: message }],
      });

      for await (const event of anthropicStream) {
        if (
          event.type === "content_block_delta" &&
          event.delta.type === "text_delta"
        ) {
          controller.enqueue(
            encoder.encode(`data: ${JSON.stringify({ text: event.delta.text })}\n\n`)
          );
        }
      }

      controller.enqueue(encoder.encode("data: [DONE]\n\n"));
      controller.close();
    },
  });

  return new NextResponse(stream, {
    headers: {
      "Content-Type": "text/event-stream",
      "Cache-Control": "no-cache",
      Connection: "keep-alive",
    },
  });
}

Tool Use: Conectando Claude con el Mundo Real

Tool Use permite que Claude llame funciones de tu código para obtener datos en tiempo real o ejecutar acciones.

import anthropic
import json
from datetime import datetime

client = anthropic.Anthropic()

# Definir las herramientas disponibles
tools = [
    {
        "name": "buscar_documentacion",
        "description": "Busca en la documentación de ToolBox Hub. Úsalo cuando el usuario pregunte sobre herramientas o funcionalidades específicas.",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "El término o pregunta a buscar"
                },
                "categoria": {
                    "type": "string",
                    "enum": ["herramientas", "tutoriales", "api", "precios"],
                    "description": "Categoría de la documentación"
                }
            },
            "required": ["query"]
        }
    },
    {
        "name": "obtener_precio_herramienta",
        "description": "Obtiene el precio actual de una herramienta específica",
        "input_schema": {
            "type": "object",
            "properties": {
                "nombre_herramienta": {
                    "type": "string",
                    "description": "Nombre de la herramienta (e.g., 'cursor', 'github-copilot')"
                }
            },
            "required": ["nombre_herramienta"]
        }
    }
]

# Implementaciones de las herramientas
def buscar_documentacion(query: str, categoria: str = "herramientas") -> str:
    # En producción, aquí iría una búsqueda real en tu BD o vectorstore
    return json.dumps({
        "resultados": [
            {"titulo": f"Guía de {query}", "url": f"/docs/{query.lower().replace(' ', '-')}"},
        ],
        "total": 1
    })

def obtener_precio_herramienta(nombre_herramienta: str) -> str:
    precios = {
        "cursor": {"plan_gratis": "$0", "pro": "$20/mes", "business": "$40/usuario/mes"},
        "github-copilot": {"individual": "$10/mes", "business": "$19/usuario/mes"},
    }
    precio = precios.get(nombre_herramienta.lower(), {"error": "Herramienta no encontrada"})
    return json.dumps(precio)

def ejecutar_herramienta(nombre: str, parametros: dict) -> str:
    if nombre == "buscar_documentacion":
        return buscar_documentacion(**parametros)
    elif nombre == "obtener_precio_herramienta":
        return obtener_precio_herramienta(**parametros)
    return json.dumps({"error": f"Herramienta {nombre} no encontrada"})

# Loop del agente
def agente_asistente(pregunta_usuario: str) -> str:
    messages = [{"role": "user", "content": pregunta_usuario}]

    while True:
        response = client.messages.create(
            model="claude-opus-4-6",
            max_tokens=2048,
            tools=tools,
            messages=messages
        )

        if response.stop_reason == "tool_use":
            # Procesar llamadas a herramientas
            tool_calls = [b for b in response.content if b.type == "tool_use"]
            tool_results = []

            for tool_call in tool_calls:
                resultado = ejecutar_herramienta(tool_call.name, tool_call.input)
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": tool_call.id,
                    "content": resultado
                })

            # Añadir respuesta del asistente y resultados al historial
            messages.append({"role": "assistant", "content": response.content})
            messages.append({"role": "user", "content": tool_results})

        else:
            # Respuesta final
            return response.content[0].text

# Ejemplo de uso
respuesta = agente_asistente("¿Cuánto cuesta Cursor IDE?")
print(respuesta)

Procesamiento de Imágenes (Vision)

Claude puede analizar imágenes: wireframes, screenshots, diagramas, fotos.

import anthropic
import base64
from pathlib import Path

client = anthropic.Anthropic()

def analizar_imagen(imagen_path: str, pregunta: str) -> str:
    # Leer y codificar la imagen
    imagen_bytes = Path(imagen_path).read_bytes()
    imagen_base64 = base64.standard_b64encode(imagen_bytes).decode("utf-8")

    # Determinar el tipo MIME
    extension = Path(imagen_path).suffix.lower()
    mime_types = {
        ".jpg": "image/jpeg",
        ".jpeg": "image/jpeg",
        ".png": "image/png",
        ".gif": "image/gif",
        ".webp": "image/webp"
    }
    media_type = mime_types.get(extension, "image/png")

    response = client.messages.create(
        model="claude-opus-4-6",
        max_tokens=2048,
        messages=[
            {
                "role": "user",
                "content": [
                    {
                        "type": "image",
                        "source": {
                            "type": "base64",
                            "media_type": media_type,
                            "data": imagen_base64,
                        }
                    },
                    {
                        "type": "text",
                        "text": pregunta
                    }
                ]
            }
        ]
    )

    return response.content[0].text

# Casos de uso
analisis_ui = analizar_imagen(
    "screenshot_app.png",
    "Revisa este diseño de UI. ¿Qué problemas de usabilidad ves? ¿Qué mejorarías?"
)

analisis_error = analizar_imagen(
    "error_log.png",
    "Analiza este stack trace y explica cuál es el error y cómo solucionarlo."
)

Manejo de Errores y Resilencia

from anthropic import Anthropic, APIError, RateLimitError, APIConnectionError
import time
import logging

logger = logging.getLogger(__name__)

def llamar_api_con_reintentos(
    client: Anthropic,
    **kwargs,
    max_reintentos: int = 3,
    backoff_base: float = 2.0
) -> str:
    """Llama a la API con reintentos y backoff exponencial."""
    for intento in range(max_reintentos):
        try:
            response = client.messages.create(**kwargs)
            return response.content[0].text

        except RateLimitError:
            if intento < max_reintentos - 1:
                tiempo_espera = backoff_base ** intento
                logger.warning(f"Rate limit alcanzado. Esperando {tiempo_espera}s...")
                time.sleep(tiempo_espera)
            else:
                raise

        except APIConnectionError as e:
            logger.error(f"Error de conexión: {e}")
            if intento < max_reintentos - 1:
                time.sleep(backoff_base)
            else:
                raise

        except APIError as e:
            logger.error(f"Error de API: {e.status_code} - {e.message}")
            raise  # No reintentar errores 4xx (excepto rate limit)

    raise Exception("Máximo de reintentos alcanzado")

Optimización de Costos

def elegir_modelo(tipo_tarea: str, longitud_esperada: str = "media") -> str:
    """Selecciona el modelo más eficiente para cada tipo de tarea."""
    if tipo_tarea in ["clasificacion", "extraccion_simple", "moderacion"]:
        return "claude-haiku-3-5"   # Rápido y barato para tareas simples

    elif tipo_tarea in ["chat_general", "resumen", "traduccion", "codigo_simple"]:
        return "claude-sonnet-4-6"  # Equilibrio para producción

    elif tipo_tarea in ["analisis_profundo", "codigo_complejo", "razonamiento", "investigacion"]:
        return "claude-opus-4-6"    # Máxima calidad cuando importa

    return "claude-sonnet-4-6"      # Default seguro

Conclusión

La API de Claude te da acceso a uno de los modelos de lenguaje más capaces disponibles hoy. Con esta guía puedes:

Integrar IA en cualquier aplicación con solo unas pocas líneas de código
Crear chatbots inteligentes con memoria de conversación
Construir agentes que usan herramientas externas para obtener datos en tiempo real
Procesar imágenes para análisis visual automatizado
Hacer streaming para interfaces de usuario más responsivas

El siguiente paso es explorar la documentación oficial en docs.anthropic.com y experimentar con los modelos disponibles en tu caso de uso específico. La mejor forma de aprender es construir: elige un proyecto pequeño y ponlo en marcha esta semana.