@dodopayments/ingestion-blueprints como createLLMTracker().
Quick Start
Instala el SDK, crea un medidor y envuelve tu cliente de LLM.
API Reference - Events Ingestion
El endpoint de API que recibe los eventos de uso.
API Reference - Meters
Crea y configura medidores para la facturación.
Usage-Based Billing Guide
Configura la facturación basada en el uso con medidores de principio a fin.
Úsalo en aplicaciones SaaS, chatbots de IA, herramientas de generación de contenido y cualquier otra aplicación basada en LLM que facture según el uso.
Inicio rápido
Para realizar un seguimiento del uso de tokens, instala el paquete, crea un medidor y envuelve tu cliente de LLM.1
Install the SDK
Instala el paquete Dodo Payments Ingestion Blueprints:Instala también el SDK de tu proveedor de LLM, como
openai, @anthropic-ai/sdk, groq-sdk, @google/genai o ai con @ai-sdk/google.2
Get Your API Keys
Necesitas dos claves de API:
- Clave de API de Dodo Payments: Crea una en Developer → API Keys, dentro del panel de Dodo Payments, y guárdala en
DODO_PAYMENTS_API_KEY. Usa una clave de modo de prueba mientras desarrollas. Una clave de modo de prueba solo funciona contest_mode. - Clave de API del proveedor de LLM: La clave del proveedor al que llamas, como OpenAI, Anthropic, Groq, OpenRouter o Google. Los ejemplos la leen de variables como
OPENAI_API_KEY.
3
Create a Meter in Dodo Payments
Crea un medidor antes de realizar el seguimiento del uso:Para obtener instrucciones detalladas, consulta la Guía de facturación basada en el uso.
- En el panel de Dodo Payments, ve a Products → Meters.
- Haz clic en Create Meter.
- Configura el medidor:
- Meter Name: Un nombre descriptivo, como
LLM Token Usage. - Event Name: Un identificador de evento único, como
llm.chat_completion. - Aggregation Type: Sum, para sumar los recuentos de tokens.
- Over Property: El recuento de tokens que se facturará:
inputTokens: tokens de entrada (prompt).outputTokens: tokens de salida (completion), incluidos los tokens de razonamiento cuando el modelo los informa.totalTokens: tokens de entrada y salida combinados.
- Measurement Unit: La unidad que se muestra en las facturas, como
tokens.
- Meter Name: Un nombre descriptivo, como
- Haz clic en Create Meter.
El Event Name que establezcas aquí debe coincidir exactamente con el
eventName que pasas al SDK (distingue mayúsculas de minúsculas).4
Track Token Usage
Crea un tracker, envuelve tu cliente de LLM y llama al cliente como de costumbre:
Cada llamada completada a través del cliente envuelto ahora envía un evento de uso con sus recuentos de tokens a Dodo Payments para la facturación.
Configuración
Configuración del tracker
Crea un tracker una sola vez al iniciar la aplicación y reutilízalo para cada cliente.createLLMTracker() acepta estas opciones y genera un error si apiKey o eventName falta o está vacío:
string
requerido
Tu API key de Dodo Payments. Obtenla en la página de API Keys.
string
El modo de entorno del tracker:
test_mode: para desarrollo y pruebas. Es el valor predeterminado.live_mode: para producción.
live_mode de forma predeterminada, así que establece live_mode explícitamente en producción.string
requerido
El nombre del evento que activa tu medidor. Debe coincidir exactamente con el Event Name de tu medidor de Dodo Payments (distingue mayúsculas de minúsculas).
Este nombre de evento vincula el uso registrado con el medidor correcto para los cálculos de facturación.
wrap(), el tracker tiene track(response, customerId, metadata), que registra el uso de una respuesta que ya tienes, y healthCheck(), que devuelve true cuando la API de Dodo Payments está disponible.
Configuración del wrapper
Pasa estos parámetros awrap():
object
requerido
La instancia de tu cliente de LLM, como un cliente de OpenAI, Anthropic, Groq o Google GenAI, o un objeto que contenga funciones de AI SDK, como
{ generateText }.string
requerido
El ID de cliente de Dodo Payments del cliente al que se facturará. Comienza con
cus_.object
Datos adicionales opcionales que se adjuntan a cada evento de seguimiento, para filtrado y análisis. Cada valor debe ser una cadena, un número o un booleano. Una clave llamada
inputTokens, outputTokens, totalTokens o model reemplaza el valor registrado.Ejemplo de configuración completa
Este ejemplo registra una llamada de AI SDK y adjunta metadatos deprovider al evento:
Seguimiento automático: El wrapper devuelve sin cambios la respuesta del proveedor, por lo que tu código sigue siendo el mismo que con el SDK original del proveedor. Envía el evento de uso antes de devolver la respuesta, de modo que cada llamada espera a que se complete la solicitud de ingestión; si esta falla, la llamada envuelta genera un error aunque la llamada al proveedor haya tenido éxito. Las respuestas de streaming no incluyen los recuentos finales de tokens en el objeto devuelto, por lo que el wrapper no realiza su seguimiento.
Proveedores compatibles
El tracker lee los recuentos de tokens de los formatos de respuesta de estos proveedores y SDK:AI SDK (Vercel)
AI SDK (Vercel)
Realiza un seguimiento del uso con Vercel AI SDK, que ofrece una interfaz para muchos proveedores de LLM.Métricas registradas:
inputTokens→inputTokensoutputTokens+reasoningTokens→outputTokenstotalTokens→totalTokens- Nombre del modelo: los resultados de AI SDK no tienen un campo
modelde nivel superior, por lo que el tracker registraunknown. Para registrar el modelo, pásalo comomodelenmetadatadel wrapper, como en este ejemplo.
Cuando usas un modelo con capacidad de razonamiento mediante AI SDK, como Gemini 2.5 Flash de Google con el modo de pensamiento activado, el tracker añade los tokens de razonamiento informados a
outputTokens.OpenRouter
OpenRouter
Realiza un seguimiento del uso de tokens en más de 200 modelos mediante la API unificada de OpenRouter.Métricas registradas:
prompt_tokens→inputTokenscompletion_tokens→outputTokenstotal_tokens→totalTokens- Nombre del modelo
OpenAI
OpenAI
Realiza un seguimiento del uso de tokens de los modelos GPT de OpenAI.Métricas registradas:
prompt_tokens→inputTokenscompletion_tokens→outputTokenstotal_tokens→totalTokens- Nombre del modelo
Anthropic Claude
Anthropic Claude
Realiza un seguimiento del uso de tokens de los modelos Claude de Anthropic.Métricas registradas:
input_tokens→inputTokensoutput_tokens→outputTokenstotalTokens, calculado comoinput_tokens+output_tokens- Nombre del modelo
Groq
Groq
Realiza un seguimiento del uso de tokens de los modelos servidos por Groq.Métricas registradas:
prompt_tokens→inputTokenscompletion_tokens→outputTokenstotal_tokens→totalTokens- Nombre del modelo
Google Gemini
Google Gemini
Realiza un seguimiento del uso de tokens de los modelos Gemini de Google mediante el SDK de Google GenAI.Métricas registradas:
promptTokenCount→inputTokenscandidatesTokenCount+thoughtsTokenCount→outputTokenstotalTokenCount→totalTokens- Versión del modelo, de
modelVersion
Modo de pensamiento de Gemini: En los modelos Gemini que piensan antes de responder, como Gemini 2.5 Pro, el tracker añade
thoughtsTokenCount (tokens de razonamiento) a outputTokens, de modo que el evento refleja toda la salida producida por el modelo.Uso avanzado
Varios proveedores
Para realizar un seguimiento por separado del uso en distintos proveedores de LLM, crea un tracker por proveedor:Integración de API con Express.js
Esta API de Express.js registra cada completion de chat para el cliente que realizó la solicitud. Para simplificar, leeuserId del cuerpo de la solicitud. userId debe ser el ID de cliente de Dodo Payments del usuario. En producción, léelo de la sesión autenticada en lugar de confiar en el cuerpo de la solicitud.
Qué se registra
Cada llamada registrada envía un evento de uso a Dodo Payments con esta estructura:Campos del evento
string
Identificador único de este evento. El SDK lo genera.Formato:
llm_[timestamp]_[random], donde timestamp es la hora en milisegundos y random son seis caracteres aleatorios.string
El ID de cliente que pasaste al envolver el cliente. Dodo Payments factura a este cliente.
string
El nombre del evento que activa tu medidor. Procede de la configuración de tu tracker.
string
Marca de tiempo ISO 8601, establecida cuando el tracker envía el evento después de que responde el proveedor.
object
Uso de tokens y datos de seguimiento adicionales:
inputTokens: número de tokens de entrada (prompt) utilizados.outputTokens: número de tokens de salida (completion) utilizados, incluidos los tokens de razonamiento cuando corresponda.totalTokens: tokens totales (entrada + salida).model: el modelo de LLM utilizado, comogpt-4, ounknownsi la respuesta no especifica ninguno.provider: el proveedor de LLM, si lo incluiste en los metadatos del wrapper.- Cualquier metadato personalizado que proporcionaste al envolver el cliente.
Tokens de razonamiento: En los modelos con capacidades de razonamiento,
outputTokens incluye tanto los tokens de completion como los tokens de razonamiento.Tu medidor de Dodo Payments utiliza los campos
metadata, normalmente inputTokens, outputTokens o totalTokens, para calcular el uso y la facturación.