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. La pregunta importante no es si la clave es mejor, sino qué ruta está activa en esta sesión.
Empieza con /status. 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 API credits son un saldo aparte de Console, 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 |
| Compraste API credits o activaste auto-reload | API credits | Saldo prepago de Console | 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 API credits son un tercer concepto. Son saldo prepago de Claude Console para API, Workbench y Claude Code cuando Claude Code opera por la ruta API. No son cuota de Pro o Max.
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, /stats, /cost y Console
/status responde por la ruta. Dice qué cuenta y qué modo está usando la sesión actual. Es la primera lectura.
/stats ayuda a usuarios de suscripción a entender sus patrones dentro de Claude Code. Puede mostrar si una forma de trabajar consume el plan rápido, pero no es una factura de Console.
/cost 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.
Console Billing y Usage son la fuente de verdad para API credits, 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.
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.
API Credits y precios
Claude Console usa API credits prepagos para la ruta API. Cubren API, Workbench y Claude Code cuando Claude Code opera mediante API. No forman parte de Pro o Max.
El 20 de abril 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 como factura final de la suscripción. Es útil como contexto de tokens, pero /status, /stats 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.
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 20 de abril de 2026.
Para tu cuenta, usa el mismo orden: /status, luego ANTHROPIC_API_KEY, luego Console Usage. Así obtienes primero el dueño de la sesión y después decides si toca limpiar el entorno, comprar créditos, 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 API credits son lo mismo que la suscripción?
No. Los API credits viven en Claude Console y financian uso API. La suscripción Pro o Max tiene sus propios límites.
¿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, /stats para patrones de suscripción 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.