Aliyun Videoretalk

Name: Aliyun Videoretalk
Author: cinience

cinience/alicloud-skills

51 installs
396 repo stars
Updated July 18, 2026
cinience/alicloud-skills

Replaces lip sync in an existing talking-head video with a new speech track using Alibaba Cloud Model Studio VideoRetalk via its async HTTP API.

About

This skill prepares and submits requests to Alibaba Cloud Model Studio VideoRetalk to replace lip sync in an existing person video with a new audio track. A developer uses it to dub videos, swap narration, or sync a talking-head clip to new speech.

Model string videoretalk; async-only DashScope HTTP API in Beijing region
Supports ref_image_url for multi-face targeting and video_extension for longer audio

Aliyun Videoretalk by the numbers

51 all-time installs (skills.sh)
Ranked #891 of 1,335 Generative Media skills by installs in the Skillselion catalog
Data as of Aug 5, 2026 (Skillselion catalog sync)

npx skills add https://github.com/cinience/alicloud-skills --skill aliyun-videoretalk

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/cinience/alicloud-skills/aliyun-videoretalk.svg)](https://skillselion.com/skills/cinience/alicloud-skills/aliyun-videoretalk)

Installs	51
repo stars	★ 396
Last updated	July 18, 2026
Repository	cinience/alicloud-skills ↗

What it does

Replaces lip sync in an existing talking-head video with a new speech track using Alibaba Cloud Model Studio VideoRetalk via its async HTTP API.

Files

SKILL.mdMarkdownGitHub ↗

Category: provider

Model Studio VideoRetalk

Validation

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

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

Output And Evidence

Save normalized request payloads, target face selection settings, and task polling snapshots under output/aliyun-videoretalk/.
Record the exact video/audio input URLs and whether video_extension was enabled.

Use VideoRetalk when the input is already a person video and the job is to replace lip sync with a new speech track.

Critical model names

Use this exact model string:

videoretalk

Prerequisites

This model currently only supports China mainland (Beijing).
API is HTTP async only; there is no online console experience.
Set DASHSCOPE_API_KEY in your environment, or add dashscope_api_key to ~/.alibabacloud/credentials.

Normalized interface (video.retalk)

Request

model (string, optional): default videoretalk
video_url (string, required)
audio_url (string, required)
ref_image_url (string, optional): target face when input video contains multiple faces
video_extension (bool, optional): extend video to match longer audio
query_face_threshold (int, optional): 120 to 200

Response

task_id (string)
task_status (string)
video_url (string, when finished)
usage (object, optional)

Endpoint and execution model

Submit task: POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis/
Poll task: GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}
HTTP calls are async only and must set header X-DashScope-Async: enable.

Quick start

python skills/ai/video/aliyun-videoretalk/scripts/prepare_retalk_request.py \
  --video-url "https://example.com/talking-head.mp4" \
  --audio-url "https://example.com/new-voice.wav" \
  --video-extension

Operational guidance

Keep input videos front-facing and close enough for stable face tracking.
If the video contains multiple faces, provide ref_image_url to anchor the intended target.
If the new audio is longer than the input video, decide explicitly whether to extend the picture track or truncate the audio.
URLs must be public HTTP/HTTPS links; local file paths are not accepted by the API.

Output location

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

References

references/sources.md

interface:
  display_name: "Alibaba Cloud AI Video Retalk"
  short_description: "Lip-sync replacement with VideoRetalk"
  default_prompt: "Use $aliyun-videoretalk to complete this ai/video retalk task on Alibaba Cloud."

#!/usr/bin/env python3
"""Prepare a normalized request for Model Studio VideoRetalk."""

from __future__ import annotations

import argparse
import json
from pathlib import Path


def main() -> None:
    parser = argparse.ArgumentParser()
    parser.add_argument("--video-url", required=True)
    parser.add_argument("--audio-url", required=True)
    parser.add_argument("--ref-image-url")
    parser.add_argument("--video-extension", action="store_true")
    parser.add_argument("--query-face-threshold", type=int)
    parser.add_argument("--output", default="output/aliyun-videoretalk/request.json")
    args = parser.parse_args()

    payload: dict[str, object] = {
        "model": "videoretalk",
        "input": {
            "video_url": args.video_url,
            "audio_url": args.audio_url,
        },
        "parameters": {
            "video_extension": args.video_extension,
        },
    }
    if args.ref_image_url:
        payload["input"]["ref_image_url"] = args.ref_image_url
    if args.query_face_threshold is not None:
        payload["parameters"]["query_face_threshold"] = args.query_face_threshold

    output = Path(args.output)
    output.parent.mkdir(parents=True, exist_ok=True)
    output.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
    print(json.dumps({"ok": True, "request_path": str(output)}, ensure_ascii=False))


if __name__ == "__main__":
    main()