通过 GET /v1/users/me/balance 接口可以实时查询 Kimi 账户的可用余额、代金券余额和现金余额。可用余额 = 现金余额 + 代金券余额，当可用余额 ≤ 0 时推理 API 将返回错误。适合在应用中实现余额预警机制。

Kimi API 余额查询

接口说明

GET https://api.moonshot.cn/v1/users/me/balance
Authorization: Bearer {MOONSHOT_API_KEY}

---

响应字段

字段	类型	说明
available_balance	float	可用余额（元），= cash_balance + voucher_balance
voucher_balance	float	代金券余额，不能为负
cash_balance	float	现金余额，可为负

重要：当 available_balance ≤ 0 时，推理 API 调用将被拒绝，直到充值后恢复。

---

响应示例

{
  "code": 0,
  "data": {
    "available_balance": 49.58894,
    "voucher_balance": 46.58893,
    "cash_balance": 3.00001
  },
  "scode": "0x0",
  "status": true
}

---

代码示例

const response = await fetch(
  "https://api.moonshot.cn/v1/users/me/balance",
  {
    headers: {
      Authorization: `Bearer ${process.env.MOONSHOT_API_KEY}`,
    },
  }
);

const data = await response.json();
const balance = data.data;

console.log(`可用余额: ¥${balance.available_balance.toFixed(2)}`);
console.log(`代金券: ¥${balance.voucher_balance.toFixed(2)}`);
console.log(`现金: ¥${balance.cash_balance.toFixed(2)}`);

// 余额预警
if (balance.available_balance < 10) {
  console.warn("余额不足 10 元，请及时充值！");
}

import os
import requests

api_key = os.environ.get("MOONSHOT_API_KEY")

response = requests.get(
    "https://api.moonshot.cn/v1/users/me/balance",
    headers={"Authorization": f"Bearer {api_key}"},
)

data = response.json()["data"]
print(f"可用余额: ¥{data['available_balance']:.2f}")
print(f"代金券: ¥{data['voucher_balance']:.2f}")
print(f"现金: ¥{data['cash_balance']:.2f}")

---

错误响应

HTTP 状态码	含义
401	API Key 无效或缺失
500	服务器内部错误

---

常见问题

Q: 代金券和现金余额有什么区别？

A: 代金券不能提现，使用期限可能有限制（参见代金券有效期说明）；现金余额可以退款，没有使用期限。扣费时优先使用代金券。

Q: 如何设置余额预警避免服务中断？

A: 在控制台的「消费提醒」中设置短信告警阈值，或在代码中定期调用此接口判断 available_balance，低于阈值时发邮件/短信通知。

Q: 现金余额显示负数正常吗？

A: 正常。cash_balance 可以为负（如代金券用完后欠款），此时可用余额取决于剩余代金券。cash_balance 为负不影响调用，只要 available_balance > 0 即可正常使用。