Skip to main content
O LLM Blueprint encapsula seu cliente de LLM para que cada chamada concluída envie um evento de uso com as contagens de tokens de entrada, saída e total para o Dodo Payments. Um medidor soma essas contagens, permitindo cobrar cada cliente pelos tokens utilizados. O blueprint está disponível no pacote npm @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 com test_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.
Armazene suas chaves de API em variáveis de ambiente. Não faça commit delas no controle de versão.
3

Create a Meter in Dodo Payments

Crie um medidor antes de acompanhar o uso:
  1. No dashboard do Dodo Payments, acesse Products → Meters.
  2. Clique em Create Meter.
  3. 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.
  4. Clique em Create Meter.
O Event Name definido aqui deve corresponder exatamente ao eventName passado para o SDK (diferencia maiúsculas de minúsculas).
Para obter instruções detalhadas, consulte o Usage-Based Billing Guide.
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.
Os SDKs do Dodo Payments usam live_mode por padrão. Portanto, defina live_mode explicitamente em produção.
Use test_mode durante o desenvolvimento para que o tráfego de teste não crie eventos de uso reais.
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.
Além de 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 para wrap():
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_.
Armazene o ID do cliente do Dodo Payments de cada usuário junto ao registro do usuário e passe-o aqui. O ID de usuário próprio do seu aplicativo não corresponde a um cliente do Dodo Payments.
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 metadados provider 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:
Acompanhe o uso com o Vercel AI SDK, que oferece uma interface para vários provedores de LLM.
Métricas acompanhadas:
  • inputTokens → inputTokens
  • outputTokens + reasoningTokens → outputTokens
  • totalTokens → totalTokens
  • Nome do modelo: os resultados do AI SDK não têm um campo model de nível superior, então o rastreador registra unknown. Para registrar o modelo, passe-o como model no wrapper metadata, 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.
Acompanhe o uso de tokens em mais de 200 modelos por meio da API unificada do OpenRouter.
Métricas acompanhadas:
  • prompt_tokens → inputTokens
  • completion_tokens → outputTokens
  • total_tokens → totalTokens
  • Nome do modelo
O OpenRouter oferece acesso a modelos da OpenAI, Anthropic, Google, Meta e outros provedores por meio de uma única API.
Acompanhe o uso de tokens dos modelos GPT da OpenAI.
Métricas acompanhadas:
  • prompt_tokens → inputTokens
  • completion_tokens → outputTokens
  • total_tokens → totalTokens
  • Nome do modelo
Acompanhe o uso de tokens dos modelos Claude da Anthropic.
Métricas acompanhadas:
  • input_tokens → inputTokens
  • output_tokens → outputTokens
  • totalTokens, calculado como input_tokens + output_tokens
  • Nome do modelo
Acompanhe o uso de tokens dos modelos disponibilizados pelo Groq.
Métricas acompanhadas:
  • prompt_tokens → inputTokens
  • completion_tokens → outputTokens
  • total_tokens → totalTokens
  • Nome do modelo
Acompanhe o uso de tokens dos modelos Gemini do Google por meio do SDK Google GenAI.
Métricas acompanhadas:
  • promptTokenCount → inputTokens
  • candidatesTokenCount + thoughtsTokenCount → outputTokens
  • totalTokenCount → 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:
Use um nome de evento diferente para cada provedor, com um medidor para cada um, para acompanhar o uso separadamente.

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, como gpt-4, ou unknown se 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.
Última modificação em 26 de setembro de 2026