Claude API: Crash Course para developers con TypeScript

Hace unos meses un developer me escribió frustrado. Llevaba dos días intentando integrar Claude en su app. No le funcionaba el streaming, no entendía por qué sus respuestas llegaban cortadas, y había probado tres ejemplos distintos de Stack Overflow que usaban versiones diferentes del SDK.

El problema no era la API. Era que había empezado por el medio.

Esta es la Claude API introducción que yo habría querido tener al principio: sin rodeos, con código real, y con el orden correcto para entender qué está pasando antes de que algo falle.

Qué es la Claude API y por qué te importa

Claude es el modelo de lenguaje de Anthropic. La API te da acceso directo a ese modelo desde tu código: puedes enviarle mensajes, pedirle que razone, que use herramientas externas, que responda en streaming o que procese imágenes.

La diferencia respecto a ChatGPT para developers es principalmente la calidad del razonamiento en tareas de código complejas y el system prompt — Claude lo sigue con una precisión que cambia cómo construyes agentes.

Setup: API key y SDK

Primero necesitas una cuenta en console.anthropic.com. Una vez dentro, ve a API Keys y genera una nueva clave. Guárdala — no la vuelves a ver.

Instala el SDK oficial con npm o Bun:

npm install @anthropic-ai/sdk
# o con Bun
bun add @anthropic-ai/sdk

Guarda la clave en una variable de entorno. Nunca en el código:

# .env
ANTHROPIC_API_KEY=sk-ant-...

Tu primera llamada en TypeScript

Este es el "Hello World" de la Claude API. Sin clases, sin abstracción, directo al grano:

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

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

async function main() {
  const response = await client.messages.create({
    model: "claude-sonnet-4-6",
    max_tokens: 1024,
    messages: [
      {
        role: "user",
        content: "Explica qué es un closure en JavaScript en 2 líneas.",
      },
    ],
  });

  console.log(response.content[0].type === "text" ? response.content[0].text : "");
}

main();

Eso es todo. Ejecutas esto y tienes una respuesta de Claude en tu terminal.

Lo que necesitas entender de la estructura:

• model — qué versión de Claude usas (más sobre esto abajo)
• max_tokens — límite de tokens en la respuesta (no el total de la conversación)
• messages — array de turnos de conversación con role: "user" o role: "assistant"

Los conceptos que no puedes ignorar

Modelos disponibles

Anthropic tiene tres familias activas:

Modelo	Cuándo usarlo
claude-sonnet-4-6	El equilibrio perfecto: velocidad + calidad. Mi default para casi todo.
claude-haiku-4-5	Más rápido y barato. Bueno para tareas simples o llamadas en volumen.
claude-opus-4-8	El más potente. Para tareas de razonamiento complejo donde el coste no es el problema.

Si estás empezando, usa claude-sonnet-4-6. No pienses más.

System prompt vs User message

El system es la personalidad y las instrucciones permanentes de Claude. El user es lo que cambia en cada turno.

const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  system: "Eres un reviewer de código senior. Responde siempre en español. Sé directo y señala el problema antes de proponer la solución.",
  messages: [
    {
      role: "user",
      content: "Revisa esta función: function add(a, b) { return a - b; }",
    },
  ],
});

El system prompt es donde ocurre la mayor parte de la magia cuando construyes agentes. Si quieres ver cómo llevamos esto a proyectos reales con Claude Code, en el curso Construye con IA cubrimos exactamente eso: de la idea al producto con agentes que siguen instrucciones de producción.

Tokens: lo que cuesta dinero

Un token es aproximadamente 0,75 palabras en inglés (algo menos en español). La API te cobra por input_tokens (lo que envías) y output_tokens (lo que Claude responde).

Después de cada llamada puedes ver el uso:

console.log(response.usage);
// { input_tokens: 48, output_tokens: 312 }

max_tokens limita la respuesta, no la llamada completa. Si pones max_tokens: 100 y la respuesta necesita 200 tokens, Claude cortará el texto a mitad. Es uno de los errores más comunes al empezar.

¿Cómo implementar streaming con la Claude API en TypeScript?

Sin streaming, esperas a que Claude termine de generar toda la respuesta antes de recibirla. Con streaming, recibes los tokens a medida que se generan — igual que ves escribir a Claude en el chat web.

Para UX en tiempo real, el streaming no es opcional. Es lo que distingue una app que se siente viva de una que "se congela" tres segundos antes de mostrar algo. En los proyectos de agentes que construimos en Labs, migrar de llamada síncrona a streaming eliminó la necesidad de un loader — los usuarios percibieron la respuesta como inmediata sin que cambiáramos nada más.

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

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

async function streamResponse() {
  const stream = await client.messages.create({
    model: "claude-sonnet-4-6",
    max_tokens: 1024,
    stream: true,
    messages: [
      {
        role: "user",
        content: "Escribe un test unitario en TypeScript para una función que suma dos números.",
      },
    ],
  });

  for await (const event of stream) {
    if (
      event.type === "content_block_delta" &&
      event.delta.type === "text_delta"
    ) {
      process.stdout.write(event.delta.text);
    }
  }

  console.log("\n--- Stream completado ---");
}

streamResponse();

El loop for await itera sobre los eventos del stream. El tipo que te importa es content_block_delta con delta.type === "text_delta" — ahí está el texto.

¿Qué es el tool use en Claude API y cómo funciona?

Tool use (o function calling) permite que Claude llame a funciones definidas por ti. Claude decide cuándo usarlas y con qué argumentos. Tú ejecutas la función y le devuelves el resultado.

El siguiente ejemplo define una herramienta get_weather ficticia:

const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  tools: [
    {
      name: "get_weather",
      description: "Obtiene el tiempo actual para una ciudad.",
      input_schema: {
        type: "object",
        properties: {
          city: {
            type: "string",
            description: "El nombre de la ciudad.",
          },
        },
        required: ["city"],
      },
    },
  ],
  messages: [
    {
      role: "user",
      content: "¿Qué tiempo hace en Madrid ahora mismo?",
    },
  ],
});

// Si Claude quiere usar la herramienta, el stop_reason será "tool_use"
if (response.stop_reason === "tool_use") {
  const toolUse = response.content.find((b) => b.type === "tool_use");
  console.log("Claude quiere llamar a:", toolUse?.name);
  console.log("Con argumentos:", toolUse?.input);
  // Aquí ejecutarías la función real y devolverías el resultado a Claude
}

Esto es la base de cualquier agente. Claude no ejecuta código — tú lo ejecutas y le informas del resultado. El loop de razonamiento lo controla Claude; la ejecución la controlas tú. Si quieres ver cómo este patrón escala a un pipeline completo — desde un ticket de Jira hasta el deploy —, tienes el ejemplo en el post sobre automatizar el proceso de desarrollo con IA.

Errores comunes al empezar

Rate limits. La API tiene límites por minuto tanto en requests como en tokens. Si los golpeas, recibes un 429. Solución: exponential backoff o usar Haiku para prototipos de alto volumen.

Context window agotado. Cada modelo tiene un límite de tokens totales en conversación (input + output). Sonnet 4.6 tiene 200K tokens de context window — es enorme, pero si metes archivos enteros en cada llamada, lo llenas. Sé selectivo con lo que incluyes en el contexto.

Formato de mensajes incorrecto. El array messages debe alternar user y assistant. No puedes tener dos mensajes de user seguidos sin un assistant entre medias. Eso devuelve un error 400.

max_tokens demasiado bajo. Si la respuesta se corta, sube max_tokens. El valor por defecto no existe — es un parámetro obligatorio. Empieza con 1024 y ajusta según lo que necesites.

Variables de entorno no cargadas. Si ves AuthenticationError, casi siempre es que ANTHROPIC_API_KEY no está disponible en el proceso. Verifica con console.log(process.env.ANTHROPIC_API_KEY) antes de depurar nada más.

Qué explorar después

Una vez tienes la llamada básica y el streaming funcionando, estos son los siguientes pasos lógicos:

Vision. Puedes enviar imágenes en el array content y Claude las analiza. Útil para screenshots, diagramas, facturas.

Embeddings. Anthropic no tiene embeddings propios en la API, pero Claude funciona muy bien combinado con embeddings de OpenAI o Cohere para búsqueda semántica.

Batch API. Para procesar cientos de prompts sin necesidad de respuesta en tiempo real. Hasta un 50% más barato que llamadas individuales.

Workbench de Anthropic. En console.anthropic.com tienes un playground para probar prompts, comparar modelos y ver el uso de tokens antes de escribir una sola línea de código. Es la herramienta que más uso al diseñar system prompts.

Multiturno real. Construir una conversación que mantenga contexto entre turnos requiere gestionar el array messages manualmente — añadir cada respuesta de Claude como role: "assistant" y cada input del usuario como role: "user". No hay estado en la API.

Si quieres ver tool use aplicado a un workflow de code review automático antes de un PR, tienes el flujo completo en el post sobre agentic code review con Claude Code.

Si tuvieras que elegir solo un área para explorar después del streaming, elige Vision — es el salto de ROI más rápido y el que más impacto tiene en una demo.

---

FAQ

¿Necesito tarjeta de crédito para empezar?
Sí. Anthropic requiere un método de pago para activar la API, pero tiene un tier de prueba con crédito gratuito. Puedes hacer cientos de llamadas de desarrollo sin pagar nada en los primeros días.

¿Cuál es la diferencia entre la API de Claude y Claude.ai?
Claude.ai es el producto de consumo (el chat web). La API es el acceso programático al modelo. Tienen facturación y cuentas separadas. Una suscripción a Claude.ai no te da acceso a la API.

¿Cuánto cuesta en producción?
Depende del modelo y el volumen. Claude Sonnet 4.6 está alrededor de $3 por millón de input tokens y $15 por millón de output tokens — verifica siempre en anthropic.com/pricing antes de hacer estimaciones de arquitectura, los precios se actualizan con cada generación de modelo.

¿Puedo usar la API en el frontend directamente?
Técnicamente sí, pero nunca deberías. La API key quedaría expuesta en el cliente. Siempre llama a la API desde un backend o un serverless function que tú controlas.

¿Qué pasa si Claude no termina la respuesta y stop_reason no es end_turn?
Si stop_reason es max_tokens, la respuesta se cortó por el límite que pusiste. Si es tool_use, Claude quiere ejecutar una herramienta. Si es stop_sequence, alcanzó una secuencia de parada que definiste. Valida siempre stop_reason en producción.

---

Si quieres ver todo esto aplicado en un proyecto real — no en ejemplos de tutorial sino en un producto con usuarios — en Dominicode Labs tenemos el código de los proyectos que construimos en directo, incluyendo agentes con tool use y streaming. Es donde llevamos la teoría a producción.

Y si prefieres el formato video con más ejemplos en directo, en el canal de YouTube de Dominicode cubrimos estas integraciones con frecuencia.

---

Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.