Integración de la API de Claude en tu aplicación

Una integración de la API de Claude es sencilla el primer día: instalar un SDK y realizar una llamada autenticada. Pero lo que determina si está lista para producción es todo lo que rodea esa llamada: streaming, reintentos, presupuestos de tokens y observabilidad. Esta guía cubre todo el proceso, con código funcional que puedes adaptar directamente.

Autenticación y tu primera solicitud

Instala el SDK oficial (pip install anthropic o npm install @anthropic-ai/sdk), guarda tu clave en una variable de entorno —nunca en el código fuente— y realiza una llamada a la API de mensajes para comprobar el flujo completo. La API se versiona mediante una cabecera anthropic-version que los SDK configuran por ti.

Las claves funcionan igual tanto si proceden de Anthropic Console como de una pasarela compatible con Anthropic, como AI Prime Tech (un servicio independiente, no afiliado a Anthropic): la única diferencia es el base_url con el que se crea tu cliente.

Elegir modelos según la tarea

Las integraciones que fijan un único modelo en el código gastan de más o rinden por debajo de lo esperado. Enruta según la tarea: Haiku 4.5 para clasificación, extracción y enrutamiento; Sonnet 4.6 para la mayoría de las funciones del producto y la programación; Opus 4.8 cuando la profundidad del razonamiento es el producto; Fable 5 cuando necesitas la ventana de contexto de 1M. Consulta la comparación completa en <a href="/es/learn/claude-api-models-compared/">Comparación de modelos Claude</a>.

Define el modelo como un valor de configuración, no como una constante: los nombres de los modelos cambian cada pocos meses y querrás hacer pruebas A/B con las nuevas versiones sin realizar un despliegue.

Streaming, tiempos de espera y reintentos

Usa streaming para cualquier respuesta que una persona vea: los eventos enviados por el servidor entregan los tokens a medida que se generan, lo que reduce la latencia percibida de varios segundos a menos de un segundo. Las llamadas sin streaming con valores altos de max_tokens también tienen más probabilidades de agotar el tiempo de espera de lectura del proxy, un tipo de error que solo aparece en producción.

Reintenta las respuestas 429 y 5xx con espera exponencial y variación aleatoria, respeta las cabeceras retry-after cuando estén presentes y limita el total de intentos. Trata las respuestas 400 como errores permanentes: el propio cuerpo de la solicitud es incorrecto (a menudo por una entrada demasiado grande; consulta <a href="/es/learn/claude-api-errors-troubleshooting/">Errores de la API de Claude</a>) y reintentar solo consume cuota.

Lista de comprobación para producción

Antes del lanzamiento: límites de tokens aplicados tanto a la entrada como a la salida; registro del coste por solicitud (el uso se devuelve en cada respuesta); caché de prompts habilitada para los prompts de sistema repetidos; un modelo o endpoint alternativo para incidentes; y revisión de inyección de prompts si la entrada del usuario llega al prompt.

La mayoría de los problemas de integración no proceden de la propia API, sino del crecimiento ilimitado del contexto y de la falta de observabilidad. Registra los tokens de entrada y salida desde el primer día y desaparecerán las sorpresas en los costes.

import os, anthropic

client = anthropic.Anthropic(
    api_key=os.environ["ANTHROPIC_API_KEY"],
    base_url=os.environ.get("ANTHROPIC_BASE_URL", "https://aiprimetech.io"),
)

with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Summarize our launch plan in 3 bullets."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Preguntas frecuentes

AI Prime Tech es una pasarela de API independiente. No está afiliada a Anthropic, no cuenta con su respaldo ni es un distribuidor de Anthropic. Claude y los nombres de los modelos relacionados son marcas comerciales de sus respectivos propietarios.