AI Photo Background Change
The AI Photo Background Change API 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 or predefined templates.
Sample Usage
Before: 
After: 
Before: 
After: 
1. Upload Image
Request upload URLs and file IDs via:
POST /s2s/v2.0/fileUpload the image using the returned URL. Alternatively, provide a publicly accessible image URL hosted on your own storage.
2. Prepare a background description prompt or select a background template.
GET /s2s/v2.0/task/template/bg-replaceRetrieve the list of predefined background templates and select one using its template_id. When using prompt which is the default, the background will be generated based on the provided prompt. When using template, the background will be generated from the predefined template specified by template_id, and the prompt parameter will be ignored.
3. Execute Analysis Task
POST /s2s/v2.0/task/bg-replaceSubmit 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.
4. Retrieve Task Result
GET /s2s/v2.0/task/bg-replace/{task_id}Use the task ID to track status and obtain results.
Webhooks 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.
- 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 - curl >= 7.58 (modern TLS/HTTP support) - jq >= 1.6 (robust JSON parsing) |
| Node.js (JavaScript) | Node >= 18 (for global fetch) |
| JavaScript | - Chrome / Edge >= 80 - Firefox >= 74 - 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 |