StepFun Contextual TTS(預設 stepaudio-2.5-tts)
使用階躍星辰的 Contextual TTS 生成中文/日語語音 — 情感與韻律透過自然語言描述,而非固定標籤。預設模型為 stepaudio-2.5-tts(捆綁腳本使用的模型):在 2026-09-16 的內部盲測 A/B 比較中,2.5 在 neutral / jiao / lively-girl 三組中以 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 克隆相似度 0.272、2.5 建立的新克隆相似度 0.195(錨點 0.773),2.5 同 ID 則為 0.743/0.678。
夥伴:如需使用
stepaudio-3-asr-max(同系列模型)進行語音轉寫,請使用stepfun-asr技能 — 兩者共用 API Key,但使用不同端點與不同請求結構。
為何需要此技能 — 若不事先了解,有兩個不易察覺的陷阱可能浪費數小時:
stepaudio-3-tts拒絕voice_label(step-tts-2 的方式)— 於 v3 2026-09-16 驗證:HTTP 400voice_label is not supported for this model。情感/韻律透過instruction(自然語言描述,v3 上限 500 字 — 2.5 為 200)及文字內的括號()控制。- 審查行為依模型版本而異 — 2.5 時代的觸發清單(死/消失/敏感政治用語 →
censorship_block)在 2026-09-16 的單一樣本測試中並未觸發 v3;請將審查視為存在,但在建立改寫對應表前,請針對每個觸發條件重新驗證。2.5 時代的選項詳見references/migration_from_v2.md。
設定與認證
API Key 存放於 $STEPFUN_API_KEY(建議)或 ${CLAUDE_PLUGIN_DATA}/config.json(跨 session 持久化的備用方案)。所有捆綁腳本會優先讀取環境變數,再讀取設定檔。
首次設定(一行指令):
mkdir -p "${CLAUDE_PLUGIN_DATA}" && cat > "${CLAUDE_PLUGIN_DATA}/config.json" <<EOF
{"api_key": "<貼上你的 Key>"}
EOF
若使用者尚未設定 Key,請要求他們貼上(請勿猜測或使用佔位符)。StepFun API Key 可在 https://platform.stepfun.com/ → API Keys 取得。請使用 Normal Key,不要使用 Plan Key(Plan Key 僅限文字模型,在音訊端點上會靜默失敗)。
常見任務 — 決策樹
| 使用者需求... | 腳本 | 關鍵細節 |
|---|---|---|
| 合成 1–500 字中文語音(含情感) | scripts/tts_generate.py | 使用 instruction 設定情緒,() 控制行內韻律 |
| 合成長文字(500–1000 字) | scripts/tts_generate.py | 1000 字為硬性上限;超過時請依語意邊界分割 |
| 批次生成遊戲/應用語音台詞 | scripts/tts_generate.py --batch <jsonl> | 逐行處理 censorship_block 的備援邏輯 |
| A/B 比較兩種 TTS 模型 | 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 "溫暖的希望感"。如需更細緻的控制,請閱讀下方「Contextual 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鉤子攔截。 - 完整遷移從
step-tts-2→ Contextual TTS:在動任何程式碼前,請完整閱讀references/migration_from_v2.md。該文件包含INSTRUCTION_MAP、SKIP_CENSORED 清單模式,以及非破壞性 A/B 比較的輸出目錄策略(以 2.5 為基礎撰寫;遷移機制在 v3 上完全相同)。
Contextual TTS — 超越情感標籤
stepaudio-3-tts 的主要功能是:你不再將情感對應到固定標籤,而是開始用自然語言描述你的需求。共有兩層:
全域上下文(instruction 參數) — 設定整個語句的整體語氣。v3 上限 500 字(2.5 為 200;300 字的 instruction 已於 2026-09-16 在 v3 上驗證可正常使用)。可以想像成你在對配音演員下達舞台指示。
instruction: "剋制的悲傷,語氣低沉柔弱,像快要消失一樣"
行內上下文(input 中的 () 括號) — 句內的指令。括號內的內容會被視為指示,不會被朗讀出來。可用於精確控制停頓、氣息、強調或句中的情緒轉變。
input: "(試探著問)你好嗎?(開心地)太好了!(突然沉下來)不過...我快要消失了。"
實際驗證可行的範例(2026-04-23 於 2.5 驗證;全部五個範例於 2026-09-16 在 v3 上重新驗證,包含這些 instruction 和行內韻律案例):
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) | 將 voice_label 傳給 Contextual TTS 模型 | 移除 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的完整 request/response JSON、所有欄位、錯誤回應。當你直接撰寫原始 HTTP 呼叫而非使用捆綁腳本時閱讀。references/migration_from_v2.md— 將 step-tts-2 專案遷移至 Contextual TTS 的完整操作手冊。內含情感→instruction 改寫對照表、A/B 目錄策略、決策檢查點,以及 2026-04 的速度/品質權衡資料(基於 2.5 撰寫)。請在進行任何遷移工作前閱讀。references/known_issues.md— 審查模式、TTS 時長膨脹、v2 家族參數命名陷阱、1000 字硬性上限。基於 2.5 時代驗證;若需依賴特定項目,請在 v3 上重新驗證。除錯異常輸出或評估是否採用時閱讀。
設計不變原則(請勿違反)
- 非破壞性 A/B 輸出 — 使用新模型重新生成語料時,請寫入平行目錄(
voice/zh_v3/),切勿覆蓋生產用語料。遷移手冊說明了原因。 - 逐行處理審查 — 若 29 行中有 2 行觸發
censorship_block,不應讓整個批次失敗。記錄跳過的 ID,繼續處理。混合模型備援(被跳過的 2 行改用 step-tts-2)是正常做法。 - 新程式碼中請勿重複 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 鎖定根本原因:階躍的整個復刻堆疊仍屬於 2.5 家族。建立 API(POST /v1/audio/voices)僅接受stepaudio-2.5-tts/step-tts-2/step-tts-mini,而 v3 的/v1/audio/speech對任何復刻 ID 會靜默回退至預設女聲 — 相似度 0.272(step-tts-2 克隆)和 0.195(全新的 2.5 克隆)對比錨點 0.773;相同 ID 在 2.5 上得分為 0.743/0.678。請使用stepaudio-2.5-tts(最佳相似度)或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 重新驗證。