Skip to main content
萬相-早期視頻模型(2.1-2.6)

萬相-視頻編輯API參考(2.1)

萬相2.1-視頻編輯統一模型支援文本、映像、視頻等多種模態輸入,可執行多種視頻產生與編輯任務。

相關文檔使用指南

適用範圍

為確保調用成功,請務必保證模型、Endpoint URL 和 API Key 均屬於同一地區。跨地區調用將會失敗。
本文的範例程式碼適用於新加坡地區
阿里雲百鍊為華北2(北京)、新加坡地區推出了業務空間專屬網域名稱,能夠為推理請求提供卓越的效能和更高的穩定性,建議遷移至新網域名稱:
  • 華北2(北京)地區:從 https://dashscope.aliyuncs.com 遷移至 https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • 新加坡地區:從 https://dashscope-intl.aliyuncs.com 遷移至 https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
其中 {WorkspaceId} 為您的業務空間 ID,可在阿里雲百鍊控制台的業務空間詳情頁面查看。現有網域名稱仍可正常使用。

HTTP調用

視頻編輯統一模型的處理耗時較長(約5-10分鐘),API採用非同步呼叫的方式。整個流程包含 “建立任務 -> 輪詢擷取” 兩個核心步驟,具體如下:

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

  • 新加坡
  • 北京
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis調用時請將{WorkspaceId}替換為真實的業務空間ID

請求參數

要求標頭(Headers)
Content-Typestring(必選)請求內容類型。此參數必須設定為application/jsonAuthorizationstring(必選)請求身份認證。介面使用阿里雲百鍊API Key進行身份認證。樣本值:Bearer sk-xxxx。X-DashScope-Asyncstring(必選)非同步處理配置參數。HTTP請求只支援非同步,必須設定為enable
缺少此要求標頭將報錯:“current user api does not support synchronous calls”。
請求體(Request Body)
  • 多圖參考
  • 視頻重繪
  • 局部編輯
  • 視頻延展
  • 視頻畫面擴充
model string (必選)模型名稱。樣本值:wan2.1-vace-plus。
input object (必選)輸入的基本資料,如提示詞等。

屬性

promptstring(必選)提示詞,用來描述產生視頻中期望包含的元素和視覺特點。支援中英文,長度不超過800個字元,每個漢字/字母佔一個字元,超過部分會自動截斷。提示詞技巧請參見文生視頻/圖生視頻Prompt指南functionstring(必選)功能名稱。多圖參考設定為image_reference多圖參考支援最多3張參考圖。映像內容可以包括主體與背景,例如人物、動物、服飾、情境等。使用 prompt 描述期望產生的視頻畫面內容,模型可將多張圖片融合產生連貫的視頻內容。ref_images_urlarray[string] (必選)輸入參考映像的URL 數組。
  1. 公網URL:
參考映像支援1-3 張映像,若超過 3 張,則僅保留前 3 張作為輸入。映像限制:
  • 映像格式:JPG、JPEG、PNG、BMP、TIFF、WEBP。
  • 映像解析度:映像的寬和高範圍在[360, 2000],單位像素。
  • 映像大小:不超過10MB。
  • URL地址中不能包含中文字元。
使用建議:
  • 若使用參考映像中的主體時,建議每張映像中僅包含一個主體。背景建議為純色(如白色或單一顏色),以便更好地突出主體。
  • 若使用參考映像的背景時,背景映像最多隻有一張,且背景映像中不包含任何主體對象。
parameters object (可選)視頻處理參數,如設定浮水印等。

屬性

obj_or_bg array[string] (可選)該參數用於標識每張參考映像的用途,與 ref_images_url 參數一一對應。數組中每個元素表示對應位置的映像為“主體”還是“背景”:
  • obj:表示該映像作為主體參考。
  • bg:表示該映像作為背景參考 (最多僅允許一個)。
使用說明:
  • 建議傳入該參數,且長度必須與 ref_images_url保持一致,否則將報錯。
  • 僅當 ref_images_url為單元素數組時,可不傳,此時預設值為 ["obj"]
樣本值: ["obj", "obj", "bg"]。size string (可選)產生視頻的解析度(寬*高)。目前支援產生720P 視頻,解析度的取值為:
  • 1280*720(預設值):視頻寬高比為16:9。其中,1280代表寬度,720代表高度。
  • 720*1280:視頻寬高比為9:16。
  • 960*960:視頻寬高比為1:1。
  • 832*1088:視頻寬高比為3:4。
  • 1088*832:視頻寬高比為4:3。
duration integer (可選)視頻產生時間長度,單位為秒。當前參數值固定為5,且不支援修改。模型將始終產生5秒時間長度的視頻。prompt_extendbool (可選)是否開啟prompt智能改寫。開啟後使用大模型對輸入prompt進行智能改寫。對於較短的prompt產生效果提升明顯,但會增加耗時。
  • true(預設值):開啟智能改寫。
  • false:關閉智能改寫。
seedinteger(可選)隨機數種子,用於控制模型產生內容的隨機性。seed參數取值範圍是[0, 2147483647]如果不提供,則演算法自動產生一個隨機數作為種子。如果您希望產生內容保持相對穩定,請使用相同的seed參數值。watermark bool(可選)是否添加浮水印標識,浮水印位於圖片右下角,文案為“AI產生”。
  • false(預設值):不添加浮水印。
  • true:添加浮水印。
  • 多圖參考
  • 視頻重繪
  • 局部編輯
  • 視頻延展
  • 視頻畫面擴充
新加坡和北京地區的API Key不同,擷取API Key
# 以下為新加坡地區URL,調用時請將{WorkspaceId}替換為真實的業務空間ID,各地區的URL不同。
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "wan2.1-vace-plus",
    "input": {
        "function": "image_reference",
        "prompt": "視頻中,一位女孩自晨霧繚繞的古老森林深處款款走出,她步伐輕盈,鏡頭捕捉她每一個靈動瞬間。當她站定,環顧四周蔥鬱林木時,她臉上綻放出驚喜與喜悅交織的笑容。這一幕,定格在了光影交錯的瞬間,記錄下她與大自然的美妙邂逅。",
        "ref_images_url": [
            "http://wanx.alicdn.com/material/20250318/image_reference_2_5_16.png",
            "http://wanx.alicdn.com/material/20250318/image_reference_1_5_16.png"
        ]
    },
    "parameters": {
        "prompt_extend": true,
        "obj_or_bg": ["obj","bg"],
        "size": "1280*720"
    }
}'

響應參數

output object任務輸出資訊。

屬性

task_id string任務ID。查詢有效期間24小時。task_status string任務狀態。

枚舉值

  • PENDING:任務排隊中
  • RUNNING:任務處理中
  • SUCCEEDED:任務執行成功
  • FAILED:任務執行失敗
  • CANCELED:任務已取消
  • UNKNOWN:任務不存在或狀態未知
request_idstring請求唯一標識。可用於請求明細溯源和問題排查。codestring請求失敗的錯誤碼。請求成功時不會返回此參數,詳情請參見錯誤碼messagestring請求失敗的詳細資料。請求成功時不會返回此參數,詳情請參見錯誤碼
  • 成功響應
  • 異常響應
請儲存 task_id,用於查詢任務狀態與結果。
{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

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

  • 新加坡
  • 北京
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}調用時請將{WorkspaceId}替換為真實的業務空間ID

請求參數

要求標頭(Headers)
Authorizationstring(必選)請求身份認證。介面使用阿里雲百鍊API Key進行身份認證。樣本值:Bearer sk-xxxx。
URL路徑參數(Path parameters)
task_id string(必選)任務ID。
  • 查詢任務結果
{task_id}完整替換為上一步介面返回的task_id的值。task_id查詢有效期間為24小時,並請將{WorkspaceId}替換為真實的業務空間ID
curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

響應參數

outputobject任務輸出資訊。

屬性

task_id string任務ID。查詢有效期間24小時。task_status string任務狀態。

枚舉值

  • PENDING:任務排隊中
  • RUNNING:任務處理中
  • SUCCEEDED:任務執行成功
  • FAILED:任務執行失敗
  • CANCELED:任務已取消
  • UNKNOWN:任務不存在或狀態未知
submit_time 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。video_urlstring視頻URL。連結有效期間24小時,可通過此URL下載視頻。輸出視頻格式為mp4(H.264 編碼)。orig_prompt string原始的輸入prompt。actual_prompt string開啟prompt智能改寫後實際使用的prompt。若不開啟prompt智能改寫,不會返回該欄位。codestring請求失敗的錯誤碼。請求成功時不會返回此參數,詳情請參見錯誤碼messagestring請求失敗的詳細資料。請求成功時不會返回此參數,詳情請參見錯誤碼
usage object輸出資訊統計。只對成功的結果計數。

屬性

video_duration integer產生視頻的時間長度,單位為秒。video_ratio string產生視頻的比例。固定為standardvideo_count integer產生視頻的數量。
request_idstring請求唯一標識。可用於請求明細溯源和問題排查。
  • 任務執行成功
  • 任務執行失敗
任務資料(如任務狀態、視頻URL等)僅保留24小時,逾時後會被自動清除。請您務必及時儲存產生的視頻。
{
    "request_id": "851985d0-fbba-9d8d-a17a-xxxxxx",
    "output": {
        "task_id": "208e2fd1-fcb4-4adf-9fcc-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-05-15 16:14:44.723",
        "scheduled_time": "2025-05-15 16:14:44.750",
        "end_time": "2025-05-15 16:20:09.389",
        "video_url": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/xxx.mp4?xxxxxx",
        "orig_prompt": "視頻中,一位女孩自晨霧繚繞的古老森林深處款款走出,她步伐輕盈,鏡頭捕捉她每一個靈動瞬間。當女孩站定,環顧四周蔥鬱林木時,她臉上綻放出驚喜與喜悅交織的笑容。這一幕,定格在了光影交錯的瞬間,記錄下女孩與大自然的美妙邂逅。",
        "actual_prompt": "一位身著淺色長裙的女孩從晨霧繚繞的古老森林深處緩緩走出,步伐輕盈如舞。她長發微卷,面容清秀,眼神明亮。鏡頭跟隨她的動作,捕捉每一個靈動瞬間。當她站定,轉身環顧四周蔥鬱林木時,臉上綻放出驚喜與喜悅交織的笑容。陽光透過樹葉灑下斑駁光影,定格這一人與自然和諧共處的美好時刻。畫面風格為清新自然系寫真,中景全景結合,平視視角帶有輕微調動運鏡。"
    },
    "usage": {
        "video_duration": 5,
        "video_ratio": "standard",
        "video_count": 1
    }
}

使用限制

  • 資料時效:任務task_id和 視頻video_url均只保留 24 小時,到期後將無法查詢或下載。
  • 音頻支援:當前僅支援產生無聲視頻,不支援音訊輸出。如有需要,可通過語音合成產生音頻。

錯誤碼

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

常見問題

Q:如何擷取視頻儲存的訪問網域名稱白名單?

A: 模型產生的視頻儲存於阿里雲OSS,API將返回一個臨時的公網URL。若需要對該下載地址進行防火牆白名單配置,請注意:由於底層儲存會根據業務情況進行動態變更,為避免到期資訊影響訪問,文檔不提供固定的OSS網域名稱白名單。如有安全管控需求,請聯絡客戶經理擷取最新OSS網域名稱列表。
文本產生
映像產生
音頻
Realtime API
  • 概述
向量與排序
模型生產