Skip to main content

愛詩-文生視頻API參考

愛詩-文生視頻模型基於 文本提示詞 ,生成一段流暢的視頻。

本文件僅適用於新加坡地域,且必須使用該地域的API Key。

服務開通

  1. 前往阿里雲百鍊控制台,搜尋 PixVerse,找到 PixVerse 模型卡片,單擊立即開通;
  2. 在彈窗內確認開通及授權。

適用範圍

為確保呼叫成功,請務必保證模型、Endpoint URL 和 API Key 均屬於同一地域。跨地域呼叫將會失敗。
本文的示例程式碼適用於新加坡地域。

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。
缺少此請求頭將報錯:“current user api does not support synchronous calls”。
請求體(Request Body)
model string (必選)模型名稱。可選值:
  • pixverse/pixverse-v6-t2v
input object (必選)輸入的基本資訊,如提示詞等。

屬性

prompt string (必選)文本提示詞。用來描述生成視頻中期望包含的元素和視覺特點。支援中英文,每個漢字/字母佔一個字符,字符編碼為UTF-8,超過部分會自動截斷。
  • pixverse/pixverse-v6-t2v:不超過5000個字符。
parameters object (必選)視頻生成參數。如設定視頻解析度、時長、是否生成音訊等。

屬性

size string (必選)生成視頻的解析度,格式為寬*高的像素值。
size直接影響費用,請在呼叫前確認模型價格。
不同解析度檔位和寬高比對應的可選值見下方表格。

pixverse/pixverse-v6-t2v模型

解析度檔位

寬高比

size取值(寬*高)

360P

16:9

640*360

4:3

640*480

1:1

640*640

3:4

480*640

9:16

360*640

3:2

640*432

2:3

432*640

21:9

640*288

540P

16:9

1024*576

4:3

1024*768

1:1

1024*1024

3:4

768*1024

9:16

576*1024

3:2

1024*688

2:3

688*1024

21:9

1024*448

720P

16:9

1280*720

4:3

1108*832

1:1

960*960

3:4

832*1108

9:16

720*1280

3:2

1200*800

2:3

800*1200

21:9

1280*560

1080P

16:9

1920*1080

4:3

1664*1248

1:1

1440*1440

3:4

1248*1664

9:16

1080*1920

3:2

1776*1184

2:3

1184*1776

21:9

1920*832

duration integer (必選)
duration直接影響費用,按秒計費,請在呼叫前確認模型價格。
生成視頻的時長,單位為秒。
  • pixverse/pixverse-v6-t2v:取值範圍為[1, 15]之間的整數。
audio boolean (可選)
audio直接影響費用,請在呼叫前確認模型價格。
是否生成有聲視頻。開啟後模型將根據視頻內容自動生成匹配的背景音樂或音效。
  • false:預設值,輸出無聲視頻。
  • true:輸出有聲視頻。
watermark boolean (可選)是否添加水印標識,水印位於視頻右下角,文案固定為“AI生成”。
  • false:預設值,不添加水印。
  • true:添加水印。
shot_type string (可選)支援模型:pixverse/pixverse-v6-t2v。指定生成視頻的鏡頭類型,控制視頻是由一個連續鏡頭還是多鏡頭組成。
  • single:預設值,生成單鏡頭視頻。
  • multi:多鏡頭,系統會進行智慧分鏡。
使用建議:prompt 參數優先級高於 shot_type 。為獲得最佳效果,建議此參數設定與 prompt 描述保持一致。
  • 若想穩定輸出單鏡頭:設定 shot_type="single" 並在 prompt 中描述單鏡頭場景。
  • 若想穩定輸出多鏡頭:設定 shot_type="multi" 並在 prompt 中描述多鏡頭場景。
seedinteger(可選)隨機數種子,取值範圍為[0, 2147483647]。未指定時,系統自動生成隨機種子。若需提升生成結果的可復現性,建議固定seed值。請注意,由於模型生成具有概率性,即使使用相同 seed,也不能保證每次生成結果完全一致。
  • 文生視頻
  • 文生視頻(多鏡頭)
支援模型:pixverse/pixverse-v6-t2v。
# 调用时请将 {WorkspaceId} 替换为真实的业务空间ID。
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "pixverse/pixverse-v6-t2v",
    "input": {
        "prompt": "下着雨,赛博城市里,一只浣熊在栏杆上行走。突然他眼睛发出蓝光,变身成一架高科技无人机,快速飞离画面。"
    },
    "parameters": {
        "size": "1280*720",
        "duration": 5,
        "watermark": true
    }
}'

響應參數

output object任務輸出資訊。

屬性

task_id string任務ID。查詢有效期24小時。task_status string任務狀態。

枚舉值

  • PENDING:任務排隊中
  • RUNNING:任務處理中
  • SUCCEEDED:任務執行成功
  • FAILED:任務執行失敗
  • CANCELED:任務已取消
  • UNKNOWN:任務不存在或狀態未知
request_idstring請求唯一標識。可用於請求明細溯源和問題排查。codestring請求失敗的錯誤碼。請求成功時不會返回此參數,詳情請參見錯誤碼。messagestring請求失敗的詳細資訊。請求成功時不會返回此參數,詳情請參見錯誤碼。
  • 成功響應
  • 異常響應
請儲存 task_id,用於查詢任務狀態與結果。
{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

步驟2:根據任務ID查詢結果

新加坡地域:GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
  • 輪詢建議:視頻生成過程約需數分鐘,建議採用輪詢機制,並設定合理的查詢間隔(如 15 秒)來取得結果。
  • 任務狀態流轉:PENDING(排隊中)→ RUNNING(處理中)→ SUCCEEDED(成功)/ FAILED(失敗)。
  • task_id 有效期:24小時,超時後將無法查詢結果,介面將返回任務狀態為UNKNOWN。
  • RPS 限制:查詢介面預設RPS為20。如需更高頻查詢或事件通知,建議設定非同步任務回呼。
  • 更多操作:如需批量查詢、取消任務等操作,請參見管理非同步任務。

請求參數

請求頭(Headers)
Authorizationstring(必選)請求身份認證。介面使用阿里雲百鍊API Key進行身份認證。示例值:Bearer sk-xxxx。
URL路徑參數(Path parameters)
task_id string(必選)任務ID。
  • 查詢任務結果
將{task_id}完整替換為上一步介面返回的task_id的值。task_id查詢有效期為24小時,並請將{WorkspaceId}替換為真實的業務空間ID。
curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

響應參數

outputobject任務輸出資訊。

屬性

task_id string任務ID。查詢有效期24小時。task_status string任務狀態。

枚舉值

  • PENDING:任務排隊中
  • RUNNING:任務處理中
  • SUCCEEDED:任務執行成功
  • FAILED:任務執行失敗
  • CANCELED:任務已取消
  • UNKNOWN:任務不存在或狀態未知
輪詢過程中的狀態流轉:
  • PENDING(排隊中) → RUNNING(處理中)→ SUCCEEDED(成功)/ FAILED(失敗)。
  • 初次查詢狀態通常為 PENDING(排隊中)或 RUNNING(處理中)。
  • 當狀態變為 SUCCEEDED 時,響應中將包含生成的視頻URL。
  • 若狀態為 FAILED,請檢查錯誤資訊並重試。
  • 若狀態為 CANCELED,表示任務已取消,如需繼續請重新提交任務。
  • 若狀態為 UNKNOWN,表示任務不存在或狀態未知,可能在 task_id 不存在或超過 24 小時有效期後出現。
submit_time string任務提交時間。格式為 YYYY-MM-DD HH:mm:ss.SSS。scheduled_time string任務執行時間。格式為 YYYY-MM-DD HH:mm:ss.SSS。end_time string任務完成時間。格式為 YYYY-MM-DD HH:mm:ss.SSS。video_urlstring視頻URL。僅在 task_status 為 SUCCEEDED 時返回。視頻格式為MP4(H.264 編碼)。視頻連結暫無過期時間,但不建議將其作為長期儲存,請及時下載。orig_prompt string原始輸入的prompt,對應請求參數prompt。codestring請求失敗的錯誤碼。請求成功時不會返回此參數,詳情請參見錯誤碼。messagestring請求失敗的詳細資訊。請求成功時不會返回此參數,詳情請參見錯誤碼。
usage object輸出資訊統計。只對成功的結果計數。

屬性

duration integer生成視頻的總視頻時長(秒),用於計費。size string生成視頻的解析度。fps integer生成視頻的幀率。SR string生成視頻的解析度檔位。audio boolean生成視頻是否為有聲視頻。video_count integer生成視頻的數量。固定為1。shot_typestring生成視頻的鏡頭類型。
request_idstring請求唯一標識。可用於請求明細溯源和問題排查。
  • 任務執行成功
  • 任務執行失敗
  • 任務查詢過期
{
    "request_id": "19171ea5-9efb-4d35-93a1-xxxxxx",
    "output": {
        "task_id": "7ed706b7-a9a9-4319-820c-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-03-20 10:34:41.630",
        "scheduled_time": "2026-03-20 10:34:41.655",
        "end_time": "2026-03-20 10:35:12.725",
        "orig_prompt": "下着雨,赛博城市里,一只浣熊在栏杆上行走。突然他眼睛发出蓝光,变身成一架高科技无人机,快速飞离画面。",
        "video_url": "https://media.pixverseai.cn/xxxx.mp4"
    },
    "usage": {
        "duration": 5,
        "shot_type": "single",
        "size": "1280*720",
        "fps": 24,
        "video_count": 1,
        "audio": false,
        "SR": "720"
    }
}

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"
    }
}

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": ""
}

錯誤碼

如果模型呼叫失敗並返回報錯資訊,請參見錯誤碼進行解決。