Skip to main content
萬相

萬相-視頻換人API參考

萬相-視頻換人模型能夠依據人物圖片和參考視頻，將視頻中的主角替換為圖片中的角色，同時保留原視頻的情境、光照和色調，實現無縫換人。

  • 核心功能： 在不改變原始視頻的動作、表情及環境的條件下，將視頻中的角色替換為指定圖片中的人物。
  • 適用情境：適用於二次創作、影視後期製作等需要進行角色替換的情境。

效果樣本

萬相-視頻換人模型wan2.2-animate-mix提供標準模式wan-std和專業模式wan-pro兩種服務模式，不同模式在效果和計費上存在差異，詳情參見計費與限流。
人物圖片參考視頻輸出視頻（標準模式wan-std）輸出視頻（專業模式wan-pro）
mix_input_image

HTTP調用

您需要已擷取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：發送一個請求建立任務，該請求會返回任務ID（task_id）。
  2. 根據任務ID查詢結果：使用task_id輪詢任務狀態，直到任務完成並獲得視頻URL。

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

新加坡地區：POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis 北京地區：POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2video/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。
缺少此要求標頭將報錯：“current user api does not support synchronous calls”。
請求體（Request Body）
model string （必選）模型名稱，必須設定為wan2.2-animate-mix。input object （必選）視頻換人的輸入圖片和視頻。

屬性

image_url string （必選）人物圖片的公網可訪問HTTP/HTTPS URL，不能包含中文等非ASCII字元，否則需編碼後傳入。
  • 格式限制：JPG、JPEG、PNG、BMP、WEBP
  • 尺寸限制：映像的寬度和高度都在[200,4096]像素範圍內，寬高比在1:3至3:1範圍內。
  • 大小限制：不超過5MB
  • 樣本：https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/bhkfor/mix_input_image.jpeg
video_url string （必選）參考視頻的公網可訪問HTTP/HTTPS URL，不能包含中文等非ASCII字元，否則需編碼後傳入。建議：更高的解析度和幀率可有效提升輸出視頻畫質。
  • 格式限制：MP4、AVI、MOV
  • 尺寸限制：視頻的寬度和高度都在[200, 2048]像素範圍內，寬高比在1:3至3:1範圍內。
  • 大小限制：不超過200MB
  • 時間長度限制：不小於2s且不大於30s
  • 樣本：https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/wqefue/mix_input_video.mp4
watermark bool（可選）是否添加浮水印標識，浮水印位於圖片右下角，文案為“通義AI產生”。
  • false（預設值）：不添加浮水印。
  • true：添加浮水印。
parameters object （必選）

屬性

check_image bool （可選）控制是否在處理前對輸入圖片進行檢查。
  • true（預設值）：在處理前檢查輸入圖片。
  • false：跳過檢查，直接處理。
mode string （必選）服務模式，提供兩種選擇：
  • wan-std：標準模式。產生速度快、性價比高，適用於快速預覽和基礎動畫。
  • wan-pro：專業模式。動畫更流暢、畫質更優，但處理時間和費用相應增加。
詳情請參見效果樣本和計費與限流。
  • 視頻換人
以下為新加坡地區的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-mix",
        "input": {
            "image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/bhkfor/mix_input_image.jpeg",
            "video_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/wqefue/mix_input_video.mp4",
            "watermark": true
        },
        "parameters": {
            "mode": "wan-std"
        }
      }'

響應參數

output object任務輸出資訊。

屬性

task_id string任務ID。查詢有效期間24小時。task_status string任務狀態。

枚舉值

  • PENDING：任務排隊中
  • RUNNING：任務處理中
  • SUCCEEDED：任務執行成功
  • FAILED：任務執行失敗
  • CANCELED：任務已取消
  • UNKNOWN：任務不存在或狀態未知
request_idstring請求唯一標識。可用於請求明細溯源和問題排查。messagestring請求失敗的詳細資料。請求成功時不會返回此參數，詳情請參見錯誤碼。codestring請求失敗的錯誤碼。請求成功時不會返回此參數，詳情請參見錯誤碼。
  • 成功響應
  • 異常響應
請儲存 task_id，用於查詢任務狀態與結果。
{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

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

  • 新加坡
  • 華北2（北京）
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}調用時請將{WorkspaceId}替換為真實的Workspace ID。
  • 輪詢建議：視頻產生過程約需數分鐘，建議採用輪詢機制，並設定合理的查詢間隔（如 15 秒）來擷取結果。
  • 任務狀態流轉：PENDING（排隊中）→ RUNNING（處理中）→ SUCCEEDED（成功）/ FAILED（失敗）。
  • 結果連結：任務成功後返回視頻連結，有效期間為 24 小時。建議在擷取連結後立即下載並轉存至永久儲存（如阿里雲 OSS）。
  • task_id 有效期間：24小時，逾時後將無法查詢結果，介面將返回任務狀態為UNKNOWN。

請求參數

要求標頭（Headers）
Authorizationstring（必選）請求身份認證。介面使用阿里雲百鍊API Key進行身份認證。樣本值：Bearer sk-xxxx。
URL路徑參數（Path parameters）
task_id string（必選）任務ID。
  • 查詢任務結果
請將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"

響應參數

outputobject任務輸出資訊。

屬性

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_urlstring視頻URL。僅在 task_status 為 SUCCEEDED 時返回。連結有效期間24小時，可通過此URL下載視頻。視頻格式為MP4（H.264 編碼）。
codestring請求失敗的錯誤碼。請求成功時不會返回此參數，詳情請參見錯誤碼。messagestring請求失敗的詳細資料。請求成功時不會返回此參數，詳情請參見錯誤碼。
usage object僅在任務成功時返回。

屬性

video_duration float產生視頻的時間長度，單位：秒。video_ratio string本次請求使用的服務模式。選擇標準模式wan-std時返回standard，選擇專業模式wan-pro時返回pro。
request_idstring請求唯一標識。可用於請求明細溯源和問題排查。
  • 任務執行成功
  • 任務執行失敗
視頻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_id和視頻URL均只保留 24 小時，到期後將無法查詢或下載，請及時下載視頻到本地。 內容審核：輸入與輸出內容均會經過Alibaba Content Security Service審核，包含違規內容的請求將報錯“IPInfringementSuspect”或“DataInspectionFailed”，具體參見錯誤碼。

計費與限流

  • 模型免費額度和計費單價請參見模型價格。
  • 模型限流請參見萬相系列。
  • 計費說明：
    • 輸入不計費，輸出計費。按成功產生的 視頻秒數 計費。
    • 模型調用失敗或處理錯誤不產生任何費用，也不消耗免費額度。

錯誤碼

如果調用失敗，請參見錯誤碼。

常見問題

Q: 如何查看模型調用量？

A: 調用資料存在約一小時延遲。請在模型觀測（新加坡或北京）頁面查看調用量、調用次數和成功率等指標。如何查看模型調用記錄？

Q: 如何提升產生視頻的品質?

A: 建議：
  1. 確保輸入圖片與參考視頻中的人物畫幅佔比相似。
  2. 盡量保持圖片和視頻中人物的身材比例一致。
  3. 使用高清素材，避免使用模糊圖片和低幀率視頻，確保細節識別準確。

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

A: 不支援直接轉換。請在後端下載視頻檔案後上傳至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: 返回的視頻連結可以在瀏覽器中直接播放嗎？

A: 不建議直接播放，連結會在 24 小時後失效。請在後端下載轉存後，使用永久連結播放。

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

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