StepFun コンテキスト TTS(デフォルト stepaudio-2.5-tts) は何をしますか?
StepFunのコンテキストTTSを使用して中国語・日本語の音声を生成します。感情とプロソディは固定ラベルではなく、自然言語の説明で指定します。デフォルトモデルは stepaudio-2.5-tts(バンドルスクリプトが使用するもの):2026-09-16の自社ケースによるブラインドA/Bテストでは、2.5がニュートラル/ジオ/活発女子のペアで3:2で勝利しました。囁き声や大量のインライン()プロソディがある場合は stepaudio-3-tts を選択 — v3はこれらの2ペアで勝利。また、v3では instruction の上限が500文字に拡張されています(2.5は200)。⚠️ クローン音声をv3で合成しないでください — v3の音声はクローン音色IDを受け付けてもエラーにならず、デフォルトの女性音声にサイレントフォールバックします。根本原因は、StepFunのクローン処理全体が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。
補足:
stepaudio-3-asr-max(兄弟モデル)を使った文字起こしにはstepfun-asrスキルを使用してください — 同じAPIキーを共有しますが、エンドポイントとリクエストボディが異なります。
このスキルが存在する理由 — 知らないと何時間も費やす可能性がある2つの落とし穴:
stepaudio-3-ttsはvoice_labelを拒否します(step-tts-2の方法)— 2026-09-16にv3で確認済み: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キーは $STEPFUN_API_KEY(推奨)または ${CLAUDE_PLUGIN_DATA}/config.json(セッション間の永続化のためのフォールバック)に格納します。バンドルされているすべてのスクリプトは、最初に環境変数、次に設定ファイルを試します。
初回設定(一行コマンド):
mkdir -p "${CLAUDE_PLUGIN_DATA}" && cat > "${CLAUDE_PLUGIN_DATA}/config.json" <<EOF
{"api_key": "<キーをここに貼り付け>"}
EOF
ユーザーがキーを設定していない場合は、キーを貼り付けるよう依頼してください(推測しないでください。プレースホルダーも使用しないでください)。StepFun APIキーは https://platform.stepfun.com/ → API Keys で取得できます。Normalキーを使用してください。Planキーは使用しないでください(Planキーはテキストモデルに制限されており、オーディオエンドポイントではサイレントに失敗します)。
一般的なタスク — 決定ツリー
| ユーザーの希望 | スクリプト | 重要な詳細 |
|---|---|---|
| 感情を伴う1〜500文字の中国語を合成 | scripts/tts_generate.py | ムードには instruction、インラインプロソディには () を使用 |
| 長いテキスト(500〜1000文字)を合成 | scripts/tts_generate.py | 1000文字がハードリミット。それを超える場合は意味的な境界で分割 |
| ゲーム・アプリの音声ラインをバッチ生成 | scripts/tts_generate.py --batch <jsonl> | censorship_block のフォールバックは個別に処理 |
| 2つのTTSモデルをA/B比較 | scripts/ab_compare.sh | 2つのディレクトリ間で再生時間/サイズを比較 |
step-tts-2 / stepaudio-2.5-tts から移行 | references/migration_from_v2.md を参照 | voice_label.emotion → instruction への書き換え + 2.5時代の検閲リスト |
スタートガイド
- 1行の合成:
python3 scripts/tts_generate.py --text "你好" --out /tmp/hello.mp3 --instruction "暖かな希望の感じ"を実行。詳細な制御については下記の「コンテキストTTS」セクションを参照。 - コードから:このスクリプトは
llm-registry内のエンドポイントラッパーです —llmreg.wrapper_for("stepfun-tts").tts_generate.synthesize(api_key=…, text=…, model=…, extra={…})。extraはリクエストボディにそのままマージされます。{"timestamp": True, "return_url": True}を指定すると、サーバーはaudio_bytesの代わりに JSON エンベロープ({"data": {"url", "subtitles"}})を返します(2026-09-19確認)。パラメータは課金されませんので、必要なものを送信してください。他の場所からの直接/v1/audio/speech呼び出しはllm-entry-guardフックでブロックされます。 - 完全な移行(
step-tts-2→ コンテキストTTS):コードに触れる前にreferences/migration_from_v2.mdを最初から最後まで読んでください。INSTRUCTION_MAP、SKIP_CENSOREDリストパターン、非破壊A/Bのための出力ディレクトリ戦略が含まれています(2.5用に記述されていますが、移行メカニズムはv3でも同じです)。
コンテキストTTS — 感情ラベルを超えて
stepaudio-3-tts の最大の特徴は、感情を固定タグにマッピングするのをやめ、自然言語で望むものを記述できることです。2つのレイヤー:
グローバルコンテキスト(instruction パラメータ) — 発話全体の全体的なトーンを設定します。v3では≤500文字(2.5は200。300文字のinstructionがv3で受け付けられたことを2026-09-16に確認)。声優への演技指示を与えるように考えてください。
instruction: "抑制された悲しみ、低くか細い声、消え入りそうな感じで"
インラインコンテキスト(input 内の () 括弧) — 文中の指示。括弧で囲まれた内容は指示として消費され、読み上げられません。ポーズ、息継ぎ、強調、文中の感情変化を精密に制御するために使用します。
input: "(ためらいがちに)元気?(嬉しそうに)よかった!(突然沈んで)でも…もう消えそうだ。"
実際に動作した例(2026-04-23に2.5で確認、2026-09-16にv3でも全5例を再確認。これらの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) | コンテキストTTSモデルに voice_label を送信した | 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の正確なリクエスト/レスポンスJSON、全フィールド、エラーレスポンス。バンドルスクリプトの代わりに生のHTTP呼び出しを書くときに読む。references/migration_from_v2.md— step-tts-2プロジェクトをコンテキストTTSに移行するための完全なプレイブック。感情→instruction書き換えテーブル、A/Bディレクトリ戦略、決定チェックポイント、2026年4月の速度/品質トレードオフデータ(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に根本原因を特定:StepFunのクローンスタック全体がまだ2.5ファミリー。作成API(POST /v1/audio/voices)はstepaudio-2.5-tts/step-tts-2/step-tts-miniのみ受け付け、v3の/v1/audio/speechは任意のクローンIDに対してデフォルトの女性音声にサイレントフォールバック — SIM 0.272(step-tts-2クローン)および0.195(2.5で新規作成したクローン)vs アンカー0.773。2.5での同一IDスコアは0.743/0.678。クローンはstepaudio-2.5-tts(最高SIM)または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を使用(字幕はレスポンスJSONdata.subtitles[]に文字レベルのms、累積絶対軸で到着)— 単体の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 で再確認してください。