/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`