Communitygithub.com

StepFun コンテキスト TTS(デフォルト stepaudio-2.5-tts)

StepFunのコンテキストTTSを使用して中国語・日本語の音声を生成します。感情やプロソディを自然言語で記述し、固定ラベルは使いません。バッチ音声ライン、感情・韻律制御、step-tts-2からの移行、クローン音声に対応。

StepFun コンテキスト TTS(デフォルト stepaudio-2.5-tts) とは?

このスキルは、StepFun社のコンテキストTTS(stepaudio-2.5-tts、stepaudio-3-tts)を利用して中国語・日本語の音声を合成するためのAIエージェントスキルです。デフォルトモデルはstepaudio-2.5-ttsで、感情表現や韻律制御はvoice_labelではなく、自然言語によるinstructionパラメータとテキスト内の丸括弧()を使ったインラインプロソディで行います。stepaudio-3-ttsではinstructionの上限が500文字に拡張され、より柔軟な表現が可能です。ただし、クローン音声(复刻)はstepaudio-3-ttsでは正しく合成されないため、必ずstepaudio-2.5-ttsまたはstep-tts-2を使用する必要があります。また、検閲動作はモデルバージョンに依存するため個別に確認が必要です。このスキールはClaude Code, Cursor, CodexといったAIエージェントツールで利用でき、スクリプトベースで単一音声合成、バッチ処理、A/B比較、移行作業をサポートします。APIキーは環境変数または設定ファイルで管理し、エラー処理や検閲回避のベストプラクティスも提供します。

対応✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/daymade/claude-code-skills/tree/HEAD/daymade-audio/stepfun-tts

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

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つの落とし穴:

  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": "<キーをここに貼り付け>"}
EOF

ユーザーがキーを設定していない場合は、キーを貼り付けるよう依頼してください(推測しないでください。プレースホルダーも使用しないでください)。StepFun APIキーは https://platform.stepfun.com/ → API Keys で取得できます。Normalキーを使用してください。Planキーは使用しないでください(Planキーはテキストモデルに制限されており、オーディオエンドポイントではサイレントに失敗します)。

一般的なタスク — 決定ツリー

ユーザーの希望スクリプト重要な詳細
感情を伴う1〜500文字の中国語を合成scripts/tts_generate.pyムードには instruction、インラインプロソディには () を使用
長いテキスト(500〜1000文字)を合成scripts/tts_generate.py1000文字がハードリミット。それを超える場合は意味的な境界で分割
ゲーム・アプリの音声ラインをバッチ生成scripts/tts_generate.py --batch <jsonl>censorship_block のフォールバックは個別に処理
2つのTTSモデルをA/B比較scripts/ab_compare.sh2つのディレクトリ間で再生時間/サイズを比較
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でも再確認してから特定のエントリに依存すること。異常な出力のデバッグや採用の評価時に読む。

設計不変条件(これらを壊さないこと)

  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.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 を使用(字幕はレスポンスJSON data.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 で再確認してください。

Individual skills in this repo

This repo contains 9 individual skills — each has its own dedicated page.

daymade/claude-code-skills

This skill should be used when comparing two videos to analyze compression results or quality differences. Generates interactive HTML reports with quality metrics (PSNR, SSIM) and frame-by-frame visual comparisons. Triggers when users mention "compare videos", "video quality", "compression analysis", "before/after compression", or request quality assessment of compressed videos.

daymade/claude-code-skills

Download YouTube videos and HLS streams (m3u8) from platforms like Mux, Vimeo, etc. using yt-dlp and ffmpeg. Use this skill when users request downloading videos, extracting audio, handling protected streams with authentication headers, or troubleshooting download issues like nsig extraction failures, 403 errors, or cookie extraction problems.

daymade/local-conversation-history

Entry point for local AI conversation history across providers. Routes a request to the one skill that owns it, by platform (Claude Code, OpenAI Codex, Kimi CLI) and action (read evidence vs continue interrupted work), and owns the one job none of them own alone: a single inventory spanning all three providers. Use when the provider is unknown or plural ("our history", "what have I been working on", "which chats did I have"), when the user wants Kimi CLI history at all, when it is unclear whether they need evidence or resumption, or when they ask for this skill by name. Vague recall that names no platform ("we discussed this once, when was it?") belongs here rather than to a single-provider reader, because a Claude-only answer to an unscoped question cannot support an absence claim. When the platform and the action are both already clear, load that executor skill directly instead — except Kimi CLI, which has no reader or continuation skill of its own and always routes through here.

daymade/ppt-creator

Create professional slide decks from topics or documents. Generates structured content with data-driven charts, speaker notes, and complete PPTX files. Applies persuasive storytelling principles (Pyramid Principle, assertion-evidence). Supports multiple formats (Marp, PowerPoint). Use for presentations, pitches, slide decks, or keynotes.

daymade/prompt-optimizer

Transform vague prompts into precise, well-structured specifications using EARS (Easy Approach to Requirements Syntax) methodology. This skill should be used when users provide loose requirements, ambiguous feature descriptions, or need to enhance prompts for AI-generated code, products, or documents. Triggers include requests to "optimize my prompt", "improve this requirement", "make this more specific", or when raw requirements lack detail and structure.

daymade/qa-expert

This skill should be used when establishing comprehensive QA testing processes for any software project. Use when creating test strategies, writing test cases following Google Testing Standards, executing test plans, tracking bugs with P0-P4 classification, calculating quality metrics, or generating progress reports. Includes autonomous execution capability via master prompts and complete documentation templates for third-party QA team handoffs. Implements OWASP security testing and achieves 90% coverage targets.

daymade/read-claude-code-history

Reads, searches, and exports local Claude Code history without resuming work. Covers recent session inventory, exact session timelines, verbatim human input including queued mid-turn prompts, full-event keyword search, hybrid recall when wording changed, end-state triage, and deleted-file recovery across active Claude homes plus registered archives. Use whenever the user asks what they or Claude said, wants a Claude Code session ID or original context, remembers prior work vaguely, needs an old file from a transcript, or must prove what a Claude session contained before continuing it. Also owns the only Kimi CLI surface, via its Kimi inventory and search flags. For Codex history use read-codex-history; when the request names no platform at all or spans providers, start at local-conversation-history.

daymade/read-codex-history

Reads, searches, and exports local OpenAI Codex history without continuing the old task. Lists recent Codex sessions, extracts exact prompt-ledger inputs by Session, locates a rollout by verified session_meta identity, reconstructs one chronological user/assistant timeline with fork and compaction lineage, and performs bounded keyword search across live and archived rollouts. Use whenever the user asks what they told Codex, wants recent original inputs, a Codex Session ID, full prior context, fork ancestry, or evidence of what a Codex run did. For Claude Code history use read-claude-code-history.

daymade/twitter-reader

Fetch Twitter/X post content including long-form Articles with full images and metadata. Use when Claude needs to retrieve tweet/article content, author info, engagement metrics, and embedded media. Supports individual posts and X Articles (long-form content). Automatically downloads all images to local attachments folder and generates complete Markdown with proper image references. Preferred over Jina for X Articles with images.

関連スキル