Image

Image Matting (Background Removal)

0calls

1 credits / call

Still tracing outlines with the lasso tool one click at a time? Or want to add one-click ID-photo background swapping to your app? This API automatically detects the subject in an image and strips away complex backgrounds in an instant.

POST

uapis.cn

/api/v1/image/matting

Body

file

The image file to matte. Supports PNG, JPEG, WebP and other common formats, up to 16MB. Do not submit together with url or image_base64.

Drag a file here, orclick to upload

The image file to matte. Supports PNG, JPEG, WebP and other common formats, up to 16MB. Do not submit together with url or image_base64.

url

string

A publicly accessible image URL. Do not submit together with file or image_base64.

image_base64

string

Base64-encoded image data. Can be a full Data URI or raw Base64 content. Do not submit together with file or url.

image_name

string

Custom image file name. Recommended when passing url or raw Base64, to help infer the extension; also used as image_name in the response.

model

string

Segmentation model. Defaults to u2net when omitted.

output

string

Result type. Defaults to cutout when omitted.

background_color

string

Composite background color, e.g. #RRGGBB. Only effective when output=background.

threshold

number

Alpha binarization threshold, range [0, 1). When greater than 0, binarizes the alpha channel to remove semi-transparent edges. Skipped when omitted.

feather_px

integer

Gaussian feather radius in pixels for the alpha channel, range [0, 64], for softer edges. Skipped when omitted.

out_format

string

Output image format. Defaults to png when omitted. jpeg is only allowed when output=background.

jpeg_quality

integer

JPEG compression quality, range [1, 100]. Only effective when out_format=jpeg.

Feature Overview

Just provide an image, and the API runs a powerful segmentation model in the cloud and returns the processed result directly. It supports a high degree of customization, letting you:

Choose a segmentation model (model): Depending on the image type, switch freely between general-purpose, lightweight-fast, portrait-specific, and sharper-edge models.
Customize the output (output): By default, you get a clean transparent-background subject image (cutout). For further design work, you can also get a grayscale alpha mask (mask), or composite the subject directly onto a specified solid background (background).
Fine-tune the edges: threshold (binarize away semi-transparency) and feather_px (Gaussian feathering) let you refine the cutout edges for a more natural blend.

Usage Notes

Mutually exclusive image inputs: to avoid conflicts, choose exactly one of file, url, or image_base64.

Output format restriction: if you request jpeg as the output format, since JPEG doesn't support an alpha channel, you must also set output=background, otherwise the request will fail.

Size limit: each uploaded image is capped at 16MB.

Request body

Form data with the image to matte and optional rendering parameters. Must be submitted as multipart/form-data.

file

fileoptional

The image file to matte. Supports PNG, JPEG, WebP and other common formats, up to 16MB. Do not submit together with url or image_base64.

url

stringoptional

A publicly accessible image URL. Do not submit together with file or image_base64.

image_base64

stringoptional

Base64-encoded image data. Can be a full Data URI or raw Base64 content. Do not submit together with file or url.

image_name

stringoptional

Custom image file name. Recommended when passing url or raw Base64, to help infer the extension; also used as image_name in the response.

model

stringoptional

Segmentation model. Defaults to u2net when omitted.

output

stringoptional

Result type. Defaults to cutout when omitted.

background_color

stringoptional

Composite background color, e.g. #RRGGBB. Only effective when output=background.

threshold

numberoptional

Alpha binarization threshold, range [0, 1). When greater than 0, binarizes the alpha channel to remove semi-transparent edges. Skipped when omitted.

feather_px

integeroptional

Gaussian feather radius in pixels for the alpha channel, range [0, 64], for softer edges. Skipped when omitted.

out_format

stringoptional

Output image format. Defaults to png when omitted. jpeg is only allowed when output=background.

jpeg_quality

integeroptional

JPEG compression quality, range [1, 100]. Only effective when out_format=jpeg.

Name	Type	Attributes	Description
`file`	file	optional	The image file to matte. Supports PNG, JPEG, WebP and other common formats, up to 16MB. Do not submit together with url or image_base64.
`url`	string	optional	A publicly accessible image URL. Do not submit together with file or image_base64.
`image_base64`	string	optional	Base64-encoded image data. Can be a full Data URI or raw Base64 content. Do not submit together with file or url.
`image_name`	string	optional	Custom image file name. Recommended when passing url or raw Base64, to help infer the extension; also used as image_name in the response.
`model`	string	optional	Segmentation model. Defaults to `u2net` when omitted.
`output`	string	optional	Result type. Defaults to `cutout` when omitted.
`background_color`	string	optional	Composite background color, e.g. `#RRGGBB`. Only effective when `output=background`.
`threshold`	number	optional	Alpha binarization threshold, range `[0, 1)`. When greater than 0, binarizes the alpha channel to remove semi-transparent edges. Skipped when omitted.
`feather_px`	integer	optional	Gaussian feather radius in pixels for the alpha channel, range `[0, 64]`, for softer edges. Skipped when omitted.
`out_format`	string	optional	Output image format. Defaults to `png` when omitted. `jpeg` is only allowed when `output=background`.
`jpeg_quality`	integer	optional	JPEG compression quality, range `[1, 100]`. Only effective when `out_format=jpeg`.

Response

200 / OK

Matting succeeded, returns the result image as Base64 with basic metadata.

JSON

{
  // Base64-encoded result image (no Data URI prefix).
  "image_base64": "string",
  // Result image file name, with an extension matching the actual output format. Only returned when image_name was passed or a file was uploaded.
  "image_name": "product-01.png",
  // Actual format of the result image.
  "format": "png",
  // Result image width in pixels.
  "width": 800,
  // Result image height in pixels.
  "height": 800,
  // Segmentation model actually used.
  "model": "u2net",
  // Result type actually used.
  "output": "cutout",
  // Matting inference time in milliseconds.
  "matting_ms": 412.5
}

400 / Bad Request

Invalid request parameters. Common causes: missing image source, multiple sources submitted at once, or conflicting format options.

Format 1Missing or conflicting input source

JSON

{
  "code": "INVALID_PARAMETER",
  "message": "Exactly one of file, url, or image_base64 must be provided"
}

Format 2Conflicting format options

JSON

{
  "code": "INVALID_PARAMETER",
  "message": "jpeg does not support an alpha channel; use output=background or out_format=png|webp instead"
}

Format 3External link unreachable

JSON

{
  "code": "INVALID_PARAMETER",
  "message": "The provided image URL is unreachable or not allowed"
}

413 /

The submitted image exceeds the cloud limit (max 16MB).

JSON

{
  "code": "FILE_TOO_LARGE",
  "message": "Image size cannot exceed 16777216 bytes"
}

415 /

Unsupported file format. Make sure you submit a common static image (PNG, JPEG, WebP).

JSON

{
  "code": "UNSUPPORTED_MEDIA_TYPE",
  "message": "Currently only PNG, JPEG, and WebP images are supported"
}

502 / Bad Gateway

Image retrieval failed or a network hiccup occurred during processing; please try again later.

JSON

{
  "code": "REQUEST_FAILED",
  "message": "Matting request failed, please try again later"
}

503 / Service Unavailable

The matting service is temporarily unavailable or the queue is full.

JSON

{
  "code": "SERVICE_TEMPORARILY_UNAVAILABLE",
  "message": "Service is busy or temporarily unavailable, please try again later"
}

Quick start

Pick your language to see usage examples

Auth mode:

cURL command

curl -X POST 'https://uapis.cn/api/v1/image/matting' \
  -F 'url=https://uapis.cn/matting-samples/product-01.png'

Frequently asked questions

The cutout edges aren't clean enough, what can I do?

Try passing `feather_px` to feather the mask for a smoother edge transition. If there's visible discoloration because the subject and background colors are too close, try `threshold` to remove semi-transparent edge pixels, or switch to `model=isnet` for a sharper edge detection model.

How do I get an ID-photo-style solid blue or red background?

Set `output` to `background`, and pass `background_color` with the corresponding hex color (e.g. `#FFFFFF` for white, `#438EDB` for a common ID photo blue).

Why does setting the output format to jpeg return an error?

Because the JPEG file format itself does not support storing alpha channel information, and when `output` is the default `cutout` or `mask`, the image contains large transparent areas. So JPEG export only works when you choose `output=background` (composited onto a solid background image).

Related APIs

Image Sensitive Content Detection

This is an image content moderation API that automatically detects prohibited content in uploaded images and returns handling recommendations.

Universal OCR Text Recognition

Whether you need to implement automated receipt entry, or highlight text coordinates on images in web frontend, this high-precision OCR endpoint can provide you with powerful basic capabilities.

Decode and Scale Image

Decoding images on devices with extremely limited RAM and Flash is a heavy task. This endpoint is designed for IoT and embedded development, moving complex image decoding and scaling operations to the cloud, directly outputting binary pixel streams suitable for microcontroller screens.

Image to Base64

See a picture on the web and want to convert it to Base64 encoding so you can embed it in your HTML or CSS? This endpoint is for you.

PreviousImage Sensitive Content Detection

NextAdd Image Watermark