Usage and Billing

/v1/usage lets the current API key inspect its balance, quota, and usage statistics.

Query Usage

Interface details:

Item	Value
Method	GET
Path	/v1/usage
Authentication	Authorization: Bearer YOUR_API_KEY

Query parameters:

Parameter	Type	Required	Description
days	integer	No	Daily usage window. Allowed range is 1-90.
timezone	string	No	Time zone used for daily statistics.
start_date	string	No	Model statistics start date in YYYY-MM-DD format.
end_date	string	No	Model statistics end date in YYYY-MM-DD format.

Request example:

curl 'https://llmapi.site/v1/usage?days=7&start_date=2026-05-01&end_date=2026-05-29&timezone=Asia%2FShanghai' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response Modes

The endpoint returns different modes depending on API key configuration.

mode	Description
quota_limited	API key has a quota or rate limit configured.
unrestricted	API key has no key-level quota and returns a subscription or wallet balance view.

Quota-limited response example:

{
  "mode": "quota_limited",
  "isValid": true,
  "status": "active",
  "quota": {
    "limit": 100,
    "used": 12.34,
    "remaining": 87.66,
    "unit": "USD"
  },
  "remaining": 87.66,
  "unit": "USD",
  "usage": {
    "today": {
      "requests": 42,
      "input_tokens": 12000,
      "output_tokens": 3400,
      "total_tokens": 15400,
      "cost": 0.82,
      "actual_cost": 0.82
    },
    "total": {
      "requests": 320,
      "input_tokens": 80000,
      "output_tokens": 25000,
      "total_tokens": 105000,
      "cost": 12.34,
      "actual_cost": 12.34
    },
    "average_duration_ms": 1820,
    "rpm": 3,
    "tpm": 1200
  },
  "daily_usage": [],
  "model_stats": []
}

Wallet balance response example:

{
  "mode": "unrestricted",
  "isValid": true,
  "planName": "钱包余额",
  "remaining": 42.5,
  "unit": "USD",
  "balance": 42.5,
  "usage": {
    "today": {
      "requests": 10,
      "total_tokens": 3200,
      "actual_cost": 0.21
    }
  }
}

Subscription response example:

{
  "mode": "unrestricted",
  "isValid": true,
  "planName": "Pro Plan",
  "unit": "USD",
  "remaining": 15.2,
  "subscription": {
    "daily_usage_usd": 1.2,
    "weekly_usage_usd": 4.5,
    "monthly_usage_usd": 18.3,
    "daily_limit_usd": 5,
    "weekly_limit_usd": 30,
    "monthly_limit_usd": 100,
    "expires_at": "2026-06-30T00:00:00Z"
  }
}

Image Billing Fields

Async image tasks write usage records after successful generation. Important fields:

Field	Meaning
inbound_endpoint	Caller-facing endpoint, usually /v1/images/tasks for async images.
upstream_endpoint	Actual upstream endpoint. OpenAI async image tasks usually use /v1/images/generations; Gemini async image tasks use /v1beta/models/{model}:generateContent.
request_id	Async image task ID.
image_count	Number of generated images.
image_size	Output size used for billing.
billing_mode	Billing mode, usually image billing for image generation.
actual_cost	Actual balance deducted.

The reserved amount for an async task is not the final bill. Successful tasks settle actual cost; if actual cost is lower than the reservation, the difference is returned, and if it is higher, the difference is deducted and the user balance may become negative. Failed, timed-out, and canceled tasks do not write usage records or charge the user; they release the full reservation.

Task success is committed before the usage record is written. If usage-record writing fails, the task still remains in succeeded state.