Objects Removal API

Try on PicWish

AI removes unwanted objects, watermarks, blemishes, or distractions from images. Mark the removal area with a mask image or rectangles, then get a naturally inpainted result. It works for ecommerce product photos, portraits, and design assets, with async and sync request modes.

The result image URL is 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 objects removal task

POST /api/tasks/visual/inpaint

Body Parameters

image_url string optional

Source image URL. If this parameter is present, image_file must be empty.

one required

image_file file optional

Source image file as binary data. If this parameter is present, image_url must be empty.

For image upload requirements, see Guidelines and Limits #6.

mask_url string optional

Mask image URL. If this parameter is present, the other removal-area parameters must be empty.

For removal-area requirements, see Guidelines and Limits #5.

one required

mask_file file optional

Mask image file as binary data. If this parameter is present, the other removal-area parameters must be empty.

For removal-area requirements, see Guidelines and Limits #5.

one required

rectangles string optional

One or more rectangular areas to erase, up to 50 rectangles. Example: [{"x":0,"y":0,"width":100,"height":100}]. If this parameter is present, the other removal-area parameters must be empty.

For removal-area requirements, see Guidelines and Limits #5.

return_type integer optional

Result return type. 1 returns an image URL; 2 returns a base64-encoded image string. Default is 1.

sync integer optional

Whether to return the result immediately. 0 returns task_id asynchronously and lets you fetch the result later through the query endpoint; 1 waits for the result and returns it immediately. Results are retained for up to 1 hour after submission.

Return Parameters

status number

HTTP response status code. 200 means success, and non-200 means failure. See Status Code Definitions.

message string

Response message. If the task fails, refer to this field or contact support.

data.task_id string

Objects removal task ID used for polling.

status number

HTTP response status code. 200 means success, and non-200 means failure. See Status Code Definitions.

message string

Response message. If the task fails, refer to this field or contact support.

data.task_id string

Objects removal task ID. If the task fails, contact support with this task_id.

data.created_at string

Timestamp of task creation.

data.processed_at string

Timestamp when the task started to be processed.

data.completed_at string

Timestamp of task completion.

data.image string

Result image URL or Base64 data. URL results are valid for 1 hour.

data.progress number

Task progress. 100 means processing is complete.

data.state number

Task status. 1 means succeeded, 0 or greater than 1 means processing, and less than 0 means failed. -7 means invalid image file. See Status Code Definitions.

Query objects removal result

GET /api/tasks/visual/inpaint/{task_id}

Path Parameters

task_id string required

Task ID returned after creating an async objects removal task. Use it to query the processing result.

Return Parameters

status number

HTTP response status code. 200 means success, and non-200 means failure. See Status Code Definitions.

message string

Response message. If the task fails, refer to this field or contact support.

data.task_id string

Objects removal task ID. If the task fails, contact support with this task_id.

data.created_at string

Timestamp of task creation.

data.processed_at string

Timestamp when the task started to be processed.

data.completed_at string

Timestamp of task completion.

data.image string

Result image URL or Base64 data. URL results are valid for 1 hour.

data.progress number

Task progress. 100 means processing is complete.

data.state number

Task status. 1 means succeeded, 0 or greater than 1 means processing, and less than 0 means failed. -7 means invalid image file. See Status Code Definitions.

Guidelines and Limits

The result image URL is valid for 1 hour. Please download and store it promptly.
HTTP status 200 means the HTTP request succeeded, not that object removal succeeded. Check data.state for the task result. See Status Code Definitions.
When passing URLs as parameters, follow URL encoding standards to prevent parameter parsing issues.
You must not use this service for any activity that violates laws, regulations, or the legitimate rights of others.
You need to mark the removal area before processing. The API supports mask images and rectangles. For a mask image, the mask must have the same size as the source image; the removal area is white and the rest is black. The removal area should not exceed 50% of the source image.

Source Image Mask Image Result Image
Uploaded images must meet the following format, resolution, and file size limits.

Format Resolution Size

jpg, jpeg, bmp, png, webp, tiff, tif, bitmap, raw, rgb, jfif, lzw Up to 4096 x 4096 Up to 20MB

Format	Resolution	Size
jpg, jpeg, bmp, png, webp, tiff, tif, bitmap, raw, rgb, jfif, lzw	Up to 4096 x 4096	Up to 20MB

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/inpaint/93a5e47b-a9c1-47ac-9b5e-22cb89f7d358-image.jpg", // Only present in async polling results.
    "progress": 100, // Only present in async polling results.
    "state": 1 // Only present in async polling results.
  }
}