stepfun-tts

StepFun Contextual TTS（デフォルトは step audio-2.5-tts）

StepFun の Contextual TTS で中国語／日本語の音声を生成します。感情や韻律は固定ラベルではなく、自然言語の説明で指定します。デフォルトモデルは stepaudio-2.5-tts（同梱スクリプトが使用するモデル）です。2026-09-16 に独自のケースで実施したブラインド A/B テストでは、ニュートラル／jiao／活発な女の子のペアで 2.5 が 3 対 2 で勝ちました。ささやき声や、本文中に () を多用した韻律指定には stepaudio-3-tts を選んでください。この 2 種のペアでは v3 が勝ちました。また、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 つあります。

1. stepaudio-3-tts は voice_label（step-tts-2 方式）を拒否します。2026-09-16 に v3 で確認済みです。HTTP 400 voice_label is not supported for this model が返されます。感情／韻律は instruction（自然言語による説明。v3 の上限は 500 文字で、2.5 の上限は 200 文字）と、本文内のインライン () 括弧で指定します。
2. 検閲の挙動はモデルのバージョンによって異なります。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": "<paste key here>"}
EOF

ユーザーがキーを設定していない場合は、キーを貼り付けるよう依頼してください（推測したり、プレースホルダーを使ったりしないでください）。StepFun API キーは https://platform.stepfun.com/ → API Keys から取得できます。Plan キーではなく Normal キーを使用してください（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 "温暖的希望感" を実行します。細かく制御するには、以下の「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"}}）を返し、audio_bytes ではなく json の下に格納されます（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 の主な特徴は、感情を固定タグに対応付けるのをやめ、自然言語で求める内容を説明できることです。2 つのレイヤーがあります。

グローバルコンテキスト（instruction パラメーター） — 発話全体のトーンを設定します。v3 では最大 500 文字です（2.5 では 200 文字でした。2026-09-16 に v3 で 300 文字の指示が受け付けられることを確認済みです）。声優に演技の指示を出すようなものだと考えてください。

instruction: "克制的悲伤，语气低沉柔弱，像快要消失一样"

インラインコンテキスト（input 内の () 括弧） — 文中の指示です。括弧内の内容は指示として扱われ、音読されません。間、息継ぎ、強調、文中での感情の変化を細かく制御するために使います。

input: "(试探着问)你好吗？(开心地)太好了！(突然沉下来)不过...我快要消失了。"

実際に動作した例（2026-04-23 に 2.5 で確認済み。これらの指示とインライン韻律の例を含む 5 例すべてを、2026-09-16 に v3 でも再確認済み）：

• 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）	Contextual 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 プロジェクトを Contextual TTS に移行するための完全な手順書です。感情から指示への書き換え表、A/B テスト用ディレクトリー戦略、判断のチェックポイント、2026-04 時点の速度／品質のトレードオフデータが含まれています（2.5 を対象に記述）。移行作業を始める前にお読みください。
• references/known_issues.md — コンテンツフィルターのパターン、TTS の長さの増加、v2 系のパラメーター名に関する注意点、1000 文字の上限について記載されています。2.5 時代の検証結果のため、特定の項目を信頼する前に v3 で再確認してください。異常な出力をデバッグする場合や、導入を検討する場合にお読みください。

設計上の不変条件（変更しないでください）

1. 非破壊的な A/B 出力 — 新しいモデルでコーパスを再生成する場合は、並行するディレクトリ（voice/zh_v3/）に書き込み、本番コーパスを上書きしないでください。移行手順書でその理由を説明しています。
2. 行ごとの検閲への対応 — 29 行中 2 行で censorship_block が発生しても、バッチ全体を失敗させないでください。スキップした ID をログに記録し、処理を続けます。スキップした 2 行に step-tts-2 を使う混合モデルでのフォールバックは通常の対応です。
3. 新しいコードで 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.773 の基準音声に対して 0.272（step-tts-2 でクローン）と 0.195（2.5 で新規作成したクローン）です。同じ ID を 2.5 で使用すると、スコアは 0.743／0.678 になります。クローン音声の合成には、SIM が最も高い 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 の音声合成：1 万文字あたり 2.5 元（公式モデルページ、2026-09-16 — 2.5 時代の約 5.8 元より安価）
• ゼロショット音声クローン：音色 1 種類あたり 9.9 元

関係者に提示する前に、https://platform.stepfun.com/docs/zh/guides/pricing/details で再確認してください。