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

第8章 使用 Leonardo.AI API 移除图片背景

移除背景本指南介绍如何通过 Leonardo.AI REST API 调用 Remove bg 模型来移除图片背景。Leonardo 提供两种调用该模型的方式: Sync API(推荐用于单张图片处理)。单次请求即可在响应中返回处理后的图片,无需轮询。由于请求最长可能需要约 27 秒才会触发服务超时,因此对于可能超时的任务,请使用 Async API。 Async API。先提交任务,待处理完成后再获取结果。适用于批处理、超大尺寸图片,以及不适合长时间保持连接的场景。 两种方式下的请求体结构完全一致,均使用相同的模型、参数和图片引用,区别仅在于 ephemeral 和 base64 参数仅在 Sync API 中可用。parameters 下若出现未知字段,将被拒绝而非忽略。
请求示例 同步 API curl --location 'https://cloud.leonardo.ai/api/rest/v2/generationssync' \ --header 'authorization: Bearer {api-key}' \ --header 'Content-Type: application/json' \ --data '{ "model": "remove-bg", "public": false, "ephemeral": true, "parameters": { "size": "auto", "type": "auto", "format": "png", "guidances": { "image_reference": [ { "image": { "id": "YOUR_IMAGE_ID", "type": "UPLOADED" } } ] } } }' 异步 API curl --location 'https://cloud.leonardo.ai/api/rest/v2/generations' \ --header 'authorization: Bearer {api-key}' \ --header 'Content-Type: application/json' \ --data '{ "model": "remove-bg", "public": false, "parameters": { "size": "auto", "type": "auto", "format": "png", "guidances": { "image_reference": [ { "image": { "id": "YOUR_IMAGE_ID", "type": "UPLOADED" } } ] } } }' API 请求端点、请求头与参数 端点 同步 API — 响应中包含处理后的图片(默认返回 url,base64 为 true 时返回 dataB64)。请求可能需要约 27 秒,超过后服务会超时: https://cloud.leonardo.ai/api/rest/v2/generationssync 异步 API — 响应会立即返回一个 generation ID;任务完成后可通过该 ID 获取生成结果,也可以配置 webhook 回调地址来接收结果,无需轮询: https://cloud.leonardo.ai/api/rest/v2/generations 请求头 两个端点使用相同的请求头: --header "accept: application/json" \ --header "authorization: Bearer " \ --header "content-type: application/json" 请求体参数 参数 | 类型 | 说明 base64 | boolean | 可选。仅同步 API 可用。设为 true 时,响应返回 results[].dataB64 而非 results[].url。如果编码后的数据超过响应大小限制,请求会失败。默认 false。 ephemeral | boolean | 可选。仅同步 API 可用。设为 true 时,结果不会保存到你的 Leonardo 图库,响应中的 URL 是一个 30 分钟有效的预签名 GET 链接。默认 false。 model | string | 必填。固定为 remove-bg。 parameters.bg_color | string | 可选。为抠图结果添加纯色背景,支持十六进制色值或颜色名称。输出不再是透明背景——建议尽量搭配 jpg 格式使用。 parameters.channels | string | 可选。设为 rgba 返回抠图图像,设为 alpha 则只返回灰度 alpha 蒙版。默认 rgba。 parameters.crop | boolean | 可选。设为 true 时,输出图像会裁剪到主体边界框。默认 false。 parameters.crop_margin | string | 可选。裁剪后主体周围的留白边距,可以是绝对值(30px)或相对主体大小的百分比(10%)。支持 1 个、2 个或 4 个值。仅在启用 crop 时生效。 parameters.format | string | 可选。输出图像格式,可选 png、jpg 或 webp。PNG 和 WebP 保留透明度,JPG 不保留。PNG 输出上限为 10 百万像素,因此更大的 size 建议搭配 webp 以保留透明度。默认 png。 parameters.guidances.background_image_reference | array | 可选。恰好包含 1 张图片的数组,用于合成到抠图结果后方,替换被移除的背景。省略此参数则背景保持透明(或通过 bg_color 设置纯色背景)。每一项的 image 对象格式与 image_reference 相同。 parameters.guidances.image_reference | array | 必填。恰好包含 1 张待去背景图片的数组。每一项指定一个 image 对象,包含类型(UPLOADED、GENERATED、VARIATION、URL 或 BASE64)以及对应的来源字段:图片已在 Leonardo 图库中时用 id;type 为 URL 时用 url(图片 URL 或 base64 data URL);type 为 BASE64 时用 data(base64 编码的图片字节)。可选的 order 整数用于设置引导顺序。 parameters.position | string | 可选。主体在输出画布中的位置,可选 original、center、单个百分比,或分别表示水平和垂直位置的两个百分比。 parameters.quantity | integer | 可选。生成结果的数量。固定为 1。默认 1。 parameters.roi | string | 可选。用于搜索主体的感兴趣区域,以两个 x/y 坐标对表示,单位为像素(0px 0px 100px 100px)或百分比(0% 0% 100% 100%)。该矩形之外的内容视为背景。 parameters.scale | string | 可选。主体相对于输出画布的大小,可选 original 或 10% 到 100% 之间的百分比。 parameters.semitransparency | boolean | 可选。保留半透明区域,如玻璃、烟雾和纱质物。默认 true。 parameters.shadow_opacity | integer | 可选。人工阴影的不透明度,取值 0 到 100。仅在启用阴影时生效。 parameters.shadow_type | string | 可选。主体下方渲染的人工阴影样式,可选 none、drop、3d 或 car。默认 none。 parameters.size | string | 可选。输出图像的最大分辨率,可选 auto、preview、full 或 50MP。无论此设置如何,PNG 输出上限均为 10 百万像素。默认 auto。 parameters.type | string | 可选。前景类型提示,用于提高抠图质量。可选 auto、person、product、car、animal、graphic、transportation 或 other。默认 auto。 parameters.type_level | string | 可选。主体分类的精细程度。设为 none 跳过分类,1 为粗略类别,2 为具体类别,latest 为可用的最精细分类。 public | boolean | 可选。设为 false 保持结果私密。ephemeral 为 true 时忽略此参数。 响应 同步 API 同步 API 始终返回包含处理后图像的 JSON。 { "id": "b3a6c1d2-…", "blockedCount": 0, "cost": { "amount": "0.1047", "unit": "DOLLARS" }, "results": [ { "url": "https://…", "contentType": "image/png", "width": 1024, "height": 768 } ] } 字段 | 说明 id | 本次生成的标识符。联系客服时请附上此 ID。 results | 输出结果数组——每个通过内容审核的输出对应一项,因此可能为空。访问 results[0] 前请做好判空处理。 results[0].url | 存储图像的 CDN URL;ephemeral 为 true 时返回 30 分钟有效的预签名 URL。base64 为 true 时省略此字段。 results[0].dataB64 | base64 编码的图像字节。仅当请求中 base64 设为 true 时存在。 results[0].contentType | 生成图像的媒体类型,例如 image/png。 results[0].width / results[0].height | 输出尺寸(像素),由服务提供商提供时返回。 cost | 本次生成的费用(amount 加上单位 CREDITS 或 DOLLARS)。生产环境 API 用户可见。 blockedCount | 被内容审核拦截的输出数量。 异步 API 异步 API 会立即返回生成 ID: { "generationId": "b3a6c1d2-…", "apiCreditCost": 1 } 字段 | 说明 generationId | 生成任务的唯一标识符。任务完成后可通过此 ID 获取生成结果。 apiCreditCost | 本次生成消耗的 API 积分。生产环境 API 用户可见。 任务完成后可通过 ID 获取生成结果——持久化的结果包含长效的 CDN URL——也可以配置 webhook 回调地址,实时接收生成结果而无需轮询。 更新于 3 个月前  此页面对你有帮助吗?

评论 (0)