步步
- 作者仓库星标 0
- 作者更新于 2026年8月24日 07:33
- 作者仓库 claude-code-skills
- 领域
- 通用
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @daymade · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 需要 · Vendor-specific
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# StepFun stepaudio-2.5-tts
Generate Chinese / Japanese speech with `stepaudio-2.5-tts` (released 2026-04, verified 2026-04-23). Contextual TTS — emotion and prosody go through natural-language description, not fixed labels.
> Companion: for transcription with `stepaudio-2.5-asr` (the sibling model), use the `stepfun-asr` skill — they share an API key but live on different endpoints with different body shapes.
**Why this skill exists** — StepAudio 2.5 has two non-obvious pitfalls that cost hours if you don't know them:
1. `stepaudio-2.5-tts` **rejects** `voice_label` (the step-tts-2 way). Emotion/prosody now goes through `instruction` (natural-language description, ≤200 chars) and inline `()` parentheses inside the text itself.
2. Censorship is stricter — anything containing 死 / 消失 / sensitive political terms returns `censorship_block`. Your rewrite options are in `references/migration_from_v2.md`.
## Config and auth
API key lives in `$STEPFUN_API_KEY` (preferred) or `${CLAUDE_PLUGIN_DATA}/config.json` (fallback for cross-session persistence). All bundled scripts try env first, then config.
First-time setup (one-liner):
```bash
mkdir -p "${CLAUDE_PLUGIN_DATA}" && cat > "${CLAUDE_PLUGIN_DATA}/config.json" <<EOF
{"api_key": "<paste key here>"}
EOF
```
If the user hasn't set a key, ask them to paste it (don't guess / don't use a placeholder). StepFun API keys are available at https://platform.stepfun.com/ → API Keys. **Use a Normal key, not a Plan key** (Plan keys are restricted to text models and silently fail on audio endpoints).
## Common tasks — decision tree
| User wants... | Script | Key detail |
|---|---|---|
| Synthesize 1–500 char Chinese with emotion | `scripts/tts_generate.py` | Use `instruction` for mood, `()` for inline prosody |
| Synthesize long text (500–1000 char) | `scripts/tts_generate.py` | 1000 char is the hard cap; split at semantic boundaries above that |
| Batch-generate game/app voice lines | `scripts/tts_generate.py --batch <jsonl>` | Handle `censorship_block` fallback individually |
| A/B compare two TTS models | `scripts/ab_compare.sh` | Compares duration/size across two directories |
| Migrate from `step-tts-2` | see `references/migration_from_v2.md` | `voice_label.emotion` → `instruction` rewrite + censorship list |
## Starting points
- **Synthesize a single line**: Run `python3 scripts/tts_generate.py --text "你好" --out /tmp/hello.mp3 --instruction "温暖的希望感"`. For fine-grained control read the "Contextual TTS" section below.
- **A full migration** from `step-tts-2` → `stepaudio-2.5-tts`: read `references/migration_from_v2.md` end-to-end before touching code. It has the `INSTRUCTION_MAP`, the SKIP_CENSORED list pattern, and the output-directory-strategy for non-destructive A/B.
## Contextual TTS — beyond emotion labels
The headline feature of `stepaudio-2.5-tts` is that you stop mapping emotions to fixed tags and start describing what you want in natural language. Two layers:
**Global context (`instruction` parameter)** — sets the overall tone for the entire utterance. ≤200 chars. Think of it like giving stage direction to a voice actor.
```
instruction: "克制的悲伤,语气低沉柔弱,像快要消失一样"
```
**Inline context (`()` parentheses inside `input`)** —句内 directives. Parenthesised content is consumed as directions and is NOT read aloud. Use for precise control of pauses, breath, emphasis, or mid-sentence emotion shifts.
```
input: "(试探着问)你好吗?(开心地)太好了!(突然沉下来)不过...我快要消失了。"
```
Examples that worked in practice (from 2026-04-23 verification):
- `instruction: "活泼俏皮,像是在撒娇,带点嘴硬"` — visibly speeds up delivery vs neutral
- `instruction: "耳语声,气声很重,几乎听不清"` — produces audible whisper/breath
- `input: "你好(停顿一下)我是蕾格(轻声)今天(加重)的天气真不错。"` — inline directives all respected
**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.
## Common error patterns (real errors, real fixes)
| Error response | Actual cause | Fix |
|---|---|---|
| `"voice_label is not supported for v2 models"` | Sent `voice_label` to `stepaudio-2.5-tts` | Remove `voice_label`; put the same intent into `instruction` as natural language |
| `"The content you provided or machine outputted is blocked." type: censorship_block` | Sensitive word (死 / 消失 / etc.) | Rewrite the phrase OR fall back to `step-tts-2` for that specific line (mixed-model is fine) |
| Silent audio truncation (input > 1000 chars) | Hard cap exceeded | Split at semantic boundaries; don't truncate mid-sentence |
More in `references/known_issues.md`.
## When to read references
- `references/api_reference.md` — exact request/response JSON for `/v1/audio/speech`, all fields, error responses. Read when writing raw HTTP calls instead of using the bundled scripts.
- `references/migration_from_v2.md` — complete playbook for moving a step-tts-2 project to stepaudio-2.5-tts. Has the emotion→instruction rewrite table, the A/B directory strategy, decision checkpoints, and the 2026-04 speed/quality trade-off data (`stepaudio-2.5-tts` is ~20% slower than step-tts-2; audible prosody improvement). Read before any migration work.
- `references/known_issues.md` — censorship patterns, TTS duration inflation, v2-family parameter naming gotcha, 1000-char hard cap. Read when debugging anomalous output or evaluating whether to adopt.
## Design invariants (don't break these)
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. The migration playbook shows why.
2. **Per-line censorship handling** — if 2/29 lines get `censorship_block`, don't fail the batch. Log the skipped IDs, continue. Mixed-model fallback (step-tts-2 for the skipped 2) is normal.
3. **Don't duplicate voice_label logic in new code** — any new TTS code targeting stepaudio-2.5-tts should only use `instruction` + inline `()`. Do not write a branch that conditionally emits `voice_label`.
## Pricing (verified 2026-04-23, volatile)
- `stepaudio-2.5-tts` contextual synthesis: ~5.8 元 / 万字符
- Zero-shot voice cloning: ~9.9 元 / 音色
Re-verify at https://platform.stepfun.com/docs/zh/guides/pricing/details before quoting to stakeholders.
章节与文件索引
按说明文件中的顺序排列。
配置和授权
常见任务——决策树
起点
上下文 TTS — 超越情感标签
常见错误模式(真实错误、真实修复)
文件/命令 -> stepaudio-2.5-tts · stepaudio-2.5-asr · stepfun-asr · voice_label · instruction · censorship_block · references/migration_from_v2.md · $STEPFUN_API_KEY
内容校验值 -> fb87e6f44191
当前原文的自动摘译,尚未人工审校。
配置和授权
API 密钥位于
$STEPFUN_API_KEY(首选)或${CLAUDE_PLUGIN_DATA}/config.json(跨会话持久性的后备)中。所有捆绑的脚本首先尝试 env,然后是 config。首次设置(单行):如果用户尚未设置密钥,请要求他们粘贴它(不要猜测/不要使用占位符)。 StepFun API 密钥可在 https://platform.stepfun.com/ → API 密钥获取。使用普通键,而不是计划键(计划键仅限于文本模型,并且在音频端点上静默失败)。常见任务——决策树
用户想要... · 脚本 · 关键细节 合成 1–500 个字符的有情感的中文 ·
scripts/tts_generate.py· 使用instruction表示情绪,()表示行内韵律 合成长文本(500–1000 字符) ·scripts/tts_generate.py· 1000 字符为硬上限;在语义边界上方进行分割 批量生成游戏/应用程序语音线 ·scripts/tts_generate.py --batch <jsonl>· 单独处理censorship_block回退起点
合成一行:运行
python3 scripts/tts_generate.py --text "你好" --out /tmp/hello.mp3 --instruction "温暖的希望感"。要进行细粒度控制,请阅读下面的“上下文 TTS”部分。从step-tts-2→stepaudio-2.5-tts的完整迁移:在接触代码之前端到端地阅读references/migration_from_v2.md。它具有INSTRUCTION_MAP、SKIP_CENSORED 列表模式以及用于非破坏性 A/B 的输出目录策略。上下文 TTS — 超越情感标签
stepaudio-2.5-tts的主要特点是你不再将情感映射到固定标签上,而是开始用自然语言描述你想要的东西。两层:全局上下文(instruction参数)——设置整个话语的整体基调。 ≤200 个字符。可以把它想象成给配音演员提供舞台指导。内联上下文(()括号内input)—句内指令。括号内的内容作为指示使用,不会大声朗读。用于精确控制停顿、呼吸、重音或句子中间的情绪变化。常见错误模式(真实错误、真实修复)
错误响应·实际原因·修复
"voice_label is not supported for v2 models"·发送voice_label至stepaudio-2.5-tts·删除voice_label;将相同的意图放入instruction作为自然语言"The content you provided or machine outputted is blocked." type: censorship_block·敏感词(死/消失/等)·重写短语或针对该特定行退回到step-tts-2(混合模型很好)