Blueprint de LLM

Rastreie facilmente o uso de tokens de LLM para cobrança baseada em uso, com ingestão automática em <CardGroup cols={2}>. Funciona com AI SDK, OpenAI, Anthropic, OpenRouter, Groq e Google Gemini.

Quick Start

Comece em 2 minutos com o rastreamento automático de tokens.

API Reference - Events Ingestion

Documentação completa da API para ingerir eventos de uso.

API Reference - Meters

Saiba como criar e configurar medidores para cobrança.

Usage-Based Billing Guide

Guia completo sobre cobrança baseada em uso com medidores.

Perfeito para aplicativos SaaS, chatbots de IA, ferramentas de geração de conteúdo e qualquer aplicativo baseado em LLM que precise de cobrança baseada em uso.

​

Início rápido

Comece a rastrear automaticamente tokens de LLM em apenas 2 minutos:

1. Install the SDK

   Instale os Blueprints de ingestão do Dodo Payments:

   npm install @dodopayments/ingestion-blueprints
   
2. Get Your API Keys

   Você precisará de duas chaves de API:

   • Chave de API do Dodo Payments: obtenha-a no Dashboard do Dodo Payments
   • Chave de API do provedor de LLM: do AI SDK, OpenAI, Anthropic, Groq etc.

   Armazene suas chaves de API com segurança em variáveis de ambiente. Nunca faça commit delas no controle de versão.

3. Create a Meter in Dodo Payments

   Antes de rastrear o uso, crie um medidor no seu dashboard do Dodo Payments:

   1. Faça login no Dashboard do Dodo Payments
   2. Acesse Products → Meters
   3. Clique em “Create Meter”
   4. Configure seu medidor:
      • Nome do medidor: escolha um nome descritivo (por exemplo, “Uso de tokens de LLM”)
      • Nome do evento: defina um identificador de evento exclusivo (por exemplo, llm.chat_completion)
      • Tipo de agregação: selecione sum para somar as contagens de tokens
      • Sobre a propriedade: escolha o que rastrear:
        • inputTokens - Rastrear tokens de entrada/prompt
        • outputTokens - Rastrear tokens de saída/conclusão (inclui tokens de raciocínio quando aplicável)
        • totalTokens - Rastrear tokens combinados de entrada + saída

   O Nome do evento definido aqui deve corresponder exatamente ao valor enviado ao SDK (diferencia maiúsculas de minúsculas).

   Para obter instruções detalhadas, consulte o Guia de cobrança baseada em uso.

4. Track Token Usage

   Envolva seu cliente de LLM e comece a rastrear automaticamente:

   AI SDK

   import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
   import { generateText } from 'ai';
   import { google } from '@ai-sdk/google';
   
   const llmTracker = createLLMTracker({
     apiKey: process.env.DODO_PAYMENTS_API_KEY,
     environment: 'test_mode',
     eventName: 'aisdk.usage',
   });
   
   const client = llmTracker.wrap({
     client: { generateText },
     customerId: 'customer_123'
   });
   
   const response = await client.generateText({
     model: google('gemini-2.0-flash'),
     prompt: 'Hello!',
     maxOutputTokens: 500
   });
   
   console.log('Usage:', response.usage);
   

   import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
   import OpenAI from 'openai';
   
   const openrouter = new OpenAI({
     baseURL: 'https://openrouter.ai/api/v1',
     apiKey: process.env.OPENROUTER_API_KEY
   });
   
   const llmTracker = createLLMTracker({
     apiKey: process.env.DODO_PAYMENTS_API_KEY,
     environment: 'test_mode',
     eventName: 'openrouter.usage'
   });
   
   const client = llmTracker.wrap({
     client: openrouter,
     customerId: 'customer_123'
   });
   
   const response = await client.chat.completions.create({
     model: 'qwen/qwen3-max',
     messages: [{ role: 'user', content: 'Hello!' }],
     max_tokens: 500
   });
   
   console.log('Response:', response.choices[0].message.content);
   console.log('Usage:', response.usage);
   

   import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
   import OpenAI from 'openai';
   
   // 1. Create your LLM client (normal way)
   const openai = new OpenAI({ 
     apiKey: process.env.OPENAI_API_KEY 
   });
   
   // 2. Create tracker ONCE at startup
   const tracker = createLLMTracker({
     apiKey: process.env.DODO_PAYMENTS_API_KEY,
     environment: 'test_mode', // Use 'live_mode' for production
     eventName: 'llm.chat_completion' // Match your meter's event name
   });
   
   // 3. Wrap & use - automatic tracking!
   const client = tracker.wrap({ 
     client: openai, 
     customerId: 'customer_123' 
   });
   
   // Every API call is now automatically tracked
   const response = await client.chat.completions.create({
     model: 'gpt-4',
     messages: [{ role: 'user', content: 'Hello!' }]
   });
   
   // ✨ Usage automatically sent to Dodo Payments!
   console.log('Tokens used:', response.usage);
   

   import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
   import Anthropic from '@anthropic-ai/sdk';
   
   const anthropic = new Anthropic({ 
     apiKey: process.env.ANTHROPIC_API_KEY 
   });
   
   const tracker = createLLMTracker({
     apiKey: process.env.DODO_PAYMENTS_API_KEY,
     environment: 'test_mode',
     eventName: 'anthropic.usage'
   });
   
   const client = tracker.wrap({ 
     client: anthropic, 
     customerId: 'customer_123' 
   });
   
   const response = await client.messages.create({
     model: 'claude-sonnet-4-0',
     max_tokens: 1024,
     messages: [{ role: 'user', content: 'Hello Claude!' }]
   });
   
   console.log('Tokens used:', response.usage);
   

   import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
   import Groq from 'groq-sdk';
   
   const groq = new Groq({ 
     apiKey: process.env.GROQ_API_KEY 
   });
   
   const tracker = createLLMTracker({
     apiKey: process.env.DODO_PAYMENTS_API_KEY,
     environment: 'test_mode',
     eventName: 'groq.usage'
   });
   
   const client = tracker.wrap({ 
     client: groq, 
     customerId: 'customer_123' 
   });
   
   const response = await client.chat.completions.create({
     model: 'llama-3.1-8b-instant',
     messages: [{ role: 'user', content: 'Hello!' }]
   });
   
   console.log('Tokens:', response.usage);
   

   import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
   import { GoogleGenAI } from '@google/genai';
   
   const googleGenai = new GoogleGenAI({
     apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY
   });
   
   const llmTracker = createLLMTracker({
     apiKey: process.env.DODO_PAYMENTS_API_KEY,
     environment: 'test_mode',
     eventName: 'gemini.usage'
   });
   
   const client = llmTracker.wrap({
     client: googleGenai,
     customerId: 'customer_123'
   });
   
   const response = await client.models.generateContent({
     model: 'gemini-2.5-flash',
     contents: 'Why is the sky blue?'
   });
   
   console.log('Response:', response.text);
   console.log('Usage:', response.usageMetadata);
   

   É só isso! Agora, cada chamada de API rastreia automaticamente o uso de tokens e envia eventos para Dodo Payments para cobrança.

---

​

Configuração

​

Configuração do rastreador

Crie um rastreador uma vez na inicialização do aplicativo com estes parâmetros obrigatórios:

apiKey · string · obrigatório

Sua chave de API do Dodo Payments. Obtenha-a na página de chaves de API.

apiKey: process.env.DODO_PAYMENTS_API_KEY

environment · string · obrigatório

O modo de ambiente do rastreador.

• test_mode - Use em desenvolvimento e testes
• live_mode - Use em produção

environment: 'test_mode' // or 'live_mode'

Sempre use test_mode durante o desenvolvimento para evitar afetar as métricas de produção.

eventName · string · obrigatório

O nome do evento que aciona seu medidor. Deve corresponder exatamente ao que você configurou no medidor do Dodo Payments (diferencia maiúsculas de minúsculas).

eventName: 'llm.chat_completion'

Esse nome de evento vincula o uso rastreado ao medidor correto para os cálculos de cobrança.

​

Configuração do wrapper

Ao envolver seu cliente de LLM, forneça estes parâmetros:

client · object · obrigatório

Sua instância de cliente de LLM (OpenAI, Anthropic, Groq etc.).

client: openai

customerId · string · obrigatório

O identificador exclusivo do cliente para cobrança. Deve corresponder ao ID do cliente em Dodo Payments.

customerId: 'customer_123'

Use o ID de usuário ou de cliente do seu aplicativo para garantir uma cobrança precisa por cliente.

metadata · object

Dados adicionais opcionais para anexar ao evento de rastreamento. Úteis para filtragem e análise.

metadata: {
  feature: 'chat',
  userTier: 'premium',
  sessionId: 'session_123',
  modelVersion: 'gpt-4'
}

​

Exemplo completo de configuração

Full Configuration

import { createLLMTracker } from "@dodopayments/ingestion-blueprints";
import { generateText } from "ai";
import { google } from "@ai-sdk/google";
import "dotenv/config";

async function aiSdkExample() {
  console.log("🤖 AI SDK Simple Usage Example\n");

  try {
    // 1. Create tracker
    const llmTracker = createLLMTracker({
      apiKey: process.env.DODO_PAYMENTS_API_KEY!,
      environment: "test_mode",
      eventName: "your_meter_event_name",
    });

    // 2. Wrap the ai-sdk methods
    const client = llmTracker.wrap({
      client: { generateText },
      customerId: "customer_123",
      metadata: {
        provider: "ai-sdk",
      },
    });

    // 3. Use the wrapped function
    const response = await client.generateText({
      model: google("gemini-2.5-flash"),
      prompt: "Hello, I am a cool guy! Tell me a fun fact.",
      maxOutputTokens: 500,
    });

    console.log(response);
    console.log(response.usage);
    console.log("✅ Automatically tracked for customer\n");
  } catch (error) {
    console.error(error);
  }
}

aiSdkExample().catch(console.error);

Rastreamento automático: o SDK rastreia automaticamente o uso de tokens em segundo plano sem modificar a resposta. Seu código permanece limpo e idêntico ao uso dos SDKs originais dos provedores.

---

​

Provedores compatíveis

O Blueprint de LLM funciona perfeitamente com todos os principais provedores e agregadores de LLM:

AI SDK (Vercel)

Rastreie o uso com o Vercel AI SDK para obter suporte universal a LLMs.

AI SDK Integration

import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
import { generateText } from 'ai';
import { google } from '@ai-sdk/google';

const llmTracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode',
  eventName: 'aisdk.usage',
});

const client = llmTracker.wrap({
  client: { generateText },
  customerId: 'customer_123',
  metadata: {
    model: 'gemini-2.0-flash',
    feature: 'chat'
  }
});

const response = await client.generateText({
  model: google('gemini-2.0-flash'),
  prompt: 'Explain neural networks',
  maxOutputTokens: 500
});

console.log('Usage:', response.usage);

Métricas rastreadas:

• inputTokens → inputTokens
• outputTokens + reasoningTokens → outputTokens
• totalTokens → totalTokens
• Nome do modelo

Ao usar modelos com capacidade de raciocínio por meio do AI SDK (como o Gemini 2.5 Flash do Google com modo de raciocínio), os tokens de raciocínio são incluídos automaticamente na contagem outputTokens para uma cobrança precisa.

OpenRouter

Rastreie o uso de tokens em mais de 200 modelos por meio da API unificada do OpenRouter.

OpenRouter Integration

import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
import OpenAI from 'openai';

// OpenRouter uses OpenAI-compatible API
const openrouter = new OpenAI({
  baseURL: 'https://openrouter.ai/api/v1',
  apiKey: process.env.OPENROUTER_API_KEY
});

const tracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode',
  eventName: 'openrouter.usage'
});

const client = tracker.wrap({ 
  client: openrouter, 
  customerId: 'user_123',
  metadata: { provider: 'openrouter' }
});

const response = await client.chat.completions.create({
  model: 'qwen/qwen3-max',
  messages: [{ role: 'user', content: 'What is machine learning?' }],
  max_tokens: 500
});

console.log('Response:', response.choices[0].message.content);
console.log('Usage:', response.usage);

Métricas rastreadas:

• prompt_tokens → inputTokens
• completion_tokens → outputTokens
• total_tokens → totalTokens
• Nome do modelo

O OpenRouter fornece acesso a modelos da OpenAI, Anthropic, Google, Meta e muitos outros provedores por meio de uma única API.

OpenAI

Rastreie automaticamente o uso de tokens dos modelos GPT da OpenAI.

OpenAI Integration

import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
import OpenAI from 'openai';

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const tracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode',
  eventName: 'openai.usage'
});

const client = tracker.wrap({ 
  client: openai, 
  customerId: 'user_123' 
});

// All OpenAI methods work automatically
const response = await client.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Explain quantum computing' }]
});

console.log('Total tokens:', response.usage.total_tokens);

Métricas rastreadas:

• prompt_tokens → inputTokens
• completion_tokens → outputTokens
• total_tokens → totalTokens
• Nome do modelo

Anthropic Claude

Rastreie o uso de tokens dos modelos Claude da Anthropic.

Anthropic Integration

import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

const tracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode',
  eventName: 'anthropic.usage'
});

const client = tracker.wrap({ 
  client: anthropic, 
  customerId: 'user_123' 
});

const response = await client.messages.create({
  model: 'claude-sonnet-4-0',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Explain machine learning' }]
});

console.log('Input tokens:', response.usage.input_tokens);
console.log('Output tokens:', response.usage.output_tokens);

Métricas rastreadas:

• input_tokens → inputTokens
• output_tokens → outputTokens
• totalTokens calculado
• Nome do modelo

Groq

Rastreie a inferência de LLM ultrarrápida com o Groq.

Groq Integration

import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
import Groq from 'groq-sdk';

const groq = new Groq({ apiKey: process.env.GROQ_API_KEY });

const tracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode',
  eventName: 'groq.usage'
});

const client = tracker.wrap({ 
  client: groq, 
  customerId: 'user_123' 
});

const response = await client.chat.completions.create({
  model: 'llama-3.1-8b-instant',
  messages: [{ role: 'user', content: 'What is AI?' }]
});

console.log('Tokens:', response.usage);

Métricas rastreadas:

• prompt_tokens → inputTokens
• completion_tokens → outputTokens
• total_tokens → totalTokens
• Nome do modelo

Google Gemini

Rastreie o uso de tokens dos modelos Gemini do Google por meio do Google GenAI SDK.

Google Gemini Integration

import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
import { GoogleGenAI } from '@google/genai';

const googleGenai = new GoogleGenAI({ 
  apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY 
});

const tracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode',
  eventName: 'gemini.usage'
});

const client = tracker.wrap({ 
  client: googleGenai, 
  customerId: 'user_123' 
});

const response = await client.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: 'Explain quantum computing'
});

console.log('Response:', response.text);
console.log('Usage:', response.usageMetadata);

Métricas rastreadas:

• promptTokenCount → inputTokens
• candidatesTokenCount + thoughtsTokenCount → outputTokens
• totalTokenCount → totalTokens
• Versão do modelo

Modo de raciocínio do Gemini: ao usar modelos Gemini com recursos de raciocínio (como o Gemini 2.5 Pro), o SDK inclui automaticamente thoughtsTokenCount (tokens de raciocínio) em outputTokens para refletir com precisão o custo computacional total.

---

​

Uso avançado

​

Vários provedores

Rastreie o uso em diferentes provedores de LLM com rastreadores separados:

Multiple Provider Setup

import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
import OpenAI from 'openai';
import Groq from 'groq-sdk';
import Anthropic from '@anthropic-ai/sdk';
import { GoogleGenAI } from '@google/genai';

// Create separate trackers for different providers
const openaiTracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'live_mode',
  eventName: 'openai.usage'
});

const groqTracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'live_mode',
  eventName: 'groq.usage'
});

const anthropicTracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'live_mode',
  eventName: 'anthropic.usage'
});

const geminiTracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'live_mode',
  eventName: 'gemini.usage'
});

const openrouterTracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'live_mode',
  eventName: 'openrouter.usage'
});

// Initialize clients
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const groq = new Groq({ apiKey: process.env.GROQ_API_KEY });
const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
const googleGenai = new GoogleGenAI({ apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY });
const openrouter = new OpenAI({ 
  baseURL: 'https://openrouter.ai/api/v1',
  apiKey: process.env.OPENROUTER_API_KEY 
});

// Wrap clients
const trackedOpenAI = openaiTracker.wrap({ client: openai, customerId: 'user_123' });
const trackedGroq = groqTracker.wrap({ client: groq, customerId: 'user_123' });
const trackedAnthropic = anthropicTracker.wrap({ client: anthropic, customerId: 'user_123' });
const trackedGemini = geminiTracker.wrap({ client: googleGenai, customerId: 'user_123' });
const trackedOpenRouter = openrouterTracker.wrap({ client: openrouter, customerId: 'user_123' });

// Use whichever provider you need
const response = await trackedOpenAI.chat.completions.create({...});
// or
const geminiResponse = await trackedGemini.models.generateContent({...});
// or
const openrouterResponse = await trackedOpenRouter.chat.completions.create({...});

Use nomes de eventos diferentes para provedores diferentes para rastrear o uso separadamente nos seus medidores.

​

Integração de API com Express.js

Exemplo completo de integração do rastreamento de LLM a uma API do Express.js:

Express.js Server

import express from 'express';
import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
import OpenAI from 'openai';

const app = express();
app.use(express.json());

// Initialize OpenAI client
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

// Create tracker once at startup
const tracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: process.env.NODE_ENV === 'production' ? 'live_mode' : 'test_mode',
  eventName: 'api.chat_completion'
});

// Chat endpoint with automatic tracking
app.post('/api/chat', async (req, res) => {
  try {
    const { message, userId } = req.body;
    
    // Validate input
    if (!message || !userId) {
      return res.status(400).json({ error: 'Missing message or userId' });
    }
    
    // Wrap client for this specific user
    const trackedClient = tracker.wrap({
      client: openai,
      customerId: userId,
      metadata: { 
        endpoint: '/api/chat',
        timestamp: new Date().toISOString()
      }
    });
    
    // Make LLM request - automatically tracked
    const response = await trackedClient.chat.completions.create({
      model: 'gpt-4',
      messages: [{ role: 'user', content: message }],
      temperature: 0.7
    });
    
    const completion = response.choices[0].message.content;
    
    res.json({ 
      message: completion,
      usage: response.usage
    });
  } catch (error) {
    console.error('Chat error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

---

​

O que é rastreado

Cada chamada à API de LLM envia automaticamente um evento de uso para Dodo Payments com a seguinte estrutura:

Event Structure

{
  "event_id": "llm_1673123456_abc123",
  "customer_id": "customer_123",
  "event_name": "llm.chat_completion",
  "timestamp": "2024-01-08T10:30:00Z",
  "metadata": {
    "inputTokens": 10,
    "outputTokens": 25,
    "totalTokens": 35,
    "model": "gpt-4",
  }
}

​

Campos do evento

event_id · string

Identificador exclusivo deste evento específico. Gerado automaticamente pelo SDK.

Formato: llm_[timestamp]_[random]

customer_id · string

O ID do cliente fornecido ao envolver o cliente. Usado para cobrança.

event_name · string

O nome do evento que aciona seu medidor. Corresponde à configuração do rastreador.

timestamp · string

Timestamp no formato ISO 8601 em que o evento ocorreu.

metadata · object

Uso de tokens e dados adicionais de rastreamento:

• inputTokens - Número de tokens de entrada/prompt usados
• outputTokens - Número de tokens de saída/conclusão usados (inclui tokens de raciocínio quando aplicável)
• totalTokens - Total de tokens (entrada + saída)
• model - O modelo de LLM usado (por exemplo, “gpt-4”)
• provider - O provedor de LLM (se incluído nos metadados do wrapper)
• Quaisquer metadados personalizados fornecidos ao envolver o cliente

Tokens de raciocínio: para modelos com recursos de raciocínio, outputTokens inclui automaticamente os tokens de conclusão e de raciocínio.

Seu medidor do Dodo Payments usa os campos metadata (especialmente inputTokens, outputTokens ou totalTokens) para calcular o uso e a cobrança.

---