全部產品
Search

搜尋本產品

    Alibaba Cloud Model Studio：萬相-圖生視頻API參考

    文件中心

    Alibaba Cloud Model Studio：萬相-圖生視頻API參考

    更新時間：Apr 04, 2026

    萬相-圖生視頻模型全新升級，支援多模態輸入（文本/映像/音頻/視頻），可完成首幀生視頻、首尾幀生視頻、視頻續寫三大任務。

    說明

    全新推出的圖生視頻 API（wan2.7-i2v模型）支援上述三大任務，推薦優先選用。

    原圖生視頻-基於首幀（wan2.6及早期模型）僅支援首幀生視頻。

    適用範圍

    為確保調用成功，請務必保證模型、endpoint URL 和 API Key 均屬於同一地區。跨地區調用將會失敗。

    說明

    本文的範例程式碼適用於新加坡地區。

    HTTP調用

    重要

    此介面為圖生視頻新版協議，僅支援wan2.7模型。

    圖生視頻任務耗時較長（通常為1-5分鐘），API採用非同步呼叫的方式。整個流程包含 “建立任務 -> 輪詢擷取” 兩個核心步驟，具體如下：

    步驟1：建立任務擷取任務ID

    新加坡

    POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

    北京

    POST https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

    說明

    • 建立成功後，使用介面返回的 task_id 查詢結果，task_id 有效期間為 24 小時。請勿重複建立任務，輪詢擷取即可。

    • 新手指引請參見Postman。

    請求參數

    首幀生視頻

    基於首幀映像和音頻產生視頻。

    curl --location 'https://dashscope-intl.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": "wan2.7-i2v",
    "input": {
        "prompt": "一幅都市奇幻藝術的情境。一個充滿動感的塗鴉藝術角色。一個由噴漆所畫成的少年，正從一面混凝土牆上活過來。他一邊用極快的語速演唱一首英文rap，一邊擺著一個經典的、充滿活力的饒舌歌手姿勢。情境設定在夜晚一個充滿都市感的鐵路橋下。燈光來自一盞孤零零的街燈，營造齣電影般的氛圍，充滿高能量和驚人的細節。視頻的音頻部分完全由rap構成，沒有其他對話或雜音。",
        "media": [
            {
                "type": "first_frame",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/wpimhv/rap.png"
            },
            {
                "type": "driving_audio",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/ozwpvi/rap.mp3"
                
            }
        ]
    },
    "parameters": {
        "resolution": "720P",
        "duration": 10,
        "prompt_extend": true,
        "watermark": true
    }
}'

    首尾幀生視頻

    傳入首幀和尾幀產生視頻。

    curl --location 'https://dashscope-intl.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": "wan2.7-i2v",
    "input": {
        "prompt": "寫實風格,一隻小黑貓好奇地仰望天空,鏡頭從平視角度逐漸升高,最後以俯視角度捕捉到它好奇的眼神。",
        "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"
            }
        ]
    },
    "parameters": {
        "resolution": "720P",
        "duration": 10,
        "prompt_extend": false,
        "watermark": true
    }
}'

    視頻續寫

    基於首段視頻片段，讓模型產生後續內容。

    curl --location 'https://dashscope-intl.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": "wan2.7-i2v",
    "input": {
        "prompt": "一隻戴著墨鏡的狗在街道上滑滑板，3D卡通。",
        "media": [
            {
                "type": "first_clip",
                "url": "http://wanx.alicdn.com/material/20250318/video_extension_1.mp4"
            }
        ]
    },
    "parameters": {
        "resolution": "720P",
        "duration": 10,
        "prompt_extend": true,
        "watermark": true
    }
}'

    Content-Type string （必選）

    請求內容類型。此參數必須設定為application/json。

    Authorization string（必選）

    請求身份認證。介面使用阿里雲百鍊API-Key進行身份認證。樣本值：Bearer sk-xxxx。

    X-DashScope-Async string （必選）

    非同步處理配置參數。HTTP請求只支援非同步，必須設定為enable。

    重要

    缺少此要求標頭將報錯：“current user api does not support synchronous calls”。

    請求體（Request Body）

    model string （必選）

    模型名稱。模型列表與價格詳見模型價格。

    樣本值：wan2.7-i2v。

    input object （必選）

    輸入的基本資料，如提示詞等。

    屬性

    prompt string （可選）

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

    支援中英文，每個漢字/字母佔一個字元，超過部分會自動截斷。長度限制因模型版本而異：

    • wan2.7-i2v：長度不超過5000個字元。

    樣本值：一隻小貓在草地上奔跑。

    提示詞提示詳見文生視頻/圖生視頻Prompt指南。

    negative_prompt string （可選）

    反向提示詞，用來描述不希望在視頻畫面中看到的內容，可以對視頻畫面進行限制。

    支援中英文，長度不超過500個字元，超過部分會自動截斷。

    樣本值：低解析度、錯誤、最差品質、低品質、殘缺、多餘的手指、比例不良等。

    media array （必選）

    媒體素材列表，用於指定視頻產生所需的參考素材（映像、音頻和視頻）。

    數組的每個元素為一個媒體對象，包含 type 與 url 欄位。

    素材組合

    僅支援以下特定的素材組合，非法組合將報錯。

    • 首幀生視頻：

      • 首幀：first_frame

      • 首幀+音頻：first_frame+driving_audio

    • 首尾幀生視頻：

      • 首幀+尾幀：first_frame+last_frame

      • 首幀+尾幀+音頻：first_frame+last_frame+driving_audio

    • 視頻續寫：

      • 首段視頻續寫：first_clip

      • 首段視頻+尾幀續寫：first_clip+last_frame

    屬性

    type string （必選）

    媒體素材類型。可選值為：

    • first_frame：首幀。

    • last_frame：尾幀。

    • driving_audio：驅動音頻。

    • first_clip：首視頻片段。

    使用限制：每種 type 在 media 數組中最多出現一次（例如：不可同時傳入兩個 first_frame）。

    url string （必選）

    媒體素材URL。素材包括映像、音頻和視頻。

    傳入映像（type=first_frame或last_frame）

    首幀或尾幀URL。目前支援首幀生視頻、首尾幀生視頻。

    映像限制：

    • 格式：JPEG、JPG、PNG（不支援透明通道）、BMP、WEBP。

    • 解析度：寬和高的範圍為[240, 8000]像素。

    • 寬高比：1:8～8:1。

    • 檔案大小：不超過20MB。

    支援輸入的格式：

    1. 公網URL:

      • 支援 HTTP 或 HTTPS 協議。

      • 樣本值：https://xxx/xxx.png。

    傳入音頻（type=driving_audio）

    音頻檔案的 URL。

    • 傳入音頻：模型將以該音頻為驅動源產生視頻（如口型同步、動作卡點等）。

    • 未傳入音頻：模型將根據視頻畫面內容，自動產生匹配的背景音樂或音效。

    音頻限制：

    • 格式：wav、mp3。

    • 時間長度：2～30s。

    • 檔案大小：不超過15MB。

    • 截斷處理：若音頻長度超過 duration 值（如5秒），自動截取前5秒，其餘部分丟棄。若音頻長度不足視頻時間長度，超出音頻長度部分為無聲視頻。例如，音頻為3秒，視頻時間長度為5秒，輸出視頻前3秒有聲，後2秒無聲。

    支援輸入的格式：

    1. 公網URL：

      • 支援 HTTP 和 HTTPS 協議。

      • 樣本值：https://xxx/xxx.mp3。

    傳入的視訊（type=first_clip）

    視頻檔案的 URL。模型將基於該視頻內容進行續寫產生，續寫時間長度的上限由 duration 參數控制。

    例如：當duration=15時，輸入視頻 3 秒，則模型續寫產生 12 秒，最終輸出視頻總時間長度 15 秒， 按 15 秒計費。

    視頻限制：

    • 格式：mp4、mov。

    • 時間長度：2～10s。

    • 解析度：寬和高的範圍為[240, 4096]像素。

    • 寬高比：1:8～8:1。

    • 檔案大小：不超過100MB。

    支援輸入的格式：

    1. 公網URL：

      • 支援 HTTP 和 HTTPS 協議。

      • 樣本值：https://xxx/xxx.mp4。

    parameters object （可選）

    視頻處理參數，如設定視頻解析度、設定視頻時間長度、開啟prompt智能改寫、添加浮水印等。

    屬性

    resolution string （可選）

    重要

    resolution直接影響費用，請在調用前確認模型價格。

    指定產生的視頻解析度檔位，用於控制視頻的清晰度（總像素）。

    模型根據選擇的解析度檔位，自動縮放至相近總像素。視頻寬高比盡量與輸入素材（首幀或首段視頻）保持一致，詳見常見問題。

    • wan2.7-i2v：可選值：720P、1080P。預設值為1080P。

    樣本值：1080P。

    duration integer （可選）

    重要

    duration直接影響費用，按秒計費，請在調用前確認模型價格。

    產生視頻的時間長度，單位為秒。該參數的取值依賴於 model參數：

    • wan2.7-i2v：取值為[2, 15]之間的整數。預設值為5。

    樣本值：5。

    prompt_extend boolean （可選）

    是否開啟prompt智能改寫。開啟後使用大模型對輸入prompt進行智能改寫。對於較短的prompt產生效果提升明顯，但會增加耗時。

    • true：預設值，開啟智能改寫。

    • false：不開啟智能改寫。

    樣本值：true。

    watermark boolean （可選）

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

    • false：預設值，不添加浮水印。

    • true：添加浮水印。

    樣本值：false。

    seed integer （可選）

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

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

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

    響應參數

    成功響應

    請儲存 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"
}

    output object

    任務輸出資訊。

    屬性

    task_id string

    任務ID。查詢有效期間24小時。

    task_status string

    任務狀態。

    枚舉值

    • PENDING：任務排隊中

    • RUNNING：任務處理中

    • SUCCEEDED：任務執行成功

    • FAILED：任務執行失敗

    • CANCELED：任務已取消

    • UNKNOWN：任務不存在或狀態未知

    request_id string

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

    code string

    請求失敗的錯誤碼。請求成功時不會返回此參數，詳情請參見錯誤資訊。

    message string

    請求失敗的詳細資料。請求成功時不會返回此參數，詳情請參見錯誤資訊。

    步驟2：根據任務ID查詢結果

    新加坡

    GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id}

    北京

    GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

    說明

    • 輪詢建議：視頻產生過程約需數分鐘，建議採用輪詢機制，並設定合理的查詢間隔（如 15 秒）來擷取結果。

    • 任務狀態流轉：PENDING（排隊中）→ RUNNING（處理中）→ SUCCEEDED（成功）/ FAILED（失敗）。

    • 結果連結：任務成功後返回視頻連結，有效期間為 24 小時。建議在擷取連結後立即下載並轉存至永久儲存（如阿里雲 OSS）。

    • task_id 有效期間：24小時，逾時後將無法查詢結果，介面將返回任務狀態為UNKNOWN。

    請求參數

    查詢任務結果

    將{task_id}完整替換為上一步介面返回的task_id的值。task_id查詢有效期間為24小時。

    curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
    要求標頭（Headers）

    Authorization string（必選）

    請求身份認證。介面使用阿里雲百鍊API-Key進行身份認證。樣本值：Bearer sk-xxxx。

    URL路徑參數（Path parameters）

    task_id string（必選）

    任務ID。

    響應參數

    任務執行成功

    視頻URL僅保留24小時，逾時後會被自動清除，請及時儲存產生的視頻。

    {
    "request_id": "2ca1c497-f9e0-449d-9a3f-xxxxxx",
    "output": {
        "task_id": "af6efbc0-4bef-4194-8246-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-09-25 11:07:28.590",
        "scheduled_time": "2025-09-25 11:07:35.349",
        "end_time": "2025-09-25 11:17:11.650",
        "orig_prompt": "一幅都市奇幻藝術的情境。一個充滿動感的塗鴉藝術角色。一個由噴漆所畫成的少年，正從一面混凝土牆上活過來。他一邊用極快的語速演唱一首英文rap，一邊擺著一個經典的、充滿活力的饒舌歌手姿勢。情境設定在夜晚一個充滿都市感的鐵路橋下。燈光來自一盞孤零零的街燈，營造齣電影般的氛圍，充滿高能量和驚人的細節。視頻的音頻部分完全由他的rap構成，沒有其他對話或雜音。",
        "video_url": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.mp4?Expires=xxx"
    },
    "usage": {
        "duration": 15,
        "input_video_duration": 0,
        "output_video_duration": 15,
        "video_count": 1,
        "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"
    }
}

    output object

    任務輸出資訊。

    屬性

    task_id string

    任務ID。查詢有效期間24小時。

    task_status string

    任務狀態。

    枚舉值

    • PENDING：任務排隊中

    • RUNNING：任務處理中

    • SUCCEEDED：任務執行成功

    • FAILED：任務執行失敗

    • CANCELED：任務已取消

    • UNKNOWN：任務不存在或狀態未知

    輪詢過程中的狀態流轉：

    • PENDING（排隊中） → RUNNING（處理中）→ SUCCEEDED（成功）/ FAILED（失敗）。

    • 初次查詢狀態通常為 PENDING（排隊中）或 RUNNING（處理中）。

    • 當狀態變為 SUCCEEDED 時，響應中將包含產生的視頻url。

    • 若狀態為 FAILED，請檢查錯誤資訊並重試。

    submit_time string

    任務提交時間。時區為UTC+8，格式為 YYYY-MM-DD HH:mm:ss.SSS。

    scheduled_time string

    任務執行時間。時區為UTC+8，格式為 YYYY-MM-DD HH:mm:ss.SSS。

    end_time string

    任務完成時間。時區為UTC+8，格式為 YYYY-MM-DD HH:mm:ss.SSS。

    video_url string

    視頻URL。僅在 task_status 為 SUCCEEDED 時返回。

    連結有效期間24小時，可通過此URL下載視頻。視頻格式為MP4（H.264 編碼）。

    orig_prompt string

    原始輸入的prompt，對應請求參數prompt。

    code string

    請求失敗的錯誤碼。請求成功時不會返回此參數，詳情請參見錯誤資訊。

    message string

    請求失敗的詳細資料。請求成功時不會返回此參數，詳情請參見錯誤資訊。

    usage object

    輸出資訊統計，只對成功的結果計數。

    屬性

    input_video_duration integer

    輸入的視頻的時間長度，單位秒。

    output_video_duration integer

    輸出視頻的時間長度，單位秒。

    duration integer

    總的視頻時間長度，用於計費。

    SR integer

    輸出視頻的解析度檔位。樣本值：720。

    video_count integer

    輸出視頻的數量。固定為1。

    request_id string

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

    使用限制

    • 資料時效：任務task_id和 視頻video_url均只保留 24 小時，到期後將無法查詢或下載。

    • 內容審核：輸入的內容（如prompt、映像、視頻）、輸出視頻均會經過Alibaba Content Security Service審核，含違規內容將返回 “IPInfringementSuspect”或“DataInspectionFailed”錯誤，詳見參見錯誤資訊。

    錯誤碼

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

    常見問題

    Q：如何產生特定寬高比（如3:4）的視頻？

    A： 輸出視頻的寬高比由 輸入素材（首幀映像或首視頻片段）決定，但無法保證嚴格等於輸入比例（如精確 3:4），實際輸出會存在微小偏差。

    下面以“輸入首幀映像”為例說明具體邏輯：

    • 為什麼會有偏差？

      • 執行邏輯：以輸入映像的比例為基準比例參考，結合 resolution 檔位的目標總像素，且視頻長寬必須為 16 的倍數（視頻編碼規範），系統會自動微調至最接近的合法解析度。

      • 計算樣本：輸入首幀映像750×1000（寬高比 3:4 = 0.75），並設定 resolution = "720P"（目標總像素約 92 萬），實際輸出視頻的解析度為816×1104（寬高比 ≈ 0.739，總像素約90萬）。

    • 實踐建議：

      • 輸入控制：盡量使用與目標比例一致的首幀或首視頻片段作為輸入。

      • 後期處理：如果您對比例有嚴格要求，建議在視頻產生後，使用編輯工具進行簡單的裁剪或黑邊填充。

    Q：如何擷取視頻儲存的訪問網域名稱白名單？

    A： 模型產生的視頻儲存於阿里雲OSS，API將返回一個臨時的公網URL。若需要對該下載地址進行防火牆白名單配置，請注意：由於底層儲存會根據業務情況進行動態變更，為避免到期資訊影響訪問，文檔不提供固定的OSS網域名稱白名單。如有安全管控需求，請聯絡客戶經理擷取最新OSS網域名稱列表。