早見表・トラブル解決・理解度チェック

最終ステップでは、開発中にいつでも見返せるAPI＆出力フォーマット早見表、実務で遭遇しがちな5大トラブルの解決策、そしてここまでの学習成果を試せる全6問の理解度チェッククイズを用意しました。ページ末尾には本サイトの設計・アセット生成記録と Cloudflare Workers デプロイ手順も収録しています。

1. 出力オーディオ形式・サンプリングレート早見表

generation_config.speech_config.response_format で指定できる MIME タイプとサンプリングレートの一覧です。用途に合わせて最適な形式を選択してください。

モード / 指定値	MIME タイプ	対応サンプルレート	特徴・主な用途
一括生成のデフォルト（`stream: false`）	`audio/wav`	`24000`（既定） `16000` / `8000`	先頭 44 バイトの RIFF WAV ヘッダ付き。そのまま `.wav` ファイルとして保存・ブラウザ再生可能。
ストリーミングのデフォルト（`stream: true`）	`audio/l16`	`24000`（既定） `16000` / `8000`	ヘッダなしの 16-bit リニア PCM（リトルエンディアン・モノラル）。リアルタイム再生や複数チャンクのシームレス結合に最適。
電話回線・IVR 向け 1	`audio/mulaw`	`8000`（推奨）	北米・日本の電話網や Twilio Media Streams で標準の G.711 μ-law。トランスコード不要で電話回線へ直結可能。
電話回線・IVR 向け 2	`audio/alaw`	`8000`（推奨）	欧州等の電話網で標準の G.711 A-law。

2. Interactions API（推奨）と generateContent API の違い

Gemini 3.8 TTS は、新しい Interactions API（/v1beta/interactions） と従来の generateContent API（/v1beta/models/...:generateContent） の両方から呼び出せます。新規開発では Interactions API の利用が強く推奨されます。

機能・比較軸	Interactions API（公式推奨） `client.interactions.create()`	generateContent API（従来互換） `client.models.generate_content()`
3レイヤー分離（`speech_metadata.style`）	ネイティブ対応（ターンやブロック単位で `style` フィールドに分離可能）	非対応（`contents` 内のテキストプロンプトに自然言語で演技指示を書く必要あり）
マルチパートターン（途中の演技変更）	対応（`content` 配列の要素ごとに別々の `style` を付与可能）	非対応
2話者対話のスピーカー指定	`speech_config.speakers` 配列＋各パートの `speech_metadata.speaker`	`multi_speaker_voice_config` ＋テキスト内の `SpeakerName: セリフ` 記法
カスタムボイス（Voice Design / Clone）	`voice: "voice_..."` または `"voicekey_..."` をそのまま指定可能	一部プレビュー制限あり（Interactions API がフル機能対応）

3. 現場でハマりやすい5大トラブルと解決策

トラブル1：複数の音声チャンクを結合したら、つなぎ目で「ブチッ」とノイズが鳴る

原因：一括生成（stream: false）のデフォルト出力は audio/wav であり、各レスポンスの先頭 44 バイトに RIFF WAV ヘッダが含まれています。そのままバイト結合すると、2つ目以降の WAV ヘッダ（44バイトの非音声データ）が音声波形として再生され、クリックノイズになります。
解決策：レシピ1で紹介した通り、response_format: { "mime_type": "audio/l16", "sample_rate": 24000 } を指定してヘッダなし生 PCM で受け取って結合するか、2つ目以降の WAV データの先頭 44 バイト（wav_bytes[44:]）をスライスして除去してから連結してください。

トラブル2：演技指示やインラインタグがそのまま声に出して読まれてしまう

原因：text フィールドの中に （悲しそうに） と日本語でト書きを書いたり、<ため息> と日本語タグを書いたりしているためです。
解決策：演技指示は必ず speech_metadata.style に移動し、インラインタグは公式の英語タグ（<sigh>、<chuckle>、<short pause> 等）のみを使用してください。

トラブル3：Voice Replication（ボイスクローン）登録時に 400 エラーが返る

原因：① consent_audio の読み上げ内容が公式同意フレーズと一字一句一致していない、② source_audio と consent_audio の録音環境（マイクや反響）が違いすぎて別人と判定された、③ 音声長が10秒未満または30秒超、のいずれかです。
解決策：同じ静かな部屋・同じマイクで続けて両方を録音し、ffmpeg -i input.m4a -ar 24000 -ac 1 -c:a pcm_s16le out.wav で 24kHz モノラル 16-bit WAV に揃えてから送信してください。

トラブル4：2話者対話で `speech_config` に `"mode": "conversational"` を入れたら 400 エラーになった

原因：Interactions API のライブエンドポイントでは、speech_config に speakers 配列を渡した時点で自動的にマルチスピーカー対話モードとして処理されるため、未知のフィールド mode を追加するとスキーマエラーになります。
解決策：speech_config にはシンプルに { "speakers": [{ "speaker": "A", "voice": "Aoede" }, { "speaker": "B", "voice": "Puck" }] } だけを指定してください。

トラブル5：英語の頭文字（API、UI、TTS など）が不自然に読まれる

原因：文脈によっては英単語として一括読みされそうになる場合があります。
解決策：日本語の原稿内であれば エーピーアイ、ティーティーエス のようにカタカナで表記するか、アルファベット間にハイフン（T-T-S）または IPA 発音表記（/tiːtiːɛs/）を使うと 100% 意図通りに発音されます。

4. マスター理解度チェッククイズ（全6問）

ここまでの6ステップで学んだ重要ポイントを、6問のクイズで確認してみましょう。すべて正解できれば、あなたはもう Gemini 3.8 TTS マスターです！

Q1. Gemini 3.8 TTS（Interactions API）において、「緊急のささやき声で、早口で」といったそのターンの演技指示を書くべき正しいフィールドはどこですか？

Q2. 日本語のセリフの中で「ため息」と「短い間」を入れたい場合、text フィールド内の正しいタグ表記はどれですか？

Q3. 2話者対話（Multi-Speaker）で、話者Aが話している最中に話者Bに「うんうん」と自然な相づち（バックチャネル）を重ねさせたいときの記法は？

Q4. 自分の声を30秒の録音からクローンする「Voice Replication（type: "replicated"）」で必須となる2つの音声データの組み合わせは？

Q5. 1分（60秒）の音声を「Gemini 3.8 Flash-Lite TTS（2026年プロモ料金 $6 / 100万トークン）」で生成したときの出力トークン数と料金は？

Q6. Gemini 3.1 TTS から 3.8 TTS（一括生成 stream=False）へ移行する際、デフォルトの出力音声フォーマットに関して注意すべき変更点は？

5. Cloudflare Workers デプロイ手順＆制作・意思決定の記録

本サイトは Cloudflare Workers Paid（$5プラン）＋ Astro 7 ＋ TypeScript ＋ Zod ＋ Biome で構築されており、ローカルビルドとすべての静的アセット（実音声22ファイル・日本語グラレコ図解4枚）の生成・検証が完了しています。

本番環境（Cloudflare Workers）へのデプロイコマンド

# 1. 品質チェック（Biome Lint/Format ＆ Astro TypeScript 型チェック）
pnpm check

# 2. 프로ダクションビルド（dist/ への出力確認）
pnpm build

# 3. Cloudflare Workers へデプロイ（初回のみ Cloudflare ログイン確認が出る場合があります）
npx wrangler deploy

自律進行における意思決定・名付け・生成アセットの記録（オーナー確認用）

項目	決定内容と理由
サイト名称	『Gemini 3.8 TTS 実践マスターガイド ─ 基礎からボイスクローン・対話生成まで』 ChatGPT/Gemini 経験者が「何が学べて、どこまで到達できるか」を一目で理解できる実用重視の名称に決定。
カリキュラム構成（全6ステップ）	Home（3秒で違いがわかる聴き比べ＆全体像）→ Step 1: TTS基礎と3.5 Transcribe → Step 2: 3.8 Flash vs Flash-Lite 比較・料金計算・30ボイス試聴 → Step 3: 3レイヤー演技指導・24種タグ・パイプ相づち・シミュレーター → Step 4: ボイスクローン（Voice Replication）＆音声デザイン → Step 5: 実用5大レシピ（Cloudflare Workers + R2 実装含む） → Step 6: 早見表・トラブル解決・理解度クイズ。
実音声サンプル生成（全22件）	Interactions API 経由で `gemini-3.8-flash-tts` および `gemini-3.8-flash-lite-tts` を実際に呼び出し、`public/guides/gemini-tts/audio/samples/*.mp3` に22件の日本語サンプル音声を生成。実波形（RMSピーク）と秒数を抽出し `src/data/audio-samples.json` に格納。
Nano Banana 2.1 日本語グラレコ図解（全4枚）	ご指定通り「すべて日本語テキスト・登場人物は日本人」で `gemini-nano-banana-2.1` により4枚の16:9図解（`hero-studio-concept.webp`, `three-layer-architecture.webp`, `voice-cloning-security.webp`, `dialogue-backchannel-scene.webp`）を生成し、視覚検収のうえ `public/guides/gemini-tts/images/illustrations/生成記録.md` に全プロンプトを記録。
技術スタック＆コード品質	Astro 7.4 (`output: 'static'` + `@astrojs/cloudflare` v14)、`astro/zod` によるスキーマ検証、Biome 2.6 による Lint/Format、`wrangler.jsonc`（`nodejs_compat` 有効）を構成。