image erase completion, image editing and generation, human erase, layout erase - Alibaba Cloud Model Studio

This document details the parameters for the image erase completion model. This model removes one or more elements from an image, such as people, pets, objects, text, or watermarks, while preserving the background. You can specify the areas to remove using a mask image.

Related guide: Image erase completion

Important

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-TypestringRequired

The content type of the request. The value must be application/json.

AuthorizationstringRequired

We recommend using your Model Studio API key. You can also use your DashScope API key. Example: Bearer d1xxx2a.

X-DashScope-AsyncstringRequired

Specifies whether to enable asynchronous processing. You must set this parameter to enable.

Request body

modelstringRequired

The model to call.

inputobjectRequired

Input image details, such as the image URL.

Properties

image_urlstringRequired

The 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_urlstringRequired

The 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 Optional

The 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 Optional

Parameters for image processing.

Properties

fast_modeboolOptional

Specifies 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_flagboolOptional

The 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 booleanOptional

Adds 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

outputobject

Task output details.

Properties

task_idstring

The unique task identifier.

task_statusstring

The 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.

codestring

The error code. This parameter is not returned if the request is successful.

messagestring

The error message. This parameter is not returned if the request is successful.

request_idstring

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

Successful response

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

Error response

{
    "code":"InvalidApiKey",
    "message":"Invalid API-key provided.",
    "request_id":"fb53c4ec-1c12-4fc4-a580-xxxxxxxxxxxx"
}

Step 2: Query the result

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

Request headers

AuthorizationstringRequired

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

Path parameters

task_idstringRequired

The 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

outputobject

Task output details.

Properties

task_id string

The task ID.

task_status string

The 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 object

Task statistics.

Properties

TOTAL integer

The total number of tasks.

SUCCEEDED integer

The number of successful tasks.

FAILED integer

The number of failed tasks.

submit_time string

The time the task was submitted.

scheduled_time string

The time the task started running.

end_time string

The time the task was completed.

output_image_url string

The URL of the output image.

codestring

The error code. This parameter is not returned if the request is successful.

messagestring

The error message. This parameter is not returned if the request is successful.

usageobject

Usage statistics.

Properties

image_countinteger

The number of generated images.

request_idstring

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

Completed 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
    }
}

In-progress task

{
    "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
        }
    }
}

Failed task

{
   "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.