qué son los tokens en Claude y costos de uso

¿Qué son los tokens en Claude?

Un token es la unidad de texto que Claude lee y escribe: un fragmento de palabra, aproximadamente 3.5 caracteres en inglés. Esa cifra proviene del glosario de Anthropic. El total supera ampliamente un token por palabra al incluir espacios y puntuación; por tanto, mil palabras de prosa equivalen a más de 1,300 tokens. El código consume más tokens por línea: las llaves, operadores, guiones bajos e indentación generan más tokens por carácter que el inglés. Un archivo de código fuente de unas pocas cientos de líneas suele pesar varios miles de tokens. Si el agente decide leer un archivo de 2,000 líneas, el consumo será de cinco cifras de tokens antes de escribir una sola línea de código nuevo.

Dos aspectos sobre los tokenizadores suelen causar errores. Primero, son específicos de cada modelo. A partir de julio de 2026, Opus 4.7 y versiones posteriores, Sonnet 5 y Fable 5 utilizan un tokenizador más reciente. Este produce aproximadamente un 30% más de tokens para el mismo texto que los modelos Claude anteriores (el incremento exacto varía según el contenido). Esto altera cualquier presupuesto basado en tokens, aunque el precio por token no aumentó con este cambio. Segundo, tiktoken, la librería que se usa habitualmente en blogs, es el tokenizador de OpenAI. Este subestima el conteo de Claude en un 15–20% en texto común, y en mayor medida en código. El único conteo fiable es el endpoint count_tokens, detallado a continuación.

Por qué su sesión de programación tiene ese costo

Cada factura de Claude, ya sea una factura de API o un límite de suscripción, depende de un único medidor: tokens de entrada y tokens de salida. La página de precios lo presenta de forma sencilla: tantos dólares por millón de tokens de entrada y tantos por millón de salida. Lo que no explica es que, en una sesión de programación con agentes, el consumo de entrada es mucho mayor de lo que sugiere la intuición, porque la conversación completa se reenvía en cada turno. He vendido infraestructura de facturación por medición durante quince años, y los tokens son el primer medidor donde la mayoría de los clientes no pueden identificar qué lo está disparando. Esta es la lección sobre la lectura del medidor: qué se considera entrada y salida en una sesión con agentes, por qué el bucle de reenvío es tan costoso, por qué el prompt caching cambia el cálculo y qué variables afectan realmente al número final.

Todo es input: qué es lo que realmente cuenta el medidor

Se asume que se paga por el código que escribe Claude. En una sesión de agentes, ese es el concepto con menor peso. Los tokens de input —con una tarifa más baja, pero un volumen mucho mayor— incluyen:

• El system prompt. Las instrucciones propias del entorno de Claude Code, además de sus archivos CLAUDE.md y de memoria, cargados al inicio de la sesión y presentes en cada solicitud posterior.
• Definiciones de herramientas. Cada esquema de herramienta que el agente puede llamar. Cada servidor MCP al que te conectes añade este gasto fijo —aunque Claude Code ahora pospone las definiciones completas de herramientas MCP por defecto, por lo que solo los nombres de las herramientas ocupan contexto hasta que se usa una herramienta por primera vez, lo que reduce pero no elimina el coste—.
• Cada archivo que el agente lee. Un Read de un archivo fuente añade el contenido completo al contexto, y este permanece allí.
• Cada resultado de herramienta. Ejecuciones de tests, salida de grep, texto de la terminal, logs de compilación; todo regresa como tokens de input. Una suite de tests fallida que imprime 8,000 líneas equivale al coste de un libro pequeño.
• La conversación completa hasta el momento, reenviada en cada turno. Este punto requiere su propia sección.

El problema del reenvío de datos en cada turno

La API de Claude no tiene estado. No recuerda la sesión entre peticiones; nada lo hace. Por tanto, en el turno 2, el cliente envía el turno 1, su respuesta y el nuevo mensaje. En el turno 50, se reenvían los turnos del 1 al 49 —cada lectura de archivo, cada resultado de herramienta, cada diff— más el turno 50. El modelo vuelve a leer toda la transcripción en cada ocasión, y cada uno de esos tokens re-leídos se factura como input.

La consecuencia: el coste por turno crece de forma lineal según la longitud de la sesión, y el coste total de la sesión crece de forma cuadrática. Un mensaje que costó medio centavo en el turno 3 puede costar veinte veces más en el turno 60, para la misma pregunta de una línea, porque transporta el contenido de sesenta turnos. Este es el hecho que explica la mayoría de los tickets de "por qué mi factura es tan alta", y no es una peculiaridad de Claude: todos los productos de LLM que parecen tener estado son en realidad APIs sin estado con un bucle de reenvío subyacente.

Output: lo que ves, más el proceso de pensamiento interno

Los tokens de salida son los más costosos: cinco veces la tarifa de entrada en la línea actual ($5/$25 en Opus 4.8, $3/$15 en Sonnet 5, $1/$5 en Haiku 4.5, a partir de julio de 2026). El output incluye el texto y el código que genera Claude, y los thinking tokens: el razonamiento interno que realiza el modelo antes de responder. Dos hechos son importantes aquí. El razonamiento se factura con las tarifas de salida y consume max_tokens — una respuesta de API que termina con stop_reason: "max_tokens" y una respuesta truncada suele significar que el razonamiento consumió el presupuesto antes que la respuesta. Además, en los modelos actuales el resumen del razonamiento puede no mostrarse; Opus 4.8, Sonnet 5 y Fable 5 lo omiten por defecto, pero el proceso de pensamiento ocurre y se factura igualmente. Lo invisible no es gratuito.

Claude Code permite el pensamiento extendido por defecto porque mejora mediblemente el trabajo de múltiples pasos, y el presupuesto predeterminado puede alcanzar decenas de miles de tokens por solicitud. En tareas más simples puede reducirlo: baje el nivel de esfuerzo con /effort o en /model, o ajuste la configuración de pensamiento en /config. Es un control de costos real, no una superstición.

Prompt caching redefine los costos

El prompt caching es la razón por la cual los bucles de reenvío no agotan los recursos de todos. La API puede almacenar en caché un prefijo estable de su prompt —system prompt, definiciones de herramientas, historial de conversación— y entregarlo en la siguiente solicitud a una fracción del precio. A partir de julio de 2026, los multiplicadores son: una escritura (write) en caché cuesta 1.25× la tarifa base de entrada (2× para la variante de 1 hora), y una lectura (read) en caché cuesta 0.1×. Las escrituras tienen un recargo; las lecturas tienen un 90% de descuento. Una sola lectura compensa con creces el recargo de la escritura de 5 minutos.

Claude Code gestiona el caché por usted, y en una sesión estable casi todo ese reenvío masivo se sirve desde el caché. Sin embargo, el caché por defecto dura cinco minutos desde su último uso. Si se ausenta durante un café prolongado y regresa para enviar un mensaje, el caché habrá expirado; el prefijo acumulado se volverá a escribir a 1.25× en lugar de leerse a 0.1×. En una sesión de 150K tokens, ese único turno en frío cuesta más que una docena de turnos en caliente. Este es el resultado contraintuitivo que debe asimilar: un ritmo de inactividad y reanudación puede costar más que el trabajo continuo, porque cada intervalo de inactividad que supere el TTL convierte su siguiente turno de una lectura barata en una reescritura costosa. Trabaje en bloques; no envíe una sesión enorme mediante goteo con un mensaje cada diez minutos.

Si llama a la API desde su propia aplicación en un VPS, no obtiene nada de esto de forma gratuita. El error clásico es interpolar una marca de tiempo o un ID de solicitud en el system prompt, lo cual cambia los bytes del prefijo en cada solicitud y desactiva el caché silenciosamente. El indicador es ver usage.cache_read_input_tokens en cero en llamadas que parecen idénticas.

La fórmula, con un ejemplo práctico

Ignore cualquier afirmación que indique un costo fijo como "una sesión cuesta $X". El costo de las sesiones varía en dos órdenes de magnitud. Lo que es constante es la fórmula:

turn cost = (uncached input      x base input price)
          + (cache writes        x 1.25 x base input price)
          + (cache reads         x 0.10 x base input price)
          + (output incl. thinking x output price)

session cost = sum over all turns

Ejemplo práctico en Claude Opus 4.8, que a partir de julio de 2026 cuesta $5 por millón de tokens de entrada y $25 por millón de salida. Un turno intermedio de sesión con 80,000 tokens de contexto acumulado: 75,000 leídos desde el cache, 3,000 escritos recientemente, 2,000 de entrada nueva sin cache y 1,500 tokens de salida incluyendo el proceso de pensamiento (thinking).

• Lecturas de cache: 75,000 × $0.50/M = $0.0375
• Escrituras de cache: 3,000 × $6.25/M = $0.019
• Entrada sin cache: 2,000 × $5/M = $0.010
• Salida: 1,500 × $25/M = $0.0375

Aproximadamente $0.10 por turno; cincuenta turnos iguales sumarían unos $5. Ahora, el mismo turno después de que el cache expire: los 80,000 tokens completos reescritos a $6.25/M resultan en $0.50 antes de la salida; esto es aproximadamente cinco veces el costo del turno con cache para el mismo trabajo. Esa diferencia representa el impacto total del caching en un solo valor.

Para calibración en lugar de predicción: las cifras publicadas por Anthropic para despliegues de Claude Code en empresas, a partir de julio de 2026, promedian unos $13 por desarrollador por día activo —$150–250 por mes— con un 90% de los usuarios manteniéndose por debajo de $30 al día. El costo final depende de la elección del modelo, la higiene de la sesión y el tamaño del codebase, razón por la cual los parámetros detallados a continuación son importantes.

Ver su propio consumo

En Claude Code, el comando es /usage (/cost sigue funcionando; es un alias). El bloque Session en la parte superior muestra estadísticas de tokens y una estimación de coste calculada localmente para la sesión actual; en los planes de suscripción, la misma pantalla muestra las barras de límite de su plan y un desglose que atribuye el uso reciente a skills, subagents, plugins y servidores MCP individuales. Para la facturación oficial en cuentas de API, la página de uso en Claude Console es la fuente de verdad; la cifra de la CLI es una estimación. /context genera una cuadrícula de colores de qué está ocupando la ventana de contexto — system prompt, tools, definiciones de MCP, archivos, history — y es la forma más rápida de detectar un CLAUDE.md saturado o un servidor MCP con exceso de comunicación; use all para expandir el desglose detallado por elemento.

Desde la API, cada respuesta indica exactamente lo que ocurrió:

response = client.messages.create(model="claude-sonnet-5", max_tokens=2048,
                                  messages=messages)
u = response.usage
total_prompt = u.input_tokens + u.cache_creation_input_tokens + u.cache_read_input_tokens
print(f"uncached={u.input_tokens} written={u.cache_creation_input_tokens} "
      f"read={u.cache_read_input_tokens} output={u.output_tokens}")

Tenga en cuenta que input_tokens es solo el resto sin caché — el tamaño real del prompt es la suma de los tres campos de entrada. Un agente que se ejecute durante una hora y muestre input_tokens: 4000 no es barato; los otros 200,000 tokens se sirvieron desde la caché. Para realizar una estimación antes de enviar, use el endpoint de conteo de tokens; es gratuito, tiene su propio límite de tasa (rate limit) y cuenta con el tokenizer del modelo que se especifique (considere el resultado como una estimación cercana; la facturación refleja la solicitud real):

count = client.messages.count_tokens(model="claude-sonnet-5",
                                     messages=[{"role": "user", "content": big_file}])
print(count.input_tokens)

Nunca use tiktoken, por la razón expuesta anteriormente.

Planes de suscripción frente a pago por uso

La mecánica en esta guía es idéntica en todas partes; solo difiere la liquidación. Con una API key, Anthropic factura por uso, por token, según las tarifas publicadas; cada número anterior representa dinero real. En una suscripción de Claude (Pro, Max, Team, Enterprise), el uso de Claude Code consume el cupo incluido en su plan: a partir de julio de 2026, esto consiste en una ventana de sesión rotativa de cinco horas más una ventana semanal, compartida entre modelos y con el chat de claude.ai, y la cifra de /usage dólares es informativa y no un cargo. Si agota una ventana verá "You've hit your session limit" o "You've hit your weekly limit" con una hora de reinicio; cambiar de modelo con /model no restaurará el acceso, ya que las ventanas se comparten entre modelos. Los planes pueden habilitar opcionalmente créditos de uso, gestionados con /usage-credits, para comprar uso adicional tras alcanzar el límite. No incluiré las cuotas de los planes: son los valores más volátiles de este tema, así que consulte claude.com/pricing y sus propias barras de /usage en su lugar. La mecánica de tokens sigue siendo relevante en una suscripción: una sesión ineficiente consume su ventana exactamente de la misma forma en que consumiría dólares. Para detalles sobre la suscripción, vea qué plan de Claude se adapta a su uso.

Los mecanismos que realmente funcionan

• Limita el alcance de la lectura del agente. "Fix the validation bug in auth.py" lee un solo archivo; "improve this codebase" lee cuarenta. Mantén CLAUDE.md ligero —se carga en cada sesión, así que usa solo lo esencial— y mueve las instrucciones específicas del flujo de trabajo a skills que se carguen bajo demanda.
• Claro y compacto. /clear entre tareas no relacionadas; el contexto obsoleto se vuelve a enviar y a facturar en cada mensaje posterior. Dentro de una tarea larga, /compact Focus on the failing tests and the diff resume el historial para evitar el crecimiento cuadrático de tokens.
• Elige el modelo adecuado. Sonnet es ideal para la mayoría de tareas de programación con un precio de $2/$10 por millón de tokens en la tarifa de introducción a julio de 2026 ($3/$15 estándar, frente a Opus a $5/$25); Haiku a $1/$5 es la herramienta correcta para tareas mecánicas de subagentes como el triage de logs. /model permite cambiar de modelo durante la sesión.
• Pre-filtra la salida verbosa. Un hook que use grep para reducir el resultado de un test solo a los fallos antes de que Claude lo reciba convierte 20,000 tokens de resultado de herramienta en 300, y lo hace en cada reenvío futuro de ese turno.
• Procesa por lotes lo que no sea interactivo. Para tus propios pipelines de API —clasificación, revisión masiva, trabajos nocturnos— la Batches API ejecuta los mismos modelos con un 50% de descuento a cambio de una entrega asíncrona.
• Respeta el tiempo de caché. Trabaja en periodos continuos. Una sesión de Claude Code en tmux en un VPS desconectada no tiene coste mientras esté inactiva —los tokens solo se gastan cuando se ejecuta un turno—, pero el tiempo de inactividad hace que se pierda la caché caliente y el siguiente turno pagará la re-escritura.

FAQ

¿Cuántos tokens consume una sesión de programación en Claude Code?

No hay un número fijo. Un solo turno intermedio suele llevar decenas de miles de tokens de prompt cuando se acumulan archivos e historial. Una sesión de trabajo alcanza millones de tokens, la mayoría servidos desde cache a una décima parte de la tarifa base. Para calibración, las cifras empresariales publicadas por Anthropic a julio de 2026 promedian unos $13 por desarrollador por día activo; el 90% de los usuarios gasta menos de $30. Ejecute /usage en su propia sesión; cinco minutos de observación superan cualquier promedio publicado.

¿Los tokens de pensamiento tienen coste aunque no pueda verlos?

Sí. Los tokens de pensamiento se facturan como tokens de salida (la tarifa más alta) y cuentan para max_tokens. Los modelos actuales los facturan incluso cuando la interfaz omite el resumen de razonamiento de la pantalla. Si una respuesta se trunca con stop_reason: "max_tokens" antes de que termine la respuesta visible, es probable que el razonamiento haya consumido el presupuesto. En Claude Code, reduzca el nivel de esfuerzo con /effort para tareas que no requieran un razonamiento profundo.

¿Por qué una sesión larga de Claude Code es más cara por mensaje?

Porque la API no tiene estado (stateless): cada turno reenvía la conversación completa —cada lectura de archivo, resultado de herramienta e intercambio previo— como input facturable. Por tanto, el turno 50 incluye los turnos del 1 al 49 como carga. El prompt caching sirve el prefijo repetido a aproximadamente una décima parte del precio base de input, pero el prefijo sigue creciendo. Cualquier intervalo de inactividad que supere el TTL del cache convierte el siguiente turno en una reescritura a precio completo. /compact reduce el historial; /clear lo reinicia.

¿Cómo puedo consultar mi uso y coste de tokens de Claude?

En Claude Code, /usage muestra las estadísticas de tokens de la sesión, una estimación de coste local y barras de límite de plan en suscripciones (/cost es un alias); /context muestra el contenido de la ventana. Para la facturación oficial de la API, use la página de usage en la Claude Console. En su propio código, lea response.usage —la suma de input_tokens, cache_creation_input_tokens y cache_read_input_tokens da el tamaño real del prompt— y realice estimaciones previas con el endpoint count_tokens, nunca con tiktoken.