@dodopayments/ingestion-blueprints como createLLMTracker().
Quick Start
Instale o SDK, crie um medidor e encapsule seu cliente de LLM.
API Reference - Events Ingestion
O endpoint da API que recebe eventos de uso.
API Reference - Meters
Crie e configure medidores para cobrança.
Usage-Based Billing Guide
Configure a cobrança baseada em uso com medidores, do início ao fim.
Use-o em aplicativos SaaS, chatbots de IA, ferramentas de geração de conteúdo e qualquer outro aplicativo baseado em LLM que faça cobranças por uso.
Início rápido
Para acompanhar o uso de tokens, instale o pacote, crie um medidor e encapsule seu cliente de LLM.1
Install the SDK
Instale o pacote Dodo Payments Ingestion Blueprints:Instale também o SDK do seu provedor de LLM, como
openai, @anthropic-ai/sdk, groq-sdk, @google/genai ou ai com @ai-sdk/google.2
Get Your API Keys
Você precisa de duas chaves de API:
- Chave de API do Dodo Payments: crie uma em Developer → API Keys, no dashboard do Dodo Payments, e armazene-a em
DODO_PAYMENTS_API_KEY. Use uma chave de modo de teste enquanto desenvolve. Uma chave de modo de teste funciona apenas comtest_mode. - Chave de API do provedor de LLM: a chave do provedor que você chama, como OpenAI, Anthropic, Groq, OpenRouter ou Google. Os exemplos leem essa chave de variáveis como
OPENAI_API_KEY.
3
Create a Meter in Dodo Payments
Crie um medidor antes de acompanhar o uso:Para obter instruções detalhadas, consulte o Usage-Based Billing Guide.
- No dashboard do Dodo Payments, acesse Products → Meters.
- Clique em Create Meter.
- Configure o medidor:
- Meter Name: um nome descritivo, como
LLM Token Usage. - Event Name: um identificador de evento exclusivo, como
llm.chat_completion. - Aggregation Type: Sum, para somar as contagens de tokens.
- Over Property: a contagem de tokens a ser cobrada:
inputTokens: tokens de entrada (prompt).outputTokens: tokens de saída (conclusão), incluindo tokens de raciocínio quando o modelo os informar.totalTokens: tokens de entrada e saída combinados.
- Measurement Unit: a unidade exibida nas faturas, como
tokens.
- Meter Name: um nome descritivo, como
- Clique em Create Meter.
O Event Name definido aqui deve corresponder exatamente ao
eventName passado para o SDK (diferencia maiúsculas de minúsculas).4
Track Token Usage
Crie um rastreador, encapsule seu cliente de LLM e chame o cliente normalmente:
Agora, cada chamada concluída pelo cliente encapsulado envia um evento de uso com suas contagens de tokens ao Dodo Payments para cobrança.
Configuração
Configuração do rastreador
Crie um rastreador uma vez na inicialização do aplicativo e reutilize-o para cada cliente.createLLMTracker() aceita estas opções e gera um erro se apiKey ou eventName estiver ausente ou vazio:
string
obrigatório
Sua chave de API do Dodo Payments. Obtenha-a na página de chaves de API.
string
O modo de ambiente do rastreador:
test_mode: para desenvolvimento e testes. Esse é o padrão.live_mode: para produção.
live_mode por padrão. Portanto, defina live_mode explicitamente em produção.string
obrigatório
O nome do evento que aciona seu medidor. Ele deve corresponder exatamente ao Event Name do seu medidor do Dodo Payments (diferencia maiúsculas de minúsculas).
Esse nome de evento vincula seu uso acompanhado ao medidor correto para os cálculos de cobrança.
wrap(), o rastreador possui track(response, customerId, metadata), que registra o uso de uma resposta que você já possui, e healthCheck(), que retorna true quando a API do Dodo Payments está acessível.
Configuração do wrapper
Passe estes parâmetros parawrap():
object
obrigatório
Sua instância de cliente de LLM, como um cliente OpenAI, Anthropic, Groq ou Google GenAI, ou um objeto que contenha funções do AI SDK, como
{ generateText }.string
obrigatório
O ID do cliente do Dodo Payments a ser cobrado. Ele começa com
cus_.object
Dados adicionais opcionais a serem anexados a cada evento de rastreamento, para filtragem e análise. Cada valor deve ser uma string, um número ou um booleano. Uma chave chamada
inputTokens, outputTokens, totalTokens ou model substitui o valor rastreado.Exemplo de configuração completa
Este exemplo acompanha uma chamada do AI SDK e anexa metadadosprovider ao evento:
Rastreamento automático: o wrapper retorna a resposta do provedor sem alterações, portanto seu código permanece igual ao usado com o SDK original do provedor. Ele envia o evento de uso antes de retornar a resposta, então cada chamada aguarda a solicitação de ingestão, e uma solicitação de ingestão malsucedida faz a chamada encapsulada gerar um erro mesmo quando a chamada do provedor é bem-sucedida. Respostas em streaming não incluem as contagens finais de tokens no objeto retornado, portanto o wrapper não as rastreia.
Provedores compatíveis
O rastreador lê as contagens de tokens nos formatos de resposta destes provedores e SDKs:AI SDK (Vercel)
AI SDK (Vercel)
Acompanhe o uso com o Vercel AI SDK, que oferece uma interface para vários provedores de LLM.Métricas acompanhadas:
inputTokens→inputTokensoutputTokens+reasoningTokens→outputTokenstotalTokens→totalTokens- Nome do modelo: os resultados do AI SDK não têm um campo
modelde nível superior, então o rastreador registraunknown. Para registrar o modelo, passe-o comomodelno wrappermetadata, como neste exemplo.
Quando você usa um modelo com capacidade de raciocínio pelo AI SDK, como o Gemini 2.5 Flash do Google com o modo de pensamento ativado, o rastreador adiciona os tokens de raciocínio informados a
outputTokens.OpenRouter
OpenRouter
Acompanhe o uso de tokens em mais de 200 modelos por meio da API unificada do OpenRouter.Métricas acompanhadas:
prompt_tokens→inputTokenscompletion_tokens→outputTokenstotal_tokens→totalTokens- Nome do modelo
OpenAI
OpenAI
Acompanhe o uso de tokens dos modelos GPT da OpenAI.Métricas acompanhadas:
prompt_tokens→inputTokenscompletion_tokens→outputTokenstotal_tokens→totalTokens- Nome do modelo
Anthropic Claude
Anthropic Claude
Acompanhe o uso de tokens dos modelos Claude da Anthropic.Métricas acompanhadas:
input_tokens→inputTokensoutput_tokens→outputTokenstotalTokens, calculado comoinput_tokens+output_tokens- Nome do modelo
Groq
Groq
Acompanhe o uso de tokens dos modelos disponibilizados pelo Groq.Métricas acompanhadas:
prompt_tokens→inputTokenscompletion_tokens→outputTokenstotal_tokens→totalTokens- Nome do modelo
Google Gemini
Google Gemini
Acompanhe o uso de tokens dos modelos Gemini do Google por meio do SDK Google GenAI.Métricas acompanhadas:
promptTokenCount→inputTokenscandidatesTokenCount+thoughtsTokenCount→outputTokenstotalTokenCount→totalTokens- Versão do modelo, proveniente de
modelVersion
Modo de pensamento do Gemini: para modelos Gemini que raciocinam antes de responder, como o Gemini 2.5 Pro, o rastreador adiciona
thoughtsTokenCount (tokens de raciocínio) a outputTokens, para que o evento reflita toda a saída produzida pelo modelo.Uso avançado
Vários provedores
Para acompanhar separadamente o uso entre provedores de LLM, crie um rastreador por provedor:Integração de API com Express.js
Esta API do Express.js acompanha cada conclusão de chat do cliente que fez a solicitação. Para simplificar, ela lêuserId do corpo da solicitação. userId deve ser o ID do cliente do Dodo Payments do usuário. Em produção, leia-o da sessão autenticada em vez de confiar no corpo da solicitação.
O que é rastreado
Cada chamada acompanhada envia um evento de uso ao Dodo Payments com esta estrutura:Campos do evento
string
Identificador exclusivo deste evento. O SDK o gera.Formato:
llm_[timestamp]_[random], em que timestamp é o horário em milissegundos e random são seis caracteres aleatórios.string
O ID do cliente passado ao encapsular o cliente. O Dodo Payments cobra esse cliente.
string
O nome do evento que aciona seu medidor. Ele vem da configuração do rastreador.
string
Timestamp ISO 8601, definido quando o rastreador envia o evento após a resposta do provedor.
object
Uso de tokens e dados adicionais de rastreamento:
inputTokens: número de tokens de entrada (prompt) utilizados.outputTokens: número de tokens de saída (conclusão) utilizados, incluindo tokens de raciocínio quando aplicável.totalTokens: tokens totais (entrada + saída).model: o modelo de LLM utilizado, comogpt-4, ouunknownse a resposta não nomear um modelo.provider: o provedor de LLM, se você o incluiu nos metadados do wrapper.- Qualquer metadado personalizado fornecido ao encapsular o cliente.
Tokens de raciocínio: para modelos com recursos de raciocínio,
outputTokens inclui os tokens de conclusão e os tokens de raciocínio.Seu medidor do Dodo Payments usa os campos
metadata, geralmente inputTokens, outputTokens ou totalTokens, para calcular o uso e a cobrança.