Objects Removal - Advanced API

Remove selected objects using a source image and a mask of the area to remove.

Result image URLs are generally valid for 1 hour. Please download and store them 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 advanced objects removal task

POST /api/tasks/visual/external/image-inpainting

Body Parameters

image_url string optional

Source image URL. Provide at least one of image_url or image_file; image_file takes precedence when both are supplied.

one required

image_file file optional

Source image file as binary data. Provide at least one of image_file or image_url; image_file takes precedence when both are supplied.

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

mask_url string optional

Mask image URL specifying the area to remove. Provide either mask_url or mask_file.

one required

mask_file file optional

Mask image file as binary data specifying the area to remove. Provide either mask_file or mask_url.

provider integer optional

Processing route:

1: Route 1 (default)
2: Route 2

Return Parameters

status integer

HTTP response status code. 200 means the request succeeded, not that image processing succeeded. See Status Code Definitions.

message string

Response message. Include the error message and task_id when contacting support about a failed task.

data.task_id string

Task ID used to query the objects removal result.

Query advanced objects removal result

For asynchronous requests, poll the result once every 1 second. The maximum polling duration for this API is 600 seconds; if the total polling time exceeds this without a result, treat it as a timeout failure.

GET /api/tasks/visual/external/image-inpainting/{task_id}

Path Parameters

task_id string required

Task ID returned when the objects removal task was created.

Return Parameters

status integer

HTTP response status code. 200 means the request succeeded, not that image processing succeeded. See Status Code Definitions.

message string

Response message. Include the error message and task_id when contacting support about a failed task.

data.task_id string

Task ID used to query the objects removal result.

data.image string

Result image URL or base64 data. Result URLs are generally valid for 1 hour.

data.state integer

Task state: 0 queued; 1 succeeded; 2 preparing; 3 waiting; 4 processing; < 0 failed. Stop polling on success or failure. See Status Code Definitions.

data.progress integer

Task progress from 0 to 100. Check data.state to determine whether processing succeeded.

data.created_at integer

Timestamp of task creation.

data.processed_at integer

Timestamp when processing started.

data.completed_at integer

Timestamp of task completion.

data.time_elapsed string

Elapsed processing time.

data.state_detail string

Detailed task status.

data.return_type integer

Result return method.

data.cost number

Cost value returned by the API.

data.use_point integer

Credits consumed by this task. Each successful call consumes 6 credits.

Guidelines and Limits

Result image URLs are generally valid for 1 hour. Please download and store them promptly.
HTTP status 200 only means the request succeeded. data.state = 1 means processing succeeded; data.state < 0 means it failed. Stop polling on either success or failure.
Follow URL encoding standards when passing URLs. Preserve all signed URL parameters when downloading results; incorrectly escaping & can invalidate the URL.
Both the source and mask must meet the format, size and resolution limits below. Each URL supports HTTP and OSS, up to 512 characters, with a 20-second download timeout.
Processing usually takes 1–2 minutes, depending on image size, with a maximum processing time of 10 minutes.
The default QPS limit is 2. Contact sales for a higher limit. Each successful call consumes 6 credits.
Both source and mask images must meet the following requirements.

Format File size Resolution

jpg, jpeg, png (JPEG recommended) Up to 4.7MB per image ≤ 4096 × 4096

Format	File size	Resolution
jpg, jpeg, png (JPEG recommended)	Up to 4.7MB per image	≤ 4096 × 4096

Response

{
  "status": 200,
  "data": {
    "task_id": "94806a3f-1173-4afb-9bcc-3ff19c0981f4",
    "created_at": 1789541552,
    "processed_at": 1789541552,
    "completed_at": 1789541563,
    "image": "YOUR_RESULT_IMAGE_URL",
    "progress": 100,
    "state": 1,
    "state_detail": "Complete",
    "return_type": 2,
    "cost": 0,
    "use_point": 6
  }
}