Referencia de la APIGET /v1/balance

GET /v1/balance

Devuelve el saldo de la cuenta dueña de la clave de API y cuánto queda de los topes de gasto de esa clave. Úsalo para mostrar el crédito restante en tu app, para recargar saldo antes de que un lote se quede sin fondos o para pausar un agente antes de que reciba un 402.

Marcadores de posición: $API_BASE es https://api.abliteratedllm.dev/v1, $API_ORIGIN es https://api.abliteratedllm.dev y $YOUR_KEY es tu clave 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 disponible para nuevas solicitudes, en USD con 6 decimales. El crédito retenido por las solicitudes en curso ya está descontado.
held_usdCrédito reservado por solicitudes que siguen en curso. Cuando termina cada una, su retención vuelve al saldo, menos el costo real.
trialtrue hasta que se acredita la primera recarga de la cuenta. Las cuentas de prueba tienen límites más estrictos.
available_usdEl crédito de la cuenta menos lo que retienen las solicitudes en curso. Las retenciones se descuentan del saldo en el momento en que se aplican, así que siempre es igual a balance_usd. Lo comparten todas las claves de la cuenta; los topes de una clave pueden limitarlo aún más (los campos siguientes).
key_daily_remaining_usdLo que queda hoy (UTC) del tope diario de esta clave, o null si la clave no tiene tope diario.
key_monthly_remaining_usdLo que queda del tope mensual de esta clave en este mes calendario (UTC), o null si no tiene.
key_lifetime_remaining_usdLo que queda del presupuesto total de esta clave, o null si no tiene.

Los montos son cadenas decimales para no perder precisión. Interprétalos como decimales, no como números de punto flotante.

Notas

  • balance_usd puede quedar ligeramente por debajo de cero: una solicitud siempre se cobra según su uso real, aunque supere su retención. Mientras el saldo sea menor que la retención de la siguiente solicitud, las solicitudes fallan con 402 insufficient_balance hasta que recargues saldo.
  • held_usd normalmente es "0.000000" cuando no hay nada en curso. Las retenciones de solicitudes que nunca terminan se liberan automáticamente después de 15 minutos.
  • Un tope restante es el tope menos el gasto liquidado de la clave en el período y las retenciones de sus solicitudes en curso, la misma suma que verifica el gateway antes de reenviar una solicitud. Nunca baja de cero. Una solicitud falla con 402 key_spend_cap_reached cuando su propia retención no cabe, así que un remanente pequeño aún puede rechazar una solicitud con un presupuesto de salida grande. Consulta Autenticación.
  • Los topes de gasto son por clave y no cambian el saldo. Cada clave informa sus propios topes; el saldo lo comparten todas las claves de la cuenta.
  • Recarga saldo en Facturación. El crédito no vence.