LivePortrait video generation API reference - Alibaba Cloud Model Studio

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: Obtain 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

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis

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. 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. 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

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.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://{WorkspaceId}.ap-southeast-1.maas.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.

curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.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 codes.

​Model overview

​HTTP

​Prerequisites

​Input limits

​Submit a task

​Request parameters

​Response parameters

​Action templates

​Sample request

​Sample response

​Query task status and retrieve results

​Request parameters

​Response parameters

​Sample request

​Sample response (successful)

​Sample response (failed)

​Error codes

Model overview

HTTP

Prerequisites

Input limits

Submit a task

Request parameters

Response parameters

Action templates

Sample request

Sample response

Query task status and retrieve results

Request parameters

Response parameters

Sample request

Sample response (successful)

Sample response (failed)

Error codes