萬相-參考生視頻模型支援多模態輸入(文本/映像/視頻),可將人或物體作為主角,產生單角色表演或多角色互動視頻。模型還支援智能分鏡,產生多鏡頭視頻。
相關文檔:使用指南
適用範圍
為確保調用成功,請務必保證模型、Endpoint URL 和 API Key 均屬於同一地區。跨地區調用將會失敗。
選擇模型:確認模型所屬的地區。
選擇 URL:選擇對應的地區 Endpoint URL,支援HTTP URL。
配置 API Key:選擇地區並擷取API Key,再配置API Key到環境變數(準備下線,併入配置 API Key)。
本文的範例程式碼適用於新加坡地區。
HTTP調用
由於參考生視頻任務耗時較長(通常為1-5分鐘),API採用非同步呼叫。整個流程包含 “建立任務 -> 輪詢擷取” 兩個核心步驟,具體如下:
步驟1:建立任務擷取任務ID
新加坡
POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
維吉尼亞
POST https://dashscope-us.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
北京
POST https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
建立成功後,使用介面返回的
task_id查詢結果,task_id 有效期間為 24 小時。請勿重複建立任務,輪詢擷取即可。新手指引請參見Postman。
請求參數 | 多角色互動(參考映像和視頻)通過 多角色互動(參考視頻)通過 單角色扮演通過 產生無聲視頻僅支援 當產生無聲視頻時,必須顯式設定 |
要求標頭(Headers) | |
Content-Type 請求內容類型。此參數必須設定為 | |
Authorization 請求身份認證。介面使用阿里雲百鍊API-Key進行身份認證。樣本值:Bearer sk-xxxx。 | |
X-DashScope-Async 非同步處理配置參數。HTTP請求只支援非同步,必須設定為 重要 缺少此要求標頭將報錯:“current user api does not support synchronous calls”。 | |
請求體(Request Body) | |
model 模型名稱。模型列表與價格詳見模型價格。 樣本值:wan2.6-r2v-flash。 | |
input 輸入的基本資料,如提示詞等。 | |
parameters 影像處理參數。如設定視頻解析度、開啟prompt智能改寫、添加浮水印等。 |
響應參數 | 成功響應請儲存 task_id,用於查詢任務狀態與結果。 異常響應建立任務失敗,請參見錯誤資訊進行解決。 |
output 任務輸出資訊。 | |
request_id 請求唯一標識。可用於請求明細溯源和問題排查。 | |
code 請求失敗的錯誤碼。請求成功時不會返回此參數,詳情請參見錯誤資訊。 | |
message 請求失敗的詳細資料。請求成功時不會返回此參數,詳情請參見錯誤資訊。 |
步驟2:根據任務ID查詢結果
新加坡
GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id}
維吉尼亞
GET https://dashscope-us.aliyuncs.com/api/v1/tasks/{task_id}
北京
GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}
輪詢建議:視頻產生過程約需數分鐘,建議採用輪詢機制,並設定合理的查詢間隔(如 15 秒)來擷取結果。
任務狀態流轉:PENDING(排隊中)→ RUNNING(處理中)→ SUCCEEDED(成功)/ FAILED(失敗)。
結果連結:任務成功後返回視頻連結,有效期間為 24 小時。建議在擷取連結後立即下載並轉存至永久儲存(如阿里雲 OSS)。
task_id 有效期間:24小時,逾時後將無法查詢結果,介面將返回任務狀態為
UNKNOWN。
請求參數 | 查詢任務結果將 |
要求標頭(Headers) | |
Authorization 請求身份認證。介面使用阿里雲百鍊API-Key進行身份認證。樣本值:Bearer sk-xxxx。 | |
URL路徑參數(Path parameters) | |
task_id 任務ID。 |
響應參數 | 任務執行成功視頻URL僅保留24小時,逾時後會被自動清除,請及時儲存產生的視頻。 任務執行失敗若任務執行失敗,task_status將置為 FAILED,並提供錯誤碼和資訊。請參見錯誤資訊進行解決。 任務查詢到期task_id查詢有效期間為 24 小時,逾時後將無法查詢,返回以下報錯資訊。 |
output 任務輸出資訊。 | |
usage 輸出資訊統計。只對成功的結果計數。 | |
request_id 請求唯一標識。可用於請求明細溯源和問題排查。 |
使用限制
資料時效:任務
task_id和 視頻video_url均只保留 24 小時,到期後將無法查詢或下載。內容審核:輸入的 prompt 和輸出的視頻均會經過Alibaba Content Security Service審核,包含違規內容的請求將報錯“IPInfringementSuspect”或“DataInspectionFailed”,具體參見錯誤資訊。
網路訪問配置:視頻連結儲存於阿里雲 OSS,如果業務系統因安全性原則無法訪問外部OSS連結,請將以下 OSS 網域名稱加入網路訪問白名單。
# OSS網域名稱列表 dashscope-result-bj.oss-cn-beijing.aliyuncs.com dashscope-result-hz.oss-cn-hangzhou.aliyuncs.com dashscope-result-sh.oss-cn-shanghai.aliyuncs.com dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com dashscope-result-zjk.oss-cn-zhangjiakou.aliyuncs.com dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com dashscope-result-hy.oss-cn-heyuan.aliyuncs.com dashscope-result-cd.oss-cn-chengdu.aliyuncs.com dashscope-result-gz.oss-cn-guangzhou.aliyuncs.com dashscope-result-wlcb-acdr-1.oss-cn-wulanchabu-acdr-1.aliyuncs.com
錯誤碼
如果模型調用失敗並返回報錯資訊,請參見錯誤資訊進行解決。