API 积分
了解 Rivya API 如何使用账户积分、余额检查、预留积分、失败退款和积分排查。
最近审阅于 2026年11月5日
Rivya API 使用和 Studio 相同的账户积分钱包。
使用 GET /api/v1/credits 读取 API Key 所属账户的当前余额。
API 与工作台共用账户余额,Key 没有独立钱包;积分可来自符合条件的注册赠送、订阅、积分包或任务退回,各自发放与有效期规则仍适用,见积分与计费。
Endpoint
GET https://rivya.ai/api/v1/credits必需 header:
Authorization: Bearer rvya_sk_...Key 需要 credits:read 或 *。创建、权限、有效期和撤销见API 密钥鉴权。密钥只应保存在服务端,不要放在浏览器代码或公开仓库。
在服务端环境已设置 RIVYA_API_KEY 后,可执行以下请求:
curl https://rivya.ai/api/v1/credits \
-H "Authorization: Bearer $RIVYA_API_KEY"响应
{
"current_credits": 123
}123 是示例余额。current_credits 只是已存余额快照,不列出每笔发放、有效期、预留或结算。没有余额记录时返回 0,数据库失败返回错误而不是零余额。余额会随使用、过期处理、发放与退回变化,扣除预留时会检查过期。查询不会预留积分,也不保证后续请求可开始。余额为正也不代表每个模型可调用;先检查模型发现中的 api_status 和 Key 权限。
生成计费
新生成请求需能覆盖初始预留;Rivya 在发送给模型服务前检查并扣除。金额取决于模型、输入和设置。reserved_credits 是该任务的初始预留,不是模型统一价格。final_credits 是当前记录值,排队或处理中也可等于预留,并非一定为零。
必须读取 settlement_status:PENDING、RESERVED 表示未最终结算;SETTLED 表示已结算,有效用量低于预留时退还差额;RECONCILIATION_REQUIRED 表示用量缺失、无效或超出预留等待核对,保留预留,不自动追加超额。任务可以成功但积分仍未结算。扣除预留后的余额已反映该扣除,不要再从后续 current_credits 减一次预留。
聊天计费
POST /api/v1/chat/completions 使用同一账户余额。新轮次会在联系模型服务前扣除初始预留,响应提供 credits.reserved、credits.final 和 credits.settlement_status。
usage 在可用时提供 token 数量;token 数量不等于扣费积分,应读取积分和结算字段。已返回的回复仍可能是 RECONCILIATION_REQUIRED,表示积分尚未结算。
HTTP 请求失败本身不能证明轮次未保存或已退还积分。再次发送付费轮次前,检查已有会话并遵循聊天 API及错误与限制。
失败任务
任务失败与积分退回是两件事。对已有任务同时检查 status 和 settlement_status:REFUNDED 表示预留积分已退回账户;结算值 FAILED 表示未记录退回,和任务 status: failed 不同,本身也不证明已扣费。
等待过久或查询失败不代表生成失败、也不证明已退还。保留原任务 ID,参阅生成状态及失败任务与积分退回。任务积分退回不等于订阅或积分包付款退款。
常见积分错误
insufficient_credits(402):余额无法覆盖预留,重试前核对余额、所需积分和有效期;查询余额不要求正余额。api_key_invalid(401):Key 无效;缺失、过期和撤销分别用api_key_missing、api_key_expired、api_key_revoked。api_scope_denied(403):缺少权限,余额接口要求credits:read或*。public_api_disabled(503):API 关闭或鉴权不可用,不返回账户余额。internal_error(500):请求未能完成;余额查询失败不能当作余额为0。
这些错误可能来自余额检查或付费请求,并非都由余额端点返回。错误格式、请求 ID 和重试条件见API 错误与限制。
