用量 API

跟踪您的 API 使用情况、积分消耗，并获取 API 调用的详细分析。

GET/v1/usage

响应字段说明

/v1/usage响应格式: JSON

字段	类型	说明
`records[]`	object[]	分页后的调用明细。
`records[].id / request_id`	integer / string	记录 ID 和请求追踪 ID。
`records[].endpoint`	string	被调用的 API 路径。
`records[].response_status`	integer	HTTP 响应状态码。
`records[].response_time_ms`	integer	响应耗时（毫秒）。
`records[].credits_charged`	number	本次扣除积分。
`records[].upstream_service`	string \| null	实际调用的上游服务。
`records[].client_ip / error_code`	string \| null	客户端 IP 和错误码。
`records[].ctime`	string	调用时间（ISO 8601）。
`total / page / page_size`	integer	总记录数、当前页和每页数量。

/v1/usage/stats响应格式: JSON

字段	类型	说明
`stats[]`	object[]	按日期聚合的用量统计。
`stats[].date`	string	统计日期。
`stats[].total_requests`	integer	请求总数。
`stats[].successful_requests / failed_requests`	integer	成功和失败请求数。
`stats[].total_credits`	number	当日积分消耗。
`stats[].avg_response_time_ms`	number	平均响应耗时（毫秒）。
`period_start / period_end`	string	统计周期起止日期。

参数

参数	类型	必填	描述
`start_date`	string	可选	起始日期，格式为 YYYY-MM-DD
`end_date`	string	可选	结束日期，格式为 YYYY-MM-DD
`endpoint`	string	可选	按特定端点过滤

响应

Response

{
  "records": [
    {
      "date": "2025-01-15",
      "endpoint": "/v1/paper-search/google",
      "calls": 45,
      "credits_used": 45
    },
    {
      "date": "2025-01-15",
      "endpoint": "/v1/citation/verify",
      "calls": 12,
      "credits_used": 24
    }
  ],
  "total_credits_used": 69
}

示例

import requests

response = requests.get(
    "https://api.qinyanai.com/v1/usage",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={
        "start_date": "2025-01-01",
        "end_date": "2025-01-31",
    }
)

data = response.json()
print(f"Total credits used: {data['total_credits_used']}")