抠图

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

抠图或蒙版

options.output 决定返回内容。

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

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

抠图

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

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

蒙版

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

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
模型	BiRefNet 通用模型
接受	一张图片
返回	RGBA 抠图结果或 8 位灰度蒙版，格式为 PNG 或 WebP
标价（额度）	每张图片 1
模型池	付费池：从余额中扣费
录制的处理时间	882 ms（一次录制的调用）

调用示例

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

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 字符串已缩短。

{
  "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 参考。

本次调用的费用。 1（image）额度，与本响应的实际扣费一致；蒙版价格相同，也没有缓存折扣。单价见计费。

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 参考

• birefnet：模型的工作原理、限制和实测延迟。
• 计费：birefnet 每次调用计一个 image。
• 图片：图片限制、存储和坐标。