# 速率限制与模型池

账户可以调用哪些模型、调用速度多快，取决于所在的模型池。模型池将模型分组，并带有每日包含额度和每分钟限制。`GET /v1/models` 显示适用于调用账户的内容。

## 模型池

| 模型池 | 开放时机 | 模型 | 每个 UTC 日包含 | 每分钟 |
|---|---|---|---|---|
| 公共池 | 注册即开放 | `ppocr-v6`、`dinov3`、`siglip2` | 100 次调用 | 10 |
| 免费池 | 首次储值后 | 公共池的模型和 `sam-lite` | 1,000 次调用 | 60（仅限包含额度内的调用） |
| 付费池 | 首次储值后 | 全部模型：`sam3`、`paddleocr-vl` 和 `birefnet` 仅在此池提供 | 不适用：按调用计费 | 无固定限制 |

- 已注册账户使用公共池。超出每日额度的调用以 `429 daily_limit_reached` 拒绝。
- 已储值账户（完成过储值的账户）还可使用免费池。每个池内模型每个 UTC 日的前 1,000 次调用免费，超出部分从余额中扣费。
- `sam3`、`paddleocr-vl` 和 `birefnet` 始终从余额中扣费。调用账户尚不能使用的模型，返回 `403 model_locked`，`GET /v1/models` 会在 `unlockedBy` 中给出解锁方式。
- 每日额度在 UTC 00:00 重置。账户的调用合并计数，与使用哪个密钥无关。失败的调用会退回其占用的名额。

每个响应的 `billing` 对象显示由哪个模型池覆盖了该调用，以及当日的计数。详见[计费](https://stack.foldbun.com/zh/docs/billing/)。

## 每分钟限制

每分钟限制是按账户的令牌桶：突发量等于每分钟限制，令牌持续补充。超出限制时返回 `429 rate_limited` 并带有 `Retry-After` 响应头。该限制由账户的所有密钥共享，采用提供该模型的模型池的限制。

已储值账户的免费池每分钟 60 次只用于控制包含的每日额度内调用的速度。超出每日额度的调用，或在每分钟 60 次已用完时到达的调用，按正常价格从余额中扣费，不受速率限制；该调用不占用每日额度，额度仍可供之后的调用使用。此时只有余额无法支付的调用才返回 `429 rate_limited`。并发调用仍受账户并发限制约束。批量请求遵循同一规则：一个批量请求消耗一个令牌，令牌用完时，其条目改为计费而不是免费。仅使用公共池的已注册账户仍返回 429。

账户没有固定限制时，GPU 容量不足会以 `503 model_busy` 或 `503 model_unavailable` 的形式返回。

## 查看限制

`GET /v1/models` 免费、不计量，也不受模型池的速率限制。每个模型都带有描述调用账户情况的字段。

| 字段 | 含义 |
|---|---|
| `available` | 账户当前是否可调用该模型。 |
| `pool` | 为账户提供服务的模型池：`public`、`free` 或 `paid`。模型不可用时为 `null`。 |
| `freeDailyCalls` | 每个 UTC 日免费包含的调用次数。没有时为 `null`。 |
| `perMinute` | 每分钟调用次数。无限制时为 `null`。 |
| `unlockedBy` | 模型不可用时的解锁方式，例如 `top-up`。 |

```json
{
  "id": "ppocr-v6",
  "name": "PP-OCRv6 small",
  "task": "ocr",
  "endpoints": ["/v1/ocr"],
  "license": "Apache-2.0",
  "prices": [{ "unit": "image", "price": 0.25 }],
  "available": true,
  "pool": "public",
  "freeDailyCalls": 100,
  "perMinute": 10,
  "unlockedBy": null
}
```

## 状态码

| 状态码 | 错误码 | 原因 | 处理 |
|---|---|---|---|
| 402 | `insufficient_balance` | 余额不足以支付调用。 | 增加额度。 |
| 403 | `model_locked` | 模型池或密钥范围不包含该模型。 | 增加额度，或使用范围包含该模型的密钥。 |
| 429 | `rate_limited` | 达到每分钟限制（已储值账户：且余额无法支付该调用）。 | 等待 `Retry-After` 后重试。 |
| 429 | `daily_limit_reached` | 公共池的每日额度已用完。 | 增加额度，或等到下一个 UTC 日。 |

完整列表详见[错误](https://stack.foldbun.com/zh/docs/errors/)。