映像擦除補全API參考 - Alibaba Cloud Model Studio

相關指南：映像擦除補全

本文檔僅適用於“中國內地（北京）”地區。如需使用模型，需使用“中國內地（北京）”地區的API Key。
image-erase-completion 模型當前僅提供免費體驗，免費額度用完後不可調用且不支援付費，推薦參考影像編輯-千問或影像編輯-萬相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 協議。映像限制：

圖片格式：JPEG、PNG，JPG，BMP，WEBP。
映像解析度：不低於512×512像素且不超過4096×4096像素。
映像單邊長度範圍：[512, 4096]，單位像素。
圖片大小：不超過10MB。
URL地址中不能包含中文字元。

mask_urlstring必選輸入擦除地區掩碼映像URL地址或者映像base64資料。URL 需為公網可訪問的地址，並支援 HTTP 或 HTTPS 協議。映像限制：

圖片格式：JPG、JPEG、PNG、HEIF、WEBP。
映像解析度：不低於512×512像素且不超過4096×4096像素。
映像單邊長度範圍：[512, 4096]，單位像素。
圖片大小：不超過10MB。

在與映像相同大小的空白畫布進行塗抹，非0值地區為擦除掩碼地區；也可選用人物執行個體分割直接產生人物的分割結果作為擦除掩碼地區。foreground_urlstring 可選輸入保留地區掩碼映像URL地址或者映像base64資料。URL 需為公網可訪問的地址，並支援 HTTP 或 HTTPS 協議。映像限制：

圖片格式：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查詢結果

狀態代碼說明