Image erase completion API reference - Alibaba Cloud Model Studio

Related guide: Image erase completion

This document applies only to the China (Beijing) region. To use the model, you must use an API key from the China (Beijing) region.
The image-erase-completion model is currently available only as a free trial. Once you exhaust your free quota, you can no longer call the model, as paid options are not supported. As alternatives, we recommend using Image editing - Qwen or Image editing - Wan2.1.

Prerequisites

Obtain an API key and export the API key as an environment variable.

HTTP call

To reduce wait times and prevent request timeouts, the service processes requests asynchronously. You need to make two requests:

Create a task: Send a request to create an image generation task. This request returns a task ID.
Query the result by task ID: Use the returned task ID to query the result.

Step 1: Create a task

POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis

Request headers

Content-TypestringRequiredThe content type of the request. The value must be application/json.AuthorizationstringRequiredWe recommend using your Model Studio API key. You can also use your DashScope API key. Example: Bearer d1xxx2a.X-DashScope-AsyncstringRequiredSpecifies whether to enable asynchronous processing. You must set this parameter to enable.

Request body

modelstringRequiredThe model to call.inputobjectRequiredInput image details, such as the image URL.

Properties

image_urlstringRequiredThe URL or Base64-encoded data of the input image.The URL must be publicly accessible and use HTTP or HTTPS.Image requirements:

Formats: JPEG, PNG, JPG, BMP, WEBP.
Resolution: Must be at least 512×512 pixels and no more than 4096×4096 pixels.
Side length range: [512, 4096] pixels.
File size: Must not exceed 10 MB.
The URL must not contain Chinese characters.

mask_urlstringRequiredThe URL or Base64-encoded data of the mask image that specifies the area to erase.The URL must be publicly accessible and use HTTP or HTTPS.Image requirements:

Formats: JPG, JPEG, PNG, HEIF, WEBP.
Resolution: Must be at least 512×512 pixels and no more than 4096×4096 pixels.
Side length range: [512, 4096] pixels.
File size: Must not exceed 10 MB.

To create a mask, paint on a blank canvas of the same size as the input image. Areas with non-zero pixel values serve as the erase mask. Alternatively, use human instance segmentation to directly generate a segmentation result as the erase mask.foreground_urlstring OptionalThe URL or Base64-encoded data of the mask image that specifies the area to preserve.The URL must be publicly accessible and use HTTP or HTTPS.Image requirements:

Formats: JPG, JPEG, PNG, HEIF, WEBP.
Resolution: Must be at least 512×512 pixels and no more than 4096×4096 pixels.
Side length range: [512, 4096] pixels.
File size: Must not exceed 10 MB.

To create a preserve mask, paint on a blank canvas of the same size as the input image. Areas with non-zero pixel values serve as the preserve mask. Alternatively, use human instance segmentation to specify a person ID, which isolates that person's mask area to prevent them from being erased.

parametersobject OptionalParameters for image processing.

Properties

fast_modeboolOptionalSpecifies whether to enable fast mode. The default value is false. In fast mode, inference takes about one-fourth the time of standard mode. This mode is suitable for scenarios that do not require high detail.dilate_flagboolOptionalThe default value is true. We recommend setting this to true if an algorithm generates the erase mask, and to false if you manually paint the erase mask.add_watermark booleanOptionalAdds a Generated by AI watermark. The default value is true, which adds the watermark to the bottom-left corner of the output image.

Image erase completion

curl --location --request POST 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
    "model": "image-erase-completion",
    "input": {
            "image_url": "http://xxx/input.png",
            "mask_url": "http://xxx/mask.png",
            "foreground_url": "http://xxx/foreground.png"
        },
    "parameters":{
        "dilate_flag":true
    }
}'

Response

outputobjectTask output details.

Properties

task_idstringThe unique task identifier.task_statusstringThe task status.

PENDING: The task is in the queue.
RUNNING: The task is in progress.
SUSPENDED: The task is suspended.
SUCCEEDED: The task completed successfully.
FAILED: The task failed.

codestringThe error code. This parameter is not returned if the request is successful.messagestringThe error message. This parameter is not returned if the request is successful.request_idstringThe unique request ID. Use this ID to trace and troubleshoot issues.

{
    "output": {
        "task_status": "PENDING",
        "task_id": "53950fb7-281a-4e60-b543-xxxxxxxxxxxx"
    },
    "request_id": "1027557e-8c3f-9db5-8cd2-xxxxxxxxxxxx"
}

Step 2: Query the result

GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

Request headers

AuthorizationstringRequiredYour API key. Example: Bearer d1**2a.

Path parameters

task_idstringRequiredThe task ID.

Task result

curl -X GET \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
https://dashscope.aliyuncs.com/api/v1/tasks/53950fb7-281a-4e60-b543-xxxxxxxxxxxx

Response

outputobjectTask output details.

Properties

task_id stringThe task ID.task_status stringThe task status.

PENDING: The task is in the queue.
RUNNING: The task is in progress.
SUSPENDED: The task is suspended.
SUCCEEDED: The task completed successfully.
FAILED: The task failed.

task_metrics objectTask statistics.

Properties

TOTAL integerThe total number of tasks.SUCCEEDED integerThe number of successful tasks.FAILED integerThe number of failed tasks.

submit_time stringThe time the task was submitted.scheduled_time stringThe time the task started running.end_time stringThe time the task was completed.output_image_url stringThe URL of the output image.codestringThe error code. This parameter is not returned if the request is successful.messagestringThe error message. This parameter is not returned if the request is successful.

usageobjectUsage statistics.

Properties

image_countintegerThe number of generated images.

request_idstringThe unique request ID. Use this ID to trace and troubleshoot issues.

Completed task
In-progress task
Failed task

Completed task results are available for 24 hours. After this period, the system deletes the task and its results. The generated image URL also expires after 24 hours, so you must save the image after retrieving the task result.

{
    "request_id": "b67df059-ca6a-9d51-afcd-9b3c4456b1e2",
    "output": {
        "task_id": "53950fb7-281a-4e60-b543-xxxxxxxxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2024-05-16 13:50:01.247",
        "scheduled_time": "2024-05-16 13:50:01.354",
        "end_time": "2024-05-16 13:50:27.795",
        "output_image_url": "http://xxx/result.png"
    },
    "usage": {
        "image_count": 1
    }
}

{
    "request_id":"7574ee8f-38a3-4b1e-9280-11c33ab46e51",
    "output":{
        "task_id":"53950fb7-281a-4e60-b543-xxxxxxxxxxxx",
        "task_status":"RUNNING",
        "task_metrics":{
            "TOTAL":1,
            "SUCCEEDED":1,
            "FAILED":0
        }
    }
}

{
   "request_id":"4246a1de-2aab-9b49-ba87-e0d12e221a06",
   "output":{
      "task_id":"53950fb7-281a-4e60-b543-xxxxxxxxxxxx",
      "task_status":"FAILED",
      "submit_time":"2024-03-22 12:07:07.183",
      "scheduled_time":"2024-03-22 12:07:07.253",
      "end_time":"2024-03-22 12:07:07.604",
      "code":"InternalError.Algo",
      "message":"algorithm process error"
   }
}

Status codes

For common status codes for Model Studio services, see Error messages. This API also returns the following specific status codes:

HTTP status code	Error code	Error message	Description
400	InvalidParameter.JsonPhrase	input json error	Invalid JSON in the request.
400	InvalidParameter.FileDownload	oss download error	Failed to download the input image.
400	InvalidParameter.ImageFormat	read image error	Failed to read the image.
400	InvalidParameter.ImageContent	The image content is not compliant.	The image content is not compliant.
400	InvalidParameter	An input parameter value is out of range: xxx	An input parameter value is out of range.
400	InvalidParameter.ImageResolution	The input image size is too small or too large.	The input image size is too small or too large.
500	InternalError.Algo	algorithm process error	Algorithm error.
500	InternalError.FileUpload	oss upload error	Failed to upload the file.

​Prerequisites

​HTTP call

​Step 1: Create a task

Request headers

Request body

Response

​Step 2: Query the result

Request headers

Path parameters

Response

​Status codes

Prerequisites

HTTP call

Step 1: Create a task

Step 2: Query the result

Status codes