# API 키로 잔액 조회하기

> sk- API 키로 현재 키의 남은 할당량을 조회합니다. GET /v1/user/balance는 is_active / balance / unit을, GET /v1/credits는 OpenRouter 형식의 total_credits / total_usage를 반환하며 cc-switch 등 서드파티 클라이언트의 주기적 조회를 지원합니다.

URL: https://docs.lmuai.com/ko/docs/api/balance



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

<Callout type="info">
  **읽기 전용 엔드포인트입니다**: 과금도 할당량 소모도 없습니다. 인증은 키 자체만 검증하므로 할당량을 모두 사용해 업무 요청이 거부되는 상태에서도 남은 할당량을 조회할 수 있습니다(이때 `is_active`는 `false`입니다).
</Callout>

***

## 1. 엔드포인트 개요 [#1-엔드포인트-개요]

| 엔드포인트                  | 대응하는 클라이언트 형식                         | 반환                                                                  |
| ---------------------- | ------------------------------------- | ------------------------------------------------------------------- |
| `GET /v1/user/balance` | cc-switch 범용 잔액 템플릿                   | `is_active` / `balance` / `unit`, 키에 총 할당량이 있으면 `used` / `total` 추가 |
| `GET /user/balance`    | 위와 동일. Base URL에 `/v1`을 붙이지 않는 경우의 형식 | 위와 완전히 동일                                                           |
| `GET /v1/credits`      | OpenRouter 형식                         | `data.total_credits` / `data.total_usage`                           |

| 항목        | 값                                |
| --------- | -------------------------------- |
| Base URL  | `https://api.lmuai.com`          |
| 인증 방식     | `Authorization: Bearer <sk-...>` |
| 응답 형식     | JSON                             |
| 로그인 필요 여부 | 불필요. API 키만 있으면 됩니다              |

<Callout type="warn">
  `/user/balance`는 `/v1/user/balance`의 별칭입니다(클라이언트에서 Base URL을 `/v1` 없이 설정한 경우 사용). `/v1/credits`에는 루트 경로 별칭이 **없습니다**. 반드시 `/v1`을 붙여야 합니다.
</Callout>

***

## 2. 어떤 잔액이 반환되나요 [#2-어떤-잔액이-반환되나요]

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

| 순서 | 키 상태             | `balance`의 의미                          |
| -- | ---------------- | -------------------------------------- |
| 1  | 키에 별도 총 할당량이 설정됨 | 해당 키의 남은 할당량(`total - used`)           |
| 2  | 키가 구독 그룹에 속함     | 구독의 남은 할당량(`unit`이 `requests`이면 남은 횟수) |
| 3  | 위 어디에도 해당하지 않음   | 계정 지갑 잔액                               |

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

***

## 3. `GET /v1/user/balance` [#3-get-v1userbalance]

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

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

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

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

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

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

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

### 응답 필드 [#응답-필드]

| 필드          | 타입     | 설명                                        |
| ----------- | ------ | ----------------------------------------- |
| `is_active` | bool   | 이 키가 현재 업무 요청에 사용 가능한지                    |
| `balance`   | number | 남은 할당량. 단위는 `unit` 참조                     |
| `unit`      | string | `USD`(기본값), 또는 횟수 기반 구독 그룹의 경우 `requests` |
| `used`      | number | **키에 총 할당량이 있을 때만** 반환. 이 키의 사용량          |
| `total`     | number | **키에 총 할당량이 있을 때만** 반환. 이 키의 총 할당량        |

<Callout type="info">
  `used` / `total`은 키 개별 할당량 모드에서만 정확한 값을 가집니다. 지갑 잔액 모드와 구독 모드에서는 반환되지 않습니다. `balance`를 기준으로 하고 `total - used`로 역산하지 마세요.
</Callout>

***

## 4. `GET /v1/credits` [#4-get-v1credits]

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

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

**응답:**

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

| 필드                   | 타입     | 설명                                                                   |
| -------------------- | ------ | -------------------------------------------------------------------- |
| `data.total_credits` | number | **사용량 + 남은 양**. `total_credits - total_usage`가 정확히 남은 할당량이 되도록 구성됩니다 |
| `data.total_usage`   | number | 사용한 할당량                                                              |

<Callout type="warn">
  `total_credits`는 '사용량 + 남은 양'을 합성한 값이며 할당량 상한의 문자 그대로의 값이 **아닙니다**. 지갑 잔액 모드에서는 `total_usage`가 `0`이므로 `total_credits`가 잔액과 같습니다. 할당량을 모두 사용하면 남은 할당량은 `0`으로 잘리므로, 이때 `total_credits`는 사용량과 같아집니다.
</Callout>

***

## 5. 서드파티 클라이언트 설정 [#5-서드파티-클라이언트-설정]

| 클라이언트 / 용도                              | 설정 방법                                                                                             |
| --------------------------------------- | ------------------------------------------------------------------------------------------------- |
| cc-switch 범용 잔액 템플릿                     | Base URL을 `https://api.lmuai.com`(`/v1` 없이) 또는 `https://api.lmuai.com/v1`(`/v1` 포함) 모두 사용할 수 있습니다 |
| OpenRouter 호환 클라이언트(Kelivo, RikkaHub 등) | Base URL에 `https://api.lmuai.com/v1`을 설정하면 클라이언트가 `/v1/credits`를 호출합니다                            |
| 직접 작성한 스크립트                             | `/v1/user/balance`를 직접 호출하는 것을 권장합니다. 필드가 더 직관적입니다                                                |

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

***

## 6. 오류 응답 [#6-오류-응답]

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

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

| 상태 코드 | `code`             | 상황                                                                            |
| ----- | ------------------ | ----------------------------------------------------------------------------- |
| `200` | —                  | 정상 응답입니다. 한도 소진, 키 만료, 구독 없음도 `200`을 반환하며 `is_active: false`로 사용할 수 없음을 나타냅니다 |
| `401` | `API_KEY_REQUIRED` | 요청에 API 키가 없음                                                                 |
| `401` | `INVALID_API_KEY`  | 키가 존재하지 않거나 형식이 잘못됨                                                           |
| `401` | `API_KEY_DISABLED` | 키가 비활성화됨                                                                      |
| `403` | `ACCESS_DENIED`    | 키에 IP 허용 목록 / 차단 목록이 설정되어 있고 현재 IP가 허용되지 않음                                   |

일반적인 오류는 [오류 코드](/ko/docs/guide/errors)를 참조하세요.

***

## 7. '사용 내역 상세 내보내기'와의 차이 [#7-사용-내역-상세-내보내기와의-차이]

|    | 이 페이지의 잔액 엔드포인트       | [사용 내역 상세 내보내기](/ko/docs/api/usage-export) |
| -- | --------------------- | ------------------------------------------ |
| 인증 | `sk-` API 키           | 계정과 비밀번호로 JWT 발급                           |
| 단위 | 현재 키의 남은 할당량          | 계정 단위 요청별 상세 내역                            |
| 용도 | 클라이언트의 잔액 표시, 잔액 모니터링 | 청구서 내보내기, 대사, BI 적재                        |

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