UapiProUApiPro
图像

图片抠图（背景移除）

0次调用
1 积分/次

还在用套索工具一点点抠图？或者想给应用加个一键制作证件照的功能？这个接口能帮你全自动识别图片主体，瞬间剥离复杂背景。

POST
uapis.cn
/api/v1/image/matting
Body
file
file

待抠图的本地图片文件。支持 PNG、JPEG、WebP 等常见格式。请勿与 url 或 image_base64 同时提交。

拖动文件到此处，或点击上传

待抠图的本地图片文件。支持 PNG、JPEG、WebP 等常见格式。请勿与 url 或 image_base64 同时提交。

url
string

公网可直接访问的图片地址。请勿与 file 或 image_base64 同时提交。

image_base64
string

图片的 Base64 字符串。可以携带完整的 Data URI 前缀。请勿与 file 或 url 同时提交。

image_name
string

自定义图片文件名。传链接或纯 Base64 时建议一起传，便于保留扩展名特征；此名称也会体现在响应结构中。

model
string

选择底层图像分割模型。不传时默认使用 u2net。

output
string

输出内容的形态。不传时默认输出 cutout。

background_color
string

合成的底色。仅在 output=background 时生效。

threshold
number

alpha 二值化阈值，范围 [0, 1)。设置大于 0 时会滤除半透明像素，边缘更锐利。不传则保持原生渐变。

feather_px
integer

对 alpha 蒙版进行高斯羽化的像素半径，范围 [0, 64]。边缘显得生硬时可以用来柔化边缘。

out_format
string

期望返回的图片文件格式。不传默认 png。注意 jpeg 格式不支持透明。

jpeg_quality
integer

JPEG 压缩质量，范围 1 到 100。仅在 out_format=jpeg 时才生效。

功能概述

只需提供一张图片，接口会在云端跑强大的分割模型，并直接返回处理好的结果。接口支持高度的定制化，你可以：

  • 选择分割模型 (model)：根据图片类型，在“通用”、“轻量快速”、“人像特化”及“高锐利度边缘”等模型之间自由切换。
  • 自定义输出内容 (output)：默认返回一张清爽的透明背景主体图（cutout）。如果需要做进一步的设计处理，你也可以选择获取灰度的 alpha 蒙版（mask），或是直接将主体合成到指定的纯色背景上（background）。
  • 细节精修：提供 threshold (二值化去半透明) 与 feather_px (高斯羽化) 两种精修参数，让抠出来的边缘更自然贴合。

使用须知

互斥的图片输入：为了防止冲突，file、url 和 image_base64 三种输入方式只能选择其中一种进行提交。

输出格式限制：如果你指定了输出图片格式为 jpeg，由于 JPEG 不支持透明通道，因此你必须同时将输出模式设置为 output=background，否则请求会报错。

大小限制：单张上传的图片大小上限为 16MB。

请求体

包含待抠图图像及可选渲染参数的表单数据。请求需采用 multipart/form-data 格式。

file
file可选

待抠图的本地图片文件。支持 PNG、JPEG、WebP 等常见格式。请勿与 url 或 image_base64 同时提交。

url
string可选

公网可直接访问的图片地址。请勿与 file 或 image_base64 同时提交。

image_base64
string可选

图片的 Base64 字符串。可以携带完整的 Data URI 前缀。请勿与 file 或 url 同时提交。

image_name
string可选

自定义图片文件名。传链接或纯 Base64 时建议一起传，便于保留扩展名特征；此名称也会体现在响应结构中。

model
string可选

选择底层图像分割模型。不传时默认使用 u2net。

output
string可选

输出内容的形态。不传时默认输出 cutout。

background_color
string可选

合成的底色。仅在 output=background 时生效。

threshold
number可选

alpha 二值化阈值，范围 [0, 1)。设置大于 0 时会滤除半透明像素，边缘更锐利。不传则保持原生渐变。

feather_px
integer可选

对 alpha 蒙版进行高斯羽化的像素半径，范围 [0, 64]。边缘显得生硬时可以用来柔化边缘。

out_format
string可选

期望返回的图片文件格式。不传默认 png。注意 jpeg 格式不支持透明。

jpeg_quality
integer可选

JPEG 压缩质量，范围 1 到 100。仅在 out_format=jpeg 时才生效。

响应

200 / 请求成功

抠图成功，返回结果图片的 Base64 数据与基础图像信息。

JSON
{
  // 处理后的结果图片 Base64 字符串（不含 Data URI 前缀，可直接渲染或保存）。
  "image_base64": "string",
  // 结果图片文件名。仅当请求中传入了 image_name 或上传了 file 时才会返回。
  "image_name": "product-01.png",
  // 实际响应的图片格式。
  "format": "png",
  // 结果图片的实际宽度（像素）。
  "width": 800,
  // 结果图片的实际高度（像素）。
  "height": 800,
  // 本次推理实际命中的分割模型。
  "model": "u2net",
  // 实际使用的输出模式。
  "output": "cutout",
  // 图像抠图推理的耗时，单位毫秒。
  "matting_ms": 412.5
}

400 / 错误的请求

请求参数有误。常见原因包括：缺少图片来源、同时提交了多个来源、格式互相冲突等。

格式 1缺少或冲突的输入来源
JSON
{
  "code": "INVALID_PARAMETER",
  "message": "file、url、image_base64 三个来源里必须且只能传一个"
}
格式 2格式选项冲突
JSON
{
  "code": "INVALID_PARAMETER",
  "message": "jpeg 不支持透明通道，请改用 output=background 或 out_format=png|webp"
}
格式 3外部链接不可达
JSON
{
  "code": "INVALID_PARAMETER",
  "message": "提供的图片 URL 无法访问或不被允许"
}

413 / 请求实体太大

提交的图片大小超出了云端限制（最大 16MB）。

JSON
{
  "code": "FILE_TOO_LARGE",
  "message": "图片大小不能超过 16777216 字节"
}

415 /

不支持的文件格式。请确保提交的是常见的静态图片（PNG、JPEG、WebP）。

JSON
{
  "code": "UNSUPPORTED_MEDIA_TYPE",
  "message": "目前仅支持 PNG、JPEG 与 WebP 图片"
}

502 / 网关错误

图像抓取失败或处理过程中发生网络波动，请稍后再试。

JSON
{
  "code": "REQUEST_FAILED",
  "message": "抠图请求失败，请稍后再试"
}

503 / 服务不可用

抠图服务暂时不可用或排队队列已满。

JSON
{
  "code": "SERVICE_TEMPORARILY_UNAVAILABLE",
  "message": "服务繁忙或暂时不可用，请稍后再试"
}
上一篇图片敏感检测
下一篇添加图片隐水印