Qué es la API de Claude y cuándo conviene usarla

Imagina a Mariana, encargada de ventas de Viajes Kukulcán, una agencia de Mérida. Cada mañana responde por WhatsApp y correo las mismas preguntas: cuánto cuesta el tour a Chichén Itzá, si el traslado a los cenotes de Homún incluye comida, qué llevar a Celestún. Ya probó pegar esas preguntas en Claude desde el navegador y las respuestas le sirven, pero sigue copiando y pegando cien veces al día. Lo que necesita la agencia no es otra pestaña abierta: es que su propio sistema hable con el modelo. Para eso existe la API.

En esta lección no escribimos todavía una llamada real. Primero aclaramos qué es la API, qué la distingue de las apps, cómo se cobra y cómo organizar tu cuenta para que no haya sorpresas en la factura.

Al terminar podrás:

• explicar la diferencia entre la API de Claude y las apps de Claude;
• decidir si un caso concreto conviene resolverlo con la API o con la app;
• estimar el costo de una tarea a partir de tokens de entrada y salida;
• orientarte en la consola: claves, workspaces, límites y facturación.

La API y las apps no son lo mismo

Claude se puede usar de dos maneras muy distintas.

Las apps de Claude (claude.ai en el navegador, escritorio y móvil) son productos terminados. Tienen una interfaz de chat, guardan tus conversaciones, permiten subir archivos y se pagan con un plan para personas o equipos. Están pensadas para que una persona converse con el modelo.

La API de Claude es un servicio para programas. Tu código envía una solicitud HTTP a https://api.anthropic.com/v1/messages con el modelo, las instrucciones y los mensajes, y recibe una respuesta en JSON. No hay interfaz, no hay historial guardado y no hay un plan mensual fijo: pagas por lo que consumes. Todo lo demás (pantallas, base de datos, usuarios, reglas de negocio) lo construyes tú.

Una forma práctica de verlo: la app es un restaurante, la API es la cocina con ingredientes. En el restaurante te sirven el plato como viene. En la cocina decides la receta, la porción y cuántos platos sacas por hora, pero también lavas los trastes.

Cuándo conviene la API

La API tiene sentido cuando se cumple al menos una de estas condiciones:

1. La tarea se repite muchas veces. Clasificar 400 correos de clientes al día, contestar preguntas frecuentes, resumir cada reservación nueva.
2. El resultado debe entrar en otro sistema. Guardar una cotización en tu base de datos, llenar un CRM, generar un PDF con formato fijo.
3. Necesitas control fino. Elegir el modelo exacto, limitar cuántos tokens se gastan, exigir JSON con un esquema, registrar cada llamada.
4. Los usuarios no son tú. Un asistente en el sitio web de la agencia lo usan clientes que nunca verán claude.ai.

La app sigue siendo mejor para trabajo personal y exploratorio: redactar un correo difícil, analizar una hoja de cálculo una sola vez, pensar en voz alta sobre una estrategia. Si la tarea ocurre dos veces al mes y la hace la misma persona, programar una integración rara vez se paga sola.

Para Viajes Kukulcán la respuesta es clara: el asistente que contesta dudas de clientes, lee comprobantes de reservación y prepara cotizaciones encaja en las cuatro condiciones.

Cómo se cobra: tokens

La API cobra por tokens, que son los fragmentos de texto con los que trabaja el modelo. Un token puede ser una palabra corta, parte de una palabra larga o un signo de puntuación. No hay una equivalencia exacta con palabras, y además depende del modelo: la documentación de Anthropic indica que los modelos desde Claude Opus 4.7 usan un tokenizador nuevo que produce aproximadamente un 30 % más de tokens para el mismo texto que los modelos anteriores. También indica que un millón de tokens equivale aproximadamente a 555 mil palabras en inglés con ese tokenizador. En español suelen salir algunos tokens más por palabra, así que mide siempre con tus propios textos (en la lección 2.4 usamos el endpoint de conteo).

Cada llamada tiene dos contadores:

• Tokens de entrada: todo lo que envías. Instrucciones, historial de la conversación, documentos, definiciones de herramientas.
• Tokens de salida: todo lo que genera el modelo, incluido el razonamiento interno cuando el modelo piensa antes de responder.

Los precios se publican en dólares por millón de tokens (MTok), y la salida siempre cuesta más que la entrada. Estos son los precios base de los modelos actuales según la página oficial de precios, consultada en octubre de 2026:

Hay descuentos que veremos más adelante: las solicitudes por lotes cuestan 50 % menos y la lectura de caché de prompts cuesta una fracción del precio de entrada. Los precios cambian con cada generación de modelos, así que antes de presupuestar revisa la página de precios vigente.

Un cálculo rápido

Este script no llama a la API; solo convierte tokens en pesos para que te hagas una idea. Puedes ejecutarlo con cualquier Python 3.10 o superior:

# estimar_costo.py
PRECIOS_USD_POR_MTOK = {
    "claude-opus-5-5": {"entrada": 4.00, "salida": 20.00},
    "claude-sonnet-5-5": {"entrada": 2.00, "salida": 10.00},
    "claude-haiku-5-5": {"entrada": 0.10, "salida": 0.50},
}
TIPO_DE_CAMBIO = 18.5  # pesos por dólar; ajústalo al del día


def costo_mxn(modelo: str, tokens_entrada: int, tokens_salida: int) -> float:
    precio = PRECIOS_USD_POR_MTOK[modelo]
    usd = (tokens_entrada * precio["entrada"] + tokens_salida * precio["salida"]) / 1_000_000
    return usd * TIPO_DE_CAMBIO


# Una respuesta típica del asistente: 1,500 tokens de entrada y 400 de salida
for modelo in PRECIOS_USD_POR_MTOK:
    por_respuesta = costo_mxn(modelo, 1_500, 400)
    al_mes = por_respuesta * 300 * 30  # 300 preguntas diarias durante 30 días
    print(f"{modelo}: {por_respuesta:.4f} MXN por respuesta, {al_mes:,.2f} MXN al mes")

El tipo de cambio es un supuesto tuyo; Anthropic factura en dólares. Lo importante del ejercicio es el orden de magnitud: con estas cifras de ejemplo, la diferencia entre modelos puede ser de decenas de veces. Elegir modelo (lección 1.3) y controlar tokens (lección 2.4) son decisiones de negocio, no detalles técnicos.

La consola: tu centro de control

La API se administra desde la Claude Console, en https://platform.claude.com. Ahí creas tu organización y encuentras:

• API keys (Settings > API keys): las claves con las que tu código se identifica. Al crear una eliges nombre, expiración (por ejemplo 7 o 30 días, una duración propia o sin expiración) y a qué cuenta queda ligada.
• Workbench o playground: un espacio para probar prompts sin escribir código.
• Usage y Cost: gráficas de tokens y gasto por modelo y por workspace.
• Rate limits: los límites de solicitudes y tokens por minuto de tu organización.
• Billing: método de pago, créditos y límites de gasto.

Las apps y la API se facturan por separado. Tener un plan de claude.ai no te da saldo en la consola, y viceversa.

Tipos de clave

La documentación actual distingue tres tipos. La clave personal actúa en tu nombre y deja de funcionar si sales de la organización; sirve para tu desarrollo. La clave de cuenta de servicio pertenece a una identidad técnica que crea un administrador; es la recomendada para servidores y procesos compartidos. La clave de workspace es el tipo antiguo y se considera heredado. Para empezar este curso basta una clave personal.

Workspaces: separar proyectos y entornos

Un workspace es una división dentro de tu organización. Cada organización tiene un workspace por defecto que no se puede renombrar ni borrar, y puedes crear más (hasta 100 por defecto). Sirven para:

• separar entornos: desarrollo, pruebas y producción;
• separar proyectos o equipos y ver el costo de cada uno;
• poner límites de gasto y de tasa por workspace, más bajos que los de la organización.

Para Viajes Kukulcán una estructura razonable sería un workspace "Kukulcán desarrollo" con límites bajos, donde haces todas las prácticas de este curso, y otro "Kukulcán producción" para el asistente real. Si un script de prueba entra en un ciclo infinito, el daño queda acotado al límite del workspace de desarrollo.

Dos detalles que conviene saber: no se pueden poner límites al workspace por defecto, y los archivos y lotes que crees por API quedan aislados dentro del workspace al que pertenece la clave. La caché de prompts también se aísla por workspace en la API de Anthropic.

Límites de gasto y niveles de uso

Anthropic aplica dos tipos de límites:

• Límites de gasto: un tope mensual de lo que puede gastar la organización. Según la documentación vigente, el nivel Start tiene un tope de 500 USD al mes, Build de 1,000 USD y Scale de 200,000 USD. Las organizaciones nuevas pueden empezar en un nivel de evaluación con límites menores. Además puedes fijar tu propio límite, por debajo del tope, en Settings > Billing.
• Límites de tasa: cuántas solicitudes por minuto y cuántos tokens de entrada y salida por minuto puedes usar con cada modelo. Los ves en la página Rate limits de la consola. Los veremos a detalle en la lección 2.3.

Cuando alcanzas un límite de gasto que tú configuraste, la API responde con un error y deja de procesar hasta que lo subas o empiece el siguiente periodo. Eso es justamente lo que quieres en desarrollo: que un error de código te cueste un susto, no una factura.

Práctica

Dedica 20 minutos. No necesitas programar todavía.

1. Escribe tres tareas de tu trabajo (o de Viajes Kukulcán) donde usarías IA. Para cada una, marca cuáles de las cuatro condiciones de la sección "Cuándo conviene la API" se cumplen. Decide app o API.
2. Para la tarea que elegiste como API, estima cuántas veces al día ocurre y cuántos tokens de entrada y salida tendría una llamada típica. Si no sabes, usa 1,500 de entrada y 400 de salida.
3. Ejecuta estimar_costo.py con tus cifras y con el tipo de cambio del día. Anota el costo mensual para cada modelo.
4. Crea tu cuenta en la Claude Console (o entra si ya la tienes). Crea un workspace llamado curso-api-desarrollo.
5. Configura un límite de gasto bajo para ese workspace, por ejemplo 10 USD al mes, y anota dónde lo encontraste. Todavía no crees la clave; lo haremos en la siguiente lección.

Resumen

• Las apps de Claude son productos para personas; la API es un servicio para programas, sin interfaz ni historial, que se paga por consumo.
• Conviene usar la API cuando la tarea se repite, el resultado entra en otro sistema, necesitas control fino o los usuarios no eres tú.
• Se cobra por tokens de entrada y de salida, con precios por millón de tokens que dependen del modelo; la salida cuesta más.
• La Claude Console concentra claves, uso, límites y facturación; las apps y la API se facturan por separado.
• Los workspaces separan entornos y proyectos, y permiten poner límites de gasto y de tasa propios.

Quiz