Como Rastrear Gastos da API OpenAI por Funcionalidade: Guia de Atribuição de Custos

Seu extrato do OpenAI diz que você gastou $4.237 no mês passado. Ele não informa que $3.100 disso vieram de um endpoint de sumarização descontrolado, $700 de um cliente que paga $50 por mês, e $437 de uma funcionalidade que ninguém usa. O painel esconde a imagem que você precisa para tomar qualquer decisão de precificação, capacidade ou roadmap. Este guia mostra como fazer a atribuição de custos da API OpenAI da maneira certa: marque cada requisição com metadados, agregue o gasto por funcionalidade, rota e cliente, defina limites de orçamento por chave, e projete prompts para que o custo deixe de ser um item misterioso. Se você implementa funcionalidades de LLM, este é o trabalho que transforma a IA de uma despesa descontrolada em um custo de produto gerenciado.

botão

TL;DR

Marque cada chamada da API OpenAI com metadados estruturados (funcionalidade, rota, customer_id, ambiente), emita uma linha de log estruturada por requisição que capture a contagem de tokens e o custo calculado, e então agregue por tag em seu data warehouse. Defina limites de orçamento por chave no painel do OpenAI, alerte sobre anomalias de gastos por hora e valide o wrapper de ponta a ponta com testes de cenário do Apidog antes de confiar nos números.

Introdução

Você lança uma nova funcionalidade de IA na terça-feira. Na sexta-feira de manhã, seu CFO está na sua DM perguntando por que a linha do OpenAI subiu 40 por cento. Você abre o painel. Ele mostra o gasto total aumentando. Ele não mostra qual funcionalidade, qual cliente ou qual rota é responsável. Você começa a adivinhar.

Esta é a lacuna que toda equipe que executa cargas de trabalho de LLM em produção encontra. A interface de cobrança do OpenAI é construída para contas a pagar, não para atribuição de engenharia. Você vê os totais diários, a quebra por modelo, e só. Você não vê o formato da requisição, o cliente que a disparou ou a funcionalidade que chamou o modelo.

A solução é simples em conceito e implacável na execução. Você envolve cada chamada de API com uma camada de metadados. Você registra cada requisição em um armazenamento estruturado. Você agrega por tag. Você define limites. Você alerta sobre deltas. Ao final deste post, você terá um modelo de dados concreto, dois exemplos de código funcionais, um fluxo de trabalho de verificação com Apidog e uma comparação de ferramentas para que você possa decidir se constrói, compra ou usa a API de uso do OpenAI diretamente.

Para contexto de precificação que impulsiona seus cálculos de custo, consulte a análise de preços do GPT-5.5. Para um problema relacionado de atribuição de cobrança no lado das ferramentas de desenvolvedor, consulte cobrança de uso do GitHub Copilot para equipes de API. Para os conceitos básicos da API OpenAI, consulte a referência oficial da API OpenAI.

Por que o painel de cobrança do OpenAI não é suficiente

Abra a página de cobrança do OpenAI agora mesmo. Você verá um gráfico de gastos diários, uma análise por modelo e um limite de uso. Essa é a interface inteira. Funciona bem se você tiver um aplicativo, um cliente e uma funcionalidade. No momento em que você tem qualquer um destes: várias funcionalidades no mesmo produto, vários clientes, vários ambientes ou vários desenvolvedores, o painel deixa de ser útil.

Aqui está o que está faltando.

Gasto total sem contexto. O painel informa que você gastou $312 ontem no GPT-5.5. Ele não diz se isso veio de um cliente acessando seu endpoint de chat de suporte 50.000 vezes ou de um job em segundo plano que resumiu toda a sua base de conhecimento porque alguém deixou uma flag ativada. Ambos parecem idênticos no gráfico.

Nenhuma análise por funcionalidade. O OpenAI marca as requisições por chave de API e modelo. Ele não as marca por sua funcionalidade, rota, ID do cliente ou ambiente. Se você quiser qualquer uma dessas informações, você as constrói. Não há uma dimensão nativa para análise de produto no painel.

Defasagem nos relatórios. Os dados de uso aparecem com um atraso medido em dezenas de minutos a algumas horas. No momento em que um loop descontrolado aparece em seu painel, ele já consumiu um cartão de crédito. Você precisa de rastreamento em tempo real, não de um gráfico histórico.

Sem primitivas de alerta. O OpenAI oferece um limite de orçamento por organização e um e-mail de notificação suave. Não há alerta por chave, limite por funcionalidade, nem detecção de anomalias. Se você quiser "me notifique se o endpoint de chat exceder $50 em uma hora", você mesmo constrói isso.

Sem atribuição de cliente. Se você vende SaaS B2B com uma funcionalidade de IA, precisa saber qual cliente impulsionou qual gasto para poder precificar, limitar ou fazer upsell. O painel não pode responder "quanto o cliente X está me custando este mês". Sua equipe financeira precisa desse número para calcular a margem bruta por cliente. Sem ele, sua economia unitária é uma suposição.

Contas de serviço e chaves em nível de projeto ajudam, mas apenas parcialmente. As chaves de projeto do OpenAI permitem dividir o uso por projeto. Isso lhe dá um nível de atribuição. Não lhe dá por funcionalidade, por cliente ou por rota. Você ainda precisa de metadados em nível de aplicativo para responder às perguntas que importam. A API de uso do OpenAI retorna dados agregados por projeto, não por requisição.

O padrão se repete em todas as equipes que implementam funcionalidades de LLM em escala. O thread do Dev.to "OpenAI Tells You What You Spent. Not Where. So I Built a Dashboard" se tornou viral porque nomeou o problema em voz alta: você não pode gerenciar o que não pode medir. O painel nativo responde a uma pergunta financeira. Você precisa responder a uma pergunta de produto.

O modelo de dados de atribuição de custos

A atribuição de custos começa com uma decisão: cada requisição do OpenAI gera um evento com tags que é gravado em seu data warehouse. Esse evento é sua unidade de análise. Acerte o esquema e o resto do trabalho – painéis, alertas, limites – se torna uma consulta SQL.

Aqui está o esquema mínimo que você precisa.

Calcule o custo no momento da gravação, não no momento da consulta. Os preços mudam; você quer um número fixo que reflita a taxa que você pagou no dia em que a requisição ocorreu. A lógica de cálculo para GPT-5.5 é a seguinte:

PRICING = {  # USD por 1M tokens, a partir de maio de 2026
    "gpt-5.5":      {"input": 5.00,  "cached": 2.50,  "output": 30.00},
    "gpt-5.5-pro":  {"input": 30.00, "cached": 15.00, "output": 180.00},
    "gpt-5.4":      {"input": 2.50,  "cached": 1.25,  "output": 15.00},
    "gpt-5.4-mini": {"input": 0.25,  "cached": 0.125, "output": 2.00},
}

def compute_cost_usd(model, prompt_tokens, cached_tokens, completion_tokens, reasoning_tokens):
    rates = PRICING[model]
    uncached = max(0, prompt_tokens - cached_tokens)
    input_cost  = (uncached      * rates["input"])  / 1_000_000
    cache_cost  = (cached_tokens * rates["cached"]) / 1_000_000
    output_cost = ((completion_tokens + reasoning_tokens) * rates["output"]) / 1_000_000
    return round(input_cost + cache_cost + output_cost, 6)

Os tokens de raciocínio são contados como saída. A API do OpenAI os retorna em usage.completion_tokens_details.reasoning_tokens, mas eles são cobrados na taxa de saída. Se você ignorar isso, subestimará o custo em cada chamada do modo Thinking. Para a matemática de precificação completa, consulte a análise de preços do GPT-5.5.

Agora envolva o cliente OpenAI. Cada chamada passa por uma função. Essa função recebe metadados, faz a requisição e grava o evento.

import time, uuid, json, logging
from openai import OpenAI

client = OpenAI()
logger = logging.getLogger("llm.cost")

def call_with_attribution(
    *, feature, route, customer_id, environment,
    model, messages, **openai_kwargs
):
    request_id = str(uuid.uuid4())
    started = time.time()
    error_code = None
    response = None

    try:
        response = client.chat.completions.create(
            model=model, messages=messages, **openai_kwargs
        )
    except Exception as e:
        error_code = getattr(e, "code", "unknown_error")
        raise
    finally:
        latency_ms = int((time.time() - started) * 1000)
        u = response.usage if response else None
        prompt_tokens     = getattr(u, "prompt_tokens", 0)
        completion_tokens = getattr(u, "completion_tokens", 0)
        cached_tokens     = getattr(getattr(u, "prompt_tokens_details", None), "cached_tokens", 0) or 0
        reasoning_tokens  = getattr(getattr(u, "completion_tokens_details", None), "reasoning_tokens", 0) or 0
        cost_usd = compute_cost_usd(model, prompt_tokens, cached_tokens, completion_tokens, reasoning_tokens)

        logger.info(json.dumps({
            "event": "openai.request",
            "request_id": request_id,
            "feature": feature,
            "route": route,
            "customer_id": customer_id,
            "environment": environment,
            "model": model,
            "prompt_tokens": prompt_tokens,
            "completion_tokens": completion_tokens,
            "reasoning_tokens": reasoning_tokens,
            "cached_tokens": cached_tokens,
            "latency_ms": latency_ms,
            "cost_usd": cost_usd,
            "error_code": error_code,
        }))

    return response

Esse wrapper único é sua superfície de atribuição de custos. Cada funcionalidade em seu produto o chama. A linha de log estruturada é sua entrada para o data warehouse. A partir daqui, envie os logs para BigQuery, ClickHouse, Snowflake ou Postgres via seu pipeline de log existente (Vector, Fluent Bit, Logstash, coletor OTLP). Sem segundo pipeline. Sem serviço extra.

Para equipes Node.js, o formato é idêntico. Envolva o SDK do OpenAI em uma função que receba metadados, capture response.usage, calcule o custo e grave uma linha JSON. Se sua plataforma já executa um barramento de eventos (Kafka, NATS, Pub/Sub), publique o evento lá em vez de no stdout e deixe que os consumidores downstream o distribuam para seu data warehouse e seu sistema de alerta.

Conecte o rastreamento de custos e teste-o com Apidog

Você tem o esquema e o wrapper. Agora transforme-o em algo operacional. Seis passos.

1. Substitua as chamadas diretas do OpenAI pelo wrapper. Faça uma busca em sua base de código por OpenAI( e client.chat.completions.create. Cada ocorrência se torna uma chamada para call_with_attribution(...). Torne feature e route argumentos obrigatórios. Passe-os no local da chamada, não de um global. Se você esquecer de passá-los, a função deve gerar um erro, não assumir o padrão "unknown."

2. Emita logs estruturados. Registre no stdout como JSON, uma linha por evento. Defina o nível do logger para INFO especificamente para esses eventos. Não os misture com ruído de depuração. Se você já usa um logger estruturado (structlog, pino, winston), conecte-o a ele.

3. Agregue por funcionalidade em seu data warehouse. Uma vez que os eventos chegam ao BigQuery ou ClickHouse, as consultas se escrevem sozinhas:

SELECT
  feature,
  DATE_TRUNC(timestamp, DAY) AS day,
  COUNT(*) AS requests,
  SUM(cost_usd) AS spend_usd,
  SUM(prompt_tokens + completion_tokens) AS tokens,
  AVG(latency_ms) AS avg_latency_ms,
  SUM(cached_tokens) / NULLIF(SUM(prompt_tokens), 0) AS cache_hit_rate
FROM openai_events
WHERE environment = 'prod'
  AND timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
GROUP BY feature, day
ORDER BY day DESC, spend_usd DESC;

4. Gráfico de gastos por rota. Conecte Grafana, Metabase, Looker ou Superset à tabela. Construa três visualizações: gastos por funcionalidade ao longo do tempo, gastos por cliente ao longo do tempo e uma tabela das 20 principais rotas classificadas pelos gastos de ontem. Este é o seu painel de operações diárias.

5. Teste o wrapper com Apidog antes de implementá-lo. Este é o passo que a maioria das equipes pula e se arrepende. Seu wrapper grava logs estruturados. Se o esquema estiver errado, seu data warehouse estará silenciosamente errado, e os painéis mentirão. Use Apidog para executar testes de ponta a ponta em seu serviço:

• Crie um cenário no Apidog que envie uma requisição para seu endpoint de IA com um customer_id e feature conhecidos.
• Capture a resposta e a emissão de log do canal lateral (stdout, OTLP, seu endpoint de log).
• Use as asserções de resposta do Apidog para verificar se o payload do log contém o feature, route, customer_id esperados, e se cost_usd > 0 e prompt_tokens > 0.
• Execute o mesmo cenário em ambientes de staging e produção usando variáveis de ambiente do Apidog.
• Reproduza requisições marcadas e certifique-se de que as chamadas repetidas não contam o custo duas vezes (seu wrapper deve reutilizar o request_id na repetição).

Para abordagens mais amplas de testes de API que se encaixam nesta etapa de verificação, consulte ferramentas de teste de API para engenheiros de QA. Para a abordagem "contract-first" que se alinha com a cobertura de atribuição de custos, consulte desenvolvimento de API "contract-first".

6. Defina limites de orçamento e alertas por chave. O OpenAI permite criar uma chave de projeto por ambiente ou por funcionalidade. Use-a. Crie uma chave prod-support-chat, uma chave prod-summarization, uma chave staging-all. Defina limites rígidos no painel do OpenAI para que um loop descontrolado em uma funcionalidade não esgote todo o orçamento da organização. Adicione seus próprios alertas: uma consulta SQL que é executada a cada 10 minutos e o notifica se qualquer funcionalidade exceder 3x a média horária de gastos dos últimos 7 dias. PagerDuty, Opsgenie ou um webhook do Slack funcionam; o gatilho vem do seu data warehouse, não do OpenAI.

A combinação de limites de chave nativos mais alertas impulsionados pelo data warehouse oferece duas camadas de defesa. Os limites nativos são uma proteção contra um consumo catastrófico. Os alertas do data warehouse detectam o desvio lento antes que o limite seja atingido.

Técnicas avançadas e dicas profissionais

Uma vez que o pipeline básico está funcionando, as otimizações seguem.

Cache de prompt. O GPT-5.5 cobra 50% da taxa de entrada para tokens em cache. Estruture seu prompt de sistema como um prefixo estável e coloque variáveis por requisição no final. Taxas de acerto de cache acima de 70% em cargas de trabalho de chat são normais depois de fazer isso. Rastreie a cache_hit_rate por funcionalidade em seu painel para que você possa ver quando uma mudança de prompt diminui sua taxa de acerto. A documentação oficial de cache de prompt do OpenAI cobre as regras de elegibilidade.

API Batch para trabalho offline. Qualquer coisa que não precise de uma resposta síncrona pode ir através da API Batch para um desconto de 50%. Sumarização noturna, execuções de avaliação, preenchimento de embeddings, reprocessamento de documentos. O wrapper de custo ainda se aplica; chame o endpoint Batch e marque os eventos com batch_job_id para que você possa atribuí-los de volta à carga de trabalho de origem.

Ajuste do esforço de raciocínio. O GPT-5.5 Thinking é o mesmo modelo com maior reasoning.effort. Cada nível de esforço multiplica os tokens de saída. Audite suas funcionalidades: você está executando medium onde low passaria nos critérios de qualidade? Execute um teste A/B, rastreie qualidade e custo, implemente a opção mais barata se a qualidade se mantiver. Para matemática mais aprofundada, consulte como usar a API GPT-5.5.

Disciplina na janela de contexto. Prompts longos são caros. RAG com um orçamento de recuperação apertado é melhor do que enfiar toda a base de conhecimento na janela de contexto. Monitore a média de prompt_tokens por funcionalidade; se ela aumentar semana a semana sem uma mudança de funcionalidade, seu prompt está inchando.

Fique atento ao limite de 272K tokens do GPT-5.5. O OpenAI aplica um multiplicador de entrada de 2x e um multiplicador de saída de 1.5x em requisições acima de 272K tokens. Adicione um guarda em seu wrapper que registra um aviso quando prompt_tokens > 250000 para que você possa detectar prompts que estão prestes a atingir o limite. Para detalhes de precificação, consulte o post sobre precificação do GPT-5.5.

Limites de gastos por cliente. Se você vende SaaS B2B e seu contrato inclui uma funcionalidade alimentada por LLM, você precisa de um limite por cliente. Calcule o gasto acumulado por customer_id do seu data warehouse e faça com que seu aplicativo o verifique antes de cada chamada. Se o limite for atingido, retorne um 429 com a mensagem "cota mensal de IA excedida" e uma chamada para ação de cobrança. Isso é o que transforma as funcionalidades de IA de um risco de margem em um produto de margem.

Erros comuns a evitar.

• Contar tokens de raciocínio como entrada. Eles são saída. Fature-os à taxa de saída.
• Confiar no painel do OpenAI para decisões em tempo real. Ele tem atrasos. Use seu próprio data warehouse.
• Tagging no nível do SDK em vez do local da chamada. As tags pertencem à funcionalidade, não ao cliente.
• Esquecer de marcar jobs em segundo plano. Jobs cron, workers de fila e webhooks fazem as mesmas chamadas OpenAI; marque-os com uma route sintética como cron:nightly-summarize ou queue:image-caption.
• Amostragem. Não amostre. Registre cada requisição. O volume de dados é trivial; a precisão da atribuição não é.
• Deixar customer_id como nulo. Se você não conhece o cliente, registre internal ou system, nunca nulo. Nulo se torna um buraco negro de atribuição.

Alternativas e ferramentas

Você não precisa construir isso sozinho. Aqui está uma comparação honesta.

Trade-offs a serem considerados. Um proxy (Helicone) adiciona um salto em seu caminho crítico; o custo de latência é pequeno, mas real, e você se torna dependente da disponibilidade deles. Uma pilha de observabilidade auto-hospedada (Langfuse) oferece controle total, mas você a opera. O caminho do data warehouse personalizado é onde a maioria das grandes equipes acaba; ele se integra com o restante da sua pilha de dados, mas você escreve as consultas e os alertas por conta própria. A API de uso nativa é boa se suas necessidades forem simples, inútil quando não são.

Para uma leitura mais aprofundada sobre o que uma boa observabilidade de custos de LLM significa na prática, o guia da equipe Helicone sobre rastreamento de custos de LLM explora a abordagem baseada em proxy. A documentação da Langfuse sobre rastreamento de custos aborda o caminho de código aberto.

Se você opera isso em escala de plataforma, os padrões se generalizam. Veja Plataformas de API para arquitetura de microsserviços para entender como os wrappers de atribuição de custos se encaixam em uma estratégia de service mesh.

Casos de uso no mundo real

SaaS B2B com gastos de LLM por cliente. Uma empresa vende um produto de inteligência de vendas. Cada cliente dispara chamadas GPT-5.5 ao solicitar um resumo. Sem atribuição, a empresa sabe que gasta $80.000 por mês com OpenAI. Com a atribuição por cliente, ela descobre que 12% dos clientes geram 71% dos gastos. Ela introduz preços por camadas, cotas suaves na camada mais baixa e uma cobrança por uso excedente por assento. A margem bruta da funcionalidade de IA passa de 41% para 73% em um trimestre.

Rastreamento de ferramentas internas para desenvolvedores. Uma organização de engenharia oferece a cada desenvolvedor acesso a um assistente de chat GPT-5.5 privado. Com tags por desenvolvedor (customer_id se torna dev_email), a engenharia de plataforma vê que três desenvolvedores são responsáveis por 50% dos gastos internos. Dois deles estão executando loops de agentes automatizados que esqueceram de desativar. Desligá-los economiza $1.800 por mês. O terceiro está fazendo um trabalho legítimo; os dados justificam uma cota maior para eles em toda a organização.

Previsão de gastos com recursos de IA. Uma equipe de produto quer lançar um novo recurso de sumarização. O PM não sabe como prever o custo. Com dados históricos por recurso, a equipe constrói um modelo: média de tokens de prompt por chamada, média de tokens de saída, chamadas esperadas por usuário ativo, usuários ativos esperados. A previsão retorna: $0,04 por usuário ativo por dia, ou $1,20 por mês. A equipe de precificação precifica o recurso em $5 por usuário por mês. A equipe financeira aprova porque a economia unitária é visível.

Conclusão

Você não pode gerenciar o que não pode medir. O painel de cobrança do OpenAI responde a uma pergunta financeira. A atribuição por funcionalidade, por cliente, por rota responde à pergunta do produto. Construa o wrapper, registre o evento, consulte o data warehouse, e sua linha de IA deixa de ser um mistério.

Cinco lições:

• Marque cada requisição com funcionalidade, rota, customer_id e ambiente. Torne as tags obrigatórias no local da chamada.
• Calcule o custo no momento da gravação para que os dados históricos reflitam a taxa que você pagou naquele dia.
• Use uma chave de projeto por ambiente e defina limites rígidos no painel do OpenAI como uma proteção.
• Adicione alertas controlados pelo data warehouse sobre os limites nativos para detectar desvios lentos antes que o limite seja atingido.
• Teste o wrapper com Apidog antes de implementá-lo; tags incorretas significam erros silenciosos de atribuição.
• Audite o esforço de raciocínio e o tamanho do prompt trimestralmente; a otimização mais barata é aquela que mantém a qualidade estável.
• Rastreie a taxa de acerto do cache por funcionalidade para que uma alteração no prompt não duplique silenciosamente seu custo de entrada.

Baixe o Apidog e use-o para verificar seu wrapper de atribuição de custos de ponta a ponta. Dirija seus endpoints de IA com requisições marcadas, verifique o formato do payload de log e reproduza cenários em diferentes ambientes para que os dados em que seu data warehouse confia sejam os dados que seus engenheiros escreveram.

Para leitura relacionada sobre gerenciamento de custos, consulte a análise de preços do GPT-5.5 e cobrança de uso do GitHub Copilot para equipes de API.

FAQ

Os tokens de raciocínio contam como entrada ou saída para cobrança?Os tokens de raciocínio são cobrados na taxa de saída. A API do OpenAI os retorna em usage.completion_tokens_details.reasoning_tokens. Adicione-os a completion_tokens ao calcular o custo. Para os multiplicadores por esforço, consulte a análise de preços do GPT-5.5.

Quão preciso é response.usage em comparação com o painel do OpenAI?As contagens de tokens em response.usage correspondem ao painel token por token. Mudanças de preços podem causar pequenas variações se você calcular o custo de uma tabela de taxas desatualizada; defina a taxa por modelo e atualize-a no dia em que o OpenAI alterar os preços.

Posso fazer atribuição apenas com as chaves de projeto do OpenAI?As chaves de projeto oferecem uma dimensão de atribuição: por projeto. Elas não fornecem por funcionalidade, por cliente ou por rota. Use as chaves de projeto para divisões de ambiente e limites de orçamento; use metadados em nível de aplicativo para todo o resto.

E as retentativas e erros de limite de taxa? Eles contam o custo duas vezes?Uma requisição que falha antes de o modelo ser executado (4xx, erro de rede antes da conclusão) não retorna um objeto usage, portanto nenhum custo é registrado. Uma requisição que é bem-sucedida e depois retentada na camada do aplicativo será registrada duas vezes, a menos que você reutilize o request_id. Retentativas idempotentes devem passar o mesmo request_id e seu wrapper deve deduplicar na gravação.

Com que rapidez a API de uso do OpenAI retorna dados?A API de uso tem um atraso de dezenas de minutos. Para decisões em tempo real (alertas, kill-switches), use seu próprio data warehouse. Para reconciliação mensal, a API de uso é adequada e corresponde à sua fatura de cobrança.

Devo amostrar as requisições para reduzir o volume de logs?Não. O volume de dados é pequeno (uma linha JSON por requisição), e a amostragem compromete a atribuição por cliente e por rota. Registre cada requisição.

Posso usar esta abordagem para outros provedores de LLM?Sim. O esquema se generaliza. Adicione uma coluna provider (openai, anthropic, google, deepseek) e uma tabela de preços por provedor. O wrapper é específico do provedor; o data warehouse e os painéis não são. Para um ponto de comparação, consulte precificação da API DeepSeek V4.

Isso funciona para embeddings e chamadas de geração de imagem também?Sim, com matemática de custo específica do provedor. Embeddings são cobrados por token de entrada a uma taxa fixa; imagens são cobradas por imagem a uma taxa por resolução. Adicione endpoint (por exemplo, chat, embeddings, image) ao esquema e ramifique sua computação de custo nele.

botão