---
url: https://limapi.com/docs/guide/management.md
---
# 管理与平台 API

本页是「用量自助查询」这一族接口的完整参考：用 API Key 就能查自己租户的余额、速率、单条请求和各类统计，不需要登录控制台。

## 通用约定

**Base URL**：`https://limapi.com`

**认证**：所有接口都要带 API Key，只返回该 Key 所属租户（`/usage/org-stats` 见下文，可覆盖同组织成员）的数据。

```
Authorization: Bearer sk-xxx
```

也可以用 `x-api-key` 或 `x-goog-api-key` 请求头。缺 Key 或 Key 无效返回 `403 access_denied`。

**金额单位**：元（¥），`cost` / `total_cost` / `balance` 都是元，最多 6 位小数；统计接口里的 `total_cost` 统一四舍五入到 4 位。`currency` 字段返回 `"CNY"`。
**金额口径是折后实收**：所有 `cost` / `total_cost` / `/management/usage` 的 `cost` / `/management/generation` 的 `usage` 都取租户实际被扣的费用（命中折扣时低于标价），与你账单上的数字一致；模型页展示的标价不出现在这些接口里。

**`provider` 是模型厂商，不是内部渠道**：`/usage/market-share`、`/usage/provider-health`、`/usage/model-stats`、`/generations/{id}` 与 `/management/generation` 的 `provider` 一律按模型厂商（如 `月之暗面`、`Moonshot AI`）聚合或展示，不会下发我方内部供应渠道的标识。

**时间窗**：带 `days` 参数的接口取值范围 1～90，超出会被静默收敛到边界（不报错）。`/usage/leaderboard` 的 `limit` 同理收敛到 1～50。

**数据延迟**：统计类接口读聚合表 `request_logs`，最新数据有约 1 分钟延迟；`/generations/{id}` 读 Buffer 表，刚发生的请求可即时查到。

**只统计「已解析到模型」的请求**：`/usage/leaderboard`、`/usage/market-share`、`/usage/provider-health`、`/usage/model-stats` 四条会排除鉴权阶段、限流阶段、余额预检阶段就被拒绝的请求（这些请求没有模型名，否则报表里会凭空多出空模型和 0% 成功的行）。因此这四条的请求数之和通常**小于** `/management/usage` 的全量 `requests`。`/usage/org-stats` 不做这个排除。

**查询失败不报 5xx**：统计接口内部查询异常时返回 `200`，响应体退化为 `{"tenant_id": "...", "days": 7, "data": []}`——注意字段名会从正常的 `leaderboard` / `providers` / `models` 变成 `data`。客户端解析时建议对 `data` 兜底。

**错误格式**：

```json
{
  "error": {
    "message": "错误描述信息",
    "type": "错误类型",
    "code": "错误码"
  }
}
```

详见[错误码参考](/guide/errors)。

## 两套接口的关系

历史上先有 `/api/v1/management/*`，后有 `/api/v1/usage/*` 这一族，两者有三对重叠：

| 旧 | 现行 | 差异 |
|---|---|---|
| `GET /api/v1/management/payg/balance` | `GET /api/v1/balance` | 两者 `balance` 口径不同：旧版＝组织额度＋个人额度，新版只给个人额度；需要额度拆分用旧版 |
| `GET /api/v1/management/generation?id=xxx` | `GET /api/v1/generations/{generationId}` | 字段新旧版不同；新版多 token 明细、首包、错误原文，且只查 Buffer 表（刚发生的请求即时可查），旧版查聚合表有约 1 分钟延迟。建议用新版 |
| `GET /api/v1/management/usage` | `GET /api/v1/usage/org-stats` | 旧版只有三个总量数字，新版有每日/成员明细 |

新接入一律用 `/api/v1/usage/*` + `/api/v1/balance` + `/api/v1/subscription` + `/api/v1/generations/{id}`。

***

# Platform API

## 速率限制

当前 Key 的限额，以及本租户全部启用 Key 的限额与额度消耗。

```
GET /api/v1/usage/rate-limits
```

**请求参数**：无

**响应字段**

| 字段 | 类型 | 说明 |
|---|---|---|
| `tenant_id` | string | 租户 ID |
| `current_key` | object | 本次调用所用 Key 的限额 |
| `current_key.rpm_limit` | int | 每分钟请求数上限 |
| `current_key.tpm_limit` | int | 每分钟 token 上限 |
| `current_key.credit_limit` | number | 该 Key 额度上限，`-1` 表示无限制 |
| `all_keys` | array | 本租户所有启用中的 Key |
| `all_keys[].key_prefix` | string | Key 前缀（不含密钥本体） |
| `all_keys[].key_type` | string | Key 类型 |
| `all_keys[].key_name` | string | Key 名称，未命名为空串 |
| `all_keys[].rpm_limit` | int | 每分钟请求数上限 |
| `all_keys[].tpm_limit` | int | 每分钟 token 上限 |
| `all_keys[].credit_limit` | number | 额度上限，未设置按 `-1`（无限制） |
| `all_keys[].credit_used` | number | 已消耗额度 |

**示例**

```json
{
  "tenant_id": "t_1a2b3c",
  "current_key": { "rpm_limit": 600, "tpm_limit": 1000000, "credit_limit": -1 },
  "all_keys": [
    {
      "key_prefix": "sk-abcd",
      "key_type": "standard",
      "key_name": "生产环境",
      "rpm_limit": 600,
      "tpm_limit": 1000000,
      "credit_limit": -1,
      "credit_used": 0
    }
  ]
}
```

## 余额

```
GET /api/v1/balance
```

**请求参数**：无

**响应字段**

| 字段 | 类型 | 说明 |
|---|---|---|
| `tenant_id` | string | 租户 ID |
| `balance` | number | 个人 PAYG 池余额（元），**不含组织分配额度**；要看可花总额用 `/management/payg/balance` |
| `currency` | string | 固定返回 `"CNY"` |
| `key_type` | string | 本次调用 Key 的类型 |

**示例**

```json
{ "tenant_id": "t_1a2b3c", "balance": 128.402316, "currency": "CNY", "key_type": "PAYG" }
```

## 订阅信息

```
GET /api/v1/subscription
```

**请求参数**：无

**响应字段**

| 字段 | 类型 | 说明 |
|---|---|---|
| `tenant_id` | string | 租户 ID |
| `plan` | string | 套餐标识，当前平台按量计费，未单独配置套餐时返回 `FREE` |
| `expires_at` | string | null | 套餐到期时间 |
| `quota_remaining` | int | 配额窗口剩余量；当前平台不发放套餐配额，恒为 `0` |
| `quota_reset_at` | string | null | 配额重置时间 |
| `is_active` | boolean | 租户是否启用 |

> 本平台以按量（PAYG）计费为主，本接口主要用于确认账号状态。额度请看[余额](#余额)。

**示例**

```json
{
  "tenant_id": "t_1a2b3c",
  "plan": "FREE",
  "expires_at": null,
  "quota_remaining": 0,
  "quota_reset_at": null,
  "is_active": true
}
```

## 单条请求详情

按 `generation_id` 查一次请求的完整记录。

```
GET /api/v1/generations/{generationId}
```

**路径参数**

| 参数 | 类型 | 说明 |
|---|---|---|
| `generationId` | string | 响应里返回的 `generation_id` |

**响应字段**

| 字段 | 类型 | 说明 |
|---|---|---|
| `generation_id` | string | 请求唯一标识 |
| `tenant_id` | string | 租户 ID |
| `key_type` | string | 调用所用 Key 类型 |
| `requested_model` | string | 你请求的模型 ID |
| `actual_model` | string | 实际服务的模型；对外只展示平台公开模型名，降级到其他公开模型时这里就是那个模型 |
| `provider` | string | 模型厂商 |
| `api` | string | 入口协议，如 `chat.completions`、`responses`、`messages` |
| `stream` | int | 是否流式，`1` / `0` |
| `prompt_tokens` | int | 输入 token |
| `completion_tokens` | int | 输出 token |
| `total_tokens` | int | 总 token |
| `reasoning_tokens` | int | 思考链 token |
| `latency_ms` | int | 端到端总耗时 |
| `first_token_latency_ms` | int | 首包耗时 |
| `cost` | number | 本次实收（元） |
| `status_code` | int | HTTP 状态码 |
| `error_type` | string | 错误类型，成功为空 |
| `error_message` | string | 错误说明，已做对外可读化处理，成功为空 |
| `finish_reason` | string | 结束原因：`stop` / `length` / … |
| `created_at` | string | 请求时间 |

**错误**：查不到、或该请求不属于本租户 → `404 not_found`。

**示例**

```json
{
  "generation_id": "gen-3f2a1b9c8d7e6f5a",
  "tenant_id": "t_1a2b3c",
  "key_type": "standard",
  "requested_model": "kimi-k3",
  "actual_model": "kimi-k3",
  "provider": "Moonshot AI",
  "api": "chat.completions",
  "stream": 1,
  "prompt_tokens": 1820,
  "completion_tokens": 640,
  "total_tokens": 2460,
  "reasoning_tokens": 210,
  "latency_ms": 9420,
  "first_token_latency_ms": 1830,
  "cost": 0.0312,
  "status_code": 200,
  "error_type": "",
  "error_message": "",
  "finish_reason": "stop",
  "created_at": "2026-10-04 15:22:41"
}
```

## 时序统计

按小时或按天聚合 token 与费用。

```
GET /api/v1/usage/timeseries?granularity=day&days=7
```

**查询参数**

| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `granularity` | string | `day` | `day` 或 `hour`；其他值按 `day` 处理 |
| `days` | int | `7` | 回看天数，1～90 |

**响应字段**：`data[]` 每行

| 字段 | 类型 | 说明 |
|---|---|---|
| `time_bucket` | string | 时间桶，`day` 粒度为 `2026-10-04`，`hour` 粒度为 `2026-10-04 15:00` |
| `prompt_tokens` | int | 输入 token 合计 |
| `completion_tokens` | int | 输出 token 合计 |
| `total_tokens` | int | 总 token 合计 |
| `total_cost` | number | 费用合计（元，4 位小数） |
| `request_count` | int | 请求数 |

**示例**

```json
{
  "tenant_id": "t_1a2b3c",
  "granularity": "day",
  "days": 7,
  "data": [
    {
      "time_bucket": "2026-10-03",
      "prompt_tokens": 1820000,
      "completion_tokens": 640000,
      "total_tokens": 2460000,
      "total_cost": 31.24,
      "request_count": 1204
    }
  ]
}
```

## 模型排行榜

按请求数降序返回模型列表。

```
GET /api/v1/usage/leaderboard?days=7&limit=10
```

**查询参数**

| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `days` | int | `7` | 回看天数，1～90 |
| `limit` | int | `10` | 返回条数，1～50 |

排序固定为 `request_count DESC`，暂不支持按 token / 费用排序。

**响应字段**：`leaderboard[]` 每行

| 字段 | 类型 | 说明 |
|---|---|---|
| `model` | string | 模型 ID |
| `request_count` | int | 请求数 |
| `total_tokens` | int | 总 token |
| `total_cost` | number | 折后实收（元） |
| `avg_latency_ms` | int | 平均耗时 |

**示例**

```json
{
  "tenant_id": "t_1a2b3c",
  "days": 7,
  "leaderboard": [
    {
      "model": "kimi-k3",
      "request_count": 4210,
      "total_tokens": 18600000,
      "total_cost": 246.13,
      "avg_latency_ms": 9400
    }
  ]
}
```

## 供应商份额

各供应方的请求分布与占比。

```
GET /api/v1/usage/market-share?days=7
```

**查询参数**

| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `days` | int | `7` | 回看天数，1～90 |

**响应字段**：`providers[]` 每行

| 字段 | 类型 | 说明 |
|---|---|---|
| `provider` | string | 模型厂商（同一厂商的多个模型合并成一行） |
| `request_count` | int | 请求数 |
| `total_tokens` | int | 总 token |
| `total_cost` | number | 折后实收（元） |
| `avg_latency_ms` | int | 平均耗时 |
| `share_pct` | number | 请求数占比百分数，2 位小数；窗口内无请求时该字段不下发 |

按 `request_count DESC` 排序。

**示例**

```json
{
  "tenant_id": "t_1a2b3c",
  "days": 7,
  "providers": [
    {
      "provider": "月之暗面",
      "request_count": 4210,
      "total_tokens": 18600000,
      "total_cost": 246.13,
      "avg_latency_ms": 9400,
      "share_pct": 68.42
    }
  ]
}
```

## 供应商健康度

按供应方聚合成功率与延迟分位，用来判断错误率或延迟集中在哪一路。

```
GET /api/v1/usage/provider-health?days=7
```

**查询参数**

| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `days` | int | `7` | 回看天数，1～90 |

**响应字段**

| 字段 | 类型 | 说明 |
|---|---|---|
| `summary.total_requests` | int | 窗口内总请求数 |
| `summary.success_count` | int | 成功数（`status_code` 在 200～399） |
| `summary.error_count` | int | 失败数（`status_code >= 400`） |
| `summary.overall_success_rate` | number | 全局成功率百分数 |
| `providers[]` | array | 按供应方明细，`request_count DESC` 排序 |
| `providers[].provider` | string | 模型厂商 |
| `providers[].request_count` | int | 请求数 |
| `providers[].success_count` | int | 成功数 |
| `providers[].error_count` | int | 失败数 |
| `providers[].success_rate` | number | 该供应方成功率百分数，2 位小数 |
| `providers[].avg_latency_ms` | int | 平均耗时（含失败请求） |
| `providers[].avg_success_latency_ms` | int | 平均耗时（仅成功请求） |
| `providers[].p50_latency_ms` | int | 耗时中位数 |
| `providers[].p99_latency_ms` | int | 耗时 P99 |
| `providers[].total_tokens` | int | 总 token |
| `providers[].total_cost` | number | 折后实收（元） |

**示例**

```json
{
  "tenant_id": "t_1a2b3c",
  "days": 7,
  "summary": {
    "total_requests": 6150,
    "success_count": 6098,
    "error_count": 52,
    "overall_success_rate": 99.15
  },
  "providers": [
    {
      "provider": "月之暗面",
      "request_count": 4210,
      "success_count": 4180,
      "error_count": 30,
      "success_rate": 99.29,
      "avg_latency_ms": 9400,
      "avg_success_latency_ms": 9210,
      "p50_latency_ms": 6100,
      "p99_latency_ms": 41200,
      "total_tokens": 18600000,
      "total_cost": 246.13
    }
  ]
}
```

## 组织调用统计

组织管理员视角：整个组织的汇总 + 每日明细 + 成员明细。

```
GET /api/v1/usage/org-stats
GET /api/v1/usage/org-stats?days=30
```

**查询参数**

| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `days` | int | 不传＝全部历史 | 回看天数；不收敛上限，全量查询请显式传 `days` |

统计范围：调用 Key 所属租户若已加入组织，则覆盖该组织下全部启用成员；未加入组织则只统计自己。

**响应字段**

| 字段 | 类型 | 说明 |
|---|---|---|
| `tenant_id` | string | 本次调用的租户 ID |
| `org_id` | string | 组织 ID，无组织为空串 |
| `days` | int | string | 回显；不传时为 `"all"` |
| `member_count` | int | 纳入统计的成员租户数 |
| `summary.request_count` | int | 总请求数（含被鉴权/限流拒绝的请求） |
| `summary.total_tokens` | int | 总 token |
| `summary.total_cost` | number | 折后实收合计（元） |
| `summary.error_count` | int | `status_code >= 400` 的请求数 |
| `daily[]` | array | 每日明细，按日期升序 |
| `daily[].date` | string | 日期 |
| `daily[].request_count` | int | 请求数 |
| `daily[].total_tokens` | int | 总 token |
| `daily[].total_cost` | number | 折后实收（元） |
| `members[]` | array | 成员明细，按请求数降序 |
| `members[].tenant_id` | string | 成员租户 ID |
| `members[].request_count` | int | 请求数 |
| `members[].total_tokens` | int | 总 token |
| `members[].total_cost` | number | 折后实收（元） |

三段查询各自独立容错：某一段失败只让那一段落空（`summary` 归零、`daily` / `members` 为空数组），不影响其余两段。

**示例**

```json
{
  "tenant_id": "t_1a2b3c",
  "org_id": "org_7x8y",
  "days": 30,
  "member_count": 4,
  "summary": { "request_count": 6150, "total_tokens": 18600000, "total_cost": 246.13, "error_count": 52 },
  "daily": [
    { "date": "2026-10-03", "request_count": 1204, "total_tokens": 2460000, "total_cost": 31.24 }
  ],
  "members": [
    { "tenant_id": "t_1a2b3c", "request_count": 4210, "total_tokens": 12800000, "total_cost": 168.4 }
  ]
}
```

## 模型用量

每个模型（同一模型分供应方时逐条列出）的 token 明细、费用、延迟与错误数。

```
GET /api/v1/usage/model-stats?days=7
```

**查询参数**

| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `days` | int | `7` | 回看天数，1～90 |

**响应字段**

| 字段 | 类型 | 说明 |
|---|---|---|
| `summary.total_requests` | int | 请求数 |
| `summary.total_tokens` | int | 总 token |
| `summary.total_cost` | number | 折后实收合计（元） |
| `models[]` | array | 明细，按 `total_tokens DESC` 排序 |
| `models[].model` | string | 模型 ID |
| `models[].provider` | string | 模型厂商 |
| `models[].request_count` | int | 请求数 |
| `models[].prompt_tokens` | int | 输入 token |
| `models[].completion_tokens` | int | 输出 token |
| `models[].total_tokens` | int | 总 token |
| `models[].total_cost` | number | 折后实收（元） |
| `models[].avg_latency_ms` | int | 平均耗时 |
| `models[].avg_first_token_ms` | int | 平均首包耗时 |
| `models[].error_count` | int | `status_code >= 400` 请求数 |

**示例**

```json
{
  "tenant_id": "t_1a2b3c",
  "days": 7,
  "summary": { "total_requests": 6150, "total_tokens": 18600000, "total_cost": 246.13 },
  "models": [
    {
      "model": "kimi-k3",
      "provider": "月之暗面",
      "request_count": 4210,
      "prompt_tokens": 12000000,
      "completion_tokens": 6600000,
      "total_tokens": 18600000,
      "total_cost": 246.13,
      "avg_latency_ms": 9400,
      "avg_first_token_ms": 1830,
      "error_count": 30
    }
  ]
}
```

***

# Management API（旧版兼容）

以下接口为早期版本，仍可用；新接入请用上面的 Platform API。

## 查询额度

```
GET /api/v1/management/payg/balance
```

响应：`tenantId`、`balance`（组织＋个人合计，元）、`orgBalance`（组织分配额度）、`personalBalance`（个人额度）、`currency`（固定 `CNY`）。

`balance` = `orgBalance` + `personalBalance`；个人额度只对未归属组织的租户 Key 生效。

## 查询用量

```
GET /api/v1/management/usage
```

响应：`tenantId`、`requests`、`tokens`、`cost`（折后实收，元）。窗口固定为近 90 天，不可配置；需要每日或成员明细用 `/api/v1/usage/org-stats`。

## 查询定价

```
GET /api/v1/management/pricing
```

响应：`{ "models": { "<模型ID>": { "input_price_per_1m": n, "output_price_per_1m": n } } }`，单位元 / 百万 token。

> ⚠️ 这份表是内置兜底价，不是权威价目表：模型实际单价以[模型列表](/guide/models)与控制台模型详情为准，且不含你所在租户的折扣。请以账单核对实际扣费。

## 查询生成记录

```
GET /api/v1/management/generation?id=xxx
```

响应：`api`、`generationId`、`model`、`provider`（模型厂商）、`generationTime`、`latency`、`nativeTokens{prompt_tokens,completion_tokens,total_tokens}`、`usage`（本次折后实收，元）。

> 优先用 [`GET /api/v1/generations/{generationId}`](#单条请求详情)：字段更全（token 明细、首包耗时、错误原文），且读实时表，刚发生的请求即时可查；本接口读聚合表，有约 1 分钟延迟。

## 查询统计

```
GET /api/v1/management/stats
```

响应：`totalRequests`、`totalTokens`、`totalCost`（本租户近 90 天，`totalCost` 为折后实收）。

> 与 [`/api/v1/management/usage`](#查询用量) 是同一份数据，只是字段名为驼峰；新接入按需要的命名任选其一。