背景移除 API

bgly API 是异步接口：先提交抠图请求并保存任务 ID，再轮询直到成功或失败。

创建或管理 API Key

Base URL

https://bgly.net/api/v1

鉴权

在 设置 → API Keys 创建密钥。每个请求都需要携带：

Authorization: Bearer sk_your_api_key

只有购买过套餐或积分的用户可以使用 API。完整密钥只在创建时展示一次。

计费

• 网页和 API 共用同一个积分余额。
• 标准处理消耗 1 积分。HD（precision: "high"）消耗 2 积分。
• 创建任务时预扣积分；失败会退回。
• 付费 API 用户直接获得完整分辨率结果链接，下载不再额外扣费。

创建抠图任务

POST /bg/removals

curl -X POST 'https://bgly.net/api/v1/bg/removals' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: demo-request-001' \
  -d '{
    "model": "bg-remover",
    "image_url": "https://example.com/photo.jpg",
    "subject": "auto",
    "precision": "standard",
    "output_format": "png"
  }'

提交成功返回 HTTP 202：

{
  "id": "task_xxx",
  "object": "bg.removal",
  "model": "bg-remover",
  "status": "queued",
  "input": {
    "image_url": "https://example.com/photo.jpg",
    "subject": "auto",
    "precision": "standard",
    "output_format": "png"
  },
  "output": null,
  "usage": null,
  "error": null
}

请求字段

字段	类型	必填	说明
image_url	string	是	源图的公开 HTTP(S) URL
model	string	否	若传则必须为 bg-remover
subject	string	否	auto（默认）、product、portrait 或 hair
precision	string	否	standard（默认，1 积分）或 high（HD，2 积分）。hd 视为 high。
output_format	string	否	png（默认）或 webp

建议携带 Idempotency-Key。相同 key + 相同请求体会返回原任务且不再扣费；换了请求体则返回 HTTP 409。

当前版本只接受公开图片 URL，暂不支持 multipart 上传。

查询任务状态

GET /bg/removals/{task_id}

curl 'https://bgly.net/api/v1/bg/removals/task_xxx' \
  -H 'Authorization: Bearer YOUR_API_KEY'

建议每 2–5 秒轮询一次。成功时返回：

{
  "id": "task_xxx",
  "object": "bg.removal",
  "model": "bg-remover",
  "status": "succeeded",
  "output": {
    "url": "https://cdn.bgly.net/.../output.png",
    "width": 1600,
    "height": 1200,
    "format": "png"
  },
  "usage": { "credits": 1 },
  "error": null
}

状态包括 queued、processing、succeeded、failed、canceled。

结果 URL 可能过期，如需本地文件请尽快下载。

JavaScript 示例

const headers = {
  Authorization: `Bearer ${process.env.BGLY_API_KEY}`,
  'Content-Type': 'application/json',
  'Idempotency-Key': crypto.randomUUID(),
};

const created = await fetch('https://bgly.net/api/v1/bg/removals', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    image_url: 'https://example.com/photo.jpg',
    precision: 'standard',
  }),
}).then((response) => response.json());

const task = await fetch(`https://bgly.net/api/v1/bg/removals/${created.id}`, {
  headers: { Authorization: headers.Authorization },
}).then((response) => response.json());

Python 示例

import os
import uuid
import requests

base_url = "https://bgly.net/api/v1"
headers = {
    "Authorization": f"Bearer {os.environ['BGLY_API_KEY']}",
    "Idempotency-Key": str(uuid.uuid4()),
}

created = requests.post(
    f"{base_url}/bg/removals",
    headers=headers,
    json={"image_url": "https://example.com/photo.jpg"},
).json()

task = requests.get(
    f"{base_url}/bg/removals/{created['id']}",
    headers={"Authorization": headers["Authorization"]},
).json()

错误

错误使用标准 HTTP 状态码和统一结构：

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient credits",
    "request_id": "request_xxx"
  }
}

HTTP	Code	含义
400	invalid_request	请求参数无效
401	invalid_api_key	缺少、无效或已删除的 API Key
402	insufficient_credits	积分不足
403	api_access_required	需要付费套餐或积分购买
404	task_not_found	任务不存在或不属于当前用户
409	idempotency_conflict	幂等键被用于不同请求
429	rate_limit_exceeded / concurrency_limit	请求过频，或并发任务过多

机器可读的 OpenAPI 文件位于 https://bgly.net/openapi.json。