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

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

AccessToken은 모델 요청에 쓰는 API 키와 다르며, 계정에 대한 권한이 더 넓습니다.

서버의 환경 변수나 시크릿 매니저에 보관하세요.
브라우저나 클라이언트 앱에 넣지 마세요.

AccessToken 발급

계정 설정 열기

콘솔에 로그인한 뒤 계정 설정을 엽니다.

시스템 토큰 창 열기

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

AccessToken 복사

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

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

엔드포인트

GET https://api.laozhang.ai/api/user/self
Authorization: <your AccessToken>

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

응답

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

{
  "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을 한 번 설정합니다. 자리 표시자는 실제 값으로 바꾸세요.

export LAOZHANG_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

cURL
cURL + jq
Python
Node.js

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 오류를 낼 수 있습니다.

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
  }'

python -m pip install requests로 requests를 설치한 뒤 실행합니다.

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 응답을 자동으로 해제합니다.

아래 코드를 .mjs 파일로 저장하고 Node.js 18 이상에서 실행합니다.

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

{
  "success": false,
  "message": "Unauthorized"
}

Authorization 헤더가 비어 있거나, AccessToken이 일부만 입력되었거나 더 이상 유효하지 않거나, AccessToken 대신 모델 API 키를 보낸 경우입니다. 원인별 해결 방법은 잔액 조회 API의 401 오류 해결에서 확인하세요. 상태 코드와 본문을 함께 보세요.

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

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

403 Forbidden

{
  "success": false,
  "message": "Forbidden"
}

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

깨진 출력 또는 jq 오류

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

모니터링 권장 사항

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

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이 아니면 알림을 보내세요. 예를 들면 다음과 같습니다.

*/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

비디오 생성 API

텍스트 API

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

AccessToken 발급

엔드포인트

응답

quota를 달러로 환산

코드 예제

오류

401 Unauthorized

403 Forbidden

깨진 출력 또는 jq 오류

모니터링 권장 사항

관련 문서

​AccessToken 발급

​엔드포인트

​응답

​quota를 달러로 환산

​코드 예제

​오류

​401 Unauthorized

​403 Forbidden

​깨진 출력 또는 jq 오류

​모니터링 권장 사항

​관련 문서

AccessToken 발급

엔드포인트

응답

quota를 달러로 환산

코드 예제

오류

401 Unauthorized

403 Forbidden

깨진 출력 또는 jq 오류

모니터링 권장 사항

관련 문서