Skip to main content
影像編輯

通用影像編輯-萬相2.1

萬相-通用影像編輯模型支援輸入文本指令,實現擴圖、去浮水印、風格遷移、指令編輯、局部重繪、映像修複等多種影像編輯任務。

本文檔僅適用於“中國內地(北京)”地區。如需使用模型,需使用“中國內地(北京)”地區的API Key

模型概覽

效果樣本

image

原圖

image

把她的頭髮修改為紅色

35779519-bfc3-4b0a-a594-d764fe9a46d83005601501

給她戴上一副墨鏡

image

轉換成法國繪本風格

更多樣本請參見關鍵能力
模型與價格
  • 北京地區
北京地區無免費額度,調用將產生費用,請確認後再操作。

模型名稱

計費單價

限流(主帳號與RAM子帳號共用)

任務下發介面RPS限制

同時處理中任務數量

wanx2.1-imageedit

$0.020070/張

2

2

快速開始

前提條件

在調用前,請擷取API Key,再配置API Key到環境變數(準備下線,併入配置 API Key)。如果通過DashScope SDK進行調用,還需要安裝SDK

範例程式碼

本節示範如何調用通用影像編輯 API 完成一次“局部重繪”任務。
SDK 在底層封裝了非同步處理邏輯,上層介面表現為同步調用(即單次請求並等待最終結果返回);而 curl 樣本則對應兩個獨立的非同步 API 介面:一個用於提交任務,另一個用於查詢結果。
  • Python
  • Java
  • curl
本樣本支援三種映像輸入方式:公網URL、Base64編碼、本地檔案路徑。

請求樣本

import base64
import os
from http import HTTPStatus
from dashscope import ImageSynthesis
import mimetypes

"""
環境要求:
    dashscope python SDK >= 1.23.8
安裝/升級SDK:
    pip install -U dashscope
"""

# 若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
api_key = os.getenv("DASHSCOPE_API_KEY")

# --- 輔助函數:用於 Base 64 編碼 ---
# 格式為 data:{MIME_type};base64,{base64_data}
def encode_file(file_path):
    mime_type, _ = mimetypes.guess_type(file_path)
    if not mime_type or not mime_type.startswith("image/"):
        raise ValueError("不支援或無法識別的映像格式")
    with open(file_path, "rb") as image_file:
        encoded_string = base64.b64encode(image_file.read()).decode('utf-8')
    return f"data:{mime_type};base64,{encoded_string}"

"""
映像輸入方式說明:
以下提供了三種圖片輸入方式,三選一即可

1. 使用公網URL - 適合已有公開可訪問的圖片
2. 使用本地檔案 - 適合本地開發測試
3. 使用Base64編碼 - 適合私人圖片或需要加密傳輸的情境
"""

# 【方式一】使用公網圖片 URL
mask_image_url = "http://wanx.alicdn.com/material/20250318/description_edit_with_mask_3_mask.png"
base_image_url = "http://wanx.alicdn.com/material/20250318/description_edit_with_mask_3.jpeg"

# 【方式二】使用本地檔案(支援絕對路徑和相對路徑)
# 格式要求:file:// + 檔案路徑
# 樣本(絕對路徑):
# mask_image_url = "file://" + "/path/to/your/mask_image.png"     # Linux/macOS
# base_image_url = "file://" + "C:/path/to/your/base_image.jpeg"  # Windows
# 樣本(相對路徑):
# mask_image_url = "file://" + "./mask_image.png"                 # 以實際路徑為準
# base_image_url = "file://" + "./base_image.jpeg"                # 以實際路徑為準

# 【方式三】使用Base64編碼的圖片
# mask_image_url = encode_file("./mask_image.png")               # 以實際路徑為準
# base_image_url = encode_file("./base_image.jpeg")              # 以實際路徑為準

def sample_sync_call_imageedit():
    print('please wait...')
    rsp = ImageSynthesis.call(api_key=api_key,
                              model="wanx2.1-imageedit",
                              function="description_edit_with_mask",
                              prompt="陶瓷兔子拿著陶瓷小花",
                              mask_image_url=mask_image_url,
                              base_image_url=base_image_url,
                              n=1)
    assert rsp.status_code == HTTPStatus.OK

    print('response: %s' % rsp)
    if rsp.status_code == HTTPStatus.OK:
        for result in rsp.output.results:
            print("---------------------------")
            print(result.url)
    else:
        print('sync_call Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))

if __name__ == '__main__':
    sample_sync_call_imageedit()

響應樣本

url 有效期間24小時,請及時下載映像。
{
    "status_code": 200,
    "request_id": "dc41682c-4e4a-9010-bc6f-xxxxxx",
    "code": null,
    "message": "",
    "output": {
        "task_id": "6e319d88-a07a-420c-9493-xxxxxx",
        "task_status": "SUCCEEDED",
        "results": [
            {
                "url": "https://dashscope-result-wlcb-acdr-1.oss-cn-wulanchabu-acdr-1.aliyuncs.com/xxx.png?xxxxxx"
            }
        ],
        "submit_time": "2025-05-26 14:58:27.320",
        "scheduled_time": "2025-05-26 14:58:27.339",
        "end_time": "2025-05-26 14:58:39.170",
        "task_metrics": {
            "TOTAL": 1,
            "SUCCEEDED": 1,
            "FAILED": 0
        }
    },
    "usage": {
        "image_count": 1
    }
}

關鍵能力

通用影像編輯API 通過 function 參數來指定不同的影像編輯功能。所有功能均遵循快速開始的調用方式。 下文以curl調用為例,僅列出各功能專屬的 inputparameters JSON 片段,用於說明請求體中需配置的內容。
提示:curl完整請求應包含 model、input、parameters 等頂層欄位,具體結構請參考通用影像編輯API參考

全域風格化

將整張映像遷移至指定的藝術風格。使用情境包括:繪本創作、社交媒體配圖(產生符合特定視覺風格的背景或概念圖)等。
  • 如何使用:將參數function設定為stylization_all
  • 支援的風格
    • 法國繪本風格
    • 金箔藝術風格
  • 搭配使用的參數parameters.strength (0.0-1.0, 預設 0.5) 控制修改幅度,值越小越接近原圖。
  • 提示詞技巧:使用“轉換成xx風格”的句式,如“轉換成法國繪本風格”。

請求樣本

{
  "input": {
    "function": "stylization_all",
    "prompt": "轉換成法國繪本風格",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/stylization_all_3.png"
  },
  "parameters": {
    "strength": 0.5
  }
}

輸入映像

輸出映像

提示詞:轉換成法國繪本風格

提示詞:轉換成金箔藝術風格

image

image

image

image

image

image

通過strength控製圖像修改幅度
通過parameters.strength參數來控製圖像修改幅度。該參數為可選值,取值範圍為[0.0, 1.0],預設值為0.5。值越接近0,則越接近原圖效果;值越接近1,對原圖的修改幅度越大。
輸入提示詞:轉換成法國繪本風格。

輸入映像

輸出映像

strength=0.0(最小值)

strength=0.5(預設值)

strength=1.0(最大值)

image

image

image

image

局部風格化

僅對映像的局部地區進行風格遷移。使用情境包括:個人化定製(如人物服裝風格化)、廣告設計(突出商品)。
  • 如何使用:將參數function設定為stylization_local
  • 支援的風格:中英文對照如下:
    • 冰雕:ice
    • 雲朵:cloud
    • 花燈:chinese festive lantern
    • 木板:wooden
    • 青花瓷:blue and white porcelain
    • 毛茸茸:fluffy
    • 毛線:weaving
    • 氣球:balloon
  • 提示詞技巧:使用“把xx變成xx風格”的句式,如“把房子變成木板風格”。

請求樣本

{
  "input": {
    "function": "stylization_local",
    "prompt": "把房子變成木板風格",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/stylization_local_1.png"
  }
}

輸入映像

輸出映像

image

image

冰雕

image

雲朵

image

花燈

image

木板

image

青花瓷

image

毛茸茸

image
毛線

image

氣球

指令編輯

無需指定地區,僅通過文本指令即可增加或修改映像內容。使用情境包括:為人物添加配飾、更換髮色等無需精確定位的簡單編輯。
  • 如何使用:將參數function設定為description_edit
  • 搭配使用的參數parameters.strength (0.0-1.0, 預設 0.5) 控制修改幅度,值越小越接近原圖。
  • 提示詞技巧:顯式寫明“添加”“修改”這類操作描述。刪除操作推薦使用局部重繪

請求樣本

{
  "input": {
    "function": "description_edit",
    "prompt": "給小貓添加一副墨鏡",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/description_edit_1.jpeg"
  },
  "parameters": {
    "strength": 0.5
  }
}

能力

輸入映像

輸出映像

添加元素

image

image

給小貓添加一副墨鏡。

修改元素

image

image

把她的頭髮修改為紅色。

通過strength控製圖像修改幅度
通過parameters.strength參數來控製圖像修改幅度。該參數為可選值,取值範圍為[0.0, 1.0],預設值為0.5。值越接近0,則越接近原圖效果;值越接近1,對原圖的修改幅度越大。
輸入提示詞:將她穿的衣服修改為彩色印花的沙灘襯衣。

輸入映像

輸出映像

strength=0.0(最小值)

strength=0.5(預設值)

strength=1.0(最大值)

image

image

image

image

局部重繪

通過提供塗抹地區(mask)映像,對指定地區進行增加、修改或刪除操作。使用情境包括:換裝、替換物體、移除幹擾物等需要精確控制範圍的編輯。
  • 如何使用:將參數function設定為description_edit_with_mask
  • 塗抹地區要求:需要提供 mask_image_url,塗抹映像中白色地區為待編輯地區,黑色為保留地區。
  • 提示詞技巧:顯式寫明“添加”“修改”以及描述刪除後的內容這類操作描述。
    • 增加/修改:可描述動作(“給小狗添加一頂帽子”)或描述最終結果(“一隻戴著帽子的小狗”)。
    • 刪除:若刪除對象較小,prompt 可留空 ("");若刪除對象較大,prompt 需描述刪除後應出現的背景內容(如“一個透明玻璃花瓶放在桌子上”),而非“刪除小熊”。

請求樣本

{
  "input": {
    "function": "description_edit_with_mask",
    "prompt": "一隻陶瓷兔子抱著一朵陶瓷花",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/description_edit_with_mask_1.jpeg",
    "mask_image_url": "http://wanx.alicdn.com/material/20250318/description_edit_with_mask_1_mask.png"
  }
}
能力輸入映像輸入塗抹地區映像(白色為待編輯地區)輸出映像
增加元素
image
image
image
給小狗添加一頂帽子。
提示詞也可以寫為“一隻戴著帽子的小狗”(描述期望的映像內容)。
修改元素
image
image
image
一隻陶瓷兔子抱著一朵陶瓷花。
提示詞也可以寫為“將陶瓷兔子抱著的胡蘿蔔換做陶瓷花”(描述動作)。
刪除元素
image
image
image
一個透明玻璃花瓶放在桌子上。
提示詞需要描述刪除後的內容,不要寫為“刪除一隻棕色的小熊”。

去文字浮水印

法律風險提示使用本功能處理受著作權保護的映像(如去除他人品牌浮水印)可能構成侵權行為。請確保您擁有所處理映像的合法使用權,並自行承擔所有相關法律責任。
去除映像中的中英文字元或常見浮水印。使用情境包括:素材二次處理、廣告圖淨化等。
  • 如何使用:將參數function設定為remove_watermark
  • 提示詞技巧:可使用通用指令如“去除映像中的文字”,或指定類型如“去除英文文字”。

請求樣本

{
  "input": {
    "function": "remove_watermark",
    "prompt": "去除映像中的文字",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/remove_watermark_1.png"
  }
}

輸入映像

輸出映像(去除映像中的文字)

image

image

image

image

擴圖

沿映像的上、下、左、右四個方向按比例擴充畫布,並智能填充內容。使用情境包括:調整構圖、將豎圖擴充為橫圖以適配不同媒介尺寸。
  • 如何使用:將參數function設定為expand
  • 搭配使用的參數parameters中的top_scale, bottom_scale, left_scale, right_scale 分別控制四個方向的擴充比例(如全部設定為 1.5,表示擴充為原尺寸的 1.5倍)。
  • 提示詞技巧:描述擴充後期望看到的完整情境內容。

請求樣本

{
  "input": {
    "function": "expand",
    "prompt": "一家人在公園草坪上",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/expand_1.jpeg"
  },
  "parameters": {
    "top_scale": 1.5,
    "bottom_scale": 1.5,
    "left_scale": 1.5,
    "right_scale": 1.5
  }
}

輸入映像

輸出映像

image

image

映像超分

增益圖像清晰度並支援放大,將低解析度或模糊映像變得清晰。使用情境包括:老照片修複、提升素材解析度以滿足高清列印或展示需求。
  • 如何使用:將參數function設定為super_resolution
  • 搭配使用的參數parameters.upscale_factor (1-4, 預設 1) 控制放大倍數。當值為 1 時,僅提升清晰度而不放大。
  • 提示詞技巧:可使用“映像超分”或描述映像內容。

請求樣本

{
  "input": {
    "function": "super_resolution",
    "prompt": "映像超分",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/super_resolution_1.jpeg"
  },
  "parameters": {
    "upscale_factor": 2
  }
}

輸入映像(模糊映像)

輸出映像(清晰映像)

image

image

映像上色

將黑白或灰階映像轉換為彩色映像(黑白/灰階 → 彩色)。使用情境包括:歷史照片上色、為線稿或灰階圖填充顏色。
  • 如何使用:將參數function設定為colorization
  • 提示詞技巧:可留空由模型自動上色,或通過提示詞指定關鍵元素的顏色(如“藍色背景,黃色葉子”)。

請求樣本

{
  "input": {
    "function": "colorization",
    "prompt": "藍色背景,黃色的葉子",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/colorization_1.jpeg"
  }
}

輸入映像

輸出映像

image

image

線稿生圖(支援塗鴉作畫)

基於輸入映像的輪廓(線稿)並結合提示詞產生新映像。使用情境包括:建築概念設計、插畫設計、塗鴉作畫等。
  • 如何使用:將參數function設定為doodle
  • 搭配使用參數parameters.is_sketch,用來控制模型的產生效果。
    • false (預設):輸入為 RGB 映像,模型會先提取線稿再產生映像(RGB映像 → 線稿 → 新圖)。
    • true:輸入為 RGB 映像(如塗鴉或線稿),模型將直接基於此映像產生映像(RGB映像 → 新圖)。
  • 提示詞技巧:描述期望產生的映像內容,描述越具體,產生效果越好。
{
  "input": {
    "function": "doodle",
    "prompt": "北歐極簡風格的客廳。",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/doodle_1.png"
  },
  "parameters": {
    "is_sketch": false
  }
}

請求樣本2:塗鴉作畫

{
  "input": {
    "function": "doodle",
    "prompt": "一顆樹,二次元動漫風格",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/doodle_2.png"
  },
  "parameters": {
    "is_sketch": true
  }
}

能力

輸入映像

輸出映像

線稿生圖

(is_sketch=false)

image

image

北歐極簡風格的客廳。

塗鴉作畫

(is_sketch=true)

image

image

一顆樹,二次元動漫風格。

參考卡通形象生圖

法律風險提示使用本功能處理受著作權保護的卡通形象可能構成侵權行為。請確保您擁有所參考形象的合法使用權,或使用您原創的形象,並自行承擔所有相關法律責任。
  • 如何使用:將參數function設定為control_cartoon_feature
  • 提示詞技巧採用“卡通形象...”的句式,詳細描述形象的動作和所處環境。

請求樣本2:塗鴉作畫

{
  "input": {
    "function": "control_cartoon_feature",
    "prompt": "卡通形象小心翼翼地探出頭,窺視著房間內一顆璀璨的藍色寶石",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/control_cartoon_feature_1.png"
  }
}

輸入映像

輸出映像

image

image

應用於生產環境

最佳實務

  • 非同步輪詢:采輪詢查詢非同步任務結果時,建議採用合理的輪詢策略(如前30秒每3秒一次,之後拉長間隔),避免因過於頻繁的請求而觸發限流。
  • 參數調優:對於 strength 等影響效果的關鍵參數,建議在正式上線前進行小範圍測試,找到最適合業務情境的數值。
  • 映像儲存:API 返回的映像 URL 有效期間24小時。請及時將產生的映像下載並轉存到您自己的持久化儲存服務中(如阿里雲 OSS)。

風險防範

  • 錯誤處理:對任務查詢結果中的 task_status 進行判斷。對於 FAILED 狀態,應記錄 codemessage 以便排查。部分錯誤(如系統逾時)可能是瞬時的,可設計重試邏輯。
  • Alibaba Content Security Service:API 會對輸入和輸出內容進行安全性稽核。若內容不合規,請求將會報錯 DataInspectionFailed 錯誤。

API 參考

關於萬相-通用影像編輯模型的輸入與輸出參數,請參見通用影像編輯API參考

計費與限流

  • 模型免費額度和計費單價請參見模型列表與價格
  • 模型限流請參見萬相
  • 計費說明:
    • 按成功產生的 映像張數 計費。僅當介面返回task_statusSUCCEEDED 並成功產生映像後,才會計費。
    • 模型調用失敗或處理錯誤不產生任何費用,也不消耗新人免費額度

錯誤碼

如果模型調用失敗並返回報錯資訊,請參見錯誤資訊進行解決。

常見問題

Q: 為什麼我的工作會失敗(FAILED)? A: 任務失敗的常見原因包括:
  1. 內容審核不通過:輸入或產生的映像內容觸發了安全性原則。
  2. 參數錯誤:請求中的參數不合法,如 function 名稱錯誤、URL 無法訪問等。
  3. 模型內部錯誤:模型在處理過程中遇到預期外的問題。請檢查任務查詢響應中的codeerror 欄位,擷取具體錯誤碼和資訊,以便定位問題。
Token Plan
模型體驗
用量統計與效能監控
資產中心
服務支援