图像擦除补全API参考

本文档仅适用于华北2（北京）地域，且必须使用该地域的API Key。
image-erase-completion 模型当前仅提供免费体验，免费额度用完后不可调用且不支持付费，推荐参考图像编辑-千问或图像编辑-万相2.1获取替代方案。

模型概览

模型名	免费额度（查看）	计费单价	限流（含主账号与RAM子账号）
			任务下发接口QPS限制	同时处理中任务数量
image-erase-completion	500张	目前仅供免费体验。免费额度用完后不可调用，推荐参考图像编辑-千问或图像编辑-万相2.1获取替代方案。	2	1

前提条件

您需要已获取与配置 API Key并配置API Key到环境变量。请将示例代码中的 DASHSCOPE_API_HOST 替换为获取的 API Host。

HTTP调用

为了减少等待时间并且避免请求超时，服务采用异步方式提供。您需要发起两个请求：

创建任务：首先发送一个请求创建文生图任务，该请求会返回任务ID。
根据任务ID查询结果：使用上一步获得的任务ID，查询模型生成的结果。

步骤1：创建任务获取任务ID

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

请求头（Headers）

Content-Typestring必选请求内容类型。固定为application/json。Authorizationstring必选推荐您使用阿里云百炼API-Key，也可填DashScope API-Key。例如：Bearer d1xxx2a。X-DashScope-Asyncstring必选是否开启异步处理。必须开启异步处理，设置为enable。

请求体（Request Body）

modelstring必选调用模型。inputobject必选输入图像的基本信息，比如图像URL。

属性

image_urlstring必选输入图像URL地址或者图像base64数据。URL 需为公网可访问的地址，并支持 HTTP 或 HTTPS 协议。您也可在此获取临时公网URL。图像限制：

图片格式：JPEG、PNG，JPG，BMP，WEBP。
图像分辨率：不低于512×512像素且不超过4096×4096像素。
图像单边长度范围：[512, 4096]，单位像素。
图片大小：不超过10MB。
URL地址中不能包含中文字符。

mask_urlstring必选输入擦除区域掩码图像URL地址或者图像base64数据。URL 需为公网可访问的地址，并支持 HTTP 或 HTTPS 协议。您也可在此获取临时公网URL。图像限制：

图片格式：JPG、JPEG、PNG、HEIF、WEBP。
图像分辨率：不低于512×512像素且不超过4096×4096像素。
图像单边长度范围：[512, 4096]，单位像素。
图片大小：不超过10MB。

在与图像相同大小的空白画布进行涂抹，非0值区域为擦除掩码区域；也可选用人物实例分割直接产生人物的分割结果作为擦除掩码区域。foreground_urlstring 可选输入保留区域掩码图像URL地址或者图像base64数据。URL 需为公网可访问的地址，并支持 HTTP 或 HTTPS 协议。您也可在此获取临时公网URL。图像限制：

图片格式：JPG、JPEG、PNG、HEIF、WEBP。
图像分辨率：不低于512×512像素且不超过4096×4096像素。
图像单边长度范围：[512, 4096]，单位像素。
图片大小：不超过10MB。

在与图像相同大小的空白画布进行涂抹，非0值区域为保留掩码区域；也可选用人物实例分割，通过指定人物ID的方式分离该人物的掩码区域，保留该人物不被擦除。

parametersobject 可选图像处理参数。

属性

fast_modebool可选是否为快速模式，默认为false，快速模式推理耗时约为非快速模式的四分之一，适合不需要生成大量细节的场景。dilate_flagbool可选默认为true，建议若擦除mask为算法分割结果，设置为true；若擦除mask为涂抹结果，设置为false。add_watermark boolean可选添加Generated by AI水印。默认值为true，在输出图像左下角处添加水印。

图像擦除补全

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

响应

outputobject任务输出信息。

属性

task_idstring任务id，任务唯一标识。task_statusstring任务状态。

PENDING：排队中
RUNNING：处理中
SUSPENDED：挂起
SUCCEEDED：执行成功
FAILED：执行失败

codestring接口错误码。接口成功请求不会返回该参数。messagestring接口错误信息。接口成功请求不会返回该参数。request_idstring请求唯一标识。可用于请求明细溯源和问题排查。

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

步骤2：根据任务ID查询结果

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

请求头（Headers）

Authorizationstring必选API-Key，例如：Bearer d1**2a。

URL路径参数（Path parameters）

task_idstring必选任务id。

获取任务结果

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

响应

outputobject输出的任务信息。

属性

task_id string任务id。task_status string任务状态。

PENDING：排队中
RUNNING：处理中
SUSPENDED：挂起
SUCCEEDED：执行成功
FAILED：执行失败

task_metrics object任务统计信息。

属性

TOTAL integer总的任务数。SUCCEEDED integer任务状态为成功的任务数。FAILED integer任务状态为失败的任务数。

submit_time string任务提交时间。scheduled_time string任务执行时间。end_time string任务完成时间。output_image_url string输出图像URL地址。codestring接口错误码。接口成功请求不会返回该参数。messagestring接口错误信息。接口成功请求不会返回该参数。

usageobject输出信息统计。

属性

image_countinteger生成图像的数量。

request_idstring请求唯一标识。可用于请求明细溯源和问题排查。

任务执行成功
任务执行中
任务执行失败

对于本模型，任务在结束之后的状态会持续保留24小时以备客户随时查询，24小时之后，任务将从系统中清除，相关的结果也将一并清除；对应的，任务生成的结果为图像的URL地址，出于安全考虑，该URL的下载有效期也是24小时，需要用户在获取任务结果后根据需要及时使用或者转存。

{
    "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":"video generation error"
   }
}

状态码说明

DashScope阿里云百炼模型服务通用状态码请查阅：错误码。此API还有特定状态码，具体如下所示：

HTTP状态码	接口错误码（code）	接口错误信息（message）	含义说明
400	InvalidParameter.JsonPhrase	input json error	输入JSON错误
400	InvalidParameter.FileDownload	oss download error	输入图像下载失败
400	InvalidParameter.ImageFormat	read image error	读取图像失败
400	InvalidParameter.ImageContent	The image content does not comply with green network verification	图像内容不合规
400	InvalidParameter	the parameters must conform to the specification: xxx	输入参数值超出范围
400	InvalidParameter.ImageResolution	the size of input image is too small or too large	输入图像的尺寸过小或者过大
500	InternalError.Algo	algorithm process error	算法错误
500	InternalError.FileUpload	oss upload error	文件上传失败

​模型概览

​前提条件

​HTTP调用

​步骤1：创建任务获取任务ID

请求头（Headers）

请求体（Request Body）

响应

​步骤2：根据任务ID查询结果

请求头（Headers）

URL路径参数（Path parameters）

响应

​状态码说明

模型概览

前提条件

HTTP调用

步骤1：创建任务获取任务ID

步骤2：根据任务ID查询结果

状态码说明