메인 콘텐츠로 건너뛰기
GET
https://api.apimart.ai
/
v1
/
user
/
balance
curl --request GET \
  --url 'https://api.apimart.ai/v1/user/balance' \
  --header 'Authorization: Bearer <token>'

{
  "success": true,
  "remain_balance": 100.0,
  "used_balance": 25.5,
  "unlimited_quota": false
}
현재 사용자 계정의 남은 잔액과 사용된 잔액을 조회합니다. 이 엔드포인트는 특정 토큰에 의존하지 않는 사용자 수준의 잔액 정보를 반환하며, 전체 계정 잔액을 확인하는 데 사용됩니다. 
curl --request GET \
  --url 'https://api.apimart.ai/v1/user/balance' \
  --header 'Authorization: Bearer <token>'

{
  "success": true,
  "remain_balance": 100.0,
  "used_balance": 25.5,
  "unlimited_quota": false
}

​
인증

​
Authorization
string
required
모든 API 엔드포인트에는 Bearer Token 인증이 필요합니다API 키 받기:API 키 관리 페이지에서 API 키를 받으세요요청 헤더에 추가:
Authorization: Bearer YOUR_API_KEY

​
엔드포인트

GET /v1/user/balance
GET /user/balance
두 엔드포인트는 동일한 기능을 가지고 있습니다. 둘 중 하나를 사용할 수 있습니다.

​
응답

​
success
boolean
요청 성공 여부
​
message
string
오류 메시지 (실패 시에만 반환)
​
remain_balance
float
사용자 남은 잔액 (성공 시 반환). unlimited_quota가 true일 때 값은 -1입니다
​
used_balance
float
사용자 사용된 잔액 (성공 시 반환)
​
unlimited_quota
boolean
사용자가 무제한인지 여부. true는 무제한, false는 제한됨을 의미합니다

​
토큰 잔액 vs 사용자 잔액

비교 항목토큰 잔액 (/v1/balance)사용자 잔액 (/v1/user/balance)
범위단일 토큰전체 사용자 계정
데이터 소스Token의 RemainQuota와 UsedQuotaUser의 quota와 used_quota
사용 사례단일 API 키 사용량 모니터링전체 계정 잔액 확인
제한 대상토큰 수준 한도사용자 수준 한도

​
사용 사례

  • 사용자 계정의 전체 잔액 확인
  • 충전 알림 및 잔액 경고 설정
  • 사용자 대시보드에서 계정 잔액 표시
잔액 단위 정보잔액 값의 단위는 시스템 설정에 따라 다릅니다:
  • USD - 미국 달러
  • CNY - 중국 위안
  • Tokens - 토큰 수
무제한 사용자사용자가 무제한으로 설정된 경우:
  • unlimited_quota 필드는 true를 반환합니다
  • remain_balance 필드는 -1을 반환합니다
  • 해당 사용자는 제한 없이 API를 무제한으로 사용할 수 있습니다

​
일반적인 오류

오류 메시지원인해결 방법
Authorization 헤더 없음Authorization 헤더가 제공되지 않음Authorization: Bearer sk-xxxxx 헤더 추가
사용자 잔액 가져오기 실패사용자가 존재하지 않음토큰과 연결된 사용자가 존재하는지 확인
사용된 잔액 가져오기 실패데이터베이스 쿼리 오류관리자에게 연락하여 시스템 상태 확인
보안 참고 사항API 키는 비밀번호와 같습니다. 안전하게 보관하고 다른 사람과 공유하지 마세요. 프로덕션에서는 항상 HTTPS를 사용하세요.