萬相2.7-圖生視頻模型全新升級,支援 多模態輸入 (文本/映像/音頻/視頻),可完成 首幀生視頻、首尾幀生視頻、視頻續寫 三大任務。
相關文檔:使用指南
為確保調用成功,請務必保證模型、endpoint URL 和 API Key 均屬於同一地區。跨地區調用將會失敗。
圖生視頻任務耗時較長(通常為1-5分鐘),API採用非同步呼叫的方式。整個流程包含 “建立任務 -> 輪詢擷取” 兩個核心步驟,具體如下:
調用時請將
調用時請將
SDK 的參數命名與HTTP介面基本一致,參數結構根據語言特性進行封裝。
由於圖生視頻任務耗時較長(通常為1-5分鐘),SDK 在底層封裝了 HTTP 非同步呼叫流程,支援同步、非同步兩種調用方式。
根據模型所在地區設定
調用時請將
根據模型所在地區設定
調用時請將
如果模型調用失敗並返回報錯資訊,請參見錯誤碼進行解決。
A: 輸出視頻的寬高比由 輸入素材(首幀映像或首視頻片段)決定,但無法保證嚴格等於輸入比例(如精確 3:4),實際輸出會存在微小偏差。
下面以“輸入首幀映像”為例說明具體邏輯:
A: 模型產生的視頻儲存於阿里雲OSS,API將返回一個臨時的公網URL。若需要對該下載地址進行防火牆白名單配置,請注意:由於底層儲存會根據業務情況進行動態變更,為避免到期資訊影響訪問,文檔不提供固定的OSS網域名稱白名單。如有安全管控需求,請聯絡客戶經理擷取最新OSS網域名稱列表。
全新推出的圖生視頻 API(wan2.7模型)支援上述三大任務,推薦優先選用。原圖生視頻-基於首幀(wan2.6及早期模型)僅支援首幀生視頻。
適用範圍
為確保調用成功,請務必保證模型、endpoint URL 和 API Key 均屬於同一地區。跨地區調用將會失敗。
- 選擇模型:確認模型所屬的地區。
- 選擇 URL:選擇對應的地區 Endpoint URL,支援HTTP URL或 DashScope SDK URL。
- 配置 API Key:擷取該地區的API Key,再配置API Key到環境變數。
- 安裝 SDK:如需通過SDK進行調用,請安裝DashScope SDK。
本文的範例程式碼適用於新加坡地區。
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。
請求參數Content-Typestring(必選)請求內容類型。此參數必須設定為application/json。Authorizationstring(必選)請求身份認證。介面使用阿里雲百鍊API Key進行身份認證。樣本值:Bearer sk-xxxx。X-DashScope-Asyncstring(必選)非同步處理配置參數。HTTP請求只支援非同步,必須設定為enable。請求體(Request Body)modelstring (必選)模型名稱。模型列表與價格詳見模型價格。樣本值:wan2.7-i2v-2026-04-25。input object (必選)輸入的基本資料,如提示詞等。
屬性 prompt string (可選)文本提示詞。用來描述產生視頻中期望包含的元素和視覺特點。支援中英文,長度不超過5000個字元。每個漢字/字母佔一個字元,超過部分會自動截斷。樣本值:一隻小貓在草地上奔跑。提示詞提示詳見文生視頻/圖生視頻Prompt指南。negative_prompt string (可選)反向提示詞,用來描述不希望在視頻畫面中看到的內容,可以對視頻畫面進行限制。支援中英文,長度不超過500個字元,超過部分會自動截斷。樣本值:低解析度、錯誤、最差品質、低品質、殘缺、多餘的手指、比例不良等。media array (必選)媒體素材列表,用於指定視頻產生所需的參考素材(映像、音頻和視頻)。數組的每個元素為一個媒體對象,包含 type 與 url 欄位。
素材組合 僅支援以下特定的素材組合,非法組合將報錯。
屬性 type string (必選)媒體素材類型。可選值為:
type 在 media 數組中最多出現一次(例如:不可同時傳入兩個 first_frame)。url string (必選)媒體素材URL。素材包括映像、音頻和視頻。
傳入映像(type=first_frame或last_frame) 首幀或尾幀URL,或 Base 64 編碼資料。目前支援首幀生視頻、首尾幀生視頻。映像限制:
傳入音頻(type=driving_audio) 音頻檔案的 URL。
傳入的視訊(type=first_clip) 視頻檔案的 URL。模型將基於該視頻內容進行續寫產生,續寫時間長度的上限由 duration 參數控制。例如:當duration=15時,輸入視頻 3 秒,則模型續寫產生 12 秒,最終輸出視頻總時間長度 15 秒, 按 15 秒計費。視頻限制:
object (可選)視頻處理參數,如設定視頻解析度、設定視頻時間長度、開啟prompt智能改寫、添加浮水印等。
屬性 resolution string (可選)指定產生的視頻解析度檔位,用於控制視頻的清晰度(總像素)。模型根據選擇的解析度檔位,自動縮放至相近總像素。視頻寬高比盡量與輸入素材(首幀或首段視頻)保持一致,詳見常見問題。可選值:
integer (可選)產生視頻的時間長度,單位為秒。取值為[2, 15]之間的整數。預設值為5。prompt_extendboolean (可選)是否開啟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小時,並請將{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。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總的視頻時間長度,用於計費。SR integer輸出視頻的解析度檔位。樣本值:720。video_count integer輸出視頻的數量。固定為1。string請求唯一標識。可用於請求明細溯源和問題排查。 |
視頻URL僅保留24小時,逾時後會被自動清除,請及時儲存產生的視頻。 |
DashScope SDK調用
SDK 的參數命名與HTTP介面基本一致,參數結構根據語言特性進行封裝。
由於圖生視頻任務耗時較長(通常為1-5分鐘),SDK 在底層封裝了 HTTP 非同步呼叫流程,支援同步、非同步兩種調用方式。
具體耗時受限於排隊任務數和服務執行情況,請在擷取結果時耐心等待。
Python SDK調用
根據模型所在地區設定 dashscope.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調用
根據模型所在地區設定 Constants.baseHttpApiUrl:
- 新加坡
- 北京
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"{WorkspaceId}替換為真實的業務空間ID。
- 同步調用
- 非同步呼叫
同步調用會阻塞等待,直到視頻產生完成並返回結果。
請求樣本
錯誤碼
如果模型調用失敗並返回報錯資訊,請參見錯誤碼進行解決。
常見問題
Q:如何產生特定寬高比(如3:4)的視頻?
A: 輸出視頻的寬高比由 輸入素材(首幀映像或首視頻片段)決定,但無法保證嚴格等於輸入比例(如精確 3:4),實際輸出會存在微小偏差。
下面以“輸入首幀映像”為例說明具體邏輯:
-
為什麼會有偏差?
- 執行邏輯:以輸入映像的比例為基準比例參考,結合
resolution檔位的目標總像素,且視頻長寬必須為 16 的倍數(視頻編碼規範),系統會自動微調至最接近的合法解析度。 - 計算樣本:輸入首幀映像750×1000(寬高比 3:4 = 0.75),並設定 resolution = "720P"(目標總像素約 92 萬),實際輸出視頻的解析度為816×1104(寬高比 ≈ 0.739,總像素約90萬)。
- 執行邏輯:以輸入映像的比例為基準比例參考,結合
-
實踐建議:
- 輸入控制:盡量使用與目標比例一致的首幀或首視頻片段作為輸入。
- 後期處理:如果您對比例有嚴格要求,建議在視頻產生後,使用編輯工具進行簡單的裁剪或黑邊填充。