用量汇总

用量汇总（L1）提供按日 / 月级别的用量与成本汇总，供调用方做成本趋势分析。宁享Token 提供多种协议兼容端点。

所有端点使用 TokenAuth 鉴权，按 API Key 隔离。

Base URL

/  （部署域名，例如 https://your-domain.com）

nxtoken 原生：用量汇总

GET/v1/billing/usage

获取当前 API Key 的用量汇总。支持日级 / 月级粒度，可按 modality（文本/图像/音频）、billing_unit（token/秒/张）、metrics 维度聚合。

Bearer Token

请求参数

请求参数

参数	类型	必填	默认值	描述
start_date	string	是	-	起始日期，格式 YYYY-MM-DD
end_date	string	是	-	结束日期，格式 YYYY-MM-DD
granularity	string	否	day	汇总粒度，day 或 month
modality	string	否	-	模态过滤：text / image / audio
billing_unit	string	否	-	计费单位过滤：token / second / piece
metrics	string	否	-	指标维度：cost / usage / all

请求示例

curl "/v1/billing/usage?start_date=2025-01-01&end_date=2025-01-31&granularity=day" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

resp = requests.get(
    "/v1/billing/usage",
    params={
        "start_date": "2025-01-01",
        "end_date": "2025-01-31",
        "granularity": "day",
    },
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(resp.json())

响应示例

成功响应

{
  "granularity": "day",
  "start_date": "2025-01-01",
  "end_date": "2025-01-31",
  "items": [
    {
      "date": "2025-01-01",
      "modality": "text",
      "billing_unit": "token",
      "usage": 125000,
      "cost": 1.25,
      "currency": "CNY"
    }
  ],
  "total_cost": 35.8,
  "currency": "CNY"
}

OpenAI 兼容：用量汇总

GET/v1/dashboard/billing/usage

OpenAI 兼容端点，返回结构含 daily_costs，与 OpenAI Billing Usage API 一致。

Bearer Token

请求参数

请求参数

参数	类型	必填	默认值	描述
start_date	string	是	-	起始日期，格式 YYYY-MM-DD
end_date	string	是	-	结束日期，格式 YYYY-MM-DD

请求示例

curl "/v1/dashboard/billing/usage?start_date=2025-01-01&end_date=2025-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"

响应示例

成功响应

{
  "object": "list",
  "total_usage": 12.5,
  "total_usage_micro": 12500000,
  "daily_costs": [
    {
      "date": "2025-01-01",
      "line_items": [
        {
          "name": "glm-5.2",
          "cost": 1.25,
          "currency": "CNY"
        }
      ]
    }
  ]
}

total_usage 沿用 OpenAI 协议口径（美元美分），不做单位改写；精确到微元的人民币总额见 total_usage_micro。

OpenAI costs：成本列表

GET/v1/costs

OpenAI Costs API 兼容端点，返回成本行项列表，支持分页。

Bearer Token

请求参数

请求参数

参数	类型	必填	默认值	描述
start_date	string	否	近 30 天	起始日期，格式 YYYY-MM-DD
end_date	string	否	今天	结束日期，格式 YYYY-MM-DD

请求示例

curl "/v1/costs?start_date=2025-01-01&end_date=2025-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"

响应示例

成功响应

{
  "object": "list",
  "data": [
    {
      "object": "cost.bucket",
      "start_time": "2025-01-01T00:00:00+08:00",
      "end_time": "2025-01-02T00:00:00+08:00",
      "results": [
        {
          "object": "cost.result",
          "cost": {
            "currency": "USD",
            "cost_value": 0.18
          },
          "line_item": {
            "model": "glm-5.2",
            "cost_micro": 1250000
          }
        }
      ]
    }
  ],
  "has_more": false,
  "next_cursor": null
}

data 为按日分桶（cost.bucket），每个桶内 results 才是逐条成本行（cost.result）。 cost.currency 恒为 "USD"、cost_value 为该协议口径下的美元值；精确到微元的人民币金额在 line_item.cost_micro（1 元 = 1,000,000 微）。

Anthropic 兼容：消息用量报告

GET/v1/organizations/usage_report/messages

Anthropic 兼容端点，返回 Anthropic 原生 usage report 结构。

Bearer Token

请求参数

请求参数

参数	类型	必填	默认值	描述
start	string	是	-	起始日期，格式 YYYY-MM-DD
end	string	是	-	结束日期，格式 YYYY-MM-DD
model	string	否	-	按模型名过滤

请求示例

curl "/v1/organizations/usage_report/messages?start=2025-01-01&end=2025-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"

响应示例

成功响应

{
  "data": [
    {
      "model": "glm-5.2",
      "start": "2025-01-01",
      "end": "2025-01-02",
      "input_tokens": 100000,
      "output_tokens": 25000,
      "cost": 1.25,
      "currency": "CNY"
    }
  ],
  "has_more": false
}

相关文档

• 对账 API 概览
• 余额查询
• 逐条明细
• 厂商兼容端点总表

协议兼容说明：/v1/costs 与 /v1/dashboard/billing/usage 为 OpenAI 协议兼容接口，响应中的 currency: "USD"（以及 total_usage 的美元美分单位）为协议固定口径。实际计费一律以人民币（CNY）结算，人民币微元金额见 line_item.cost_micro / total_usage_micro，账单明细与扣费均以 CNY 为准。