Referência da APIGET /v1/balance

GET /v1/balance

Retorna o saldo da conta dona da chave de API e quanto resta dos tetos de gastos dessa chave. Use-o para mostrar o crédito restante no seu app, para adicionar crédito antes que um lote fique sem saldo ou para pausar um agente antes que ele receba um 402.

Marcadores: $API_BASE é https://api.abliteratedllm.dev/v1, $API_ORIGIN é https://api.abliteratedllm.dev e $YOUR_KEY é sua chave de API.

bash
curl $API_BASE/balance -H "Authorization: Bearer $YOUR_KEY"
json
{
  "balance_usd": "12.345678",
  "held_usd": "0.000000",
  "trial": false,
  "available_usd": "12.345678",
  "key_daily_remaining_usd": "4.500000",
  "key_monthly_remaining_usd": null,
  "key_lifetime_remaining_usd": "40.000000"
}

Campos

CampoSignificado
balance_usdCrédito disponível para novas requisições, em USD com 6 casas decimais. O crédito reservado por requisições em andamento já foi descontado.
held_usdCrédito reservado por requisições que ainda estão em andamento. Quando cada uma termina, a reserva dela volta ao saldo, descontado o custo real.
trialtrue até que a primeira recarga da conta seja creditada. Contas de teste têm limites mais rígidos.
available_usdO crédito da conta menos o que as requisições em andamento reservam. As reservas são descontadas do saldo assim que são feitas; então este valor é sempre igual a balance_usd. Ele é compartilhado por todas as chaves da conta; os tetos de uma chave podem limitá-lo ainda mais (os campos abaixo).
key_daily_remaining_usdQuanto resta do teto diário desta chave hoje (UTC), ou null quando a chave não tem teto diário.
key_monthly_remaining_usdQuanto resta do teto mensal desta chave neste mês-calendário (UTC), ou null se não houver um.
key_lifetime_remaining_usdQuanto resta do orçamento total desta chave, ou null se não houver um.

Os valores são strings decimais para que nenhuma precisão se perca. Interprete-os como decimais, não como floats.

Observações

  • balance_usd pode ficar um pouco abaixo de zero: uma requisição sempre é cobrada pelo uso real, mesmo quando ele ultrapassa a reserva. Enquanto o saldo estiver abaixo da reserva da próxima requisição, as requisições falham com 402 insufficient_balance até você adicionar crédito.
  • held_usd normalmente é "0.000000" quando nada está em andamento. As reservas de requisições que nunca terminam são liberadas automaticamente após 15 minutos.
  • Um teto restante é o teto menos o gasto liquidado da chave no período e as reservas das requisições dela em andamento, a mesma soma que o gateway verifica antes de encaminhar uma requisição. Ele nunca fica abaixo de zero. Uma requisição falha com 402 key_spend_cap_reached quando a própria reserva não cabe; então, com um valor restante pequeno, uma requisição com orçamento de saída grande ainda pode ser recusada. Veja Autenticação.
  • Os tetos de gastos são por chave e não alteram o saldo. Cada chave informa os próprios tetos; o saldo é compartilhado por todas as chaves da conta.
  • Adicione crédito em Faturamento. O crédito não expira.