Open API 积分余额与消耗反馈

概述

Open API 提供两种积分反馈方式：

通过 /open-api/v1/credits-balance 主动查询账户 API 积分和监控积分余额。
在搜索接口、详情接口、监控接口等业务接口的标准响应体中，直接读取本次请求后的剩余积分和本次消耗积分。

这两种方式可用于前端余额展示、调用日志记录、余额监控和低余额告警。

余额查询接口

接口信息

请求方法: POST
接口地址: /open-api/v1/credits-balance
接口说明: 查询当前 API Key 对应账号的 API 积分和监控积分余额明细。
价格说明: 免费查询，不消耗 API 积分或监控积分。
限流说明: 全局约 1000 次/分钟；单个 API Key 约 60 次/分钟。超过限制时返回 444。

请求头:

Content-Type: application/json
Accept: application/json

请求参数

参数名	类型	必填	描述	示例
key	string	是	用户申请的外部 API 请求 key	"your_api_key_here"

请求示例

curl -X POST "https://www.pipispy.com/open-api/v1/credits-balance" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "key": "your_api_key_here"
  }'

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "total_api_credits": 10000,
    "remaining_api_credits": 8500,
    "purchased_api_credits": 10000,
    "used_api_credits": 1500,
    "total_monitor_credits": 5000,
    "remaining_monitor_credits": 4200,
    "purchased_monitor_credits": 5000,
    "used_monitor_credits": 800
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "success": true,
  "fail": false
}

data 字段说明

字段名	类型	描述
total_api_credits	Long	API 积分总数。发生扣除后又退还时，该值可能大于 `purchased_api_credits`
remaining_api_credits	Long	API 剩余积分数，用于数据搜索、详情等数据查询接口
purchased_api_credits	Long	API 已购买积分总数
used_api_credits	Long	API 已使用积分总数
total_monitor_credits	Long	广告/店铺监控积分总数。发生扣除后又退还时，该值可能大于 `purchased_monitor_credits`
remaining_monitor_credits	Long	广告/店铺监控剩余积分数
purchased_monitor_credits	Long	广告/店铺监控已购买积分总数
used_monitor_credits	Long	广告/店铺监控已使用积分总数

业务接口积分反馈

除余额查询接口外，搜索接口、详情接口、监控接口等业务接口的标准响应体会返回以下字段：

字段名	类型	描述
remaining_credits	Long	当前账户剩余可用积分。数据查询类接口返回 API 剩余积分；监控类接口返回监控剩余积分
consumed_credits	Long	本次请求实际消耗积分。免费访问、请求失败或未扣费时返回 0

业务接口响应示例

{
  "code": 200,
  "message": "success",
  "data": {},
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 20,
  "success": true,
  "fail": false
}

适用接口

接口类型	入口	积分含义
搜索接口	`/open-api/v1/data`	返回 API 剩余积分和本次搜索消耗
详情接口	`/open-api/v1/data`	返回 API 剩余积分和本次详情查询消耗
监控接口	`/open-api/v1/monitor/data`	返回监控剩余积分和本次监控操作消耗
监控任务接口	`/open-api/v1/ad-monitor-task/*`	返回监控剩余积分和本次监控任务操作消耗

错误码

错误码	描述
200	成功
400	请求参数错误，API Key 为空或请求体格式不正确
401	认证失败，API Key 无效或已过期
442	积分不足
444	请求过于频繁，已触发限流
500	服务器内部错误，请稍后重试

使用建议

需要展示完整余额明细时，调用 /open-api/v1/credits-balance。
每次业务调用后，可直接读取 remaining_credits 和 consumed_credits 记录本次消耗。
当 remaining_credits 低于内部阈值时，可触发邮件、飞书、钉钉、Slack 等告警。
如果账号未开通某类积分能力，对应余额字段可能返回 null。
建议余额监控任务按分钟级或更低频率调用，避免触发限流。