全部產品
Search

搜尋本產品

    Alibaba Cloud Model Studio：萬相-圖生動作API參考

    文件中心

    Alibaba Cloud Model Studio：萬相-圖生動作API參考

    更新時間：Jul 15, 2026

    基於人物圖片和參考視頻，產生人物動作視頻。

    • 功能簡述：將參考視頻中的動作和表情遷移到人物圖片，產生動態視頻。

    • 適用情境：舞蹈複刻、高難度肢體動作複刻、影視表演複刻，可作為動作捕捉的低成本替代方案。

    模型效果

    wan2.2-animate-move 提供兩種服務模式：標準模式wan-std和專業模式wan-pro，兩種模式在畫質效果和計費上有所不同，詳見萬相-圖生動作。

    人物圖片

    參考視頻

    輸出視頻（標準模式wan-std）

    輸出視頻（專業模式wan-pro）

    move_input_image

    前提條件

    您需要已擷取API Key並配置API Key到環境變數。請將範例程式碼中的 DASHSCOPE_API_HOST 替換為擷取的 API Host。

    重要

    華北2（北京）和新加坡地區擁有獨立的 API Key 與請求地址，不可混用，跨地區調用將導致鑒權失敗或服務報錯。

    重要

    阿里雲百鍊為華北2（北京）、新加坡地區推出了業務空間專屬網域名稱，能夠為推理請求提供卓越的效能和更高的穩定性，建議遷移至新網域名稱：

    • 華北2（北京）地區：從 https://dashscope.aliyuncs.com 遷移至 https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com

    • 新加坡地區：從 https://dashscope-intl.aliyuncs.com 遷移至 https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

    其中 {WorkspaceId} 為您的業務空間 ID，可在阿里雲百鍊控制台的業務空間詳情頁面查看。現有網域名稱仍可正常使用。

    HTTP調用

    視頻產生任務耗時較長，API 採用非同步呼叫，分為兩個步驟：建立任務，然後輪詢擷取結果。

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

    新加坡地區：POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis

    北京地區：POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis

    說明

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

    • 新手指引請參見Postman。

    請求參數

    圖生動作

    以下為新加坡地區的URL。請將 {WorkspaceId} 替換為您的百鍊業務空間ID，各地區的URL不同。

    curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis' \
    --header 'X-DashScope-Async: enable' \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
    --header 'Content-Type: application/json' \
    --data '{
        "model": "wan2.2-animate-move",
        "input": {
            "image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/adsyrp/move_input_image.jpeg",
            "video_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/kaakcn/move_input_video.mp4",
            "watermark": true
        },
        "parameters": {
            "mode": "wan-std"
        }
      }'
    要求標頭（Headers）

    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.2-animate-move。

    input object （必選）

    輸入參數對象，包含以下欄位：

    屬性

    image_url string （必選）

    人物圖片的公網可訪問 HTTP/HTTPS 連結。URL 中若含中文等非 ASCII 字元，需先進行URL編碼。

    • 格式：JPG、JPEG、PNG、BMP、WEBP。

    • 尺寸：寬高均在[200, 4096]像素範圍內，寬高比在 1:3 至 3:1 之間。

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

    • 樣本值：https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/adsyrp/move_input_image.jpeg

    video_url string （必選）

    參考視頻的公網可訪問 HTTP/HTTPS 連結。URL 中若含中文等非 ASCII 字元，需先進行URL編碼。

    建議：使用高解析度、高幀率的參考視頻，可有效提升產生視頻的畫質效果。

    • 格式：MP4、AVI、MOV。

    • 時間長度：2～30 秒。

    • 尺寸：寬高均在[200, 2048]像素範圍內，寬高比在 1:3 至 3:1 之間。

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

    • 樣本值：https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/kaakcn/move_input_video.mp4

    watermark bool （可選）

    是否在視頻右下角添加"千問AI產生"浮水印。

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

    • true：添加浮水印。

    parameters object （必選）

    屬性

    check_image bool （可選）

    是否對輸入圖片進行檢測。

    • true：預設值，檢測傳入的圖片。

    • false：跳過圖片檢測，直接處理。

    mode string （必選）

    服務模式，支援以下兩種：

    • wan-std：標準模式，產生速度快、性價比高，適合快速預覽和基礎動畫情境。

    • wan-pro：專業模式，動畫流暢度更高、效果更佳，處理時間和費用相應增加。

    詳情請參見模型效果和計費與限流。

    響應參數

    成功響應

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

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

    message string

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

    code string

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

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

    新加坡

    GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

    調用時請將{WorkspaceId}替換為真實的Workspace ID。

    華北2（北京）

    GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}

    調用時請將{WorkspaceId}替換為真實的Workspace ID。

    說明

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

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

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

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

    請求參數

    查詢任務結果

    將0385dc79-5ff8-4d82-bcb6-xxxxxx替換為實際的 task_id。

    以下為新加坡地區的URL。請將 {WorkspaceId} 替換為您的百鍊業務空間ID，各地區的URL不同。
    curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/0385dc79-5ff8-4d82-bcb6-xxxxxx \
    --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": "a67f8716-18ef-447c-a286-xxxxxx",
    "output": {
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-09-18 15:32:00.105",
        "scheduled_time": "2025-09-18 15:32:15.066",
        "end_time": "2025-09-18 15:34:41.898",
        "results": {
            "video_url": "http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxx.mp4?Expires=xxxxxx"
        }
    },
    "usage": {
        "video_duration": 5.2,
        "video_ratio": "standard"
    }
}

    任務執行失敗

    若任務執行失敗，task_status將置為 FAILED，並提供錯誤碼和資訊。請參見錯誤碼進行解決。

    {
    "request_id": "daad9007-6acd-9fb3-a6bc-xxxxxx",
    "output": {
        "task_id": "fe8aa114-d9f1-4f76-b598-xxxxxx",
        "task_status": "FAILED",
        "code": "InternalError",
        "message": "xxxxxx"
    }
}

    output object

    任務輸出資訊。

    屬性

    task_id string

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

    task_status string

    任務狀態。

    枚舉值

    • PENDING：任務排隊中

    • RUNNING：任務處理中

    • SUCCEEDED：任務執行成功

    • FAILED：任務執行失敗

    • CANCELED：任務已取消

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

    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。

    results object

    屬性

    video_url string

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

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

    code string

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

    message string

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

    usage object

    用量統計資訊，僅統計成功的請求。

    屬性

    video_duration float

    本次請求產生視頻的時間長度，單位：秒。

    video_ratio string

    本次請求所用的服務模式標識，枚舉值：standard、pro。

    標準模式wan-std對應standard，專業模式wan-pro對應pro。

    request_id string

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

    使用限制

    資料時效：task_id 和視頻URL均只保留 24 小時，請及時下載視頻到本地，到期後將無法查詢或訪問。

    內容審核：輸入和輸出內容均會經過Alibaba Content Security Service審核，包含違規內容的請求將返回 IPInfringementSuspect 或 DataInspectionFailed 錯誤，詳見錯誤碼。

    計費與限流

    • 免費額度和計費單價，請參見萬相-圖生動作。

    • 模型限流，請參見萬相系列。

    • 計費說明：

      • 輸入不計費，輸出按成功產生的視頻秒數計費。

      • 調用失敗不產生任何費用，也不消耗新人免費額度。

    錯誤碼

    調用失敗時，請參見錯誤碼排查解決。

    常見問題

    Q: 如何最佳化產生視頻的效果?

    可參考以下建議：

    1. 確保輸入圖片與參考視頻中的人物畫幅佔比相近。

    2. 保持圖片和視頻中人物的身材比例一致。

    3. 使用高清素材，避免模糊圖片和低幀率視頻，以確保細節識別準確。

    Q: 如何將臨時的視頻連結轉為永久連結？

    無法直接轉換該連結。正確做法是：後端擷取到視頻URL後，通過代碼下載視頻檔案，再上傳至永久Object Storage Service（如阿里雲 OSS），產生新的永久訪問連結。

    範例程式碼：下載視頻到本地

    import requests

def download_and_save_video(video_url, save_path):
    try:
        response = requests.get(video_url, stream=True, timeout=300) # 設定逾時
        response.raise_for_status() # 如果HTTP狀態代碼不是200，則引發異常
        with open(save_path, 'wb') as f:
            for chunk in response.iter_content(chunk_size=8192):
                f.write(chunk)
        print(f"視頻已成功下載到: {save_path}")
        # 此處可以接上傳到永久儲存的邏輯
    except requests.exceptions.RequestException as e:
        print(f"下載視頻失敗: {e}")

if __name__ == '__main__':
    video_url = "http://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxxx"
    save_path = "video.mp4"
    download_and_save_video(video_url, save_path)

    Q: 返回的視頻連結可以在瀏覽器中直接播放嗎？

    不建議。視頻連結 24 小時後失效，最佳實務是後端下載轉存後，通過永久連結提供視頻播放。

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

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