Costos y consumo

Theus estima el costo y el consumo de tokens de tu sesión de forma local, a partir del uso real de cada modelo. Sin proveedor remoto obligatorio: cuando trabajas con tu propia clave (BYOK) o con un modelo local, el costo real lo define tu proveedor.

El comando `/cost`

Escribe /cost en la sesión para ver un resumen del costo total y la duración acumulada. El comando muestra el costo total y la duración de la sesión actual y también funciona en modo no interactivo.

El resumen incluye estos campos:

Total cost — costo estimado acumulado en USD.
Total duration (API) — tiempo total consumido en llamadas al proveedor.
Total duration (wall) — tiempo total transcurrido de la sesión.
Total code changes — líneas añadidas y eliminadas por las herramientas.
Usage by model — desglose por modelo: tokens de entrada, de salida, de lectura de caché, de escritura de caché y, si aplica, búsquedas web, con el costo parcial de cada modelo.

Si tienes una suscripción activa de Theus, /cost no muestra el desglose de gasto: en su lugar indica que tu uso se cubre con tu suscripción (o con tus excedentes, que se reinician automáticamente al llegar el corte del periodo). El detalle de costos por token está pensado para cuando pagas el consumo directamente al proveedor.

Cómo se calcula el consumo

Cada respuesta del modelo reporta su uso de tokens. Theus toma esos valores y los multiplica por la tarifa del modelo para obtener un costo en USD, acumulándolo en el estado de la sesión. El cálculo cubre cinco componentes:

Tokens de entrada (input).
Tokens de salida (output).
Tokens de lectura de caché de prompt (cache read), mucho más baratos que la entrada normal.
Tokens de escritura de caché de prompt (cache write).
Búsquedas web, tarifadas por solicitud.

Las tarifas se expresan por millón de tokens (Mtok). A modo de referencia, Theus mantiene varios niveles de precio internos, por ejemplo:

Nivel	Entrada / Salida (por Mtok)	Lectura caché	Escritura caché
Sonnet estándar	$3 / $15	$0.30	$3.75
Opus 4/4.1	$15 / $75	$1.50	$18.75
Opus 4.5 / 4.6	$5 / $25	$0.50	$6.25
Haiku 4.5	$1 / $5	$0.10	$1.25
Haiku 3.5	$0.80 / $4	$0.08	$1.00

Las búsquedas web se tarifan a $0.01 por solicitud. Algunos modelos tienen una tarifa distinta bajo modo rápido.

Cómo Theus reduce tu consumo

Además de contar tokens, Theus trabaja activamente para que gastes menos. Tres mecanismos operan de forma automática:

Prompt caching nativo. Cuando el gateway enruta a un modelo de la familia Claude, usa el adaptador nativo (API /v1/messages) y marca puntos de caché explícitos (cache_control) en el system prompt, las herramientas y el último mensaje. El contexto repetido entre turnos se sirve como lectura de caché, que cuesta ~10% de la tarifa de entrada normal — un descuento de ~90% en la parte del prompt que no cambia. En el desglose de /cost lo ves como tokens de lectura y escritura de caché.
Microcompact (CLI). Theus limpia automáticamente del contexto los resultados antiguos de herramientas (lecturas de archivos, comandos de shell, búsquedas) que ya no aportan al turno actual. Menos contexto enviado = menos tokens de entrada, sin que pierdas el hilo de la conversación.
Techo de contexto (chat web). En una conversación el navegador reenvía el hilo entero en cada mensaje, y ese hilo se cobra entero cada vez. Cuando supera el presupuesto de contexto (~60.000 tokens), el gateway deja de reenviar completos los mensajes intermedios más antiguos: conserva siempre las instrucciones del sistema, tu primer mensaje —lo que pediste— y los últimos intercambios, y anota en su lugar que hubo conversación previa. El corte nunca parte una llamada a herramienta de su resultado.
Memoria y recall. El índice local y el recall híbrido devuelven símbolos con archivo:línea, memorias del proyecto y el subgrafo de relaciones, de modo que el agente no relee archivos completos para reencontrar lo que ya conoce. Los episodios de sesiones anteriores también se recuperan sin reconstruir contexto. Ver Memoria.

Las peticiones de embeddings de la memoria semántica (/v1/embeddings, modelo theus-embed) también pasan por el gateway con tu suscripción; el CLI las cachea en disco por proyecto para que solo se embeba lo nuevo.

Cuotas por plan (suscripción Theus)

Con la suscripción Theus no pagas por token: cada plan incluye una cuota de créditos y un límite de solicitudes por minuto. La cuota se renueva por ciclo: en el plan Free por mes calendario, y en los planes pagados anclada al periodo de facturación de tu suscripción. Si compraste solo Atlas by Theus, la ventana se ancla al periodo de tu suscripción Atlas cuando es mensual, y vuelve al mes calendario cuando es anual; el detalle está en Planes y cuotas.

Plan	Créditos incluidos por ciclo	Solicitudes/minuto
Free	300	15
Pro Code	1.500	60
Studio AI	5.000	120
Max Agent	15.000	240
Omnipresente	15.000 + 300 imágenes + 1.320 créditos de vídeo	240
Omnipotente + Atlas	40.000 + 300 imágenes + 1.320 créditos de vídeo	480

La escalera en soles tiene sus propias cuotas. Impulso 1.000 créditos · Pro 2.000 · Power 5.000 · Creativo 6.000 (con 150 imágenes y 660 créditos de vídeo) · Empresa 12.000 (con 200 imágenes y sin cubo de vídeo). No son las cuotas del plan en dólares del que heredan las capacidades: están calibradas aparte. La tabla completa, con precios e IGV, está en Planes → La escalera en soles.

En el plan Free, agotar la cuota no lo apaga todo. Los modelos con coste upstream medido en $0,00 siguen respondiendo sin créditos, con un tope propio de 6 peticiones por minuto y 60 turnos al día. El tope existe por los sockets y el caudal del gateway, no por el coste de la inferencia, que en ese carril es cero.

Omnipresente: cuotas separadas por modalidad. Además de los 15.000 créditos de texto, incluye un cubo de 300 imágenes y otro de 1.320 créditos de vídeo al mes —unos 120 segundos del modelo estándar, o ~32 del ultra—, contadores independientes que no descuentan de tus créditos: la imagen se cuenta por unidad entregada y el vídeo en créditos ponderados por el peso real de cada modelo (así el precio es justo elijas el modelo barato o el caro). Los cubos de imagen y vídeo no se rellenan con créditos ni se acumulan entre ciclos. La generación de imagen y vídeo se incluye en Omnipresente y Omnipotente; los planes por debajo no la tienen.

El multi-agente multiplica el consumo de un turno. Desde Max Agent, cuando la petición va al modelo automático, TITAN puede repartirla en varias subtareas paralelas (hasta 4, y 5 en Omnipotente). Cada subtarea se cobra por separado, a su modelo y a su peso, además de la síntesis final: un turno repartido entre cuatro modelos consume aproximadamente como cuatro turnos. Solo ocurre con el modelo automático y una vez por turno tuyo, no en cada paso del bucle de herramientas. Ver Multi-agente y visión.

1 crédito = 1.000 Theus Tokens (Theus Tokens, o TT, es la unidad interna que pondera cada modelo según su costo). El contador del periodo no suma tokens crudos: acumula tokens_weighted, el uso de cada petición ponderado por el peso de su modelo. La entrada y la salida ponderan distinto: los tokens que el modelo genera van a su peso completo, y los que lee (tu mensaje y el contexto) a un peso menor, porque upstream la entrada cuesta unas cinco veces menos. El cargo de un turno es tokens_de_entrada × peso_de_entrada + tokens_de_salida × peso_del_modelo. La tabla pública en theus.pe/consumo se alimenta de la misma configuración del gateway y publica ambas columnas, la referencia de una respuesta típica y el peso relativo. Un modelo económico consume menos créditos por token que uno premium; por eso la cuota se mide en créditos y no en tokens brutos.

Al agotar la cuota del ciclo, el gateway rechaza las peticiones con HTTP 429 y código quota_exceeded, indicando la fecha de renovación y la cabecera Retry-After:

HTTP 429  quota_exceeded
"Alcanzaste el límite de <N> créditos incluidos en tu plan <Plan> para este periodo.
 Tu cuota se renueva el <fecha>."

Si superas el límite de solicitudes por minuto (sin agotar la cuota), recibes el mismo HTTP 429 pero con código rate_limit_exceeded y un Retry-After de segundos. Puedes mejorar tu plan en theus.pe/#planes.

El cuerpo del quota_exceeded trae además un bloque en soles con el primer plan de la escalera peruana que da estrictamente más créditos que los que tenías, su precio con IGV y el enlace a la vitrina. Se ofrece la suscripción y no el pack a propósito: por el mismo S/ 39, el pack acredita 440 créditos y el plan Impulso 1.000. Nunca se sugiere un plan que tenga tu misma cuota, y nunca se abre un checkout solo.

Recarga de créditos (packs)

Si no quieres esperar a la renovación del ciclo, puedes recargar créditos con un pack prepago. Los créditos recargados no expiran y se suman a tu saldo:

Pack	Precio (USD)	Precio (soles)	Créditos
Chispa	—	S/ 9	100
Impulso	$10	S/ 39	440
Turbo	$25	S/ 99	1.120
Nitro	$60	S/ 239	2.750

En Perú puedes pagar en soles con tarjeta local o con Yape (vía MercadoPago), sin tarjeta internacional; fuera de Perú, con tarjeta internacional en dólares. Los dos rieles acreditan exactamente los mismos créditos.

Yape se paga sin salir de Theus. Escribes tu número de celular y el código de aprobación que te da tu app, y los créditos entran en el acto — sin tarjeta y sin pasar por otro sitio. Cómo funciona, cuánto cabe en un pago y qué hacer si Yape lo rechaza, en Pagar con Yape, sin salir de Theus.

Reglas de la recarga:

Prepago explícito, sin cobros sorpresa — tú eliges cuándo comprar; Theus nunca cobra de forma automática al agotarse tu cuota.
Orden de consumo — primero se agota la cuota incluida de tu plan del ciclo y solo después se usa tu saldo de créditos recargado. Nunca al revés.
No reembolsable — la compra es final. El pago pasa por Stripe (tarjeta internacional, dólares) o por MercadoPago (soles, con tarjeta local o Yape).
¿Pack o suscripción? — para la misma cifra en soles la suscripción rinde más: S/ 39 compran 440 créditos en pack y 1.000 al mes en el plan Impulso. El pack es para tapar un hueco a mitad de ciclo, no para sustituir un plan.
Tope por ciclo — hasta 4 packs por ciclo de plan.

Compra desde tu consola (sección Recargar créditos), desde la Estación de carga del chat, o desde el CLI con /recarga. El pago en soles —tarjeta peruana o Yape— funciona en los tres sitios: desde v1.2.0 el CLI cobra con Yape sin abrir el navegador.

Pagar con Yape, sin salir de Theus

Con un pack en soles, «Yape» cobra dentro de Theus: escribes tu número de celular y el código de aprobación de seis dígitos que genera tu app, y los créditos entran en tu saldo en el acto. No hace falta tarjeta —ni peruana ni internacional— ni salir a otra web a terminar la compra.

Funciona en los dos sitios donde compras: en la Estación de carga del chat, y en el CLI desde v1.2.0 — ahí eliges el pack en /recarga, pulsas y, y escribes los dos datos en la propia terminal.

El reparto de responsabilidades es lo que importa, porque es lo que protege tus datos:

Abres tu app de Yape y generas un código de aprobación de seis dígitos.
Escribes ese código y tu celular donde estés comprando: el formulario del chat o la pantalla del CLI. Tu propio equipo —el navegador o la terminal— se los entrega directamente a MercadoPago, que los canjea por un token de un solo uso.
Al servidor de Theus solo llega ese token, que no sirve para nada más. Con él se crea el cobro y se acreditan los créditos.

Tu celular y tu código de Yape no pasan por los servidores de Theus. Los valida MercadoPago directamente contra tu equipo —da igual que compres desde el navegador o desde la terminal—, así que nunca tocan nuestro servidor ni nuestros registros. Y no es una casualidad del diseño: si una petición llegara con el celular o el código dentro, el servidor la rechaza entera en lugar de ignorarlos en silencio — un cliente que los enviara estaría filtrando credenciales de pago a los registros sin saberlo.

El límite de un pago por Yape lo pones tú, no Theus. El monto máximo por operación se elige en la propia app de Yape —S/ 500, S/ 900 o S/ 2.000— y Theus no puede saber cuál tienes puesto. Por eso asume el más bajo del rango y no ofrece por Yape ningún pack que no quepa debajo: preferimos no ofrecerte algo que tu propia app va a rechazar. Hoy los cuatro packs en soles (Chispa, Impulso, Turbo y Nitro) caben de sobra bajo el tope más bajo, así que los cuatro se pagan con Yape. Si tu tope se te queda corto, súbelo desde tu app o paga con tarjeta.

Hay además un tope de intentos por hora (ocho por defecto). El token es de un solo uso, pero un rechazo deja reintentar, y sin techo este formulario sería una forma gratuita de sondear celulares y códigos ajenos.

Cuando Yape rechaza el pago

Un rechazo no mueve dinero: no se cobró nada y puedes volver a intentarlo. Theus traduce el motivo que devuelve MercadoPago a algo accionable, porque un mensaje que no dice qué hacer es una venta perdida:

Lo que ves	Qué pasó	Qué hacer
El código de Yape no coincide	El código caducó o se escribió mal; los de Yape duran poco a propósito.	Genera uno nuevo en tu app y vuelve a intentarlo.
Tu Yape no tiene saldo suficiente	El monto del pack supera tu saldo disponible.	Recarga tu Yape o elige un pack más pequeño.
El monto supera el límite que tienes puesto en tu app	Tu tope por operación (S/ 500, S/ 900 o S/ 2.000) se queda corto.	Súbelo desde Yape, o compra un pack menor.
Tu banco necesita autorizar este pago	El emisor pide una confirmación extra antes de dejarlo pasar.	Autorízalo desde la app de tu banco y reintenta.
Demasiados intentos seguidos	Se acumularon rechazos en muy poco tiempo.	Espera unos minutos antes de volver a probar.
Tu Yape está inhabilitado para pagos por internet	La cuenta no tiene activados los pagos en línea.	Actívalos desde tu app de Yape.
Ya hiciste un pago igual hace un momento	Entró un cobro idéntico hace muy poco.	Revisa tu saldo de créditos antes de reintentar, para no pagar dos veces.
Yape no aprobó el pago	Decisión del emisor, que no detalla el motivo.	Prueba con otro medio de pago o escríbenos.

Si alguna vez lees «cobramos el pago pero aún no vemos los créditos», no vuelvas a pagar. Significa que el dinero entró y la acreditación se quedó a medias. El aviso que MercadoPago manda por ese mismo pago vuelve a intentarla, y el abono es idempotente: se acredita una sola vez aunque el intento se repita. Los créditos aparecen solos en unos minutos.

Si el cobro dentro de Theus no está disponible en ese momento, la Estación de carga te lleva al checkout de MercadoPago, donde Yape también se puede pagar — solo que saliendo del sitio. En ningún caso se te pide una tarjeta internacional para pagar en soles.

Yape sirve para recargas, no para suscripciones. Un pago con Yape se autoriza una sola vez y su token no se puede reutilizar, así que no puede fundar un cobro recurrente: las suscripciones en soles se contratan con tarjeta peruana. Para pagar un plan con Yape existe el Fundador Anual: doce meses del plan Pro en un pago único.

Desde el CLI, en una sesión interactiva

Escribe /recarga y se abre un selector: verás tu saldo actual, los packs que quedan en el ciclo, y cada pack con su precio, sus créditos y su coste por crédito para poder compararlos.

↑ ↓ eligen el pack · Enter confirma · Esc sale.
Al confirmar, Theus crea el pago y abre tu navegador en el checkout de Stripe.
Después espera la acreditación y te muestra el saldo nuevo en cuanto entra, así vuelves a trabajar sin comprobar nada a mano. Esc deja de esperar; el pago sigue su curso y los créditos se acreditan igual.
/recarga turbo abre el selector con ese pack ya marcado.

Entrar al comando no cuesta nada y no crea ninguna sesión de pago: la compra se crea solo al confirmar, y una sola vez por intento. La escalera de precios que ves la sirve el mismo componente que cobra, así que no puede quedar desfasada. Compra final, sin reembolsos.

Desde un script (modo no interactivo)

theus -p "/recarga"                     # lista los packs y sus precios
theus -p "/recarga turbo"               # muestra el pack elegido; no cobra ni abre nada
theus -p "/recarga turbo confirmar"     # abre el checkout seguro de Stripe

En este modo el comando solo crea la sesión de pago cuando escribes confirmar: sin esa palabra no se genera ningún enlace de pago. Compra final, sin reembolsos.

Packs de imagen y vídeo

Además de los créditos de texto, puedes recargar imagen y vídeo con packs de cubo propio: no se mezclan con tus créditos de texto y no expiran. La imagen se cuenta por unidad entregada; el vídeo en créditos de vídeo, ponderados por el peso real de cada modelo.

Pack de imagen	Imágenes	Precio
Vista	50	$19
Galería	150	$49
Estudio	400	$119

Pack de vídeo	Créditos de vídeo	Precio
Clip	800	$19
Escena	2.200	$49
Rodaje	5.600	$119

Se compran con tu sesión iniciada, desde tu consola (sección «Recargar créditos») o desde la Estación de carga del chat. El plan Omnipresente ya incluye 300 imágenes y 1.320 créditos de vídeo al mes con cuota propia; estos packs son para ampliar. Prepago, sin reembolso.

Modelos desconocidos y estimaciones

Theus solo conoce las tarifas de sus propios modelos de primera parte. Si usas un modelo cuyo precio no está registrado, Theus lo estima aplicando una tarifa por defecto y marca el resumen con una advertencia:

Total cost:            $0.1234 (costs may be inaccurate due to usage of unknown models)

Con un modelo desconocido, la cifra que ves es una estimación, no una factura. El costo real siempre lo determina tu proveedor. Trata /cost como una guía de consumo, no como un documento de facturación.

Modelo local-first: el costo depende del proveedor

Theus es local-first: ningún servicio remoto es obligatorio para arrancar. Esto tiene consecuencias directas sobre el costo:

Modelo local — si ejecutas el modelo en tu propia máquina o infraestructura, no hay cargo por token: el "costo" es tu propio cómputo. La estimación de /cost puede seguir apareciendo, pero no representa un gasto facturable.
BYOK (tu propia clave) — al conectar tu clave a un proveedor compatible, el consumo y la tarifa reales los define ese proveedor, según su propia política de precios. La estimación de Theus solo coincidirá con tu factura si el modelo y sus tarifas coinciden con los niveles conocidos.
Suscripción Theus — el uso se cubre con la cuota de créditos de tu plan (ver Cuotas por plan); /cost lo refleja como cobertura de suscripción en lugar de gasto por token.

La selección de proveedor sigue el orden documentado (variables THEUS_BASE_URL / THEUS_OPENAI_BASE_URL, luego el primer proveedor con capacidad de texto en ~/.theus/providers.json, y por último el motor compatible). El costo depende de cuál de estos atiende tus solicitudes.

Persistencia y resumen de sesión

El costo acumulado se guarda junto con la configuración del proyecto y se asocia a la sesión actual. Al reanudar la misma sesión, Theus restaura el costo, la duración y el uso por modelo, de modo que el total sigue creciendo desde donde lo dejaste en lugar de reiniciarse.

Cuando la sesión termina, si tu cuenta tiene acceso a facturación en consola, Theus imprime automáticamente el mismo resumen de /cost al salir, para que quede un registro del consumo de la sesión.

Consulta también la página de proveedores para configurar BYOK o un modelo local, y la de seguridad para entender qué datos permanecen en tu equipo bajo el modelo local-first.

Theus — Muchas inteligencias. Una decisión.