TokenLab Management API adiciona consulta de saldo da organização

A API de Gerenciamento da TokenLab agora oferece suporte à consulta direta de saldo, permitindo que as equipes verifiquem o saldo total da sua organização por meio de um token de gerenciamento, em vez de verificar o painel manualmente. Isso preenche uma lacuna comum para equipes que executam verificações automáticas de orçamento, alertas de recarga ou fluxos de trabalho limitados pelo uso.

Principais pontos

• A API de Gerenciamento agora expõe um endpoint de saldo que retorna o saldo total atual da sua organização.
• Isso é separado das chaves de API de inferência de modelo usadas para chamar Claude Sonnet 5, GPT-5.5, Gemini 3.5 Flash e outros modelos.
• A consulta de saldo destina-se a verificações de orçamento, alertas de recarga, pausa ou retomada de fluxos de trabalho automatizados e alimentação de painéis financeiros.
• O endpoint combina bem com o endpoint de uso de chave de API existente para criar uma visão completa dos gastos.

Por que isso estava faltando

Antes desta atualização, verificar o saldo da sua organização significava fazer login no painel da TokenLab e lê-lo na página de faturamento. Isso é aceitável para uma pessoa que verifica uma vez por dia, mas torna-se inviável no momento em que você deseja automatizar qualquer coisa.

Equipes que executam cargas de trabalho de produção em modelos como DeepSeek V4 Pro, Qwen3.7 Plus ou Kimi K2.7 Code geralmente desejam um script que verifique o saldo antes de iniciar um grande trabalho, ou um monitor que dispare um alerta quando o saldo cair abaixo de um limite. Sem um endpoint de saldo consultável, as únicas opções eram verificações manuais ou fazer scraping do painel, nenhuma das quais é algo que você deseja executar em produção.

A consulta de saldo por meio da API de Gerenciamento resolve isso. Agora, a mesma automação que dispara um lote de trabalhos de geração de vídeo no Kling 3.0 ou Seedance pode verificar o saldo disponível primeiro e decidir se deve prosseguir.

Tokens de Gerenciamento vs. Chaves de API de Inferência de Modelo

Vale a pena ser preciso sobre isso, porque os dois tipos de credenciais servem a propósitos diferentes e confundi-los leva a erros confusos.

As chaves de API de inferência de modelo são o que você usa para chamar modelos diretamente. Se você está enviando uma solicitação de chat completion para o GPT-5.5, gerando uma imagem com GPT Image 2 ou Nano Banana Pro, ou renderizando vídeo com Veo 3 ou PixVerse V6, você está se autenticando com uma chave de inferência. Essas chaves têm escopo para fazer chamadas de modelo e retornar a saída do modelo. Elas não dão acesso a dados em nível de conta, como saldo ou resumos de uso.

Os tokens de gerenciamento são um tipo de credencial separado criado para operações de conta. Eles permitem que você consulte informações sobre sua organização como um todo: saldo, uso por chaves de API e outros dados em nível de conta. Um token de gerenciamento não chama nenhum modelo diretamente. É a credencial que você usa para o lado contábil da execução de uma conta na TokenLab, não para o lado da geração.

Manter esses itens separados é importante por um motivo prático: permite que você entregue um token de gerenciamento a um processo financeiro ou de operações sem dar a esse processo a capacidade de consumir seu orçamento de modelo. Por outro lado, um serviço que só precisa chamar GLM-5.2 ou DeepSeek V4 Flash não precisa de visibilidade sobre seu saldo ou histórico de gastos, portanto, deve manter apenas uma chave de inferência.

Como funciona a consulta de saldo

O novo endpoint retorna o saldo total atual da sua organização como uma resposta direta. Você o chama com um token de gerenciamento, e ele informa a situação.

Aqui está um exemplo mínimo usando valores de espaço reservado:

curl -s https://api.tokenlab.sh/v1/management/balance \
  -H "Authorization: Bearer YOUR_MANAGEMENT_TOKEN"

A resposta fornece o valor do saldo atual da sua organização. A partir daí, o padrão usual é:

1. Chamar o endpoint de saldo em um cronograma ou logo antes do início de um trabalho caro.
2. Comparar o valor retornado com um limite definido por você.
3. Disparar a ação que fizer sentido: enviar um alerta, pausar uma fila, bloquear novas submissões de trabalho ou apenas registrar para mais tarde.

Como se trata de uma operação de leitura simples, é barato chamar com frequência. Equipes que executam pipelines de alto volume em modelos como DeepSeek V4 Pro ou Claude Sonnet 5 podem verificar o saldo antes de cada grande lote sem adicionar sobrecarga significativa.

Os detalhes completos do endpoint estão na referência de saldo da API de Gerenciamento.

Onde isso se encaixa: verificações de orçamento, alertas e painéis

Os usos mais comuns que as equipes têm solicitado mapeiam para quatro cenários:

Caso de uso	Como funciona
Verificação de orçamento pré-trabalho	O script verifica o saldo antes de enviar um trabalho em lote grande para um modelo como Kling 3.0 ou Veo 3, ignorando o trabalho se o saldo estiver muito baixo
Alerta de recarga	A verificação agendada compara o saldo com um valor mínimo, enviando um alerta no Slack ou e-mail quando ultrapassado
Pausa e retomada de fluxo de trabalho	A automação pausa um pipeline que chama Qwen3.7 Plus ou GLM-5.2 quando o saldo cai, retomando assim que for recarregado
Painéis financeiros	O valor do saldo é extraído em um cronograma e exibido junto com os dados de uso para relatórios

Se você estiver configurando isso pela primeira vez, uma pequena lista de verificação ajuda a manter a implementação limpa:

• Crie ou confirme se seu token de gerenciamento tem o escopo correto para acesso ao saldo
• Armazene o token de gerenciamento separadamente de quaisquer chaves de API de inferência
• Defina um intervalo de polling sensato (uma vez por trabalho, por hora ou diariamente, dependendo do seu caso de uso)
• Decida seu limite de alerta com antecedência, não depois que o saldo ficar baixo
• Combine a consulta de saldo com o endpoint de uso de chave de API se desejar um detalhamento completo dos gastos junto com o valor do saldo

Para equipes que também desejam dados históricos de gastos em vez de apenas um número de saldo ao vivo, a postagem sobre exportações de uso do painel aborda como extrair esses dados para relatórios.

Primeiros passos

Se você já está usando a API de Gerenciamento para relatórios de uso, adicionar verificações de saldo é simples: o mesmo padrão de autenticação, um novo endpoint para chamar. Se você ainda não configurou um token de gerenciamento, gere um nas configurações da sua conta e mantenha-o separado de quaisquer chaves de API de inferência que você usa para chamar modelos.

Perguntas frequentes

A consulta de saldo requer uma chave de API especial? Nenhum tipo de chave especial além de um token de gerenciamento padrão. É uma credencial diferente das chaves de API de inferência usadas para chamar modelos, mas nenhuma configuração adicional é necessária além de ter um token de gerenciamento válido.

Posso usar isso para interromper automaticamente os trabalhos quando o saldo acabar? Sim. Esse é um dos principais casos de uso. Verifique o saldo antes ou durante um trabalho e, se ele cair abaixo do seu limite, pause o fluxo de trabalho, interrompa a fila ou bloqueie novas submissões até que o saldo seja restaurado.

Isso é o mesmo que o endpoint de uso? Não. A consulta de saldo retorna o saldo total atual. O endpoint de uso de chave de API retorna dados de uso detalhados por chave. A maioria dos painéis financeiros usa ambos em conjunto.

Fontes e atualizações

Este artigo reflete o endpoint de saldo da API de Gerenciamento conforme observado em 2026-07-07. O comportamento do endpoint e os formatos de resposta podem mudar; verifique a documentação oficial do endpoint de saldo para a referência atual.

---

Pronto para incorporar verificações de saldo ao seu fluxo de trabalho? Faça login na TokenLab, gere um token de gerenciamento e comece a consultar o saldo da sua organização hoje mesmo.

Leitura relacionada e próximo passo

A consulta de saldo da organização funciona junto com outras ferramentas de relatório já disponíveis na API de Gerenciamento da TokenLab. Para uma visão mais detalhada de como os dados de gastos podem ser extraídos e revisados regularmente, consulte TokenLab Usage Exports Make AI API Spend Easier to Review. Se você está planejando gastos antes de um lançamento, o AI API Cost Calculator Guide: Estimate Spend Before You Ship orienta sobre como estimar custos antes que as solicitações sejam enviadas. E para o contexto sobre como os provedores se comparam, a AI API Pricing Comparison 2026: The Real Cost of GPT-5.5, Claude Sonnet 5, and Gemini 3.5 Flash detalha as taxas atuais entre os principais modelos.

Como sempre, a disponibilidade e os preços dos modelos mudam com frequência, portanto, confirme os detalhes atuais antes de confiar neles para uso em produção de alto volume. Pronto para testar a consulta de saldo você mesmo? Crie uma chave de API e comece a testar hoje.