@dodopayments/ingestion-blueprints come createLLMTracker().
Quick Start
Installa l’SDK, crea un meter e avvolgi il tuo client LLM.
API Reference - Events Ingestion
L’endpoint API che riceve gli eventi di utilizzo.
API Reference - Meters
Crea e configura i meter per la fatturazione.
Usage-Based Billing Guide
Configura la fatturazione basata sull’utilizzo con i meter dall’inizio alla fine.
Usalo in applicazioni SaaS, chatbot AI, strumenti per la generazione di contenuti e qualsiasi altra applicazione basata su LLM che fattura in base all’utilizzo.
Avvio rapido
Per monitorare l’utilizzo dei token, installa il pacchetto, crea un meter e avvolgi il tuo client LLM.1
Install the SDK
Installa il pacchetto Dodo Payments Ingestion Blueprints:Installa anche l’SDK del tuo provider LLM, ad esempio
openai, @anthropic-ai/sdk, groq-sdk, @google/genai o ai con @ai-sdk/google.2
Get Your API Keys
Sono necessarie due chiavi API:
- Chiave API di Dodo Payments: creane una in Developer → API Keys nella dashboard di Dodo Payments e salvala in
DODO_PAYMENTS_API_KEY. Usa una chiave in modalità test durante lo sviluppo. Una chiave in modalità test funziona solo contest_mode. - Chiave API del provider LLM: la chiave del provider che utilizzi, ad esempio OpenAI, Anthropic, Groq, OpenRouter o Google. Gli esempi la leggono da variabili come
OPENAI_API_KEY.
3
Create a Meter in Dodo Payments
Crea un meter prima di monitorare l’utilizzo:Per istruzioni dettagliate, consulta la Usage-Based Billing Guide.
- Nella dashboard di Dodo Payments, vai a Products → Meters.
- Fai clic su Create Meter.
- Configura il meter:
- Meter Name: un nome descrittivo, ad esempio
LLM Token Usage. - Event Name: un identificatore univoco dell’evento, ad esempio
llm.chat_completion. - Aggregation Type: Sum, per sommare i conteggi dei token.
- Over Property: il conteggio dei token da fatturare:
inputTokens: token di input (prompt).outputTokens: token di output (completamento), inclusi i token di ragionamento quando il modello li comunica.totalTokens: token di input e output combinati.
- Measurement Unit: l’unità mostrata sulle fatture, ad esempio
tokens.
- Meter Name: un nome descrittivo, ad esempio
- Fai clic su Create Meter.
Il valore Event Name impostato qui deve corrispondere esattamente a
eventName, che passi all’SDK (con distinzione tra maiuscole e minuscole).4
Track Token Usage
Crea un tracker, avvolgi il tuo client LLM e chiama il client come di consueto:
Ogni chiamata completata tramite il client avvolto ora invia a Dodo Payments un evento di utilizzo con i relativi conteggi dei token per la fatturazione.
Configurazione
Configurazione del Tracker
Crea un tracker una volta all’avvio dell’applicazione e riutilizzalo per ogni cliente.createLLMTracker() accetta queste opzioni e genera un errore se apiKey o eventName manca o è vuoto:
string
obbligatorio
La tua chiave API di Dodo Payments. Ottienila dalla pagina delle chiavi API.
string
La modalità dell’ambiente per il tracker:
test_mode: per sviluppo e test. È il valore predefinito.live_mode: per la produzione.
live_mode, quindi imposta esplicitamente live_mode in produzione.string
obbligatorio
Il nome dell’evento che attiva il tuo meter. Deve corrispondere esattamente a Event Name del meter di Dodo Payments (con distinzione tra maiuscole e minuscole).
Questo nome dell’evento collega l’utilizzo monitorato al meter corretto per i calcoli di fatturazione.
wrap(), il tracker dispone di track(response, customerId, metadata), che registra l’utilizzo da una risposta già disponibile, e di healthCheck(), che restituisce true quando l’API di Dodo Payments è raggiungibile.
Configurazione del wrapper
Passa questi parametri awrap():
object
obbligatorio
L’istanza del tuo client LLM, ad esempio un client OpenAI, Anthropic, Groq o Google GenAI, oppure un oggetto che contiene funzioni AI SDK, come
{ generateText }.string
obbligatorio
L’ID cliente di Dodo Payments del cliente da fatturare. Inizia con
cus_.object
Dati aggiuntivi facoltativi da allegare a ogni evento di tracking, per il filtraggio e l’analisi. Ogni valore deve essere una stringa, un numero o un booleano. Una chiave denominata
inputTokens, outputTokens, totalTokens o model sostituisce il valore monitorato.Esempio di configurazione completa
Questo esempio monitora una chiamata AI SDK e allega metadatiprovider all’evento:
Tracking automatico: il wrapper restituisce invariata la risposta del provider, quindi il tuo codice rimane uguale a quello usato con l’SDK del provider originale. Invia l’evento di utilizzo prima di restituire la risposta, quindi ogni chiamata attende la richiesta di ingestion e una richiesta di ingestion non riuscita fa fallire la chiamata avvolta anche quando la chiamata al provider è riuscita. Le risposte in streaming non contengono i conteggi finali dei token nell’oggetto restituito, quindi il wrapper non le monitora.
Provider supportati
Il tracker legge i conteggi dei token dai formati di risposta dei seguenti provider e SDK:AI SDK (Vercel)
AI SDK (Vercel)
Monitora l’utilizzo con Vercel AI SDK, che offre un’unica interfaccia per numerosi provider LLM.Metriche monitorate:
inputTokens→inputTokensoutputTokens+reasoningTokens→outputTokenstotalTokens→totalTokens- Nome del modello: i risultati di AI SDK non hanno un campo
modeldi primo livello, quindi il tracker registraunknown. Per registrare il modello, passalo comemodelinmetadatadel wrapper, come nell’esempio.
Quando utilizzi un modello con capacità di ragionamento tramite AI SDK, come Gemini 2.5 Flash di Google con la modalità thinking, il tracker aggiunge i token di ragionamento segnalati a
outputTokens.OpenRouter
OpenRouter
Monitora l’utilizzo dei token su oltre 200 modelli tramite l’API unificata di OpenRouter.Metriche monitorate:
prompt_tokens→inputTokenscompletion_tokens→outputTokenstotal_tokens→totalTokens- Nome del modello
OpenAI
OpenAI
Monitora l’utilizzo dei token dei modelli GPT di OpenAI.Metriche monitorate:
prompt_tokens→inputTokenscompletion_tokens→outputTokenstotal_tokens→totalTokens- Nome del modello
Anthropic Claude
Anthropic Claude
Monitora l’utilizzo dei token dei modelli Claude di Anthropic.Metriche monitorate:
input_tokens→inputTokensoutput_tokens→outputTokenstotalTokens, calcolato comeinput_tokens+output_tokens- Nome del modello
Groq
Groq
Monitora l’utilizzo dei token dei modelli forniti da Groq.Metriche monitorate:
prompt_tokens→inputTokenscompletion_tokens→outputTokenstotal_tokens→totalTokens- Nome del modello
Google Gemini
Google Gemini
Monitora l’utilizzo dei token dei modelli Gemini di Google tramite Google GenAI SDK.Metriche monitorate:
promptTokenCount→inputTokenscandidatesTokenCount+thoughtsTokenCount→outputTokenstotalTokenCount→totalTokens- Versione del modello, da
modelVersion
Modalità Thinking di Gemini: per i modelli Gemini che elaborano la risposta prima di fornirla, come Gemini 2.5 Pro, il tracker aggiunge
thoughtsTokenCount (token di ragionamento) a outputTokens, così l’evento riflette l’output completo prodotto dal modello.Utilizzo avanzato
Più provider
Per monitorare separatamente l’utilizzo tra diversi provider LLM, crea un tracker per ogni provider:Integrazione API Express.js
Questa API Express.js monitora ogni completamento della chat per il cliente che ha effettuato la richiesta. Per brevità, leggeuserId dal corpo della richiesta. userId deve essere l’ID cliente di Dodo Payments dell’utente. In produzione, leggilo invece dalla sessione autenticata, anziché fidarti del corpo della richiesta.
Cosa Viene Monitorato
Ogni chiamata monitorata invia a Dodo Payments un evento di utilizzo con questa struttura:Campi Evento
string
Identificatore univoco per questo evento. Viene generato dall’SDK.Formato:
llm_[timestamp]_[random], dove timestamp è l’ora in millisecondi e random è composto da sei caratteri casuali.string
L’ID cliente passato quando hai avvolto il client. Dodo Payments fattura questo cliente.
string
Il nome dell’evento che attiva il tuo meter. Proviene dalla configurazione del tracker.
string
Timestamp ISO 8601, impostato quando il tracker invia l’evento dopo la risposta del provider.
object
Utilizzo dei token e dati aggiuntivi di monitoraggio:
inputTokens: numero di token di input (prompt) utilizzati.outputTokens: numero di token di output (completamento) utilizzati, inclusi i token di ragionamento quando applicabile.totalTokens: token totali (input + output).model: il modello LLM utilizzato, comegpt-4, oppureunknownse la risposta non ne specifica uno.provider: il provider LLM, se lo hai incluso nei metadati del wrapper.- Qualsiasi metadato personalizzato fornito quando hai avvolto il client.
Token di ragionamento: per i modelli con capacità di ragionamento,
outputTokens include sia i token di completamento sia i token di ragionamento.Il meter di Dodo Payments utilizza i campi
metadata, generalmente inputTokens, outputTokens o totalTokens, per calcolare utilizzo e fatturazione.