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://api.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"
  }
}

Task API Billing

Async tasks do not currently write traditional usage_logs, so they do not appear as individual entries in the traditional usage detail. Task charges update the balance directly. Use GET /v1/tasks/{id} or the admin task detail to inspect estimated_cost, actual_cost, and billing_detail.

The estimated amount is reserved at submission. Successful tasks settle using the configured image size matrix, video duration, or per-request price. If actual cost is lower than the estimate, the difference is returned; if it is higher, the difference is deducted. Failed, timed-out, and canceled tasks release the reservation and are not charged. Token usage returned by an upstream video provider does not currently affect billing.

Errors

Status	Cause
400	Query parameters such as date range or timezone are invalid.
401	API key is missing or invalid.
403	The API key is inactive or not allowed to query usage.
500	Usage statistics could not be loaded.