1实现原理 · 为什么它能做到
核心知识是 2.5 时代的两大变故：不再接受 voice_label（要改用自然语言 instruction ≤200 字 + 文本内联 () 韵律指令），且审查更严（死/消失/敏感政治词触发 censorship_block）。
daymade-audio/stepfun-tts/SKILL.md
**What `stepaudio-2.5-tts` will NOT accept** — `voice_label` parameter. Error: `voice_label is not supported for v2 models`. This is the #1 migration gotcha from step-tts-2.
注：这里在做什么：把『迁移期最贵的两个坑』前置——报错原文被脚本转译成可执行提示（'HINT: stepaudio-2.5-tts does not accept voice_label. Put emotion/prosody into `instruction`…'），审查词表与改写策略在 references/migration_from_v2.md。
脚本请求 /v1/audio/speech：JSON body（model/input/voice/response_format/speed/volume + 可选 instruction），Authorization Bearer，成功直接落盘 mp3 字节。
daymade-audio/stepfun-tts/scripts/tts_generate.py
body: dict[str, Any] = { "model": MODEL, "input": text, "voice": voice, "response_format": response_format, "speed": speed, "volume": volume, }
注：API_URL = "https://api.stepfun.com/v1/audio/speech"、MODEL = "stepaudio-2.5-tts"、DEFAULT_VOICE = "shuangkuaijiejie"；instruction 存在时校验 ≤200 字符（超长返回错误不发起请求）。
instruction 长度硬校验 + 内联 () 韵律由文本透传：句内 (试探着问)/(轻声)/(停顿一下) 等括号内容被模型消费为表演指令、不朗读。
daymade-audio/stepfun-tts/scripts/tts_generate.py
if instruction: if len(instruction) > 200: return {"ok": False, "status": 0, "err": f"instruction too long: {len(instruction)} > 200 chars"}
注：SKILL.md 给出已验证示例：instruction '活泼俏皮，像是在撒娇，带点嘴硬' 明显加速语速、'耳语声，气声很重' 出气声；input '你好(停顿一下)我是蕾格(轻声)今天(加重)的天气真不错。' 内联指令全部生效。
censorship_block 的逐行降级：检测 'censorship_block'/'blocked' 标记失败行，批量模式记录跳过 ID 继续，不整批中断。
daymade-audio/stepfun-tts/scripts/tts_generate.py
censored = "censorship_block" in raw or "blocked" in raw.lower()
注：批量循环中 censored 行进 censored 列表、其余失败进 failed 列表，最后汇总输出；SKILL.md 建议混合模型兜底（该行退回 step-tts-2 也是正常的）。
批处理：--batch 读 JSONL（{id, text, instruction?} 每行一个对象），逐行合成到 --out-dir/<id>.mp3，行间 sleep delay-ms 防限流。
daymade-audio/stepfun-tts/scripts/tts_generate.py
out_path = args.out_dir / f"{line_id}.mp3" if result["ok"]: out_path.write_bytes(result["audio_bytes"])
注：read_batch 跳过空行与 # 注释行；每行可覆盖 voice/speed/volume。main() 结束按 failed 列表空否返回 0/1，censored 单独计数。
非破坏性 A/B 是设计不变式：重生成语料写并行目录（voice/zh_v25/）绝不覆盖生产语料；ab_compare.sh 用 ffprobe/stat 对比两目录 mp3 的大小与时长出 markdown 表。
daymade-audio/stepfun-tts/SKILL.md
1. **Non-destructive A/B output** — when regenerating a corpus with a new model, write to a parallel directory (`voice/zh_v25/`), never overwrite the production corpus.
注：ab_compare.sh 头注释 'compare two directories of mp3 files (size + duration)'，只比两边都有的文件，独有文件另行列出；依赖 ffprobe 与 GNU/BSD stat 双兼容。
2核心能力
01单句合成（--text/--out/--instruction/--voice/--speed/--volume）
02中/日文 1-1000 字符合成与 1000 字硬上限的语义边界切分指引
03批量语音线合成（--batch jsonl + 逐行 censorship 降级 + 行间延迟防限流）
04情绪/韵律控制：全局 instruction + 句内 () 括号指令
05step-tts-2 → 2.5 迁移手册（INSTRUCTION_MAP/SKIP_CENSORED/输出目录策略）
06双模型 A/B 对比（ab_compare.sh：ffprobe 时长 + stat 字节 + Δ% markdown 表）
07censorship 改写/兜底指引（死/消失/政治词 → 改写或该行退回 step-tts-2）
3外部依赖
| 类型 | 依赖 |
|---|---|
| network | api.stepfun.com（StepAudio TTS 端点） |
| network | platform.stepfun.com（取 key/定价/voice 文档，仅指引） |
| cli | python3（stdlib urllib，无第三方包） |
| cli | ffprobe（ffmpeg，ab_compare 用） |
4风险提醒 风险提醒：橙色 · 评估后使用
风险提醒：橙色 · 评估后使用
- 文本内容外发第三方 API — 待合成文本（含 instruction）POST 到 api.stepfun.com；若批量语料含未公开文案/剧本，属内容离机，需合规评估。
- 明文 API key 落盘 — config.json 明文存 key（或走 env）；目录权限取决于宿主，泄露面由此决定。
- 服务端审查会导致产出缺口 — 死/消失/政治词触发 censorship_block；批量中这些行只能改写或退回旧模型，可能造成语料不一致（音色/质量差异）。
- 1000 字符硬上限与时长膨胀 — 超限静默截断是已知坑（需按语义边界切分）；2.5 比 step-tts-2 慢约 20%，长批量成本与延迟需预估。
- 第三方 API 漂移与定价不透明 — 邀请 beta 期无公开稳定定价；参数/审查行为可能变化，价格引用前必须回官方页复核。
风险提醒：橙色，评估后使用。按统一分档：接触明文 API 凭证（$STEPFUN_API_KEY / ${CLAUDE_PLUGIN_DATA}/config.json）即橙色；并有网络外发（文本内容 POST 到 api.stepfun.com 官方 TTS 端点）。本地写 mp3 为用户指定输出，无破坏性操作。同 stepfun-asr：key 接触面 + 内容外发第三方，故橙色。
5第二遍独立确认
- [ok] 端点/body/模型名（/v1/audio/speech + stepaudio-2.5-tts） — tts_generate.py API_URL/MODEL 常量与 body dict 逐字存在；api_reference.md 同。
- [ok] voice_label 拒绝处理（迁移 gotcha） — 脚本对 raw 含 'voice_label is not supported' 时追加 HINT 文案；SKILL.md 错误表同描述。
- [ok] instruction ≤200 硬校验 — synthesize() 内 'if len(instruction) > 200: return {ok: False, status: 0, err: ...}' 存在，超长不发请求。
- [ok] censorship 逐行降级（不整批失败） — censored 列表单独收集、failed 汇总、循环 continue；main 返回码只按 failed 定。
- [ok] API key 解析（env → CLAUDE_PLUGIN_DATA/config.json） — load_api_key 顺序与 asr 版一致（env 优先、config 兜底、fail-fast）。
- [ok] A/B 脚本无网络、本地文件对比 — ab_compare.sh 仅 comm/stat/ffprobe；--noproxy/网络 token 零命中。
- [ok] 功能声明 vs 夸大检查（voice cloning 未验证声明） — known_issues.md 第 56 行明确 'Zero-shot voice cloning (9.9 元/音色) … was not verified in this skill's test pass'——SKILL.md 也未把克隆列为核心能力，无夸大。
- [ok] 元数据（license/stars/commit） — 仓库级 MIT、stars=1385、pushed_at=2026-09-09T12:33:29Z；本地 HEAD==pin d5c4678cb5d4fd6acc9c922690df035dbd33d247。
6结论
适合：适合：需要中/日文带情绪与句内韵律的语音合成（游戏/App 语音线、配音）；从 step-tts-2 迁移到 stepaudio-2.5-tts 的存量项目（迁移手册是主菜）；需要批量合成且容忍单行审查跳过、或做双模型 A/B 选型的团队。
不适合：不适合：无 StepFun Normal key 的用户；内容含大量审查词且不能改写、不能混用旧模型的场景（整批会被拦）；需要语音克隆的用户（该能力本 skill 未验证）；超过 1000 字符想一次合成的文本（必须语义切分）；仅需基础中性朗读、不需要情绪控制的轻量场景（可用更便宜的 step-tts-2 系）。
安装 agent 直装可复制
① 本站镜像 更新 2026-09-09
方式 A · 人下载镜像包下载 stepfun-tts.tar.gz
sha256:
方式 B · JSON 格式安装指南，复制给 agentf7fa276a8ae68d1a…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② 上游 GitHub · 原始来源
来源信息 GitHub 原始
作者 / 仓库daymade / daymade/claude-code-skills
原始 GitHubdaymade/claude-code-skills ↗
Stars1385
最近推送2026-09-09
本 skill commit
d5c4678cb5许可MIT（仓库根 LICENSE 文件；GitHub API spdx MIT；Copyright (c) 2025 daymade）
本站信息
收录日期2026-09-06
分类内容创作
侦查报告2026-09-06 · 2 遍
本站镜像与 GitHub 原始是不同来源：本站锁定 commit 快照经 /r2 分发；GitHub 为实时上游，内容可能已更新。