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外部依赖

Kind	Dependency / Endpoint
network	api.stepfun.com（StepAudio TTS 端点）
network	platform.stepfun.com（取 key/定价/voice 文档，仅指引）
cli	python3（stdlib urllib，无第三方包）
cli	ffprobe（ffmpeg，ab_compare 用）

4管控建议与判定依据

建议配套管控措施

面向 Agent

分级或逐次授权，建议在沙箱运行

面向管理者

审批流程、可回滚、全程审计

判定依据（文件路径与关键语句摘要）

scripts/: 执行本地脚本或命令: daymade-audio/stepfun-tts/scripts/tts_generate.py
网络端点: 声明外部网络访问: POST https://api.stepfun.com/v1/audio/speech（请求体含待合成文本 + instruction + Auth
本地工作目录: 文件读写与工件输出: tts_generate.py 写 --out（单句）或 --out-dir/<id>.mp3（批量，mkdir parents）到用户指定路径

审计说明： 。按统一分档：接触明文 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结论

把 2.5 的破坏性变更（voice_label→instruction）与审查收紧做成完整迁移手册 + 脚本报错转译，老用户迁移成本大幅下降。

情绪/韵律控制贴近真实配音工作流：全局 instruction + 句内 () 括号指令，示例都带 2026-04-23 实测效果。

批处理抗单行失败：censorship 降级 + 混合模型兜底被设计为正常路径而非异常。

非破坏 A/B 不变式保护生产语料，配 ab_compare 出可粘贴的对比表。

诚实标注边界：价格 volatile、voice cloning 未实测、时长膨胀/审查已知问题都写进 references，不给 stakeholder 报假数。

适合： 适合：需要中/日文带情绪与句内韵律的语音合成（游戏/App 语音线、配音）；从 step-tts-2 迁移到 stepaudio-2.5-tts 的存量项目（迁移手册是主菜）；需要批量合成且容忍单行审查跳过、或做双模型 A/B 选型的团队。

不适合： 不适合：无 StepFun Normal key 的用户；内容含大量审查词且不能改写、不能混用旧模型的场景（整批会被拦）；需要语音克隆的用户（该能力本 skill 未验证）；超过 1000 字符想一次合成的文本（必须语义切分）；仅需基础中性朗读、不需要情绪控制的轻量场景（可用更便宜的 step-tts-2 系）。

Install Agent-Ready

① Verified Mirror 2026-09-09

Option A · Direct DownloadDownload stepfun-tts.tar.gz

sha256: f7fa276a8ae68d1a…

Option B · Copy Guide for Agent

install.json

agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。

② Upstream GitHub

GitHub Repo ↗

Pinned to commit d5c4678cb5.