API 키로 잔액 조회하기

sk-로 시작하는 API 키로 현재 키의 남은 할당량과 사용 가능 상태를 바로 조회할 수 있습니다. 서드파티 클라이언트가 화면에 잔액을 표시하거나, 스크립트로 잔액을 모니터링할 때 적합합니다.

1. 엔드포인트 개요

2. 어떤 잔액이 반환되나요

balance는 반드시 계정 지갑 잔액은 아니며, 현재 키가 실제로 사용할 수 있는 남은 할당량입니다. 다음 순서에서 처음 해당하는 값이 사용됩니다.

또한 is_active는 이 키가 현재 업무 요청에 사용할 수 있는지를 나타냅니다. 키 상태가 활성이고, 만료되지 않았고, 총 할당량을 모두 사용하지 않았으면 true입니다. 구독 그룹에 속해 있으면서 유효한 구독이 없으면 false입니다.

3. GET /v1/user/balance

GET /v1/user/balance HTTP/1.1
Host: api.lmuai.com
Authorization: Bearer sk-xxxxxxxx

응답 — 지갑 잔액 모드 (키에 할당량이 없고 구독 그룹도 아님):

{
  "is_active": true,
  "balance": 1575.13,
  "unit": "USD"
}

응답 — 키에 총 할당량이 있는 경우 (used와 total이 추가로 반환됩니다):

{
  "is_active": true,
  "balance": 6,
  "unit": "USD",
  "used": 4,
  "total": 10
}

응답 — 횟수 기반 구독 그룹:

{
  "is_active": true,
  "balance": 842,
  "unit": "requests"
}

응답 필드

4. GET /v1/credits

OpenRouter 형식의 잔액 포맷이며, 클라이언트는 total_credits - total_usage로 남은 할당량을 표시합니다.

GET /v1/credits HTTP/1.1
Host: api.lmuai.com
Authorization: Bearer sk-xxxxxxxx

응답:

{
  "data": {
    "total_credits": 20,
    "total_usage": 4
  }
}

5. 서드파티 클라이언트 설정

curl -s https://api.lmuai.com/v1/user/balance \
  -H "Authorization: Bearer sk-xxxxxxxx"

6. 오류 응답

잔액 조회는 게이트웨이 공통 API 키 인증을 사용하므로, 오류도 다른 API 호출과 같은 형식으로 반환됩니다. 요청에 키가 없을 때:

{
  "code": "API_KEY_REQUIRED",
  "message": "API key is required in Authorization header (Bearer scheme), x-api-key header, or x-goog-api-key header"
}

일반적인 오류는 오류 코드를 참조하세요.

7. '사용 내역 상세 내보내기'와의 차이

GET /v1/usage는 그 중간에 해당하는 엔드포인트입니다. 마찬가지로 sk- 키를 사용하며 현재 키의 오늘 / 누적 사용 통계와 할당량 정보를 반환합니다. 필드가 더 상세합니다.

마지막 업데이트: 2026-11-05

京ICP备2020034311号-7