mcpField
T
text-to-speech

text-to-speech

github.com/deepgramクリエイティブ・メディア2644 回インストール4 日前に更新
リポジトリ

text-to-speech について

このスキルは、Deepgramのテキスト読み上げを統合する開発者向けガイドです。AuraとFlux TTSのエンドポイント、音声の選択、ストリーミングとバッチリクエスト、各種制御を扱います。

主な機能

  1. 01AuraまたはFlux TTSエンドポイントの選択
  2. 02WebSocketによる音声ストリーミング
  3. 03バッチリクエストによる音声生成
  4. 04音声と対応言語の選択
  5. 05速度、発音、ポーズの制御

活用シーン

  1. 01割り込みに対応するストリーミング音声エージェントの構築
  2. 02音声ファイルやIVRプロンプトの生成
  3. 03多言語音声出力の設定

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/deepgram/skills --skill text-to-speech

インストール後、Claude Code で/text-to-speechを入力して読み込まれたか確認します。

詳細

Deepgram テキスト読み上げ

Deepgram は、別々のエンドポイントで 2 系統のテキスト読み上げを提供しており、音声は互換性がありません。 Aura 音声は /v1/speak でのみ動作します。Flux TTS 音声は /v2/speak でのみ動作します。/v2/speak は追加のエンドポイントです。/v1/speak に変更はなく、引き続きサポートされます。

まず音声の系統を選ぶ

要件系統エンドポイント
LLM の出力をストリーミングし、割り込みにも対応する必要がある音声エージェントFlux TTSwss://api.deepgram.com/v2/speak
単発の音声：ファイル、IVR プロンプト、通知Flux TTS バッチPOST https://api.deepgram.com/v2/speak
英語とスペイン語を切り替える 1 つの応答Aura-2 コードスイッチング音声/v1/speak
Voice Agent 内の英語以外の音声Aura-2agent.speak.provider.version: "v1"
継続して使う必要がある既存の aura-2-* または aura-{voice}-en 音声Aura-2 または Aura-1/v1/speak

目安として、新規開発では 42 言語のいずれの場合も Flux TTS が推奨されます。 Flux TTS 音声は、英語（アメリカ、イギリス、アイルランド、オーストラリア、インド、シンガポール、フィリピンのアクセント）と、ほかの 41 言語に対応しています。言語はモデル文字列の接尾辞で示されます（flux-anouk-nl はオランダ語です）。テキストの正規化（数字、日付、略語）は、英語、ドイツ語、オランダ語、フランス語、ヒンディー語、イタリア語、日本語、ポルトガル語、ロシア語、スペイン語に対応しています。ほかの 32 言語は正規化なしのアーリーアクセスのため、数字や日付は単語で記述してください。英語以外の音声は api.deepgram.com、api.eu.deepgram.com、api.in.deepgram.com で提供されますが、現時点では api.au.deepgram.com では利用できません。Aura-2 は前世代（英語、スペイン語、ドイツ語、フランス語、オランダ語、イタリア語、日本語）で、Aura-1 は初代で英語のみです。Voice Agent 内では、英語以外の音声や圧縮形式またはコンテナ形式の出力には Aura（v1）音声が必要です（間違い 7 を参照）。

最初のリクエスト：REST で Aura を使う

curl --request POST \
  --url "https://api.deepgram.com/v1/speak?model=aura-2-thalia-en&encoding=linear16&container=wav" \
  --header "Authorization: Token $DEEPGRAM_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"text": "Hello, how can I help you today?"}' \
  --output hello.wav \
  --fail-with-body --silent || echo "Request failed"

期待される動作：

  • 2xx の本文はバイナリー音声です。エラーは JSON です。解析する前に HTTP ステータスを確認してください。
  • オプションはクエリー文字列に指定します。JSON 本文には text のみを含めます。
  • encoding を指定しない場合、REST は mp3 を返します。WAV の場合は encoding=linear16&container=wav を指定してください。REST で指定できるほかのエンコーディングは opus、flac、aac、mulaw、alaw で、container、bit_rate、sample_rate も指定できます。
  • model を省略すると、/v1/speak は Aura-1 音声の aura-asteria-en を使用します。必ず model を指定してください。
  • Aura-2 の speed は 0.7 から 1.5 まで指定でき、英語とスペイン語の音声でのみ動作します。スペイン語の音声では 0.9 から 1.5 を使用してください。0.9 未満の値では、発話が不自然になる場合があります。
  • Aura-2 の発音制御は、英語とスペイン語の音声で、Flux TTS と同じエスケープ済みの \{"word":"...","pronounce":"<IPA>"\} 構文を使って /v1/speak で GA として利用できます。入力上限は 2000 文字です。Aura-2 にはポーズ制御はありません。

WebSocket 経由の Aura

wss://api.deepgram.com/v1/speak?model=aura-2-thalia-en&encoding=linear16&sample_rate=24000 に、 同じ Authorization: Token ヘッダーを付けて接続します。JSON テキストフレームを送信します。{"type":"Speak","text":"..."} でテキストをキューに追加し、{"type":"Flush"} で音声の出力を強制し、{"type":"Clear"} でバッファーを破棄し、{"type":"Close"} で終了します。音声はバイナリフレームで届き、Metadata、Flushed、Cleared、Warning は JSON で届きます。LLM が応答を完了したら Flush を送信します。Flush の送信は 60 秒あたり 20 回までです。ストリーミング出力の形式は、raw linear16（デフォルト）、mulaw、alaw のみです。

Aura ソケットには、リクエストあたりテキスト 2000 文字（接続終了コード 1009、ペイロード BIG-0001）、ソケットへの送信は Speak メッセージ全体でカウントして 1 分あたり 2400 文字（接続終了コード 1008、DATA-0001）、初回接続から 60 分間（接続終了コード 1011、NET-0003）という制限があります。より長い会話では、新しいソケットを開いてください。接続終了フレームのコードと、アップグレードに失敗した場合の dg-error ヘッダーは、https://developers.deepgram.com/docs/tts-troubleshooting-websocket-net-and-data-errors に記載されています。リージョン別ホストの api.eu.deepgram.com、api.au.deepgram.com、api.in.deepgram.com では、同じキーを使用して /v1/speak、REST、WebSocket を利用できます。

音声エージェント向け Flux TTS

wss://api.deepgram.com/v2/speak?model=flux-haley-en に接続します。model は必須で、flux-* 音声である必要があります。デフォルト値はなく、Aura の文字列は拒否されます。リージョン内で処理するには、wss://api.eu.deepgram.com/v2/speak、wss://api.au.deepgram.com/v2/speak、または wss://api.in.deepgram.com/v2/speak を使用します。利用できないリージョンが指定された場合、別のリージョンにルーティングされず、リクエストは失敗します。

セッションはターンの連続で構成されます。トークンをストリーミングしてから、ターンを終了します。

{"type": "Speak", "text": "Sure, I can "}
{"type": "Speak", "text": "help you cancel your subscription."}
{"type": "Flush"}
  • Flushを送信する前から音声のストリーミングが始まります。Flushでターンが終了し、その後サーバーから課金情報とタイミングを含むFlushedと SpeechMetadataが送信されます。Flushedのほうが先に届くため、ターンの終了はSpeechMetadataで判断してください。
  • サーバーは各ターンのSpeechStartedとSpeechMetadataでspeech_idを割り当てます。クライアントから送信しないでください。
  • 最初のメッセージはrequest_id、model_name、model_version、model_uuidsを含むConnectedです。 正常終了時の最後のメッセージは、セッションの累計値を含むSessionMetadataです。Interruptを送信すると、 total_audio_duration_msはクライアントが実際に再生した音声を基準に再計算されます。
  • サーバーから送信されるJSONメッセージはConnected、SpeechStarted、Flushed、SpeechMetadata、 SpeechInterrupted、ConfigureSuccess、ConfigureFailure、Warning、Error、SessionMetadataです。 Warningにはcodeとdescriptionが含まれ、セッションは開いたままです。Errorは致命的で、 すべてのDOMAIN-NNNNコード（MESSAGE-0000、DATA-0000、DATA-0002、BIG-0000、NET-0000から NET-0004）の後にWebSocketが切断されます。
  • バージイン時は、まずローカルでの再生を停止してから、 {"type":"Interrupt","playback_offset":{"type":"time_ms","value":2340}}を送信してください。
    • SpeechInterruptedにはtext_spokenとtext_remainingが返されます。text_spokenをLLMの コンテキストに戻してください。playback_offsetを指定しない場合、テキストは分割されません。
    • valueはこのターン開始からではなく、セッション開始から再生されたミリ秒数です。各Interruptの値は 前回のオフセットを上回る必要があります。そうでない場合はINVALID_INTERRUPT_OFFSETで無視されます。 次のオフセットの基準値として、SpeechInterruptedのaudio_played_msを読み取ってください。
  • {"type":"Configure","speed":1.15}を送信すると、セッション中に速度を変更できます。変更は次のセグメント境界で 適用されます。speedは0.5から1.5まで、0.05刻みで指定します。デフォルトは1.0です。
    • サーバーは適用された設定を含むConfigureSuccess、またはcodeとdescription（失敗が特定の項目に関連する場合は fieldとvalueも含む）を含むConfigureFailureを返し、以前の設定を維持します。
    • 0.45と1.55を指定すると'speed' must be between 0.5 and 1.5が返され、1.07を指定すると 'speed' must be provided in increments of 0.05が返されます。
    • ConfigureFailureコードはSPEED_OUT_OF_RANGE、SPEED_INCREMENT_INVALID、SPEED_NOT_SUPPORTED、 CONTROL_COMBINATION_INVALID（キュー内のターンに発音制御が残っています。先にそのターンをFlushしてください）、 INTERNAL_ERROR（有効な設定をサーバーが適用できなかった場合）です。
  • expressivityは-2（穏やか）から2（生き生きとした表現）までの整数で指定します。デフォルトは0です。 整数以外の値は指定できません。不正な値はWebSocketへのアップグレード完了前にHTTP 400で拒否されるため、 Connectedメッセージは届きません。小数（例：1.5）の場合はEXPRESSIVITY_INCREMENT_INVALID、 -2から2の範囲外の値の場合はEXPRESSIVITY_OUT_OF_RANGEが返されます。この機能はベータ版で、 接続ごとに固定されます（Configureでは変更できません）。本番環境で検証されている値は0のみです。
  • 発音制御はFlux TTS /v2/speakではEarly Accessです（Aura-2 /v1/speakではGAです。Aura RESTのセクションを参照してください）。 テキスト内のエスケープされたJSONオブジェクトとして、ソケットとバッチの両方で指定します。 \{"word":"dupilumab","pronounce":"duːˈpɪljuːmæb"\}。
    • 上限はリクエストあたり500件です。IPAは最大128文字で、元の単語の長さの10倍以下とします。ただし、下限は15文字です。
    • speedが1.0の場合のみ機能します。ソケットでは、別の速度で開いたセッションに発音を送信するか、 Configureで別の速度に設定した後に発音を送信すると、接続がDATA-0002で終了します。バッチでは、 リクエストが400 CONTROL_COMBINATION_INVALIDで拒否されます。
    • IPAが無効でもベストエフォートで適用され、ソケットではPRONUNCIATION_WARNINGS警告、バッチでは dg-warningsヘッダーで通知されます。
    • 構文とIPAのガイダンス：https://developers.deepgram.com/docs/tts-voice-controls
  • ポーズ制御の\{pause:500ms\}はバッチ専用です。
    • 制限：500～3000 msを100 ms刻みで指定し、リクエストあたり最大8個までです。隣接するポーズの間にはテキストが必要です。 ポーズが含まれる場合、speedは1.15以下に制限されます（PAUSE_SPEED_CAP_EXCEEDED）。 ポーズは指定した長さから約100 ms以内の精度で挿入されます。
    • ソケットでポーズマーカーを指定すると接続がDATA-0002で終了します。ポーズと発音を組み合わせると、 CONTROL_COMBINATION_INVALIDで拒否されます。
    • その他のバッチの400コードはBREAK_OUT_OF_RANGE、BREAK_INCREMENT_INVALID、 BREAKS_LIMIT_EXCEEDED、BREAK_SYNTAX_INVALIDです。BREAK_SYNTAX_INVALIDには2つの原因があります。 バックスラッシュなしの単純なマーカー、またはバックスラッシュ付きの構造化マーカーです。
    • 使用できる形式は\{pause:500\}（数値のみの場合はミリ秒）、\{pause:500ms\}、 \{pause:1.5s\}、およびエスケープされていない構造化形式の{pause:{duration_ms:500}}です。
  • 各ターンのSpeechMetadata.controls_appliedには、pronunciations_applied、breaks_applied、 pronunciation_warningsの数が記録されます。バッチでは、レスポンスヘッダーdg-pronunciations-appliedと dg-breaks-appliedが返されます。
  • ソケットではデフォルトのlinear16（誤り5を参照）を含め、未加工の音声のみがストリーミングされます。 バッチ専用のパラメーター（container、bit_rate、callback、callback_method、priority）や不明な パラメーターを指定すると、接続が終了します。
  • アイドル状態のセッションは60秒後に終了します（NET-0004）。ターン間にWebSocket Pingを送信してください。 すべてのセッションは1時間後に終了します（NET-0003）。
  • バッチ：POST https://api.deepgram.com/v2/speak?model=flux-haley-enに{"text": "..."}を送信すると、 音声レスポンスが1つ返されます。デフォルトはmp3で、opus、flac、aac、container、bit_rateを指定できます。 インラインポーズを処理できるのは、このトランスポートのみです。
  • SDK：すべてのDeepgram SDKにFlux TTSクライアントが含まれています。Python、JavaScript、Javaでは speak.v2という名前です。.NETにはFluxSpeakRESTClientとFluxSpeakWebSocketClientが含まれています。 Rustではspeak::flux、Goではv3.8.0以降のpkg/client/speak/v2を使用します。Flux TTSの全機能を説明している SDKスキルはRustのみです。PythonスキルにはFluxバッチのセクションが1つ（TextBuilderヘルパー）あります。 JS、Java、Go、.NETのtext-to-speech SDKスキルが扱うのは/v1/speakのみです。そのため、/v2/speakの メッセージ形式はこのスキルを参照してください。

音声

  • Aura：英語、スペイン語、ドイツ語、フランス語、オランダ語、イタリア語、日本語では aura-2-{voice}-{lang} を使用します。また、英語の Aura-1 音声が 12 種類あり、aura-{voice}-en という名前です。5 種類のスペイン語音声は、1 回のリクエスト内で英語とスペイン語を切り替えます：aura-2-aquila-es、aura-2-carina-es、aura-2-diana-es、aura-2-javier-es、aura-2-selena-es。カタログ：https://developers.deepgram.com/docs/tts-models
  • Flux TTS：英語とその他 41 言語に対応し、2 文字の言語サフィックスを持つ flux-{voice}-{language} を使用します。地域別のバリエーションは同じサフィックスを共有します。ブラジルポルトガル語とヨーロッパポルトガル語はどちらも -pt、フラマン語は -nl、スイスドイツ語は -de、標準中国語、台湾華語、広東語はすべて -zh です。そのため、カタログから音声名で選択してください。おすすめの英語音声には flux-haley-en、flux-alexis-en、flux-kit-en があります。カタログ：https://developers.deepgram.com/docs/flux-tts/voices

料金

テキスト読み上げは、Flux TTS、Aura-2、Aura-1 のいずれも入力テキスト 1,000 文字ごとに課金されます。料金はモデルやプランによって異なり、時間とともに変更されます。https://deepgram.com/pricing で確認してください。記憶に頼って数値を引用しないでください。

よくある間違い

  1. 認証スキームの誤りです。API キーは Authorization: Token <key> に指定します。Bearer は POST https://api.deepgram.com/v1/auth/grant で取得する短時間有効な JWT 専用です。キーを Bearer で送ると 401 が返されます。

  2. モデルエラーの読み違いです。スペルミスを含め、存在しないモデル名の場合は、400 と {"err_code":"Bad Request","err_msg":"Bad Request: No such model/language/tier combination found."} が返されます。 モデルは存在するものの、プロジェクトで使用できない場合は 403 と {"err_code":"INSUFFICIENT_PERMISSIONS","err_msg":"Project does not have access to the requested model."} が返されます。400 の場合は、上記のカタログでモデル名を確認してください。アクセスを申請するのは 403 の場合だけです。

    GET https://api.deepgram.com/v1/models が返すのは公開カタログであり、キーで利用できるモデルではありません。また、tts リストには Aura の音声のみが含まれ、flux-* の項目はありません。Flux TTS の音声名は https://developers.deepgram.com/docs/flux-tts/voices で確認してください。

  3. 音声を JSON として解析することです。どちらのエンドポイントでも、成功時の本文はバイト列です。まずステータスで分岐してください。

  4. ファミリーを混同することです。/v2/speak で Aura 音声を使用した場合も、/v1/speak で Flux TTS 音声を使用した場合も失敗します。また、/v2/speak では model の指定がない場合も拒否されます。

  5. WebSocket で mp3 を要求することです。どちらのエンドポイントでも、ストリーミングされるのは生の音声データです。圧縮形式の出力には REST を使用してください。

  6. Flux TTS がテキストを整えてくれると期待することです。Speak のテキストはそのまま連結されるため、"Hello world." の後に "How are you?" を指定すると "Hello world.How are you?" になります。応答、ツールの結果、次の応答をつなぐときは、スペースを挿入してください。

    プレーンテキストを送信してください。SSML は解釈されません。Flux TTS が認識するマークアップは、独自のエスケープされた制御構文のみで、発音指定は両方のトランスポートで、ポーズ指定はバッチでのみ有効です。認識対象の SSML、ElevenLabs、Cartesia のタグは除去され、Speak ごとに INPUT_MARKUP_STRIPPED 警告が 1 回返されます。検出器が認識しないマークアップ（Markdown、HTML、カスタム XML）はそのまま転送され、読み上げられる場合があります。https://developers.deepgram.com/docs/flux-tts/client-messages を参照してください。

  7. Voice Agent を api.deepgram.com に接続することです。Voice Agent API の接続先は wss://agent.deepgram.com で、agent.speak.provider.version に基づいて TTS ファミリーが選択されます。Flux TTS は v2、Aura は v1 です。agent.speak を省略すると、flux-kit-en を使用した Flux TTS になります。

    • エージェントが受け付けるのは、英語の Flux TTS 音声のみです。現時点では、ほかの 41 言語は /v2/speak 専用です。そのため、英語以外のエージェント音声には Aura-2（v1）の音声か、サードパーティープロバイダーを使用してください。
    • エージェント内の速度と expressivity は agent.speak.provider に指定します。https://developers.deepgram.com/docs/voice-agent-tts-controls を参照してください。
    • インラインのポーズマーカーは読み上げられず、エラーも返されないため、これを含むテキストは無音になります。間の調整には句読点と数字の区切りを使用してください。
    • audio.output に圧縮エンコーディング（mp3、opus、flac、aac）または wav などのコンテナ形式を指定すると、INVALID_SETTINGS が返されます。agent.speak を省略する場合も含め、これらの形式には Aura（v1）の音声を設定してください。

  8. 対応していない言語で音声制御を使用することです。Flux TTS の speed、ポーズ、発音指定が文書化されているのは英語の音声のみです。また、Aura-2 の速度と発音指定は英語とスペイン語のみを対象とします。それ以外の音声では、句読点で速度を調整してください。

別のスキルを使う場合

  • すべてのパラメーター、列挙型、メッセージスキーマが必要な場合：api スキルのファイル references/speak.md を参照してください。
  • 名前のわからないドキュメントページが必要な場合：docs スキルを使ってください。
  • 実行可能なアプリが必要な場合：starters スキルを使ってください。対応する機能は text-to-speech（Aura REST）、live-text-to-speech（Aura WebSocket）、flux-tts（node、flask、fastapi、django、java のみ）です。
  • 50 行未満のスニペットが必要な場合：recipes スキルを使ってください。レシピが対応しているのは Aura の /v1/speak のみで、Flux TTS のレシピはまだありません。
  • サードパーティのプラットフォームと接続する場合：examples スキルを使ってください（現時点では Aura に対応）。Twilio と Flux TTS を使う場合は、deepgram-sdk 7.6.0 以降が必要な https://developers.deepgram.com/docs/twilio-and-deepgram-tts に従ってください。
  • コーディングツール内でドキュメントを参照したい場合：setup-mcp スキルを使ってください。
  • 1 つの言語で慣用的なコードが必要な場合：SDK リポジトリの deepgram-{js,python,java,go,rust,dotnet}-text-to-speech スキルを使ってください（npx skills add deepgram/deepgram-python-sdk など）。Flux TTS の詳細な説明があるのは Rust SDK スキルのみです。Flux TTS セクションの SDK の箇条書きを参照してください。
  • Deepgram に 1 つの接続で音声テキスト変換、LLM、TTS を実行させたい場合：voice-agent スキルと deepgram-{lang}-voice-agent を使ってください。
  • 合成ではなく文字起こしを行う場合：speech-to-text スキルを使ってください。「Flux」という名前は /v2/listen の音声テキスト変換製品と、この /v2/speak のテキスト音声変換製品の両方を指すことに注意してください。

参照元

すべてのページは Markdown 形式で利用できます（任意の URL に .md を追加してください）。インデックスは https://developers.deepgram.com/llms.txt にあります。

コメント

Markdown 対応