11资金
余额
API 余额由账号下的所有密钥共用。发送一批请求之前先检查可用金额,并在代码中处理余额不足的情况。
查询余额
GET
/balance只需要 API 密钥。该端点没有请求体和参数,查询也不会扣费。
curl --fail-with-body --max-time 20 \ https://api.rendergrid.io/ api/ public/ v1/ balance \ -H "Authorization: Bearer $RENDERGRID_API_KEY"
import os from decimal import Decimal import requests key = os.environ["RENDERGRID_API_KEY"] response = requests.get( "https://api.rendergrid.io/ api/ public/ v1/ balance", headers={"Authorization": f"Bearer {key}"}, timeout=(5, 20), ) response.raise_for_status() # 字符串 -> Decimal,而不是 float available = Decimal(response.json()["available"]) print(available)
// Node.js 22+,文件扩展名为 .mjs const url = "https://api.rendergrid.io/ api/ public/ v1/ balance"; const key = process.env.RENDERGRID_API_KEY; const response = await fetch(url, { headers: { Authorization: `Bearer ${key}` }, signal: AbortSignal.timeout(20_000), }); if (!response.ok) { const body = await response.text(); throw new Error(`HTTP ${response.status}: ${body}`); } // 这是字符串:不要把它转换成 Number const { available } = await response.json(); console.log(available);
{
"currency": "USD",
"balance": "42.5000",
"overdraft_limit": "0.0000",
"available": "42.5000"
}| 字段 | 类型 | 含义 |
|---|---|---|
currency | string | 货币代码:USD |
balance | string | 当前余额。在获批的信用额度内可以为负数 |
overdraft_limit | string | 信用额度。"0.0000" 表示只能预付费使用 |
available | string | 可以花费的金额:balance + overdraft_limit |
金额是字符串
三个金额都是以美元计的十进制字符串,小数点后保留四位。请保持这一精度:Python 中使用 Decimal,其他语言中使用以 $0.0001 为单位的整数。二进制浮点数不适合用来表示金额。
| 示例 | balance | overdraft_limit | available |
|---|---|---|---|
| 普通余额 | "42.5000" | "0.0000" | "42.5000" |
| 信用额度 | "-3.0000" | "10.0000" | "7.0000" |
| 为空 | "0.0000" | "0.0000" | "0.0000" |
什么时候扣费
金额在接收请求时、开始处理之前扣除。如果没有生成出图片,扣费会自动退回。
请求失败不收费:金额会立即退回余额。
查询余额不会预留任何金额:在你读取余额的同时,另一个请求可能已经把余额用掉了。因此即使检查通过,也始终要处理 402。
响应
HTTP/1.1 402 Payment Required { "error": { "code": "ERR_INSUFFICIENT_BALANCE", "message": "insufficient api wallet balance", "details": { "required": "0.0400", "available": "0.0100", "top_up_url": "/portal/billing" } } }
required 是这张图片的价格,available 是当前可用的金额。两个金额都是以美元计、保留四位小数的字符串。top_up_url 指向控制台的“余额与充值”页面。
HTTP/1.1 402 Payment Required { "error": { "code": "ERR_INSUFFICIENT_BALANCE", "message": "monthly budget exceeded", "details": { "reason": "monthly_budget_exceeded", "cap": 50.0 } } }
账号或密钥的月度限额按 UTC 日历月计算;失败图片的退款会释放相应的金额。这是硬性限制:限额用尽期间不会接收生成请求,也不会从余额中扣费。详见“限额”页面。
如何读取余额
- 在发送一批请求之前检查余额,并在运行期间不时检查。
- 查询余额计入账号的请求速率限制,但不占用生成名额,也不与任务轮询间隔共用。
- 不要把检查当作保证:起决定作用的是生成请求本身的响应。
充值
公开 API 中没有充值端点。余额通过控制台的“余额与充值”页面用 USDT 充值,或通过经理充值。余额和交易记录也在同一处查看。
常见问题
可以查询单个密钥的余额吗?
不可以:余额由账号的所有密钥共用,单个密钥没有独立的余额。
失败的图片什么时候退款?
失败时立即退回:扣费会自动退还,无需申请。请在控制台中查看余额和交易记录。
“信用额度”是什么意思?
这是余额允许透支的金额。如果没有信用额度,
overdraft_limit 字段为 "0.0000",只能预付费使用。