Skip to main content

Vidu-參考生視訊 API 參考

Vidu-參考生視訊模型支援傳入 參考圖片 和 文本提示詞 ，將圖片中的主體角色融合到提示詞描述的場景中，生成流暢的視訊內容。

使用說明

為確保呼叫成功，請務必保證模型、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
  • 建立成功後，使用介面返回的 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 （必選）模型名稱。可選值為：
  • vidu/viduq3-ad_reference2video
  • vidu/viduq3-drama_reference2video
  • vidu/viduq3-mix_reference2video

模型選型

  • 廣告視訊：推薦 viduq3-ad，面向廣告行業，支援營銷級智能切鏡、運鏡和音效直出，上傳商品圖即可生成廣告視訊。
  • 精品劇 / AI 漫劇：推薦 viduq3-drama，角色一致性強、動效細膩、情緒表達真實，適合劇情向內容生產。
  • 通用場景：推薦 viduq3-mix，畫面質感與動態效果均衡，適合大多數參考生視訊需求。
input object （必選）輸入的基本資訊，包括參考圖片和提示詞。

屬性

prompt string （必選）文本提示詞。用來描述生成視訊中期望包含的元素和視覺特點。支援中英文，不超過 5000 個字符，超過部分會自動截斷。示例值：男人坐在靠窗的椅子上，手持吉他，在咖啡廳旁演奏一首舒緩的美國鄉村民謠。media array （必選）媒體素材列表，用於指定視訊生成所需的參考圖像。數組的每個元素為一個媒體對象，包含 type和 url 字段。

元素屬性

type string （必選）媒體素材類型。可選值與模型有關：

僅傳入參考圖像

支援模型：vidu/viduq3-ad_reference2video、vidu/viduq3-drama_reference2video、vidu/viduq3-mix_reference2video固定為：
  • image：參考圖像。
素材限制：圖像數量為1～7張。
url string （必選）媒體素材URL。素材包括圖像、視訊。

傳入圖像（type=image）

參考圖像URL，必須為公網可訪問的 URL。
  • 支援 HTTP 或 HTTPS 協議。
  • 示例值：https://xxx/xxx.png。
圖像限制：
  • 格式：JPEG、JPG、PNG、WEBP。
  • 寬高比：1:4～4:1。
  • 檔案大小：不超過 50MB。
parameters object （必選）視訊生成參數。如設定視訊解析度、時長等。

屬性

resolution string （可選）
resolution直接影響費用，請在呼叫前確認模型價格。
生成視訊的解析度。可選值與模型有關：
  • vidu/viduq3-ad_reference2video：可選720P、1080P。預設值為720P。
  • vidu/viduq3-drama_reference2video：可選720P、1080P。預設值為1080P。
  • vidu/viduq3-mix_reference2video：可選720P、1080P。預設值為720P。
size string （可選）生成視訊的解析度，格式為宽*高的像素值。預設值根據resolution而定：
  • 當 resolution=720P 時，size 預設為 1280*720。
  • 當 resolution=1080P 時，size 預設為 1920*1080。
各模型支援的寬高比有所不同：
  • vidu/viduq3-drama_reference2video：僅支援 16:9 和 9:16。
  • 其他模型：支援 16:9、4:3、1:1、3:4、9:16。
各解析度檔位對應的 size 取值：
  • 720P
    • 16:9：1280*720
    • 4:3：1280*960
    • 1:1：1280*1280
    • 3:4：960*1280
    • 9:16：720*1280
  • 1080P
    • 16:9：1920*1080
    • 4:3：1920*1440
    • 1:1：1808*1808
    • 3:4：1440*1920
    • 9:16：1080*1920
duration integer （必選）
duration直接影響費用，按秒計費，請在呼叫前確認模型價格。
生成視訊的時長，單位為秒。
  • vidu/viduq3-ad_reference2video：取值為[3, 15]之間的整數。預設值為5。
  • vidu/viduq3-drama_reference2video：取值為[2, 15]之間的整數。預設值為5。
    • 當分鏡數量過多或明顯少於duration時，模型可能自動調整時長以保障故事完整性，實際視訊時長可能多於或少於duration設定值。
    • 計費按實際輸出時長計算。
  • vidu/viduq3-mix_reference2video：取值為[1, 16]之間的整數。預設值為5。
audio boolean （可選）支援模型：vidu/viduq3-ad_reference2video、vidu/viduq3-mix_reference2video。是否生成有聲視訊。開啓後模型將根據視訊內容自動生成匹配的背景音樂或音效。
  • false：預設值，輸出無聲視訊。
  • true：輸出有聲視訊。
vidu/viduq3-drama_reference2video 不支援該參數，預設輸出有聲視訊。
watermark boolean （可選）是否添加水印標識，水印位於視訊右下角，文案固定為“內容由AI生成”。
  • false：預設值，不添加水印。
  • true：添加水印。
seedinteger（可選）隨機數種子，取值範圍為[0, 2147483647]。未指定時，系統自動生成隨機種子。若需提升生成結果的可復現性，建議固定seed值。請注意，由於模型生成具有概率性，即使使用相同 seed，也不能保證每次生成結果完全一致。示例值：12345。
  • 參考生視訊-廣告（僅參考圖像）
  • 參考生視訊-短劇（僅參考圖像）
  • 參考生視訊（僅參考圖像）
支援模型：vidu/viduq3-ad_reference2video。
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": "vidu/viduq3-ad_reference2video",
    "input": {
        "media": [
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/dtnctw/ad-1.png"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/bspdpd/ad-2.png"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/mhsjyy/ad-3.png"
            }
        ],
        "prompt": "一个瑜伽裤的广告。商品是一条左右各有一个口袋的黑色高腰瑜伽裤。亚洲模特开心地说"我现在再也不穿没有口袋的瑜伽裤了"。画面保持清晰、稳定、容易理解。"
    },
    "parameters": {
        "duration": 8,
        "size": "1080*1920",
        "resolution": "1080P",
        "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小時
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 編碼）。視訊連結有效期24 小時，請及時下載。orig_prompt string原始輸入的prompt，對應請求參數prompt。codestring請求失敗的錯誤碼。請求成功時不會返回此參數，詳情請參見錯誤碼。messagestring請求失敗的詳細資訊。請求成功時不會返回此參數，詳情請參見錯誤碼。
usage object輸出資訊統計。只對成功的結果計數。

屬性

duration integer生成視訊的總視訊時長，用於計費。size string生成視訊的解析度。fps integer生成視訊的影格率。固定為 24。SR string生成視訊的解析度檔位。audio boolean生成視訊是否為有聲視訊。video_count integer生成視訊的數量。固定為 1。reference_type string參考素材類型。
request_idstring請求唯一標識。可用於請求明細溯源和問題排查。
  • 任務執行成功
  • 任務執行失敗
  • 任務查詢過期
視訊URL僅保留24小時，超時後會被自動清除，請及時儲存生成的視訊。
{
    "request_id": "8f240644-efe8-43bf-86ff-xxxxxx",
    "output": {
        "task_id": "b7e05baa-c318-440d-b293-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-03-27 15:10:42.723",
        "scheduled_time": "2026-03-27 15:10:42.754",
        "end_time": "2026-03-27 15:11:17.388",
        "orig_prompt": "男人坐在靠窗的椅子上，手持吉他，在咖啡厅旁演奏一首舒缓的美国乡村民谣",
        "video_url": "https://prod-ss-vidu.s3.cn-northwest-1.amazonaws.com.cn/xxx.mp4?xxx"
    },
    "usage": {
        "duration": 5,
        "size": "960*528",
        "output_video_duration": 5,
        "fps": 24,
        "video_count": 1,
        "audio": false,
        "reference_type": "image,video",
        "SR": "540"
    }
}

錯誤碼

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

常見問題

Q：size 與 resolution 必須同時傳入嗎？

A： 不必。二者均為可選參數，但推薦同時傳入。同時傳入可精准控制生成視訊的寬高比，具體參見size取值。 若不同時傳入，系統將按以下兩種場景處理：
  • 僅傳 size：size參數會被忽略，系統強制按預設的 resolution=720P 及其對應的size預設值（1280*720）處理。
    例如：介面返回為size="1280*720", SR=720。
  • 僅傳 resolution：按指定解析度檔位及該檔位對應的 16:9 比例輸出。
    例如：當resolution=540P時，介面返回 size="960528", SR=540；當resolution=1080P時，介面返回 size="19201080", SR=1080。