账户额度 API | 深旋科技文档中心

通过账户额度 API，您可以在提交任务前查询可用算力点数，或在任务结束后查看额度变化。接口返回当前凭据所属账号的额度信息，无需传入用户 ID。

查询账户额度

GET https://api.atomelody.com/v1/wallet/info
Authorization: Bearer <YOUR_API_KEY>

接口不需要请求体或查询参数。API Key 可在控制台的 API Key 凭据页面创建和管理。通用鉴权与响应格式见 API 接入指南。

调用示例

以下示例从环境变量 ATOMELODY_API_KEY 读取凭据。

curl --fail-with-body --silent --show-error \
  'https://api.atomelody.com/v1/wallet/info' \
  --header "Authorization: Bearer ${ATOMELODY_API_KEY}"

Python 示例仅使用标准库，无需安装第三方依赖。

响应示例

{
  "code": "OK",
  "message": "OK",
  "data": {
    "available": 9700,
    "frozen": 200,
    "balance": 9900,
    "cycle_quota": 10000,
    "next_reset_at": "2026-10-18T16:00:00Z",
    "status": 1
  }
}

响应字段

字段	类型	含义
`available`	int64	当前可用于创建任务的算力点数
`frozen`	int64	已被任务预占、尚未结算或释放的算力点数
`balance`	int64	当前总点数，等于 `available + frozen`
`cycle_quota`	int64	当前周期的额度上限，不代表剩余可用点数；以接口实际返回值为准
`next_reset_at`	string	下一个额度周期的开始时间，RFC 3339 格式；`Z` 表示 UTC 时间
`status`	int32	额度账户状态：`1` 正常、`2` 冻结、`3` 注销；不是推理任务状态

所有额度字段的单位均为算力点数，与任务询价的 estimated_cost 和创建任务的 billing_order.frozen 一致，无需乘除 100。示例中的 9700 表示 9,700 点。

如何使用查询结果

提交前检查额度：调用任务询价接口，将 estimated_cost 与本接口的 available 比较，同时检查额度账户 status 是否正常。额度查询和询价均不会为新任务预占点数，其他并发任务可能消耗额度，最终以创建任务的结果为准。
查看结算变化：任务结束后，可重新查询可用和冻结点数。结算或释放可能稍晚于任务状态更新，本接口反映的是整个账号的额度；查看单个任务的扣费应使用任务详情接口。
处理周期刷新：首次查询可能初始化额度，跨周期查询可能刷新正常账户的额度。当前周期从北京时间（UTC+8）每周一 00:00 开始；示例中的 2026-10-18T16:00:00Z 对应北京时间 10 月 19 日 00:00。被冻结或注销的额度账户不会因此恢复为正常状态。

周期刷新会保留尚未结算的冻结点数，不会把 cycle_quota 作为额外点数叠加到当前余额。详细规则见免费额度与周期重置规则。

错误处理

调用失败时，响应使用统一错误格式：

{
  "code": "UNAUTHORIZED",
  "message": "Authentication is required or has expired."
}

错误码	HTTP 状态码	处理方式
`UNAUTHORIZED`	401	检查 API Key 是否缺失、无效、过期或已撤销
`ACCOUNT_PENDING_DELETION`	403	账号处于待注销状态，需先在控制台处理账号状态
`INTERNAL_ERROR`	500	服务暂时异常，可稍后重试

根据 HTTP 状态码和 code 判断错误，不要依赖 message 文本。HTTP 200 且 code: "OK" 表示额度查询成功，是否可提交任务还需结合 data.status、可用点数及任务创建结果判断。