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.

A 26 de septiembre de 2026, 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. Una suscripción no sirve para eso.
• 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.
• 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, Haiku 4.5, Fable 5.1), y esa elección pesa en el coste: por token, Opus 5.5 cuesta el doble que Sonnet 5. En Pro, Fable solo está disponible pagando con usage credits; en Max puede consumir hasta el 50 % del límite semanal.

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:

Programar tú: la suscripción suele bastar

Todos los planes de pago incluyen Claude Code. Su límite es el del plan: una ventana móvil de 5 horas más un límite semanal, y lo que gastas en la terminal sale del mismo saldo que el chat de la web, el escritorio y el móvil. Cuando llegas al tope tienes tres salidas: esperar a que se restablezca, subir de plan o activar los usage credits, que se cobran a la tarifa estándar de la API. 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.

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
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
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.

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.

Cuánto cuesta cada camino

Precios publicados por Anthropic a 26 de septiembre de 2026, en dólares y sin impuestos:

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 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. 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. Los escenarios de uso intensivo, con cuentas más detalladas, están en Claude Code para usuarios intensivos: mantener suscripción, bajar de plan o usar API, 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.

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.

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 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.

¿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.

¿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.

¿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 dos cosas distintas. En la Console, los créditos son el saldo prepago con el que pagas la API. 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.