잔액 조회

현재 API 키가 속한 계정의 잔액 상태를 반환합니다. 사용 가능 잔액, 누적 충전, 누적 사용을 포함합니다.

이 엔드포인트는 OfoxAI OpenAPI에 속하며 프로토콜(OpenAI / Anthropic / Gemini)에 종속되지 않습니다. 유효한 OfoxAI API 키라면 모두 호출할 수 있으며 응답 구조는 cc-switch 등 서드파티 도구와 호환됩니다.

엔드포인트


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

동일 엔드포인트는 Anthropic / Gemini 입구를 통해서도 노출되어, 다른 Base URL이 이미 설정된 클라이언트에서도 재사용할 수 있습니다:

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

세 URL은 완전히 동일한 응답 구조를 반환합니다.

인증

유효한 OfoxAI API 키(sk-...)를 Authorization: Bearer 헤더로 전달합니다:


Authorization: Bearer sk-xxx

사용자 레벨 API 키(Dashboard 에서 생성)를 사용하세요. Internal / Gateway 내부 키는 사용하지 마세요.

요청 예시

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"사용 가능 잔액: ${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(`사용 가능 잔액: $${data.balance.toFixed(4)} ${data.currency}`)

응답 형식

성공 응답 200 OK:


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

응답 필드

필드	타입	설명
`is_active`	boolean	계정 사용 가능 여부. 인증 성공 시 `true`, 실패 시 `false`
`balance`	number	현재 사용 가능 잔액, `total - used`와 동일
`total`	number	누적 충전: 충전 + 보너스 + 기프트 카드 합계
`used`	number	누적 사용: 모든 호출의 총 소비량
`currency`	string	통화 단위, `"USD"` 고정

모든 금액은 USD 단위의 64비트 부동소수점이며, 내부적으로 NanoDollar(10⁻⁹ USD) 정밀도로 추적되어 서브 센트 단위까지 정확합니다.

오류 응답

인증 실패 또는 서비스 이상 시 200이 아닌 상태 코드와 cc-switch 호환 형식의 본문을 반환합니다:


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

상태 코드	`error` 값	설명
`401`	`unauthenticated`	API 키 무효, 비활성화 또는 만료
`500`	`internal error`	서비스 내부 오류, 잠시 후 재시도

서드파티 도구 호환성

본 엔드포인트의 응답 구조는 cc-switch 의 잔액 조회 템플릿과 호환되어, cc-switch 잔액 제공자로 직접 연동 가능합니다:

is_active로 상태 체크
balance는 cc-switch의 remaining 필드에 매핑
total / used로 사용 진행 표시