# 抠图

抠图以发丝级的细节将前景主体与背景分离，返回主体的 RGBA 抠图，或单独返回 8 位灰度 alpha 蒙版。典型用途包括商品图、人像、合成，以及自行应用 alpha 的流程。

## 抠图或蒙版

`options.output` 决定返回内容。

- `cutout`（默认）：主体的 RGBA 图像，背景透明，可直接放到新的背景上，无需后续处理。
- `matte`：8 位灰度 alpha 蒙版，白色为主体，黑色为背景，边缘半透明处（头发、毛发）为中间灰度。适用于自行应用 alpha 的流程，例如在编辑器中做遮罩、与原图的其他裁剪合成，或将蒙版交给后续处理步骤。

两种输出按 `image` 计费，单价相同。

## 抠图

抠图保留主体的颜色并去掉背景，发丝处带有柔和的 alpha。

![左侧是柏油路面上的约克夏梗犬，右侧是同一只狗位于棋盘格透明图案上，背景已移除。](../../../../../assets/docs/birefnet-cutout.webp)

*Playground 对 `output: "cutout"` 的录制结果。棋盘格表示透明像素。*

## 蒙版

蒙版只包含 alpha 通道，以灰度图像表示。

![左侧是同一张约克夏梗犬照片，右侧是它的 alpha 蒙版：黑色背景上的白色狗轮廓。](../../../../../assets/docs/birefnet-matte.webp)

*Playground 对 `output: "matte"` 的录制结果：白色为主体，黑色为背景。*

## 输出格式

`options.format` 决定返回图像的编码。

- `png`（默认）：无损 PNG。
- `webp`，用于 `cutout`：质量 90 的有损 RGB 加无损 alpha 通道，因此蒙版是精确的。WebP 抠图通常比 PNG 小约 10 倍，例如在 1791 × 1008 像素下约为 200 kB，而 PNG 约为 2 MB，且无肉眼可见的差异，响应也更快到达。
- `webp`，用于 `matte`：灰度蒙版的无损 WebP。它以灰色 RGB 存储，因此所有解码器都显示为灰色，其中红色通道即为蒙版。

## 支持的模型

`birefnet` 是 `POST /v1/remove-background` 的默认模型，也是唯一的模型。

| | [`birefnet`](https://stack.foldbun.com/zh/docs/models/birefnet/#抠图) |
|---|---|
| 模型 | BiRefNet 通用模型 |
| 接受 | 一张图片 |
| 返回 | RGBA 抠图结果或 8 位灰度蒙版，格式为 PNG 或 WebP |
| 标价（额度） | 每张图片 1 |
| 模型池 | 付费池：从余额中扣费 |
| 录制的处理时间 | 882 ms（一次录制的调用） |

## 调用示例

对图中的狗照片抠图，并以 WebP 返回：

```bash
curl https://api.stack.foldbun.com/v1/remove-background \
  -H "Authorization: Bearer $FOLDBUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "birefnet",
    "image": { "id": "img_3343c2ff2ab3bf8b5a45e85a184f65e819d577d6de2ac81cc32eb0bb88fb9e4d" },
    "options": { "output": "cutout", "format": "webp" }
  }'
```

以下响应有删减：`data` 字符串已缩短。

```json
{
  "id": "call_01a1913f-3d29-73dc-ab68-81ad46905b04",
  "model": "birefnet",
  "image": {
    "id": "img_3343c2ff2ab3bf8b5a45e85a184f65e819d577d6de2ac81cc32eb0bb88fb9e4d",
    "width": 1091,
    "height": 1008,
    "bytes": 204026,
    "contentType": "image/jpeg"
  },
  "format": "webp",
  "width": 1091,
  "height": 1008,
  "data": "UklGRtYGAABXRUJQVlA4...",
  "cost": 1,
  "balance": 995,
  "timing": { "queueMs": 0, "processingMs": 882 },
  "billing": {
    "lines": [
      { "unit": "image", "quantity": 1, "unitPrice": 1, "amount": 1, "waived": false }
    ],
    "total": 1,
    "charged": true,
    "pool": null
  }
}
```

### 响应解读

- `format` 为 `webp`，与 `options.format` 的请求一致。
- `width` 和 `height` 为返回图片的尺寸。此处为 1091 × 1008，与输入图片的尺寸（`image.width`、`image.height`）一致，因为长边小于默认的 `options.size`（2048）。更大的图片会在长边上缩小到 `options.size`。
- `data` 是以 base64 字符串内联返回的图片，没有下载链接。
- `billing.charged` 为 `true`，`pool` 为 `null`：本次调用从余额中扣费，因此 `cost` 为 1。

全部字段：[API 参考](https://stack.foldbun.com/zh/docs/api/operations/removebackground/)。

**本次调用的费用。** 1（`image`）额度，与本响应的实际扣费一致；蒙版价格相同，也没有缓存折扣。单价见[计费](https://stack.foldbun.com/zh/docs/billing/#价目表)。

### Python 完整流程

```python
import base64
import os

import requests

response = requests.post(
    "https://api.stack.foldbun.com/v1/remove-background",
    headers={"Authorization": f"Bearer {os.environ['FOLDBUN_API_KEY']}"},
    json={
        "image": {"id": "img_3343c2ff2ab3bf8b5a45e85a184f65e819d577d6de2ac81cc32eb0bb88fb9e4d"},
        "options": {"output": "cutout", "format": "webp"},
    },
    timeout=120,
)
response.raise_for_status()
result = response.json()

with open(f"cutout.{result['format']}", "wb") as f:
    f.write(base64.b64decode(result["data"]))
```

## 接口与参考

| 接口 | 在本用例中 | 参考 |
|---|---|---|
| `POST /v1/remove-background` | 一张图片得到抠图结果（RGBA）或 alpha 蒙版（8 位灰度），格式为 PNG 或 WebP | [API 参考](https://stack.foldbun.com/zh/docs/api/operations/removebackground/) |

- [`birefnet`](https://stack.foldbun.com/zh/docs/models/birefnet/)：模型的工作原理、限制和实测延迟。
- [计费](https://stack.foldbun.com/zh/docs/billing/#价目表)：`birefnet` 每次调用计一个 `image`。
- [图片](https://stack.foldbun.com/zh/docs/images/)：图片限制、存储和坐标。