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

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

重要

本文檔僅適用於華北2（北京）地區。如需使用模型，需使用華北2（北京）地區的API Key。

HTTP調用介面

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

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

前提條件

您需要已擷取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連結，不支援本地路徑。也可使用平台提供的臨時儲存空間，上傳本地檔案並建立連結。
- 如果使用臨時儲存空間上傳檔案後擷取到的oss://首碼URL，在HTTP要求標頭中必須添加X-DashScope-OssResourceResolve: enable參數。未添加該參數會導致報錯No connection adapters were found for 'oss://...'。詳細說明請參見上傳檔案擷取臨時URL。

作業提交介面

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
parameters.query_face_threshold	Integer	Body	否	當輸入人臉參考圖時，可通過該值調整人臉匹配的信賴度。取值範圍為120-200。值越小，人臉參考圖的匹配越寬鬆；值越大，人臉參考圖的匹配越嚴格。預設值為170。備忘：input.ref_image_url 為空白時該參數不生效。	170

出參描述

欄位	類型	描述	樣本值
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"
usage.size	String	本次請求產生視頻的解析度，和輸入視頻解析度一致	"size": "1080*1920"
usage.fps	Integer	本次請求產生視頻的幀率，和輸入視訊框架率一致	"fps": 25
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.2,
        "size": "1080*1920",
        "video_ratio": "standard",
        "fps": 25
    }
}

異常響應樣本

{
    "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），識別指定人臉。若未輸入人臉參考圖，則預設選擇第一個有人臉畫面中，佔比最大的人臉。