Object Retouching API

Try on PicWish

AI retouches selected object areas from a source image and mask, improving material texture, line structure, and product details while optionally preserving specified regions. It is suitable for ecommerce product images, accessories, bags, transparent objects, metal objects, and other refined product retouching scenarios, with async and sync request modes.

The result image URL is generally valid for 1 hour. Please download and store it promptly.

Authentication

Every API request must include your API Key in the X-API-KEY request header. Send it with each request exactly as shown in the examples and parameter descriptions.

X-API-KEY: YOUR_API_KEY

Create an object retouching task

POST /api/tasks/visual/retouching-collection

Body Parameters

image_url string optional

Image download URL. Optional, but one of image_file or image_url is required. Supports HTTP and OSS URLs, up to 512 characters, with a 10-second download timeout. If both image_file and image_url are provided, image_file takes priority.

one required

image_file file optional

Image file as binary data. Optional, but one of image_file or image_url is required. It takes priority over image_url.

Images must match the source size and resolution; see Guidelines and Limits #4.
For image upload requirements, see Guidelines and Limits #5.

mask_url string optional

Mask image download URL for the subject to retouch. Optional, but one of mask_file or mask_url is required. Supports HTTP and OSS URLs, up to 512 characters, with a 10-second download timeout. If both mask_file and mask_url are provided, mask_file takes priority.

one required

mask_file file optional

Mask image file for the subject to retouch. Optional, but one of mask_file or mask_url is required. It takes priority over mask_url.

Images must match the source size and resolution; see Guidelines and Limits #4.

retain_mask_url string optional

Download URL of the mask image for areas whose original features should be retained, up to 512 characters. Provide either retain_mask_url or retain_mask_file; both are optional. If empty, the whole retouch subject is processed.

one optional

retain_mask_file file optional

Mask image file for areas whose original features should be retained. Provide either retain_mask_file or retain_mask_url; both are optional, and retain_mask_file takes priority. If empty, the whole retouch subject is processed.

Images must match the source size and resolution; see Guidelines and Limits #4.

sync number optional

Whether to wait for the result and return it immediately. Use 0 to return a task_id asynchronously, then fetch the result later with the task_id. Use 1 to wait and return the result synchronously.

retouch_strength number optional

Material strength, from 0 to 100. Default is 37. A higher value changes the material more. Only effective in the normal model.

line_strength number optional

Line strength, from 0 to 100. Default is 60. A higher value applies stronger line constraints. Only effective in the normal model.

type number optional

Retouch type. 1 = normal-general; 2 = advanced-general; 3 = advanced-transparent; 4 = advanced-metal; 5 = advanced-jewelry/accessories; 6 = advanced-bags. Default is 1.

Return Parameters

status number

HTTP response status code. 200 means the HTTP request succeeded, not necessarily that object retouching succeeded. See Status Code Definitions.

message string

API response message. Usually success for a successful request.

data.task_id string

Async object retouching task ID returned after the task is created. Use it to query the result later.

status number

HTTP response status code. 200 means the HTTP request succeeded, not necessarily that object retouching succeeded. See Status Code Definitions.

message string

API response message.

data.task_id string

Object retouching task ID.

data.created_at string

Task creation timestamp.

data.processed_at string

Timestamp when processing started.

data.completed_at string

Task completion timestamp.

data.image string

Object retouching result image URL or Base64 data. The URL is valid for 1 hour.

data.return_type number

Result return type.

data.type number

Retouch type used for the task.

data.progress number

Task progress. 100 means processing is complete.

data.state number

Task status code. 1 means completed, greater than 1 means processing, and less than 0 means failed. See Status Code Definitions.

data.time_elapsed string

Processing time.

data.state_detail string

Detailed task state.

Query object retouching result

GET /api/tasks/visual/retouching-collection/{task_id}

Path Parameters

task_id string required

Object retouching task ID returned after creating an async task. Use it to query the processing result.

Return Parameters

status number

HTTP response status code. 200 means the HTTP request succeeded, not necessarily that object retouching succeeded. See Status Code Definitions.

message string

API response message.

data.task_id string

Object retouching task ID.

data.created_at string

Task creation timestamp.

data.processed_at string

Timestamp when processing started.

data.completed_at string

Task completion timestamp.

data.image string

Object retouching result image URL or Base64 data. The URL is valid for 1 hour.

data.return_type number

Result return type.

data.type number

Retouch type used for the task.

data.progress number

Task progress. 100 means processing is complete.

data.state number

Task status code. 1 means completed, greater than 1 means processing, and less than 0 means failed. See Status Code Definitions.

data.time_elapsed string

Processing time.

data.state_detail string

Detailed task state.

Guidelines and Limits

The result image URL is generally valid for 1 hour. Please download and store it promptly.
HTTP status 200 indicates that the HTTP request succeeded, not that object retouching succeeded. See Status Code Definitions for details.
When passing URLs as parameters, follow URL encoding standards to prevent parameter parsing confusion.
The image and mask must have the same dimensions and resolution. If a retain_mask image is provided, all three images must be consistent.

Original image Retouch subject mask Retain feature mask Result image
Uploaded images must meet the following format, resolution, and file size limits.

Format Resolution Size

jpg, jpeg, bmp, png, webp, tiff, bitmap Up to 4096 x 4096 Less than 30MB

Format	Resolution	Size
jpg, jpeg, bmp, png, webp, tiff, bitmap	Up to 4096 x 4096	Less than 30MB

Response

{
  "status": 200,
  "message": "success",
  "data": {
    "task_id": "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "created_at": "1634884056", // Only present in async polling results.
    "processed_at": "1634884056", // Only present in async polling results.
    "completed_at": "1634884056", // Only present in async polling results.
    "image": "https://wxtechhk.oss-hongkong.aliyuncs.com/tasks/output/retouching-collection/93a5e47b-a9c1-47ac-9b5e-22cb89f7d358-image.jpg", // Only present in async polling results.
    "return_type": 1, // Only present in async polling results.
    "type": 1, // Only present in async polling results.
    "progress": 100, // Only present in async polling results.
    "state": 1, // Only present in async polling results.
    "time_elapsed": "4.23s", // Only present in async polling results.
    "state_detail": "success" // Only present in async polling results.
  }
}