# 🛠 Endpoints | METHOD | URL | DESCRIPTION | | ------ | ---------------------------------------------------------------------- | ------------------------------------------- | | GET | `https://people-photo-background-removal.p.rapidapi.com/v1/version` | Get a service version. | | POST | `https://people-photo-background-removal.p.rapidapi.com/v1/results` | Perform image processing and get results. | ## 👉 Get version Returns an actual version of the service in format `vX.Y.Z` where X is the version of API. | PROPERTY | DESCRIPTION | | ---------------- | ------------------------------------------------------------------- | | Endpoint | `https://people-photo-background-removal.p.rapidapi.com/v1/version` | | Method | `GET` | | Query parameters | – | | POST parameters | – | **Example** ```bash curl -X 'GET' 'https://people-photo-background-removal.p.rapidapi.com/v1/version' \ -H 'X-RapidAPI-Key: ...' ```

Click here to view the response

``` v1.3.0 ```

## 👉 Analyze image and return results Performs actual image analysis and responds with results. | PROPERTY | DESCRIPTION | | ---------------- | ------------------------------------------------------------------- | | Endpoint | `https://people-photo-background-removal.p.rapidapi.com/v1/results` | | Method | `POST` | | Query parameters | `mode` | | POST parameters | `image`, `url`, `image-bg`, `url-bg` | **Passing image** Image can be passed by posting regular "multipart form data" in two alternative ways: * as binary file in `image` field * as URL to some public resource in `url` field Image must be a regular JPEG or PNG image (with or without transparency). Usually such images have extensions: `.jpg`, `.jpeg`, `.png`. The service checks input file by MIME type and accepts the following types: * `image/jpeg` * `image/png` The size of the image file must be less than `16Mb`. The maximum allowed resolution is `4096x4096`. **Passing optional background image** If the background image is passed then it's content will be blended below a person image (aligned by the center). The final output image will have the same size as the main input image (not background image!). Meaningless if the mode is `fg-mask`. Background image can be passed by posting regular "multipart form data" in two alternative ways: * as binary file in `image-bg` field * as URL to some public resource in `url-bg` field Image must be a regular JPEG or PNG image (with or without transparency). Usually such images have extensions: `.jpg`, `.jpeg`, `.png`. The service checks input file by MIME type and accepts the following types: * `image/jpeg` * `image/png` The size of the image file must be less than `16Mb`. The maximum allowed resolution is `4096x4096`. **Specifying mode** Query parameter `mode` is optional and may be used to choose the format of the output image: foreground (person) mask or foreground (person) image. By default the service uses `fg-image`. Available modes and expected content of the resulting image: ✅ `fg-image` (default) – the image with the foreground (person). Here the result is a 4-channel (`RGBA`) PNG image where background is transparent. * Areas recognized as foreground will have the same color values at output image as the original input image. * Areas recognized as background will be transparent at output image. * Pixels of output image near the foreground borders may be semi transparent. ✅ `fg-mask` – the mask of foreground (person). In this case the result is a single-channel grayscale PNG image. * Areas recognized as foreground will have white color. * Areas recognized as background will be black at output image. * Pixels of output image near to foreground borders may have gray values: the closer to black, the more likely the pixel is the background. **Response schema** For responses with `200` HTTP code the type of response is JSON object with the following schema: ```json { "results": [ { "status": { "code": ..., "message": ... }, "name": ..., "md5": ..., "page": ..., "width": ..., "height": ..., "entities": [ { "kind": "image", "name": ..., "image": ..., "format": "PNG", "representation": "base64" }, { "kind": "objects", "name": "objects", "objects": [...] } ] } ] } ``` Primary fields: | Name | Type | Description | | ----------------------------- | -------- | ------------------------------------------------------------ | | `results[].status.code` | `string` | Status code of image processing: `ok` or `failure`. | | `results[].status.message` | `string` | Human readable explanation for the status of image processing. | | `results[].name` | `string` | Original image name passed in request (e.g. `my_image.jpg`). | | `results[].md5` | `string` | MD5 sum of original image passed in request. | | `results[].page` | `int` | Optional page number (presented for multipage inputs only). | | `results[].width` | `int` | Optimal image width (presented for valid inputs only). | | `results[].height` | `int` | Optional image height (presented for valid inputs only). | | `results[].entities[].name` | `string` | The name of the output entity. | | `results[].entities[].image` | `string` | PNG result image encoded as base64. | | `results[].entities[].format` | `string` | Image format. | * Entity name. It depends on `mode`. Examples: * `people-fg-image` if the output is a foreground (person). * `people-fg-mask` if the output is a foreground (person) mask. * The most important part of the response is `results[].entities[].image` field. * *Image*. The resulting image is a PNG image with transparency. Pixels of the original image that are recognized as background will be transparent in the result image. * *Mask*. The result image is a single-channel grayscale PNG image. Pixels of the original image that are recognized as background will be black in the resulting image and foreground will be white. The output image in `results[].entities[].image` field is encoded as base64. Other fields that are not described above always have the same values.

# 📌 Examples ## 👉 The original image

## 👉 Just remove the background

```bash curl -X 'POST' 'https://people-photo-background-removal.p.rapidapi.com/v1/results' \ -H 'X-RapidAPI-Key: ...' \ -F 'image=@img.jpg' ```

Click here to view the response

```json { "results": [ { "status": { "code": "ok", "message": "Success" }, "name": "img.jpg", "md5": "ccdc22a0b1c9e1eab905344a59c83520", "width": 1169, "height": 779, "entities": [ { "kind": "image", "name": "people-fg-image", "image": "iVBORw0KGgoAAAA...YII=", "format": "PNG", "representation": "base64" }, { "kind": "objects", "name": "objects", "objects": [ { "box": [ 0.34302822925577414, 0.08985879332477535, 0.32335329341317365, 0.9101412066752247 ], "entities": [ { "kind": "classes", "name": "classes", "classes": { "opaque-content": 1 } } ] } ] } ] } ] } ```

## 👉 Get person's mask

```bash curl -X 'POST' 'https://people-photo-background-removal.p.rapidapi.com/v1/results?mode=fg-mask' \ -H 'X-RapidAPI-Key: ...' \ -F 'image=@img.jpg' ```

Click here to view the response

```json { "results": [ { "status": { "code": "ok", "message": "Success" }, "name": "img.jpg", "md5": "ccdc22a0b1c9e1eab905344a59c83520", "width": 1169, "height": 779, "entities": [ { "kind": "image", "name": "people-fg-mask", "image": "iVBORw0KGgoAAAA...YII=", "format": "PNG", "representation": "base64" }, { "kind": "objects", "name": "objects", "objects": [ { "box": [ 0.34302822925577414, 0.08985879332477535, 0.32335329341317365, 0.9101412066752247 ], "entities": [ { "kind": "classes", "name": "classes", "classes": { "opaque-content": 1 } } ] } ] } ] } ] } ```

## 👉 Use custom background

```bash curl -X 'POST' 'https://people-photo-background-removal.p.rapidapi.com/v1/results' \ -H 'X-RapidAPI-Key: ...' \ -F 'image=@img.jpg' \ -F 'image-bg=@bg.png' ```

Click here to view the response

# ❗️ Possible errors ## 👉 The service can not process an image When a client sends an image that can not be processed for some reason(s), the service responds with `200` code and returns a JSON object in the same format as the format for successful analysis. In this case, the `results[].status.code` will have `failure` value and `results[].status.message` will contain relevant explanation. Example of possible reasons for the issue: * Unsupported MIME type * Image resolution exceeds limits * Corrupted image **Example response for image with unsupported MIME type:** ```json { "results": [ { "status": { "code": "failure", "message": "Can not load image." }, "name": "file.txt", "md5": "d41d8cd98f00b204e9800998ecf8427e", "entities": [] } ] } ``` **Example response for image with the resolution too big to process:** ```json { "results": [ { "status": { "code": "failure", "message": "Resolution is too big: 6000x4000. Max allowed resolution: 4096x4096." }, "name": "24mpx.jpg", "md5": "a24c7cd77e21b303a1211889cea7527b", "entities": [] } ] } ``` ## 👉 Request size is too big Request size is limited by approximately `32Mb`. When a client sends a request that exceeds this limit, the service responds with `413` code. The typical reason for exceeding this limit is an overly large image. Taking into account additional HTTP overhead, we strongly recommend not passing image files of size more than `16Mb`. **Example response for overly big image:** ``` Error: Request Entity Too Large Your client issued a request that was too large. ``` ## 👉 Missing image When a client sends a request without an image, the service responds with `422` code and returns a JSON object. **Example response for request with missing image:** ```json {"detail":"Missing image or url field."} ```

# ❓ F.A.Q. ## 👉 How to pass an image as binary file? Post a file content as a "multipart form data" field named `image`. ```bash curl -X 'POST' 'https://people-photo-background-removal.p.rapidapi.com/v1/results' \ -H 'X-RapidAPI-Key: ...' \ -F 'image=@img.jpg' ``` ## 👉 How to pass an image as URL? Post a URL to file as a "multipart form data" field named `url`. ```bash curl -X 'POST' 'https://people-photo-background-removal.p.rapidapi.com/v1/results' \ -H 'X-RapidAPI-Key: ...' \ -F 'url=https://static.api4.ai/rapidapi/background-removal/shoes.jpg' ``` ## 👉 How to get a persons's segmentation mask? Use `mode=fg-mask` query parameter. ```bash curl -X 'POST' 'https://people-photo-background-removal.p.rapidapi.com/v1/results?mode=fg-mask' \ -H 'X-RapidAPI-Key: ...' \ -F 'image=@img.jpg' ``` ## 👉 How to pass a custom background image as binary file? Post a file content as a "multipart form data" field named `image-bg`. ```bash curl -X 'POST' 'https://people-photo-background-removal.p.rapidapi.com/v1/results' \ -H 'X-RapidAPI-Key: ...' \ -F 'image=@img.jpg' \ -F 'image-bg=@bg.jpg' ``` ## 👉 How to pass a custom background image as URL? Post a file as a "multipart form data" field named `url-bg`. ```bash curl -X 'POST' 'https://people-photo-background-removal.p.rapidapi.com/v1/results?mode=fg-image-shadow-hideclp' \ -H 'X-RapidAPI-Key: ...' \ -F 'image=@img.jpg' \ -F 'url-bg=https://static.api4.ai/rapidapi/background-removal/bg.png' ``` ## 👉 I've got JSON response. Where is the resulting image??? The resulting png image is a part of JSON response and encoded as base64 string. Property path: `results[].entities[].image` ```json { "results": [ { ... "entities": [ { "kind": "image", "image": RESULTING-PNG-IMAGE-ENCODED-AS-BASE64-STRING, ... } ... ] } ] } ``` ## 👉 Where to find code examples? Code examples in Python, C#, JavaScript, Swift and other popular programming languages: https://gitlab.com/api4ai/examples/img-bg-removal-general ## 👉 Where to try live demo? * 🤖 Telegram demo bot: https://t.me/a4a_img_bg_removal_bot * 🔗 Web demo: [https://api4.ai/apis/people-bg-removal](https://api4.ai/apis/people-bg-removal?utm_source=rapidapi&utm_medium=referral&utm_campaign=people-bg-removal) ## 👉 I need support Feel free to contact API4AI team if you have any questions. * 📩 Email: hello@api4.ai * 💬 Telegram: https://t.me/a4a_support_bot