从 remove.bg API 迁移到 Leonardo.Ai
背景移除功能现已通过 Leonardo.Ai API 提供。本指南介绍两个 API 之间的差异,以及迁移所需的代码改动。
Leonardo 提供两种方式:
- Sync API(从 remove.bg 迁移时推荐)。单个请求即可在响应中返回处理后的图片,无需轮询。本指南主要介绍 Sync API。
- Async API。先提交任务,等完成后再获取结果。适合批量处理、超大图片,以及不适合长时间保持连接的场景。详见 Async API 文档。
改动一览
|
| remove.bg API |
Leonardo Sync API |
| Endpoint |
POST https://api.remove.bg/v1.0/removebg |
POST https://cloud.leonardo.ai/api/rest/v2/generationssync |
| Auth |
X-Api-Key: |
Authorization: Bearer |
| Request body |
multipart/form-data 或 JSON |
仅 JSON(application/json) |
| Model |
隐式指定 |
显式指定:"model": "remove-bg" |
| Source image |
image_file / image_url / image_file_b64 表单字段 |
parameters.guidances.image_reference 中的一个图片对象:URL、base64 或已上传的图片 ID |
| Max input size |
22MB |
输入 URL / BASE64 / 上传:最高 25MB。
|
| Output data |
B64(仅在 "base64": true 时):像素量不超过约 7.45MB,否则调用失败 |
| Options(size、type、bg_color 等) |
顶层表单字段 |
字段名相同,嵌套在 parameters 下 |
| Response |
默认返回原始图片字节(可选 JSON) |
始终返回 JSON。默认取 results[0].url。
|
使用 `"base64": true` 时:获取 `results[0].dataB64`(无 url 字段)
结果存储
默认不保留任何文件
默认保存在你的 Leonardo 库中:设置 `ephemeral: true` 可获取 30 分钟有效期的 URL,库中不保留任何文件
输出格式
png、jpg、webp、zip
自动处理
png、jpg、webp(不支持 zip 和 auto)
费用报告
`X-Credits-Charged` 请求头
响应体中的 cost 对象(美元 $)
以下三项变更覆盖了大多数集成场景:
1. 新的端点和鉴权头。
2. 请求变为 JSON 格式。文件需 Base64 编码,选项值保持不变并移至 parameters 字段下。
3. 响应为 JSON 格式。默认下载 `results[0].url`。如需在响应中获取字节数据,设置 `"base64": true` 并解码 `results[0].dataB64`。
准备工作
你需要一个拥有 API 访问权限的 Leonardo 账号。前往 app.leonardo.ai 的 API 访问页面创建 API 密钥,并在每个请求中将其作为 Bearer 令牌发送。
背景移除每张图像收费 0.1047 美元。每个响应都会包含该次调用的费用。最新定价:https://app.leonardo.ai/api-access/pricing-calculator
五分钟迁移指南
迁移前,remove.bg 配合图像 URL 的调用方式:
```bash
curl -H 'X-Api-Key: YOUR_KEY' \
-F 'image_url=https://www.remove.bg/example.jpg' \
-F 'size=auto' \
-f https://api.remove.bg/v1.0/removebg -o no-bg.png
```
迁移后,Leonardo 同步 API:
```bash
curl --request POST \
--url https://cloud.leonardo.ai/api/rest/v2/generationssync \
--header 'accept: application/json' \
--header 'authorization: Bearer YOUR_LEONARDO_API_KEY' \
--header 'content-type: application/json' \
--data '{
"model": "remove-bg",
"ephemeral": true,
"parameters": {
"size": "full",
"format": "png",
"guidances": {
"image_reference": [
{ "image": { "type": "URL", "url": "https://www.remove.bg/example.jpg" } }
]
}
}
}' | jq -r '.results[0].url'
```
流程保持不变:单次请求即可返回图像。主要的结构差异在于:源图像和选项被移入 JSON 请求体,且输出格式为 JSON。默认返回 URL;如需在响应体中获取字节数据,请设置 `"base64": true`。
常见集成场景
在下方找到你当前的集成方式,查看对应的具体变更。
当前集成方式 | 查看位置 | 输入 image_url,输出图像文件(二进制) | 场景 1
输入 image_file 上传,输出图像文件 | 场景 2
输入 image_file_b64,输出 JSON | 场景 3
输出 format=zip | 场景 4
bg_image_file | 场景 5
场景 1:输入图像 URL,输出图像文件
即上方五分钟迁移指南中展示的请求。需变更及注意的事项如下:
- URL 从 `image_url` 表单字段移至 `parameters.guidances.image_reference[0].image`,并指定 `"type": "URL"`。
- 仅支持 HTTPS URL;Leonardo 抓取图像的极限约为 20MB。
- 响应为 JSON 而非原始字节。默认获取 `results[0].url`(当 `ephemeral: true` 时,该链接有效期为 30 分钟)。如需内联字节数据,添加 `base64: true` 并解码 `results[0].dataB64`。
- 如果当前使用 `format=auto`,请显式指定格式:透明背景用 png 或 webp,否则用 jpg。
- 设置 `"ephemeral": true` 以匹配 remove.bg 不存储图像的行为。默认情况下,结果会保存到你的 Leonardo 库中。
- 每次调用的费用包含在响应体中,不再通过 `X-Credits-Charged` 头返回。
响应示例
默认结果 url:
```json
{
"id": "b3a6c1d2-…",
"blockedCount": 0,
"cost": { "amount": "0.1047", "unit": "DOLLARS" },
"results": [
{
"url": "https://…",
"contentType": "image/png",
"width": 1024,
"height": 768
}
]
}
```
设置 `base64: true` 时:
```json
{
"id": "b3a6c1d2-…",
"blockedCount": 0,
"cost": { "amount": "0.1047", "unit": "DOLLARS" },
"results": [
{
"dataB64": "iVBOR…",
"contentType": "image/png",
"width": 1024,
"height": 768
}
]
}
```
将图像写入磁盘:
```bash
# 默认 (url)
curl … | jq -r '.results[0].url'
# 设置 "base64": true 后
curl … | jq -r '.results[0].dataB64' | base64 --decode > no-bg.png
```
场景 2:上传文件,输出图像文件
同步 API 不接受 `multipart/form-data`,因此无法直接附加文件。
对于小于约 7.5MB 的文件,将文件 Base64 编码并放入 JSON 请求体中即可,仅需代码变更,无需额外请求。
迁移前,remove.bg (Python):
```python
import requests
response = requests.post(
'https://api.remove.bg/v1.0/removebg',
files={'image_file': open('/path/to/file.jpg', 'rb')},
data={'size': 'auto'},
headers={'X-Api-Key': 'YOUR_KEY'},
)
if response.status_code == requests.codes.ok:
with open('no-bg.png', 'wb') as out:
out.write(response.content)
```
迁移后,Leonardo 同步 API (Python):
```python
import base64, requests
with open('/path/to/file.jpg', 'rb') as f:
image_b64 = base64.b64encode(f.read()).decode()
response = requests.post(
'https://cloud.leonardo.ai/api/rest/v2/generationssync',
headers={'Authorization': 'Bearer YOUR_LEONARDO_API_KEY'},
json={
'model': 'remove-bg',
'ephemeral': True,
'base64': True,
'parameters': {
'size': 'auto',
'format': 'png',
'guidances': {
'image_reference': [
{'image': {'type': 'BASE64', 'data': image_b64}}
]
}
}
},
)
if response.ok:
results = response.json()['results']
with open('no-bg.png', 'wb') as out:
out.write(base64.b64decode(results[0]['dataB64']))
else:
print('Error:', response.status_code, response.text)
```
Node.js:
```javascript
import fs from "node:fs";
const imageB64 = fs.readFileSync("/path/to/file.jpg").toString("base64");
const response = await fetch("https://cloud.leonardo.ai/api/rest/v2/generationssync", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_LEONARDO_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "remove-bg",
ephemeral: true,
base64: true,
parameters: {
size: "auto",
format: "png",
guidances: {
image_reference: [{ image: { type: "BASE64", data: imageB64 } }],
},
},
}),
});
if (response.ok) {
const { results } = await response.json();
fs.writeFileSync("no-bg.png", Buffer.from(results[0].dataB64, "base64"));
} else {
throw new Error(`${response.status}: ${await response.text()}`);
}
```
注意事项:
- 输入支持 BASE64 / URL / 上传,图像上限为 25MB。这与输出 `dataB64` 的限制不同,后者仅适用于小于约 7.45MB 像素的数据。对于较大的输出,请省略 base64 并使用 URL。
- 发送原始图像字节需 Base64 编码,不加 `data:` 前缀。在 Shell 中可使用 `base64 -w0 file.jpg` 生成编码字符串。
- 场景 1 中关于响应和存储的说明同样适用。
- 如果需重复处理同一源图像,或希望将输入存储在你的 Leonardo 库中,请通过 `init-image` 端点上传一次,并引用返回的 ID:`{ "type": "UPLOADED", "id": "
" }`。
场景 3:输入 Base64,输出 JSON
这是最接近的匹配项,集成结构无需改变。只需进行三处重命名:
- 请求:`image_file_b64` 变为 `parameters.guidances.image_reference` 下的图像对象 `{ "type": "BASE64", "data": … }`。源图像需小于约 7.5MB;更大文件建议作为 URL 传递。
- 响应:默认获取 `results[0].url`。设置 `"base64": true` 时获取 `results[0].dataB64`。
- 费用:从响应体中的 cost 对象读取,而非 `X-Credits-Charged` 头。
场景 4:ZIP 输出
不支持 ZIP 格式(color.jpg + alpha.png)。请直接请求最终格式(透明背景用 png 或 webp),并从流水线中移除客户端合成步骤。如果单独使用 alpha 蒙版,支持 `channels` 参数(alpha)。
场景 5:替换背景图像
`bg_image_url` 变为 `guidances.background_image_reference`:重命名后变为图像对象数组,并置于 `parameters.guidances` 下,而非与其他选项并列:
```json
"parameters": {
"format": "png",
"guidances": {
"image_reference": [
{ "image": { "type": "URL", "url": "https://assets.leonardo.ai/xxwm-YUEYUO43E2f_example.jpg" } }
],
"background_image_reference": [
{ "image": { "type": "URL", "url": "https://example.com/background.jpg" } }
]
}
}
```
`bg_image_file` 无直接对应项——背景图像无法附加或内联在请求中。请自行托管该图像,并作为 `background_image_reference` (URL / BASE64 / UPLOADED) 传入。不要发送 `parameters.bg_image_url`。
请求结构
```json
{
"model": "remove-bg",
"ephemeral": true,
"public": false,
"parameters": {
"format": "png",
"size": "auto",
"guidances": {
"image_reference": [
{ "image": { /* 一种输入模式 */ } }
]
}
}
}
```
- model (必填) — 始终为 `"remove-bg"`。
- ephemeral (可选,默认 false) — 控制输入和输出是否保留在你的 Leonardo 库中。参见结果存储与隐私。
- public (可选,默认 false) — 控制 Feed 可见性;仅在结果被持久化时相关。
- parameters (必填) — 包含你的 remove.bg 选项及源图像。
每个图像对象仅提供一种源——不要混合字段:
remove.bg 字段 | Leonardo 图像对象 | 大小限制
`image_url` | `{ "type": "URL", "url": "https://assets.leonardo.ai/xxwm-YUEYUO43E2f_example.jpg" }` | 最多约 25MB
`image_file_b64` | `{ "type": "BASE64", "data": "" }` | 小于约 7.5MB
`image_file=@file` | 将文件 Base64 编码 (BASE64),或上传一次并使用 `{ "type": "UPLOADED", "id": "" }` | Base64 小于约 7.5MB;上传最多约 25MB
Leonardo 中已有的图像也可作为源:UPLOADED(已上传图像)、GENERATED(生成图像)和 VARIATION(变体输出)。
参数映射
选项值保持不变,仅移至 parameters 下。
remove.bg | Leonardo | 说明
`size` | `parameters.size` | 值相同:preview, auto, full, 50MP
`type` | `parameters.type` | 主题提示相同:auto, person, product, car, animal, graphic, transportation, other
`type_level` | `parameters.type_level` | 不变
`format` | `parameters.format` | png, jpg, webp。不支持 zip 或 auto
`channels` | `parameters.channels` | 不变 (rgba / alpha)
`bg_color` | `parameters.bg_color` | 不变
`crop` / `crop_margin` | `parameters.crop` / `parameters.crop_margin` | 不变
`roi` | `parameters.roi` | 不变
`scale` / `position` | `parameters.scale` / `parameters.position` | 不变
`semitransparency` | `parameters.semitransparency` | 不变
`shadow_type` / `shadow_opacity` | `parameters.shadow_type` / `parameters.shadow_opacity` | 不变
`add_shadow` | — | 已在 remove.bg 中废弃;使用 shadow_type + shadow_opacity
`bg_image_url` | `guidances.background_image_reference` | 移至 guidances
`bg_image_file` | — | 无对应项——托管图像并使用 guidances.background_image_reference——参见场景 5
响应
始终为 JSON;无原始字节响应模式。
```json
{
"id": "b3a6c1d2-…",
"blockedCount": 0,
"cost": { "amount": "0.1047", "unit": "DOLLARS" },
"results": [
{
"contentType": "image/png",
"url": "https://…",
"width": 1234,
"height": 567
}
]
}
```
- id — 请求 ID;联系支持时请提供此 ID。
- results — 输出数组。背景移除返回一项。
- `results[0].dataB64` — 仅当 `"base64": true` 时存在。
- `results[0].url` — 默认路径。`ephemeral: false` 时为持久化 CDN URL;`ephemeral: true` 时为 30 分钟有效的 S3 GET。当 `"base64": true` 时省略。
- `results[0].contentType` — 例如 image/png。
- `results[0].width` / `results[0].height` — 可用时的输出尺寸。
- cost — 本次调用的美元费用。
- blockedCount — 此模型通常为 0。
remove.bg 响应数据在 Leonardo Sync 中的对应:
remove.bg | Leonardo Sync
原始图像字节 (默认) | 下载 `results[0].url`。内联:设置 `"base64": true` 后使用 `results[0].dataB64`
`data.result_b64` (JSON 模式) | `results[0].dataB64` — 解码为字节
Content-Type 头 | `results[0].contentType`
X-Width / X-Height 头 | `results[0].width` / `height`
X-Credits-Charged 头 | 响应体中的 cost 对象 (美元)
X-Type (检测的前景) | 无对应项
X-Foreground-Top/Left/Width/Height (及 JSON foreground_*) | 无对应项
结果存储与隐私
默认存储行为与 remove.bg 不同。remove.bg 不存储任何数据;Leonardo 默认将输入和输出持久化到 Leonardo 库和 CDN (ephemeral: false)。
若要复制 remove.bg 的行为(调用后不留存任何数据),请设置:
`"ephemeral": true`
设置 `ephemeral: true` 后,不会为输入或输出创建持久的库资产;响应返回 30 分钟有效的 url。如需获取 dataB64 替代该 url,请添加 `"base64": true`。
默认 `ephemeral: false` 时,结果将持久化到你的库并附带 CDN URL,`public` 控制 Feed 可见性。
无论设置如何,使用量均会被计量;该标志仅控制图像是否保留,不影响计费。处理用户图像时请审阅此设置。
错误、速率限制与重试
错误处理遵循相同模式:Hasura 通常返回 HTTP 200 并附带 `errors[]`。读取 `errors[0].message` 以及 `extensions.statusCode` / `extensions.code`(例如 BAD_REQUEST)。不要仅依赖 HTTP 4xx 状态码。
尚未支持的功能
remove.bg 功能 | Leonardo 状态
`format=zip` | 不支持。直接请求 png 或 webp (场景 4)
`format=auto` | 不支持。显式指定 png, jpg 或 webp
`bg_image_file` | 无对应项——托管图像并使用 `guidances.background_image_reference`——参见场景 5
响应中的原始图像字节 | 不支持。响应始终为 JSON。默认为 url;仅当 `"base64": true` 时提供 dataB64
`multipart/form-data` 请求 | 不支持。仅限 JSON;输入 BASE64/URL/上传最多 25MB。输出 dataB64 有单独的约 7.45MB 上限
X-Type 及前景位置元数据 | 不支持
`POST /improve` (图像贡献) | 不支持
OAuth 2.0 最终用户登录 | 不支持。使用账号 API 密钥进行鉴权
异步 API
同步 API 是与 remove.bg 最接近的匹配。Leonardo 的生产 API 也支持异步背景移除,适用于批处理、超大图像以及不应保持连接打开的流水线。
流程:
1. POST 至 `https://cloud.leonardo.ai/api/rest/v2/generations`,使用与同步 API 相同的请求体(相同的 model, parameters, 及图像引用)。不要发送 ephemeral 或 base64。
2. 响应立即返回生成 ID。
3. 完成时通过 ID 获取生成结果。持久化的结果包含持久 CDN URL。
4. 可选:配置 Webhook 回调 URL 以实时接收生成结果,替代轮询。
请求体相同,因此在同步和异步之间切换只需极少变更。相同的请求格式还可访问 Leonardo 的其他图像、视频、3D、Blueprint 和音频模型。
迁移检查清单
- 创建 Leonardo API 密钥,将 `X-Api-Key` 替换为 `Authorization: Bearer `。
- 将请求指向 `POST https://cloud.leonardo.ai/api/rest/v2/generationssync`。
- 发送 `Content-Type: application/json`,并包含 `"model": "remove-bg"`。
- 将源图像移至 `parameters.guidances.image_reference`:小于约 7.5MB 的文件用 base64,更大文件用 URL 或上传后引用。
- 将选项移至 `parameters` 下:值保持不变。
- 将 `format=auto` / `format=zip` 替换为显式的 png, jpg 或 webp。
- 下载 `results[0].url`,或设置 `"base64": true` 并解码 `results[0].dataB64`;从 cost 对象读取费用 (美元),替代 `X-Credits-Charged`。
- 如需 remove.bg 式的无存储行为,请设置 `"ephemeral": true`。
- 保留 429/5xx 重试逻辑;将错误解析更新为 Leonardo 的错误结构。
- 如果使用 `bg_image_file` 或 ZIP 输出,切换前请审阅“尚未支持”部分。
更新于 3 个月前。此页面对您有帮助吗?