stepfun-tts

StepFun 上下文 TTS（默认使用 stepaudio-2.5-tts）

使用 StepFun 的上下文 TTS 生成中文 / 日语语音——通过自然语言描述传递情绪和韵律，而非使用固定标签。默认模型为 stepaudio-2.5-tts（随附脚本使用的模型）：在 2026-09-16 针对我们自己的案例进行的盲测 A/B 对比中，2.5 在中性 / 娇俏 / 活泼少女这几组中以 3:2 获胜。如果台词需要耳语或大量内嵌 () 韵律标记，则选择 stepaudio-3-tts——v3 恰好在这两组中获胜；v3 还将 instruction 上限提高到 500 个字符（2.5 为 200）。⚠️ 绝不要使用 v3 合成复刻音色——v3 语音接受复刻音色 ID 而不报错，但会静默回退到默认女声。根因 = 阶跃复刻链路整体停留在 2.5 系列（复刻创建 API 只接受 2.5/step-tts-2/step-tts-mini，不包括 v3；v3 合成侧的复刻功能尚未发布）。在 v3 上，两代创建的克隆音色都会失效：step-tts-2 克隆 SIM 为 0.272，2.5 创建的新克隆 SIM 为 0.195（锚点为 0.773），而在 2.5 上，同一 ID 的 SIM 分别为 0.743/0.678。

配套技能：若要使用配套模型 stepaudio-3-asr-max 转录，请使用 stepfun-asr 技能——二者共用一个 API 密钥，但使用不同的端点，且请求体格式不同。

此技能存在的原因——有两个不太明显的陷阱，如果不了解，可能会耗费数小时：

1. stepaudio-3-tts 不接受 voice_label（step-tts-2 的用法）——已于 2026-09-16 在 v3 上验证：HTTP 400 voice_label is not supported for this model。情绪 / 韵律需通过 instruction（自然语言描述；v3 上限为 500 个字符，2.5 的上限为 200 个字符）以及文本中的内嵌 () 括号传递。
2. 审查行为因模型版本而异——在 2026-09-16 的单样本探测中，2.5 时代的触发词列表（死 / 消失 / 敏感政治术语 → censorship_block）在 v3 上没有触发；请假定审查机制仍然存在，但在构建改写映射前，应逐个重新验证触发词。2.5 时代的选项见 references/migration_from_v2.md。

配置和身份验证

API 密钥位于 $STEPFUN_API_KEY（优先）或 ${CLAUDE_PLUGIN_DATA}/config.json（回退，用于跨会话持久保存）。所有随附脚本都会先尝试环境变量，再尝试配置文件。

首次设置（一行命令）：

mkdir -p "${CLAUDE_PLUGIN_DATA}" && cat > "${CLAUDE_PLUGIN_DATA}/config.json" <<EOF
{"api_key": "<paste key here>"}
EOF

如果用户尚未设置密钥，请让他们粘贴密钥（不要猜测 / 不要使用占位符）。可前往 https://platform.stepfun.com/ → API Keys 获取 StepFun API 密钥。请使用 Normal 密钥，而非 Plan 密钥（Plan 密钥仅限文本模型，在音频端点上会静默失败）。

常见任务——决策树

用户需求……	脚本	关键细节
合成 1–500 个字符的中文并添加情绪	scripts/tts_generate.py	使用 instruction 设置情绪，使用 () 添加内嵌韵律
合成长文本（500–1000 个字符）	scripts/tts_generate.py	硬性上限为 1000 个字符；超过上限时，按语义边界拆分
批量生成游戏 / 应用语音台词	scripts/tts_generate.py --batch <jsonl>	分别处理 censorship_block 回退
对比两个 TTS 模型的 A/B 效果	scripts/ab_compare.sh	对比两个目录中的时长 / 大小
从 step-tts-2 / stepaudio-2.5-tts 迁移	参见 references/migration_from_v2.md	将 voice_label.emotion 改写为 instruction，并参考 2.5 时代的审查词列表

入门指南

• 合成单句语音：运行 python3 scripts/tts_generate.py --text "你好" --out /tmp/hello.mp3 --instruction "温暖的希望感"。如需精细控制，请阅读下文的“上下文 TTS”部分。
• 从代码调用：此脚本是 llm-registry 中该端点的封装——llmreg.wrapper_for("stepfun-tts").tts_generate.synthesize(api_key=…, text=…, model=…, extra={…})。extra 会原样合并到请求正文中；使用 {"timestamp": True, "return_url": True} 时，服务会返回 JSON 封装（{"data": {"url", "subtitles"}}），结果会放在 json 中，而不是 audio_bytes（已于 2026-09-19 验证）。参数不会计费——按需传入即可。其他地方直接调用 /v1/audio/speech 会被 llm-entry-guard hook 拦截。
• 完整迁移：从 step-tts-2 迁移到上下文 TTS 前，请从头到尾阅读 references/migration_from_v2.md。其中包含 INSTRUCTION_MAP、SKIP_CENSORED 列表模式，以及用于非破坏性 A/B 测试的输出目录策略（针对 2.5 编写；v3 的迁移机制完全相同）。

上下文 TTS——不止是情绪标签

stepaudio-3-tts 的核心特性是：不再将情绪映射到固定标签，而是开始用自然语言描述期望效果。分为两层：

全局上下文（instruction 参数）——设定整段语音的整体语气。v3 最多支持 500 个字符（2.5 为 200 个字符；已于 2026-09-16 验证 v3 接受 300 字符的指令）。可以把它想象成给配音演员的舞台指示。

instruction: "克制的悲伤，语气低沉柔弱，像快要消失一样"

内联上下文（input 中的 () 括号）——句内指令。括号中的内容会作为指示处理，不会被朗读出来。可用于精确控制停顿、呼吸、重音或句中情绪变化。

input: "(试探着问)你好吗？(开心地)太好了！(突然沉下来)不过...我快要消失了。"

实践中有效的示例（已于 2026-04-23 在 2.5 上验证；其中五个示例已于 2026-09-16 在 v3 上重新验证，包括这些指令和内联韵律示例）：

• instruction: "活泼俏皮，像是在撒娇，带点嘴硬"——与中性语气相比，语速明显加快
• instruction: "耳语声，气声很重，几乎听不清"——会产生听得见的耳语和气声
• input: "你好(停顿一下)我是蕾格(轻声)今天(加重)的天气真不错。"——所有内联指令均得到遵循

stepaudio-3-tts 不接受的参数——voice_label。v3 上的错误为：voice_label is not supported for this model（2.5 上显示 ...for v2 models）。这是从 step-tts-2 迁移时最容易踩的坑。

常见错误模式（真实错误，真实修复方法）

错误响应	实际原因	修复方法
"voice_label is not supported for this model"（v3）/ "...for v2 models"（2.5）	向上下文 TTS 模型发送了 voice_label	移除 voice_label；将相同意图用自然语言写入 instruction
"The content you provided or machine outputted is blocked." type: censorship_block	包含敏感词（2.5 时期：死 / 消失 / 等；v3 触发词尚未验证）	改写短语，或针对该句改用 step-tts-2（混用模型没有问题）
音频无提示地截断（输入超过 1000 个字符）	超出硬性上限	按语义边界拆分；不要在句子中间截断

更多信息请参阅 references/known_issues.md。

何时阅读参考资料

• references/api_reference.md——/v1/audio/speech 的准确请求／响应 JSON、所有字段及错误响应。编写原始 HTTP 调用而非使用捆绑脚本时请阅读。
• references/migration_from_v2.md——将 step-tts-2 项目迁移到上下文 TTS 的完整操作指南。包含情绪→指令改写表、A/B 目录策略、决策检查点，以及 2026-04 的速度／质量权衡数据（针对 2.5 编写）。开始任何迁移工作前请阅读。
• references/known_issues.md——内容审查模式、TTS 时长膨胀、v2 系列参数命名陷阱，以及 1000 字符硬性上限。验证基于 2.5 时期；依赖具体条目之前，请先在 v3 上重新验证。调试异常输出或评估是否采用时请阅读。

设计不变量（不要破坏）

1. 非破坏性 A/B 输出 — 使用新模型重新生成语料时，写入并行目录（voice/zh_v3/），绝不覆盖生产语料。迁移操作手册说明了原因。
2. 逐行处理审查拦截 — 如果 29 行中有 2 行触发 censorship_block，不要让整个批次失败。记录被跳过的 ID，然后继续。对被跳过的 2 行使用混合模型回退（step-tts-2）属于正常做法。
3. 不要在新代码中重复实现 voice_label 逻辑 — 任何面向 stepaudio-3-tts 的新增 TTS 代码都只能使用 instruction + 行内 ()。不要编写按条件输出 voice_label 的分支。

v3 特有信息（已于 2026-09-16 验证）

• 官方音色：通过 GET /v1/audio/system_voices?model=stepaudio-3-tts 可获取 60 多种音色 — 完整继承了 2.5 的音色列表，并新增了音色（例如，英文名的 Lisa/Alfie，以及上海话音色 shanghaifemale/shanghaimale）。
• 克隆（复刻）音色：不要使用 stepaudio-3-tts — 根本原因已于 2026-09-16 查明：StepFun 的整个克隆技术栈仍属于 2.5 系列。创建 API（POST /v1/audio/voices）仅接受 stepaudio-2.5-tts / step-tts-2 / step-tts-mini；v3 /v1/audio/speech 会对任何克隆 ID 静默回退到默认女声 — SIM 为 0.272（step-tts-2 克隆）和 0.195（新创建的 2.5 克隆），而参照值为 0.773；同一 ID 在 2.5 上的得分为 0.743/0.678。请使用 stepaudio-2.5-tts（SIM 最佳）或 step-tts-2 合成克隆音色。
• v3 不支持 WebSocket 流式传输（截至 2026-09-16）：wss://api.stepfun.com/v1/realtime/audio?model=stepaudio-3-tts 在握手时被拒绝（404），而 2.5 仍可在该地址进行流式传输。v3 需要字符级字幕时间戳？请使用 REST timestamp:true + return_url:true（字幕会出现在响应 JSON 的 data.subtitles[] 中，精确到字符，单位为毫秒，采用累积绝对时间轴）— 单独使用 stream_format:"audio" 无法携带字幕（服务器返回 400）。

定价（已于 2026-09-16 验证，价格可能变动）

• stepaudio-3-tts 合成：2.5 元 / 万字符（官方模型页面，2026-09-16 — 低于 2.5 时代约 5.8 元的价格）
• 零样本音色克隆：9.9 元 / 音色

向利益相关方报价前，请在 https://platform.stepfun.com/docs/zh/guides/pricing/details 重新核实。