如何通过 hiapi API 使用 851-labs/background-remover：curl、Python 与可运行的请求

851-labs/background-remover 只需一次 API 调用，就能把商品、人像或宠物照片转成透明 PNG —— 无需提示词、无需蒙版、无需宽高比设置。本文介绍确切的请求结构、可运行的 curl 命令、可直接放入后端的 Python 脚本，以及一个最容易让人踩坑的 schema 错误。

准备工作

• 一个 hiapi 账号，以及从控制台获取的 API key。
• 一张托管在公共 HTTPS URL 上的图片。任务 API 接收的是 URL，而不是文件上传 —— 如果你的源图只存在于本地，请先把它放到任意 CDN 或对象存储上。

所有请求都发往统一的任务端点：

POST https://api.hiapi.ai/v1/tasks
Authorization: Bearer sk-<your-key>
Content-Type: application/json

请求结构（以及唯一必须牢记的规则）

模型 id 是 851-labs/background-remover，直接原样传入。它的 input schema 只有一个字段：

字段	类型	必填	说明
image_url	string	是	必须匹配 ^https?://[^\s]+$ —— 一个可直接访问的 http(s) URL。

这就是整个 schema。在写任何代码之前，有两点值得了解：

1. 没有 prompt、mask、background-color 或 aspect-ratio 字段。这个端点只做一件事 —— 前景/背景分离 —— 别的什么都不做。如果你之后需要重新上色或调整尺寸，那需要再调用另一个模型。
2. 多余字段会被拒绝，而不是被忽略。如果你从其他模型的 payload 里带过来一个 format 或 size 字段，任务甚至还没开始就会返回 400 INVALID_REQUEST: <root>: additional properties 'format' not allowed。

最小可运行示例：curl

创建任务：

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "851-labs/background-remover",
    "input": {
      "image_url": "https://your-cdn.example.com/product-shot.jpg"
    }
  }'

提交成功后会返回一个任务 id，位于 data 中：

{"code": 200, "data": {"taskId": "tk-hiapi-..."}}

轮询结果：

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-... \
  -H "Authorization: Bearer sk-<your-key>"

运行期间，data.status 会依次经过 queued → handling → archiving。完成后它会变为 "success"，透明 PNG 会出现在 data.output 中：

{
  "code": 200,
  "data": {
    "status": "success",
    "output": [{"url": "https://.../result.png", "expireAt": "..."}]
  }
}

输出 URL 是短时有效的（注意 expireAt）。任务成功后应立即下载文件字节 —— 不要热链或持久保存原始 URL。

生产可用的 Python：提交、轮询、下载

import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
API_KEY = "sk-<your-key>"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def remove_background(image_url: str) -> bytes:
    # 1. 创建任务
    resp = requests.post(API_BASE, headers=HEADERS, json={
        "model": "851-labs/background-remover",
        "input": {"image_url": image_url},
    }, timeout=60)
    body = resp.json()
    if resp.status_code != 200 or not (body.get("data") or {}).get("taskId"):
        raise RuntimeError(f"create failed [{resp.status_code}]: {body}")
    task_id = body["data"]["taskId"]

    # 2. 轮询直到进入终态
    deadline = time.time() + 300
    while time.time() < deadline:
        task = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS,
                            timeout=30).json().get("data") or {}
        if task.get("status") == "success":
            outputs = task.get("output") or []
            if not outputs or not outputs[0].get("url"):
                raise RuntimeError(f"task {task_id} succeeded but returned no output URL")
            # 3. 立即下载 —— URL 会过期
            png = requests.get(outputs[0]["url"], timeout=120)
            png.raise_for_status()
            return png.content
        if task.get("status") == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(3)
    raise TimeoutError(f"task {task_id} still running after 300s")


if __name__ == "__main__":
    png = remove_background("https://your-cdn.example.com/product-shot.jpg")
    with open("cutout.png", "wb") as f:
        f.write(png)
    print(f"saved cutout.png ({len(png)} bytes)")

背景移除属于轻量图像任务，通常远在 300 秒截止时间之内就能完成 —— 这个超时只是安全网，而不是预期运行时间。

用回调代替轮询

对于 Web 后端，建议在创建任务时注册回调，而不是在请求处理器中轮询。callback 对象位于顶层，与 model 同级：

{
  "model": "851-labs/background-remover",
  "input": { "image_url": "https://your-cdn.example.com/product-shot.jpg" },
  "callback": {
    "url": "https://your-app.example.com/hooks/hiapi",
    "when": "final"
  }
}

callback.when 仅支持 "final" —— 任务进入 success 或 fail 时你会恰好收到一次 POST，而不会收到进度事件。处理程序应以 taskId 为键，避免重复投递的 webhook 被重复处理，并定期扫一遍 GET /v1/tasks/<id>，检查你的端点从未确认过的 id。

错误处理：真正重要的错误

创建时返回 400 INVALID_REQUEST —— 错误消息会指出确切的字段：

消息	原因
invalid input: image_url: missing required field "image_url"	input 为空，或键名拼写错误
image_url: 'not-a-url' does not match pattern '^https?://[^\s]+$'	该值不是格式正确的 http(s) URL
<root>: additional properties 'format' not allowed	你发送了该模型不接受的字段

这些错误是永久性的 —— 重试相同的 payload 会永远失败。修正字段后重新发送。

创建时返回 401 permission_denied —— 问题出在 key 本身，而不是请求体：

{"error": {"code": "permission_denied", "message": "...", "request_id": "...", "type": "hiapi_error"}}

请在控制台中检查该 key 的模型权限。

任务返回 status: "fail" —— 创建成功但运行本身失败（通常是后端无法获取 image_url）。读取 data.error.code / message；这类失败可以安全地退避重试一次。

GET 一个未知或已过期的任务 id 会返回 404，内容为 {"code": 404, "data": null, "message": "task not found"} —— 在任何对账扫描中应把它视为终态，而不是“仍在等待”。

下一步

• 851-labs/background-remover 模型页面 —— 实时示例与当前价格。
• 用基于提示词的编辑移除图像背景 —— 基于 Seedream 的替代方案，适用于你不仅要去除背景、还要更改背景的场景。
• hiapi 异步任务 API 文档 —— 完整的创建/轮询/回调参考。
• hiapi 认证文档 —— API key 设置与请求头格式。
• 价格 —— 当前的每图费率。

常见问题

我需要提示词吗？ 不需要。只需提供一个 image_url，模型会自行分离前景与背景。

输出真的是透明的吗？ 是的 —— 结果是一张带 alpha 通道的 PNG，可直接合成到任意背景上。

我能在同一次调用中更改宽高比、颜色或背景吗？ 不能。该端点只移除背景。如需重新上色、调整尺寸或替换背景，请用这张透明 PNG 作为输入，再链式调用一个图像编辑模型。

为什么我会收到“additional properties '...' not allowed”？ 该 schema 只接受一个字段 image_url。任何从其他模型 payload 带过来的字段 —— format、size、background_color，任何字段 —— 都会被直接拒绝，而不是被静默忽略。

我应该如何保存结果？ 在任务达到 status: "success" 后立即下载。输出 URL 是签名 URL 且带有 expireAt；它不适合长期热链。

费用是多少？ 按每张图片用量计费。请在价格页面查看当前费率。