stepfun-tts
- Repo stars 1,187
- Forks 185
- Author updated Jun 14, 2026, 10:01 AM
- Author repo claude-code-skills
- Domain
- Other
- Compatible agents
-
- Claude Code
- Cursor
- Cline
- Codex
- Windsurf
- Gemini CLI
- +20
- Trust score
- 88 / 100 · community maintained
- Author / version / license
- @daymade · no license declared
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Required · Vendor-specific
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- No special requirements
- Permissions
-
- Read-only
- Write / modify
- Network behavior
- External requests
- Install commands
- 26 variants
Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.
Heads up: 未限定 allowed-tools,默认拥有全部工具权限。
---
name: stepfun-tts
description: Generate Chinese / Japanese speech with stepaudio-2.5-tts (released 2026-04, verified 2026-04-23…
category: other
runtime: no special runtime
---
# stepfun-tts output preview
## PART A: Task fit
- Use case: 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. requires Vendor-specific API key. Works with Claude Code, Cursor, Cline and 23 more..
- Inputs: target material, constraints, expected output, and acceptance criteria.
- Evidence boundary: follow “Config and auth / Common tasks — decision tree / Starting points” and do not present inference as author intent.
## PART B: Execution result
- **01** The card summarizes the use case; runtime output centers on “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. requires Vendor-specific API key. Works with Claude Code, Cursor, Cline and 23 more.”.
- **02** When the source has headings, the agent prioritizes “Config and auth / Common tasks — decision tree / Starting points” so the result follows the author’s structure.
- **03** Typical output includes task judgment, concrete steps, required commands or file edits, validation, and follow-up options.
- **04** Risk context follows the fingerprint: read files, write/modify files; may access external network resources; requires Vendor-specific API keys.
## Running Rules
- read files, write/modify files; may access external network resources; requires Vendor-specific API keys.
- Validate with a small sample before expanding scope.
- Return the result, validation criteria, and next iteration options. The source mentions slash commands such as `/tmp`, `/v1`; use them first when your agent supports command triggers.
Name target files or source material, expected output, forbidden changes, and whether network or shell access is allowed. Permission fingerprint: read files, write/modify files.
Start with a small task and check whether the result follows “Config and auth / Common tasks — decision tree / Starting points”. Inspect diffs, logs, previews, or tests before expanding scope.
Confirm the final output includes a concrete result, evidence, and next action. If it stays generic, tighten inputs, boundaries, and acceptance criteria.
---
name: stepfun-tts
description: Generate Chinese / Japanese speech with stepaudio-2.5-tts (released 2026-04, verified 2026-04-23…
category: other
source: daymade/claude-code-skills
---
# stepfun-tts
## When to use
- Generate Chinese / Japanese speech with stepaudio-2.5-tts (released 2026-04, verified 2026-04-23). Contextual TTS — em…
- Use it when the task has clear inputs, repeatable steps, and validation criteria.
## What to provide
- Target material, scope, expected result, and forbidden changes.
- Whether network, commands, file writes, or external services are allowed.
## Execution rules
- Organize steps around “Config and auth / Common tasks — decision tree / Starting points” and keep inference separate from source facts.
- read files, write/modify files; may access external network resources; requires Vendor-specific API keys.
- Validate with a small sample before expanding the task.
## Output requirements
- Return the deliverable, key evidence, validation method, and next action.
- Mark missing information as unknown; do not invent commands, platforms, or dependencies. The author source anchors workflow facts; repository files anchor sources and commands; Fluxly only adds fit, limitations, and quality judgment.
skill "stepfun-tts" {
input -> user goal + target files + boundaries + acceptance criteria
context -> Config and auth / Common tasks — decision tree / Starting points
rules -> SKILL.md triggers / order / output contract
runtime -> no special runtime | read files, write/modify files | may access external network resources
guardrails -> requires Vendor-specific API keys + small-sample validation + diff/log review
output -> copyable result + checklist + next iteration
} 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 thestepfun-asrskill — 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:
stepaudio-2.5-ttsrejectsvoice_label(the step-tts-2 way). Emotion/prosody now goes throughinstruction(natural-language description, ≤200 chars) and inline()parentheses inside the text itself.- Censorship is stricter — anything containing 死 / 消失 / sensitive political terms returns
censorship_block. Your rewrite options are inreferences/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):
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: readreferences/migration_from_v2.mdend-to-end before touching code. It has theINSTRUCTION_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 neutralinstruction: "耳语声,气声很重,几乎听不清"— produces audible whisper/breathinput: "你好(停顿一下)我是蕾格(轻声)今天(加重)的天气真不错。"— 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-ttsis ~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)
- 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. - 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. - 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 emitsvoice_label.
Pricing (verified 2026-04-23, volatile)
stepaudio-2.5-ttscontextual 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.
Decide Fit First
Design Intent
How To Use It
Boundaries And Review