愛詩-首尾幀生視頻模型基於 首幀圖像 、 尾幀圖像和文本提示詞 ,生成一段平滑過渡的視頻。
服務開通
- 前往阿里雲百鍊控制台,搜尋 PixVerse,找到 PixVerse 模型卡片,單擊立即開通;
- 在彈窗內確認開通及授權。
適用範圍
為確保呼叫成功,請務必保證模型、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-kf2v
input object (必選) 輸入的基本資訊,包含首幀、尾幀圖像和提示詞。 屬性 prompt string (必選) 文本提示詞。用來描述首幀到尾幀之間的變化過程。 支援中英文,每個漢字/字母佔一個字符,字符編碼為UTF-8,超過部分會自動截斷。
- pixverse/pixverse-v6-kf2v:不超過5000個字符。
media array (必選) 媒體資源列表,包含首幀和尾幀圖像。 數組的每個元素為一個媒體對象,包含 type 與 url 字段。 屬性 type string (必選) 媒體類型。
first_frame:首幀圖像。
last_frame:尾幀圖像。
素材限制:
- 首幀圖像:有且僅有1張。
- 尾幀圖像:有且僅有1張。
url string (必選) 圖像的公網可訪問URL。 圖像限制:
- 格式:JPG、PNG、WEBP。
- 解析度:寬度和高度均不超過10000像素。
- 檔案大小:不超過20MB。
parameters object (必選) 視頻生成參數。如設定視頻解析度、時長、是否生成音訊等。 屬性 resolution string (必選) 重要resolution直接影響費用,請在呼叫前確認模型價格。 生成視頻的解析度。 可選值:360P、540P、720P、1080P。 duration integer (必選) 重要duration直接影響費用,請在呼叫前確認模型價格。 生成視頻的時長,單位為秒。
- pixverse/pixverse-v6-kf2v:取值範圍為[1, 15]之間的整數。
audio boolean (可選) 重要audio直接影響費用,請在呼叫前確認模型價格。 是否生成有聲視頻。開啟後模型將根據視頻內容自動生成匹配的背景音樂或音效。
false:預設值,輸出無聲視頻。
true:輸出有聲視頻。
watermark boolean (可選) 是否添加水印標識,水印位於視頻右下角,文案固定為“AI生成”。
false:預設值,不添加水印。
true:添加水印。
seedinteger(可選) 隨機數種子,取值範圍為[0, 2147483647]。 未指定時,系統自動生成隨機種子。若需提升生成結果的可復現性,建議固定seed值。 請注意,由於模型生成具有概率性,即使使用相同 seed,也不能保證每次生成結果完全一致。 | 首尾幀生視頻支援模型:pixverse/pixverse-v6-kf2v。 # 调用时请将 {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-kf2v",
"input": {
"media": [
{
"type": "first_frame",
"url": "https://wanx.alicdn.com/material/20250318/first_frame.png"
},
{
"type": "last_frame",
"url": "https://wanx.alicdn.com/material/20250318/last_frame.png"
}
],
"prompt": "一只小猫从窗台向下跳跃,轻盈地落在沙发上,然后好奇地环顾四周。"
},
"parameters": {
"resolution": "720P",
"duration": 5,
"watermark": true
}
}'
Python SDKimport 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': 'first_frame', 'url': 'https://wanx.alicdn.com/material/20250318/first_frame.png'}, {'type': 'last_frame', 'url': 'https://wanx.alicdn.com/material/20250318/last_frame.png'}]
def sample_async_call():
# 非同步提交視頻生成任務
try:
job = client.videos.jobs.create(model='pixverse/pixverse-v6-kf2v',
media=media,
prompt='一只小猫从窗台向下跳跃,轻盈地落在沙发上,然后好奇地环顾四周。',
resolution='720P',
duration=5,
watermark=True)
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()
|
響應參數 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": "40799260-689c-4c44-9d7c-xxxxxx",
"output": {
"task_id": "408b6c3b-27c9-43dd-b928-xxxxxx",
"task_status": "SUCCEEDED",
"submit_time": "2026-03-20 13:47:42.916",
"scheduled_time": "2026-03-20 13:47:42.949",
"end_time": "2026-03-20 13:48:41.896",
"orig_prompt": "一只小猫从窗台向下跳跃,轻盈地落在沙发上,然后好奇地环顾四周。",
"video_url": "https://media.pixverseai.cn/xxx.mp4"
},
"usage": {
"duration": 5,
"size": "1280*960",
"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"
}
}
|
錯誤碼
如果模型呼叫失敗並返回報錯資訊,請參見錯誤碼進行解決。
常見問題
A: media數組中需要包含兩個對象,分別設定type為first_frame(首幀)和last_frame(尾幀),順序不影響結果,系統會根據type字段自動識別。
Q: 首幀和尾幀圖像的解析度是否需要一致?
A: 不需要。首幀和尾幀圖像的解析度可以不同,系統會自動處理。
輸出視頻的寬高比將以首幀圖像為基準(近似),解析度將根據所選 resolution 檔位(如 720P)自動適配至相近總像素。