开放平台余额

接口描述

查询当前开放平台账户的可用点数余额，可用于设置余额预警。

数据说明：余额数据可能存在短暂延迟，请以接口实际返回为准。

请求 URL

• 方法：GET
• 路径：/open/v1/credit/balance

点数消耗

• 消耗点数：0

前置条件

• 使用有效的 API Key。
• 请求头携带 X-API-KEY、X-TIMESTAMP、X-SIGN。
• GET 请求没有请求体，签名原文为 X-TIMESTAMP 与空字符串拼接。

请求参数

无路径参数、查询参数或请求体。

请求头

请求头	必需	描述
X-API-KEY	是	您的 API Key
X-TIMESTAMP	是	当前 13 位毫秒时间戳，与服务端时间差不得超过 5 分钟
X-SIGN	是	使用应用 Secret 对 X-TIMESTAMP + 空请求体 生成的 HMAC-SHA256 签名

完整签名规则请参考「身份验证 / 调用全流程」。

响应字段

仅展示 data 对象的字段结构：

字段	类型	实际返回类型	描述
balance	long	string	当前可用总点数
buyBalance	long	string	购买获得的可用点数
giveBalance	long	string	赠送获得的可用点数
recentExpireTime	date	number / null	最近一批点数的过期时间，毫秒时间戳；无可用点数时为 null
recentBalance	long	string	最近一批将过期的点数；无可用点数时为 "0"

字段关系

• balance = buyBalance + giveBalance。
• recentExpireTime 和 recentBalance 用于判断最近一批点数的到期时间与数量。
• 无可用点数时，balance、buyBalance、giveBalance、recentBalance 均为 "0"，recentExpireTime 为 null。

cURL 示例（Linux/macOS）

curl --location --request GET 'https://api.valuescan.ai/api/open/v1/credit/balance' \
--header 'X-API-KEY: your-api-key' \
--header 'X-TIMESTAMP: 1785110400000' \
--header 'X-SIGN: xxxxx' \
--header 'Accept: application/json'

cURL 示例（Windows CMD）

curl --location --request GET "https://api.valuescan.ai/api/open/v1/credit/balance" ^
--header "X-API-KEY: your-api-key" ^
--header "X-TIMESTAMP: 1785110400000" ^
--header "X-SIGN: xxxxx" ^
--header "Accept: application/json"

成功响应示例

{
    "code": 200,
    "message": "success",
    "data": {
        "balance": "15000",
        "recentExpireTime": 1785513600000,
        "recentBalance": "3000",
        "buyBalance": "10000",
        "giveBalance": "5000"
    },
    "requestId": "xxx-xxx-xxx"
}

无有效余额响应示例

{
    "code": 200,
    "message": "success",
    "data": {
        "balance": "0",
        "recentExpireTime": null,
        "recentBalance": "0",
        "buyBalance": "0",
        "giveBalance": "0"
    },
    "requestId": "xxx-xxx-xxx"
}

常见错误

错误码	说明
20001	缺少 API Key
20012	请求时间戳已过期
20021	签名验证失败
60001	调用频率超限
70002	当前用户的 OpenAPI 访问已被禁用