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。Content-Typestring（必選）請求內容類型。此參數必須設定為application/json。X-DashScope-Asyncstring（必選）非同步處理設定參數。HTTP請求只支援非同步，必須設定為enable。
缺少此請求頭將報錯：“current user api does not support synchronous calls”。
請求體（Request Body）
model string （必選）模型名稱。可選值為：
  • vidu/viduq2-pro-fast_img2video
input object （必選）輸入的基本資訊，如提示詞、媒體素材等。

屬性

prompt string （可選）文本提示詞。用來描述生成視訊中期望包含的元素和視覺特點。支援中英文，每個漢字/字母佔一個字符，字符長度不能超過 5000 個字符，超過部分會自動截斷。media array （必選）媒體素材列表，用於指定圖生視訊所需的圖像。數組的每個元素為一個媒體對象，包含 type 與 url 字段。

屬性

type string （必選）媒體素材類型。固定值為：
  • image：圖像URL。
素材限制：圖像素材有且只有1張。url string （必選）圖像檔案的URL地址，必須為公網可訪問的URL。
  • 支援 HTTP 或 HTTPS 協議。
  • 示例值：https://xxx/xxx.jpg。
圖像限制：
  • 格式：JPG、JPEG、PNG、WEBP。
  • 寬高比：1:4～4:1。
  • 檔案大小：不超過50MB。
parameters object （可選）視訊處理參數，如設定視訊解析度、設定視訊時長等。

屬性

resolution string （可選）
resolution直接影響費用，請在呼叫前確認模型價格。
指定生成的視訊解析度檔位。模型根據選擇的解析度檔位，自動縮放至相近總像素，視訊寬高比將盡量接近輸入圖像的寬高比。可選值：720P、1080P。預設值為720P。duration integer （可選）
duration直接影響費用，按秒計費，時間越長費用越高，請在呼叫前確認模型價格。
生成視訊的時長，單位為秒。取值為[1, 10]之間的整數，預設值為5。audio boolean （可選）watermark boolean （可選）是否添加水印標識，水印位於視訊右下角，文案固定為“內容由AI生成”。
  • false：預設值，不添加水印。
  • true：添加水印。
seedinteger（可選）隨機數種子，取值範圍為[0, 2147483647]。未指定時，系統自動生成隨機種子。若需提升生成結果的可復現性，建議固定seed值。請注意，由於模型生成具有概率性，即使使用相同 seed，也不能保證每次生成結果完全一致。
  • 圖生視訊
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/viduq2-pro-fast_img2video",
    "input": {
        "media": [
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260121/zlpocv/wan-i2v-haigui.webp"
            }
        ],
        "prompt": "镜头从海龟下方缓缓上移，海龟悠然游动，腹部细节清晰可见。"
    },
    "parameters": {
        "duration": 5,
        "resolution": "720P",
        "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。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總的視訊計費時長（秒）。output_video_durationinteger輸出視訊的時長（秒）。size string輸出視訊的解析度。fps integer輸出視訊的影格率。固定為24。SR string輸出視訊的解析度檔位。audio boolean輸出視訊是否為有聲視訊。video_count integer輸出視訊的數量。固定為1。
request_idstring請求唯一標識。可用於請求明細溯源和問題排查。
  • 任務執行成功
  • 任務執行失敗
  • 任務查詢過期
{
    "request_id": "3606f9f4-b833-44ec-8385-xxxxxx",
    "output": {
        "task_id": "2846881f-0496-4288-947f-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-03-27 14:25:32.057",
        "scheduled_time": "2026-03-27 14:25:32.084",
        "end_time": "2026-03-27 14:28:29.600",
        "orig_prompt": "镜头从海龟下方缓缓上移，海龟悠然游动，腹部细节清晰可见。",
        "video_url": "https://prod-ss-vidu.s3.cn-northwest-1.amazonaws.com.cn/xxx.mp4?xxxx"
    },
    "usage": {
        "duration": 5,
        "size": "990*932",
        "output_video_duration": 5,
        "fps": 24,
        "video_count": 1,
        "audio": false,
        "SR": "720"
    }
}

錯誤碼

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