Para usar Claude Code de forma interactiva con Claude Pro o Max, normalmente no necesitas una API key. Si ANTHROPIC_API_KEY está configurada en tu entorno, Claude Code puede priorizar esa clave y cargar el uso a la facturación API de Claude Console. Si activas usage credits después de agotar el uso incluido, el trabajo posterior continúa con tarifas API estándar. La pregunta importante no es qué ruta es más barata en abstracto, sino qué ruta está activa en esta sesión.
Empieza con /status. Luego separa /usage, variables de entorno y Console. Para programar en tu terminal como persona, la ruta limpia suele ser la suscripción. Para SDK, CI, tareas sin login humano, servicios backend o automatización de equipo, la ruta correcta suele ser una API key. Los usage credits son una continuación pagada explícita, no una bolsa oculta dentro de Pro o Max.
| Situación | Ruta recomendada | Quién paga | Primera comprobación |
|---|---|---|---|
| Usas Claude Code de forma interactiva con Pro o Max | Inicio de sesión de suscripción | Uso del plan Claude | /status |
Tienes ANTHROPIC_API_KEY o ejecutas automatización | Ruta API key | Claude Console Usage | Variable de entorno y Console |
| Activaste usage credits tras agotar el plan | Continuación con credits | Uso adicional a tarifas API estándar | Settings > Usage y Console Billing |
| Hay suscripción, pero aparece gasto API | Diagnóstico antes de comprar más | La API key puede haber tomado prioridad | /status y echo "$ANTHROPIC_API_KEY" |
Mira primero la ruta activa
Claude Code puede conectarse con tus credenciales de Claude o mediante una API key. Ambas rutas pueden existir en la misma máquina, pero no comparten el mismo dueño de facturación. El inicio de sesión de suscripción pertenece al uso de Pro o Max. La API key pertenece a Claude Console, proyectos, créditos y registro de uso.
Si estás leyendo un repo, pidiendo refactors, revisando código o explorando errores en una sesión local, el punto de partida es la suscripción. Ese camino está ligado a los límites del plan, no a una deducción token por token de API credits.
La API key es para trabajo que realmente es API: SDK, servidor, CI, agentes sin interacción, tareas programadas o un equipo que necesita imputar gasto a un proyecto de Console. Es una buena herramienta, pero cambia el contrato de pago.
Los usage credits son un tercer concepto. Permiten a usuarios Pro, Max 5x y Max 20x seguir trabajando tras agotar el uso incluido, pero el uso posterior se factura por separado a tarifas API estándar. No son cuota oculta de Pro o Max, y el cambio a credits debe ser una decisión explícita.
Por qué aparece facturación API si ya pagas una suscripción
La causa más común es que ANTHROPIC_API_KEY quedó en el entorno. Puede venir de .zshrc, .bashrc, .env, un perfil de terminal, un devcontainer, un secreto de CI o un script de arranque. Tú crees que estás usando la suscripción, pero Claude Code ve la clave y trabaja con la cuenta API.
Otra causa es la automatización. CI y contenedores no deberían depender de una sesión personal de navegador. Para ellos, una API key suele ser más correcta, pero el gasto debe presupuestarse y revisarse en Console.
La secuencia mínima es esta:
bashclaude /status echo "$ANTHROPIC_API_KEY"
Si /status muestra una ruta de suscripción, interpreta el problema como límites de plan. Si muestra una ruta API, mira variables de entorno, proyecto de Console y Usage. No cambies de plan ni compres más créditos antes de resolver esa bifurcación.
Qué significan /status, /usage, /cost y Console
/status responde por la ruta. Dice qué cuenta y qué modo está usando la sesión actual. Es la primera lectura.
/usage ayuda a usuarios de suscripción a entender barras de plan, consumo de usage credits y patrones dentro de Claude Code. Si tu versión o tu equipo todavía habla de /stats, léelo como una vista de patrones, no como una factura de Console.
/cost o una cifra en dólares dentro de usage output debe leerse como estimación de coste API por tokens. Para Pro o Max no es la factura final de la suscripción. Para una ruta API, Console Usage sigue siendo el registro más fiable.
Settings > Usage separa uso incluido y consumo de usage credits. Console Billing y Usage son la fuente de verdad para ruta API, auto-reload, proyectos API y gasto de Claude Code cuando opera por API. Si un equipo pregunta qué proyecto pagó una ejecución, la respuesta debe salir de Console.
Para un runbook de equipo, guarda la ruta de /status junto al ledger de Settings o Console; esos dos datos prueban la ruta activa y el dueño de la factura.
Cuándo sí usar una API key
Una API key es correcta cuando el trabajo es programático. No es una mejora automática sobre la suscripción ni una forma neutra de saltarse límites.
Úsala cuando:
- un backend o SDK llama a Claude API
- CI debe ejecutarse sin login humano
- un agente o batch job corre de forma programada
- el gasto debe pertenecer a un proyecto de Console
- necesitas budget controls y usage ledger
- aceptas pagar las tarifas API del modelo usado
Si el problema es que tu trabajo interactivo choca con límites, mira primero Claude Code Pro vs Max. Si el problema es un cargo inesperado, separa primero la ruta de facturación.
Usage credits y precios
Los usage credits permiten continuar después del uso incluido de un plan pagado, pero se facturan por separado a tarifas API estándar. Los credits de Console y auto-reload siguen perteneciendo a la ruta API, no a la cuota mensual de Pro o Max.
El 25 de mayo de 2026, la página pública de precios de Anthropic listaba precios por input y output tokens. Por ejemplo, Claude Sonnet 4.6 figuraba a 3 dólares por millón de input tokens y 15 dólares por millón de output tokens, mientras que Claude Opus 4.7 figuraba a 5 y 25 dólares respectivamente. Tómalos como ejemplos fechados. Para presupuesto real, revisa la página oficial actual y tu Console.
La decisión no es "API siempre es más barata" ni "suscripción siempre es más barata". Para una persona que programa varias horas en un repo, la suscripción suele ser más predecible. Para CI, backend, batch y automatización de equipo, la ruta API suele ser más auditable. Si quieres saber si existe acceso gratuito a API, separa la duda y consulta la guía de Claude API key free tier.
Cómo volver al inicio de sesión de suscripción
Si esperabas usar la suscripción y ves gasto API, no empieces borrando claves en Console. Primero elimina el override local:
bashunset ANTHROPIC_API_KEY claude logout claude login claude /status
Esto no borra la API key de Claude Console. Solo evita que el shell actual la entregue a Claude Code, reinicia la sesión local y te permite verificar la ruta nueva.
Si la clave vuelve al abrir una terminal nueva, está escrita en una configuración persistente. Revisa archivos de inicio del shell, .env, devcontainer, CI secrets, LaunchAgent o scripts de arranque del IDE. En equipos, basta una regla clara: suscripción para trabajo local interactivo, API key para automatización, Console para revisar gasto API.
Lo que no conviene mezclar
No digas que Claude Code es gratis solo porque se puede iniciar sesión con un plan pagado. La suscripción tiene límites y la API tiene facturación separada.
No digas que Pro incluye llamadas API generales. Pro o Max pueden cubrir el uso de Claude Code mediante credenciales de Claude, pero Claude API es un contrato de Console.
No uses /cost ni una estimación local en dólares como factura final de la suscripción. Es útil como contexto de tokens, pero /status, /usage, Settings > Usage y Console Usage responden preguntas diferentes.
No pegues una API key real en tickets, chats, capturas o prompts de soporte. Lo que se debe mostrar es si la variable existe y qué ruta reporta /status, no el secreto.
Regla práctica para equipos
En un equipo conviene escribir la regla antes de que aparezca la factura. Trabajo local e interactivo: inicio de sesión de suscripción. CI, backend, agentes programados y scripts sin usuario humano: API key con dueño de presupuesto. Continuar después del límite incluido: usage credits con consentimiento explícito. Gasto de proyecto, auto-reload y ledger API: Claude Console.
La evidencia también debe ser segura. Comparte qué dice /status, si ANTHROPIC_API_KEY está presente en ese shell, qué periodo y proyecto aparecen en Console Usage, y si Settings > Usage muestra consumo de credits. No compartas la clave real, un .env completo ni capturas con otros proyectos. Para resolver el problema basta con saber qué contrato pagó la sesión.
Separar estas rutas evita una mala decisión frecuente: subir a Max cuando el problema era un API key heredado, o comprar credits cuando el bloqueo real era un límite de suscripción. Primero identifica la ruta; después decides si limpiar entorno, esperar reset, habilitar usage credits, cambiar plan o mover la tarea a API.
Ruta de verificación
La separación de rutas y facturación anterior se basa en Claude Help, Claude Code docs, Anthropic billing y Anthropic pricing revisados el 25 de mayo de 2026.
Para tu cuenta, usa el mismo orden: /status, luego ANTHROPIC_API_KEY, luego Settings > Usage o Console Usage. Así obtienes primero el dueño de la sesión y después decides si toca limpiar el entorno, comprar credits, comparar planes o cambiar una automatización.
Preguntas frecuentes
¿Necesito una API key para usar Claude Code?
No para el uso interactivo normal con Claude Pro o Max. Claude Code puede conectarse con tu cuenta de Claude. Necesitas API key para SDK, CI, backend, automatización o un proyecto de Console.
¿Por qué Claude Code factura a mi cuenta API si tengo Pro o Max?
Probablemente la sesión está usando la ruta API. Comprueba /status y revisa si ANTHROPIC_API_KEY está configurada en el mismo entorno que lanza Claude Code.
¿Los usage credits son lo mismo que la suscripción?
No. Los usage credits permiten continuar después del uso incluido, pero se facturan por separado a tarifas API estándar. La suscripción Pro o Max conserva sus propios límites incluidos.
¿Debería usar API en vez de subir a Claude Max?
Solo si el trabajo es realmente API: CI, SDK, backend, agentes o automatización auditable. Para codificación local interactiva, revisa antes problemas de límites de Claude Code y la comparación Pro/Max.
¿/cost muestra mi factura de Pro o Max?
No. Trátalo como una estimación de coste API por tokens. Usa /status para saber la ruta, /usage para uso de suscripción o credits, y Console Usage para facturación API.
¿Cómo hago que Claude Code deje de usar mi API key?
Ejecuta unset ANTHROPIC_API_KEY en el mismo shell, luego claude logout, claude login y /status. Si la clave vuelve, elimínala de archivos de shell, .env, secretos de CI o configuración de contenedor.