Gerenciamento

API de Gerenciamento

Verifique saldos do Workspace, gerencie chaves de API e consulte uso e faturamento

Use a Management API a partir do seu próprio backend ou automação para gerenciar um Workspace do TokenLab. Ela usa um token de gerenciamento, portanto o programa não precisa de uma chave de API comum.

Crie um token de gerenciamento em Dashboard → API → Management Tokens:

Authorization: Bearer mt-your-management-token

Tokens de gerenciamento e chaves de API têm funções diferentes. Use mt-... apenas com /v1/management/*. Use sk-... com APIs de modelos, como /v1/responses.

Endpoints

EndpointMétodoUso
/v1/management/balanceGETObter o saldo do Workspace
/v1/management/api-keysGETListar chaves de API
/v1/management/api-keysPOSTCriar uma chave de API
/v1/management/api-keys/{keyId}PATCHAlterar seu nome, limite, modelos, expiração ou status
/v1/management/api-keys/{keyId}/usageGETObter registros individuais de uso
/v1/management/api-keys/{keyId}/billingGETObter um resumo de faturamento

Chaves de API

  • O segredo completo de uma nova chave aparece apenas na resposta de criação.
  • models: [] não adiciona nenhuma restrição de modelo no nível da chave.
  • limitAmount: null significa ilimitado. 0 impede que a chave gere gastos.
  • Os valores usam USD. Enviar CNY retorna 400 currency_retired.
  • inactive pode ser ativado novamente. Use revoked para desativar uma chave permanentemente.

Uso e Faturamento

/usage retorna registros paginados e suporta filtros por modelo, fabricante do modelo, cenário e data. Registros liquidados podem incluir billing_transaction_id; salve-o com request_id quando precisar correlacionar uma cobrança a uma requisição.

/billing retorna totais agrupados por modelo, fabricante do modelo, cenário e data. Não inclui recargas do Workspace ou faturas.

Um endDate contendo apenas data, como 2026-07-31, significa 00:00 UTC no início desse dia. Para incluir o dia inteiro, passe a data seguinte ou um horário no formato RFC3339, como 2026-07-31T23:59:59Z.

Erros

Os erros usam o objeto error padrão. Trate-os por status e code.

StatuscodeSignificado
400validation_errorUm campo ou parâmetro de consulta é inválido
400invalid_model_accessUm modelo em models não é permitido pela política de modelos do Workspace
400currency_retiredlimitCurrency é CNY; use USD
401invalid_management_tokenO token está ausente, malformado ou foi revogado
403organization_inactiveO Workspace não está ativo
404not_foundA chave de API não está neste Workspace
409api_key_revokedUma chave revogada não pode ser reativada; crie uma nova chave
429report_busyMuitos relatórios de uso ou faturamento estão em execução. Tente novamente após os segundos indicados em Retry-After

Exemplo

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

Próximos passos

Nesta página