# AI Photo Background Removal

# Overview
Remove background from photo with impeccable accuracy, ensuring the high quality of images.
* Automatic Background Detection: : Uses AI to identify and separate the subject from the background.
* High Precision Editing: : Provides clean and precise edges around the subject.
* Supports various categories: People, Products, Animals, Cars, Graphics & more.
* Easy to chain with other AI tasks: The output file ID can be chained into other AI tasks in a flash.

![](https://plugins-media.makeupar.com/smb/blog/post/2023-11-03/54285311-7c65-4658-9e27-11bf5c8dfe56.jpg)

## Integration Guide
* How to run AI Photo Background Removal
1. **Resize your source image**</br>
  Resize your photo to fit the supported dimensions. See details in **[File Specs & Errors](#section/overview/File-Specs-and-Errors)**

2. **Upload file using the File API**</br>
  Using the ***v1.1/file/sod*** API to upload a target user image.
    - Image Requirements
      - See details in **[File Specs & Errors](#section/overview/File-Specs-and-Errors)**.
    - ***Important***: Simply calling the File API does not upload your file. You must **manually upload** the file to the **URL provided in the File API response**. That URL is your upload destination, make sure the file is successfully transferred there before proceeding.<br>
    Before calling the AI API, ensure your file has been successfully uploaded. Use the File API to retrieve an upload URL, then upload your file to that location. Once the upload is complete, you'll receive a ***file_id*** in the response, this ID is what you'll use to access AI features related to that file.
    
      > **Warning:** Please note that, you will get an 500 Server Error / unknown_internal_error or 404 Not Found error when using AI APIs if you do not upload the file to the URL provided in the File API response.

3. **Run an AI task**</br>
  Once the upload is complete, calling POST 'task/sod' with the File ID to execute the AI task and obtains a ***task_id*** to monitor.

4. **Polling to check the status of a task until it succeed or error**</BR>
This ***task_id*** is used to monitor the task's status through polling GET 'task/sod' to retrieve the current engine status. Until the engine completes the task, the status will remain 'running', and no units will be consumed during this stage.

    **Warning:** Please note that, **Polling** to check the status of a task based on it's ***polling_interval*** is mandotary. A task will be timed out if there is no polling request within the ***polling_interval***, even if the task is processed succefully(Your unit(s) will be consumed).

    > **Warning:** You will get a ***InvalidTaskId*** error once you check the status of a timed out task. So, once you run an AI task, you need to **polling** to check the status within the ***polling_interval*** until the status become either *success* or *error*.

5. **Get the result of an AI task once success**</BR>
The task will change to the 'success' status after the engine successfully processes your input file and generates the resulting image. You will get an url of the processed image and a dst_id that allow you to chain another AI task without re-upload the result image.
Your units will only be consumed in this case. If the engine fails to process the task, the task's status will change to 'error' and no unit will be consumed.</BR>
When deducting units, the system will prioritize those nearing expiration. If the expiration date is the same, it will deduct the units obtained on the earliest date.

* Demonstrative scenarios:
Common implementation cases:
![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/Transparen_Background_aca3cdbd83.jpg)

## Inputs & Outputs
* Inputs
   * `Image`
- **Type:** `image`
- **Description:** An image with clear foreground.

Real-world application (input): 
![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_removal_bg_s4_poster_1_289b8eaf81.png)

---

* Outputs
   * `Foreground image`
- **Type:** `image`
- **Description:** A background removed image.

Real-world application (output):
![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_removal_bg_s4_poster_2_a6bc3c5f6a.png)

## File Specs & Errors
* Supported Formats & Dimensions

|AI Feature|Supported Dimensions|File Size|Accepted formats|
|  ----  | ----  | ----  | ----  |
|AI Photo Background Removal|Recommendations and limitations for both input and output images are as follows:</br>Resolution: 4096 × 4096 pixels (longest side must not exceed 4096 pixels)|<10MB|JPG and PNG|

* Error Codes

|Error Code|Description|
|  ----  | ----  |
|exceed_max_filesize|Input file size exceeds the maximum limit|
|invalid_parameter|Invalid parameter value|
|error_download_image|Download source image error|
|error_download_mask|Download mask image error|
|error_decode_image|Decode source image error|
|error_decode_mask|Decode mask image error|
|error_download_video|Download source video error|
|error_decode_video|Decode source video error|
|error_nsfw_content_detected|NSFW content detected in source image|
|error_no_face|No face detected on source image|
|error_pose|Failed to detect pose on source image|
|error_face_parsing|Failed to do face segmentation on source image|
|error_inference|Inference pipeline error|
|exceed_nsfw_retry_limits|Exceed the retry limits to avoid generated NSFW image|
|error_upload|Upload result image error|
|error_multiple_people|Multiple people detected in the source image|
|error_no_shoulder|Shoulders are not visible in the source image|
|error_large_face_angle|The face angle in the uploaded image is too large|
|error_hair_too_short|Input hair is too short|
|error_unexpected_video_duration|Video durateion is not equal to the dstDuration|
|error_bald_image|Input hairstyle is bald|
|error_unsupport_ratio|The aspect ratio of input image is unsupported|
|unknown_internal_error|Others|


License: Privacy policy

## Servers

```
https://yce-api-01.makeupar.com
```

## Security

### BearerAuthenticationV2

Use the standard 'Bearer authentication'. Put your 'API Key' in header: `Authorization:Bearer YOUR_API_KEY`. Notice that there is ' ' a space between 'Bearer' and the 'YOUR_API_KEY'.

Type: http
Scheme: bearer

## Download OpenAPI description

[AI Photo Background Removal](https://docs.perfectcorp.com/_bundle/reference/ai_background_removal.yaml)

## V1.0

Automatically detect and remove backgrounds from images using AI segmentation.

### Create a new file.

 - [POST /s2s/v2.0/file/sod](https://docs.perfectcorp.com/reference/ai_background_removal/v1.0/paths/~1s2s~1v2.0~1file~1sod/post.md): To upload a new file, you'll first need to use the File API. It will give you a URL – use that URL to upload your file. Once the upload is finished, you can use the file_id from the same response to start using our AI features.

### Run an AI Photo Background Removal task.

 - [POST /s2s/v2.0/task/sod](https://docs.perfectcorp.com/reference/ai_background_removal/v1.0/paths/~1s2s~1v2.0~1task~1sod/post.md): This endpoint initiates the background removal process. You must provide a file ID obtained from the file upload API. The task will be processed asynchronously, and you can check its status using the task_id returned in this response.

### Check an AI Photo Background Removal task status.

 - [GET /s2s/v2.0/task/sod/{task_id}](https://docs.perfectcorp.com/reference/ai_background_removal/v1.0/paths/~1s2s~1v2.0~1task~1sod~1%7Btask_id%7D/get.md)