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

LivePortrait模型，可基於通過LivePortrait-detect模型檢測的人物肖像圖片和人聲音頻檔案，快速、輕量化地產生人像動態視頻。本文檔介紹了該模型提供的視頻產生能力的API調用方法。

重要

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

模型概覽

模型名	模型簡介
liveportrait	liveportrait是一個人物視頻產生模型，可基於人物肖像圖片和人聲音頻檔案，快速、輕量化地產生人物肖像動態視頻。

HTTP調用介面

功能描述

用於產生人物肖像動態視頻。

前提條件

已開通阿里雲百鍊服務並獲得API-KEY：擷取與配置 API Key。
輸入映像已通過LivePortrait 映像檢測檢測。

輸入限制

映像格式：格式為jpeg、jpg、png、bmp、webp。
映像解析度：影像檔<10M，寬高比≤2，最大邊長≤4096像素。
音頻格式：格式為wav、mp3。
音頻限制：檔案＜15M，1s＜時間長度＜3min。
音頻內容：音頻中需包含清晰、響亮的人聲語音，並去除了環境噪音、背景音樂等聲音幹擾資訊。
上傳圖片、音頻連結僅支援HTTP連結方式，不支援本地連結方式。

作業提交介面

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

說明

因該演算法調用耗時較長，故採用非同步呼叫的方式提交任務。
任務提交之後，系統會返回對應的作業ID，後續可通過“作業任務狀態查詢和結果擷取介面”擷取任務狀態及對應結果。

入參描述

欄位	類型	傳參方式	必選	描述	樣本值
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	是	指明需要調用的模型，此處用liveportrait。	liveportrait
input.image_url	String	Body	是	使用者上傳的圖片 URL，該圖應先通過LivePortrait映像檢測API。影像檔<10M，寬高比≤2，最大邊長≤4096。格式支援：jpeg、jpg、png、bmp、webp。說明上傳檔案支援HTTP或HTTPS連結方式，不支援本地連結方式。	"image_url": "http://a/a.jpg"
input.audio_url	String	Body	是	使用者上傳的音頻檔案 URL。音頻檔案＜15M，1s＜時間長度＜3min。格式支援：wav、mp3。說明上傳檔案支援HTTP或HTTPS連結方式，不支援本地連結方式。	http://aaa/bbb.wav
parameters.template_id	String	Body	否	可按模板控制人物頭部的運動姿態和幅度，當前支援3種模板：normal、calm、active。預設為normal。	"normal"
parameters.eye_move_freq	Float	Body	否	每秒眨眼次數，可設值為0-1，值越大眨眼頻率越高。預設值為0.5。	0.5
parameters.video_fps	Integer	Body	否	輸出視訊框架率，可設值為15-30。預設值為24。	24
parameters.mouth_move_strength	Float	Body	否	嘴部動作的幅度大小，可設值為0-1.5，值越大嘴型越大。若設為0則嘴部無動作。預設值為1。	1
parameters.paste_back	Boolean	Body	否	產生的人臉是否貼回原圖，可設值為true或false。若設為false則僅輸出產生的人臉，忽略人物身體。預設值為true。	true
parameters.head_move_strength	Float	Body	否	頭部動作幅度，可設值為0-1，值越大頭部動作幅度越大。預設值為0.7。	0.7

出參描述

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

可選用的動作模板

template_id	效果說明
normal	預設動作模板，頭部動作幅度適中。適用於多種情境。
calm	人物表現平靜，頭部動作幅度較小。推薦用於播報等情境。
active	人物表現活潑，頭部動作幅度較大。推薦用於演唱等情境。

請求樣本

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": "liveportrait",
    "input": {
        "image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250911/ynhjrg/p874909.png",
        "audio_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251226/fwnqyq/liveportrait_boy.mp3"
    },
      "parameters": {
         "template_id": "normal",
         "eye_move_freq": 0.5,
         "video_fps":30,
         "mouth_move_strength":1,
         "paste_back": true,
         "head_move_strength":0.7
    }
  }'

響應樣本

{
    "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 排隊中 RUNNING 處理中 SUCCEEDED 成功 FAILED 失敗 UNKNOWN 作業不存在或狀態未知
output.results.video_url	String	如果作業成功，包含模型產生的結果 object，然後每個 object 中包含按照要求產生的結果地址。video_url有效期間為作業完成後24小時。	https://xxx/1.mp4
usage.video_duration	Float	本次請求產生視頻時間長度計量，單位：秒。	10.23
usage.video_ratio	String	本次請求產生視頻的畫幅類型，該值為standard。	"video_ratio": "standard"
request_id	String	本次請求的系統唯一碼。	7574ee8f-38a3-4b1e-9280-11c33ab46e51

請求樣本

將86ecf553-d340-4e21-xxxxxxxxx替換為真實的task_id。

curl -X GET https://dashscope.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

響應樣本（作業成功執行完畢）

{
    "request_id": "b64e9c68-3923-462d-b25a-xxxxxx",
    "output": {
        "task_id": "a1c69ca5-810b-49ae-8b20-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-12-26 11:33:03.146",
        "scheduled_time": "2025-12-26 11:33:13.312",
        "end_time": "2025-12-26 11:33:22.455",
        "results": {
            "video_url": "http://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.mp4?Expires=xxx"
        }
    },
    "usage": {
        "video_duration": 2.79,
        "video_ratio": "standard"
    }
}

響應樣本（作業失敗）

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

狀態代碼說明

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