给短视频或口播准备旁白时，常见需求是：先从平台公共音色里选一个合适的声音，把稿件合成音频，并拿到可以对照画面的时间戳。蝉镜 TTS Skill 做的就是这件事。如果你还希望使用自己的声音，仓库里另有可选技能 chanjing-tts-voice-clone；它要求参考音频是可公开访问的地址，并且只应用于本人或已授权素材。

本文介绍同一仓库中的 chanjing-tts，并附带说明可选的 chanjing-tts-voice-clone。练习任务是为一段虚构的冰箱清洁口播生成公共音色音频；克隆部分只讲流程和限制，不把它写成必须完成的步骤。本文核对了官方 SKILL.md 与仓库 README，没有实际运行这些脚本，也没有使用真实密钥调用 API。文中的命令和返回字段都来自官方文档，示例结果不冒充实测录音。

一、这个 Skill 做什么，不做什么

chanjing-tts 调用蝉镜 TTS Open API：列出公共音色、创建合成任务、轮询任务状态，再根据接口返回的 URL 下载音频。官方说明它支持中文和英文、多种系统音色、语速调节，以及结果中的句级时间戳。脚本本身不依赖 ffmpeg 或 ffprobe，也不负责把音频剪进视频，或发布到抖音等平台。

它适合“把已经定稿的文本变成语音”。若你的目标是一条带数字人和画面的完整短视频，应使用一键成片技能，由它在内部编排 TTS，而不是把本文当成完整成片方案。若你需要的是对口型或数字人出镜，也应转到对应的数字人技能。

可选的 chanjing-tts-voice-clone 不是默认路径。它先用参考音频创建定制音色，再调用与公共 TTS 类似的合成接口。参考音频必须是蝉镜服务器能够拉取的公网 URL，官方要求格式为 mp3、wav 或 m4a（文档同时列出了若干可接受的 MIME 类型），大小不超过 100MB，建议时长 30 秒到 5 分钟。声音克隆只用于本人或已明确授权的素材，不能拿未授权的第三人声音做参考。

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

官方目录分别是 skills/chanjing-tts/ 与 skills/chanjing-tts-voice-clone/。本站蝉镜教程共用同一个完整源码包，版本为 cf3714fd（2026-10-22 源码快照），对应提交 cf3714fde137ca5cadd191dd2db1a4a8be601c85。这不是单独为 TTS 重新制作的新包，也不是 2026-03-28 的旧 tag v1.0.1。

解压后核对这些路径：

chan-skills-cf3714fd/
  README.md
  README.zh-CN.md
  使用说明.txt
  skills/chanjing-credentials-guard/SKILL.md
  skills/chanjing-tts/SKILL.md
  skills/chanjing-tts/scripts/list_voices.py
  skills/chanjing-tts/scripts/create_task.py
  skills/chanjing-tts/scripts/poll_task.py
  skills/chanjing-tts-voice-clone/SKILL.md

仓库未标注许可证。分享包中不应包含 credentials.json。目录存在不等于音色列表已经拉到本地，也不等于账号仍有可用额度。具体价格和时长配额以蝉镜控制台当时显示为准，本文不编造。

三、先完成凭据守卫，再准备调用环境

执行 TTS 或声音克隆前，必须先通过 chanjing-credentials-guard 完成 AK/SK 与 Token 校验。两个语音技能与 guard 使用同一份 ~/.chanjing/credentials.json。没有凭证时，脚本可能打开登录页 https://www.chanjing.cc/openapi/login，并提示你在本机终端配置，而不是在对话里粘贴密钥。

配置和检查命令与一键成片相同：

python skills/chanjing-credentials-guard/scripts/chanjing_config.py --ak <your_app_id> --sk <your_secret_key>
python skills/chanjing-credentials-guard/scripts/chanjing_config.py --status

接口主机名为 https://open-api.chanjing.cc，请求和响应都使用 JSON，文本按 UTF-8 处理。官方说明 access_token 大约一天有效，新 Token 会使旧 Token 失效。环境变量方面，可用 CHANJING_OPENAPI_CREDENTIALS_DIR 和 CHANJING_OPENAPI_BASE_URL，并兼容旧名 CHANJING_CONFIG_DIR、CHANJING_API_BASE。

如果通过官方安装器加载单个技能，示例命令是：

npx skills add chanjing-ai/chan-skills --skill chanjing-tts -y

需要可选克隆能力时，再按同样方式安装 chanjing-tts-voice-clone，或直接使用本站提供的完整源码包。这些安装命令在本文制作过程中没有执行。

四、用公共音色做一段示例旁白

练习任务可以设定为：为虚构口播「门封条发黑别硬擦。先断电，再用适量稀释的白醋擦拭缝隙。」生成一段中文语音。要求使用公共音色，不读取或上传任何人的私有录音，也不把返回示例写成已经下载成功的音频文件。

官方推荐的脚本顺序分为三步。

第一步，列出公共音色，根据名称、性别和试听信息选择，不要未比较就使用列表第一项。方言或口音往往可以从音色名称里判断。

python skills/chanjing-tts/scripts/list_voices.py

需要完整字段时，可加官方提供的 --json。文档示例里出现过名为「带货小芸」的音色，那只是接口返回示例，实际使用前仍要重新列举并对比，不要把文档里的 ID 当成长期有效的固定值。

第二步，创建合成任务。audio_man 为音色 ID，text 为待合成文本，官方要求文本长度小于 4000 字。speed 范围是 0.5（慢）到 2（快），pitch 文档写明按 1 设置。可选参数 aigc_watermark 表示是否给音频加可见水印，默认 false。

TASK_ID=$(python skills/chanjing-tts/scripts/create_task.py \
  --audio-man "<list_voices 对比后的音色 ID>" \
  --text "门封条发黑别硬擦。先断电，再用适量稀释的白醋擦拭缝隙。")

第三步，用返回的 task_id 轮询，直到任务完成并得到音频下载地址：

python skills/chanjing-tts/scripts/poll_task.py --task-id "$TASK_ID"

官方轮询接口里，status 为 1 表示正在生成，为 9 表示完成。完成时应检查 full.url、full.duration 以及 subtitles 中的 start_time、end_time 和 subtitle 文本。这些时间戳可以辅助后续字幕或切镜，但它们是接口字段说明，不是本教程已经拿到的真实结果。

示意图：蝉镜公共音色配音从校验凭证、列举音色到轮询下载的步骤

如果自己调用 HTTP 接口，而不是脚本，官方顺序同样是：获取 access_token，列举 /open/v1/list_common_audio，向 /open/v1/create_audio_task 提交任务，再轮询 /open/v1/audio_task_state。请求失败时，文档列出了参数错误、Token 校验失败、超过 QPS，以及“制作时长达到限制”等状态码。遇到额度或频率限制时，应回到控制台查看当时规则，而不是在教程里填写一个未核实的上限数字。

五、可选：已授权参考音的声音克隆

只有在你明确需要“用自己的声音朗读稿件”，并且参考音频来源合法时，才使用 chanjing-tts-voice-clone。不要把这一节当成公共音色流程的必选后续。

官方流程是：

  1. 准备可公开访问的参考音频 URL，格式和大小符合文档要求。
  2. 用 create_voice.py 创建定制音色，文档要求 model_type 使用 Cicada3.0-turbo；语言可选 cn 或 en，默认 cn。
  3. 用 poll_voice.py 轮询，直到音色就绪。文档中 status 的含义包括：0 排队、1 进行中、2 完成、3 过期、4 失败、99 已删除。轮询可能需要几分钟。
  4. 把得到的音色 ID 作为 audio_man，再调用 create_task.py 和 poll_task.py 合成语音。

示例命令如下，URL 必须换成你自己有权使用的地址：

VOICE_ID=$(python skills/chanjing-tts-voice-clone/scripts/create_voice.py \
  --name "我的声音" \
  --url "https://example.com/ref.mp3")

python skills/chanjing-tts-voice-clone/scripts/poll_voice.py --voice-id "$VOICE_ID"

TASK_ID=$(python skills/chanjing-tts-voice-clone/scripts/create_task.py \
  --audio-man "$VOICE_ID" \
  --text "门封条发黑别硬擦。先断电，再用适量稀释的白醋擦拭缝隙。")

python skills/chanjing-tts-voice-clone/scripts/poll_task.py --task-id "$TASK_ID"

如果参考音频格式不被接受，轮询结果里可能出现错误说明，例如官方示例中的“不支持的音频格式，请阅读接口文档”。此时应检查文件格式、MIME 类型和是否真的可被公网访问，而不是反复提交同一条无效链接。

不要在聊天里发送参考音频里的私人内容密钥；也不要把定制音色 ID 连同账号凭证一起写入分享包。克隆得到的是可复用的音色标识，不等于已经获得可任意商用的授权证明。授权范围、账号套餐和是否允许用于特定平台，仍要按蝉镜当时规则和你自己的素材授权来判断。

示意图：声音克隆是可选路径，仅用于本人或已授权参考音

六、验收和排错

公共音色练习的验收，建议按下面的清单逐项标记“已检查”或“待测”：

  1. 已通过 guard 完成本地凭证检查，对话中没有出现完整 AK/SK。
  2. 先列举音色再选择，选择理由能对应名称、语言或试听信息。
  3. 提交文本少于 4000 字；speed 落在 0.5 到 2，pitch 按文档设为 1。
  4. 若实际调用成功，任务状态最终为 9，且返回了 full.url。
  5. 下载音频后，聆听内容与稿件一致，并抽查时间戳是否与句子对应。
  6. 没有把这次示例写成“已实测的音质评分”或具体价格。

若走可选克隆，额外检查：参考音来源合法、URL 可访问、格式和大小符合文档、音色状态为 2 后再合成，以及参考音未进入本文使用的公共下载包。

常见失败可以这样处理：Token 失败时重新走 guard；参数错误时核对 audio_man 和文本长度；QPS 或制作时长限制按控制台提示等待或调整；下载失败时记录返回的 URL 和错误信息，不改用来路不明的第三方镜像。列出的音色与文档示例不一致是正常现象，以你当前接口返回为准。

七、限制和维护

TTS 技能提供的是音频生成能力，不包含视频封装、字幕烧录或平台发布。接口返回的句级时间戳可以帮助后续对齐，但不是自动生成的成品字幕文件。文本过长时，一键成片有自己的分批合并规则；单独使用 TTS 时，应遵守小于 4000 字的限制，超长稿件需要你自行分段并在本地拼接，这一步已超出本技能脚本的默认职责。

维护时重点关注：官方脚本参数是否变化、音色列表是否更新、Token 刷新方式，以及声音克隆的格式和时长要求。仓库未标注许可证，二次分发要自行确认。更新下载包时，应继续使用可核对的 commit 或官方正式版本，不虚构版本号，也不把旧 tag 说成当前快照。

官方与原始资料