Balance API: /api/user/self via access token

Item	Details
Endpoint	`GET https://api.laozhang.ai/api/user/self`
Authentication	A personal access token (starts with `nap_`) with the `profile:read` scope, in the `Authorization` header
Main fields	Remaining quota, used quota, request count, and account group
Conversion	Divide `quota` by 500,000 to get the remaining balance in US dollars; see Convert quota to US dollars

The legacy system AccessToken stopped working on November 9, 2026.

Requests that still use it get HTTP 401 with code set to ACCESS_TOKEN_LEGACY_RETIRED.
Create a personal access token and swap it into your script. The endpoint, request format, and response fields are unchanged.

Create a personal access token

A personal access token isn’t the API key you use for model requests. It calls account endpoints and can do only what its scopes allow. Keep it on your server in an environment variable or a secrets manager, and never ship it to a browser or client app.

Open personal access tokens

Sign in to the console, open personal settings, go to Security & Access → Personal access tokens, and create a new token.

Name it and pick scopes

Use a name that says what the token is for, such as “balance alerts”. Grant only the scopes your script needs:

Balance: profile:read
Call log export as well: add usage:read (see the log query API)
API key management: api_key:read, api_key:write, or api_key:reveal as needed (see the token management API)

You can also set an IP allowlist and an expiry date.

Copy the token

The token starts with nap_ and is shown only once. Copy it right away and store it securely.

Changing your password, 2FA, or passkeys revokes every personal access token.

Create new tokens afterwards and update every service that used the old ones.
An account can have up to 20 personal access tokens.
Do not put a token in source code, browser apps, logs, screenshots, or support tickets. When you ask support for help, send the request time, HTTP status, the code from the response, and a redacted command.

Endpoint

GET https://api.laozhang.ai/api/user/self
Authorization: <your personal access token>

The request takes no query parameters or body, and the response is JSON.

Pass the token itself as the Authorization value, as the examples below do; a Bearer prefix also works.
Accept: application/json and Content-Type: application/json are optional.
With cURL, add --compressed so that the response is decompressed.

Response

A successful request returns:

{
  "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": []
  }
}

Field	Type	Description
`success`	Boolean	Whether the request succeeded.
`message`	String or null	Error message; usually `null` on success.
`data.quota`	Integer	Remaining quota; use it for alert thresholds.
`data.used_quota`	Integer	Quota used so far.
`data.request_count`	Integer	Total number of requests.
`data.group`	String	Account group.
`data.username`	String	Username.
`data.display_name`	String	Display name.
`data.ModelFixedPrice`	Array	Model price data; ignore it if you only need the balance.
`data.access_token`	String	Sensitive; if it is returned, never write it to logs.

The response can include other fields, depending on the account. Read only the fields you need, and let your parser ignore unknown ones.

Convert quota to US dollars

quota and used_quota are returned in quota units, not dollars. 500,000 quota units are about 1 USD.

Value	Formula	Sample response
Remaining balance	`quota ÷ 500,000`	`24997909 ÷ 500,000` ≈ 50.00 USD
Amount used	`used_quota ÷ 500,000`	`10027091 ÷ 500,000` ≈ 20.05 USD
Remaining plus used	`(quota + used_quota) ÷ 500,000`	≈ 70.05 USD

Use this conversion for display. What a request actually costs depends on the model price, your token group, and the charge shown in call logs. For alerts, store the raw quota together with the converted amount so that you keep full precision.

Code examples

Set the personal access token in your terminal once, replacing the placeholder. Scripts that used the legacy AccessToken only need the new value in this variable:

export LAOZHANG_ACCESS_TOKEN="YOUR_PERSONAL_ACCESS_TOKEN"

cURL
cURL with 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"

Without --compressed, the terminal can show garbled output, and jq can report 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
  }'

Install requests with python -m pip install requests, then run:

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"Balance query failed: {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 decompresses gzip responses automatically.

Save this code in an .mjs file and run it with Node.js 18 or later:

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(`Balance query failed: HTTP ${response.status}`);
}

const payload = await response.json();
if (!payload.success) {
  throw new Error(`Balance query failed: ${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,
});

Errors

401 Unauthorized

Authentication failures return HTTP 401, and the code field says why. A request that still uses the legacy token returns:

{
  "code": "ACCESS_TOKEN_LEGACY_RETIRED",
  "message": "Legacy management tokens have been retired. Create a personal access token in your account settings instead.",
  "success": false
}

`code`	Cause and fix
`AUTH_REQUIRED`	No `Authorization` header, or `LAOZHANG_ACCESS_TOKEN` isn’t set
`ACCESS_TOKEN_LEGACY_RETIRED`	The credential isn’t a personal access token: it’s the legacy AccessToken or a model API key. Create a personal access token and use it instead
`ACCESS_TOKEN_INVALID`	The token is incomplete, deleted, or revoked; create a new one
`ACCESS_TOKEN_EXPIRED`	The token has expired; create a new one
`ACCESS_TOKEN_SCOPE_DENIED`	The token lacks `profile:read`; create one with that scope
`ACCESS_TOKEN_IP_INVALID`	The request came from an IP outside the token’s allowlist

Fix a 401 from the balance API walks through the common causes. Check success in your script instead of relying on the status code alone.

Garbled output or a jq error

If cURL prints garbled characters or jq reports Invalid numeric literal, the compressed response was not decoded. Add --compressed to the cURL command.

Monitoring recommendations

To get warned before your balance runs low, run a scheduled check against this endpoint. This script exits with status 1 when the remaining balance falls below a threshold:

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"Balance ${remaining_usd:.2f} is below ${THRESHOLD_USD}")
    sys.exit(1)

Run it from cron or your monitoring system every 10–30 minutes and send a notification on a non-zero exit, for example:

*/10 * * * * /usr/bin/python3 /opt/check_balance.py || /opt/notify.sh

Cron doesn’t load your shell environment, so provide LAOZHANG_ACCESS_TOKEN in the script or crontab. When you set it up:

Store LAOZHANG_ACCESS_TOKEN in an environment variable or a secrets manager.
Set a request timeout, such as 10 seconds.
Poll at a modest interval; balance alerts rarely need per-second checks.
Include quota, the converted balance, used_quota, request_count, the request time, and the HTTP status in alerts.
Never log the Authorization header, access_token, or other sensitive account fields.
Changing your password, 2FA, or passkeys revokes the token and the check starts returning 401, so replace the token after any security change.

Get started

Image Generation & Editing APIs

Video Generation APIs

Text APIs

Multimodal & Audio APIs

Balance API: /api/user/self via access token

Create a personal access token

Endpoint

Response

Convert quota to US dollars

Code examples

Errors

401 Unauthorized

Garbled output or a jq error

Monitoring recommendations

​Create a personal access token

​Endpoint

​Response

​Convert quota to US dollars

​Code examples

​Errors

​401 Unauthorized

​Garbled output or a jq error

​Monitoring recommendations

​Related documentation

Create a personal access token

Endpoint

Response

Convert quota to US dollars

Code examples

Errors

401 Unauthorized

Garbled output or a jq error

Monitoring recommendations

Related documentation