Consulta de saldo

Devuelve el estado de saldo de la cuenta a la que pertenece la API key actual, incluyendo saldo disponible, créditos acumulados y gasto acumulado.

Este endpoint forma parte de la OfoxAI OpenAPI y es independiente del protocolo (OpenAI / Anthropic / Gemini). Cualquier API key válida de OfoxAI puede llamarlo; la estructura de respuesta es compatible con cc-switch y herramientas similares.

Endpoint


GET https://api.ofox.ai/v1/user/balance

El mismo endpoint también está expuesto a través de las entradas Anthropic / Gemini para reutilización por clientes ya configurados con otra Base URL:

URL
`https://api.ofox.ai/v1/user/balance`
`https://api.ofox.ai/anthropic/user/balance`
`https://api.ofox.ai/gemini/user/balance`

Las tres URLs devuelven exactamente la misma estructura de respuesta.

Autenticación

Pase cualquier API key válida de OfoxAI (sk-...) mediante la cabecera Authorization: Bearer:


Authorization: Bearer sk-xxx

Use una API key de nivel de usuario (creada en el Dashboard ). No use claves internas Internal / Gateway.

Ejemplo de solicitud

cURL

Terminal


curl https://api.ofox.ai/v1/user/balance \
  -H "Authorization: Bearer $OFOX_API_KEY"

Python

balance.py


import os
import requests
 
resp = requests.get(
    "https://api.ofox.ai/v1/user/balance",
    headers={"Authorization": f"Bearer {os.environ['OFOX_API_KEY']}"},
)
data = resp.json()
print(f"Saldo disponible: ${data['balance']:.4f} {data['currency']}")

TypeScript

balance.ts


const resp = await fetch('https://api.ofox.ai/v1/user/balance', {
  headers: { Authorization: `Bearer ${process.env.OFOX_API_KEY}` },
})
const data = await resp.json()
console.log(`Saldo disponible: $${data.balance.toFixed(4)} ${data.currency}`)

Formato de respuesta

Respuesta exitosa 200 OK:


{
  "is_active": true,
  "balance": 42.1357,
  "total": 100.0000,
  "used": 57.8643,
  "currency": "USD"
}

Campos de respuesta

Campo	Tipo	Descripción
`is_active`	boolean	Si la cuenta es utilizable. `true` tras autenticación exitosa; `false` en caso de fallo
`balance`	number	Saldo disponible actual, equivale a `total - used`
`total`	number	Créditos acumulados: recargas + bonos + tarjetas de regalo
`used`	number	Gasto acumulado: consumo total de todas las llamadas
`currency`	string	Unidad monetaria, fija en `"USD"`

Todos los importes están en USD como flotantes de 64 bits. Internamente se rastrea con precisión NanoDollar (10⁻⁹ USD), exacta hasta fracciones de centavo.

Respuesta de error

Ante fallo de autenticación o error del servicio, se devuelve un código distinto de 200 con cuerpo compatible con cc-switch:


{
  "error": "unauthenticated",
  "is_active": false
}

Estado	Valor `error`	Descripción
`401`	`unauthenticated`	API key inválida, desactivada o expirada
`500`	`internal error`	Error interno del servicio, reintente más tarde

Compatibilidad con herramientas de terceros

La estructura de respuesta es compatible con la plantilla de consulta de saldo de cc-switch y funciona como proveedor de saldo directo para cc-switch:

is_active para verificación de estado
balance se mapea al campo remaining de cc-switch
total / used para mostrar progreso de uso