愛詩-參考生視頻模型支援傳入多張參考圖片,通過 文本提示詞 描述場景,將素材中的主體角色融合生成一段流暢的視頻。
服務開通
- 前往阿里雲百鍊控制台,搜尋 PixVerse,找到 PixVerse 模型卡片,單擊立即開通;
- 在彈窗內確認開通及授權。
適用範圍
為確保呼叫成功,請務必保證模型、Endpoint URL 和 API Key 均屬於同一地域。跨地域呼叫將會失敗。
- 選擇模型:確認模型所屬的地域。
- 選擇 URL:選擇對應的地域 Endpoint URL,支援HTTP URL或 DashScope SDK URL。
- 設定 API Key:選擇地域並取得與設定 API Key,再設定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。請求體(Request Body)modelstring (必選)模型名稱。模型輸出規格請參見模型列表。可選值:
object (必選)輸入的基本資訊,包括參考圖片和提示詞。
屬性 prompt string (必選)文本提示詞。用來描述生成視頻中期望包含的元素和視覺特點。支援中英文,每個漢字/字母佔一個字符,字符編碼為UTF-8,超過部分會自動截斷。
@ref_name在prompt中直接引用該圖片。
array (必選)媒體素材列表,用於指定視頻生成所需的參考圖像。數組的每個元素為一個媒體對象,包含 type和 url字段。
元素屬性 type string (必選)媒體素材類型。固定值為:
string (必選)參考圖像URL,必須為公網可訪問的 URL。
string (可選)參考圖片中主體的名稱標識,用於在prompt中通過@ref_name引用。長度不超過30個字符。object (必選)視頻生成參數。如設定視頻解析度、時長、是否生成音訊等。
屬性 size string (必選)生成視頻的解析度,格式為寬*高的像素值。不同解析度檔位對應的可選值見下方表格。
pixverse/pixverse-v6-r2v模型
integer (必選)生成視頻的時長,單位為秒。
boolean (可選)是否生成有聲視頻。開啟後模型將根據視頻內容自動生成匹配的背景音樂或音效。
boolean (可選)是否添加水印標識,水印位於視頻右下角,文案固定為“AI生成”。
integer(可選)隨機數種子,取值範圍為[0, 2147483647]。未指定時,系統自動生成隨機種子。若需提升生成結果的可復現性,建議固定seed值。請注意,由於模型生成具有概率性,即使使用相同 seed,也不能保證每次生成結果完全一致。 |
通過 media 傳入參考圖像,設定 size 和 duration 控制視頻解析度和時長。 |
響應參數outputobject任務輸出資訊。
屬性 task_id string任務ID。查詢有效期24小時。task_status string任務狀態。
枚舉值
string請求唯一標識。可用於請求明細溯源和問題排查。codestring請求失敗的錯誤碼。請求成功時不會返回此參數,詳情請參見錯誤碼。messagestring請求失敗的詳細資訊。請求成功時不會返回此參數,詳情請參見錯誤碼。 |
請儲存 task_id,用於查詢任務狀態與結果。 |
步驟2:根據任務ID查詢結果
新加坡地域:GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
請求參數請求頭(Headers)Authorizationstring(必選)請求身份認證。介面使用阿里雲百鍊API Key進行身份認證。示例值:Bearer sk-xxxx。URL路徑參數(Path parameters)task_idstring(必選)任務ID。 |
將 {task_id}完整替換為上一步介面返回的task_id的值。task_id查詢有效期為24小時,並請將{WorkspaceId}替換為真實的業務空間ID。 |
響應參數outputobject任務輸出資訊。
屬性 task_id string任務ID。查詢有效期24小時。task_status string任務狀態。
枚舉值
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請求失敗的詳細資訊。請求成功時不會返回此參數,詳情請參見錯誤碼。object輸出資訊統計。只對成功的結果計數。
屬性 duration integer生成視頻的總視頻時長,用於計費。size string生成視頻的解析度。fps integer生成視頻的幀率。SR string生成視頻的解析度檔位。audio boolean生成視頻是否為有聲視頻。video_count integer生成視頻的數量。固定為1。string請求唯一標識。可用於請求明細溯源和問題排查。 |
|
錯誤碼
如果模型呼叫失敗並返回報錯資訊,請參見錯誤碼進行解決。
常見問題
Q: prompt 效果不理想時,如何優化?
A: 可嘗試使用 @ref_name 作為替代方案。
- 預設做法:直接使用 prompt,模型會自動全局解析參考圖內容,適用於大多數常規場景。
- 替代方案:若發現生成效果偏離預期,可通過
@ref_name將參考圖指定在提示詞中,增強生成效果。
Q:如何使用ref_name?
A:ref_name 用於建立參考圖與提示詞的綁定關係。在 media數組中為圖片設定 ref_name 後,prompt 中可通過 @ref_name語法引用對應的參考圖主體。
- 例如:media 中設定
"ref_name": "小貓",則 prompt 中使用@小貓來引用該主體。注意:@小貓後必須保留空格。 - 示例:@小貓 和@小狗 在草地上玩耍。