进阶 docs.leonardo.ai 2026-11-22 15:11:20 · 0 阅读

第10章 从 remove.bg API 迁移至 Leonardo.Ai

从 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 个月前。此页面对您有帮助吗?

评论 (0)