aliyun-liveportrait

name	aliyun-liveportrait
description	Use when generating lightweight talking-head portrait videos with Alibaba Cloud Model Studio LivePortrait (`liveportrait`) from a detected portrait image and speech audio. Use when you need long-form or simple broadcast-style portrait animation beyond the typical short expressive models.
version	1.0.0

Category: provider

Model Studio LivePortrait

Validation

mkdir -p output/aliyun-liveportrait
python -m py_compile skills/ai/video/aliyun-liveportrait/scripts/prepare_liveportrait_request.py && echo "py_compile_ok" > output/aliyun-liveportrait/validate.txt

Pass criteria: command exits 0 and output/aliyun-liveportrait/validate.txt is generated.

Output And Evidence

• Save normalized request payloads, template choice, and task polling snapshots under output/aliyun-liveportrait/.
• Record the exact portrait/audio URLs and motion-strength related parameters.

Use LivePortrait when the job is lightweight portrait animation with speech audio, especially for longer clips or simpler presenter-style motion.

Critical model names

Use these exact model strings:

• liveportrait-detect
• liveportrait

Selection guidance:

• Run liveportrait-detect first to verify the portrait image.
• Use liveportrait for the actual video generation task.

Prerequisites

• China mainland (Beijing) only.
• Set DASHSCOPE_API_KEY in your environment, or add dashscope_api_key to ~/.alibabacloud/credentials.
• Input image and audio must be public HTTP/HTTPS URLs.

Normalized interface (video.liveportrait)

Detect Request

• model (string, optional): default liveportrait-detect
• image_url (string, required)

Generate Request

• model (string, optional): default liveportrait
• image_url (string, required)
• audio_url (string, required)
• template_id (string, optional): normal, calm, or active
• eye_move_freq (number, optional): 0 to 1
• video_fps (int, optional): 15 to 30
• mouth_move_strength (number, optional): 0 to 1.5
• paste_back (bool, optional)
• head_move_strength (number, optional): 0 to 1

Response

• task_id (string)
• task_status (string)
• video_url (string, when finished)

Quick start

python skills/ai/video/aliyun-liveportrait/scripts/prepare_liveportrait_request.py \
  --image-url "https://example.com/portrait.png" \
  --audio-url "https://example.com/speech.mp3" \
  --template-id calm \
  --video-fps 24 \
  --paste-back

Operational guidance

• Use a clear, front-facing portrait with low occlusion.
• Keep the audio clean and voice-dominant.
• paste_back=false outputs only the generated face region; keep it true for standard talking-head output.
• LivePortrait is a better fit than EMO when you need longer, simpler presenter-style clips.

Output location

• Default output: output/aliyun-liveportrait/request.json
• Override base dir with OUTPUT_DIR.

References

• references/sources.md