全部產品
Search
文件中心

Alibaba Cloud Model Studio:愛詩-參考生視頻API參考

更新時間:Oct 27, 2026

愛詩-參考生視頻模型支援傳入多張參考圖片,通過 文本提示詞 描述場景,將素材中的主體角色融合生成一段流暢的視頻。

重要本文件僅適用於新加坡地域,且必須使用該地域的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-r2v

input object (必選)

輸入的基本資訊,包括參考圖片和提示詞。

屬性

prompt string (必選)

文本提示詞。用來描述生成視頻中期望包含的元素和視覺特點。

支援中英文,每個漢字/字母佔一個字符,字符編碼為UTF-8,超過部分會自動截斷。

  • pixverse/pixverse-v6-r2v:不超過2048個字符。

圖片引用說明:當在 media 參數中傳入參考圖時,可以通過 @ref_name在prompt中直接引用該圖片。

  • media 中設定的 ref_name 在同一請求內必須全局唯一,且須與 prompt 中的引用一一對應。
  • 書寫規範:必須在 @ref_name 後保留一個空格作為分隔。

示例值:

  • 普通提示詞:男人坐在靠窗的椅子上,手持吉他,在咖啡廳旁演奏一首舒緩的美國鄉村民謠。
  • 含引用的提示詞:@男人 坐在靠窗的椅子上,手持@吉他 ,在@咖啡廳 旁演奏一首舒緩的美國鄉村民謠。

media array (必選)

媒體素材列表,用於指定視頻生成所需的參考圖像。

數組的每個元素為一個媒體對象,包含 type和 url字段。

元素屬性

type string (必選)

媒體素材類型。固定值為:

  • image_url:圖像URL。

素材數量限制:圖像數量最多7張。

url string (必選)

參考圖像URL,必須為公網可訪問的 URL。

圖像限制:

  • 格式:JPG、PNG、WEBP。
  • 解析度:圖像的寬度和高度均不超過10000像素。
  • 檔案大小:不超過20MB。

ref_name string (可選)

參考圖片中主體的名稱標識,用於在prompt中通過@ref_name引用。長度不超過30個字符。

parameters object (必選)

視頻生成參數。如設定視頻解析度、時長、是否生成音訊等。

屬性

size string (必選)

生成視頻的解析度,格式為寬*高的像素值。

不同解析度檔位對應的可選值見下方表格。

pixverse/pixverse-v6-r2v模型

解析度檔位

寬高比

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

示例值:1280*720。

duration integer (必選)

重要duration直接影響費用,請在呼叫前確認愛詩-參考生視頻。

生成視頻的時長,單位為秒。

  • pixverse/pixverse-v6-r2v:取值範圍為[1, 15]之間的整數。

示例值:5。

audio boolean (可選)

重要audio直接影響費用,請在呼叫前確認愛詩-參考生視頻。

是否生成有聲視頻。開啟後模型將根據視頻內容自動生成匹配的背景音樂或音效。

  • false:預設值,輸出無聲視頻。
  • true:輸出有聲視頻。

示例值:false。

watermark boolean (可選)

是否添加水印標識,水印位於視頻右下角,文案固定為“AI生成”。

  • false:預設值,不添加水印。
  • true:添加水印。

示例值:false。

seedinteger(可選)

隨機數種子,取值範圍為[0, 2147483647]。

未指定時,系統自動生成隨機種子。若需提升生成結果的可復現性,建議固定seed值。

請注意,由於模型生成具有概率性,即使使用相同 seed,也不能保證每次生成結果完全一致。

參考生視頻

通過 media 傳入參考圖像,設定 size 和 duration 控制視頻解析度和時長。

# 调用时请将 {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-r2v",
    "input": {
        "media": [
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260320/knsple/wan-r2v-role-frame.jpg"
            },
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png"
            },
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png"
            }
        ],
        "prompt": "男人坐在靠窗的椅子上,手持吉他,在咖啡厅旁演奏一首舒缓的美国乡村民谣"
    },
    "parameters": {
        "size": "1280*720",
        "duration": 5,
        "audio": false,
        "watermark": true
    }
}'

Python SDK

import dashscope
import os
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",
)

media = [{'type': 'image_url', 'url': 'https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260320/knsple/wan-r2v-role-frame.jpg'}, {'type': 'image_url', 'url': 'https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png'}, {'type': 'image_url', 'url': 'https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png'}]

def sample_async_call():
    # 非同步提交視頻生成任務
    # audio 不在具名簽名內,通過parameters透傳
    try:
        job = client.videos.jobs.create(model='pixverse/pixverse-v6-r2v',
                                        media=media,
                                        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")

    # 等待任務完成
    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()

參考生視頻(使用ref_name)

在 media 傳入參考圖像,並傳入ref_name用於設定參考圖像的主體名稱。

# 调用时请将 {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-r2v",
    "input": {
        "media": [
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260320/knsple/wan-r2v-role-frame.jpg",
                "ref_name": "男人"
            },
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png",
                "ref_name": "吉他"
            },
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png",
                "ref_name": "咖啡厅"
            }
        ],
        "prompt": "@男人 坐在靠窗的椅子上,手持@吉他 ,在@咖啡厅 旁演奏一首舒缓的美国乡村民谣"
    },
    "parameters": {
        "size": "1280*720",
        "duration": 5,
        "audio": false,
        "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"
}

異常響應

建立任務失敗,請參見錯誤碼進行解決。

{
    "code": "InvalidApiKey",
    "message": "No API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-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。

request_idstring

請求唯一標識。可用於請求明細溯源和問題排查。

任務執行成功

{
    "request_id": "35137489-2862-96cb-b6f2-xxxxxx",
    "output": {
        "task_id": "1469cfc3-3004-4d9e-ab10-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-03-10 15:03:25.848",
        "scheduled_time": "2026-03-10 15:03:25.884",
        "end_time": "2026-03-10 15:04:05.882",
        "orig_prompt": "男人坐在靠窗的椅子上,手持吉他,在咖啡厅旁演奏一首舒缓的美国乡村民谣",
        "video_url": "https://media.pixverseai.cn/xxxx.mp4"
    },
    "usage": {
        "duration": 5,
        "size": "1280*720",
        "fps": 24,
        "video_count": 1,
        "audio": false,
        "SR": "720"
    }
}

任務執行失敗

若任務執行失敗,task_status將置為 FAILED,並提供錯誤碼和資訊。請參見錯誤碼進行解決。

{
    "request_id": "e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
    "output": {
        "task_id": "86ecf553-d340-4e21-af6e-a0c6a421c010",
        "task_status": "FAILED",
        "code": "InvalidParameter",
        "message": "The size is not match xxxxxx"
    }
}

任務查詢過期

task_id查詢有效期為 24 小時,超時後將無法查詢,返回以下報錯資訊。

{
    "request_id": "a4de7c32-7057-9f82-8581-xxxxxx",
    "output": {
        "task_id": "502a00b1-19d9-4839-a82f-xxxxxx",
        "task_status": "UNKNOWN"
    }
}

錯誤碼

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

常見問題

Q: prompt 效果不理想時,如何優化?

A: 可嘗試使用 @ref_name 作為替代方案。

  • 預設做法:直接使用 prompt,模型會自動全局解析參考圖內容,適用於大多數常規場景。
  • 替代方案:若發現生成效果偏離預期,可通過 @ref_name將參考圖指定在提示詞中,增強生成效果。

Q:如何使用ref_name?

A:ref_name 用於建立參考圖與提示詞的綁定關係。在 media數組中為圖片設定 ref_name 後,prompt 中可通過 @ref_name語法引用對應的參考圖主體。

  • 例如:media 中設定 "ref_name": "小貓",則 prompt 中使用@小貓來引用該主體。注意:@小貓後必須保留空格。
  • 示例:@小貓 和@小狗 在草地上玩耍。