Skip to main content
視頻口型替換-聲動人像VideoRetalk

VideoRetalk 視頻產生 API參考

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

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

HTTP調用介面

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

前提條件

您需要已擷取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.

參考圖與視頻人臉匹配失敗

常見問題

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