蝉镜数字人 Skill 教程：对口型、口播合成与可选文生形象

数字人口播常见会把两种需求混在一起：一种是把已有的真人出镜视频做成对口型；另一种是从平台或定制数字人库里选一个形象，用文本或音频生成口播视频。蝉镜仓库把它们分成不同技能。前者是 chanjing-avatar，后者是 chanjing-video-compose。若还没有形象、只想先用提示词生成一张人物图再做成短口播，才考虑可选的 chanjing-text-to-digital-person。

本文把这组技能放在同一篇里对照说明，避免选错入口。练习以“用公共数字人朗读一段虚构清洁口播”为主，对口型和文生形象只作为并列路径讲清步骤与限制。本文核对了官方 SKILL.md、reference 与 examples，没有实际上传素材，也没有调用蝉镜 API。文中的人物 ID、任务 ID 和视频地址都是文档结构示例或占位符，不冒充已经生成的成片。

一、先分清三条路径，再决定用哪一个

chanjing-avatar 面向对口型：先上传驱动视频（以及在音频驱动时上传音频），拿到 file_id 后再创建任务。它支持文本驱动或音频驱动，可指定输出宽高，并提供基础或更高质量的模型选项。官方写明视频常用 mp4、mov、webm，音频常用 mp3、m4a、wav。如果你的需求是“上传一段真人视频，让口型跟上稿件或录音”，应优先走这条路径，不要和合成技能混用。

chanjing-video-compose 面向已有数字人形象的视频合成：先选择公共数字人（common）或定制数字人（customised），再按文本或本地音频创建任务、轮询结果。脚本同样不依赖 ffmpeg / ffprobe。默认不会自动把成片下载到本地，只有在你明确要求保存时，才使用下载脚本。

chanjing-text-to-digital-person 是可选技能，不是前两条的必经步骤。它先按人物提示词生成形象图，再把选定的图做成会说话的短视频。若需求是“上传真人素材训练定制数字人”，官方建议改用 chanjing-customised-person，本文不展开成必选流程。若需求是“已经有数字人，直接做口播”，应回到 chanjing-video-compose。

三条路径都需要先通过 chanjing-credentials-guard 校验本地 AK/SK 和 Token，并共用 ~/.chanjing/credentials.json 与 https://open-api.chanjing.cc。面孔和声音只用于本人或已授权素材；不要用未授权的真人视频、肖像或录音去创建对口型、定制形象或克隆效果。

知行之外 · mywwx.com

二、来源、版本与下载范围

这些技能都在 chanjing-ai/chan-skills 仓库中。本站三篇蝉镜教程共用完整源码包 cf3714fd（2026-10-22 源码快照），对应提交 cf3714fde137ca5cadd191dd2db1a4a8be601c85，不是为这一篇单独重打的新包，也不使用更早的 tag v1.0.1。仓库未标注许可证，包内不应包含凭证文件。

解压后核对这些路径：

chan-skills-cf3714fd/
  README.md
  README.zh-CN.md
  使用说明.txt
  skills/chanjing-credentials-guard/SKILL.md
  skills/chanjing-avatar/SKILL.md
  skills/chanjing-video-compose/SKILL.md
  skills/chanjing-video-compose/scripts/list_figures.py
  skills/chanjing-video-compose/scripts/create_task.py
  skills/chanjing-text-to-digital-person/SKILL.md

官方还提醒：文生数字人技能的完整包应包含 _auth.py、_task_api.py 以及创建、轮询、下载等脚本；若缺少其中入口，属于分发不完整，而不是改用其他技能名称就能补齐。

三、共同准备：凭证、权限和素材边界

先在本机完成 guard 配置和状态检查，命令与另外两篇蝉镜教程相同，这里不再重复密钥示例。不要在对话中粘贴 AK/SK，也不要让脚本把凭证写进项目仓库。

还要事先想清楚素材来源：

1. 对口型所使用的出镜视频，应是你本人或已获得出镜授权的素材。
2. 音频驱动时，录音也应有相应授权。
3. 公共数字人可按平台规则使用，但仍需遵守蝉镜账号和内容规范。
4. 文生形象是生成结果，不等于已经可以当作某人的肖像去商用。

这些技能会发起出站 HTTPS 请求，并可能按接口返回的地址下载音视频。chanjing-video-compose 的 create_task.py 还支持可选 --callback，若填写回调地址，服务端可能向该地址推送任务结果，需要你自己评估可信度和可达性。

四、主练习：用公共数字人合成一段口播

示例任务是：使用公共数字人，朗读「门封条发黑别硬擦。先断电，再用适量稀释的白醋擦拭缝隙。」生成一条竖屏口播视频。不下载到本地，除非你在自己的环境里明确提出保存。不使用定制人物，也不把文档中的人物 ID 当成当前可用形象。

官方标准流程如下，步骤需要分开执行：

1. 明确形象来源是 common 还是 customised。本练习选择公共数字人。
2. 列出候选形象，并在名称、形态、分辨率、audio_man_id 和人设之间对比后再选择，禁止直接取列表最前几项。无特殊要求时，文档默认优先较年轻、较有活力的形象。
3. 使用公共数字人时，还要确认 figure_type 与所选 figures[].type 一致，文档举例包括 sit_body、whole_body、circle_view。
4. 若用文本驱动，确定 audio_man_id；官方建议它与形象提供的音色一致。
5. 在创建任务前，必须明确字幕是 `show` 还是 `hide`。 不要默认替用户决定。只有一种例外：当它被一键成片的 run_render.py 调用时，以工作流根级 subtitle_required 为准，该字段默认 false，对应隐藏字幕。
6. 用户选择显示字幕但没有提出样式或位置要求时，直接使用官方推荐默认值；只有明确要改位置或样式时，才继续补充 subtitle_config。坐标以左上角为原点，字幕区域不能超出画布。
7. 创建任务并得到 video_id，再轮询直到返回 video_url。
8. 只有在用户明确要求保存到本地时，才下载到 outputs/video-compose/。

知行之外 · mywwx.com

示例命令中的 ID 均为占位符：

python skills/chanjing-video-compose/scripts/list_figures.py --source common

VIDEO_ID=$(python skills/chanjing-video-compose/scripts/create_task.py \
  --person-id "<对比后的 person_id>" \
  --figure-type "<与该形象一致的 type>" \
  --audio-man "<对应的 audio_man_id>" \
  --subtitle "hide" \
  --text "门封条发黑别硬擦。先断电，再用适量稀释的白醋擦拭缝隙。")

python skills/chanjing-video-compose/scripts/poll_task.py --id "$VIDEO_ID"

若用户要求保留字幕且不调整样式，可把 --subtitle "hide" 改为 "show"，并采用官方推荐默认值。文档给出的 1080p 默认示例是白字，位置和尺寸为 x=31 y=1521 width=1000 height=200 font_size=64 stroke_width=7；4K 画布则使用另一组更大的默认值。不要把这些默认值理解成本文已经渲染过的字幕样式。

如果改用本地音频驱动，需要先上传音频，服务名按官方示例使用 make_video_audio，再把返回的 file_id 传给创建任务脚本。定制数字人路径不需要 figure_type，但仍要先列举并对比，不能直接套用公共库的 ID。

五、对口型路径：先上传，再创建任务

当已有授权出镜视频时，使用 chanjing-avatar。官方步骤是：获取 access_token，申请上传地址并上传文件，轮询文件详情直到可用，再创建对口型任务并查询结果。

获取上传地址时，service 对驱动视频使用 lip_sync_video，对音频驱动中的音频使用 lip_sync_audio。上传完成后，不要假定固定等待时间，而应查询文件详情，直到状态表示成功（文档示例为 status === 2），这之后才能把 file_id 用于创建任务。

创建任务时，文本驱动和音频驱动的请求体不同。文本驱动需要 tts_config（文本、音色 ID，以及可选的语速和音调）；音频驱动需要 audio_file_id。画布宽高默认 1080 和 1920。model 默认 0（基础），1 表示更高质量。这些是官方字段说明，不代表两种模型的主观效果评分。

脚本入口在 skills/chanjing-avatar/scripts/，包括申请上传地址、上传、创建任务和轮询。具体参数以该目录 SKILL.md 为准。不要把对口型任务的视频文件 ID 送给 chanjing-video-compose，也不要把合成技能的 person_id 填进对口型接口。

六、可选：文生形象后再做短口播

只有在你明确希望“先用提示词生成人物图，再做成会说话的短视频”时，才使用 chanjing-text-to-digital-person。它通常分两段异步任务：

1. create_photo_task.py 创建文生图，得到 photo_unique_id。
2. poll_photo_task.py 轮询到成功，选择一张 photo_path。
3. create_motion_task.py 创建图生视频，得到 motion_unique_id。
4. poll_motion_task.py 轮询到成功，得到 video_url。
5. 仅在明确要求保存时，才使用 download_result.py，默认目录为 outputs/text-to-digital-person/。

官方示例会填写年龄、性别、生成数量、行业、背景、外貌细节和出镜姿态，再在图生视频阶段补充情绪和手势等参数。下面只保留结构示例，不把它写成已经得到的人物图或视频：

PHOTO_TASK_ID=$(python3 skills/chanjing-text-to-digital-person/scripts/create_photo_task.py \
  --age "Young adult" \
  --gender Female \
  --number-of-images 1 \
  --industry "家庭科普" \
  --background "明亮的现代厨房" \
  --detail "短发，亲和力强，休闲家居装" \
  --talking-pose "上半身特写，站立讲解")

生成形象同样要避免去模仿未授权的真人外貌。下载仍然是显式动作：轮询成功后应先返回远端 URL，不要默认落盘。

七、验收、排错和限制

主练习（公共数字人口播）建议这样验收：

1. 已完成本地凭证检查，分享包和示例里没有真实密钥。
2. 正确选择了 chanjing-video-compose，没有误走对口型技能。
3. 形象来源明确，且经过对比后才写入 person_id 和 figure_type。
4. 创建任务前已经明确字幕开关；本示例若未要求字幕，应使用 hide。
5. 若实际调用成功，轮询返回了 video_url；未要求下载时，没有擅自保存文件。
6. 未把占位 ID、示意图或文档示例当成亲测成片。

对口型练习要额外确认：文件已上传且状态可用，视频和音频格式符合文档，所用出镜素材已授权。文生形象练习要确认：先有成功的图片任务，再创建动作任务；完整脚本都在包内。

排错时，Token 问题回到 guard；找不到形象时检查 --source 和分页；公共数字人缺少形态参数时补上 figure_type；上传后立即创建任务失败，多半是文件状态还不可用。回调地址或下载目录写错，也会让结果看起来“丢失”，其实任务可能已经在服务端完成。

这些技能都不等于一键成片：它们不负责把数字人、AI 画面和多段口播自动封装成完整混剪。本机是否安装 ffmpeg，也不影响这些脚本自身的门控，但你若要把返回视频再和别的轨道拼接，那是另外的本地工作。蝉镜账号的价格、时长和并发限制以控制台为准，本文不编造配额。

官方与原始资料

• chanjing-video-compose 官方说明
• chanjing-video-compose 参考与示例
• chanjing-avatar 官方说明
• chanjing-text-to-digital-person 官方说明
• chanjing-credentials-guard 官方说明
• chan-skills 仓库说明
• 蝉镜 Open API 登录页
• 蝉镜文件管理文档