# 计费

## 额度

金额单位为额度。额度在 JSON 中以数字表示，最多 6 位小数；最小单位为微额度，因此金额是精确的。

账户余额为预付。每次调用按价目表计价，失败的调用不收费。

| 字段 | 含义 |
|---|---|
| `cost` | 本次调用实际扣费的额度。 |
| `balance` | 本次调用后的账户余额。 |

## 价目表

| 模型 | 计费单位 | 计费项及收费时机 | 价格（额度） |
|---|---|---|---|
| `sam3` | `encode_image` | 图像编码，每张图像：每次调用收取一次；同一图像的编码仍在该账户的缓存中时免收 | 0.5 |
| `sam3` | `prompt` | 文本提示：`POST /v1/segment` 中每个文本短语一次解码；样例框（无论正向还是负向）不另外收费，只含框而没有文本短语的调用计为一次 `prompt` | 0.05 |
| `sam3` | `point` | 点提示：`POST /v1/segment` 中每个点一次解码 | 0.02 |
| `sam3` | `refine` | 修整：每次 `POST /v1/refine` 调用一次解码，无论点有多少个，也无论是否带框 | 0.02 |
| `sam-lite` | `encode_image` | 图像编码，每张图像：同 `sam3` | 0.2 |
| `sam-lite` | `point` | 点提示：`POST /v1/segment` 中每个点一次解码 | 0.01 |
| `sam-lite` | `box` | 框提示：`POST /v1/segment` 中每个框一次解码 | 0.01 |
| `sam-lite` | `refine` | 修整：每次 `POST /v1/refine` 调用一次解码，同 `sam3` | 0.01 |
| `ppocr-v6` | `image` | 文字识别：每个请求一张图像 | 0.25 |
| `paddleocr-vl` | `page` | 文档解析：每个请求一页图像 | 2 |
| `dinov3` | `image` | 图像嵌入：每个请求一张图像 | 0.05 |
| `siglip2` | `image` | 图像嵌入：每个请求一张图像 | 0.05 |
| `siglip2` | `text` | 文本嵌入：`texts[]` 中的每个字符串 | 0.01 |
| `birefnet` | `image` | 抠图：每个请求一张图像 | 1 |

单位说明：

- `ppocr-v6`：每次调用计一个 `image`，与行数、词数以及是否开启 `options.words` 无关。
- `paddleocr-vl`：每次调用计一个 `page`，与区块数量无关。
- `siglip2`：对 N 张已存储图片进行文字检索，一次性计 N 个 `image`，之后每次查询计一个 `text`。
- `birefnet`：抠图结果与蒙版价格相同；没有缓存折扣，每次调用都完整运行模型。

`GET /v1/models` 在 `prices[]` 中返回当前价格，计费单位相同。价目表带有版本；每次调用按其运行时生效的版本计价。

## 预留与结算

调用在运行前预留全部价格，并按工作进程上报的用量结算。失败的调用会释放预留，不收费。余额不足以支付预留时，返回 `402 insufficient_balance`。

## SAM 图片编码费与缓存命中

`sam3` 和 `sam-lite` 每次调用收取图片编码费（`encode_image`）。同一张图片的编码已为该账户计算过、且仍缓存在 GPU 节点上时，该费用减免。响应中会出现 `"cache": "hit"` 和 `"imageFee": 0`，`encode_image` 行的 `waived` 为 `true`、`amount` 为 0。

```json
{
  "cache": "hit",
  "imageFee": 0,
  "billing": {
    "lines": [
      { "unit": "encode_image", "quantity": 1, "unitPrice": 0.5, "amount": 0, "waived": true },
      { "unit": "refine", "quantity": 1, "unitPrice": 0.02, "amount": 0.02, "waived": false }
    ],
    "total": 0.02,
    "charged": true,
    "pool": null
  }
}
```

缓存命中是额外的好处，而不是承诺。缓存的编码最长保留 7 天，到期后删除；容量不足时会更早淘汰，因此不设最短保留期限。成本规划应假设每次调用都收取编码费。缓存按账户隔离，不会在账户之间共享。

对刚完成分割的图片进行修整，通常会命中缓存，但只有响应中如此标明时才减免费用。

## SAM 调用如何计费

SAM 调用按解码次数计费。一次解码是模型在图片编码之上，针对一个提示或一个物体运行的一次推理。图片编码本身（`encode_image`）每次调用计费一次，缓存命中时减免。各阶段如何运作，见模型页面上的[工作原理](https://stack.foldbun.com/zh/docs/models/sam3/#工作原理)。

| 接口 | 一次解码为 | 单位 |
|---|---|---|
| `POST /v1/segment` | 每个提示 | `sam3`：每个文本提示计为 `prompt`（样例框（无论正向还是负向）不另外收费，只含框的调用计为一次 `prompt`），每个点计为 `point`。`sam-lite`：每个点计为 `point`，每个框计为 `box`。 |
| `POST /v1/refine` | 整个调用，无论点有多少个，也无论是否带框 | `refine` |

按标价计算的示例：

- `sam3`，`POST /v1/segment`，新图片上的 3 个文本提示：0.5（`encode_image`）+ 3 × 0.05（`prompt`）= 0.65 额度。
- `sam3`，`POST /v1/segment`，新图片上的 2 个文本提示和 3 个样例框：0.5 + 2 × 0.05 = 0.60 额度，样例框不另外收费。
- `sam3`，`POST /v1/segment`，新图片上的 4 个样例框、没有文本提示：0.5 + 0.05 = 0.55 额度，单个视觉查询计为一次 `prompt`。
- `sam3`，`POST /v1/segment`，新图片上的 1 个文本提示和 2 个点：0.5 + 0.05 + 2 × 0.02 = 0.59 额度。
- `sam-lite`，`POST /v1/segment`，新图片上的 4 个框：0.2 + 4 × 0.01 = 0.24 额度。
- `sam3`，`POST /v1/refine`，已缓存图片上的 10 次点选，每次点选各发一次调用并带上之前的全部点选：10 × 0.02 = 0.20 额度，因为编码费减免。新图片上的第一次调用为 0.5 + 0.02。使用 `sam-lite` 时，同样的编辑过程第一次调用为 0.2 + 0.01，之后每次为 0.01。
- 带 12 个点和一个框的单次 `POST /v1/refine` 调用仍然只计一次 `refine`：`sam3` 为 0.02，图片编码未缓存时另加编码费。

模型池可以在不扣减余额的情况下覆盖一次调用；`billing` 中的各行仍显示上述标价。上述单价为当前价格，每次调用按其运行时生效的价格版本计价。

## `billing` 对象

每个成功的推理响应都带有 `billing`，说明该调用如何计价。

| 字段 | 含义 |
|---|---|
| `lines[]` | 每个计价单位一行：`unit`、`quantity`、`unitPrice`、`amount` 和 `waived`。 |
| `total` | 各行之和。余额不足以支付全部价格时，`total` 为实际扣除的金额。 |
| `charged` | 是否从余额中扣费。由每日包含额度覆盖的调用以及 Playground 试用调用为 `false`。 |
| `pool` | 其每日额度覆盖了该调用的模型池（`public` 或 `free`）。计费调用为 `null`。 |
| `allowance` | 当日（UTC）包含调用的 `used` 和 `limit`，计入本次调用。仅在设置了 `pool` 时出现。 |
| `capped` | 仅当价格超过余额、扣费被削减到余额时出现，且为 `true`。 |

`cost` 始终与 `billing` 一致：`charged` 为 `true` 时等于 `total`，否则为 0。对未扣费的调用，各行仍显示标价。

以下是一次计费的 `sam3` 调用示例，含两个文本提示，缓存未命中：

```json
{
  "cost": 0.6,
  "balance": 998.4,
  "cache": "miss",
  "imageFee": 0.5,
  "billing": {
    "lines": [
      { "unit": "encode_image", "quantity": 1, "unitPrice": 0.5, "amount": 0.5, "waived": false },
      { "unit": "prompt", "quantity": 2, "unitPrice": 0.05, "amount": 0.1, "waived": false }
    ],
    "total": 0.6,
    "charged": true,
    "pool": null
  }
}
```

## 增加额度

- 最低储值金额为 US$0.99（990 额度）。
- 储值按 US$1 = 1,000 额度到账。
- 额度不设有效期。
- 首次储值还会开放免费池和付费池。详见[速率限制与模型池](https://stack.foldbun.com/zh/docs/rate-limits/)。

在线储值暂未提供。[控制台](https://stack.foldbun.com/console/billing)的 **计费** 页面说明了如何增加额度。