TokenLab Management API Adiciona Consulta de Saldo do Workspace

Deixar uma pipeline de produção automatizada travar por falta de saldo é algo evitável. A consulta de saldo da TokenLab Management API fornece aos fluxos de trabalho automatizados um saldo total consultável usando um token de gerenciamento em vez de uma chave de inferência.

Este guia aborda o contrato do endpoint GET /v1/management/balance, requisitos de autenticação, manipulação de moedas e como verificar esquemas de resposta diretamente em relação à documentação oficial.

Principais Pontos

• O endpoint de saldo da Management API (GET /v1/management/balance) retorna o saldo atual do workspace, o total de recargas e o gasto cumulativo de uso.
• A autenticação requer um token de gerenciamento (mt-...) criado em Dashboard → API → Management Tokens, mantendo verificações operacionais separadas das chaves de inferência de modelo (sk-...).
• Todos os valores monetários são retornados em USD. Cálculos exatos devem utilizar as strings decimais retornadas (balance_decimal, total_recharge_decimal, total_used_decimal).
• O endpoint combina-se com relatórios no nível de chave, como /v1/management/api-keys/{keyId}/usage e /v1/management/api-keys/{keyId}/billing.

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

Tokens de gerenciamento e chaves de inferência de modelo cumprem funções operacionais distintas no TokenLab:

• Chaves de API de inferência de modelo (sk-...): Usadas para chamar endpoints de inferência como POST /v1/chat/completions, POST /v1/responses, Anthropic Messages nativo em POST /v1/messages e Gemini em /v1beta/models/.... Essas chaves executam solicitações de geração, mas não expõem dados financeiros no nível da organização.
• Tokens de gerenciamento (mt-...): Restritos a rotas /v1/management/*. Eles permitem que backends inspecionem saldos de workspace, listem ou editem chaves de API e monitorem o uso sem conceder acesso à geração de modelos.

A separação dessas credenciais garante que scripts contábeis e monitores financeiros não possam disparar chamadas de inferência faturáveis, enquanto workers de modelo nunca obtêm acesso à administração da conta.

O Contrato de Rede do Endpoint de Saldo

Envie uma requisição GET para https://api.tokenlab.sh/v1/management/balance autenticando com seu token de gerenciamento no cabeçalho Authorization:

curl -X GET "https://api.tokenlab.sh/v1/management/balance" \
  -H "Authorization: Bearer mt-your-management-token"

Esquema de Resposta

Uma requisição bem-sucedida retorna 200 OK com um objeto organization_balance:

{
  "object": "organization_balance",
  "organization_id": "org_123",
  "balance": 42.5,
  "balance_decimal": "42.50",
  "total_recharge": 100,
  "total_recharge_decimal": "100",
  "total_used": 57.5,
  "total_used_decimal": "57.50"
}

Campos de Resposta

• object (string): Sempre organization_balance.
• organization_id (string): Organização associada ao token de gerenciamento atual.
• balance (number): Saldo atual do workspace em USD como um número de ponto flutuante para exibição.
• balance_decimal (string): Saldo atual exato do workspace em USD formatado como uma string decimal para reconciliação financeira.
• total_recharge (number): Valor total de recargas bem-sucedidas do workspace em USD.
• total_recharge_decimal (string): Valor total exato de recargas bem-sucedidas do workspace em USD formatado como uma string decimal.
• total_used (number): Gasto total de uso do workspace em USD.
• total_used_decimal (string): Gasto total exato de uso do workspace em USD formatado como uma string decimal.

Os campos monetários são estritamente em USD. Ao analisar o saldo programaticamente para verificações de limite ou conciliação contábil, analise balance_decimal com uma biblioteca decimal de precisão arbitrária em vez de primitivos de ponto flutuante para evitar perda de precisão.

Implementando Verificações de Saldo

Padrões comuns de integração incluem:

1. Guardrails Pré-Lote: Antes de disparar cargas de trabalho grandes—como geração de alto volume em modelos como gpt-5.5 ou glm-5.2—consulte /v1/management/balance. Se balance_decimal ficar abaixo do custo estimado do lote, pause a fila de tarefas.
2. Alertas de Saldo Baixo: Embora notificações automáticas por e-mail possam ser configuradas em Console → Settings, um cron agendado de monitoramento pode consultar periodicamente o endpoint e acionar notificações internas no Slack, PagerDuty ou via webhooks.
3. Reconciliação de Faturamento: Combine o saldo do workspace em tempo real com registros de uso de chaves individuais (/v1/management/api-keys/{keyId}/usage) para reconciliar despesas de tokens com itens faturados liquidados.

Para especificações completas de endpoints e métodos de gerenciamento de chaves, consulte a Referência da API Get Workspace Balance e a Visão Geral da Management API.