余额不足、预扣失败是什么意思

TL;DR 一句话:这一单需要的额度超过了你的可用余额,所以没有执行,也没有扣费。最常见的原因是还在跑的请求占着额度,或者这一单按最大可能花费预扣(张数、秒数、分辨率、max_tokens),比你以为的多。充值,或者降低并发、调小这一单的规格即可。

建一个图片、视频或音频任务时,还没开始生成,这一单的全额就先从余额里冻结(预扣)。任务完成后按实际花费扣费(比如只收实际出成的那几张),多冻的退回;任务失败则全部退回。只有可用余额(总余额减去当前被冻结的部分)够付这一单的价格,任务才能开始。

报错里会直接给出数字,例如「this request needs $0.1200 but only $0.0450 is available ($0.3000 is held by requests still running)」:第一个数是这一单的价格,第二个是你现在能用的额度,括号里是你其他还没跑完的请求占着的额度。

对话等大模型请求在调用前检查一次余额,按「估算的输入 + max_tokens 的输出」再加 20% 余量来算。

这个报错的三种样子

出现在哪	你会看到	状态
创建图片 / 视频 / 音频任务时	"Insufficient credits: this request needs $X but only $Y is available ($Z is held by requests still running). Please top up and try again; nothing was charged."	HTTP 402,不会创建任务
已经拿到任务 id 的任务	"Your account balance was too low to start this request, so it was not run or charged."(或上面那句)	state 为 "failed",failCode 为 "INSUFFICIENT_BALANCE";多个请求同一瞬间到达时会出现
对话等大模型请求	{"error": {"message": "Insufficient credits for this request", "type": "insufficient_credits"}}	HTTP 402

余额看着够,为什么还说不足

还在跑的请求占着额度。每个进行中的请求都冻结着自己的全价,直到跑完为止。批量并发发请求时,这些冻结会叠加;一旦加起来超过余额,后面的请求就会被拒,哪怕前面一单都还没真正扣费。报错里「held by requests still running」就是这部分,前面的请求一跑完就会结算、退回多冻的部分。

一单按它可能的最大花费预扣。图片请求预扣「张数 × 每张价格」再加参考图的费用;视频请求按请求的秒数和对应分辨率的每秒价格预扣,参考视频按秒计费的也算进去;大模型请求按 max_tokens 的输出预扣,不传 max_tokens 就按模型的默认上限。一单 4K、一次 4 张或者 15 秒的请求,需要的额度可能比你一分钟前发的那单多得多。

怎么解决

在控制台的「余额」页充值,支持银行卡、支付宝和 USDT。无人值守跑任务的话,在同一页打开自动充值:绑一张银行卡,设一个阈值和充值金额($10、$50、$100、$500 或 $1,000),余额低于阈值时就会自动充值。

批量任务控制并发。同时在跑的请求数,控制在「可用余额 ÷ 单个请求的价格」以内;发下一批之前先查 GET /v1/balance,其中的 balance 字段就是现在能用的额度。

大模型请求设上 max_tokens。不设的话,预检会按模型的最大输出来估,余额不多时可能直接被拒,哪怕实际回答很短。

把这一单调小:一次少出几张、降低分辨率、缩短时长,都能降低预扣的额度。

在程序里怎么处理

把 HTTP 402、failCode 为 "INSUFFICIENT_BALANCE"、错误类型为 "insufficient_credits" 当成同一种情况处理:停止继续发送,通知负责充值的人,余额恢复后再继续。循环重试没有用,在充值或前面的请求跑完之前,结果不会变。

调用示例

cURL

# Available balance before sending a batch (free, no credits charged)
curl https://api.apimodels.app/v1/balance \
  -H "Authorization: Bearer $APIMODELS_API_KEY"
# → { "code": 200, "msg": "success",
#     "data": { "balance": 12.5, "total": 12.8, "frozen": 0.3, "currency": "USD" } }
# balance = total − frozen; frozen includes credit reserved by requests still running

Python

import os, requests

H = {"Authorization": f"Bearer {os.environ['APIMODELS_API_KEY']}"}
price_per_request = 0.05        # what one of your requests costs
available = requests.get("https://api.apimodels.app/v1/balance", headers=H).json()["data"]["balance"]

max_in_flight = int(available // price_per_request)
if max_in_flight == 0:
    raise SystemExit("Top up first: one request costs more than the available balance")
print(f"Run at most {max_in_flight} requests at the same time")

常见问题

因为余额不足失败的请求扣费了吗?

没有。请求在执行前就被拒了,不扣费,也不会为它冻结任何额度。

余额显示是够的,为什么还被拒?

余额里有一部分被还在跑的请求冻结着,而且每一单都按可能的最大花费预扣。对照报错里「needs」和「available」两个数,括号里就是你正在跑的请求占着的额度。

GET /v1/balance 返回的 frozen 是什么?

暂时被冻结、现在不能用的额度,主要是还在跑的请求预扣的。它们跑完就结算:按实际花费扣费,剩下的回到可用余额。

能不能自动充值?

可以。在控制台「余额」页绑一张银行卡,打开自动充值,设好阈值和充值金额($10、$50、$100、$500 或 $1,000)即可。

为什么对话请求要求的额度比实际花费高?

检查发生在回答生成之前,只能按最长的可能来估(max_tokens,不传就按模型的默认上限),再加 20% 余量。实际只按用掉的 token 扣费。设一个合理的 max_tokens,预检要求的额度就会降下来。