withoutbg-python

环境要求

• Python 环境（SDK 为 Python 包）
• 使用 uv 包管理器（README 推荐用 uv add 安装）
• 本地模式首次运行需联网下载约 455 MB 模型权重
• 云端模式需要 withoutbg API Key

安装与启动步骤

1. 1安装 uv

   README 说明 uv 是 Astral 出品的快速 Python 包管理器，若尚未安装需先安装一次，之后才能用 uv add 命令添加依赖。

2. 2安装 withoutbg

   在项目环境中用 uv 添加 withoutbg 依赖，README 中给出的正式安装命令即为 uv add withoutbg。

   uv add withoutbg

   复制

3. 3运行本地抠图

   使用 open_weights 加载本地开源权重模型，传入图片路径即可去除背景，结果保存为 PNG 以保留透明度。

   python -c "from withoutbg import WithoutBG; model = WithoutBG.open_weights(); model.remove_background('input.jpg').save('output.png')"

   复制

4. 4等待首次权重下载

   本地模式第一次运行会从 Hugging Face 下载约 455 MB 权重，只需一次；之后完全离线在本机运行。

5. 5切换到云端模式

   若需要更好的发丝与毛发边缘且不想用本地算力，可改用云端 API，通过 API Key 或环境变量认证，调用接口与本地一致。

关键配置

如何确认成功

运行示例代码后成功生成 output.png，且图片背景透明（RGBA），即表示本地模式正常工作。

常见问题

注意事项

• 首次本地运行需联网下载约 455 MB 权重，之后可完全离线使用。
• 保存结果建议用 PNG 或 WebP，JPEG 会丢失透明通道。
• 使用 WITHOUTBG_MODEL_PATH 时不要忘记同目录下的 .onnx.json 元数据文件。
• 云端模式需要 API Key，可通过环境变量 WITHOUTBG_API_KEY 配置。