萬相-文生視頻模型基於 文本提示詞 ,產生一段流暢的視頻。
相關文檔:使用指南
為確保調用成功,請務必保證模型、Endpoint URL 和 API Key 均屬於同一地區。跨地區調用將會失敗。
由於文生視頻任務耗時較長(通常為1-5分鐘),API採用非同步呼叫。整個流程包含 “建立任務 -> 輪詢擷取” 兩個核心步驟,具體如下:
SDK 的參數命名與HTTP介面基本一致,參數結構根據語言特性進行封裝。
由於文生視頻任務耗時較長(通常為1-5分鐘),SDK 在底層封裝了 HTTP 非同步呼叫流程,支援同步、非同步兩種調用方式。
根據模型所在地區設定
根據模型所在地區設定
如果模型調用失敗並返回報錯資訊,請參見錯誤碼進行解決。
A: 不能直接轉換該連結。正確的做法是:後端服務擷取到url後,通過代碼下載該視頻檔案,然後將其上傳到永久Object Storage Service服務(如阿里雲 OSS),產生一個新的、永久訪問連結。
A: 不建議這樣做,因為連結會在 24 小時後失效。最佳實務是後端下載轉存後,使用永久連結進行視頻播放。
適用範圍
為確保調用成功,請務必保證模型、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。
請求參數要求標頭(Headers)Content-Typestring(必選)請求內容類型。此參數必須設定為application/json。Authorizationstring(必選)請求身份認證。介面使用阿里雲百鍊API Key進行身份認證。樣本值:Bearer sk-xxxx。X-DashScope-Asyncstring(必選)非同步處理配置參數。HTTP請求只支援非同步,必須設定為enable。請求體(Request Body)modelstring (必選)模型名稱。可選模型請參見模型列表。樣本值:wan2.6-t2v。input object (必選)輸入的基本資料,如提示詞等。
屬性 prompt string (必選)文本提示詞。用來描述產生視頻中期望包含的元素和視覺特點。支援中英文,每個漢字/字母佔一個字元,超過部分會自動截斷。長度限制因模型版本而異:
string (可選)反向提示詞,用來描述不希望在視頻畫面中看到的內容,可以對視頻畫面進行限制。支援中英文,長度不超過500個字元,超過部分會自動截斷。樣本值:低解析度、錯誤、最差品質、低品質、殘缺、多餘的手指、比例不良等。audio_url string (可選)支援模型:wan2.6和wan2.5系列模型。音頻檔案URL,模型將使用該音頻產生視頻。支援輸入的格式:
object (可選)影像處理參數。如設定視頻解析度、開啟prompt智能改寫、添加浮水印等。
屬性 size string (可選)指定產生的視頻解析度,格式為寬*高。該參數的預設值和可用枚舉值依賴於 model 參數,規則如下:
integer (可選)產生視頻的時間長度,單位為秒。該參數的取值依賴於 model參數:
boolean (可選)是否開啟prompt智能改寫。開啟後使用大模型對輸入prompt進行智能改寫。對於較短的prompt產生效果提升明顯,但會增加耗時。
string (可選)支援模型:wan2.6模型。指定產生視頻的鏡頭類型,即視頻是由一個連續鏡頭還是多個切換鏡頭組成。可選值:
"prompt_extend": true 時生效。參數優先順序:shot_type > prompt。例如,若 shot_type設定為"single",即使 prompt 中包含“產生多鏡頭視頻”,模型仍會輸出單鏡頭視頻。watermark 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。actual_prompt string當 prompt_extend=true 時,系統會對輸入 prompt 進行智能改寫,此欄位返回實際用於產生的最佳化後 prompt。
string請求失敗的錯誤碼。請求成功時不會返回此參數,詳情請參見錯誤碼。messagestring請求失敗的詳細資料。請求成功時不會返回此參數,詳情請參見錯誤碼。object輸出資訊統計。只對成功的結果計數。
屬性 video_duration integer僅在使用 wan2.5 及以下版本模型時返回,用於計費。產生視頻的時間長度,單位秒。枚舉值為5、10。duration float僅在使用 wan2.6 模型時返回,用於計費。表示總的視頻時間長度,且duration=input_video_duration+output_video_duration。input_video_duration integer僅在使用 wan2.6 模型時返回。固定為0。output_video_duration integer僅在使用 wan2.6 模型時返回。輸出視頻的時間長度,單位秒。其值等同於input.duration的值。SR integer僅在使用 wan2.6 模型時返回。產生視頻的解析度檔位。樣本值:720。size string僅在使用 wan2.6 模型時返回。產生視頻的解析度。格式為“寬高”,樣本值:19201080。video_ratio string僅 wan2.5 及以下版本模型時返回。產生視頻的解析度。格式為“寬高”,樣本值:832480。video_count integer產生視頻的數量。固定為1。string請求唯一標識。可用於請求明細溯源和問題排查。 |
視頻URL僅保留24小時,逾時後會被自動清除,請及時儲存產生的視頻。 |
DashScope SDK調用
SDK 的參數命名與HTTP介面基本一致,參數結構根據語言特性進行封裝。
由於文生視頻任務耗時較長(通常為1-5分鐘),SDK 在底層封裝了 HTTP 非同步呼叫流程,支援同步、非同步兩種調用方式。
具體耗時受限於排隊任務數和服務執行情況,請在擷取結果時耐心等待。
Python SDK調用
根據模型所在地區設定 dashscope.base_http_api_url:
- 同步調用
- 非同步呼叫
請求樣本
響應樣本
video_url 有效期間24小時,請及時下載視頻。
Java SDK調用
根據模型所在地區設定 Constants.baseHttpApiUrl:
- 新加坡
- 維吉尼亞
- 北京
- 法蘭克福
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";調用時請將{WorkspaceId}替換為真實的業務空間ID。- 同步調用
- 非同步呼叫
請求樣本
響應樣本
video_url 有效期間24小時,請及時下載視頻。
錯誤碼
如果模型調用失敗並返回報錯資訊,請參見錯誤碼進行解決。
常見問題
Q: 如何將臨時的視頻連結轉為永久連結?
A: 不能直接轉換該連結。正確的做法是:後端服務擷取到url後,通過代碼下載該視頻檔案,然後將其上傳到永久Object Storage Service服務(如阿里雲 OSS),產生一個新的、永久訪問連結。
範例程式碼:下載視頻到本地
範例程式碼:下載視頻到本地