管理与平台 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": "错误码"
  }
}

详见错误码参考。

两套接口的关系

历史上先有 /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。

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

查询生成记录

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 是同一份数据，只是字段名为驼峰；新接入按需要的命名任选其一。

管理与平台 API ​

通用约定 ​

两套接口的关系 ​

Platform API ​

速率限制 ​

余额 ​

订阅信息 ​

单条请求详情 ​

时序统计 ​

模型排行榜 ​

供应商份额 ​

供应商健康度 ​

组织调用统计 ​

模型用量 ​

Management API（旧版兼容） ​

查询额度 ​

查询用量 ​

查询定价 ​

查询生成记录 ​

查询统计 ​

管理与平台 API

通用约定

两套接口的关系

Platform API

速率限制

余额

订阅信息

单条请求详情

时序统计

模型排行榜

供应商份额

供应商健康度

组织调用统计

模型用量

Management API（旧版兼容）

查询额度

查询用量

查询定价

查询生成记录

查询统计