O que é a OpenAI Usage API
A Usage API é a interface da OpenAI para consultar detalhes de uso da API em uma organização. Em vez de olhar apenas para um total mensal, a equipe consegue analisar dimensões como projeto, modelo, usuário e chave de API quando o endpoint e o agrupamento usados oferecem esses dados.
O assunto ganhou atenção entre desenvolvedores porque aplicações de IA podem ter vários serviços consumindo a mesma organização. Separar as chaves ajuda a descobrir qual aplicação gerou determinado volume de requisições ou tokens, o que deixa a investigação mais objetiva.
A ferramenta foi criada pela OpenAI como parte da plataforma administrativa da API. A documentação oficial consultada descreve endpoints de uso da organização e deixa claro que os dados de uso têm finalidade analítica. A documentação não informa, nessa página, uma data única de lançamento do recurso, então não há motivo para inventar uma.
Comece tratando cada chave como uma fronteira operacional. Uma chave por aplicação ou ambiente facilita a leitura do consumo e reduz a investigação baseada em suposições.
Como funciona
O fluxo começa com uma chamada autenticada a um endpoint de uso da organização. A consulta informa um start_time e pode incluir intervalo, largura do agrupamento e dimensões como api_key_id ou model, conforme o endpoint escolhido.
O retorno é organizado em períodos de tempo. Cada resultado pode trazer contagem de requisições, tokens de entrada, tokens de saída ou outro campo específico do produto consultado. Quando o agrupamento por chave é solicitado, o campo api_key_id identifica a chave associada ao resultado.
Pense na API como um extrato técnico. O extrato mostra quando e como o consumo foi registrado, mas não substitui a conciliação financeira. A própria documentação recomenda usar o endpoint de custos ou a área de custos do painel quando a pergunta for o valor que deve bater com a fatura.
Uso e faturamento são visões relacionadas, mas não são a mesma coisa. Uma soma de tokens pode não reconciliar perfeitamente com o valor financeiro, por isso não transforme uma métrica de uso em cobrança sem validar a fonte adequada.
Principais recursos
O recurso mais útil é a possibilidade de filtrar e agrupar dados para responder perguntas concretas. Em uma organização com vários sistemas, a equipe pode começar pelo projeto ou pela chave e depois abrir a análise por modelo.
- Uso por chave: ajuda a separar aplicações que compartilham a mesma organização.
- Uso por projeto: mostra a fronteira administrativa usada para organizar serviços e ambientes.
- Uso por modelo: indica quais modelos aparecem no consumo consultado.
- Tokens e requisições: permitem acompanhar volume técnico e frequência de chamadas.
Os endpoints de uso atendem categorias diferentes da plataforma, como completions, embeddings, imagens e áudio. Os campos mudam conforme a categoria, então o painel interno deve guardar também o tipo de endpoint usado em cada coleta.
Outro diferencial é a automação. Um relatório diário pode registrar o volume por chave, detectar uma mudança fora do padrão da própria aplicação e encaminhar a investigação para o time responsável. A automação funciona melhor quando serve para apontar perguntas, não para declarar sozinha que houve uma cobrança indevida.
Como começar: acesso passo a passo
Primeiro, confirme que a conta tem uma chave administrativa apropriada para consultar o uso da organização. Não coloque essa chave em um frontend, em um repositório ou em um log. O consumidor ideal é um serviço de backend com segredo armazenado no gerenciador de credenciais.
Depois, escolha um endpoint compatível com o tipo de uso que você quer observar. Para começar com chamadas de modelo, a documentação apresenta o endpoint de completions. Defina o início do intervalo em Unix e escolha uma janela coerente com a frequência do relatório.
Por fim, faça uma consulta pequena, salve o JSON bruto em um armazenamento protegido e valide os campos antes de criar gráficos. A sequência abaixo é um modelo de chamada. A variável representa o segredo e não deve ser substituída por uma chave real no código.
export OPENAI_ADMIN_KEY='chave-carregada-do-gerenciador-de-segredos'; export INICIO_UNIX='timestamp-do-inicio'; curl 'https://api.openai.com/v1/organization/usage/completions?start_time=$INICIO_UNIX&bucket_width=1d&group_by=api_key_id' -H 'Authorization: Bearer $OPENAI_ADMIN_KEY'Em produção, prefira que o serviço injete as variáveis no processo e aplique rotação de segredo. Também registre o intervalo consultado, a categoria do endpoint e a versão do coletor, sem registrar o valor do segredo.
Exemplo prático
Imagine uma empresa com uma aplicação de atendimento, um ambiente de testes e um job de análise. Cada componente usa uma chave diferente. No fim do dia, um coletor consulta o uso por chave e grava o identificador da chave, o intervalo, o modelo quando disponível e as métricas retornadas.
O time percebe que a chave do ambiente de testes teve um salto de requisições. Em vez de olhar para a fatura e tentar adivinhar a origem, a equipe cruza o horário do salto com os logs do ambiente. Encontra um teste de carga que ficou ativo depois da janela prevista e corrige o processo de desligamento.
O resultado útil não é apenas um gráfico bonito. É uma cadeia de evidências: consulta da Usage API, identificador da chave, janela de tempo, logs da aplicação e ação tomada. Se a pergunta mudar para o valor financeiro, o time repete a análise usando a fonte de custos indicada pela OpenAI.
{ intervalo: janela-do-relatório, api_key_id: identificador-retornado-pela-api, modelo: modelo-retornado-pela-api, requisições: campo-num_model_requests, ação: investigar-o-job-de-testes }Comparação com alternativas
A Usage API é uma boa fonte para dados agregados da organização, mas não é a única camada de observabilidade. Logs da aplicação explicam o contexto de cada chamada, enquanto métricas do provedor ajudam a acompanhar o serviço em uma janela padronizada.
Uma planilha manual pode funcionar para um projeto pequeno e poucas chaves. Ela perde valor quando a coleta fica diária, quando existem vários ambientes ou quando alguém precisa reproduzir a origem de um número. Nesse cenário, um job versionado e um banco de métricas dão mais rastreabilidade.
O painel web é útil para uma leitura rápida e para a conferência financeira. Um coletor via API é melhor quando a equipe precisa integrar dados a alertas, relatórios ou rotinas próprias. O ponto forte da Usage API é entregar uma base programável, não substituir todas as outras fontes.
- Usage API: use para análise agregada e automação.
- Logs da aplicação: use para explicar cada chamada e seu contexto.
- Painel de uso e custos: use para inspeção manual e conferência financeira.
- Planilha: use apenas quando o volume e a frequência forem pequenos.
Pontos positivos e limitações
O principal ponto positivo é a granularidade. Poder relacionar resultados a uma chave, projeto ou modelo facilita a divisão de responsabilidade entre equipes e torna a investigação mais rápida.
Também existe valor operacional na repetição. Um mesmo coletor pode buscar janelas diárias, comparar períodos e alimentar um relatório sem depender de copiar números do painel. Isso reduz trabalho manual e cria um histórico consultável.
A limitação mais importante é conceitual: a Usage API não deve ser tratada como o livro-caixa. A documentação alerta que uso e custos podem não reconciliar perfeitamente por diferenças no registro de consumo e faturamento. Além disso, uma chave identifica uma credencial, não necessariamente uma única funcionalidade se ela for compartilhada.
Não use uma chave compartilhada por serviços sem uma convenção clara. Quando o identificador aparece no relatório, ainda pode ser necessário consultar logs, projetos e donos do serviço para descobrir a causa real do consumo.
Casos de uso reais
Para uma startup, a API ajuda a acompanhar um produto em produção e separar o consumo do ambiente de desenvolvimento. O time pode manter um relatório simples com a variação por chave e investigar aumentos antes de fechar o ciclo financeiro.
Para uma software house, cada cliente ou produto pode ter uma fronteira de projeto e uma chave definida pela política interna. A leitura por chave e projeto facilita atribuir o consumo à equipe certa, desde que a organização não misture credenciais sem documentação.
Para uma equipe de plataforma, o uso por modelo ajuda a responder quais serviços dependem de cada opção. Isso apoia decisões técnicas sobre prompts, cache, limites e testes, sem concluir automaticamente que um modelo é sempre mais barato ou melhor.
Para um time de segurança, a variação por chave pode ser um sinal de investigação. Um aumento inesperado merece correlação com deploys, jobs, permissões e logs. A API aponta o lugar e o período; a causa precisa ser confirmada nos sistemas internos.
Dicas e boas práticas
Defina uma convenção de nomes e donos para chaves, projetos e ambientes. O identificador retornado pela API não deve depender da memória de uma única pessoa. Mantenha um catálogo interno sem guardar a chave secreta, apenas o identificador operacional e o responsável.
Faça o coletor registrar a janela consultada e o horário da coleta. Sem esse contexto, dois relatórios com o mesmo total podem parecer diferentes quando foram gerados em períodos distintos.
Separe o dado bruto da camada de apresentação. Salve a resposta original com controle de acesso e crie tabelas derivadas para gráficos. Assim, uma mudança no dashboard não apaga a evidência usada para investigar um alerta.
Use uma chave por fronteira de responsabilidade e combine a coleta por chave com logs estruturados que carreguem o nome do serviço. Esse vínculo é mais útil do que tentar inferir o dono apenas pelo volume.
Evite três erros comuns: consultar um intervalo diferente em cada relatório, somar campos incompatíveis entre endpoints e deixar a credencial administrativa em variáveis expostas ao frontend. Valide o esquema retornado antes de calcular qualquer indicador.
Crie alertas para investigação, não para acusação. Um salto pode ser um teste planejado, uma mudança de produto ou uma diferença de janela. O alerta precisa levar a uma verificação humana ou a uma regra interna bem documentada.
Vale a pena?
Vale a pena para equipes que têm mais de uma aplicação, ambiente ou modelo e precisam acompanhar o uso de forma repetível. A separação por chave pode economizar tempo de investigação e melhorar a conversa entre desenvolvimento, plataforma e financeiro.
Talvez não seja a primeira ferramenta para quem está fazendo um experimento pequeno com uma única aplicação. Nesse caso, logs básicos e o painel da plataforma podem resolver a necessidade inicial. A API ganha força quando existe uma pergunta recorrente que você quer responder automaticamente.
O próximo passo é escolher uma janela curta, consultar um endpoint de uso compatível e comparar a resposta com os logs da sua aplicação. Depois, acrescente a fonte de custos para a conciliação financeira e documente a política de chaves. Com esse cuidado, a Usage API vira uma peça útil de observabilidade para produtos de IA.