調用映像擦除補全API移除人物浮水印與物體-大模型服務平台百鍊-阿里雲

本文介紹映像擦除補全模型的輸入輸出參數。映像擦除補全通過指定映像mask中要刪除的人體、寵物、物品、文字、浮水印等映像地區，在保留背景的同時移除映像中的一個或多個人物、物體、文字等元素。

相關指南：映像擦除補全

重要

本文檔僅適用於“中國大陸（北京）”地區。如需使用模型，需使用“中國大陸（北京）”地區的API Key。
image-erase-completion 模型當前僅提供免費體驗，免費額度用完後不可調用且不支援付費，推薦參考影像編輯-通義千問或影像編輯-通義萬相擷取替代方案。

前提條件

您需要已準備工作：擷取與配置 API Key並配置API Key到環境變數（準備下線，併入配置 API Key）。

HTTP調用

為了減少等待時間並且避免請求逾時，服務採用非同步方式提供。您需要發起兩個請求：

建立任務：首先發送一個請求建立文生圖任務，該請求會返回任務ID。
根據任務ID查詢結果：使用上一步獲得的任務ID，查詢模型產生的結果。

步驟1：建立任務擷取任務ID

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

要求標頭（Headers）	映像擦除補全 `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 必選請求內容類型。固定為`application/json`。
Authorization string 必選推薦您使用阿里雲百鍊API-Key，也可填DashScope API-Key。例如：Bearer d1xxx2a。
X-DashScope-Async string 必選是否開啟非同步處理。必須開啟非同步處理，設定為`enable`。
請求體（Request Body）
model string 必選調用模型。
input object 必選輸入映像的基本資料，比如映像URL。屬性 image_url string 必選輸入映像URL地址或者映像base64資料。 URL 需為公網可訪問的地址，並支援 HTTP 或 HTTPS 協議。映像限制：圖片格式：JPEG、PNG，JPG，BMP，WEBP。映像解析度：不低於512×512像素且不超過4096×4096像素。映像單邊長度範圍：[512, 4096]，單位像素。圖片大小：不超過10MB。 URL地址中不能包含中文字元。 mask_url string 必選輸入擦除地區掩碼映像URL地址或者映像base64資料。 URL 需為公網可訪問的地址，並支援 HTTP 或 HTTPS 協議。映像限制：圖片格式：JPG、JPEG、PNG、HEIF、WEBP。映像解析度：不低於512×512像素且不超過4096×4096像素。映像單邊長度範圍：[512, 4096]，單位像素。圖片大小：不超過10MB。在與映像相同大小的空白畫布進行塗抹，非0值地區為擦除掩碼地區；也可選用人物執行個體分割直接產生人物的分割結果作為擦除掩碼地區。 foreground_url string 可選輸入保留地區掩碼映像URL地址或者映像base64資料。 URL 需為公網可訪問的地址，並支援 HTTP 或 HTTPS 協議。映像限制：圖片格式：JPG、JPEG、PNG、HEIF、WEBP。映像解析度：不低於512×512像素且不超過4096×4096像素。映像單邊長度範圍：[512, 4096]，單位像素。圖片大小：不超過10MB。在與映像相同大小的空白畫布進行塗抹，非0值地區為保留掩碼地區；也可選用人物執行個體分割，通過指定人物ID的方式分離該人物的掩碼地區，保留該人物不被擦除。
parameters object 可選影像處理參數。屬性 fast_mode bool 可選是否為快速模式，預設為false，快速模式推理耗時約為非快速模式的四分之一，適合不需要產生大量細節的情境。 dilate_flag bool 可選預設為true，建議若擦除mask為演算法分割結果，設定為true；若擦除mask為塗抹結果，設定為false。 add_watermark boolean 可選添加`Generated by AI`浮水印。預設值為true，在輸出映像左下角處添加浮水印。

響應	成功響應 `{ "output": { "task_status": "PENDING", "task_id": "53950fb7-281a-4e60-b543-xxxxxxxxxxxx" }, "request_id": "1027557e-8c3f-9db5-8cd2-xxxxxxxxxxxx" }` 異常響應 `{ "code":"InvalidApiKey", "message":"Invalid API-key provided.", "request_id":"fb53c4ec-1c12-4fc4-a580-xxxxxxxxxxxx" }`
output object 任務輸出資訊。屬性 task_id string 任務id，任務唯一標識。 task_status string 任務狀態。 PENDING：排隊中 RUNNING：處理中 SUSPENDED：掛起 SUCCEEDED：執行成功 FAILED：執行失敗
code string 介面錯誤碼。介面成功請求不會返回該參數。
message string 介面錯誤資訊。介面成功請求不會返回該參數。
request_id string 請求唯一標識。可用於請求明細溯源和問題排查。

步驟2：根據任務ID查詢結果

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

要求標頭（Headers）	擷取任務結果 `curl -X GET \ --header "Authorization: Bearer $DASHSCOPE_API_KEY" \ https://dashscope.aliyuncs.com/api/v1/tasks/53950fb7-281a-4e60-b543-xxxxxxxxxxxx`
Authorization string 必選 API-Key，例如：Bearer d1**2a。
URL路徑參數（Path parameters）
task_id string 必選任務id。

響應	任務執行成功對於本模型，任務在結束之後的狀態會持續保留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" } }`
output object 輸出的任務資訊。屬性 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地址。 code string 介面錯誤碼。介面成功請求不會返回該參數。 message string 介面錯誤資訊。介面成功請求不會返回該參數。
usage object 輸出資訊統計。屬性 image_count integer 產生映像的數量。
request_id string 請求唯一標識。可用於請求明細溯源和問題排查。

狀態代碼說明

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	檔案上傳失敗

要求標頭（Headers）	映像擦除補全 `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 必選請求內容類型。固定為`application/json`。
Authorization string 必選推薦您使用阿里雲百鍊API-Key，也可填DashScope API-Key。例如：Bearer d1xxx2a。
X-DashScope-Async string 必選是否開啟非同步處理。必須開啟非同步處理，設定為`enable`。
請求體（Request Body）
model string 必選調用模型。
input object 必選輸入映像的基本資料，比如映像URL。屬性 image_url string 必選輸入映像URL地址或者映像base64資料。 URL 需為公網可訪問的地址，並支援 HTTP 或 HTTPS 協議。映像限制：圖片格式：JPEG、PNG，JPG，BMP，WEBP。映像解析度：不低於512×512像素且不超過4096×4096像素。映像單邊長度範圍：[512, 4096]，單位像素。圖片大小：不超過10MB。 URL地址中不能包含中文字元。 mask_url string 必選輸入擦除地區掩碼映像URL地址或者映像base64資料。 URL 需為公網可訪問的地址，並支援 HTTP 或 HTTPS 協議。映像限制：圖片格式：JPG、JPEG、PNG、HEIF、WEBP。映像解析度：不低於512×512像素且不超過4096×4096像素。映像單邊長度範圍：[512, 4096]，單位像素。圖片大小：不超過10MB。在與映像相同大小的空白畫布進行塗抹，非0值地區為擦除掩碼地區；也可選用人物執行個體分割直接產生人物的分割結果作為擦除掩碼地區。 foreground_url string 可選輸入保留地區掩碼映像URL地址或者映像base64資料。 URL 需為公網可訪問的地址，並支援 HTTP 或 HTTPS 協議。映像限制：圖片格式：JPG、JPEG、PNG、HEIF、WEBP。映像解析度：不低於512×512像素且不超過4096×4096像素。映像單邊長度範圍：[512, 4096]，單位像素。圖片大小：不超過10MB。在與映像相同大小的空白畫布進行塗抹，非0值地區為保留掩碼地區；也可選用人物執行個體分割，通過指定人物ID的方式分離該人物的掩碼地區，保留該人物不被擦除。
parameters object 可選影像處理參數。屬性 fast_mode bool 可選是否為快速模式，預設為false，快速模式推理耗時約為非快速模式的四分之一，適合不需要產生大量細節的情境。 dilate_flag bool 可選預設為true，建議若擦除mask為演算法分割結果，設定為true；若擦除mask為塗抹結果，設定為false。 add_watermark boolean 可選添加`Generated by AI`浮水印。預設值為true，在輸出映像左下角處添加浮水印。

響應	任務執行成功對於本模型，任務在結束之後的狀態會持續保留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" } }`
output object 輸出的任務資訊。屬性 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地址。 code string 介面錯誤碼。介面成功請求不會返回該參數。 message string 介面錯誤資訊。介面成功請求不會返回該參數。
usage object 輸出資訊統計。屬性 image_count integer 產生映像的數量。
request_id string 請求唯一標識。可用於請求明細溯源和問題排查。

前提條件

HTTP調用

步驟1：建立任務擷取任務ID

要求標頭（Headers）

映像擦除補全

請求體（Request Body）

響應

成功響應

異常響應

步驟2：根據任務ID查詢結果

要求標頭（Headers）

擷取任務結果

URL路徑參數（Path parameters）

響應

任務執行成功

任務執行中

任務執行失敗

狀態代碼說明