AI 大模型推理

  • AI 大模型推理 > API 文档 > 用量与账单 >大模型Token用量查询

    大模型Token用量查询

    最近更新时间: 2026-07-29 17:33:24

    接口概述

    /v3/stat/usage 接口用于查询当前账号的大模型 Token 用量数据,按模型、按计费项返回时间序列用量。

    主要能力:

    • 多粒度查询:支持天(day)与小时(hour)两种时间粒度。
    • 时区支持:通过 timezone 参数指定输出时间轴的时区,按所选时区返回每个时间桶。
    • 灵活鉴权:支持 API Key(sk- / tk-)与 AK/SK 两种鉴权方式。
      • API Key 鉴权:返回当前 Key 的用量。
      • AK/SK 鉴权:返回当前账号下所有 Key 的用量,按 API Key 分组,并返回每个 Key 的名称。
    • 日期格式兼容:AK/SK 鉴权下,时间参数另支持 v2 的 YYYY-MM-DD 日期格式(仅 day 粒度)。

    接口信息

    • 接口路径: GET /v3/stat/usage
    • 接口描述: 查询用户用量数据,支持天粒度和小时粒度查询每一个模型的用量
    • 鉴权方式: 支持用 OAuth2.0 规范的无状态 API Key、或用当前账号的 AK/SK 签名 来鉴权
    • 数据返回:
      • 采用 API Key 鉴权 时,返回当前 Key 的 Token 用量。
      • 采用 AK/SK 签名 时(即管理员模式),返回当前账号下所有 Key 的用量,并按 API Key 分组(每个分组带 name)。
    • 请求频率限制: 同一 IP 每秒可请求 5 次
    • 接入端点: https://api.qnaigc.com

    请求参数

    Query 参数

    参数名 类型 必填 描述 示例值
    granularity string 时间粒度,支持 day(天)或 hour(小时);兼容别名 g day
    start string 开始时间,RFC3339 格式(AK/SK 鉴权另兼容 YYYY-MM-DD 2024-01-01T00:00:00+08:00
    end string 结束时间,RFC3339 格式(AK/SK 鉴权另兼容 YYYY-MM-DD 2024-01-31T23:59:59+08:00
    timezone string 输出时间轴时区,IANA 时区名称,默认 Asia/Shanghai UTC
    api_key string API Key。API Key 鉴权按请求头中的 Key 查询;AK/SK 鉴权返回该账号全部 Key,此参数一般无需传入 sk-xxx

    时间格式说明

    • 标准格式: RFC3339 格式,如 2024-01-01T10:30:00+08:00
    • v2 兼容格式: AK/SK 鉴权下,start / end 也支持 v2 的 YYYY-MM-DD 格式(仅 day 粒度生效,此时返回 v2 的扁平数组结构,见响应格式

    时间范围限制

    以下限制适用于 RFC3339 格式的查询(v2 的 YYYY-MM-DD 格式不受此限制)。

    • 天粒度查询: 时间范围不能超过 1 个月(31 天)
    • 小时粒度查询: 时间范围不能超过 7 天

    timezone 参数说明

    • 默认值为 Asia/Shanghai
    • 支持任意合法的 IANA 时区名称(如 UTCAmerica/Los_Angeles),接口按该时区返回每个时间桶的数值。
    • 传入 Local 或无法识别的时区名称会返回 400 错误。

    鉴权方式

    1. API Key 鉴权

    在请求头中添加:

    Authorization: Bearer sk-xxxxxxxxxxxxxxxxx
    

    说明:

    • Token 须以 sk-(正式 Key)或 tk-(临时 Key)开头
    • 仅返回当前 API Key 下的用量信息

    2. AK/SK 鉴权

    使用七牛云标准的 AK/SK 鉴权方式,签名实现请参考 AK/SK 签名实现参考

    Authorization: Qiniu <AccessKey>:<EncodedSign>
    

    说明:

    • 需要按照七牛云鉴权规范构造签名
    • 返回该账号下所有 API Key 的用量,按 API Key 分组(每组带 name
    • 支持传统的 YYYY-MM-DD 日期格式参数(仅 day 粒度)

    响应格式

    接口统一响应体外壳:

    { "status": true,  "data": ... }      // 成功
    { "status": false, "error": "..." }   // 失败
    

    data 的具体结构随鉴权方式时间格式不同而不同,分为以下三种情况。

    1. API Key 鉴权(Bearer)

    返回模型用量数组,每个元素为一个模型的用量明细。

    {
      "status": true,
      "data": [
        {
          "id": "model_name",
          "name": "模型显示名称",
          "items": [
            {
              "name": "输入 Token",
              "unit": "kToken",
              "total": 1000,
              "categories": [
                {
                  "name": "输入 Token",
                  "values": [
                    { "time": "2024-01-01T00:00:00Z", "value": 100 },
                    { "time": "2024-01-02T00:00:00Z", "value": 150 }
                  ]
                }
              ]
            },
            {
              "name": "输出 Token",
              "unit": "kToken",
              "total": 500,
              "categories": [
                {
                  "name": "输出 Token",
                  "values": [
                    { "time": "2024-01-01T00:00:00Z", "value": 50 },
                    { "time": "2024-01-02T00:00:00Z", "value": 75 }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
    
    字段 类型 描述
    status boolean 请求状态,true 表示成功
    data array 用量数据列表
    data[].id string 模型标识符
    data[].name string 模型显示名称
    data[].items array 计费项列表
    data[].items[].name string 计费项名称
    data[].items[].unit string 计费单位
    data[].items[].total number 总量
    data[].items[].categories array 分类数据
    data[].items[].categories[].name string 分类名称
    data[].items[].categories[].values array 时间序列数据
    data[].items[].categories[].values[].time string 时间点
    data[].items[].categories[].values[].value number 用量值

    2. AK/SK 鉴权(RFC3339 时间)

    返回按 API Key 分组的列表,每个元素包含一个 API Key 的用量及其名称。

    {
      "status": true,
      "data": [
        {
          "api_key": "sk-xx*****xxxxx",
          "name": "我的测试 Key",
          "models": [
            {
              "id": "model_name",
              "name": "模型显示名称",
              "items": [
                {
                  "name": "输入 Token",
                  "unit": "kToken",
                  "total": 1000,
                  "categories": [
                    {
                      "name": "输入 Token",
                      "values": [
                        { "time": "2024-01-01T00:00:00Z", "value": 100 }
                      ]
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
    
    字段 类型 描述
    status boolean 请求状态,true 表示成功
    data array 按 API Key 分组的用量列表
    data[].api_key string API Key(脱敏后,格式 前5位*****后5位
    data[].name string 该 API Key 的名称
    data[].models array 该 API Key 的模型用量列表,结构同 API Key 鉴权data[]
    data[].models[].id string 模型标识符
    data[].models[].name string 模型显示名称
    data[].models[].items array 计费项列表(结构同上)

    AK/SK v2 兼容格式(YYYY-MM-DD)

    当 AK/SK 鉴权、granularity=day、且 start / end 为 v2 的 YYYY-MM-DD 格式时,返回v2 的扁平数组结构(无按 API Key 分组、无 categories 层):

    {
      "status": true,
      "data": [
        {
          "id": "model_name",
          "name": "模型显示名称",
          "items": [
            {
              "name": "输入 Token",
              "values": [
                { "value": 100, "time": "2024-01-01T00:00:00Z" }
              ],
              "unit": "kToken",
              "total": 1000
            }
          ]
        }
      ]
    }
    

    该格式为兼容 v2 而保留,不受时间范围上限与 timezone 参数约束,建议新接入方使用 RFC3339 格式。

    错误响应

    { "status": false, "error": "错误信息描述" }
    

    错误码说明

    HTTP 状态码 错误类型 描述
    400 Bad Request 请求参数错误(时间格式 / 时间范围 / 时区 / 粒度等)
    401 Unauthorized 鉴权失败
    500 Internal Server Error 服务器内部错误

    常见错误信息

    • "start parameter parse error, the format should be YYYY-MM-DDTHH:MM:SS±HH:MM(2024-01-01T10:30:00+08:00), but received ...": 开始时间格式错误
    • "end parameter parse error, ...": 结束时间格式错误
    • "end must be after start": 结束时间必须不早于开始时间
    • "当 granularity=day 时,时间范围不能超过 1 个月(31 天)": 天粒度查询时间范围超限
    • "当 granularity=hour 时,时间范围不能超过 7 天": 小时粒度查询时间范围超限
    • "无效的 timezone,需使用 IANA 时区名称,例如 UTC": timezone 取值为 Local 或无法识别
    • "invalid ak/sk sign": AK/SK 签名验证失败
    • API Key 无效或格式错误:返回 401

    使用示例

    示例 1: API Key 查询天粒度数据

    curl -X GET "https://api.qnaigc.com/v3/stat/usage?granularity=day&start=2024-01-01T00:00:00%2B08:00&end=2024-01-31T23:59:59%2B08:00" \
      -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxx"
    

    示例 2: AK/SK 查询小时粒度数据

    curl -X GET "https://api.qnaigc.com/v3/stat/usage?granularity=hour&start=2024-01-01T00:00:00%2B08:00&end=2024-01-07T23:59:59%2B08:00" \
      -H "Authorization: Qiniu <AccessKey>:<EncodedSign>"
    

    示例 3: 指定 UTC 时区输出

    curl -X GET "https://api.qnaigc.com/v3/stat/usage?granularity=day&start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z&timezone=UTC" \
      -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxx"
    

    示例 4: AK/SK v2 兼容日期格式(仅 day 粒度)

    curl -X GET "https://api.qnaigc.com/v3/stat/usage?granularity=day&start=2024-01-01&end=2024-01-31" \
      -H "Authorization: Qiniu <AccessKey>:<EncodedSign>"
    

    注意事项

    1. 时区处理: 建议使用 +08:00 时区或显式传入 timezone=Asia/Shanghai,避免时区转换问题;需要其他时区时通过 timezone 参数指定。
    2. 数据时效: 当天数据可能存在延迟,建议查询昨天及之前的数据。
    3. 数据口径: 返回值为同一模型各来源用量的合并值。
    4. 限流保护: 接口有频率限制(同一 IP 每秒 5 次),请合理控制请求频率。

    AK/SK 签名实现参考

    const crypto = require('crypto')
    
    /**
     * URL 安全的 Base64 编码
     * @param {Buffer} buffer - 要编码的数据
     * @returns {string} - URL 安全的 Base64 字符串
     */
    function urlSafeBase64Encode(buffer) {
      return buffer.toString('base64')
        .replace(/\+/g, '-')
        .replace(/\//g, '_');
    }
    
    /**
     * 生成待签名的原始字符串
     * @param {Object} options - 请求参数
     * @param {string} options.method - HTTP 方法(大小写敏感)
     * @param {string} options.path - 请求路径
     * @param {string} [options.query] - 查询参数(不包含 ?)
     * @param {string} options.host - 主机名
     * @param {string} [options.contentType] - Content-Type
     * @param {Object} [options.headers] - X-Qiniu-* 开头的自定义头(可选)
     * @param {string} [options.body] - 请求体(可选)
     * @returns {string} - 待签名的字符串
     */
    function generateSigningString(options) {
      const { method, path, query, host, contentType, headers, body } = options
    
      // 1. Method + 空格 + Path
      let signingStr = method.toUpperCase()
    
      // 2. 添加 Path 和 Query
      signingStr += ' ' + path
      if (query) {
        signingStr += '?' + query
      }
    
      // 3. 添加 Host
      signingStr += '\nHost: ' + host
    
      // 4. 添加 Content-Type(如果有)
      if (contentType) {
        signingStr += '\nContent-Type: ' + contentType
      }
    
      // 5. 添加 X-Qiniu-* 头部(如果有)
      if (headers) {
        // 按 key 的 ASCII 排序
        const sortedKeys = Object.keys(headers).sort()
        sortedKeys.forEach(key => {
          if (key.toLowerCase().startsWith('x-qiniu-')) {
            // 格式化 key:首字母和 - 后的字母大写,其余小写
            const formattedKey = key.split('-')
              .map((part, index) => {
                return part.charAt(0).toUpperCase() + part.slice(1).toLowerCase()
              })
              .join('-')
            signingStr += '\n' + formattedKey + ': ' + headers[key]
          }
        })
      }
    
      // 6. 添加两个连续换行符
      signingStr += '\n\n'
    
      // 7. 添加 Body(如果有且 Content-Type 不是 application/octet-stream)
      if (body && contentType && contentType !== 'application/octet-stream') {
        signingStr += body
      }
    
      return signingStr
    }
    
    /**
     * 生成七牛云管理凭证(Access Token)
     * @param {string} accessKey - 七牛云 AccessKey
     * @param {string} secretKey - 七牛云 SecretKey
     * @param {Object} requestOptions - 请求参数(同 generateSigningString)
     * @returns {string} - 管理凭证字符串
     */
    function generateAccessToken(accessKey, secretKey, requestOptions) {
      // 1. 生成待签名的原始字符串
      const signingStr = generateSigningString(requestOptions);
    
      // 2. 使用 HMAC-SHA1 计算签名
      const hmac = crypto.createHmac('sha1', secretKey);
      hmac.update(signingStr);
      const sign = hmac.digest();
    
      // 3. 对签名进行 URL 安全的 Base64 编码
      const encodedSign = urlSafeBase64Encode(sign);
    
      // 4. 将 AccessKey 和 encodedSign 用冒号连接
      const accessToken = accessKey + ':' + encodedSign;
    
      return accessToken;
    }
    
    // 示例用法
    const accessKey = '你的 AK'
    const secretKey = '你的 SK'
    const requestOptions = {
      method: 'GET',
      path: '/v3/stat/usage?granularity=day&start=2025-10-01T00:00:00%2B08:00&end=2025-10-31T23:59:59%2B08:00',
      host: 'api.qnaigc.com',
      contentType: '',
      body: ''
    }
    const accessToken = generateAccessToken(accessKey, secretKey, requestOptions)
    console.log('生成的 Access Token:', accessToken)
    
    以上内容是否对您有帮助?