用量与计费

/v1/usage 用于让当前 API Key 查询自己的余额、额度和用量统计。

查询用量

接口说明：

项目	值
Method	`GET`
Path	`/v1/usage`
认证	`Authorization: Bearer YOUR_API_KEY`

Query 参数：

参数	类型	必填	说明
`days`	integer	否	日用量统计窗口，允许 `1-90`。
`timezone`	string	否	日统计使用的时区。
`start_date`	string	否	模型统计开始日期，格式 `YYYY-MM-DD`。
`end_date`	string	否	模型统计结束日期，格式 `YYYY-MM-DD`。

请求示例：

bash

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'

响应模式

接口会根据 API Key 配置返回不同模式。

`mode`	说明
`quota_limited`	API Key 配置了总额度或速率限制。
`unrestricted`	API Key 未配置 Key 级额度，返回订阅或钱包余额视图。

额度受限响应示例：

json

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

钱包余额响应示例：

json

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

订阅分组响应示例：

json

{
  "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"
  }
}

生图计费字段

异步生图成功后会写入用量记录。关键字段含义如下：

字段	含义
`inbound_endpoint`	调用方入口，异步生图通常为 `/v1/images/tasks`。
`upstream_endpoint`	实际上游入口。OpenAI 异步生图通常为 `/v1/images/generations`；Gemini 异步生图为 `/v1beta/models/{model}:generateContent`。
`request_id`	异步生图任务 ID。
`image_count`	生成图片数量。
`image_size`	计费用输出尺寸。
`billing_mode`	计费模式，生图通常为 image 计费。
`actual_cost`	实际扣除余额。

异步任务的预扣金额不是最终账单。任务成功后按实际成本结算；实际费用低于预扣会退回差额，高于预扣会补扣差额，余额可能变为负数。失败、超时或取消不会写入用量记录，也不会扣费，会释放全部预扣额度。

任务状态先完成成功结算，再写入用量记录；如果用量记录写入异常，任务仍保持 succeeded 状态。

用量与计费 ​

查询用量 ​

响应模式 ​

生图计费字段 ​

用量与计费

查询用量

响应模式

生图计费字段