Consulta de saldo

Retorna o status de saldo da conta a que pertence a chave API atual, incluindo saldo disponível, créditos acumulados e gasto acumulado.

Este endpoint faz parte da OfoxAI OpenAPI e é independente de protocolo (OpenAI / Anthropic / Gemini). Qualquer chave API OfoxAI válida pode chamá-lo; a estrutura de resposta é compatível com cc-switch e ferramentas semelhantes.

Endpoint


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

O mesmo endpoint também é exposto via entradas Anthropic / Gemini, conveniente para clientes já configurados com outra Base URL:

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

As três URLs retornam exatamente a mesma estrutura de resposta.

Autenticação

Passe qualquer chave API OfoxAI válida (sk-...) pelo header Authorization: Bearer:


Authorization: Bearer sk-xxx

Use uma chave API de nível de usuário (criada no Dashboard ). Não use chaves Internal / Gateway internas.

Exemplo de requisição

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 disponível: ${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 disponível: $${data.balance.toFixed(4)} ${data.currency}`)

Formato de resposta

Resposta de sucesso 200 OK:


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

Campos de resposta

Campo	Tipo	Descrição
`is_active`	boolean	Se a conta está utilizável. `true` após autenticação bem-sucedida; `false` em caso de falha
`balance`	number	Saldo disponível atual, igual a `total - used`
`total`	number	Créditos acumulados: recargas + bônus + cartões-presente
`used`	number	Gasto acumulado: consumo total de todas as chamadas
`currency`	string	Moeda, fixa em `"USD"`

Todos os valores em USD como floats de 64 bits. Internamente rastreado com precisão NanoDollar (10⁻⁹ USD), preciso até frações de centavo.

Resposta de erro

Em caso de falha de autenticação ou erro de serviço, retorna código diferente de 200 com corpo compatível com cc-switch:


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

Status	Valor `error`	Descrição
`401`	`unauthenticated`	Chave API inválida, desativada ou expirada
`500`	`internal error`	Erro interno do serviço, tente novamente

Compatibilidade com ferramentas de terceiros

A estrutura de resposta é compatível com o template de consulta de saldo do cc-switch e funciona como provedor direto de saldo para cc-switch:

is_active para verificação de status
balance mapeia para o campo remaining do cc-switch
total / used para exibir progresso de uso