Recraft 去背景 API：一个可运行的示例

大多数去背景 API 都需要你选择一个通用图像编辑模型，再通过合适的提示词引导它抠出主体。recraft/remove-background 省去了这一步：它是一个专用模型，接收一个图片 URL，返回一张保留发丝与毛发级边缘细节的透明 PNG。没有提示词、没有反向提示词、没有强度参数——只需输入源图，输出抠图。

本指南走完一次完整、经过测试的调用：请求结构、你实际会收到的响应，以及让批处理任务不会因为某个边界情况而卡住的生产级模式（回调、幂等性、错误处理）。

前置条件：

• 从你的控制台获取 hiapi API key
• Python 3.9+ 并安装 requests（pip install requests），或直接使用 curl
• 你的源图位于一个公网 URL——hiapi 的任务 API 通过 URL 获取图片，而不是文件上传。格式为 PNG、JPG 或 WEBP，最大 5MB，最大 1600 万像素，两个维度均在 256 到 4096 像素之间。

请求

与 hiapi 上的所有生成模型一样，recraft/remove-background 通过共享的异步任务 API 运行：POST /v1/tasks 带上 model 和 input，你会立即收到一个 taskId，抠图在后台运行。完整契约——请求头、幂等键、状态码——已在创建任务中统一记录；模型相关的部分是 input，对此模型来说只有一个字段：

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "recraft/remove-background",
  "input": {
    "image_url": "https://static.hiapi.ai/model-covers/recraft-remove-background/2026/09/01/golden-input-2048.jpg"
  }
}'

import requests

payload = {
    "model": "recraft/remove-background",
    "input": {
        "image_url": "https://static.hiapi.ai/model-covers/recraft-remove-background/2026/09/01/golden-input-2048.jpg",
    },
}

response = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json=payload,
)
print(response.json())
# {"code": 200, "data": {"taskId": "tk-hiapi-..."}, "message": "success"}

image_url 是该模型唯一接受的字段——没有 format、response_format 或尺寸参数。发送其他任何内容，API 会在触达模型之前就以 schema 错误拒绝整个请求（见下方错误）。输出始终是透明 PNG。

轮询结果

取上述响应中的 taskId，轮询 GET /v1/tasks/{taskId}，直到 data.status 达到终态。状态枚举在平台上所有模型中一致：queued → handling → archiving → success（或 fail）。该模型的实际运行通常不到 10 秒即可完成：

import time

task_id = response.json()["data"]["taskId"]

while True:
    r = requests.get(
        f"https://api.hiapi.ai/v1/tasks/{task_id}",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
    )
    data = r.json()["data"]
    if data["status"] in ("success", "fail"):
        break
    time.sleep(2)

print(data)

状态为 success 时，data.output 是一个只含一个元素的数组：

{
  "status": "success",
  "output": [
    {
      "artifactId": "119426",
      "type": "image",
      "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M1RYTHQ5F94S2405YSC65EWM-0.png",
      "expireAt": 1789222580
    }
  ]
}

url 是临时链接——expireAt 是大约一周后的 Unix 时间戳，而不是永久 CDN 地址。任务一成功就下载字节并存入你自己的存储：

image_bytes = requests.get(data["output"][0]["url"]).content
with open("cutout.png", "wb") as f:
    f.write(image_bytes)

生产级模式

使用回调而不是循环轮询。 在创建时传入 callback.url，hiapi 会在任务完成时把最终结果 POST 给你，而不是让你在轮询循环里消耗请求：

payload = {
    "model": "recraft/remove-background",
    "callback": {"url": "https://example.com/hiapi/callback", "when": "final"},
    "input": {"image_url": "https://your-cdn.example.com/product-01.jpg"},
}

when: "final" 意味着你只会收到一次回调，在终态（success 或 fail）时触发，而不是每个中间状态各一次。对于一批产品照片来说，这是合适的默认设置，你不必为每张图维持一个轮询循环。

幂等性。 如果请求在你这边超时，但实际上已经到达 hiapi，使用相同的 Idempotency-Key 请求头重试（记录在创建任务中）会返回原始任务，而不会对第二次抠图计费。对于任何在网络错误时重试的批处理任务都值得设置。

错误——两种形态，而非一种。 格式错误的请求和认证失败会以不同的信封返回，只检查其中一种的代码会静默吞掉另一种：

// 输入错误（schema 校验）—— HTTP 400
{"code": 400, "data": null, "error_code": "INVALID_REQUEST", "message": "invalid input: image_url: missing required field \"image_url\""}

// API key 无效或已过期 —— HTTP 401
{"error": {"code": "permission_denied", "message": "This API key is invalid...", "request_id": "...", "type": "hiapi_error"}}

先检查 error_code，再回退到 error.code——不要假设所有失败都有相同的顶层键。

定价。 每张图片 $0.01（20 credits），无论输入分辨率如何，统一计价。当前价格始终在定价页面上。

当你需要替换背景，而不仅仅是抠图时

recraft/remove-background 只生成透明抠图——不填充、不带场景。如果目标是在同一次调用中换成影棚背景或生活方式场景，那就是另一项任务：使用一个图生图模型，提示它在保留主体的周围重新生成背景。查看用 API 去除图片背景：基于提示词的编辑了解该方法，以及何时值得为此支付比普通抠图更高的成本。

常见问题

recraft/remove-background 接受提示词或强度参数吗？ 不接受。schema 是严格的——image_url 是唯一接受的字段。发送 format 或 response_format 之类的额外字段会返回 400，并附带 "additional properties not allowed" 消息。

支持哪些图片格式和尺寸？ 输入：PNG、JPG 或 WEBP，最大 5MB，最大 1600 万像素，两个维度均在 256 到 4096 像素之间。输出始终是带 alpha 通道的 PNG。

我可以上传本地文件而不是 URL 吗？ 不可以——image_url 必须是一个 hiapi 服务器可以获取的公网 http(s):// URL。请先上传到对象存储或 CDN。

输出 URL 的有效期是多久？ 每个输出条目上的 expireAt 字段是 Unix 时间戳，通常大约一周后。将其视为临时链接，任务成功后立即把字节复制到你自己的存储——不要长期保存 temp.hiapi.ai 链接。

这适用于批处理数百张产品照片吗？ 是的——为每张图提交一个任务，共享一个 callback.url，让 hiapi 把结果推送回来，而不是逐个轮询。按 $0.01/图计算，一次 1,000 张图的目录处理在生成上花费 $10。