萬相-參考生視頻API參考(2.6)
萬相2.6-參考生視頻模型支援多模態輸入,可將人或物體作為主角,產生單角色表演或多角色互動視頻。
相關文檔:使用指南
適用範圍
為確保調用成功,請務必保證模型、Endpoint URL 和 API Key 均屬於同一地區。跨地區調用將會失敗。
選擇模型:確認模型所屬的地區。
選擇 URL:選擇對應的地區 Endpoint URL,支援HTTP URL。
配置 API Key:選擇地區並擷取API Key,再配置API Key到環境變數。
本文的範例程式碼適用於新加坡地區。
新加坡地區的舊版網域名稱 https://dashscope-intl.aliyuncs.com 即將下線,請及時遷移到新版網域名稱 https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com。
HTTP調用
此介面為舊版協議,只支援wan2.6模型。
由於視頻產生任務耗時較長(通常為1-5分鐘),API採用非同步呼叫。整個流程包含 “建立任務 -> 輪詢擷取” 兩個核心步驟,具體如下:
步驟1:建立任務擷取任務ID
新加坡
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
調用時請將WorkspaceId替換為真實的Workspace ID。
維吉尼亞
POST https://dashscope-us.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
調用時請將WorkspaceId替換為真實的Workspace ID。
北京
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://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
調用時請將WorkspaceId替換為真實的Workspace ID。
維吉尼亞
GET https://dashscope-us.aliyuncs.com/api/v1/tasks/{task_id}
法蘭克福
GET https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
調用時請將WorkspaceId替換為真實的Workspace 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 請求唯一標識。可用於請求明細溯源和問題排查。 |
DashScope SDK調用
SDK 的參數命名與HTTP介面基本一致,參數結構根據語言特性進行封裝。
由於參考生視頻任務耗時較長(通常為1-5分鐘),SDK 在底層封裝了 HTTP 非同步呼叫流程,支援同步、非同步兩種調用方式。
具體耗時受限於排隊任務數和服務執行情況,請在擷取結果時耐心等待。
Python SDK調用
請確保 DashScope Python SDK 版本不低於 1.25.16,再運行以下代碼。
若版本過低,可能會觸發 "url error, please check url!" 等錯誤。請參考安裝SDK進行更新。
根據模型所在地區設定 base_http_api_url:
新加坡
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
調用時請將WorkspaceId替換為真實的Workspace ID。
北京
dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'
美國
dashscope.base_http_api_url = 'https://dashscope-us.aliyuncs.com/api/v1'
法蘭克福
dashscope.base_http_api_url = 'https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1'
調用時請將WorkspaceId替換為真實的Workspace ID。
同步調用
同步調用會阻塞等待,直到視頻產生完成並返回結果。
請求樣本
from http import HTTPStatus
from dashscope import VideoSynthesis
import dashscope
import os
# 以下為新加坡地區URL,各地區的URL不同
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
# 若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
# 各地區的API Key不同。擷取API Key:https://www.alibabacloud.com/help/en/model-studio/get-api-key
api_key = os.getenv("DASHSCOPE_API_KEY")
def sample_sync_call_r2v():
# 同步調用,直接返回結果
print('please wait...')
rsp = VideoSynthesis.call(
api_key=api_key,
model='wan2.6-r2v-flash',
prompt='Character2 坐在靠窗的椅子上,手持 character3,在 character4 旁演奏一首舒緩的美國鄉村民謠。Character1 對Character2開口說道:“that sounds great“',
reference_urls=[
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/aacgyk/wan-r2v-role1.mp4",
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/mmizqq/wan-r2v-role2.mp4",
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png",
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png"
],
shot_type='multi',
audio=True,
size='1280*720',
duration=10,
watermark=True)
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print(rsp.output.video_url)
else:
print('Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
if __name__ == '__main__':
sample_sync_call_r2v()非同步呼叫
非同步呼叫會立即返回任務ID,需要自行輪詢或等待任務完成。
請求樣本
import os
from http import HTTPStatus
from dashscope import VideoSynthesis
import dashscope
# 以下為新加坡地區URL,各地區的URL不同
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
# 若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
# 各地區的API Key不同。擷取API Key:https://www.alibabacloud.com/help/en/model-studio/get-api-key
api_key = os.getenv("DASHSCOPE_API_KEY")
def sample_async_call_r2v_26():
# 非同步呼叫,返回一個task_id
rsp = VideoSynthesis.async_call(
api_key=api_key,
model='wan2.6-r2v-flash',
prompt='Character2 坐在靠窗的椅子上,手持 character3,在 character4 旁演奏一首舒緩的美國鄉村民謠。Character1 對Character2開口說道:“that sounds great“',
reference_urls=[
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/aacgyk/wan-r2v-role1.mp4",
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/mmizqq/wan-r2v-role2.mp4",
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png",
"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png"
],
shot_type='multi',
audio=True,
size='1280*720',
duration=10,
watermark=True)
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print("task_id: %s" % rsp.output.task_id)
else:
print('Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
# 擷取非同步任務資訊
status = VideoSynthesis.fetch(task=rsp, api_key=api_key)
if status.status_code == HTTPStatus.OK:
print(status.output.task_status)
else:
print('Failed, status_code: %s, code: %s, message: %s' %
(status.status_code, status.code, status.message))
# 等待非同步任務結束
rsp = VideoSynthesis.wait(task=rsp, api_key=api_key)
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print(rsp.output.video_url)
else:
print('Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
if __name__ == '__main__':
sample_async_call_r2v_26()Java SDK調用
請確保 DashScope Java SDK 版本不低於 2.22.14,再運行以下代碼。
若版本過低,可能會觸發 "url error, please check url!" 等錯誤。請參考安裝SDK進行更新。
根據模型所在地區設定 baseHttpApiUrl:
新加坡
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
調用時請將WorkspaceId替換為真實的Workspace ID。
北京
Constants.baseHttpApiUrl = "https://dashscope.aliyuncs.com/api/v1";
法蘭克福
Constants.baseHttpApiUrl = "https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1";
調用時請將WorkspaceId替換為真實的Workspace ID。
同步調用
同步調用會阻塞等待,直到視頻產生完成並返回結果。
請求樣本
// Copyright (c) Alibaba, Inc. and its affiliates.
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesis;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisParam;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;
import com.alibaba.dashscope.utils.Constants;
import java.util.ArrayList;
import java.util.List;
public class Ref2Video26 {
static {
// 以下為新加坡地區url,各地區的url不同
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
}
// 若沒有配置環境變數,請用百鍊API Key將下行替換為:apiKey="sk-xxx"
// 各地區的API Key不同。擷取API Key:https://www.alibabacloud.com/help/en/model-studio/get-api-key
public static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static void ref2video26() throws ApiException, NoApiKeyException, InputRequiredException {
VideoSynthesis vs = new VideoSynthesis();
List<String> referenceUrls = new ArrayList<>();
referenceUrls.add("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/aacgyk/wan-r2v-role1.mp4");
referenceUrls.add("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/mmizqq/wan-r2v-role2.mp4");
referenceUrls.add("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png");
referenceUrls.add("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png");
VideoSynthesisParam param =
VideoSynthesisParam.builder()
.apiKey(apiKey)
.model("wan2.6-r2v-flash")
.prompt("Character2 坐在靠窗的椅子上,手持 character3,在 character4 旁演奏一首舒緩的美國鄉村民謠。Character1 對Character2開口說道:“that sounds great“")
.referenceUrls(referenceUrls)
.shotType(VideoSynthesis.ShotType.MULTI)
.audio(Boolean.TRUE)
.size("1280*720")
.duration(10)
.watermark(Boolean.TRUE)
.build();
System.out.println("please wait...");
VideoSynthesisResult result = vs.call(param);
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args) {
try {
ref2video26();
} catch (ApiException | NoApiKeyException | InputRequiredException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}非同步呼叫
非同步呼叫會立即返回任務ID,需要自行輪詢或等待任務完成。
請求樣本
// Copyright (c) Alibaba, Inc. and its affiliates.
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesis;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisListResult;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisParam;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.task.AsyncTaskListParam;
import com.alibaba.dashscope.utils.JsonUtils;
import com.alibaba.dashscope.utils.Constants;
import java.util.ArrayList;
import java.util.List;
public class Ref2Video26Async {
static {
// 以下為新加坡地區url,各地區的url不同
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
}
// 若沒有配置環境變數,請用百鍊API Key將下行替換為:apiKey="sk-xxx"
// 各地區的API Key不同。擷取API Key:https://www.alibabacloud.com/help/en/model-studio/get-api-key
public static String apiKey = System.getenv("DASHSCOPE_API_KEY");
public static void asyncRef2video26() throws ApiException, NoApiKeyException, InputRequiredException, InterruptedException {
VideoSynthesis vs = new VideoSynthesis();
List<String> referenceUrls = new ArrayList<>();
referenceUrls.add("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/aacgyk/wan-r2v-role1.mp4");
referenceUrls.add("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/mmizqq/wan-r2v-role2.mp4");
referenceUrls.add("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png");
referenceUrls.add("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png");
VideoSynthesisParam param =
VideoSynthesisParam.builder()
.apiKey(apiKey)
.model("wan2.6-r2v-flash")
.prompt("Character2 坐在靠窗的椅子上,手持 character3,在 character4 旁演奏一首舒緩的美國鄉村民謠。Character1 對Character2開口說道:“that sounds great“")
.referenceUrls(referenceUrls)
.shotType(VideoSynthesis.ShotType.MULTI)
.audio(Boolean.TRUE)
.size("1280*720")
.duration(10)
.watermark(Boolean.TRUE)
.build();
// 提交非同步任務
VideoSynthesisResult result = vs.asyncCall(param);
System.out.println("task_id: " + result.getOutput().getTaskId());
System.out.println(JsonUtils.toJson(result));
// 等待任務完成
result = vs.wait(result, null);
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args) {
try {
asyncRef2video26();
} catch (ApiException | NoApiKeyException | InputRequiredException | InterruptedException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}錯誤碼
如果模型調用失敗並返回報錯資訊,請參見錯誤碼進行解決。