萬相3.0視頻產生API參考 - Alibaba Cloud Model Studio

萬相3.0是全能參考視頻產生模型（All-in-One），統一支援文生視頻、圖生視頻（首幀/首尾幀）和參考生視頻等多種用法。最長可產生30秒視頻，輸出幀率為30fps。

適用範圍

為確保調用成功，請務必保證模型、Endpoint URL 和 API Key 均屬於同一地區。跨地區調用將會失敗。

選擇模型：前往模型廣場選擇模型，並確認其所屬地區。
選擇 URL：選擇對應的地區 Endpoint URL。
配置 API Key：選擇地區並擷取與配置 API Key，再配置API Key到環境變數。

說明本文的範例程式碼適用於新加坡地區。

HTTP調用

由於視頻產生任務耗時較長（通常為1-5分鐘），API採用非同步呼叫。整個流程包含 "建立任務 -> 輪詢擷取" 兩個核心步驟，具體如下：

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

新加坡

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

北京

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

日本（東京）

POST https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

德國（法蘭克福）

POST https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

美國（維吉尼亞）

POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

中國香港

POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-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。

重要缺少此要求標頭將報錯：“current user api does not support synchronous calls”。

請求體（Request Body）

model string （必選）

模型名稱。可選值：

wan3.0-video-prime：高速版，能力對齊標準版，端到端速度顯著提升。
wan3.0-video：標準版。

input object （必選）

輸入的基本資料。prompt 和 media 必填其一。

屬性

prompt string （條件必選）

文本提示詞，用來描述期望產生的視頻內容。和 media 必填其一。

支援中英文，每個漢字/字母佔一個字元，不超過20000個字元，超過部分會自動截斷。

在全能參考模式下，prompt中可以用"圖1""視頻1""音頻1"等指代 media 數組中對應順序的媒體素材。

media array （條件必選）

媒體素材數組，支援映像、視頻、音頻、檔案和網頁作為輸入。和 prompt 必填其一。

數組中每個元素為一個媒體對象，包含 type 與 url 欄位。
在參考生視頻模式下，按照數組順序定義 prompt 中素材引用的順序。圖和視頻分別計數，即可同時存在圖1、視頻1。
- 數組中的第 1 個 reference_video 對應 視頻1，第 2 個對應 視頻2，以此類推。
- 數組中的第 1 個 reference_image 對應圖1，第 2 個對應圖2，以此類推。
- 數組中的第 1 個 reference_audio 對應 音頻1，第 2 個對應 音頻2，以此類推。

屬性

type string （必選）

媒體素材類型。可選值為：

first_frame：首幀映像。最多1張，嚴格作為視頻第一幀。
last_frame：尾幀映像。最多1張，嚴格作為視頻最後一幀。
reference_image：參考映像。最多10張。
reference_video：參考視頻。最多5段，總時間長度不大於15秒。
reference_audio：參考音頻。最多5段，總時間長度不大於15秒。
file：檔案。最多1個，不可與 link 同時輸入。
link：網頁連結。最多1個，不可與 file 同時輸入。

重要reference_xx/file/link 類型和 first_frame/last_frame 類型互斥，不能在同一請求中混用。

url string （必選）

媒體素材URL或Base 64 編碼資料。

傳入映像（type=first_frame / last_frame / reference_image）

映像URL或Base 64 編碼資料。

映像限制：

格式：JPEG、JPG、PNG（不支援透明通道）、BMP、WEBP。
解析度：單邊[240, 8000]像素。
長寬比：不超過8:1。
檔案大小：不超過20MB。

支援輸入的格式：

公網URL：
- 支援HTTP或HTTPS協議。
- 樣本值：https://xxx/xxx.png。
Base 64 編碼映像後的字串：
- 資料格式：data:{MIME_type};base64,{base64_data}。
- 樣本值：data:image/png;base64,GDU7MtCZzEbTbmRZ......。（編碼字串過長，僅展示片段）
- 詳情請參見傳入映像。

傳入的視訊（type=reference_video）

參考視頻URL。

視頻限制：

格式：mp4、mov。
時間長度：單個[1, 15]秒，總時間長度不大於15秒。
幀率：≥16 fps。
解析度：單邊[240, 4096]像素。
長寬比：不超過8:1。
單檔案大小：不超過100MB。

支援輸入的格式：

公網URL：
- 支援HTTP或HTTPS協議。
- 樣本值：https://xxx/xxx.mp4。

傳入音頻（type=reference_audio）

參考音頻URL。

音頻限制：

格式：wav、mp3。
時間長度：單個[1, 15]秒，總時間長度不大於15秒。
檔案大小：不超過15MB。

支援輸入的格式：

公網URL：
- 支援HTTP或HTTPS協議。
- 樣本值：https://xxx/xxx.mp3。

傳入檔案（type=file）

檔案URL。

檔案限制：

格式：docx、doc、xlsx、xls、pptx、ppt、pdf、txt、key、pages、numbers、md。
檔案大小：不超過100MB。
頁數限制：不超過50頁（對pdf、docx、doc、pptx、ppt、key、pages格式校正）。

支援輸入的格式：

公網URL：
- 支援HTTP或HTTPS協議。
- 樣本值：https://xxx/xxx.pdf。

傳入網頁連結（type=link）

公開網頁的URL地址。僅支援解析無需登入的公開網頁（如新聞、部落格、公眾號等）。

支援輸入的格式：

公網URL：
- 支援HTTP或HTTPS協議。
- 樣本值：https://xxx/article/xxx。

parameters object （可選）

視頻處理參數。

屬性

resolution string （可選）

產生視頻的解析度檔位。預設值為 1080P。可選值：

1080P
720P
480P

ratio string （可選）

產生視頻的寬高比。可選值：

adaptive（預設值）：自適應長寬比，根據輸入媒體比例和意圖自動推薦合適的長寬比。
21:9
16:9
4:3
1:1
3:4
9:16

duration integer （可選）

產生視頻的時間長度，單位為秒。預設值為5。

無視頻輸入時：取值範圍為[2, 30]的整數。
有視頻輸入時：輸入視頻總時間長度 + 輸出視頻時間長度不超過30秒。
傳 -1 時：智能時間長度模式，模型根據輸入的 prompt、內容和富媒體自動推薦合適時間長度產生。

audio boolean （可選）

輸出視頻是否包含音頻。

true：預設值，輸出視頻包含聲音。
false：輸出視頻不包含音軌。

開關聲音價格相同。

seed integer （可選）

隨機種子，用於複現產生結果。取值範圍：-1或[0, 2147483647]。傳入-1或未指定時，系統自動產生隨機種子。即使使用相同seed，也不能保證每次產生結果完全一致。

prompt_extend boolean （可選）

是否開啟prompt智能改寫。開啟後使用大模型對輸入prompt進行智能改寫。對於較短的prompt產生效果提升明顯，但會增加耗時。

true：預設值，開啟智能改寫。
false：不開啟智能改寫。

重要當傳入文件（file）或網頁（link）素材時，prompt_extend 取值必須為 true。

watermark boolean （可選）

是否添加浮水印標識。

false：預設值，不添加浮水印。
true：添加浮水印。

參考檔案生視頻

通過 file 類型傳入檔案，模型自動理解檔案內容產生視頻。

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan3.0-video",
    "input": {
        "prompt": "一支高端智能眼鏡產品廣告，整體風格極簡、未來感、時尚進階，光影克制，畫面以黑色、銀灰色、冰藍色為主色調，局部點綴柔和白光與參數UI圖形。開場在純黑背景中，一副智能眼鏡從黑暗中緩緩浮現，鏡腿邊緣掠過精緻高光，鏡框輪廓在冷冽邊緣光下被勾勒出來，鏡頭超近距離掠過鏡片、鼻托、轉軸、鏡腿與材質細節，展現金屬與高效能複合材料的細膩質感，表面處理進階克制，線條輕薄流暢。隨後產品在空中緩慢旋轉，畫面以極簡動態圖形同步展示核心參數資訊。隨後鏡頭快速收攏，所有零件精準迴歸組裝成完整產品，切換到年輕模特佩戴展示，模特五官立體、氣質自信，穿著簡潔進階的都市時尚服裝，在極簡空間和城市光影環境中自然轉頭、抬手、行走、微笑，鏡頭從正面、側面、斜後方展示眼鏡佩戴狀態，突出輕薄貼合、時尚輪廓與日常百搭屬性。結尾在純色背景中，產品懸浮定格，鏡頭緩慢推進到品牌logo和核心slogan，整體音樂極簡電子氛圍配合精準鼓點，節奏乾淨有力，畫面質感進階、剋制、純粹，具有強烈品牌記憶點和國際化科技審美。",
        "media": [
            {
                "type": "file",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260806/ebapmr/glass.pptx"
            }
        ]
    },
    "parameters": {
        "resolution": "480P",
        "ratio": "adaptive",
        "duration": 10,
        "prompt_extend": true
    }
}'

參考生視頻

通過 input.media 傳入參考圖片、視頻、音頻、檔案或網頁連結，模型自動理解意圖產生視頻。

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan3.0-video",
    "input": {
        "prompt": "視頻1抱著圖3，在圖4的椅子上彈奏一支舒緩的鄉村民謠，並說道："今天的陽光真好。"圖1手中拿著圖2，路過視頻1，把手中的圖2放到視頻1旁邊的桌子上，並說道："真好聽，能不能再唱一遍"。",
        "media": [
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/sjuytr/wan-r2v-object-girl.jpg"
            },
            {
                "type": "reference_video",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/rtjeqf/wan-r2v-object3.png"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png"
            }
        ]
    },
    "parameters": {
        "resolution": "480P",
        "ratio": "adaptive",
        "duration": 5,
        "prompt_extend": true
    }
}'

文生視頻

僅通過 prompt 產生視頻，不傳入任何媒體檔案。

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan3.0-video",
    "input": {
        "prompt": "一隻小貓在月光下的屋頂上奔跑，城市的霓虹燈在遠處閃爍，電影級畫質，流暢運鏡。"
    },
    "parameters": {
        "resolution": "480P",
        "ratio": "adaptive",
        "duration": 5,
        "prompt_extend": true
    }
}'

首幀生視頻

通過 first_frame 嚴格指定視頻首幀映像。

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan3.0-video",
    "input": {
        "prompt": "一幅都市奇幻藝術的情境。一個充滿動感的塗鴉藝術角色。一個由噴漆所畫成的少年，正從一面混凝土牆上活過來。他一邊用極快的語速演唱一首英文rap，一邊擺著一個經典的、充滿活力的饒舌歌手姿勢。情境設定在夜晚一個充滿都市感的鐵路橋下。燈光來自一盞孤零零的街燈，營造齣電影般的氛圍，充滿高能量和驚人的細節。視頻的音頻部分完全由rap構成，沒有其他對話或雜音。",
        "media": [
            {
                "type": "first_frame",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/wpimhv/rap.png"
            }
        ]
    },
    "parameters": {
        "resolution": "480P",
        "ratio": "adaptive",
        "duration": 5,
        "prompt_extend": true
    }
}'

首尾幀生視頻

同時傳入 first_frame 和 last_frame，嚴格指定視頻的首幀和尾幀映像。

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan3.0-video",
    "input": {
        "prompt": "一個年輕女孩從微笑逐漸層為大笑，鏡頭緩緩推進，背景光線從冷色調漸層為暖色調。",
        "media": [
            {
                "type": "first_frame",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/wpimhv/rap.png"
            },
            {
                "type": "last_frame",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/sjuytr/wan-r2v-object-girl.jpg"
            }
        ]
    },
    "parameters": {
        "resolution": "480P",
        "ratio": "adaptive",
        "duration": 5,
        "prompt_extend": true
    }
}'

視頻編輯

通過 reference_video 類型傳入待編輯視頻，結合 prompt 指令編輯視頻內容。

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan3.0-video",
    "input": {
        "prompt": "將整個畫面轉換為黏土風格",
        "media": [
            {
                "type": "reference_video",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260402/ldnfdf/wan2.7-videoedit-style-change.mp4"
            }
        ]
    },
    "parameters": {
        "resolution": "720P",
        "prompt_extend": true
    }
}'

視頻延長

通過 reference_video 類型傳入原始視頻，結合含延長意圖關鍵詞的 prompt 延長視頻內容。需將 ratio 設為 adaptive。

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan3.0-video",
    "input": {
        "prompt": "將視頻1向後延長，麵包師端上刷好的麵包，將刷子放到一旁，鏡頭跟隨麵包師，去斜後方的烤爐進行烤制",
        "media": [
            {
                "type": "reference_video",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260402/ldnfdf/wan2.7-videoedit-style-change.mp4"
            }
        ]
    },
    "parameters": {
        "resolution": "720P",
        "ratio": "adaptive",
        "prompt_extend": true
    }
}'

響應參數

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"
}

異常響應

建立任務失敗，請參見錯誤碼進行解決。

{
    "code": "InvalidApiKey",
    "message": "No API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

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

新加坡

GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

北京

GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}

日本（東京）

GET https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

德國（法蘭克福）

GET https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

美國（維吉尼亞）

GET https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

中國香港

GET https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1/tasks/{task_id}

說明

輪詢建議：視頻產生過程約需數分鐘，建議採用輪詢機制，並設定合理的查詢間隔（如 15 秒）來擷取結果。
任務狀態流轉：PENDING（排隊中）→ RUNNING（處理中）→ SUCCEEDED（成功）/ FAILED（失敗）。
結果連結：任務成功後返回視頻連結，有效期間為 24 小時。建議在擷取連結後立即下載並轉存至永久儲存（如阿里雲 OSS）。
task_id 有效期間：24小時，逾時後將無法查詢結果，介面將返回任務狀態為UNKNOWN。

請求參數

要求標頭（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"

響應參數

output object

任務輸出資訊。

屬性

task_id string（必選）

任務ID。

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。

orig_prompt string

原始輸入的提示詞。

video_url string

產生視頻的URL地址。任務成功時返回。

codestring

請求失敗的錯誤碼。請求成功時不會返回此參數，詳情請參見錯誤碼。

messagestring

請求失敗的詳細資料。請求成功時不會返回此參數，詳情請參見錯誤碼。

usage object

輸出資訊統計。只對成功的結果計數。

屬性

video_count integer

產生視頻的數量。固定為1。

duration float

總視頻時長，單位為秒。無輸入參考視頻時，等於輸出視頻的時長；有輸入參考視頻時，等於輸入視頻時長與輸出視頻時長之和。

input_video_duration float

輸入視頻的時間長度，單位為秒。無視頻輸入時為0.0。

output_video_duration float

輸出視頻的時間長度，單位為秒。

fps integer

產生視頻的幀率。預設值為30。

SR integer

產生視頻的解析度。樣本值：720。

ratio string

產生視頻的寬高比。樣本值：16:9。

request_idstring

請求唯一標識。可用於請求明細溯源和問題排查。

任務執行成功

視頻URL僅保留24小時，逾時後會被自動清除，請及時儲存產生的視頻。

{
    "request_id": "78c9b768-0285-996c-b682-xxxxxx",
    "output": {
        "task_id": "17ed7e50-00cf-4509-aea1-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-08-06 10:01:35.452",
        "scheduled_time": "2026-08-06 10:01:35.507",
        "end_time": "2026-08-06 10:13:33.838",
        "orig_prompt": "A golden retriever running on a sunny beach, waves crashing in the background, cinematic lighting",
        "video_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx/video.mp4"
    },
    "usage": {
        "video_count": 1,
        "duration": 5.0,
        "input_video_duration": 0.0,
        "output_video_duration": 5.0,
        "fps": 30,
        "SR": 720,
        "ratio": "16:9"
    }
}

任務執行失敗

若任務執行失敗，task_status將置為 FAILED，並提供錯誤碼和資訊。請參見錯誤碼進行解決。

{
    "request_id": "e5e57877-c0fc-47ed-8fad-xxxxxx",
    "output": {
        "task_id": "eff1443c-ccab-4676-aad3-xxxxxx",
        "task_status": "FAILED",
        "code": "InvalidParameter",
        "message": "The two modes are mutually exclusive. Do not pass reference_xx and first_frame/last_frame at the same time."
    }
}

任務查詢到期

task_id查詢有效期間為 24 小時，逾時後將無法查詢，返回以下報錯資訊。

{
    "request_id": "a4de7c32-7057-9f82-8581-xxxxxx",
    "output": {
        "task_id": "502a00b1-19d9-4839-a82f-xxxxxx",
        "task_status": "UNKNOWN"
    }
}