chanjing-avatar

蝉镜 Avatar（口型同步）

功能说明

调用蝉镜 Avatar Open API：上传音视频素材、创建口型同步任务、轮询并获取结果链接。脚本使用 Python HTTP/上传客户端，不依赖 ffmpeg/ffprobe。

运行依赖

• python3 与同仓库 scripts/*.py
• 无 ffmpeg/ffprobe 门控

环境变量与机器可读声明

• 环境变量键名与说明：manifest.yaml（environment 段）及本文
• 变量、凭据、合规 permissions、clientPermissions、agentPolicy：manifest.yaml

使用命令

• ClawHub（slug 以注册表为准）：clawhub run chanjing-avatar
• 本仓库：python skills/chanjing-avatar/scripts/create_task.py …（流程见正文 How to Use）

---

登记与审稿（单一事实来源）

主凭据、上传/下载边界、浏览器引导等：以 manifest.yaml 为准。本文从 How to Use 起为 API 步骤说明。

何时使用此技能

当用户需要创建带有同步嘴部动作的口型同步视频（数字人视频）时，使用此技能。

蝉镜 Avatar 支持：

• 文本驱动或音频驱动的口型同步
• 多种 TTS 系统语音
• 自定义视频分辨率
• 任务状态轮询与回调

如何使用此技能

前置条件：执行此 Skill 前，必须先通过 chanjing-credentials-guard 完成 AK/SK 与 Token 校验。凭据与审稿对表见 manifest.yaml。

安全与凭据（引用）

详见 manifest.yaml 中的 credentials 与 clientPermissions（含本地上传、结果 URL、浏览器行为；合规要求见顶层 permissions）。

需要调用多个 API。它们共用域名："https://open-api.chanjing.cc"。 所有请求均使用 json 通信。 整个任务中，文本都应使用 utf-8 编码和解码。

1. 获取 access_token，后续所有 API 调用均需要此 Token
2. 使用文件管理 API 上传视频/音频文件，以获取 file_id
3. 使用这些 file_id 值创建包含视频和音频/文本的口型同步任务
4. 轮询查询任务详情 API 或使用任务列表 API 检查状态
5. 状态为已完成时，使用响应中的 url 下载生成的视频

获取 AccessToken

从 ~/.chanjing/credentials.json 读取 app_id 和 secret_key，若无有效 Token 则调用：

POST /open/v1/access_token
Content-Type: application/json

请求体（使用本地配置的 app_id、secret_key）：

{
  "app_id": "<从 credentials.json 读取>",
  "secret_key": "<从 credentials.json 读取>"
}

响应示例：

{
  "trace_id": "8ff3fcd57b33566048ef28568c6cee96",
  "code": 0,
  "msg": "success",
  "data": {
    "access_token": "1208CuZcV1Vlzj8MxqbO0kd1Wcl4yxwoHl6pYIzvAGoP3DpwmCCa73zmgR5NCrNu",
    "expire_in": 1721289220
  }
}

响应字段说明：

一级字段	二级字段	说明
code		响应状态码
msg		响应消息
data		响应数据
	access_token	有效期为一天，之前的 Token 将失效
	expire_in	Token 过期时间

响应状态码说明

代码	说明
0	成功
400	参数格式无效
40000	参数错误
50000	系统内部错误

上传媒体文件（文件管理）

创建口型同步任务前，必须使用文件管理 API 上传视频（以及可选的音频）文件，以获取 file_id 值。

完整文档见 [文件管理](https://doc.chanjing.cc/api/file/file-management.html)。

第 1 步：获取上传 URL

GET /open/v1/common/create_upload_url
access_token: {{access_token}}

查询参数：

键	示例	说明
service	lip_sync_video / lip_sync_audio	文件用途。驱动视频使用 lip_sync_video，音频（音频驱动时）使用 lip_sync_audio。
name	1.mp4	包含扩展名的原始文件名

响应中会包含 sign_url、mime_type 和 file_id。使用 sign_url 通过 HTTP PUT 上传文件，并将 Content-Type 设为返回的 mime_type。PUT 完成后，轮询文件详情 API，直到文件就绪（不要假设固定等待时长）。保留返回的 file_id，供下文的 video_file_id / audio_file_id 使用。

**轮询：**调用 GET /open/v1/common/file_detail?id={{file_id}} 并附带 access_token，直到响应 data.status 表示成功（例如 status === 2）。只有此时才能将 file_id 用于创建任务 API。

创建口型同步任务

提交口型同步视频创建任务，返回一个视频 ID，供之后查询任务状态。

POST /open/v1/video_lip_sync/create
access_token: {{access_token}}
Content-Type: application/json

请求体示例（由 TTS 驱动）：

{
  "video_file_id": "e284db4d95de4220afe78132158156b5",
  "screen_width": 1080,
  "screen_height": 1920,
  "callback": "https://example.com/openapi/callback",
  "model": 0,
  "audio_type": "tts",
  "tts_config": {
    "text": "君不见黄河之水天上来，奔流到海不复回。",
    "audio_man_id": "C-f2429d07554749839849497589199916",
    "speed": 1,
    "pitch": 1
  }
}

请求体示例（由音频驱动）：

{
  "video_file_id": "e284db4d95de4220afe78132158156b5",
  "screen_width": 1080,
  "screen_height": 1920,
  "model": 0,
  "audio_type": "audio",
  "audio_file_id": "audio_file_id_from_file_management"
}

请求字段说明：

参数名称	类型	必填	说明
video_file_id	string	是	来自文件管理的文件 ID（data.file_id）。支持 mp4、mov、webm
screen_width	int	否	屏幕宽度，默认值为 1080
screen_height	int	否	屏幕高度，默认值为 1920
backway	int	否	播放到结尾时的播放顺序：1-正常，2-反向。默认值为 1
drive_mode	string	否	驱动模式：""-正常，"random"-随机帧。默认值为 ""
callback	string	否	用于异步通知的回调 URL
model	int	否	模型版本：0-基础版，1-高质量。默认值为 0
audio_type	string	否	音频类型："tts"-文本驱动，"audio"-音频驱动。默认值为 "tts"
tts_config	object	是（适用于 tts）	当 audio_type="tts" 时的 TTS 配置
tts_config.text	string	是（适用于 tts）	要合成的文本
tts_config.audio_man_id	string	是（适用于 tts）	语音 ID
tts_config.speed	number	否	语速：0.5-2，默认值为 1
tts_config.pitch	number	否	音调，默认值为 1
audio_file_id	string	是（适用于 audio）	当 audio_type="audio" 时，来自文件管理的音频文件 ID（data.file_id）。支持 mp3、m4a、wav
volume	int	否	音量：1-100，默认值为 100

响应示例：

{
  "trace_id": "8d10659438827bd4d59eaa2696f9d391",
  "code": 0,
  "msg": "success",
  "data": "9499ed79995c4bdb95f0d66ca84419fd"
}

响应字段说明：

字段	说明
code	响应状态码
msg	响应消息
data	用于后续查询的视频 ID

查询任务列表

获取口型同步任务列表。

POST /open/v1/video_lip_sync/list
access_token: {{access_token}}
Content-Type: application/json

请求体：

{
  "page": 1,
  "page_size": 10
}

请求字段说明：

参数	类型	必填	说明
page	int	否	页码，默认值为 1
page_size	int	否	每页条数，默认值为 10

响应示例：

{
  "trace_id": "8d10659438827bd4d59eaa2696f9d391",
  "code": 0,
  "msg": "success",
  "data": {
    "list": [
      {
        "id": "9499ed79995c4bdb95f0d66ca84419fd",
        "status": 20,
        "progress": 100,
        "msg": "success",
        "video_url": "https://res.chanjing.cc/xxx/lip-sync/9499ed79995c4bdb95f0d66ca84419fd.mp4",
        "preview_url": "https://res.chanjing.cc/xxx/lip-sync/9499ed79995c4bdb95f0d66ca84419fd.jpg",
        "duration": 300,
        "create_time": 1738636800
      }
    ],
    "page_info": {
      "page": 1,
      "size": 10,
      "total_count": 1,
      "total_page": 1
    }
  }
}

响应字段说明：

一级字段	二级字段	说明
code		响应状态码
msg		响应消息
data		响应数据
	list	任务列表
		id：视频 ID
		status：任务状态（0-等待中，10-生成中，20-成功，30-失败）
		progress：进度 0-100
		msg：任务消息
		video_url：视频下载 URL
		preview_url：封面图片 URL
		duration：视频时长（毫秒）
		create_time：创建时间（Unix 时间戳）
	page_info	分页信息

查询任务详情

轮询以下 API，检查任务状态，直到任务完成。

GET /open/v1/video_lip_sync/detail
access_token: {{access_token}}

查询参数：

参数	说明
id	视频 ID

示例：GET /open/v1/video_lip_sync/detail?id=9499ed79995c4bdb95f0d66ca84419fd

响应示例：

{
  "trace_id": "8d10659438827bd4d59eaa2696f9d391",
  "code": 0,
  "msg": "success",
  "data": {
    "id": "9499ed79995c4bdb95f0d66ca84419fd",
    "status": 20,
    "progress": 100,
    "msg": "success",
    "video_url": "https://res.chanjing.cc/xxx/lip-sync/9499ed79995c4bdb95f0d66ca84419fd.mp4",
    "preview_url": "https://res.chanjing.cc/xxx/lip-sync/9499ed79995c4bdb95f0d66ca84419fd.jpg",
    "duration": 300,
    "create_time": 1738636800
  }
}

响应字段说明：

一级字段	二级字段	说明
code		响应状态码
msg		响应消息
data		响应数据
	id	视频 ID
	status	任务状态：0-等待中，10-生成中，20-成功，30-失败
	progress	进度 0-100
	msg	任务消息
	video_url	视频下载 URL
	preview_url	封面图片 URL
	duration	视频时长（毫秒）
	create_time	创建时间（Unix 时间戳）

回调通知

提供回调 URL 后，任务完成时系统将发送 POST 请求：

{
  "trace_id": "8d10659438827bd4d59eaa2696f9d391",
  "code": 0,
  "msg": "success",
  "data": {
    "id": "9499ed79995c4bdb95f0d66ca84419fd",
    "status": 20,
    "progress": 100,
    "msg": "success",
    "video_url": "https://res.chanjing.cc/xxx/lip-sync/9499ed79995c4bdb95f0d66ca84419fd.mp4",
    "preview_url": "https://res.chanjing.cc/xxx/lip-sync/9499ed79995c4bdb95f0d66ca84419fd.jpg",
    "duration": 300,
    "create_time": 1738636800
  }
}

Scripts

本 Skill 提供脚本（skills/chanjing-avatar/scripts/），与 chanjing-credentials-guard 使用同一配置文件（~/.chanjing/credentials.json）获取 Token。

脚本	说明
get_upload_url.py	获取上传链接，输出 sign_url、mime_type、file_id
upload_file.py	上传本地文件，轮询 file_detail 直到就绪后输出 file_id
create_task.py	创建对口型任务（TTS 或音频驱动），输出视频任务 id
poll_task.py	轮询任务直到完成，输出 video_url

示例（在项目根或 skill 目录下执行）：

# 1. 上传驱动视频，得到 video_file_id
VIDEO_FILE_ID=$(python skills/chanjing-avatar/scripts/upload_file.py --service lip_sync_video --file ./my_video.mp4)

# 2. 创建 TTS 对口型任务（需先通过 list_common_audio 获取 audio_man_id）
TASK_ID=$(python skills/chanjing-avatar/scripts/create_task.py \
  --video-file-id "$VIDEO_FILE_ID" \
  --text "君不见黄河之水天上来" \
  --audio-man-id "C-f2429d07554749839849497589199916")

# 3. 轮询直到完成，得到视频下载链接
python skills/chanjing-avatar/scripts/poll_task.py --id "$TASK_ID"

音频驱动时：先上传音频得到 audio_file_id，再 create_task.py --video-file-id <id> --audio-file-id <audio_file_id>。

Response Status Code Description

Code	Description
0	Response successful
10400	AccessToken verification failed
40000	Parameter error
40001	Exceeds RPM/QPS limit
50000	System internal error