萬相-通用影像編輯wan2.5模型僅需文本指令,即可基於單張或多張參考映像,實現主體一致的影像編輯、多圖融合等能力。
快速入口:使用指南
在調用前,先擷取API Key,再配置API Key到環境變數。如需通過SDK進行調用,請安裝DashScope SDK。
由於影像編輯任務耗時較長(通常為1-2分鐘),API採用非同步呼叫。整個流程包含 “建立任務 -> 輪詢擷取” 兩個核心步驟,具體如下:
新加坡地區:
SDK 的參數命名與HTTP調用基本一致,參數結構根據語言特性進行封裝。
由於影像編輯任務耗時約30秒~60秒,SDK 在底層封裝了 HTTP 非同步呼叫流程,支援同步、非同步兩種調用方式。
如果模型調用失敗並返回報錯資訊,請參見錯誤碼進行解決。
模型概覽
模型功能 | 輸入樣本 | 輸出映像 |
|---|---|---|
單圖編輯 | ![]() | ![]() 將花卉連衣裙換成一件複古風格的蕾絲長裙,領口和袖口有精緻的刺繡細節。 |
多圖融合 | ![]() | ![]() 將圖1中的鬧鐘放置到圖2的餐桌的花瓶旁邊位置 |
模型名稱 | 模型簡介 | 輸出映像規格 |
|---|---|---|
wan2.5-i2i-preview | 萬相2.5 preview 支援單圖編輯、多圖融合 | 圖片格式:PNG。 映像解析度:
|
調用前,請查閱各地區支援的模型列表與價格。
前提條件
在調用前,先擷取API Key,再配置API Key到環境變數。如需通過SDK進行調用,請安裝DashScope SDK。
HTTP調用
由於影像編輯任務耗時較長(通常為1-2分鐘),API採用非同步呼叫。整個流程包含 “建立任務 -> 輪詢擷取” 兩個核心步驟,具體如下:
具體耗時受限於排隊任務數和服務執行情況,請在擷取結果時耐心等待。
步驟1:建立任務擷取任務ID
新加坡地區:POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis
北京地區:POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis
調用時請將{WorkspaceId}替換為真實的業務空間ID。
- 建立成功後,使用介面返回的
task_id查詢結果,task_id 有效期間為 24 小時。請勿重複建立任務,輪詢擷取即可。 - 新手指引請參見Postman。
請求參數要求標頭(Headers)Content-Typestring(必選)請求內容類型。此參數必須設定為application/json。Authorizationstring(必選)請求身份認證。介面使用阿里雲百鍊API Key進行身份認證。樣本值:Bearer sk-xxxx。X-DashScope-Asyncstring(必選)非同步處理配置參數。HTTP請求只支援非同步,必須設定為enable。請求體(Request Body)modelstring (必選)模型名稱。詳情參見模型列表與價格。樣本值:wan2.5-i2i-preview。input object (必選)輸入的基本資料,如提示詞等。
屬性 prompt string (必選)正向提示詞,用來描述產生映像中期望包含的元素和視覺特點。支援中英文,長度不超過2000個字元,每個漢字/字母佔一個字元,超過部分會自動截斷。提示詞的提示請參見文生圖Prompt指南。樣本值:一隻坐著的橘黃色的貓,表情愉悅,活潑可愛,逼真準確。images array of string (必選)映像URL數組。
string (可選)反向提示詞,用來描述不希望在畫面中看到的內容,可以對畫面進行限制。支援中英文,長度不超過500個字元,超過部分會自動截斷。樣本值:低解析度、錯誤、最差品質、低品質、殘缺、多餘的手指、比例不良等。object (可選)影像處理參數。如設定映像解析度、開啟prompt智能改寫、添加浮水印等。
屬性 size string (可選)設定輸出映像的解析度,格式為寬*高。預設值為 1280*1280。
推薦解析度及對應寬高比
size,系統將預設產生總像素為 1280*1280 的映像,並按以下規則保持寬高比(近似值):
integer (可選)產生圖片的數量。取值範圍為1~4張,預設為4。為控製成本,測試建議顯式設定為1。watermark boolean (可選)是否添加浮水印標識,浮水印位於圖片右下角,文案固定為“AI產生”。
boolean (可選)是否開啟prompt智能改寫。開啟後使用大模型對輸入prompt進行智能改寫,提升綜合表現,但會增加耗時。
integer (可選)隨機數種子,取值範圍是[0, 2147483647]。如果不提供,則演算法自動產生一個隨機數作為種子。如果提供,則根據n的值分別為n張圖片產生seed參數,例如n=4,演算法將分別產生seed、seed+1、seed+2、seed+3作為參數的圖片。若需提升產生結果的可複現性,建議固定seed值。請注意,由於模型產生具有機率性,即使使用相同 seed,也不能保證每次產生結果完全一致。 |
響應參數outputobject任務輸出資訊。
屬性 task_id string任務ID。查詢有效期間24小時。task_status string任務狀態。
枚舉值
string請求唯一標識。可用於請求明細溯源和問題排查。codestring請求失敗的錯誤碼。請求成功時不會返回此參數,詳情請參見錯誤碼。messagestring請求失敗的詳細資料。請求成功時不會返回此參數,詳情請參見錯誤碼。 |
請儲存 task_id,用於查詢任務狀態與結果。 |
步驟2:根據任務ID查詢結果
- 新加坡
- 華北2(北京)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}調用時請將{WorkspaceId}替換為真實的Workspace ID。- 輪詢建議:映像產生過程耗時較長,建議採用輪詢機制,並設定合理的查詢間隔(如 10 秒)來擷取結果。
- 任務狀態流轉:PENDING(排隊中)→ RUNNING(處理中)→ SUCCEEDED(成功)/ FAILED(失敗)。
- 結果連結:任務成功後返回映像連結,有效期間為 24 小時。建議在擷取連結後立即下載並轉存至永久儲存(如阿里雲 OSS)。
請求參數要求標頭(Headers)Authorizationstring(必選)請求身份認證。介面使用阿里雲百鍊API Key進行身份認證。樣本值:Bearer sk-xxxx。URL路徑參數(Path parameters)task_idstring(必選)任務ID。 |
請將 86ecf553-d340-4e21-xxxxxxxxx替換為真實的task_id。各地區的API Key不同。擷取API Key。 若使用華北2(北京)地區的模型,需將base_url替換為https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx,其中{WorkspaceId}需替換為真實的業務空間ID。 |
響應參數outputobject任務輸出資訊。
屬性 task_id string任務ID。查詢有效期間24小時。task_status string任務狀態。
枚舉值
string任務提交時間。時區為UTC+8,格式為 YYYY-MM-DD HH:mm:ss.SSS。scheduled_time string任務執行時間。時區為UTC+8,格式為 YYYY-MM-DD HH:mm:ss.SSS。end_time string任務完成時間。時區為UTC+8,格式為 YYYY-MM-DD HH:mm:ss.SSS。results array of object任務結果清單,包括映像URL、prompt、部分任務執行失敗報錯資訊等。
屬性 orig_prompt string原始輸入的prompt,對應請求參數prompt。actual_prompt string開啟 prompt 智能改寫後,返回實際使用的最佳化後 prompt。若未開啟該功能,則不返回此欄位。url string模型產生圖片的URL地址。code string映像錯誤碼。部分任務執行失敗時會返回該欄位。message string映像錯誤資訊。部分任務執行失敗時會返回該欄位。object任務結果統計。
屬性 TOTAL integer總的任務數。SUCCEEDED integer任務狀態為成功的任務數。FAILED integer任務狀態為失敗的任務數。string請求失敗的錯誤碼。請求成功時不會返回此參數,詳情請參見錯誤碼。messagestring請求失敗的詳細資料。請求成功時不會返回此參數,詳情請參見錯誤碼。object輸出資訊統計。只對成功的結果計數。
屬性 image_count integer模型成功產生圖片的數量。計費公式:費用 = 圖片數量 × 單價。string請求唯一標識。可用於請求明細溯源和問題排查。 |
映像URL僅保留24小時,逾時後會被自動清除,請及時儲存產生的映像。 |
DashScope SDK調用
SDK 的參數命名與HTTP調用基本一致,參數結構根據語言特性進行封裝。
由於影像編輯任務耗時約30秒~60秒,SDK 在底層封裝了 HTTP 非同步呼叫流程,支援同步、非同步兩種調用方式。
具體耗時受限於排隊任務數和服務執行情況,請在擷取結果時耐心等待。
Python SDK調用
- 同步調用
- 非同步呼叫
請求樣本
本樣本支援三種映像輸入方式:公網URL、Base64編碼、本地檔案路徑。響應樣本
url 有效期間24小時,請及時下載映像。
Java SDK調用
- 同步調用
- 非同步呼叫
請求樣本
本樣本支援三種映像輸入方式:公網URL、Base64編碼、本地檔案路徑。響應樣本
url 有效期間24小時,請及時下載映像。
使用限制
- 資料時效:任務task_id和 映像url均只保留 24 小時,到期後將無法查詢或下載。
- 內容審核:輸入prompt、映像和輸出映像均會經過Alibaba Content Security Service審核,包含違規內容的請求將報錯“IPInfringementSuspect”或“DataInspectionFailed”,具體參見錯誤碼。



