积分余额

返回当前套餐、剩余和已用积分、计费状态以及账户标识。这是一个只读调用：它 不消耗积分，余额为零时也能正常使用。

⚠

2026 年 10 月 4 日的变更

自该日起，GET /quota 和 MCP 工具 get_quota_info 不再返回 staticCreditCost、realtimeCreditCost、overageEnabled、overagePriceInCents、staticRateLimitPerMinute 和 realtimeRateLimitPerMinute。每次查询的费用（标准查询默认 1 个积分，实时查询默认 1.5 个积分）和您套餐的超额用量规则请在控制台查看。默认限制为标准查询 30 次/分钟（每次批量提交计为 1 次），实时查询 5 次/分钟。定制套餐的限制可能不同，请向 CPFHub.io 支持团队确认。429 响应包含 Retry-After 请求头。见使用限制。

端点

GEThttps://api.cpfhub.io/quota

身份认证

在 x-api-key 请求头中发送 API 密钥。见身份认证。

参数

该端点没有路径参数或查询参数。

请求头

请求头	必填	说明
`x-api-key`	是	您的 CPFHub.io API 密钥

请求示例

curl "https://api.cpfhub.io/quota" \
  -H "x-api-key: $CPFHUB_API_KEY"

成功响应

HTTP 200 OK

JSON

{
  "success": true,
  "data": {
    "plan": "Básico",
    "remainingCredits": 750,
    "usedCredits": 250,
    "billingStatus": "active",
    "userId": "123e4567-e89b-12d3-a456-426614174000",
    "email": "usuario@exemplo.com"
  }
}

响应字段

字段	类型	说明
`success`	`boolean`	请求处理成功时为 `true`
`data.plan`	`string`	您的订阅套餐名称：`Grátis`、`Micro`、`Básico`、`Intermediário`、`Avançado` 或定制套餐。这些是 API 返回的葡萄牙语名称。`Grátis` 即免费版，网站上的 Pro 版按用量对应 Micro、Básico、Intermediário 或 Avançado（见使用限制）。没有订阅的账户返回 `"unknown"`
`data.remainingCredits`	`integer`	本周期额度中剩余的积分，向下取整。余额 1.4 显示为 `1`。不会出现负数：开通超额用量的套餐中，该值保持为 `0`，查询继续按超额用量计费
`data.usedCredits`	`number`	整个账户（所有密钥）在当前周期内已用的积分。付费套餐的周期为订阅的计费周期。免费版的周期为当前自然月（UTC）。可能带小数，开通超额用量的套餐中可能超过额度
`data.billingStatus`	`"active"` \| `"free"`	套餐资格：账户有可使用该套餐的订阅时为 `"active"`，包括免费版订阅以及 `past_due` 等状态。没有有效订阅时为 `"free"`，例如 `canceled`、`unpaid` 或 `incomplete_expired`。此时 `plan` 可能为 `"unknown"`
`data.userId`	`string`	用户唯一标识
`data.email`	`string`	账户关联的电子邮箱

✦

余额为零时仍可使用

积分余额归零后，GET /quota 仍会正常响应。这样您可以在自己的系统中查看余额，并在查询停止前采取措施。

ℹ

余额带小数

标准查询默认消耗 1 个积分，实时查询默认消耗 1.5 个积分，因此余额可能出现小数。由于 remainingCredits 向下取整，在判断余额是否足够下一次查询之前，请先在控制台查看您套餐的具体费用。

如何监控余额

当 remainingCredits 低于您设定的阈值（例如额度的 10%）时触发告警。
跟踪 usedCredits，统计本周期的总用量。
在控制台查看您套餐的具体费用和超额用量规则。
默认限制为标准查询 30 次/分钟（每次批量提交计为 1 次），实时查询 5 次/分钟。定制套餐的限制可能不同，请向 CPFHub.io 支持团队确认。超出限制时，API 返回 429 和 Retry-After 请求头。
余额未归零时，本周期额度等于 usedCredits + remainingCredits。

状态码

状态码	说明
`200 OK`	余额查询成功
`401 Unauthorized`	API 密钥缺失、无效或已停用
`403 Forbidden`	账户已停用或封禁
`500 Internal Server Error`	校验订阅时发生内部错误（`"Erro ao validar assinatura"`，订阅校验出错）
`503 Service Unavailable`	余额暂时不可用（`error: "usage_unavailable"`）。请几秒后重试。

这些错误中，error 为字符串。GET /quota 没有每分钟限制，也不消耗积分。

⚠

保护好您的 API 密钥

切勿在公开代码、代码仓库或直接在浏览器中运行的应用里暴露 API 密钥。请始终从后端或服务器调用 API。

完整的错误码和错误信息列表见错误码。

更新于 2026 年 10 月 3 日