GET /user/balance 接口返回账户的余额信息，包括总余额、赠金余额（有有效期）和充值余额（永久有效），支持人民币（CNY）和美元（USD）。可用于构建余额监控告警，防止因余额不足导致服务中断。

DeepSeek 账户余额 API

端点： GET https://api.deepseek.com/user/balance

响应结构

{
  "is_available": true,
  "balance_infos": [
    {
      "currency": "CNY",
      "total_balance": "110.00",
      "granted_balance": "10.00",
      "topped_up_balance": "100.00"
    }
  ]
}

字段	类型	说明
is_available	boolean	账户是否有余额可用（total_balance > 0 时为 true）
balance_infos	object[]	各货币的余额信息（通常只有一个条目）
currency	string	货币："CNY"（人民币）或 "USD"（美元）
total_balance	string	总可用余额（赠金 + 充值余额之和）
granted_balance	string	赠金余额（有过期时间，赠送的免费额度）
topped_up_balance	string	充值余额（永久有效，主动充值的金额）

代码示例

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.deepseek.com",
  apiKey: process.env.DEEPSEEK_API_KEY,
});

// OpenAI SDK 没有 balance 接口，用原始 HTTP 请求
const response = await fetch("https://api.deepseek.com/user/balance", {
  headers: {
    Authorization: `Bearer ${process.env.DEEPSEEK_API_KEY}`,
    "Content-Type": "application/json",
  },
});

const data = await response.json() as {
  is_available: boolean;
  balance_infos: Array<{
    currency: string;
    total_balance: string;
    granted_balance: string;
    topped_up_balance: string;
  }>;
};

console.log(`余额可用：${data.is_available}`);
for (const info of data.balance_infos) {
  console.log(`${info.currency} 总余额：${info.total_balance}`);
  console.log(`  - 赠金：${info.granted_balance}`);
  console.log(`  - 充值：${info.topped_up_balance}`);
}

import os
import requests

response = requests.get(
    "https://api.deepseek.com/user/balance",
    headers={"Authorization": f"Bearer {os.environ['DEEPSEEK_API_KEY']}"}
)
data = response.json()

print(f"余额可用: {data['is_available']}")
for info in data["balance_infos"]:
    print(f"{info['currency']} 总余额: {info['total_balance']}")

余额监控示例

生产环境建议设置自动告警，防止余额耗尽导致服务中断：

async function checkBalanceAlert(threshold = 10) {
  const response = await fetch("https://api.deepseek.com/user/balance", {
    headers: { Authorization: `Bearer ${process.env.DEEPSEEK_API_KEY}` },
  });
  const data = await response.json() as any;

  if (!data.is_available) {
    console.error("警告：DeepSeek 余额已耗尽！");
    return false;
  }

  const cnyBalance = data.balance_infos.find((b: any) => b.currency === "CNY");
  if (cnyBalance && parseFloat(cnyBalance.total_balance) < threshold) {
    console.warn(`警告：DeepSeek 余额不足 ${threshold} 元（当前：${cnyBalance.total_balance}）`);
  }

  return true;
}

常见问题

Q: is_available: false 但看到 total_balance 有正数，为什么？

A: 可能是赠金已过期，granted_balance 有值但实际不可用。检查 topped_up_balance 是否为正数，或登录控制台确认余额状态。

Q: 余额为 0 时 API 会返回什么错误？

A: 返回 HTTP 402，错误码 insufficient_user_balance。建议在应用层捕获此错误并触发告警，详见 错误码文档。