All Products
Search

This Product

    Alibaba Cloud Model Studio:Image erase completion API reference

    Document Center

    Alibaba Cloud Model Studio:Image erase completion API reference

    Last Updated:Jun 10, 2026

    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

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

    Content-Type string Required

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

    Authorization string Required

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

    X-DashScope-Async string Required

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

    Request body

    model string Required

    The model to call.

    input object Required

    Input image details, such as the image URL.

    Properties

    image_url string Required

    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_url string Required

    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_url string 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.

    parameters object Optional

    Parameters for image processing.

    Properties

    fast_mode bool Optional

    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_flag bool Optional

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

    Adds a Generated by AI watermark. The default value is true, which adds the watermark to the bottom-left corner of the output image.

    Response

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

    output object

    Task output details.

    Properties

    task_id string

    The unique task identifier.

    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.

    code string

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

    message string

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

    request_id string

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

    Step 2: Query the result

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

    Request headers

    Task result

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

    Authorization string Required

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

    Path parameters

    task_id string Required

    The task ID.

    Response

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

    output object

    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.

    code string

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

    message string

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

    usage object

    Usage statistics.

    Properties

    image_count integer

    The number of generated images.

    request_id string

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

    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.