Stepfun Tts

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

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.