SkillAgentSearch skills...

stepfun-tts

Generates Chinese/Japanese speech with StepFun's Contextual TTS — default stepaudio-2.5-tts, stepaudio-3-tts for whisper/inline-() prosody. Replaces step-tts-2's voice_label with natural-language instruction.

Install / Use

npx skills add daymade/claude-code-skills --skill stepfun-tts

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

90/100

Category

Other

Supported Platforms

Universal

Our assessment of stepfun-tts

stepfun-tts scores 90/100 on our quality scale, 98th of 329 Other skills we index (top 30%).

Its SKILL.md is 9.6 KB long, well organised into 10 sections with 3 code examples: a thorough specification that gives an agent plenty to work with.

With 1,426 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
29/30
Structure
18/20
Description
15/15
Adoption
13/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so stepfun-tts is actively maintained.
  • Our last check on 2026-10-30 found the source still online.
  • It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-10-03. Automated pattern scan on 2026-10-03. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

stepfun-tts compared with similar skills

All 4 of these similar skills score higher than stepfun-tts; compare them before choosing.

SkillScoreStarsUpdatedFormat
stepfun-tts (this skill)by daymade901.4k53d agoSKILL.md
LocalAIby mudler10050.4ktodayMCP Server
x402by browser-use100121.0k3d agoSKILL.md
algorithmic-artby anthropics100177.9k55d agoSKILL.md
pptxby anthropics100177.9k55d agoSKILL.md

Frequently asked questions

How do I install stepfun-tts?
Run npx skills add daymade/claude-code-skills --skill stepfun-tts. The install tabs above show the steps for each supported agent.
Which AI agents does stepfun-tts work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is stepfun-tts safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is stepfun-tts still maintained?
The repository was last updated about 2 months ago, so stepfun-tts is actively maintained.

name: stepfun-tts disable-model-invocation: true description: >- Generates Chinese/Japanese speech with StepFun's Contextual TTS — default stepaudio-2.5-tts, stepaudio-3-tts for whisper/inline-() prosody. Replaces step-tts-2's voice_label with natural-language instruction. Use for emotional/prosody-controlled synthesis, batch voice lines, migrating from step-tts-2, or cloned voices (2.5/step-tts-2, not v3). Triggers on 阶跃 TTS, 语音合成, 配音. Not for transcription (use stepfun-asr).

StepFun Contextual TTS (default stepaudio-2.5-tts)

Generate Chinese / Japanese speech with StepFun's Contextual TTS — emotion and prosody go through natural-language description, not fixed labels. Default model is stepaudio-2.5-tts (what the bundled script uses): in a 2026-09-16 blind A/B on our own cases, 2.5 won the neutral / jiao / lively-girl pairs 3:2. Pick stepaudio-3-tts when the line is whisper or heavy inline-() prosody — v3 won exactly those two pairs; v3 also raises the instruction cap to 500 chars (2.5 is 200). ⚠️ Never synthesize cloned voices with v3 — v3 speech 接受复刻音色 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 0.743/0.678。

Companion: for transcription with stepaudio-3-asr-max (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 — two non-obvious pitfalls that cost hours if you don't know them:

  1. stepaudio-3-tts rejects voice_label (the step-tts-2 way) — verified on v3 2026-09-16: HTTP 400 voice_label is not supported for this model. Emotion/prosody goes through instruction (natural-language description, ≤500 chars on v3 — 200 was the 2.5 limit) and inline () parentheses inside the text itself.
  2. Censorship behavior is model-version-specific — the 2.5-era trigger list (死 / 消失 / sensitive political terms → censorship_block) did not fire on v3 in a 2026-09-16 single-sample probe; treat censorship as present but re-verify per trigger before building rewrite maps. The 2.5-era 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):

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 / stepaudio-2.5-tts | see references/migration_from_v2.md | voice_label.emotion → instruction rewrite + 2.5-era 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.
  • From code: this script is the endpoint's wrapper in llm-registry — llmreg.wrapper_for("stepfun-tts").tts_generate.synthesize(api_key=…, text=…, model=…, extra={…}). extra is merged into the request body as-is; with {"timestamp": True, "return_url": True} the server answers a JSON envelope ({"data": {"url", "subtitles"}}) that comes back under json instead of audio_bytes (verified 2026-09-19). Parameters are not billed — send what you need. Direct /v1/audio/speech calls elsewhere are blocked by the llm-entry-guard hook.
  • A full migration from step-tts-2 → Contextual 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 (written for 2.5; the migration mechanics are identical on v3).

Contextual TTS — beyond emotion labels

The headline feature of stepaudio-3-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. ≤500 chars on v3 (2.5 was 200; a 300-char instruction verified accepted on v3 2026-09-16). 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 (verified 2026-04-23 on 2.5; all five re-verified on v3 2026-09-16, including these instruction and inline-prosody cases):

  • instruction: "活泼俏皮,像是在撒娇,带点嘴硬" — visibly speeds up delivery vs neutral
  • instruction: "耳语声,气声很重,几乎听不清" — produces audible whisper/breath
  • input: "你好(停顿一下)我是蕾格(轻声)今天(加重)的天气真不错。" — inline directives all respected

What stepaudio-3-tts will NOT accept — voice_label parameter. Error on v3: voice_label is not supported for this model (2.5 said ...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 this model" (v3) / "...for v2 models" (2.5) | Sent voice_label to a Contextual TTS model | 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 (2.5-era: 死 / 消失 / etc.; v3 triggers unverified) | 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 Contextual TTS. Has the emotion→instruction rewrite table, the A/B directory strategy, decision checkpoints, and the 2026-04 speed/quality trade-off data (written against 2.5). Read before any migration work.
  • references/known_issues.md — censorship patterns, TTS duration inflation, v2-family parameter naming gotcha, 1000-char hard cap. 2.5-era verification; re-verify on v3 before relying on a specific entry. 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_v3/), 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-3-tts should only use instruction + inline (). Do not write a branch that conditionally emits voice_label.

v3-specific facts (verified 2026-09-16)

  • Official voices: 60+ via GET /v1/audio/system_voices?model=stepaudio-3-tts — the 2.5 list is fully inherited, plus new voices (e.g. English-named Lisa/Alfie, 上海话 shanghaifemale/shanghaimale).
  • Cloned (复刻) voices: do NOT use stepaudio-3-tts — root cause nailed 2026-09-16: StepFun's whole cloning stack is still 2.5-family. The creation API (POST /v1/audio/voices) only accepts stepaudio-2.5-tts / step-tts-2 / step-tts-mini, and v3 /v1/audio/speech silently falls back to a default female voice for ANY cloned ID — SIM 0.272 (step-tts-2 clone) and 0.195 (fresh 2.5-created clone) vs the 0.773 anchor; the same IDs on 2.5 score 0.743/0.678. Synthesize clones with stepaudio-2.5-tts (best SIM) or step-tts-2.
  • No WebSocket streaming for v3 (as of 2026-09-16): wss://api.stepfun.com/v1/realtime/audio?model=stepaudio-3-tts is rejected at handshake (404), while 2.5 still streams there. Need char-level subtitle timestamps on v3? Use REST timestamp:true + return_url:true (subtitles arrive in the response JSON data.subtitles[], char-level ms, accumulated absolute axis) — bare stream_format:"audio" cannot carry subtitles (server 400).

Pricing (verified 2026-09-16, volatile)

  • stepaudio-3-tts synthesis: 2.5 元 / 万字符 (official model page, 2026-09-16 — cheaper than the 2.5-era ~5.8)
  • Zero-shot voice cloning: 9.9 元 / 音色

Re-verify at https://platform.stepfun.com/docs/zh/guides/pricing/details before quoting to stakeholders.

Related Skills

View on GitHub
GitHub Stars1.4k
CategoryOther
Updated1mo ago
Forks219

Languages

Python

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions
stepfun-tts — Universal Skill: Install & Safety Check | SkillAgent