Cómo integrar la API de Claude en tu app

Para integrar la API de Claude, crea una clave de API en la consola de Claude de Anthropic, guárdala como secreto del servidor (normalmente ANTHROPIC_API_KEY) y llama a la Messages API desde una ruta de tu propio servidor usando uno de los SDK oficiales de Anthropic. Cada petición indica un modelo, define max_tokens (la respuesta más larga que aceptarás) y envía la conversación como messages, con tus instrucciones en un system prompt aparte. Establece un límite de gasto, transmite las respuestas largas en streaming y gestiona los errores de límite de frecuencia (429) y de sobrecarga (529) con reintentos.

Esta guía cubre la configuración, un flujo de petición seguro, prompts para un constructor de apps con IA y los errores que hay que prever. Los detalles de Anthropic proceden de su documentación a septiembre de 2026. Para saber cómo funcionan en general los tokens y los precios, consulta cómo usar las APIs de LLM.

Qué puedes construir con ella

• Asistentes de chat y widgets de ayuda (cómo crear una app de chatbot con IA)
• Resúmenes, reescrituras y respuestas redactadas
• Extracción de campos de documentos, correos y formularios
• Respuestas a preguntas a partir de tu propio contenido
• Agentes que llaman a las funciones de tu app mediante uso de herramientas (tool use)

Para más ideas, consulta cómo añadir funciones de IA a tu app.

La Messages API en pocas palabras

Según la referencia de la API de Anthropic, una petición es un POST a https://api.anthropic.com/v1/messages con:

La API no guarda estado: para continuar una conversación, envía de nuevo los turnos anteriores en cada petición. Por eso las conversaciones largas cuestan más por mensaje.

Anthropic publica SDK oficiales para Python, TypeScript, C#, Go, Java, PHP y Ruby. Configuran las cabeceras, procesan las respuestas y admiten streaming. Úsalos en lugar de HTTP directo salvo que tengas un motivo para no hacerlo.

Elegir un modelo

Anthropic ofrece varios modelos de Claude que equilibran capacidad, velocidad y precio, y la oferta cambia. Elige el modelo más pequeño que haga bien tu tarea, pruébalo con ejemplos reales y guarda el ID del modelo en la configuración para poder cambiarlo sin tocar el código. Consulta las páginas de modelos y precios de Anthropic para ver las opciones y tarifas vigentes.

Configurar tu cuenta

1. Inicia sesión en la consola de Claude en platform.claude.com y añade la facturación.
2. Crea una clave de API. Usa una clave por entorno (pruebas y producción) para poder revocar una sin romper la otra.
3. Establece un límite de gasto. La página de errores de Anthropic indica que, cuando el uso alcanza un límite de gasto que hayas fijado, la API devuelve un error 400; tu app debería mostrar un mensaje claro en ese caso.
4. Revisa los límites de frecuencia de tu cuenta en la consola; se miden por organización.

El flujo de la petición

1. El usuario actúa en tu app: envía un mensaje o hace clic en «Resumir».
2. El navegador llama a tu ruta del servidor, nunca directamente a Anthropic.
3. Tu servidor comprueba que el usuario ha iniciado sesión y tiene permiso para usar la función, y aplica un límite por usuario.
4. Construye la petición: un system prompt con tus reglas, la entrada del usuario y los datos que la tarea necesite de tu base de datos.
5. Llama a la Messages API con la clave del entorno y un max_tokens razonable.
6. Envía la respuesta al navegador en streaming y registra el uso de tokens que devuelve la respuesta.

Opciones y compromisos

Prompts para dar a tu constructor de apps con IA

Una primera función:

Añade un panel «Pregunta sobre este documento». Llama a una ruta del servidor POST /api/ask que comprueba que el usuario ha iniciado sesión y que es propietario del documento, y después llama a la Messages API de Claude con el SDK oficial de Anthropic y el secreto ANTHROPIC_API_KEY. Lee el ID del modelo del secreto CLAUDE_MODEL. System prompt: «Responde solo a partir del documento proporcionado. Si la respuesta no está en él, dilo». Envía el texto del documento y la pregunta, pon max_tokens en 800, transmite la respuesta a la página y nunca expongas la clave en el navegador.

Salvaguardas y errores:

Limita a cada usuario a 20 preguntas por hora, guardadas en la base de datos. Registra los tokens de entrada y salida de cada respuesta junto con el ID de usuario y el ID de la petición. Ante errores 429 o 529, reintenta con espera exponencial hasta 3 veces, respetando la cabecera retry-after, y luego muestra «El asistente está ocupado, inténtalo de nuevo en unos minutos». Si la API informa de un error por límite de gasto, muestra «Las funciones de IA están en pausa» y avisa al administrador.

Errores que hay que prever

Según la documentación de errores de Anthropic, estos son los que tu app realmente va a encontrar:

La documentación de Anthropic indica que los SDK oficiales reintentan automáticamente los fallos transitorios (errores de conexión, límites de frecuencia y errores 5xx) dos veces por defecto, con espera exponencial, y que puedes configurar ese comportamiento. Cada respuesta incluye una cabecera request-id; regístrala para que soporte pueda rastrear los problemas.

Errores habituales

• Llamar a la API desde el navegador. Tu clave queda pública. Pasa siempre por tu servidor. Consulta cómo mantener seguras las claves de API.
• Olvidar que max_tokens es un tope, no un objetivo. Ponlo en lo que necesite la función: si es demasiado bajo, las respuestas se cortan; si es demasiado alto, arriesgas respuestas largas y costosas.
• Poner reglas en el mensaje del usuario. Las instrucciones estables van en el system prompt; los permisos, en tu código.
• Enviar todo el chat indefinidamente. Recorta o resume los turnos antiguos a medida que crecen las conversaciones.
• No tener límite de gasto ni tope por usuario.
• Escribir el ID del modelo en el código. Los modelos se actualizan y se retiran.
• Ignorar el motivo de parada. Si la respuesta se detuvo por haber alcanzado max_tokens, avisa al usuario o sube el límite.

Lista de verificación

• Clave de API creada en la consola de Claude y guardada como secreto del servidor
• Claves separadas para pruebas y producción
• Límite de gasto configurado; mensaje claro cuando se alcanza
• Todas las peticiones pasan por tu servidor con comprobación de permisos
• El system prompt contiene las reglas; el ID del modelo es configurable
• max_tokens definido por función; respuestas largas en streaming
• Límite de frecuencia por usuario en tu app
• Errores 429 y 529 gestionados con espera; IDs de petición registrados
• Estado de error amigable que no rompe la página
• Probado con entradas vacías, muy largas y hostiles

Usar la API de Claude en Mythex

En las apps que construyes en Mythex, las funciones de Claude usan tu propia clave de Anthropic y se facturan a tu cuenta de Anthropic, no a los créditos de creación de Mythex. Eso es independiente del agente de Mythex que escribe tu código. Añade ANTHROPIC_API_KEY como secreto del proyecto desde /secrets, la configuración del proyecto o la tarjeta de secretos del chat, y luego describe la función con prompts como los de arriba. Vuelve a publicar tras cambiar los secretos de una app en producción. Consulta Añadir funciones de IA con tus propias claves de API para ver un prompt inicial. Si estás eligiendo entre proveedores, cómo integrar la API de OpenAI explica lo mismo para OpenAI.

Preguntas