愛詩-文生視頻模型基於 文本提示詞 ,生成一段流暢的視頻。
重要本文件僅適用於新加坡地域,且必須使用該地域的API Key。
服務開通
- 前往阿里雲百鍊控制台,搜尋 PixVerse,找到 PixVerse 模型卡片,單擊立即開通;
- 在彈窗內確認開通及授權。
適用範圍
為確保呼叫成功,請務必保證模型、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-Type 請求內容類型。此參數必須設定為 Authorization 請求身份認證。介面使用阿里雲百鍊API Key進行身份認證。示例值:Bearer sk-xxxx。 X-DashScope-Async 非同步處理設定參數。HTTP請求只支援非同步,必須設定為 重要缺少此請求頭將報錯:“current user api does not support synchronous calls”。 請求體(Request Body)model 模型名稱。 可選值:
input 輸入的基本資訊,如提示詞等。 parameters 視頻生成參數。如設定視頻解析度、時長、是否生成音訊等。 | 文生視頻支援模型:pixverse/pixverse-v6-t2v。 文生視頻(多鏡頭)支援模型:pixverse/pixverse-v6-t2v。 在 |
響應參數output 任務輸出資訊。 request_id 請求唯一標識。可用於請求明細溯源和問題排查。 code 請求失敗的錯誤碼。請求成功時不會返回此參數,詳情請參見錯誤碼。 message 請求失敗的詳細資訊。請求成功時不會返回此參數,詳情請參見錯誤碼。 | 成功響應請儲存 task_id,用於查詢任務狀態與結果。 異常響應建立任務失敗,請參見錯誤碼進行解決。 |
步驟2:根據任務ID查詢結果
新加坡地域:GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
請求參數請求頭(Headers)Authorization 請求身份認證。介面使用阿里雲百鍊API Key進行身份認證。示例值:Bearer sk-xxxx。 URL路徑參數(Path parameters)task_id 任務ID。 | 查詢任務結果將 |
響應參數output 任務輸出資訊。 usage 輸出資訊統計。只對成功的結果計數。 request_id 請求唯一標識。可用於請求明細溯源和問題排查。 | 任務執行成功任務執行失敗若任務執行失敗,task_status將置為 FAILED,並提供錯誤碼和資訊。請參見錯誤碼進行解決。 任務查詢過期task_id查詢有效期為 24 小時,超時後將無法查詢,返回以下報錯資訊。 |
DashScope SDK呼叫
SDK 的參數命名與HTTP介面基本一致,參數結構根據語言特性進行封裝。
由於文生視頻任務耗時較長(通常為1-5分鐘),SDK 在底層封裝了 HTTP 非同步呼叫流程,支援同步、非同步兩種呼叫方式。
具體耗時受限於排隊任務數和服務執行情況,請在取得結果時耐心等待。
Python SDK呼叫
重要請確保 DashScope Python SDK 版本不低於2.0.1,再執行以下程式碼。
若版本過低,可能會觸發 “url error, please check url!” 等錯誤。請參考安裝SDK進行更新。
新加坡地域:region="ap-southeast-1"
呼叫時請將{WorkspaceId}替換為真實的業務空間ID。
同步呼叫
請求示例
import os
import dashscope
from dashscope.v2 import DashScopeError
# 以下為新加坡地區的配置,調用時請將{WorkspaceId}替換為真實的業務空間ID,各地區的region取值不同。
client = dashscope.Client(
# 若未配置環境變數,請將下一行替換為您的 Model Studio 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"),
workspace="{WorkspaceId}",
region="ap-southeast-1",
)
def sample_sync_call_t2v():
# 同步呼叫 API,直接返回結果。
print('please wait...')
# generate為一步式調用(提交任務並等待完成),返回已完成的Job
# audio 不在具名簽名內,通過parameters透傳
try:
job = client.videos.generate(model='pixverse/pixverse-v6-t2v',
prompt='下着雨,赛博城市里,一只浣熊在栏杆上行走。突然他眼睛发出蓝光,变身成一架高科技无人机,快速飞离画面。',
size='1280*720',
duration=5,
watermark=False,
parameters={'audio': False})
print(job)
print(job.video_url)
except DashScopeError as e:
print(f"HTTP status code: {e.status_code}")
print(f"Error code: {e.code}")
print(f"Error message: {e.message}")
print("See the documentation: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")
if __name__ == '__main__':
sample_sync_call_t2v()
響應示例
video_url暫無過期時間,但不建議將其作為長期儲存,請及時下載。
{
"request_id": "2b68d32e-86c8-4383-8a18-xxxxxx",
"task_id": "ec40bb42-02d4-44d8-bf35-xxxxxx",
"status": "SUCCEEDED",
"results": [
{
"video_url": "https://media.pixverseai.cn/xxx.mp4"
}
],
"task_metrics": {
"TOTAL": 1,
"SUCCEEDED": 1,
"FAILED": 0
},
"usage": {
"video_count": 1,
"video_duration": 0,
"video_ratio": "",
"duration": 10,
"size": "1280x720",
"fps": 24,
"audio": false,
"SR": "720"
}
}
非同步呼叫
請求示例
import os
import dashscope
from dashscope.v2 import DashScopeError
# 以下為新加坡地區的配置,調用時請將{WorkspaceId}替換為真實的業務空間ID,各地區的region取值不同。
client = dashscope.Client(
# 若未配置環境變數,請將下一行替換為您的 Model Studio 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"),
workspace="{WorkspaceId}",
region="ap-southeast-1",
)
def sample_async_call_t2v():
# 提交非同步任務,立即返回任務資訊
# audio 不在具名簽名內,通過parameters透傳
try:
job = client.videos.jobs.create(model='pixverse/pixverse-v6-t2v',
prompt='下着雨,赛博城市里,一只浣熊在栏杆上行走。突然他眼睛发出蓝光,变身成一架高科技无人机,快速飞离画面。',
size='1280*720',
duration=5,
watermark=True,
parameters={'audio': False})
print(job)
print("task_id: %s" % job.task_id)
except DashScopeError as e:
print(f"HTTP status code: {e.status_code}")
print(f"Error code: {e.code}")
print(f"Error message: {e.message}")
print("See the documentation: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")
return
# 查詢任務狀態
try:
snapshot = client.videos.jobs.fetch(job.task_id)
print(snapshot.status) # 檢查任務狀態。
except DashScopeError as e:
print(f"HTTP status code: {e.status_code}")
print(f"Error code: {e.code}")
print(f"Error message: {e.message}")
print("See the documentation: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")
# 等待任務完成(指數退避輪詢,預設總預算24小時)
try:
done = client.videos.jobs.wait(job)
print(done)
print(done.video_url)
except DashScopeError as e:
print(f"HTTP status code: {e.status_code}")
print(f"Error code: {e.code}")
print(f"Error message: {e.message}")
print("See the documentation: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")
if __name__ == '__main__':
sample_async_call_t2v()
響應示例
1、建立任務的響應示例。
{
"request_id": "c86ff7ba-8377-917a-90ed-xxxxxx",
"task_id": "721164c6-8619-4a35-a6d9-xxxxxx",
"status": "PENDING"
}
2、查詢任務結果的響應示例
video_url暫無過期時間,但不建議將其作為長期儲存,請及時下載。
{
"request_id": "2b68d32e-86c8-4383-8a18-xxxxxx",
"task_id": "ec40bb42-02d4-44d8-bf35-xxxxxx",
"status": "SUCCEEDED",
"results": [
{
"video_url": "https://media.pixverseai.cn/xxx.mp4"
}
],
"task_metrics": {
"TOTAL": 1,
"SUCCEEDED": 1,
"FAILED": 0
},
"usage": {
"video_count": 1,
"video_duration": 0,
"video_ratio": "",
"duration": 10,
"size": "1280x720",
"fps": 24,
"audio": false,
"SR": "720"
}
}
Java SDK呼叫
重要請確保 DashScope Java SDK 版本不低於2.22.6,再執行以下程式碼。
若版本過低,可能會觸發 “url error, please check url!” 等錯誤。請參考安裝SDK進行更新。
新加坡地域:Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
呼叫時請將{WorkspaceId}替換為真實的業務空間ID。
同步呼叫
請求示例
// 调用时请将 {WorkspaceId} 替换为真实的业务空间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;
public class Text2Video {
static {
// 以下为新加坡地域URL
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
}
// 若没有配置环境变量,请用百炼API Key将下行替换为:api_key="sk-xxx"
// 获取API Key:https://www.alibabacloud.com/help/model-studio/get-api-key
public static String apiKey = System.getenv("DASHSCOPE_API_KEY");
/**
* Create a video compositing task and wait for the task to complete.
*/
public static void text2Video() throws ApiException, NoApiKeyException, InputRequiredException {
VideoSynthesis vs = new VideoSynthesis();
VideoSynthesisParam param =
VideoSynthesisParam.builder()
.apiKey(apiKey)
.model("pixverse/pixverse-v6-t2v")
.prompt("下着雨,赛博城市里,一只浣熊在栏杆上行走。突然他眼睛发出蓝光,变身成一架高科技无人机,快速飞离画面。")
.size("1280*720")
.duration(5)
.audio(true)
.watermark(true)
.seed(12345)
.build();
System.out.println("please wait...");
VideoSynthesisResult result = vs.call(param);
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args) {
try {
text2Video();
} catch (ApiException | NoApiKeyException | InputRequiredException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}
響應示例
video_url暫無過期時間,但不建議將其作為長期儲存,請及時下載。
{
"request_id": "bd1109bd-6c63-4e62-8bb8-xxxxxx",
"output": {
"task_id": "72af7c13-dad5-4aaa-b85d-xxxxxx",
"task_status": "SUCCEEDED",
"video_url": "https://media.pixverseai.cn/xxx.mp4",
"orig_prompt": "下着雨,赛博城市里,一只浣熊在栏杆上行走。突然他眼睛发出蓝光,变身成一架高科技无人机,快速飞离画面。",
"submit_time": "2026-03-20 11:21:13.227",
"scheduled_time": "2026-03-20 11:21:13.252",
"end_time": "2026-03-20 11:21:43.924"
},
"usage": {
"video_count": 1,
"duration": 5.0,
"size": "1280*720",
"input_video_duration": 0.0,
"output_video_duration": 0.0,
"SR": "720"
},
"status_code": 200,
"code": "",
"message": ""
}
非同步呼叫
請求示例
// 调用时请将 {WorkspaceId} 替换为真实的业务空间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;
public class Text2Video {
static {
// 以下为新加坡地域URL
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
}
// 若没有配置环境变量,请用百炼API Key将下行替换为:api_key="sk-xxx"
// 获取API Key:https://www.alibabacloud.com/help/model-studio/get-api-key
public static String apiKey = System.getenv("DASHSCOPE_API_KEY");
/**
* Create a video compositing task and wait for the task to complete.
*/
public static void text2Video() throws ApiException, NoApiKeyException, InputRequiredException {
VideoSynthesis vs = new VideoSynthesis();
VideoSynthesisParam param =
VideoSynthesisParam.builder()
.apiKey(apiKey)
.model("pixverse/pixverse-v6-t2v")
.prompt("下着雨,赛博城市里,一只浣熊在栏杆上行走。突然他眼睛发出蓝光,变身成一架高科技无人机,快速飞离画面。")
.size("1280*720")
.duration(5)
.audio(true)
.watermark(true)
.seed(12345)
.build();
// 异步调用
VideoSynthesisResult task = vs.asyncCall(param);
System.out.println(JsonUtils.toJson(task));
System.out.println("please wait...");
//获取结果
VideoSynthesisResult result = vs.wait(task, apiKey);
System.out.println(JsonUtils.toJson(result));
}
// 获取任务列表
public static void listTask() throws ApiException, NoApiKeyException {
VideoSynthesis is = new VideoSynthesis();
AsyncTaskListParam param = AsyncTaskListParam.builder().build();
param.setApiKey(apiKey);
VideoSynthesisListResult result = is.list(param);
System.out.println(result);
}
// 获取单个任务结果
public static void fetchTask(String taskId) throws ApiException, NoApiKeyException {
VideoSynthesis is = new VideoSynthesis();
// 如果已设置 DASHSCOPE_API_KEY 为环境变量,apiKey 可为空
VideoSynthesisResult result = is.fetch(taskId, apiKey);
System.out.println(result.getOutput());
System.out.println(result.getUsage());
}
public static void main(String[] args) {
try {
text2Video();
} catch (ApiException | NoApiKeyException | InputRequiredException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}
響應示例
1、建立任務的響應示例。
{
"request_id": "9b583f1b-2423-4fac-bb3f-xxxxxx",
"output": {
"task_id": "3944b819-1bbb-4da0-a230-xxxxxx",
"task_status": "PENDING"
},
"status_code": 200,
"code": "",
"message": ""
}
2、查詢任務結果的響應示例
video_url暫無過期時間,但不建議將其作為長期儲存,請及時下載。
{
"request_id": "bd1109bd-6c63-4e62-8bb8-xxxxxx",
"output": {
"task_id": "72af7c13-dad5-4aaa-b85d-xxxxxx",
"task_status": "SUCCEEDED",
"video_url": "https://media.pixverseai.cn/xxx.mp4",
"orig_prompt": "下着雨,赛博城市里,一只浣熊在栏杆上行走。突然他眼睛发出蓝光,变身成一架高科技无人机,快速飞离画面。",
"submit_time": "2026-03-20 11:21:13.227",
"scheduled_time": "2026-03-20 11:21:13.252",
"end_time": "2026-03-20 11:21:43.924"
},
"usage": {
"video_count": 1,
"duration": 5.0,
"size": "1280*720",
"input_video_duration": 0.0,
"output_video_duration": 0.0,
"SR": "720"
},
"status_code": 200,
"code": "",
"message": ""
}
錯誤碼
如果模型呼叫失敗並返回報錯資訊,請參見錯誤碼進行解決。