UniGateway 账户用量与计费 API#

本文档说明使用管理 API Key 查询同一账户下全部 API Key 的用量排名、计费明细和每日计费汇总。金额、币种、API Key 状态和实际可用数据均以接口实时返回为准。

概览#

准备工作#

本文接口需要管理 API Key，普通业务 API Key 不能调用。请前往 管理 API Key 控制台 创建或获取管理 API Key；完整 Key 仅在创建时显示一次。有关 API Key 的访问控制、轮换和安全管理，请参阅 账户与 API Key。

将管理 API Key 仅保存到服务端环境变量，不要写入浏览器代码、日志、公开仓库或导出文件：

export UNIGATEWAY_MANAGEMENT_KEY="<your-management-api-key>"

Windows PowerShell：

$env:UNIGATEWAY_MANAGEMENT_KEY = "<your-management-api-key>"

管理 API Key 可以读取账户下 API Key 的统计与计费数据。发生泄露时，应立即在控制台轮换 Key，并重新加载使用该 Key 的服务端配置。

通用约定#

所有接口均要求管理 API Key。普通业务 API Key 或无效的管理 API Key 会导致请求失败。响应不会包含普通 API Key 或管理 API Key 的完整值和哈希。

限流与缓存#

• 每个管理 API Key 每分钟最多可发起 60 次请求。
• usage-stats 使用独立的限流桶；billing 与 billing/daily-summary 共用一个每分钟 60 次的限流桶。
• 所有响应，包括错误响应，均包含 Cache-Control: no-store。

批量导出应在服务端执行。收到 429 Too Many Requests 后，应降低并发；响应包含 Retry-After 时按其指定的时间等待，否则使用带抖动的指数退避，然后以相同的筛选条件继续查询。

数组筛选参数#

apiKeyIds、apiKeyNames、modelTypes、modelNames、apiKeyStatuses、tokenTypes 和 currencies 均支持重复参数、逗号分隔或 JSON 数组。单个数组筛选最多接受 100 个值；省略参数或传入 [] 均表示不限制该维度。

apiKeyIds=key-1,key-2
apiKeyIds=key-1&apiKeyIds=key-2
apiKeyIds=["key-1","key-2"]

modelTypes 支持 claude、gemini、gpt、qwen、deepseek 和 other。apiKeyStatuses 支持 ACTIVE、INSUFFICIENT_BALANCE、USER_DISABLED 和 LIMIT_EXCEEDED；状态值不区分大小写，服务端会转换为大写。

API Key 用量排名#

GET /v1/account/api-keys/usage-stats

该接口按 Token 数或费用对账户下的 API Key 排名，并在每个 API Key 项中返回按相同排序规则排列的 model 明细。统计仅聚合状态为 SUCCESS 或 PARTIAL 的用量记录；已删除的 API Key 不会出现在结果中。

查询参数#

日期边界固定按 UTC+8 解释。date=2026-07-31 表示完整的 2026-07-31 UTC+8 日；纯日期 start_date 从该日 00:00:00+08:00 开始，end_date 到该日 23:59:59.999+08:00 结束。

严格 UTC 秒级时间只接受大写 Z，不接受时区偏移或小数秒。date 的时间值会选择该瞬间所在的完整 UTC+8 日；范围参数中的时间值是精确边界，且 end_date 包含该秒内的全部毫秒。响应中的 date_range 使用 UTC Z 时间戳表示实际范围。

请求示例#

以下请求按费用查询 2026 年 7 月的 API Key 用量排名：

curl -G 'https://unigateway.ai/v1/account/api-keys/usage-stats' \
  -H "Authorization: Bearer $UNIGATEWAY_MANAGEMENT_KEY" \
  --data-urlencode 'start_date=2026-07-01' \
  --data-urlencode 'end_date=2026-07-31' \
  --data-urlencode 'sort_by=cost' \
  --data-urlencode 'limit=50' \
  --data-urlencode 'offset=0'

响应示例#

{
  "date_range": {
    "start_date": "2026-06-30T16:00:00Z",
    "end_date": "2026-07-31T15:59:59Z",
    "time_zone": "UTC+8"
  },
  "sort_by": "cost",
  "currency": "USD",
  "items": [
    {
      "rank": 1,
      "id": "api-key-id-1",
      "name": "Production",
      "key_prefix": "sk-prod",
      "status": "ACTIVE",
      "request_count": "42",
      "total_tokens": "125000",
      "total_cost": "3.750000000000",
      "models": [
        {
          "rank": 1,
          "model_id": "model-id-1",
          "model_type": "gpt",
          "model_name": "gpt-5",
          "request_count": "42",
          "total_tokens": "125000",
          "total_cost": "3.750000000000"
        }
      ]
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0,
  "has_more": false
}

金额、请求数和 Token 数均以字符串返回。处理金额时应使用十进制定点类型，不要使用二进制浮点数。

账户计费明细#

GET /v1/account/billing

该接口按账单日、API Key、model、Token 类型和币种返回扁平计费明细。明细按账单日降序排列，再按 model 名称、Token 类型、币种和 API Key 进行稳定排序。

查询参数#

start_date / end_date 可替代 startDate / endDate。未使用 pageSize、pageNum 时，可使用兼容的 limit、offset 分页；未提供显式日期范围时，可使用 period=day|month|year 与对应的 date=YYYY/MM/DD|YYYY/MM|YYYY。

账单日固定使用 UTC+8，不提供可配置的账单时区。startDate 与 endDate 支持 YYYY-MM-DD，或带 Z、+/-HH:MM 时区的 RFC 3339 时间；RFC 3339 时间支持 1 至 3 位小数秒。没有小数秒的 endDate 包含最后一秒的全部毫秒；纯日期的日首和日末按 UTC+8 解释。

支持的 tokenTypes 为：

textInputTokens, textOutputTokens,
imageInputTokens, imageOutputTokens,
videoInputTokens, videoOutputTokens,
audioInputTokens, audioOutputTokens,
cacheCreationTokens5m, cacheCreationTokens1h, cacheTokens

Claude 的 1 小时缓存创建归入 cacheCreationTokens1h，不会归入表示缓存读取的 cacheTokens。没有明确 TTL 的缓存写入会归入 cacheCreationTokens5m。cacheWriteTokens 是内部缓存写入汇总字段，不是公开 tokenType。

请求示例#

以下请求查询 UTC+8 账单日下 2026 年 7 月的计费明细：

curl -G 'https://unigateway.ai/v1/account/billing' \
  -H "Authorization: Bearer $UNIGATEWAY_MANAGEMENT_KEY" \
  --data-urlencode 'startDate=2026-07-01T00:00:00+08:00' \
  --data-urlencode 'endDate=2026-07-31T23:59:59+08:00' \
  --data-urlencode 'pageSize=100' \
  --data-urlencode 'pageNum=1'

响应示例#

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 1,
    "provider": "UniGateway",
    "rows": [
      {
        "billMonth": "202607",
        "billDay": "2026-07-31",
        "billingDateTimezone": "utc+8",
        "account": "account-id-1",
        "apiKeyId": "api-key-id-1",
        "apiKeyName": "Production",
        "modelType": "claude",
        "modelName": "claude-opus-4-8",
        "tokenType": "cacheCreationTokens1h",
        "tokenCount": "5841",
        "tokenUnit": "piece",
        "currency": "USD",
        "subtotalBeforeTax": "0.05841000",
        "subtotalAfterDiscount": "0.05841000",
        "totalAmountAfterTax": "0.06322883",
        "entryType": "normal",
        "price": "0.00001000"
      }
    ]
  }
}

金额和派生单价均为 8 位小数的十进制字符串。totalAmountAfterTax 使用每条 usage_records 的 tax_rate_snapshot 计算；该字段是百分数，例如 8.25 表示 8.25%：

记录税后金额 = 记录折后金额 * (1 + tax_rate_snapshot / 100)

历史记录的快照为 null 时按 0% 处理。同一明细维度存在不同税率时，接口会先按每条记录计算税后金额，再聚合并保留 8 位小数，不会在聚合后的折后金额上套用单一税率。当前数据源只包含正常用量记录，因此每条明细固定返回 entryType: "normal"；退款和调账记录尚未接入该接口。

不要根据示例中的费用或单价推导当前 model 价格。应以 UniGateway 模型库 和接口实时返回为准。

每日计费汇总#

GET /v1/account/billing/daily-summary

该接口按 UTC+8 账单日、API Key 和币种汇总计费明细。筛选和日期解析规则与账户计费明细相同。

查询参数#

除以下差异外，接口支持与 GET /v1/account/billing 相同的查询参数和兼容形式：

apiKeyId 和 apiKeyName 可分别使用；同时提供时按 AND 匹配。需要一次查询多个值时，使用 apiKeyIds 和 apiKeyNames，格式遵循本文的数组筛选参数约定。

请求示例#

curl -G 'https://unigateway.ai/v1/account/billing/daily-summary' \
  -H "Authorization: Bearer $UNIGATEWAY_MANAGEMENT_KEY" \
  --data-urlencode 'startDate=2026-07-01' \
  --data-urlencode 'endDate=2026-07-31' \
  --data-urlencode 'apiKeyId=api-key-id-1' \
  --data-urlencode 'apiKeyName=Production' \
  --data-urlencode 'pageSize=31' \
  --data-urlencode 'pageNum=1'

响应示例#

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 1,
    "provider": "UniGateway",
    "rows": [
      {
        "billMonth": "202607",
        "billDay": "2026-07-31",
        "billingDateTimezone": "utc+8",
        "account": "account-id-1",
        "apiKeyId": "api-key-id-1",
        "apiKeyName": "Production",
        "currency": "USD",
        "subtotalBeforeTax": "25.68000000",
        "subtotalAfterDiscount": "20.54400000",
        "totalAmountAfterTax": "22.23888000",
        "entryCount": 3
      }
    ]
  }
}

相同筛选条件下，汇总金额等于计费明细接口返回的 8 位小数金额之和，包括每条明细独立计算后的 totalAmountAfterTax。两个接口均固定使用 UTC+8 账单日；对账时应固定日期范围、API Key 和币种筛选条件，再比较两类结果。

错误处理与频率限制#

GET /v1/account/api-keys/usage-stats 的错误响应格式如下：

{
  "error": {
    "code": "UnprocessableEntity",
    "message": "date must use YYYY-MM-DD or YYYY-MM-DDTHH:mm:ssZ UTC format",
    "param": null,
    "type": "BadRequest"
  }
}

该接口常见 HTTP 状态码为 400、401、429 和 500。检查日期格式、参数组合和管理 API Key 后再重试。

GET /v1/account/billing 与 GET /v1/account/billing/daily-summary 使用相同的错误结构：

{
  "code": 40003,
  "message": "The date range must not exceed 92 days",
  "data": null
}

调用方应同时检查 HTTP 状态码与 JSON 中的业务 code，不要依赖错误消息文本进行程序判断。

常见问题#

Q: 为什么使用普通 API Key 会返回 401？#

本文三个接口只接受管理 API Key。确认请求地址以 https://unigateway.ai 开头，并确认 Authorization 使用了当前有效的 mk- 前缀管理 API Key。将 UNIGATEWAY_MANAGEMENT_KEY 加载到服务端进程后，重新启动或重新加载该进程，再执行 GET /v1/account/api-keys/usage-stats?limit=1 验证。普通业务 API Key 不能调用账户级接口。

Q: 计费明细与每日汇总金额不一致，如何排查？#

先将两个请求的 startDate、endDate、apiKeyId、apiKeyName、apiKeyIds、apiKeyNames、modelTypes、modelNames、tokenTypes、currencies 和 apiKeyStatuses 设为完全相同的值。两个接口均固定按 UTC+8 账单日聚合。确认明细接口使用的范围不超过 92 天、汇总接口不超过 366 天，然后重新请求。每日汇总金额对应相同筛选条件下明细金额的净合计；不要跨币种或跨筛选条件直接比较。

Q: 如何避免导出大量计费数据时遗漏或重复？#

使用固定的日期范围和筛选条件，按 pageNum 从 1 开始依次拉取，并保留每次成功处理后的页码。遇到 429 时按 Retry-After 等待后，从最后成功页继续；不要在同一导出任务中改变 pageSize、日期范围或筛选条件。导出的 API Key ID、model、时间和费用属于敏感运营数据，应仅在受控环境中保存和处理。