# AI Photo Background Change

# Overview
The AI Photo Background Change tool enhances images by isolating the subject from the original background, enabling a wide range of applications including product-focused use cases in business.

This API enables developers to replace the background using custom prompts.

**Sample Usage**

Before:
![](https://yce.makeupar.com/assets/images/sod/banner/change/yce-topbanner-dt-before.jpg)

After:
![](https://yce.makeupar.com/assets/images/sod/banner/change/yce-topbanner-dt-after.jpg)


Before:
![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_change_bg_s5_poster_before_0753db3e02.jpg)

After:
![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_change_bg_s5_poster_after_7fb288fde2.jpg)

---

## Integration Guide

**1. Upload Image**

Request upload URLs and file IDs via:

```
POST /s2s/v2.0/file/bg-replace-v2
```

Upload the image using the returned URL.
Alternatively, provide a publicly accessible image URL hosted on your own storage.


**2. Execute Analysis Task**

```
POST /s2s/v2.0/task/bg-replace-v2
```

Submit the task using file IDs or image URLs as input, along with the desired background prompt.
The response returns a task_id for tracking and retrieving the result.


**3. Retrieve Task Result**

```
GET /s2s/v2.0/task/bg-replace-v2/{task_id}
```

Use the task ID to track status and obtain results.

[Webhooks](/develop/webhook.md) can be configured to receive asynchronous notifications on task completion with a success or error status. Polling is also supported by repeatedly calling the task endpoint until the status is updated from running to success or error.

Usage is only charged when the task completes successfully.

---

## File Specs & Errors

* Supported Formats & Dimensions

|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|
|  ----  | ----  | ----  | ----  |
| AI Photo Background Change | The length of the longer side shall not exceed 4096 pixels. | < 10MB | jpg/jpeg/png |

* Error Codes

|Error Code|Description|
|  ----  | ----  |
| exceed_max_filesize |	The input file size exceeds the maximum allowed limit. |
| size_mismatch_on_input_image_and_mask | The input image size must match the input mask image dimensions. |
| invalid_parameter | Invalid parameter value. The request parameter is missing, in an invalid format, or contains an unsupported value.|

* Environment & Dependency

| Sample Code Language / Tool | Recommended Runtime Versions |
|---|---|
| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |
| Node.js (JavaScript) | Node >= 18 (for global fetch) |
| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |
| PHP | PHP >= 7.4 (for modern TLS/compat), ext-curl (recommended) or allow_url_fopen=On + ext-openssl, ext-json |
| Python | Python >= 3.10 (for f-strings), requests >= 2.20.0 |
| Java | Java 11+ (for HttpClient), Jackson Databind >= 2.12.0 |


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 Change](https://docs.perfectcorp.com/_bundle/reference/ai_photo_background_change.yaml)

## V2.0

AI Photo Background Change API v2.0 replaces image backgrounds using a custom prompt.

### Create a new file.

 - [POST /s2s/v2.0/file/bg-replace-v2](https://docs.perfectcorp.com/reference/ai_photo_background_change/v2.0/paths/~1s2s~1v2.0~1file~1bg-replace-v2/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 Change V2 task.

 - [POST /s2s/v2.0/task/bg-replace-v2](https://docs.perfectcorp.com/reference/ai_photo_background_change/v2.0/paths/~1s2s~1v2.0~1task~1bg-replace-v2/post.md): AI tasks are asynchronous. Prefer webhook-based completion handling when the feature supports webhooks. Configure your webhook endpoint, verify webhook signatures, and use the received task_id to query the task result after a success or error notification. See the webhook integration guide for setup and verification details.

If webhooks are not supported for the feature, or if your integration cannot use webhooks, implement polling. After starting an AI task, keep polling the task status endpoint at the given polling_interval until the task status is either success or error.

Do not stop polling a running task for longer than the allowed polling window. If the task is not polled in time, the task may expire; a later status check can return InvalidTaskId even if processing finished, and the consumed units may still be charged.

### Check an AI photo Background Change V2 task status.

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