蝉镜定制数字人

功能说明

从本机上传源视频创建蝉镜定制数字人，并支持列表、查询、轮询与删除；流程与 Open API 一致：获取上传 URL（createuploadurl）→ 对返回的 sign_url 发起 PUT 上传正文 → 创建/列出/获取/轮询/删除。仅使用蝉镜 Open API 与接口返回的上传端点，不引入其它云厂商凭证。脚本不依赖 ffmpeg/ffprobe。环境变量均可选（默认 ~/.chanjing 与官方 API 基址）。凭据、令牌持久化、网络边界见 manifest.yaml。

运行依赖

• - python3 与同仓库 scripts/*.py；可读本地视频文件路径并上传

安装与分发说明

• - 本技能没有单独的「安装规范」文档，仅以本文与 manifest.yaml 中的使用说明为准。
• 仓库内仅包含 Python 脚本；脚本仅使用 Python 标准库，不会自动下载或安装 pip 包或其它二进制。
• 无内置安装器、无运行时拉取依赖，从安装/供应链面看风险较低。

环境变量与机器可读声明

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

使用命令

• - ClawHub（slug 以注册表为准）：clawhub run chanjing-customised-person
• 本仓库：python skills/chanjing-customised-person/scripts/create_person.py …（见 标准工作流程）

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

英文登记、主凭据、primaryEnv 省略、可选 env、敏感字段与出站边界：以同目录 manifest.yaml 为准（与 credential_hint、description frontmatter 一致）。本篇从 何时使用 起写业务能力与流程，勿与 manifest.yaml 重复维护长篇对表。

何时使用此技能

当用户要做这些事时使用本 Skill：

• * 上传真人源视频，创建蝉镜定制数字人
• 查询定制数字人列表或单个形象详情
• 轮询定制数字人制作进度
• 删除不再需要的定制数字人

如果需求是拿已有数字人去合成口播视频，优先使用 chanjing-video-compose。
如果需求是上传真人视频做对口型驱动，优先使用 chanjing-avatar。

前置条件

执行本 Skill 前，必须先通过 chanjing-credentials-guard 完成 AK/SK 与 Token 校验。

本 Skill 与 guard 共用：

• * ~/.chanjing/credentials.json
• https://open-api.chanjing.cc

无凭证时，脚本会自动打开蝉镜登录页，并提示配置命令。

审阅与安全（凭据与边界）

与 目的 / 凭据 / 持久化 / 网络 相关的逐项说明见 manifest.yaml（含 permissions.network_mode: open 与 signUrlPutNote）。以下仅 SKILL 正文补充：

• - credentials.json：脚本会读取本地凭据；刷新后的 accesstoken / expirein 写回同一文件为预期行为。须限制目录/文件权限（如目录 0700、文件 0600），并确保永不提交版本库（见 manifest doNotCommitToVcs）。
• signurl 与 PUT 主机：uploadfile.py / getuploadurl.py 先请求 open-api.chanjing.cc 的 createuploadurl，再向响应中的 signurl 发起 HTTPS PUT；该 URL 的主机常为蝉镜侧对象存储或 CDN，可能不在固定主机白名单中，清单中已改为 networkmode: open 以如实声明。
• create_person.py --callback：若传入 URL，远程服务可能向该端点 POST 任务结果，载荷可能含状态与资源引用等敏感信息；须自行信任该端点并承担出站与数据暴露风险。
• 本地视频：仅按用户给出的路径读取视频字节并上传到 API 指定端点；不扫描其它无关系统路径。

标准工作流程

1. 1. 上传本地源视频，获取 fileid（推荐 uploadfile.py：内部为 GET …/createuploadurl → PUT signurl（正文为文件）→ 轮询 filedetail 至就绪；亦可分步用 getuploadurl.py + 自行 PUT + 轮询）
2. 调用 createperson.py 创建定制数字人任务，得到 personid
3. 调用 pollperson.py 轮询直到成功，得到 previewurl，或用 getperson --field audiomanid 拿到声音 id
4. 如需批量查看历史形象，用 listpersons.py
5. 如需清理资源，用 delete_person.py

覆盖的 API

本 Skill 当前覆盖：

• * GET /open/v1/common/createuploadurl
• GET /open/v1/common/filedetail
• POST /open/v1/createcustomisedperson
• POST /open/v1/listcustomisedperson
• GET /open/v1/customisedperson
• POST /open/v1/deletecustomisedperson

脚本

脚本目录：

• * skills/chanjing-customised-person/scripts/

使用示例

示例 1：从本地视频创建定制数字人

bash
FILEID=$(python3 skills/chanjing-customised-person/scripts/uploadfile.py \
--file ./source.mp4)

PERSONID=$(python3 skills/chanjing-customised-person/scripts/createperson.py \
--name 演示数字人 \
--file-id $FILE_ID \
--train-type figure)

python3 skills/chanjing-customised-person/scripts/pollperson.py --id $PERSONID

示例 2：查看完整详情

bash
python3 skills/chanjing-customised-person/scripts/get_person.py \
--id C-ef91f3a6db3144ffb5d6c581ff13c7ec

示例 3：列出与删除

bash
python3 skills/chanjing-customised-person/scripts/list_persons.py

python3 skills/chanjing-customised-person/scripts/delete_person.py \
--id C-ef91f3a6db3144ffb5d6c581ff13c7ec

输出约定

默认不自动下载任何预览视频或封面图：

• * createperson.py 输出 personid
• pollperson.py 输出 previewurl，便于继续预览或保存
• 只有在用户明确要求时，才应把返回的资源 URL 另存到本地

如果后续需要落盘预览资源，建议使用：

• * outputs/customised-person/

附加资源

更多接口细节与触发样例见：

• * skills/chanjing-customised-person/reference.md
• skills/chanjing-customised-person/examples.md