教程
如何使用 Bria Eraser API：curl、Python 和一次可运行的请求
bria-eraser 可从照片中移除对象。你发送图片和黑白遮罩，它就用匹配的背景填充遮罩区域。没有 prompt 字段。本指南展示一次完整运行的请求、执行它的 Python 代码，以及决定你自己的遮罩能否奏效的细节。你需要从仪表盘获取 HiAPI key。
最小请求（curl）
该模型使用统一的异步端点 POST /v1/tasks。下面两个 URL 都是公开的，并且在撰写本文时均可访问：
curl -X POST "https://api.hiapi.ai/v1/tasks" \
-H "Authorization: Bearer $HIAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "bria-eraser",
"input": {
"image_url": "https://dev-static.hiapi.ai/model-onboarding/bria-eraser/2026/10/21/1792546025379-46c31ddb2b52110d-e1-street-src.png",
"mask_url": "https://dev-static.hiapi.ai/model-onboarding/bria-eraser/2026/10/21/1792546025861-e5d2a17ae1d12d41-e1-street-mask.png",
"mask_type": "manual"
}
}'
该调用会立即返回一个任务 id，而不是图片：
{"code":200,"data":{"taskId":"tk-hiapi-01M5K80RFJN3J788MMJT7YDVNB"},"message":"success"}
轮询 GET /v1/tasks/<taskId>，直到 data.status 为 success，然后读取 data.output[0].url。
Python：提交、轮询、下载
# pip install requests; export HIAPI_KEY=your-key first
import os, time, requests
API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}
def erase(image_url: str, mask_url: str, out_path: str) -> str:
r = requests.post(API, headers=HEADERS, timeout=30, json={
"model": "bria-eraser",
"input": {"image_url": image_url, "mask_url": mask_url, "mask_type": "manual"},
})
r.raise_for_status()
task_id = r.json()["data"]["taskId"]
for _ in range(60):
time.sleep(3)
try:
d = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
except requests.RequestException:
continue # transient network error: poll the SAME task id again
if d["status"] == "success":
img = requests.get(d["output"][0]["url"], timeout=60)
img.raise_for_status()
with open(out_path, "wb") as f:
f.write(img.content)
return task_id
if d["status"] == "fail":
raise RuntimeError(f"task {task_id} failed: {d}")
raise TimeoutError(task_id)
保留任务 id。如果某次轮询失败，就再次轮询该 id。不要重新提交，因为每次提交都是一个单独计费的任务。
请求字段
| 字段 | 是否必填 | 说明 |
|---|---|---|
input.image_url |
是 | 公开的 http/https URL。JPEG、PNG 或 WEBP。 |
input.mask_url |
是 | 与源图宽高比相同的黑白图片。白色会被擦除，黑色会保留。 |
input.mask_type |
否 | manual（默认）用于画笔绘制的遮罩，automatic 用于分割工具生成的遮罩。 |
input.preserve_alpha |
否 | 默认 false。设为 true 可保留带 alpha 通道输入的透明度。 |
生产环境：使用回调
轮询适合测试。对于服务，传入顶层 callback，让 HiAPI 在任务完成时通知你：
{
"model": "bria-eraser",
"input": { "image_url": "...", "mask_url": "..." },
"callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" }
}
保留轮询作为兜底，以防回调丢失。输出 URL 会过期，因此任务成功后应尽快把文件复制到你自己的存储。
我实际运行和看到的结果
我在撰写当天运行了一次 curl 部分的请求，并轮询到它完成。
- 状态顺序：
handling→archiving→success。archiving出现在工作完成之后、output出现之前。把它当作“尚未完成”，继续轮询。 - 时间：任务从创建到完成用了 16 秒。
outputURL 在此之后几秒出现。 - 输出：
temp.hiapi.ai上的一个 PNG，1360 × 768，带 alpha 通道。这与源图尺寸相同，符合文档中保留原始分辨率的说明。 - 计费：我查看时，公开定价数据中该模型的价格为每张图 $0.0575。当前价格请见定价。
- 验证错误：我故意测试发送了
mask_type: "bogus"。API 以 HTTP 400 拒绝：
{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: mask_type: value must be one of 'manual', 'automatic'"}
我只在一张图片上检查了一个请求。我没有测试其他遮罩样式、超大图片，或宽高比与图片不一致的遮罩。下面关于这些情况的说明来自模型文档，而非我的测试。
遮罩提示（来自文档）
- 稍微涂出对象边缘一点。紧贴轮廓的遮罩往往会在原对象周围留下光晕。
- 遮罩保持与照片相同的宽高比。文档要求如此，但未说明否则会怎样。
- 只有来自分割或抠图工具的遮罩才使用
automatic。画笔遮罩使用manual。
我应该读哪个页面？
本指南介绍使用专用端点进行基于遮罩的移除。对于使用通用图生图模型的提示词驱动编辑，请参阅图像修复和对象移除。如果要移除整个背景而不是单个对象，请参阅背景移除指南。模型页面位于 bria-eraser，字段参考见 API 文档。
常见问题
bria-eraser 需要提示词吗？
不需要。文档说明无需提示词，我运行的请求只包含图片、遮罩和 mask_type。
遮罩中哪种颜色会被移除？
白色会被擦除，黑色会保留。
输出会比输入小吗？
在我的运行中，输出为 1360 × 768，与源图完全相同。
我应该轮询还是使用回调？
测试时轮询。生产环境使用 callback.url 和 when: "final"，并以轮询作为兜底。
