VideoRetalk視頻產生 API參考 - Alibaba Cloud Model Studio

聲動人像VideoRetalk是一個人物視頻產生模型，可基於人物視頻和人聲音頻，產生人物講話口型與輸入音頻相匹配的新視頻。本文檔介紹了該模型提供的視頻產生能力的API調用方法。

重要

本文檔僅適用於“中國大陸（北京）”地區。如需使用模型，需使用“中國大陸（北京）”地區的API Key。

HTTP調用介面

VideoRetalk視頻產生API僅支援通過HTTP進行調用。為了減少等待時間並且避免請求逾時，採用了非同步處理方法。因此，您需要發起兩個請求來產生視頻。

作業提交介面：您需要先發送一個請求來建立視頻產生任務。任務提交後，將返回該任務ID。
作業任務狀態查詢和結果擷取介面：使用上一步獲得的任務ID，再發送一個請求，擷取任務狀態及產生的視頻。

前提條件

您需要已擷取與配置 API Key並配置API Key到環境變數（準備下線，併入配置 API Key）。

輸入限制

視頻要求：
- 檔案限制：支援mp4、avi、mov，檔案≤300MB，2秒＜時間長度＜120秒。
- 視頻限制：15fps≤幀率≤60fps；編碼採用H.264或H.265；邊長不低於640，不大於2048。
- 視頻內容：視頻應為人物正面出鏡的近景畫面。避免大角度側臉或人臉過小。
音頻要求：
- 檔案限制：支援wav、mp3、aac，檔案≤30MB，2秒＜時間長度＜120秒。
- 音頻內容：音頻中需包含清晰、響亮的人聲語音，並去除了環境噪音、背景音樂等聲音幹擾資訊。
人物參考圖要求：
- 檔案限制：支援jpeg、jpg、png、bmp、webp，檔案≤10MB。
- 圖片內容：需包含一張清晰的人物正臉，且該人物出現在視頻畫面中。也可從視頻畫面中截圖用作人物參考圖。
上傳檔案連結要求：
- 上傳的視頻、音頻、影像檔支援HTTP連結，不支援本地路徑。也可使用平台提供的臨時儲存空間，上傳本地檔案並建立連結。

作業提交介面

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

入參描述

欄位	類型	傳參方式	必選	描述	樣本值
Content-Type	String	Header	是	請求類型：application/json	application/json
Authorization	String	Header	是	API-Key，例如：Bearer d1**2a	Bearer d1**2a
X-DashScope-Async	String	Header	是	設定為`enable`，表明使用非同步方式建立任務	enable
model	String	Body	是	指明需要調用的模型	videoretalk
input.video_url	String	Body	是	使用者上傳的視頻檔案 URL。 URL 需為公網可訪問的地址，並支援 HTTP 或 HTTPS 協議。視頻檔案要求：大小：檔案≤300MB 格式：mp4、avi、mov 時間長度：2秒＜時間長度＜120秒幀率：15fps≤幀率≤60fps 編碼：推薦採用H.264或H.265編碼邊長：640≤邊長≤2048 內容：人物正面出鏡的近景畫面，避免大角度側臉或人臉過小。如果視頻的畫面中人臉拍不全、沒有人，請參考常見問題進行處理。	http://aaa/bbb.mp4
input.audio_url	String	Body	是	使用者上傳的音頻檔案 URL。 URL 需為公網可訪問的地址，並支援 HTTP 或 HTTPS 協議。音頻檔案要求：大小：檔案≤30MB 格式：wav、mp3、aac 時間長度：2秒＜時間長度＜120秒，如果視頻和音訊時間長度不一致，請參考常見問題進行處理內容：音頻中需包含清晰、響亮的人聲語音，並去除了環境噪音、背景音樂等聲音幹擾資訊。	http://aaa/bbb.wav
input.ref_image_url	String	Body	否	使用者上傳的人臉參考圖 URL。 URL 需為公網可訪問的地址，並支援 HTTP 或 HTTPS 協議。當輸入視頻中存在多張人臉時，您可以通過該參數指定用於口型匹配的人臉。如果視頻中僅有一張人臉，則無需進行指定。若不輸入人臉參考圖，預設將選擇視頻中第一個有人臉的畫面中，人臉佔比最大的人物為目標。影像檔要求：內容：需包含一張清晰的人物正臉，且為視頻中出現的人物檔案大小：檔案≤10MB 映像大小：長寬比小於等於2，最大邊長小於等4096 格式：jpeg、jpg、png、bmp、webp	http://aaa/bbb.jpg
parameters.video_extension	Boolean	Body	否	當輸入的音頻時間長度大於視頻時間長度時，是否擴充視頻長度。預設值為`false`，可設定為`true`或`false`。值為`true`時，使用原視頻畫面“倒放-正放”交替模式擴充視頻時間長度，直至與音頻相同。值為`false`時，不擴充畫面長度，產生視頻時間長度將與原視頻相同，音頻將被截斷。	false

出參描述

欄位	類型	描述	樣本值
output.task_id	String	提交非同步任務的作業 ID，實際作業結果需要通過非同步任務查詢介面擷取。	a8532587-fa8c-4ef8-82be-0c46b17950d1
output.task_status	String	提交非同步任務後的作業狀態。	“PENDING”
request_id	String	本次請求的系統唯一碼。	7574ee8f-38a3-4b1e-9280-11c33ab46e51

請求樣本

curl --location 'https://dashscope.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": "videoretalk",
    "input": {
        "video_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250717/pvegot/input_video_01.mp4",
        "audio_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250717/aumwir/stella2-%E6%9C%89%E5%A3%B0%E4%B9%A67.wav",
        "ref_image_url": ""
     },
    "parameters": {
        "video_extension": false
    }
  }'

響應樣本

{
    "output": {
	"task_id": "a8532587-fa8c-4ef8-82be-0c46b17950d1", 
    	"task_status": "PENDING"
    },
    "request_id": "7574ee8f-38a3-4b1e-9280-11c33ab46e51"
}

作業任務狀態查詢和結果擷取介面

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

入參描述

欄位	類型	傳參方式	必選	描述	樣本值
Authorization	String	Header	是	API-Key，例如：Bearer d1**2a。	Bearer d1**2a
task_id	String	Url Path	是	需要查詢作業的task_id，為作業提交介面返回的值。	a8532587-fa8c-4ef8-82be-0c46b17950d1

出參描述

欄位	類型	描述	樣本值
output.task_id	String	查詢作業的 task_id。	a8532587-fa8c-4ef8-82be-0c46b17950d1
output.task_status	String	被查詢作業的作業狀態。	任務狀態： PENDING：排隊中 PRE-PROCESSING：前置處理中 RUNNING：處理中 POST-PROCESSING：後置處理中 SUCCEEDED：成功 FAILED：失敗 UNKNOWN：作業不存在或狀態未知
output.video_url	String	產生的視頻，video_url有效期間為作業完成後24小時。	https://xxx/1.mp4"
usage.video_duration	Float	本次請求產生視頻時間長度計量，單位：秒。	"video_duration": 10.23
usage.video_ratio	String	本次請求產生視頻的畫幅類型，該值為standard，預設按原視頻比例輸出。	"video_ratio": "standard"
request_id	String	本次請求的系統唯一碼。	7574ee8f-38a3-4b1e-9280-11c33ab46e51

請求樣本

curl -X GET 'https://dashscope.aliyuncs.com/api/v1/tasks/<YOUR_TASK_ID>' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

響應樣本

{
    "request_id": "87b9dce5-7f36-4305-a347-xxxxxx",
    "output": {
        "task_id": "3afd65eb-9604-48ea-8a91-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-09-11 20:15:29.887",
        "scheduled_time": "2025-09-11 20:15:36.741",
        "end_time": "2025-09-11 20:16:40.577",
        "video_url": "http://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.mp4?Expires=xxx"
    },
    "usage": {
        "video_duration": 7.16,
        "video_ratio": "standard"
    }
}

異常響應樣本

{
    "request_id": "7574ee8f-38a3-4b1e-9280-11c33ab46e51",
  	"output": {
        "task_id": "a8532587-fa8c-4ef8-82be-0c46b17950d1", 
    	"task_status": "FAILED",
    	"code": "xxx", 
    	"message": "xxxxxx"
    }  
}

狀態代碼說明

大模型服務通用狀態代碼請查閱：錯誤資訊

同時本模型還有如下特定錯誤碼：

HTTP 返回碼	錯誤碼（code）	錯誤資訊（message）	含義說明
400	InvalidParameter	Field required: xxx	缺少入參，或格式錯誤
400	InvalidURL.ConnectionRefused	Connection to ${url} refused, please provide avaiable URL	下載被拒絕，請提供可用的url
400	InvalidURL.Timeout	Download ${url} timeout, please check network connection.	下載逾時，60s逾時
400	InvalidFile.Size	Invalid file size. The video/audio/image file size must be less than **MB.	視頻/音頻/影像檔必須小於**MB
400	InvalidFile.Format	Invalid file format，the request file format is one of the following types: MP4, AVI, MOV, MP3, WAV, AAC, JPEG, JPG, PNG, BMP, and WEBP.	檔案格式不符合要求，視頻支援mp4、avi、mov；音頻支援mp3, wav, aac；圖片支援jpg, jpeg, png, bmp, webp
400	InvalidFile.Resolution	Invalid video resolution. The height or width of video must be 640 ~ 2048.	視頻邊長需介於640-2048之間
400	InvalidFile.FPS	Invalid video FPS. The video FPS must be 15 ~ 60.	視訊框架率需介於15-60fps之間。
400	InvalidFile.Duration	Invalid file duration. The video/audio file duration must be 2s ~ 120s.	視頻/音頻時間長度需介於2-120s之間
400	InvalidFile.ImageSize	The size of image is beyond limit.	圖片大小超出限制。要求圖片長寬比例不大於2，且最長邊不大於4096
400	InvalidFile.Openerror	Invalid file, cannot open file as video/audio/image.	視頻/音頻/影像檔無法開啟
400	InvalidFile.Content	The input image has no human body or multi human bodies. Please upload other image with single person.	輸入圖片中沒有人或有多人
400	InvalidFile.FaceNotMatch	There are no matched face in the video with the provided reference image.	參考圖與視頻人臉匹配失敗

常見問題

輸入語音和視頻長度不一致，會如何處理？
預設將按音頻、視頻兩者中時間長度較短的來截斷。
當輸入的音頻時間長度大於視頻時間長度時，並希望按音頻長度來產生時，可將入參的視頻擴充（parameters.video_extension）值設為true，演算法將使用原視頻畫面“倒放-正放”交替模式擴充視頻時間長度，直至與音頻相同。
輸入音頻中有靜音的情況，會如何處理？
音頻靜音的時段，預期視頻中人物也會閉嘴。
輸入視頻的畫面中有無人/臉拍不全的情況，會如何處理？
若音頻中有人聲，但畫面無人或未出現人物嘴型，則保留原視頻畫面，音頻正常播放。
輸入視頻的畫面中有多人的情況，會如何處理？
僅支援替換一個人物。演算法會按照輸入人臉參考圖（input.ref_image_url），識別指定人臉。若未輸入人臉參考圖，則預設選擇第一個有人臉畫面中，佔比最大的人臉。