计费与额度

XAI XAPI 的计费系统旨在提供透明、灵活且可控的消费管理体验。

信用额度 (CreditBalance)

每个用户的余额不是一个单一的数值，而是一个由多张“信用额度卡”组成的数组，即 CreditBalance。

每张卡片包含以下信息：

• amount: 这张卡的初始面额。
• balance: 这张卡当前的剩余余额。
• granted_at: 这张卡的授予（充值）时间。
• expires_at: 这张卡的过期时间。
• reference: 备注信息，如 "Initial Funding" 或 "Recharge"。

消费扣款规则： 系统会优先从最早过期的、且有余额的卡片开始扣款。这种 "先进先出" 的策略能最大化您的资金使用效率。

额度卡合并策略： 为防止额度卡片数量过多导致管理混乱，系统会自动执行合并策略：

• 当一个用户的卡片超过12张时，系统会尝试合并同一天过期的卡片。
• 如果卡片数仍然过多，会进一步合并过期时间相近（如60天内）的卡片。
• 合并后新卡的过期时间将取被合并卡片中的最晚过期时间。

费率 (Rates) 与 价格因子 (Factor)

最终的消费金额由一个简单的公式决定：

最终消费 = 基础消费 × 用户费率 (Rates) × 价格因子 (Factor)

• 基础消费: 这是根据官方模型价卡计算出的原始费用。例如，gpt-4o 的 prompt_tokens 消费。
• 用户费率 (Rates): 这是父账户为子账户设置的计费倍率。
  • 默认值为 1，表示按标准费率计费。
  • 如果父账户为子账户设置 Rates = 1.2，那么该子账户的所有消费都会乘以 1.2。父账户可以借此获得 20% 的利润。
  • 子账户的 Rates 不能低于其父账户的 Rates。
• 价格因子 (Factor): 这是一个由 root 管理员设置的系统级全局价格系数，用于进行全局的价格调整。普通用户通常无需关心此项。

充值与扣款逻辑

当父账户为子账户充值时，资金的转移遵循以下原则：

父账户扣除额度 = 子账户充值额度 / 子账户费率 × 父账户费率

示例：

• 父账户 A (Rates=1.0)
• 子账户 B (Rates=1.2)

如果账户 A 为账户 B 充值 $120：

1. 子账户 B 的 CreditBalance 增加 $120。
2. 父账户 A 的 CreditBalance 将被扣除 $120 / 1.2 × 1.0 = $100。
3. 差额的 $20 即为父账户 A 的潜在利润，会在子账户 B 消费时逐步实现。

额度限制 (HardLimit & SoftLimit)

• HardLimit: 月度消费硬顶。当月消费超过此限制，API 请求将被拒绝。
• SoftLimit: 月度消费软顶。当月消费超过此限制，系统会发送邮件提醒。