Medidor de Balance de Gastos para la API de Kimi (Moonshot AI) con ESP32 y LVGL

KimiRate es un monitor físico de saldo open source que conecta un ESP32 a la API de Kimi (Moonshot AI), consulta tu balance en tiempo real y lo visualiza en una pantalla TFT ILI9341 con una interfaz gráfica moderna construida con LVGL v9. Ideal para desarrolladores que consumen tokens de IA y necesitan monitorear sus gastos sin depender del navegador.

Si desarrollas aplicaciones con modelos de lenguaje como Kimi de Moonshot AI, sabes que controlar el consumo de tokens es fundamental. Cada llamada a la API tiene un costo, y mantenerse al tanto del saldo disponible suele implicar entrar al panel web o hacer peticiones manuales.

KimiRate resuelve esto con un enfoque de hardware: un dispositivo dedicado que consulta automáticamente tu balance cada 60 segundos y lo muestra en una pantalla física con una interfaz visual clara y atractiva.

Este proyecto demuestra cómo combinar ESP-IDF, LVGL y HTTP/REST para crear interfaces IoT útiles, robustas y con estética profesional.

El Problema

Los desarrolladores que integran Kimi API o Moonshot AI en sus productos enfrentan un problema común:

• Falta de visibilidad en tiempo real: El saldo solo se consulta cuando se hace una petición o se accede al panel web.
• Riesgo de interrupción de servicio: Si el saldo se agota, las llamadas a la API fallan sin previo aviso.
• Monitoreo pasivo: No existe una forma nativa de "ver" tu balance sin abrir una pestaña del navegador.

La alternativa típica —hacer polling desde un script en el PC— consume recursos y no ofrece una visualización permanente.

La Solución: KimiRate

KimiRate es un medidor de gastos físico que:

• Se conecta a tu red WiFi con reconexión automática.
• Consulta periódicamente el endpoint /v1/users/me/balance de la Kimi API.
• Renderiza el saldo en una pantalla TFT ILI9341 de 240×320 píxeles usando LVGL v9.
• Muestra el balance total, desglose por tipo (granted/recargado) y una barra de progreso visual del saldo restante.
• Cambia de color según el nivel de saldo: verde, amarillo o rojo.

El resultado es un panel administrativo físico que puedes dejar sobre tu escritorio y consultar de un vistazo.

Características Técnicas

Estados visuales de la barra de progreso

La barra de progreso considera 5 USD como 100% del saldo. Según el porcentaje restante, cambia de color:

Hardware y Conexiones

La PCB: display-esp32

El proyecto corre sobre una PCB personalizada diseñada en KiCad: hardware-display-esp32. Es una placa compacta que integra el ESP32, regulación de potencia, interfaz USB-serial y conector para display SPI. En las fotos se aprecia el texto "MAYKOLREY.COM" impreso en la serigrafía roja.

Pie de imagen:

Pie de imagen:PCB from PCBWay

El foco de este artículo es el firmware KimiRate, pero la PCB es la base hardware que hace posible el proyecto.

Componentes principales

Tabla de conexiones ESP32 ↔ TFT ILI9341

Nota: Todos los pines son configurables vía menuconfig. La tabla anterior muestra los valores por defecto del proyecto.

Consideraciones de resolución

Aunque la pantalla física tiene resolución nativa de 240×320, la interfaz de usuario se renderiza en orientación horizontal como 320×240. Se recomienda mantener:

• LCD Width = 240
• LCD Height = 320

A menos que tu panel tenga una resolución nativa diferente.

Cómo Funciona

Arquitectura del firmware

El proyecto está organizado en módulos independientes dentro de main/:

kimi-rate/
├── CMakeLists.txt
├── partitions.csv          # Tabla de particiones custom (1.5MB app / 4MB flash)
├── sdkconfig.defaults      # Configuración por defecto de ESP-IDF
├── lv_conf.h               # Configuración personalizada de LVGL
└── main/
    ├── CMakeLists.txt
    ├── idf_component.yml   # Dependencias: lvgl, esp_lcd_ili9341
    ├── Kconfig.projbuild   # Opciones de menuconfig
    ├── main.c              # Punto de entrada + loop de actualización
    ├── wifi_manager.c/h    # Gestión de WiFi y reconexión
    ├── kimi_api.c/h        # Cliente HTTP para la API de Kimi
    └── display_manager.c/h # Driver ILI9340 SPI + UI con LVGL

Flujo de operación

1. Inicio: El ESP32 inicializa el display SPI y LVGL.
2. Conexión WiFi: El wifi_manager se conecta a la red configurada. Si se pierde la conexión, reintenta automáticamente.
3. Consulta API: Cada 60 segundos, kimi_api realiza una petición HTTPS autenticada al endpoint:

   GET https://api.moonshot.ai/v1/users/me/balance
   Authorization: Bearer <KIMI_API_KEY>
   

4. Parseo: Se extraen los campos total, granted y topped_up de la respuesta JSON.
5. Renderizado: El display_manager actualiza la UI con los nuevos valores y recalcula el porcentaje de la barra de progreso.
6. Cambio de color: Si el porcentaje cae por debajo de los umbrales, la barra cambia a amarillo o rojo.

Interfaz gráfica

La UI muestra los siguientes elementos:

• Título: "Kimi Balance"
• Saldo total: con moneda (USD)
• Granted: saldo gratuito otorgado por Moonshot
• Topped Up: saldo recargado por el usuario
• Barra de progreso: "SALDO RESTANTE" con porcentaje visual

La interfaz utiliza un tema oscuro con acento naranja/rosa, diseñado para ser legible en condiciones de iluminación variadas.

Configuración y Compilación

Requisitos previos

• ESP-IDF v5.x instalado y configurado
• Python 3 y idf.py disponibles en PATH
• Una API Key de Kimi (obtenible en platform.moonshot.cn)

Pasos de instalación

# Clonar el repositorio
git clone https://github.com/picli3/kimi-rate.git
cd kimi-rate

# Configurar credenciales y parámetros
idf.py menuconfig

Dentro de menuconfig, navega a:

Kimi Balance Monitor Configuration  --->
    (myssid)        WiFi SSID
    (mypassword)    WiFi Password
    (sk-xxxxxxxx)   Kimi API Key
    ILI9340 Display (SPI)  --->
        (240) LCD Width
        (320) LCD Height
        (23)  MOSI GPIO
        (18)  SCLK GPIO
        (13)  CS GPIO
        (27)  DC GPIO
        (5)   RESET GPIO
        (32)  BACKLIGHT GPIO

Compilar y flashear

# Compilar
idf.py build

# Flashear y monitorear (ajusta el puerto según tu sistema)
idf.py -p /dev/ttyUSB0 flash monitor

El proyecto incluye una tabla de particiones custom (partitions.csv) de 1.5MB para la aplicación en flash de 4MB. Esta configuración se aplica automáticamente vía sdkconfig.defaults.

Fotos del Proyecto

Foto 1: Vista frontal del panel

Vista frontal de la PCB roja personalizada con el texto "MAYKOLREY.COM" impreso. Muestra el título "PANEL ADMINISTRATIVO - Resumen del saldo", el SALDO DISPONIBLE Total: 0.95 USD, el SALDO RESTANTE al 19%, y el desglose detallado entre saldo granted y topped up.

Foto 2: Vista lateral

Vista lateral de la PCB mostrando la interfaz completa: "Kimi Balance Total: 0.95 USD", desglose de Granted: 0.00 y Topped Up: 0.95, junto con la barra de progreso del SALDO RESTANTE.

Foto 3: Vista cercana de la pantalla

Vista detallada del display mostrando el título "KimiRate", el balance total de 0.95 USD y la barra de progreso al 19% con su indicador visual.

Casos de Uso

1. Monitor de escritorio para desarrolladores

Coloca KimiRate junto a tu monitor y ten visibilidad permanente de tu saldo mientras desarrollas aplicaciones con Kimi API o Moonshot AI.

2. Panel de control en equipos de I+D

En equipos que comparten una cuenta de Kimi, el dispositivo permite que todos los miembros vean el consumo colectivo sin necesidad de acceder al panel web.

3. Demostración técnica y portfolio

El proyecto es un excelente ejemplo de integración entre ESP-IDF, LVGL y APIs REST. Puede servir como referencia para otros desarrolladores de sistemas embebidos.

4. Base para otros monitores de API

La arquitectura modular de KimiRate permite adaptarlo fácilmente para monitorear otras APIs: OpenAI, Claude, Stripe, GitHub Actions, etc.

Conclusión

KimiRate demuestra que los sistemas embebidos pueden ir más allá de los sensores tradicionales: pueden interactuar con servicios en la nube, consumir APIs modernas y presentar información útil en interfaces gráficas profesionales.

Combinando ESP32, ESP-IDF, LVGL v9 y una pantalla ILI9341, el proyecto ofrece:

• ✅ Monitoreo en tiempo real del balance de Kimi API
• ✅ Reconexión automática WiFi robusta
• ✅ Interfaz visual atractiva con tema oscuro
• ✅ Código modular y fácilmente extensible
• ✅ 100% open source bajo licencia MIT

Si consumes tokens de Moonshot AI y quieres dejar de consultar tu saldo desde el navegador, KimiRate es la solución hardware que necesitas.

Recursos y Enlaces

Palabras clave

Kimi API, Moonshot AI, ESP32, medidor de gastos, balance API, LVGL, ILI9341, ESP-IDF, monitor de saldo, IoT, interfaz gráfica embebida, pantalla TFT, SPI, API REST, hardware open source.

Artículo técnico basado en el proyecto KimiRate de Maykol Rey. Publicado bajo licencia MIT.