LivePortrait quickly generates lightweight, dynamic portrait videos from portrait images processed by LivePortrait-detect and audio files of human voices. This document describes how to call the video generation API.
This document applies only to the China (Beijing) region. To use this model, you must use an API key for the China (Beijing) region.
Model overview
Model | Description |
liveportrait | Liveportrait is a portrait video generation model that can generate lightweight, dynamic portrait videos from portrait images and human voice audio files. |
HTTP
Prerequisites
Activate Model Studio and create an API key: Get an API key.
The input image has passed LivePortrait image detection.
Input limits
Image format: JPEG, JPG, PNG, BMP, or WebP.
Image resolution: The image file must be smaller than 10 MB. The aspect ratio must be 2 or less. The maximum side length must be 4096 pixels or less.
Audio format: WAV or MP3.
Audio limits: The audio file must be smaller than 15 MB. The duration must be between 1 second and 3 minutes.
Audio content: The audio must contain a clear and loud human voice without environmental noise, background music, or other sound interference.
Upload images and audio files using HTTP or HTTPS URLs. Local file paths are not supported.
Submit a task
POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis/Because this is a time-consuming algorithm call, the task is submitted using an asynchronous invocation.
After you submit the task, the system returns a task ID. Use the "Query task status and retrieve results" API to retrieve the task status and results.
Request parameters
Field | Type | Location | Required | Description | Example |
Content-Type | String | Header | Yes | Request body format. Set this to application/json. | application/json |
Authorization | String | Header | Yes | Your API key with the Bearer prefix. | Bearer d1**2a |
X-DashScope-Async | String | Header | Yes | Set this to enable to submit the task asynchronously. | enable |
model | String | Body | Yes | The model to call. Set this to liveportrait. | liveportrait |
input.image_url | String | Body | Yes | The URL of the uploaded image. The image must first be processed by the LivePortrait image detection API.
Note File uploads support only HTTP or HTTPS links. Local file paths are not supported. | "image_url": "http://a/a.jpg" |
input.audio_url | String | Body | Yes | The URL of the uploaded audio file.
Note File uploads support only HTTP or HTTPS links. Local file paths are not supported. | http://aaa/bbb.wav |
parameters.template_id | String | Body | No | Controls the posture and range of head movements based on a template. Supported templates: normal, calm, and active. Default: normal. | "normal" |
parameters.eye_move_freq | Float | Body | No | The number of blinks per second. Valid values: 0 to 1. A larger value indicates a higher blinking frequency. Default: 0.5. | 0.5 |
parameters.video_fps | Integer | Body | No | The frame rate of the output video. Valid values: 15 to 30. Default: 24. | 24 |
parameters.mouth_move_strength | Float | Body | No | The magnitude of mouth movements. Valid values: 0 to 1.5. A larger value indicates a larger mouth shape. If you set this to 0, the mouth does not move. Default: 1. | 1 |
parameters.paste_back | Boolean | Body | No | Specifies whether to paste the generated face back onto the original image. Valid values: true or false. If you set this to false, only the generated face is returned and the body is ignored. Default: true. | true |
parameters.head_move_strength | Float | Body | No | The magnitude of head movements. Valid values: 0 to 1. A larger value indicates a larger range of head movements. Default: 0.7. | 0.7 |
Response parameters
Field | Type | Description | Example |
output.task_id | String | The ID of the submitted asynchronous task. The actual task result must be obtained using the asynchronous task query API. | a8532587-fa8c-4ef8-82be-0c46b17950d1 |
output.task_status | String | The status of the task after the asynchronous task is submitted. | "PENDING" |
request_id | String | The unique ID of the request. | 7574ee8f-38a3-4b1e-9280-11c33ab46e51 |
Action templates
template_id | Effect description |
normal | The default action template. The range of head movements is moderate. This template is suitable for various scenarios. |
calm | The character appears calm, and the range of head movements is small. This template is recommended for scenarios such as broadcasting. |
active | The character appears lively, and the range of head movements is large. This template is recommended for scenarios such as singing. |
Sample request
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
}
}'Sample response
{
"output": {
"task_id": "a8532587-fa8c-4ef8-82be-0c46b17950d1",
"task_status": "PENDING"
},
"request_id": "7574ee8f-38a3-4b1e-9280-11c33ab46e51"
}Query task status and retrieve results
GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}Request parameters
Field | Type | Location | Required | Description | Example |
Authorization | String | Header | Yes | Your API key with the Bearer prefix. | Bearer d1**2a |
task_id | String | Url Path | Yes | The ID of the task to query. | a8532587-fa8c-4ef8-82be-0c46b17950d1 |
Response parameters
Field | Type | Description | Example |
output.task_id | String | The ID of the queried task. | a8532587-fa8c-4ef8-82be-0c46b17950d1 |
output.task_status | String | The status of the queried task. | Task status: PENDING RUNNING SUCCEEDED FAILED UNKNOWN: The task does not exist or its status is unknown. |
output.results.video_url | String | If the task is successful, this parameter contains the result object generated by the model. Each object contains the URL of the generated result. The video_url is valid for 24 hours after the task is completed. | https://xxx/1.mp4 |
usage.video_duration | Float | The duration of the video generated for this request, in seconds. | 10.23 |
usage.video_ratio | String | The frame type of the video generated for this request. The value is standard. | "video_ratio": "standard" |
request_id | String | The unique ID of the request. | 7574ee8f-38a3-4b1e-9280-11c33ab46e51 |
Sample request
Replace 86ecf553-d340-4e21-xxxxxxxxx with your actual task ID.
curl -X GET https://dashscope.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"Sample response (successful)
{
"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"
}
}Sample response (failed)
{
"request_id": "7574ee8f-38a3-4b1e-9280-xxxxxx",
"output": {
"task_id": "a8532587-fa8c-4ef8-82be-xxxxxx",
"task_status": "FAILED",
"code": "xxx",
"message": "xxxxxx"
}
}Error codes
For information about common status codes, see Error messages.