计费日志开放API

透明计费 API

基本信息

• 基础路径：/api/transparency
• 鉴权方式：Authorization: Bearer sk-你的令牌
• 请求方法：GET
• 请求体：application/json（使用 JSON body，不使用 URL 查询参数）
• 响应格式：application/json
• 查询范围：仅查询当前令牌（token_id）的消费日志（type=2）

时间参数说明（北京时间）

• 支持字符串时间格式：yyyy-MM-dd HH:mm:ss
  • 例如：2026-03-25 15:25:44
• 推荐使用：
  • start_time
  • end_time
• 后端会按 Asia/Shanghai（北京时间）解析，并转换为 Unix 秒级时间戳查询数据库。
• 兼容字段（可选）：start_timestamp、end_timestamp
  • 当同时传了 start_time/end_time 时，优先使用字符串时间。

1) 查询聚合用量（按天 + 模型分组）

• 路径：GET /api/transparency/usage/summary

请求体参数

字段	类型	必填	说明
start_time	string	否	开始时间，北京时间，格式 yyyy-MM-dd HH:mm:ss
end_time	string	否	结束时间，北京时间，格式 yyyy-MM-dd HH:mm:ss
start_timestamp	int64	否	开始时间戳（秒），兼容字段
end_timestamp	int64	否	结束时间戳（秒），兼容字段
model_name	string	否	模型名筛选，支持 LIKE 模式
group	string	否	分组筛选
request_id	string	否	请求 ID 精确筛选
timezone_offset	int	否	按天分组时区偏移，默认 8

请求示例

curl --request GET "https://nxaiapp.com/api/transparency/usage/summary" \
  --header "Authorization: Bearer sk-xxxxxx" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "start_time": "2026-03-25 00:00:00",
    "end_time": "2026-03-25 23:59:59",
    "model_name": "",
    "group": "",
    "request_id": ""
  }'

响应示例

{
  "success": true,
  "message": "",
  "data": {
    "items": [
      {
        "day": "2026-03-25",
        "model_name": "gpt-4o-mini",
        "total_quota": 12.34,
        "input_tokens": 1823456,
        "output_tokens": 734221,
        "cache_hit_tokens": 120000,
        "cache_creation_tokens": 65000,
        "request_count": 423
      },
      {
        "day": "2026-03-25",
        "model_name": "claude-sonnet-4-6",
        "total_quota": 8.12,
        "input_tokens": 623411,
        "output_tokens": 201432,
        "cache_hit_tokens": 0,
        "cache_creation_tokens": 0,
        "request_count": 97
      }
    ]
  }
}

---

2) 查询用量明细（固定分页 1000）

• 路径：GET /api/transparency/usage/details
• 分页规则：
  • 每页固定 1000 条
  • 不支持自定义 page_size
  • 通过 page 翻页（从 1 开始）

请求体参数

字段	类型	必填	说明
start_time	string	否	开始时间，北京时间，格式 yyyy-MM-dd HH:mm:ss
end_time	string	否	结束时间，北京时间，格式 yyyy-MM-dd HH:mm:ss
start_timestamp	int64	否	开始时间戳（秒），兼容字段
end_timestamp	int64	否	结束时间戳（秒），兼容字段
model_name	string	否	模型名筛选，支持 LIKE 模式
group	string	否	分组筛选
request_id	string	否	请求 ID 精确筛选
page	int	否	页码，从 1 开始，默认 1

请求示例

curl --request GET "https://nxaiapp.com/api/transparency/usage/details" \
  --header "Authorization: Bearer sk-xxxxxx" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "start_time": "2026-03-25 00:00:00",
    "end_time": "2026-03-25 23:59:59",
    "model_name": "",
    "group": "",
    "request_id": "",
    "page": 1
  }'

响应示例

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 1000,
    "total": 3256,
    "items": [
      {
        "id": 1,
        "user_id": 12,
        "created_at": 1774423544,
        "type": 2,
        "content": "chat completion",
        "username": "demo_user",
        "token_name": "sdk-key",
        "model_name": "gpt-4o-mini",
        "quota": 14200,
        "prompt_tokens": 1567,
        "completion_tokens": 321,
        "use_time": 2,
        "is_stream": false,
        "channel": 3,
        "channel_name": "",
        "token_id": 88,
        "group": "default",
        "ip": "127.0.0.1",
        "request_id": "req_xxx",
        "other": "{\"cache_tokens\":120}"
      }
    ]
  }
}

---

错误响应示例

{
  "success": false,
  "message": "invalid json body"
}

备注

• 这两个接口为只读查询接口，依赖令牌鉴权中间件。
• 统计口径固定为消费日志（type=2）且仅当前令牌范围，不会返回其他令牌数据。