Claude API vs Claude Code: diferencias, cuál usar y cómo se paga

La Claude API y Claude Code no son dos modelos ni dos versiones de Claude: usan los mismos modelos desde capas distintas. La API es el acceso directo a los modelos desde tu propio código: tu programa envía peticiones a https://api.anthropic.com/v1/messages con una clave creada en la Claude Console y pagas por los tokens que consume. Claude Code es la herramienta de programación agéntica de Anthropic: lee tu código, edita archivos, ejecuta comandos y trabaja desde la terminal, el IDE, la app de escritorio o el navegador. Se paga con una suscripción (Pro, Max, Team o Enterprise) o con credenciales de API o de un proveedor cloud.

Qué ha cambiado a 8 de octubre de 2026: desde el 7 de octubre, Max y Team incluyen un crédito mensual para la API (100 $ o 200 $ en Max) que se ingresa en una organización de la Console, pero no paga Claude Code interactivo. Además, la API vende dos modelos nuevos, Sonnet 5.5 y Haiku 5.5.

La elección práctica se resume así:

• Quieres que Claude programe contigo en tu repositorio: Claude Code con tu plan Pro o Max. No necesitas la API, y el plan Free no incluye Claude Code.
• Quieres que tu aplicación llame a Claude para chatear, clasificar o extraer datos: la API con una clave propia. El login de una suscripción no sirve para eso; lo que sí cambia es que, con Max o Team, el crédito mensual puede pagar parte de ese consumo.
• Quieres ejecutar Claude Code desde un script o en CI: claude -p funciona con tu suscripción o con una clave; si añades --bare, solo con clave. Con una clave de la organización vinculada a Max o Team, ese uso sale del crédito mensual.
• El agente lo van a usar otras personas: clave API o proveedor cloud. El login de tu cuenta de claude.ai no puede ser la puerta de entrada de tus usuarios.

Qué es cada cosa y qué te cobra

La confusión viene de que ambos nombres aparecen juntos en la página de precios y en la Console, pero cada uno resuelve un trabajo distinto.

Claude Code no es un modelo. Cuando te preguntas qué modelo conviene en Claude Code, en realidad eliges entre los mismos modelos que vende la API (Opus 5.5, Sonnet 5.5, Haiku 5.5, Fable 5.1 y los anteriores que siguen disponibles), y esa elección pesa en el coste: por token, Opus 5.5 cuesta el doble que Sonnet 5.5. Desde el 9 de noviembre de 2026 el modelo Fable vigente es Fable 5.2 (claude-fable-5-2), a 8 $ / 40 $ por millón de tokens; Fable 5.1 sigue disponible como modelo heredado a 10 $ / 50 $. Con los modelos Fable la cuenta cambia según el plan: en Pro no entran en los límites del plan y se pagan con usage credits desde la primera petición; en Max puedes dedicarles hasta el 50 % del límite semanal sin coste extra, dentro de ese límite y no además de él. Como oferta de lanzamiento de Fable 5.2, del 9 al 16 de noviembre de 2026 a las 23:59 (hora del Pacífico), Pro y los asientos Standard de Team tienen los modelos Fable incluidos en el plan, hasta el 50 % del límite semanal; pasada esa fecha, vuelven a pagarse con usage credits desde la primera petición.

Claude Cowork, que a veces aparece en la misma conversación, es otra aplicación de Anthropic. No cambia nada de lo que sigue sobre la API y Claude Code.

Qué usar según la tarea

La documentación de Anthropic distingue cuatro maneras de trabajar con estos modelos: la CLI de Claude Code, el Agent SDK, el Client SDK de la API y Managed Agents. Para decidir necesitas saber además con qué credencial funciona cada una, a qué factura va y en qué punto deja de estar permitida:

El esquema es anterior al cambio del 7 de octubre de 2026: donde dice «ningún plan sirve aquí», el login de un plan sigue sin servir, pero el crédito mensual de Max y Team sí paga la API. El texto está actualizado a 8 de octubre de 2026.

Programar tú: la suscripción suele bastar

Todos los planes de pago incluyen Claude Code. Su límite es el del plan: una sesión que se restablece cada cinco horas más un límite semanal para todos los modelos, y lo que gastas en la terminal sale del mismo saldo que el chat de la web, el escritorio y el móvil. Anthropic no publica cuántos mensajes o tokens caben en cada plan; Max (antes Max 5x) da 5 veces el uso de Pro cada cinco horas y cada semana, y Ultra (antes Max 20x), 10 veces el uso semanal de Pro, sin límite de cinco horas en las cuentas verificadas.

Cuando llegas al tope tienes varias salidas: esperar a que se restablezca, subir de plan o activar los usage credits en Settings > Usage, que se cobran a la tarifa estándar de la API. Si tu cuenta tiene un restablecimiento del límite (limit reset), puedes usarlo para devolver al máximo la sesión de cinco horas o el límite semanal; se activa en Settings > Usage desde la web o Claude Desktop, no desde Claude Code en la terminal ni desde el móvil. Si programas de forma muy intensiva, también puedes pasar Claude Code a créditos de API de pago por uso con una cuenta de la Console; el crédito mensual de Max no paga ese uso interactivo.

Los contadores de cada plan y dónde verlos están en Límites de uso de Claude Pro y Max: Ultra sin límite de 5 horas. La diferencia entre usage credits, restablecimiento del límite y el crédito de la nube (el plazo para reclamarlo terminó el 7 de octubre de 2026) la tienes en Claude: crédito de la nube, créditos de uso y reinicio del límite.

La elección entre planes tiene su propio análisis en Claude Pro vs Max en 2026: precios, límites de Claude Code y cuándo compensa Max, y si todavía no lo tienes instalado, en Cómo instalar Claude Code en 2026: guía completa para Mac, Windows y Linux.

Automatizar: claude -p no es la API

Lo que en foros se llama «usar Claude Code como API» suele ser el modo no interactivo: añades -p a cualquier comando claude y la herramienta ejecuta la tarea y devuelve el resultado, con las mismas herramientas y el mismo bucle de agente que en la sesión interactiva. Anthropic lo presenta como el Agent SDK en forma de CLI; para Python y TypeScript existen los paquetes del SDK, y desde cualquier otro lenguaje puedes lanzar la CLI como subproceso con -p y --output-format json.

La credencial cambia según cómo lo lances:

# Con tu suscripción (Pro, Max, Team o Enterprise): genera un token de un año
# El uso sale de los límites de tu plan
claude setup-token
export CLAUDE_CODE_OAUTH_TOKEN=tu-token
claude -p "Busca y corrige el fallo de auth.py" --allowedTools "Read,Edit,Bash"

# Modo bare: arranca más rápido y no carga hooks, MCP ni CLAUDE.md,
# pero nunca lee la suscripción; necesita una clave de la Console
# (si es de la organización vinculada a Max o Team, gasta primero el crédito mensual)
export ANTHROPIC_API_KEY=tu-clave
claude --bare -p "Resume README.md" --allowedTools "Read"

Dos detalles que conviene tener claros antes de meterlo en CI. Primero, en modo -p, si ANTHROPIC_API_KEY existe en el entorno, se usa siempre, aunque también tengas el token de la suscripción: el gasto irá por tokens. Segundo, sin --bare, una sesión -p ejecuta los hooks de .claude/settings.json y conecta los servidores de .mcp.json del repositorio aunque nunca hayas marcado esa carpeta como de confianza, y no muestra ningún aviso. Si el pipeline procesa ramas o repositorios de terceros, --bare es la opción prudente; Anthropic la recomienda para llamadas desde scripts y SDK, y anuncia que será el comportamiento por defecto de -p en una versión futura.

Ojo con el crédito mensual: las ejecuciones que lanza la GitHub Action de Claude Code, una extensión de IDE o la app de escritorio cuentan como uso de Claude Code, así que no salen de ese crédito aunque lleven -p.

Integrar Claude en tu producto: la API, y el bucle lo pones tú

Si tu aplicación necesita responder preguntas, resumir documentos o clasificar tickets, lo que quieres es la API. La llamada mínima tiene este aspecto:

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1000,
    "messages": [
      {"role": "user", "content": "Resume en tres puntos este contrato."}
    ]
  }'

Aquí no hay herramientas de archivos ni de terminal ya montadas: si tu caso necesita que el modelo use herramientas, escribes tú el bucle o dejas que lo lleve el tool runner (beta) del Client SDK. A cambio controlas cada petición, cada coste y cada dato que envías. España figura entre los países admitidos por la API de Anthropic, así que puedes crear la cuenta y la clave directamente; los pasos para conseguir clave y saldo están en Cómo comprar acceso a Claude API: créditos, Console y claves bajo tu control.

Un agente para otras personas: clave API, siempre

Esta es la frontera que más cuesta ver. Las condiciones de Anthropic para Claude Code y el Agent SDK dicen que quien construye productos o servicios debe autenticarse con una clave API de la Console o con un proveedor cloud compatible. No se permite ofrecer el login de claude.ai dentro de tu aplicación, ni enrutar peticiones de tus usuarios a través de credenciales Free, Pro o Max, ni recoger o guardar credenciales o tokens de sesión de claude.ai. Anthropic se reserva el derecho a hacerlo cumplir sin previo aviso.

Lo que sí está permitido:

• Configurar tus propias claves API en un entorno de desarrollo, un gestor de secretos o una imagen de máquina para tus usuarios autorizados, siempre que el consumo se facture al titular de la clave y no se revenda.
• Que cada usuario final inicie sesión con su propia suscripción en el binario de Claude Code sin modificar, incluso cuando una plataforma aloja Claude Code.
• Usar tú mismo Claude Code y el Agent SDK con tu suscripción para tu trabajo. Los límites anunciados de Pro y Max presuponen un uso individual y normal de ambos; la regla no dice que cualquier script con suscripción esté prohibido.

Si prefieres que Anthropic aloje el agente y su sandbox, la opción es Managed Agents, que se configura con la API: la tienes explicada en Claude Managed Agents en 2026: qué es, cuándo usarlo y cuándo no.

Crédito mensual de API en Max y Team: qué paga y qué no

Desde el 7 de octubre de 2026, los planes Max y Team incluyen cada mes un crédito para la API de Claude. Es lo más parecido a un puente entre la suscripción y la API, pero no convierte tu plan en una clave: el crédito se ingresa en una organización de la Claude Console que tú vinculas, y se gasta con las claves de esa organización.

En Team, los créditos de todos los asientos se suman en un único saldo con un tope de 500 $ al mes: un equipo con tres asientos Standard y dos Premium recibe 260 $ (3 × 20 + 2 × 100). Los planes Team con descuento para organizaciones sin ánimo de lucro y científicos reciben las mismas cantidades por asiento.

Para reclamarlo necesitas llevar siete días en el plan. En claude.ai, desde el navegador, entra en Settings > Billing (Max) u Organization settings > Billing (propietario de Team), busca la sección de créditos de API y elige «Link organization». No hace falta método de pago. Solo puedes vincular una organización de la Console, cada organización recibe crédito de un único plan y no puedes cambiar la vinculación por tu cuenta. Anthropic lo está activando de forma escalonada durante unos días, así que es posible que todavía no veas la opción.

El resto de reglas, según el artículo de ayuda de Anthropic sobre los créditos mensuales de API para Max y Team:

• Se renueva en cada ciclo de facturación y lo que no gastes caduca; no se acumula.
• Se gasta antes que el saldo que hayas comprado en la Console. Cuando se agota, la organización sigue funcionando si tiene saldo comprado o recarga automática; si no, las peticiones a la API se detienen hasta el siguiente crédito. Nunca se cobra a tu plan de Claude.
• Va aparte de los límites del plan: no amplía lo que puedes usar en Claude, Claude Code ni Cowork.
• Si cancelas o bajas de plan, dejas de recibir créditos nuevos, pero puedes usar los que tengas hasta que caduquen. Si subes de Max a Ultra, recibes al momento la parte proporcional y después 200 $ por ciclo.
• No es el crédito para el Agent SDK que se anunció en junio: ese crédito no está disponible.

En la práctica, si ya pagas Max, el crédito te permite probar tu aplicación o ejecutar scripts con --bare y una clave de la organización vinculada sin pagar nada más hasta 100 $ o 200 $ al mes, mientras que tu trabajo diario en la terminal sigue saliendo de los límites del plan. Con Pro no hay crédito: la API se paga aparte, porque el plan Pro no incluye uso de la API a través de la Console.

Cuánto cuesta cada camino

Precios publicados por Anthropic a 8 de octubre de 2026, en dólares y sin impuestos (el pago anual de Pro corresponde a la página de precios a 26 de septiembre de 2026):

Sonnet 5.5 y Haiku 5.5 son los modelos nuevos; Sonnet 5 y Haiku 4.5 siguen disponibles en la lista de modelos anteriores de la tabla de precios de la API de Claude. Los 2 $ y 10 $ de Sonnet 5 ya son su precio estándar: la subida prevista para el 1 de septiembre de 2026 no se aplicó. La lectura desde caché cuesta el 10 % del precio de entrada (el 5 % en Opus 5.5 y Sonnet 5.5, el 2,5 % en Fable 5.1), y la API por lotes (Batch) tiene un 50 % de descuento.

Para ver el orden de magnitud, un supuesto: una sesión de programación agéntica que consume 2 millones de tokens de entrada y 150.000 de salida, sin caché. Las cifras de tokens son una hipótesis, no una medición; cambia los números por los de tu uso real.

Frente a eso, Pro cuesta 20 $ y Max, 100 $ o 200 $ al mes, pero con límites de uso: la comparación solo vale si esas sesiones caben en tu plan, y un plan no equivale a uso ilimitado a precio fijo. La caché puede abaratar mucho el contexto que se repite entre peticiones, así que la cifra de la API es un techo. Con el mismo supuesto, el crédito mensual de Max (100 $) da para unas 18 sesiones con Sonnet 5.5 por API (100 ÷ 5,50), y el de Ultra (200 $), para unas 36; solo cuentan si las lanzas con claude -p, el Agent SDK o tu propio código y una clave de la organización vinculada, no en Claude Code interactivo. Como referencia de empresa, Anthropic indica un coste medio de unos 13 $ por desarrollador y día activo, entre 150 $ y 250 $ al mes, en sus despliegues empresariales; es una media de organizaciones, no una previsión para tu caso.

La conclusión práctica: si programas tú cada día, la suscripción suele salir más barata que pagar lo mismo por tokens. La API compensa cuando el consumo lo generan tu producto o tus usuarios, cuando el uso es esporádico, o cuando tu empresa necesita condiciones comerciales y facturación por consumo; si además tienes Max o Team, el crédito mensual cubre la primera parte de ese consumo. Los escenarios de uso intensivo, con cuentas más detalladas, están en Claude API o suscripción para uso intensivo de Claude Code, y el detalle de planes, Team y extra usage en Precio de Claude Code 2026: Pro, Max, Team, API y extra usage.

Tres errores caros y cómo comprobar tu ruta

1. Pagar la API por un trabajo que ya cubre tu plan. Si tienes Pro o Max y solo programas tú, no necesitas comprar créditos de API para usar Claude Code: tu plan ya lo incluye. La API solo tiene sentido si tu propio código va a llamar a los modelos, y en ese caso, con Max o Team, reclama antes el crédito mensual para no pagar desde el primer dólar.

2. Una ANTHROPIC_API_KEY olvidada que pasa Claude Code a pago por tokens. Claude Code elige credencial por orden de prioridad: primero el proveedor cloud (CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX para Google Cloud's Agent Platform o CLAUDE_CODE_USE_FOUNDRY), luego ANTHROPIC_AUTH_TOKEN, después ANTHROPIC_API_KEY, apiKeyHelper, CLAUDE_CODE_OAUTH_TOKEN y, al final, el login de la suscripción. Si tienes suscripción y además una clave aprobada en el entorno, gana la clave. En modo interactivo te pide aprobarla una vez; en -p la usa siempre que exista. Que la clave sea de la organización vinculada a Max no lo arregla: en Claude Code interactivo ese gasto no sale del crédito mensual.

Para saber qué ruta estás usando:

# Nombres de las variables que pueden cambiar la credencial (sin mostrar su valor)
env | grep -E '^(ANTHROPIC_|CLAUDE_CODE_)' | cut -d= -f1

Dentro de Claude Code, ejecuta /status: muestra el método activo y marca la credencial que no se está usando. Si quieres volver a la suscripción, unset ANTHROPIC_API_KEY (y quítala de tu perfil de shell) o desactiva «Use custom API key» en /config. Para lo que realmente pagas por la API, la referencia es la página de uso de la Console (el crédito mensual aparece en Settings > Billing de la Console): el coste de sesión que muestra /usage es una estimación a precio de lista y, con Pro o Max, no tiene nada que ver con tu factura. El diagnóstico completo está en Claude Code: API key, suscripción y facturación API sin sorpresas, y la configuración de claves, modelos y gateways en Configuración de Claude Code API: claves, settings.json, modelos y gateways.

3. Alimentar un producto con el login de una suscripción. Un servicio que otros usan, montado sobre tu cuenta Pro o Max o sobre el token de claude setup-token, cae fuera de lo permitido. Además, los límites del plan presuponen el uso de una persona, no el tráfico de un servicio. Para cualquier cosa que atienda a terceros, clave API o proveedor cloud desde el primer día.

Preguntas frecuentes

¿Claude Code es gratis?

No. El plan Free de Claude no incluye Claude Code. Lo tienes desde Pro (20 $ al mes, o 17 $ al mes con pago anual) o pagando por tokens con una cuenta de la Console o un proveedor cloud. Si dudas entre Free y Pro para el resto de usos, mira Claude gratis vs Pro: compara límites por tareas, no por mensajes.

¿Necesito la API para usar Claude Code?

No. Con Pro, Max, Team o Enterprise inicias sesión con /login y el uso sale de tu plan. La API solo entra en juego si decides autenticar Claude Code con una clave o una cuenta de la Console, y entonces pagas por tokens: el crédito mensual de Max y Team no cubre las sesiones interactivas.

¿Puedo usar mi clave API en Claude Code?

Sí. Claude Code acepta ANTHROPIC_API_KEY y, si está definida, tiene prioridad sobre el login de la suscripción una vez aprobada. Todo lo que hagas se facturará por tokens en la Console; compruébalo con /status. Si la clave es de la organización vinculada a Max o Team, el crédito mensual paga claude -p y el Agent SDK que lances tú, pero no Claude Code interactivo en la terminal, el IDE, el escritorio o la web.

¿Max o Pro incluyen crédito para la API de Claude?

Max sí, desde el 7 de octubre de 2026: 100 $ al mes en Max y 200 $ en Ultra, que se ingresan en una organización de la Console vinculada tras siete días en el plan. Team recibe 20 $ por asiento Standard y 100 $ por asiento Premium, con un tope de 500 $. Pro, Free y Enterprise no tienen este crédito.

¿Cuánto cuesta usar la API de Claude?

No hay cuota fija: pagas por tokens. A 8 de octubre de 2026, el millón de tokens va desde 0,10 $ de entrada y 0,50 $ de salida en Haiku 5.5 (prompts de hasta 100.000 tokens) hasta 10 $ y 50 $ en Fable 5.1; Sonnet 5.5 cuesta 2 $ y 10 $, y Opus 5.5, 4 $ y 20 $. Fable 5.2, el modelo Fable vigente desde el 9 de noviembre, cuesta 8 $ y 40 $. La caché y la API por lotes rebajan esas cifras.

¿La API y Claude Code dan resultados distintos?

Usan los mismos modelos. La diferencia está en lo que rodea al modelo: Claude Code añade herramientas para leer y editar tu proyecto, ejecutar comandos y gestionar permisos y sesiones; con la API construyes tú esa parte.

¿Qué son los «créditos» de Claude?

Se usa la palabra para tres cosas distintas. En la Console, los créditos son el saldo prepago con el que pagas la API. El crédito mensual de Max y Team es un saldo que el plan ingresa en esa Console cada ciclo y se gasta antes que el comprado. En una suscripción, los usage credits te permiten seguir trabajando cuando llegas al límite del plan y se cobran a la tarifa estándar de la API; se gestionan con /usage-credits, que solo funciona si has iniciado sesión con tu cuenta de claude.ai.

¿Puedo usar la Claude API desde España?

Sí. España está en la lista de países admitidos por la API de Anthropic. Los precios se publican en dólares y sin impuestos.