> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 잔액 조회 API: AccessToken으로 /api/user/self 호출

> 시스템 AccessToken을 발급받아 /api/user/self를 호출하고, quota 필드를 읽어 달러로 환산해 잔액 알림에 활용하는 방법입니다.

| 항목 | 내용 |
| - | - |
| 엔드포인트 | `GET https://api.laozhang.ai/api/user/self` |
| 인증 | `Authorization` 헤더에 시스템 AccessToken |
| 주요 필드 | 남은 quota, 사용한 quota, 요청 횟수, 계정 그룹 |
| 환산 | `quota`를 500,000으로 나누면 남은 잔액(USD). 아래 달러 환산 절 참고 |

> [!NOTE]
>
> **AccessToken은 모델 요청에 쓰는 API 키와 다르며, 계정에 대한 권한이 더 넓습니다.**
>
> * 서버의 환경 변수나 시크릿 매니저에 보관하세요.
> * 브라우저나 클라이언트 앱에 넣지 마세요.

## AccessToken 발급

**1. 계정 설정 열기**

콘솔에 로그인한 뒤 [계정 설정](https://api.laozhang.ai/account/profile)을 엽니다.

**2. 시스템 토큰 창 열기**

**System Token**(시스템 토큰)을 선택하고, 콘솔이 요구하면 계정 비밀번호를 입력합니다.

**3. AccessToken 복사**

AccessToken이 표시되면 바로 복사해 안전한 곳에 저장하세요. 새 AccessToken을 발급하면 이전 것이 무효가 될 수 있으므로, 사용하는 모든 서비스를 함께 갱신해야 합니다.

AccessToken을 소스 코드, 브라우저 앱, 로그, 스크린샷, 지원 문의에 포함하지 마세요. 지원을 요청할 때는 요청 시각, HTTP 상태, 응답 메시지, 민감 정보를 가린 명령어를 보내 주세요.

## 엔드포인트

```text theme={null}
GET https://api.laozhang.ai/api/user/self
Authorization: <your AccessToken>
```

이 요청은 쿼리 파라미터나 본문이 없고 응답은 JSON입니다. 아래 예제처럼 `Authorization` 값으로 AccessToken을 그대로 전달하세요. `Accept: application/json`과 `Content-Type: application/json`은 선택입니다. cURL에서는 응답 압축이 풀리도록 `--compressed`를 권장합니다.

## 응답

요청이 성공하면 다음과 같이 반환됩니다.

```json theme={null}
{
  "success": true,
  "message": null,
  "data": {
    "id": 12345,
    "username": "demo_user",
    "display_name": "demo_user",
    "role": 1,
    "status": 1,
    "email": "",
    "quota": 24997909,
    "used_quota": 10027091,
    "request_count": 339,
    "group": "default",
    "ModelFixedPrice": []
  }
}
```

| 필드 | 타입 | 설명 |
| - | - | - |
| `success` | Boolean | 요청 성공 여부 |
| `message` | String 또는 null | 오류 메시지. 성공하면 보통 `null` |
| `data.quota` | Integer | 남은 quota. 알림 기준값에 사용 |
| `data.used_quota` | Integer | 지금까지 사용한 quota |
| `data.request_count` | Integer | 총 요청 횟수 |
| `data.group` | String | 계정 그룹 |
| `data.username` | String | 사용자 이름 |
| `data.display_name` | String | 표시 이름 |
| `data.ModelFixedPrice` | Array | 모델 가격 데이터. 잔액만 필요하면 무시해도 됨 |
| `data.access_token` | String | 민감한 값. 반환되더라도 로그에 남기지 마세요 |

응답에는 계정에 따라 다른 필드가 포함될 수 있습니다. 필요한 필드만 읽고, 모르는 필드는 파서가 무시하도록 하세요.

## quota를 달러로 환산

`quota`와 `used_quota`는 달러가 아니라 quota 단위로 반환됩니다. 500,000 quota가 약 1 USD입니다.

| 값 | 계산식 | 예시 응답 기준 |
| - | - | - |
| 남은 잔액 | `quota ÷ 500,000` | `24997909 ÷ 500,000` ≈ 50.00 USD |
| 사용 금액 | `used_quota ÷ 500,000` | `10027091 ÷ 500,000` ≈ 20.05 USD |
| 남은 금액과 사용 금액의 합 | `(quota + used_quota) ÷ 500,000` | ≈ 70.05 USD |

이 환산은 표시용입니다. 요청의 실제 비용은 모델 가격, 토큰 그룹, 호출 로그에 표시된 청구액으로 정해집니다. 알림용으로는 정밀도를 유지하도록 원본 `quota`와 환산 금액을 함께 저장하세요.

## 코드 예제

터미널에서 AccessToken을 한 번 설정합니다. 자리 표시자는 실제 값으로 바꾸세요.

```bash theme={null}
export LAOZHANG_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
```

> [tab] cURL
>
> ```bash theme={null}
> curl --compressed -s "https://api.laozhang.ai/api/user/self" \
>   -H "Accept: application/json" \
>   -H "Authorization: $LAOZHANG_ACCESS_TOKEN" \
>   -H "Content-Type: application/json"
> ```
>
> `--compressed`가 없으면 터미널에 깨진 문자가 나오고 `jq`는 `Invalid numeric literal` 오류를 낼 수 있습니다.

> [tab] cURL + jq
>
> ```bash theme={null}
> curl --compressed -s "https://api.laozhang.ai/api/user/self" \
>   -H "Accept: application/json" \
>   -H "Authorization: $LAOZHANG_ACCESS_TOKEN" \
>   -H "Content-Type: application/json" |
>   jq '.data | {
>     quota,
>     remaining_usd: (.quota / 500000),
>     used_quota,
>     used_usd: (.used_quota / 500000),
>     request_count,
>     group
>   }'
> ```

> [tab] Python
>
> `python -m pip install requests`로 `requests`를 설치한 뒤 실행합니다.
>
> ```python theme={null}
> import os
> import requests
>
> response = requests.get(
>     "https://api.laozhang.ai/api/user/self",
>     headers={
>         "Accept": "application/json",
>         "Authorization": os.environ["LAOZHANG_ACCESS_TOKEN"],
>         "Content-Type": "application/json",
>     },
>     timeout=10,
> )
> response.raise_for_status()
> payload = response.json()
> if not payload.get("success"):
>     raise SystemExit(f"잔액 조회에 실패했습니다: {payload.get('message')}")
>
> account = payload["data"]
> quota_per_usd = 500_000
> print("quota:", account["quota"])
> print("remaining_usd:", round(account["quota"] / quota_per_usd, 2))
> print("used_quota:", account["used_quota"])
> print("used_usd:", round(account["used_quota"] / quota_per_usd, 2))
> print("request_count:", account["request_count"])
> print("group:", account.get("group"))
> ```
>
> `requests`는 gzip 응답을 자동으로 해제합니다.

> [tab] Node.js
>
> 아래 코드를 `.mjs` 파일로 저장하고 Node.js 18 이상에서 실행합니다.
>
> ```javascript theme={null}
> const response = await fetch("https://api.laozhang.ai/api/user/self", {
>   headers: {
>     Accept: "application/json",
>     Authorization: process.env.LAOZHANG_ACCESS_TOKEN,
>     "Content-Type": "application/json",
>   },
>   signal: AbortSignal.timeout(10_000),
> });
> if (!response.ok) {
>   throw new Error(`잔액 조회에 실패했습니다: HTTP ${response.status}`);
> }
>
> const payload = await response.json();
> if (!payload.success) {
>   throw new Error(`잔액 조회에 실패했습니다: ${payload.message}`);
> }
>
> const account = payload.data;
> const quotaPerUsd = 500_000;
> console.log({
>   quota: account.quota,
>   remaining_usd: Number((account.quota / quotaPerUsd).toFixed(2)),
>   used_quota: account.used_quota,
>   used_usd: Number((account.used_quota / quotaPerUsd).toFixed(2)),
>   request_count: account.request_count,
>   group: account.group,
> });
> ```

## 오류

### 401 Unauthorized

```json theme={null}
{
  "success": false,
  "message": "Unauthorized"
}
```

`Authorization` 헤더가 비어 있거나, AccessToken이 일부만 입력되었거나 더 이상 유효하지 않거나, AccessToken 대신 모델 API 키를 보낸 경우입니다. 원인별 해결 방법은 [잔액 조회 API의 401 오류 해결](https://docs.laozhang.ai/en/faq/balance-query-api.md)에서 확인하세요.

상태 코드와 본문을 함께 보세요.

* `Authorization` 헤더가 아예 없으면 HTTP 401과 `code: AUTH_REQUIRED`가 반환됩니다.
* AccessToken이 틀렸거나 만료되었으면 **HTTP 200**과 `success: false`, 그리고 access token이 유효하지 않다는 메시지가 반환됩니다.

상태 코드만 믿지 말고 스크립트에서 `success`를 확인하세요.

### 403 Forbidden

```json theme={null}
{
  "success": false,
  "message": "Forbidden"
}
```

이 엔드포인트에 대한 권한이 없는 인증 정보이거나, 계정에 고객 지원의 확인이 필요한 경우입니다.

### 깨진 출력 또는 jq 오류

cURL이 깨진 문자를 출력하거나 `jq`가 `Invalid numeric literal`을 보고하면 압축된 응답이 해제되지 않은 것입니다. cURL 명령에 `--compressed`를 추가하세요.

## 모니터링 권장 사항

잔액이 바닥나기 전에 알림을 받으려면 이 엔드포인트를 주기적으로 확인하세요. 아래 스크립트는 남은 잔액이 기준값 아래로 내려가면 종료 코드 1로 끝납니다.

```python theme={null}
import os
import sys
import requests

THRESHOLD_USD = float(os.environ.get("LAOZHANG_ALERT_USD", "20"))

response = requests.get(
    "https://api.laozhang.ai/api/user/self",
    headers={"Authorization": os.environ["LAOZHANG_ACCESS_TOKEN"]},
    timeout=10,
)
response.raise_for_status()
remaining_usd = response.json()["data"]["quota"] / 500000

if remaining_usd < THRESHOLD_USD:
    print(f"잔액 ${remaining_usd:.2f}이(가) 기준값 ${THRESHOLD_USD} 미만입니다")
    sys.exit(1)
```

cron이나 모니터링 시스템에서 10\~30분마다 실행하고, 종료 코드가 0이 아니면 알림을 보내세요. 예를 들면 다음과 같습니다.

```bash theme={null}
*/10 * * * * /usr/bin/python3 /opt/check_balance.py || /opt/notify.sh
```

cron은 셸 환경을 불러오지 않으므로 `LAOZHANG_ACCESS_TOKEN`은 스크립트나 crontab에서 직접 지정해야 합니다. 설정할 때 다음을 지키세요.

* `LAOZHANG_ACCESS_TOKEN`은 환경 변수나 시크릿 매니저에 보관합니다.
* 10초 정도의 요청 타임아웃을 설정합니다.
* 조회 간격은 적당히 두세요. 잔액 알림에 초 단위 조회는 필요하지 않습니다.
* 알림에 `quota`, 환산한 잔액, `used_quota`, `request_count`, 요청 시각, HTTP 상태를 포함합니다.
* `Authorization` 헤더, `access_token` 같은 민감한 계정 필드는 로그에 남기지 않습니다.

## 관련 문서

* [잔액 조회 API FAQ: 깨진 출력, 401 오류, AccessToken과 API 키의 차이](https://docs.laozhang.ai/en/faq/balance-query-api.md)
* [잔액이 남았는데 실패하는 이유](https://docs.laozhang.ai/ko/faq/balance-insufficient.md)
* [호출 로그 확인과 활용](https://docs.laozhang.ai/en/faq/call-logs.md)
* [로그 조회 API: 호출 기록과 청구액 내보내기](https://docs.laozhang.ai/ko/api-capabilities/log-query.md)
* [토큰 관리 API: 코드로 API 키 발급·관리](https://docs.laozhang.ai/ko/api-capabilities/token-management.md)
* [과금과 가격](https://docs.laozhang.ai/ko/pricing.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.