萬相-參考生視頻模型支援 多模態輸入 （圖片、視頻、音頻），產生保持角色形象和音色一致性的視頻，適用於單角色表演或多角色互動情境。
相關文檔：使用指南
為確保調用成功，請務必保證模型、Endpoint URL和API Key 均屬於同一地區。跨地區調用將會失敗。
由於視頻產生任務耗時較長（通常為1-5分鐘），API採用非同步呼叫。整個流程包含 “建立任務 -> 輪詢擷取” 兩個核心步驟，具體如下：
調用時請將
調用時請將
SDK 的參數命名與HTTP介面基本一致，參數結構根據語言特性進行封裝。
參考生視頻任務通常需要1–5分鐘。SDK 封裝了HTTP非同步呼叫流程，支援同步和非同步兩種調用方式。
根據模型所在地區設定 base_http_api_url:
調用時請將
根據模型所在地區設定 baseHttpApiUrl:
調用時請將
如果模型調用失敗並返回報錯資訊，請參見錯誤碼進行解決。
主要區別如下：
僅 wan2.7 支援。在
適用範圍
為確保調用成功，請務必保證模型、Endpoint URL和API Key 均屬於同一地區。跨地區調用將會失敗。
- 選擇模型：確認模型所屬的地區。
- 選擇 URL：選擇對應的地區 Endpoint URL，支援HTTP 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{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.7-r2v、wan2.7-r2v-2026-06-12。input object （必選）輸入的基本資料，如提示詞等。
屬性 prompt string （必選）文本提示詞。用來描述產生視頻中期望包含的元素和視覺特點。支援中英文，每個漢字、字母、標點佔一個字元，超過部分會自動截斷。
media數組順序一致。圖和視頻分別計數，即同時存在圖1、視頻1等標識。若參考素材有且僅有一張圖片或一個視頻，則可簡化表述為”參考圖片”或“參考視頻”。畫面描述：假設參考圖1是一隻貓，圖2是一個房間，要描述貓在房間裡玩耍，支援兩種寫法：一種是直接使用標識指代（如“圖1在圖2裡玩耍”）；另一種是結合主體與情境補充說明（如“圖1的貓在圖2的房間裡玩耍”）。當參考圖片為多宮格（故事板映像）時，提示詞建議按照多分鏡的形式描述畫面內容。無需描述每個宮格，提供關鍵分鏡內容即可，模型將自動識別宮格邏輯並智能補全鏡頭內容。為達到更好的效果，建議單次僅輸入一張多宮格圖。提示詞的提示請參見文生視頻/圖生視頻Prompt指南。negative_prompt string （可選）反向提示詞，用來描述不希望在視頻畫面中出現的內容，可以對視頻畫面進行限制。支援中英文，長度不超過500個字元，超過部分會自動截斷。樣本值：低解析度、錯誤、最差品質、低品質、殘缺、多餘的手指、比例不良等。media array （必選）媒體素材數組，素材包括映像、視頻和音頻。支援映像/視頻輸入作為視覺參考，映像支援多視圖，常見參考角色、道具、情境等。
屬性 type string （必選）媒體素材類型。可選值為：
string （必選）媒體素材URL。每個值可指向一張映像或一段視頻。
傳入參考映像（type=reference_image） 參考映像URL或 Base 64 編碼資料。參考圖可以是主體（人物/動物/物體）或者背景。當包含主體時，僅包含一個角色。映像限制：
傳入參考視頻（type=reference_video） 參考視頻URL。視頻內容建議包含主體（人物/動物/物體），不建議使用背景或空鏡視頻。當包含主體時，僅包含一個角色。若視頻有聲音，也可以參考音色。視頻限制：
string （可選）音頻 URL。用於指定參考素材（映像/視頻）中主體角色的音色。與reference_image或reference_video搭配使用。該音頻僅參考音色，與說話內容無關。建議參考音頻語種與提示詞語種保持一致，匹配效果更佳。音頻生效邏輯：
object （可選）視頻處理參數，如設定視頻解析度。
屬性 resolution string （可選）產生視頻的解析度檔位，用於控制視頻的清晰度（總像素）。
string （可選）產生視頻的寬高比。生效邏輯：
integer （可選）產生視頻的時間長度，單位為秒。
boolean （可選）是否開啟prompt智能改寫。開啟後使用大模型對輸入prompt進行智能改寫。對於較短的prompt產生效果提升明顯，但會增加耗時。
boolean （可選）是否添加浮水印標識，浮水印位於視頻右下角，文案固定為“AI產生”。
integer（可選）隨機數種子，取值範圍為[0, 2147483647]。未指定時，系統自動產生隨機種子。若需提升產生結果的可複現性，建議固定seed值。請注意，由於模型產生具有機率性，即使使用相同 seed，也不能保證每次產生結果完全一致。 |
傳入多張參考素材（映像+視頻），並指定音色產生視頻。 |
響應參數outputobject任務輸出資訊。
屬性 task_id string任務ID。查詢有效期間24小時。task_status string任務狀態。
枚舉值
string請求唯一標識。可用於請求明細溯源和問題排查。codestring請求失敗的錯誤碼。請求成功時不會返回此參數，詳情請參見錯誤碼。messagestring請求失敗的詳細資料。請求成功時不會返回此參數，詳情請參見錯誤碼。 |
請儲存 task_id，用於查詢任務狀態與結果。 |
步驟2：根據任務ID查詢結果
- 新加坡
- 北京
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}{WorkspaceId}替換為真實的業務空間ID。
- 輪詢建議：視頻產生過程約需數分鐘，建議採用輪詢機制，並設定合理的查詢間隔（如 15 秒）來擷取結果。
- 任務狀態流轉：PENDING（排隊中）→ RUNNING（處理中）→ SUCCEEDED（成功）/ FAILED（失敗）。
- 結果連結：任務成功後返回視頻連結，有效期間為 24 小時。建議在擷取連結後立即下載並轉存至永久儲存（如阿里雲 OSS）。
- task_id 有效期間：24小時，逾時後將無法查詢結果，介面將返回任務狀態為
UNKNOWN。
請求參數要求標頭（Headers）Authorizationstring（必選）請求身份認證。介面使用阿里雲百鍊API Key進行身份認證。樣本值：Bearer sk-xxxx。URL路徑參數（Path parameters）task_idstring（必選）任務ID。 |
將 {task_id}完整替換為上一步介面返回的task_id的值。task_id查詢有效期間為24小時。 |
響應參數outputobject任務輸出資訊。
屬性 task_id string（必選）任務ID。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。video_urlstring視頻URL。僅在 task_status 為 SUCCEEDED 時返回。連結有效期間24小時，可通過此URL下載視頻。視頻格式為MP4（H.264 編碼）。orig_prompt string原始輸入的prompt，對應請求參數prompt。codestring請求失敗的錯誤碼。請求成功時不會返回此參數，詳情請參見錯誤碼。messagestring請求失敗的詳細資料。請求成功時不會返回此參數，詳情請參見錯誤碼。object輸出資訊統計。只對成功的結果計數。
屬性 input_video_duration integer輸入視頻的時間長度，單位秒。output_video_duration integer輸出視頻的時間長度，單位秒。duration integer總視頻時間長度。計費按duration時間長度計算。計算公式：duration = input_video_duration + output_video_duration。SR integer產生視頻的解析度檔位。樣本值：720。ratio string產生視頻的寬高比。樣本值：16:9。video_count integer產生視頻的數量。固定為1。string請求唯一標識。可用於請求明細溯源和問題排查。 |
視頻URL僅保留24小時，逾時後會被自動清除，請及時儲存產生的視頻。 |
DashScope SDK調用
SDK 的參數命名與HTTP介面基本一致，參數結構根據語言特性進行封裝。
參考生視頻任務通常需要1–5分鐘。SDK 封裝了HTTP非同步呼叫流程，支援同步和非同步兩種調用方式。
實際耗時取決於排隊任務數和服務運行狀態。
Python SDK調用
根據模型所在地區設定 base_http_api_url:
- 新加坡
- 北京
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'{WorkspaceId}替換為真實的業務空間ID。
- 同步調用
- 非同步呼叫
同步調用會阻塞直到視頻產生完成，直接返回結果。
請求樣本
響應樣本
video_url 有效期間24小時，請及時下載視頻。
Java SDK調用
根據模型所在地區設定 baseHttpApiUrl:
- 新加坡
- 北京
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";{WorkspaceId}替換為真實的業務空間ID。
- 同步調用
- 非同步呼叫
同步調用會阻塞直到視頻產生完成，直接返回結果。
請求樣本
響應樣本
video_url 有效期間24小時，請及時下載視頻。
錯誤碼
如果模型調用失敗並返回報錯資訊，請參見錯誤碼進行解決。
常見問題
從 wan2.6 升級到 wan2.7，代碼需要改哪些地方？
主要區別如下：
- 提示詞的參考引用寫法不同 wan2.7 不再使用 character1、character2 這類標識，需要改為按類型分別指代：映像用“圖n”（如圖1、圖2），視頻用“視頻n”（如視頻1、視頻2）。英文提示詞則寫為“Image 1”、"Video 1”這類標識。提示詞說明詳見prompt參數。
-
多鏡頭控制方式不同
- wan2.7：不支援 shot_type 參數，通過在 prompt 中描述分鏡指令碼來實現多鏡頭效果。
- wan2.6：通過設定 shot_type 為 multi 來產生多鏡頭視頻。
-
請求參數結構不同
- 參考素材傳入方式：wan2.7 使用
media（對象數組，每個元素含type和url），替代 wan2.6 的reference_urls（字串數組）。 - 解析度參數：wan2.7 使用
resolution（如720P），替代 wan2.6 的size（如1280*720）。 - audio 參數：wan2.7 預設產生有聲視頻，無需設定。wan2.6 需要顯式設定
audio為true或false。
- 參考素材傳入方式：wan2.7 使用
如何為主體配音（音色參考）？
僅 wan2.7 支援。在 media 中通過 reference_voice 傳入音頻 URL，可為參考映像或參考視頻指定參考音色。