Skip to main content
LLM Blueprint avvolge il tuo client LLM in modo che ogni chiamata completata invii a Dodo Payments un evento di utilizzo con il numero di token di input, output e totali. Un meter somma questi conteggi, così puoi fatturare a ogni cliente i token che utilizza. Il blueprint è incluso nel pacchetto npm @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 con test_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.
Salva le chiavi API nelle variabili d’ambiente. Non inserirle nel controllo versione.
3

Create a Meter in Dodo Payments

Crea un meter prima di monitorare l’utilizzo:
  1. Nella dashboard di Dodo Payments, vai a Products → Meters.
  2. Fai clic su Create Meter.
  3. 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.
  4. 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).
Per istruzioni dettagliate, consulta la Usage-Based Billing Guide.
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.
Gli SDK di Dodo Payments usano invece per impostazione predefinita live_mode, quindi imposta esplicitamente live_mode in produzione.
Usa test_mode durante lo sviluppo, così il traffico di test non crea eventi di utilizzo reali.
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.
Oltre a 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 a wrap():
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_.
Salva l’ID cliente di Dodo Payments di ogni utente insieme al relativo record utente e passalo qui. L’ID utente della tua applicazione non corrisponde a un cliente di Dodo Payments.
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 metadati provider 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:
Monitora l’utilizzo con Vercel AI SDK, che offre un’unica interfaccia per numerosi provider LLM.
Metriche monitorate:
  • inputTokens → inputTokens
  • outputTokens + reasoningTokens → outputTokens
  • totalTokens → totalTokens
  • Nome del modello: i risultati di AI SDK non hanno un campo model di primo livello, quindi il tracker registra unknown. Per registrare il modello, passalo come model in metadata del 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.
Monitora l’utilizzo dei token su oltre 200 modelli tramite l’API unificata di OpenRouter.
Metriche monitorate:
  • prompt_tokens → inputTokens
  • completion_tokens → outputTokens
  • total_tokens → totalTokens
  • Nome del modello
OpenRouter offre accesso ai modelli di OpenAI, Anthropic, Google, Meta e altri provider tramite un’unica API.
Monitora l’utilizzo dei token dei modelli GPT di OpenAI.
Metriche monitorate:
  • prompt_tokens → inputTokens
  • completion_tokens → outputTokens
  • total_tokens → totalTokens
  • Nome del modello
Monitora l’utilizzo dei token dei modelli Claude di Anthropic.
Metriche monitorate:
  • input_tokens → inputTokens
  • output_tokens → outputTokens
  • totalTokens, calcolato come input_tokens + output_tokens
  • Nome del modello
Monitora l’utilizzo dei token dei modelli forniti da Groq.
Metriche monitorate:
  • prompt_tokens → inputTokens
  • completion_tokens → outputTokens
  • total_tokens → totalTokens
  • Nome del modello
Monitora l’utilizzo dei token dei modelli Gemini di Google tramite Google GenAI SDK.
Metriche monitorate:
  • promptTokenCount → inputTokens
  • candidatesTokenCount + thoughtsTokenCount → outputTokens
  • totalTokenCount → 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:
Usa un nome dell’evento diverso per ogni provider, con un meter per ciascuno, per monitorare separatamente l’utilizzo.

Integrazione API Express.js

Questa API Express.js monitora ogni completamento della chat per il cliente che ha effettuato la richiesta. Per brevità, legge userId 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, come gpt-4, oppure unknown se 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.
Ultima modifica il 26 settembre 2026