Appearance
LivePortrait-LivePortrait video generation API reference
Generate dynamic portrait videos from portrait images processed by LivePortrait-detect and human voice audio files. This document describes the video generation API. Important
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 | Generates lightweight, dynamic portrait videos from portrait images and human voice audio. |
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: Up to 10 MB, aspect ratio 2 or less, max side length 4096 pixels.
Audio format: WAV or MP3.
Audio limits: Up to 15 MB, duration 1 second to 3 minutes.
Audio content: Clear human voice required. No environmental noise, background music, or other interference.
Upload images and audio files using HTTP or HTTPS URLs. Local file paths are not supported.
Submit a task
HELPCODEESCAPE-http
POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis/Note
Tasks are submitted asynchronously due to long processing time.
After submission, the system returns a task ID. Use the "Query task status and retrieve results" API to retrieve status and results.
Request parameters
| Field | Type | Location | Required | Description | Example |
|---|---|---|---|---|---|
| Content-Type | String | Header | Yes | Request body format. Set to application/json. | application/json |
| Authorization | String | Header | Yes | API key with Bearer prefix. | Bearer d1**2a |
| X-DashScope-Async | String | Header | Yes | Set to enable for asynchronous submission. | enable |
| model | String | Body | Yes | Model name. Set to liveportrait. | liveportrait |
| input.image_url | String | Body | Yes | URL of the uploaded image (must be processed by LivePortrait image detection API first). - Up to 10 MB, aspect ratio 2 or less, max side length 4096 pixels. - Supported formats: JPEG, JPG, PNG, BMP, and WebP. ** **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 | URL of the uploaded audio file. - Up to 15 MB, duration 1 second to 3 minutes. - Supported formats: WAV and MP3. ** **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 head movement posture and range. Options: normal (default), calm, active. | "normal" |
| parameters.eye_move_freq | Float | Body | No | Blinks per second (0-1). Higher values = more frequent blinking. Default: 0.5. | 0.5 |
| parameters.video_fps | Integer | Body | No | Output video frame rate (15-30). Default: 24. | 24 |
| parameters.mouth_move_strength | Float | Body | No | Mouth movement magnitude (0-1.5). Higher values = larger mouth shape. Set to 0 to disable movement. Default: 1. | 1 |
| parameters.paste_back | Boolean | Body | No | Paste generated face onto original image. If false, returns only the face (body ignored). Default: true. | true |
| parameters.head_move_strength | Float | Body | No | Head movement magnitude (0-1). Higher values = larger movement range. Default: 0.7. | 0.7 |
Response parameters
| Field | Type | Description | Example |
|---|---|---|---|
| output.task_id | String | Submitted task ID. Use the query API to retrieve results. | a8532587-fa8c-4ef8-82be-0c46b17950d1 |
| output.task_status | String | Task status after submission. | "PENDING" |
| request_id | String | Unique request ID. | 7574ee8f-38a3-4b1e-9280-11c33ab46e51 |
Action templates
| template_id | Effect description |
|---|---|
| normal | Default template with moderate head movement range. Suitable for various scenarios. |
| calm | The character appears calm with minimal head movement. Recommended for broadcasting scenarios. |
| active | The character appears lively with large head movement range. Recommended for singing scenarios. |
Sample request
HELPCODEESCAPE-curl
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
HELPCODEESCAPE-json
{
"output": {
"task_id": "a8532587-fa8c-4ef8-82be-0c46b17950d1",
"task_status": "PENDING"
},
"request_id": "7574ee8f-38a3-4b1e-9280-11c33ab46e51"
}Query task status and retrieve results
HELPCODEESCAPE-http
GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}Request parameters
| Field | Type | Location | Required | Description | Example |
|---|---|---|---|---|---|
| Authorization | String | Header | Yes | API key with Bearer prefix. | Bearer d1**2a |
| task_id | String | Url Path | Yes | Task ID to query. | a8532587-fa8c-4ef8-82be-0c46b17950d1 |
Response parameters
| Field | Type | Description | Example |
|---|---|---|---|
| output.task_id | String | Queried task ID. | a8532587-fa8c-4ef8-82be-0c46b17950d1 |
| output.task_status | String | Queried task status. | Task status: PENDING RUNNING SUCCEEDED FAILED UNKNOWN: Task doesn't exist or status is unknown. |
| output.results.video_url | String | If the task is successful, this field contains the generated video URL. Valid for 24 hours after task completion. | https://xxx/1.mp4 |
| usage.video_duration | Float | Generated video duration (seconds). | 10.23 |
| usage.video_ratio | String | Generated video frame type. Value: standard. | "video_ratio": "standard" |
| request_id | String | Unique request ID. | 7574ee8f-38a3-4b1e-9280-11c33ab46e51 |
Sample request
Replace 86ecf553-d340-4e21-xxxxxxxxx with your task ID.
HELPCODEESCAPE-curl
curl -X GET https://dashscope.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"Sample response (successful)
HELPCODEESCAPE-json
{
"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)
HELPCODEESCAPE-json
{
"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.