Integrar la API de Claude en tu aplicación web

Introducción

La API de Claude de Anthropic permite integrar inteligencia artificial avanzada en cualquier aplicación web. En este tutorial construiremos una integración completa usando fetch() nativo, sin SDKs adicionales.

Cubriremos desde la llamada más básica hasta funcionalidades avanzadas como streaming y tool use.

Prerrequisitos

Antes de empezar necesitas:

1. Una cuenta en console.anthropic.com
2. Una API key activa
3. Node.js 18+ (para usar fetch nativo en el backend)

Importante: Nunca expongas tu API key en el frontend. Siempre haz las llamadas desde tu backend.

Tu primera llamada a la API

La API de Claude usa el endpoint /v1/messages. Cada llamada necesita tres headers obligatorios:

• Content-Type: application/json
• x-api-key: Tu clave de API
• anthropic-versión: Version de la API (usa 2023-06-01)

El body requiere al mínimo: model, max_tokens y messages.

Modelos disponibles

Modelo	Uso ideal	Velocidad	Capacidad
claude-opus-4-20250514	Tareas complejas, razonamiento profundo	Moderada	Maxima
claude-sonnet-4-20250514	Balance general	Rapida	Alta
claude-haiku-3-5-20241022	Tareas rapidas, alto volumen	Muy rápida	Buena

Anatomia de la respuesta

La respuesta de la API tiene esta estructura:

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "TypeScript es un superset de JavaScript..."
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 12,
    "output_tokens": 156
  }
}

Puntos clave:

• content es un array (puede contener texto y/o tool_use)
• usage te dice cuantos tokens consumiste (importante para costos)
• stop_reason indica por que el modelo dejo de generar

Streaming: respuestas en tiempo real

Para mejorar la experiencia del usuario, puedes usar streaming. En lugar de esperar la respuesta completa, recibes tokens a medida que se generan.

Solo necesitas agregar stream: true al body de la petición. La respuesta será un stream de Server-Sent Events (SSE).

Tipos de eventos del stream

Evento	Descripcion
message_start	Inicio del mensaje con metadata
content_block_start	Inicio de un bloque de contenido
content_block_delta	Fragmento de texto (el contenido real)
content_block_stop	Fin del bloque
message_delta	Actualizacion final con stop_reason y usage
message_stop	Fin del mensaje

System prompts

El system prompt define el comportamiento del modelo. Es ideal para establecer el contexto de tu aplicación:

const response = await fetch('https://api.anthropic.com/v1/messages', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.ANTHROPIC_API_KEY,
    'anthropic-versión': '2023-06-01'
  },
  body: JSON.stringify({
    model: 'claude-sonnet-4-20250514',
    max_tokens: 1024,
    system: 'Eres un tutor de programación. Responde en español. Usa ejemplos de código cuando sea relevante.',
    messages: [
      { role: 'user', content: 'Como uso map en JavaScript?' }
    ]
  })
});

Conversaciones multi-turno

Para mantener una conversacion, pasa todo el historial de mensajes:

const messages = [
  { role: 'user', content: 'Que es una Promise?' },
  { role: 'assistant', content: 'Una Promise es un objeto que representa...' },
  { role: 'user', content: 'Dame un ejemplo práctico' }
];

const response = await fetch('https://api.anthropic.com/v1/messages', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.ANTHROPIC_API_KEY,
    'anthropic-versión': '2023-06-01'
  },
  body: JSON.stringify({
    model: 'claude-sonnet-4-20250514',
    max_tokens: 1024,
    messages
  })
});

Claude recordara todo el contexto de la conversacion.

Tool Use: extiende las capacidades de Claude

Tool Use permite que Claude llame funciones que tu defines. Esto es extremadamente poderoso para conectar Claude con APIs externas, bases de datos o cualquier lógica de negocio.

Flujo de Tool Use

1. Defines las herramientas disponibles con su schema
2. Envias la pregunta del usuario
3. Claude decide si necesita usar una herramienta
4. Si la usa, te devuelve el nombre y parametros
5. Tu ejecutas la función y envias el resultado de vuelta
6. Claude genera la respuesta final con ese resultado

Manejo de errores en producción

Un wrapper robusto para producción debe manejar errores, reintentos y rate limiting:

async function callClaudeWithRetry(messages, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch('https://api.anthropic.com/v1/messages', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'x-api-key': process.env.ANTHROPIC_API_KEY,
          'anthropic-versión': '2023-06-01'
        },
        body: JSON.stringify({
          model: 'claude-sonnet-4-20250514',
          max_tokens: 1024,
          messages
        })
      });

      if (response.status === 429) {
        const retryAfter = response.headers.get('retry-after') || '30';
        const waitMs = parseInt(retryAfter) * 1000;
        console.log(`Rate limited. Esperando ${retryAfter}s...`);
        await new Promise(r => setTimeout(r, waitMs));
        continue;
      }

      if (response.status === 529) {
        const waitMs = Math.pow(2, attempt) * 1000;
        console.log(`API sobrecargada. Reintento en ${waitMs}ms...`);
        await new Promise(r => setTimeout(r, waitMs));
        continue;
      }

      if (!response.ok) {
        const error = await response.json();
        throw new Error(`API Error ${response.status}: ${error.error.message}`);
      }

      return await response.json();
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      const waitMs = Math.pow(2, attempt) * 1000;
      await new Promise(r => setTimeout(r, waitMs));
    }
  }
}

Seguridad y mejores prácticas

Protege tu API key

• Almacenala en variables de entorno, nunca en el código
• Usa un backend como proxy entre tu frontend y la API
• Rota las keys periodicamente

Controla los costos

function estimateCost(inputTokens, outputTokens, model) {
  const pricing = {
    'claude-sonnet-4-20250514': { input: 3, output: 15 },
    'claude-haiku-3-5-20241022': { input: 0.25, output: 1.25 }
  };

  const rates = pricing[model];
  const inputCost = (inputTokens / 1_000_000) * rates.input;
  const outputCost = (outputTokens / 1_000_000) * rates.output;

  return { inputCost, outputCost, total: inputCost + outputCost };
}

Valida el input del usuario

Siempre sanitiza y válida el input antes de enviarlo a la API. Limita la longitud máxima y filtra contenido no deseado.

Conclusion

Integrar la API de Claude con fetch() nativo es directo y no requiere dependencias adicionales. Los conceptos clave son: llamadas básicas, streaming para mejor UX, tool use para extender capacidades y manejo robusto de errores para producción.

Empieza con llamadas simples, agrega streaming cuando mejores la UX y explora tool use cuando necesites conectar Claude con tus sistemas.

// Llamada básica a la API de Claude con fetch
async function askClaude(question) {
  const response = await fetch('https://api.anthropic.com/v1/messages', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': process.env.ANTHROPIC_API_KEY,
      'anthropic-versión': '2023-06-01'
    },
    body: JSON.stringify({
      model: 'claude-sonnet-4-20250514',
      max_tokens: 1024,
      messages: [
        { role: 'user', content: question }
      ]
    })
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`API Error: ${error.error.message}`);
  }

  const data = await response.json();
  return data.content[0].text;
}

// Uso
const answer = await askClaude('Que es TypeScript?');
console.log(answer);

// Streaming de respuestas con fetch + ReadableStream
async function streamClaude(question, onChunk) {
  const response = await fetch('https://api.anthropic.com/v1/messages', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': process.env.ANTHROPIC_API_KEY,
      'anthropic-versión': '2023-06-01'
    },
    body: JSON.stringify({
      model: 'claude-sonnet-4-20250514',
      max_tokens: 1024,
      stream: true,
      messages: [
        { role: 'user', content: question }
      ]
    })
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const text = decoder.decode(value);
    const lines = text.split('\n').filter(l => l.startsWith('data: '));

    for (const line of lines) {
      const json = JSON.parse(line.slice(6));
      if (json.type === 'content_block_delta') {
        onChunk(json.delta.text);
      }
    }
  }
}

// Uso: mostrar texto progresivamente
let fullResponse = '';
await streamClaude('Explica async/await', (chunk) => {
  fullResponse += chunk;
  process.stdout.write(chunk);
});

// Tool Use: Claude puede llamar funciones que tu defines
async function claudeWithTools(question) {
  const response = await fetch('https://api.anthropic.com/v1/messages', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': process.env.ANTHROPIC_API_KEY,
      'anthropic-versión': '2023-06-01'
    },
    body: JSON.stringify({
      model: 'claude-sonnet-4-20250514',
      max_tokens: 1024,
      tools: [{
        name: 'get_weather',
        description: 'Obtiene el clima actual de una ciudad',
        input_schema: {
          type: 'object',
          properties: {
            city: {
              type: 'string',
              description: 'Nombre de la ciudad'
            }
          },
          required: ['city']
        }
      }],
      messages: [
        { role: 'user', content: question }
      ]
    })
  });

  const data = await response.json();

  // Verificar si Claude quiere usar una herramienta
  const toolUse = data.content.find(c => c.type === 'tool_use');
  if (toolUse) {
    console.log(`Claude quiere llamar: ${toolUse.name}`);
    console.log(`Con parametros:`, toolUse.input);
  }

  return data;
}