# BiRefNet (birefnet)

`birefnet`（BiRefNet）以发丝级的细节将前景主体与背景分离，返回主体的 RGBA 抠图，或单独返回 8 位灰度 alpha 蒙版。

| | |
|---|---|
| 模型 ID | `birefnet`（接口的默认模型） |
| 模型 | BiRefNet 通用模型（Peng Zheng 等） |
| 权重 | 官方通用模型（`ZhengPeng7/BiRefNet`） |
| 用例 | [抠图](https://stack.foldbun.com/zh/docs/use-cases/background-removal/) |
| 接口 | `POST /v1/remove-background` |
| 模型池 | 付费池：从余额中扣费 |
| 计费单位 | `image`。单位与价格：[计费](https://stack.foldbun.com/zh/docs/billing/#价目表) |
| 许可证 | MIT |

## 工作原理

一次调用是分割网络对整张图片的一次前向推理，随后把结果打包为图像。

**预测。** 图片被缩放到 1024 × 1024 像素并做归一化，BiRefNet 为每个像素预测其属于前景主体的程度。该网络保留高分辨率细节，所以发丝等细小结构的边缘保持柔和、半透明。预测结果缩放回图片的尺寸，并存储为 8 位数值：255 为主体，0 为背景，两者之间为半透明像素。这就是 alpha 蒙版。

**输出。** `options.output` 为 `matte` 时，蒙版原样以灰度图像返回。为 `cutout`（默认）时，输入图片的颜色加上作为 alpha 通道的蒙版组成 RGBA 图像，因此背景透明。两种输出来自同一次推理，区别只在于结果的打包方式。随后图像按 `options.format` 编码为 PNG 或 WebP。

每次调用都在自己的图片上运行完整模型。没有可复用的编码，因此没有缓存折扣，一次调用计为一次 `image`，抠图和蒙版的价格相同。

## 各用例下的特性

### 抠图

- `birefnet` 是 `POST /v1/remove-background` 的默认模型，每次调用一张图片。
- `options.output` 返回 `cutout`（默认）或 `matte`，`options.format` 将其编码为 `png`（默认）或 `webp`；详见[输出格式](https://stack.foldbun.com/zh/docs/use-cases/background-removal/#输出格式)。
- 结果的长边为图片长边与 `options.size`（64 至 4096 的整数，默认 2048）中较小的一个，保持宽高比，图片不会被放大。结果以 base64 内联返回在 `data` 中。

用例说明与调用示例：[抠图](https://stack.foldbun.com/zh/docs/use-cases/background-removal/)。

## 限制与说明

- 每次调用一张图片。每次调用都运行完整模型，没有缓存折扣。
- 图片限制：详见[图片](https://stack.foldbun.com/zh/docs/images/)。图片长边超过 `options.size` 时，结果的长边缩小到该值。
- 延迟：录制的调用中 `timing.processingMs` 为 882 ms。该数值取决于图片、排队情况和节点负载，不构成保证。