api

Deepgram API

Deepgram の音声テキスト変換、テキスト音声変換、ボイスエージェント、音声インテリジェンス API を活用しましょう。

「Flux」は、別々の 2 つの製品の名称です。 Flux STT は /v2/listen（model=flux-general-en）を使用する会話型の音声テキスト変換です。Flux TTS は /v2/speak（model=flux-{voice}-{language}）を使用するターンベースの音声合成です。どちらも同じ名称と設計思想（ターンを認識し、ボイスエージェント向けに構築）を共有していますが、エンドポイント、モデル、パラメーター、メッセージはそれぞれ異なります。リクエストで単に「Flux」と指定されている場合は、音声の文字起こしについてなのか、音声の生成についてなのかを確認してください。

はじめに

すべての API リクエストでは、API キーまたは JWT による認証が必要です。

• API キー：Authorization: Token <API_KEY>
• JWT：Authorization: Bearer <JWT>

ベースサーバー：

• REST および STT/TTS WebSocket：https://api.deepgram.com
• ボイスエージェントの WebSocket および GET /v1/agent/settings/think/models：https://agent.deepgram.com

GET /v1/agent/settings/think/models も agent. ホスト上にあり、api. 上にはありません。api.deepgram.com では 404 を返し、agent.deepgram.com では 200 を返します。それ以外の REST エンドポイントはすべて api.deepgram.com にあります。

リージョナルエンドポイント

処理を特定の地域内にとどめるには、ホストを切り替えてください。API キー、パス、SDK はそのままで、ベース URL のみが変わります。リクエストがリージョン外にルーティングされることはありません。そのリージョンが利用できない場合は、フォールバックせずに失敗します。

リージョン	ホスト
EU	api.eu.deepgram.com
オーストラリア	api.au.deepgram.com
インド	api.in.deepgram.com

データプレーンはリージョナルですが、Projects 管理 API はリージョナルではありません。 3 つのリージョナルホストすべてで、以下のようになります。

エンドポイント	リージョナル対応
POST /v1/listen、wss://…/v1/listen	はい
wss://…/v2/listen	はい
POST /v1/speak、wss://…/v1/speak	はい
POST /v2/speak、wss://…/v2/speak	はい
POST /v1/read	はい
wss://…/v1/agent/converse	はい
GET /v1/models	はい
POST /v1/auth/grant	はい
/v1/projects/*（キー、メンバー、使用状況、請求）	いいえ — 404

注意が必要なホストのルールが 2 つあります。

1. リージョナル環境では、ボイスエージェントの接続先が api. ホストに変わります。 agent.eu.deepgram.com は存在せず（名前を解決できません）、wss://api.eu.deepgram.com/v1/agent/converse を使用してください。GET /v1/agent/settings/think/models も同様に切り替わります。グローバル環境では、引き続き agent.deepgram.com を使用します。
2. 管理系の呼び出しは api.deepgram.com に向けてください。 クライアントの管理系呼び出しをリージョナルホストに向けると、/v1/projects は 404 を返します。そのため、アプリで文字起こしとキー管理の両方を行う場合は、呼び出しの種類に応じてベース URL を分けてください。

Whisper モデルは 3 つのリージョンのいずれでも提供されていません。そこで使用する場合は、Nova または Flux STT モデルを選んでください。

Deepgram Dedicated およびセルフホスト可能なホストについては、 カスタムエンドポイントをご覧ください。 リージョンごとの機能一覧と SDK のコード例については、 リージョナルエンドポイントをご覧ください。

Deepgram の API の連携方法

                   ┌──────────────────────────────┐
                   │       api.deepgram.com        │
                   └──────────────────────────────┘
                                │
  ┌───────────┬───────────┬─────┴─────┬───────────┬───────────┐
  ▼           ▼           ▼           ▼           ▼           ▼
  /v1/listen  /v2/listen  /v1/speak   /v2/speak   /v1/read    /v1/projects/*
  Nova — STT  Flux — STT  Aura — TTS  Flux — TTS  Text AI     Management
  REST + WSS  WSS only    REST + WSS  REST + WSS  REST only   REST only

                   ┌──────────────────────────────┐
                   │      agent.deepgram.com       │
                   └──────────────────────────────┘
                                │
                                ▼
                   /v1/agent/converse
                   WebSocket only
                   audio ──▶ STT ──▶ LLM ──▶ TTS ──▶ audio
                   (Deepgram orchestrates the full pipeline)

どの API を使用すべきですか？

Audio → text (transcription)?
├─ General-purpose transcription (captions, batch, call logs, live streams with custom turn logic)
│  └─ Nova models via /v1/listen
│     ├─ Pre-recorded file    →  REST  POST https://api.deepgram.com/v1/listen?model=nova-3
│     └─ Live stream          →  WSS   wss://api.deepgram.com/v1/listen?model=nova-3
│
└─ Conversational audio / voice-agent-style turn detection
   └─ Flux STT models via /v2/listen
      └─ Live stream          →  WSS   wss://api.deepgram.com/v2/listen?model=flux-general-en

Text → audio (speech synthesis)?
├─ General-purpose TTS (broadest voice catalog, compressed/containerized audio)
│  └─ Aura models via /v1/speak
│     ├─ One-shot             →  REST  POST https://api.deepgram.com/v1/speak?model=aura-2-thalia-en
│     └─ Low-latency stream   →  WSS   wss://api.deepgram.com/v1/speak?model=aura-2-thalia-en
│
└─ Voice-agent TTS (turn-based lifecycle, barge-in, cross-turn consistency)
   └─ Flux TTS models via /v2/speak  — model is REQUIRED, and must be flux-*
      ├─ Pre-render a block   →  REST  POST https://api.deepgram.com/v2/speak?model=flux-alexis-en
      └─ Live conversation    →  WSS   wss://api.deepgram.com/v2/speak?model=flux-alexis-en

Full conversational voice agent (audio in, audio out)?
└─ WSS wss://agent.deepgram.com/v1/agent/converse
   Deepgram handles STT + your configured LLM + TTS internally

Analyze text for insights?
└─ REST POST /v1/read
   (summaries, sentiment, topics, intents)

音声テキスト変換：Nova（/v1/listen）と Flux STT（/v2/listen）

どちらのモデルファミリーも積極的に保守されており、業界をリードしています。それぞれ異なる課題を解決するため、ユースケースに合ったものを選んでください。

	Nova（/v1/listen）	Flux STT（/v2/listen）
エンドポイント	/v1/listen	/v2/listen
利用可能なモデル	nova-3（nova-3-medical、nova-3-pharma もあります）、nova-2、nova、enhanced、base	flux-general-en、flux-general-multi
最適な用途	一般的な文字起こし — キャプション、字幕、通話ログ、バッチ処理	会話音声 — 音声エージェント、インタラクティブなアシスタント、ターンテイキング対応の UI
出力	連続した文字起こしストリーム	構造化されたターンイベントと文字起こし（ターン状態機械を内蔵）
ターン検出	手動（utterance_end_ms、VAD イベント）	内蔵（EOT、eager-EOT、turn_index）
トランスポート	REST と WebSocket	WebSocket のみ
インテリジェンスのオーバーレイ	はい — summarize、sentiment、topics、intents、diarize_model、redact など	いいえ — パラメーターセットを絞り込んでおり、smart_format／diarize_model／punctuate はありません
セッション中の再設定	いいえ（変更するには再接続が必要です）	はい（Configure メッセージで、EOT のしきい値、キーターム、言語ヒント、numerals を実行中に更新できます）

次の場合は Nova（/v1/listen、model=nova-3）を選んでください：

• 録画メディアのキャプション、字幕、文字起こしを生成する
• ファイルのバッチ文字起こしを実行する（REST）
• 分析オーバーレイ（summarize、sentiment、topics、intents、diarize_model、redact）が必要
• 独自のターン検出ロジックで WebSocket ストリーミングを利用したい

次の場合は Flux STT（/v2/listen、model=flux-general-en）を選んでください：

• インタラクティブな音声エージェントまたはアシスタントを構築する
• ターン終了の検出を任せたい
• 低レイテンシーのターンシグナルと割り込み対応が必要
• 再接続せずに、セッション中に EOT のしきい値、キーターム、言語ヒント、numerals を更新したい

Nova 3 から Flux STT への移行については、公式の Nova 3 から Flux への移行ガイドをご覧ください。

テキスト読み上げ：Aura（/v1/speak）と Flux TTS（/v2/speak）

どちらの TTS ファミリーも積極的にメンテナンスされています。/v2/speak は置き換えではなく、新しいエンドポイントです。/v1/speak に変更はなく、エイリアス、リダイレクト、非推奨化もありません。両ファミリーに重複はありません。Aura の音声は /v1/speak でのみ、Flux TTS の音声は /v2/speak でのみ提供されます。

	Aura（/v1/speak）	Flux TTS（/v2/speak）
エンドポイント	/v1/speak	/v2/speak
モデル	aura-2-*（en、es、de、nl、fr、it、ja）、aura-*	flux-{voice}-{language}（例：flux-alexis-en）— ローンチ時は英語
model パラメーター	任意（デフォルトは aura-asteria-en）	必須。aura-* 文字列は拒否されます
最適な用途	最も幅広い音声カタログ、多言語、圧縮音声、1 回の合成	音声エージェント — LLM 出力のストリーミング、割り込み、複数ターンの会話
基本的な考え方	テキストバッファー → 音声ストリーム	ストリーミング優先、ターンベースの会話
ターンのライフサイクル	なし	ターンごとに SpeechStarted → 音声 → Flushed → SpeechMetadata（サーバーが speech_id を割り当て）
ターン間のコンテキスト	なし（リセットするには再接続）	プロソディはターン間で自動的に維持されます — API サーフェスはありません
トランスポート	REST + WebSocket	REST（バッチ）+ WebSocket（ストリーミング）
ストリーミングのエンコーディング	linear16、mulaw、alaw	linear16、mulaw、alaw — 生の音声のみ
バッチのエンコーディング	mp3、opus、flac、aac、linear16、mulaw、alaw + container / bit_rate	同じ — ただしバッチ専用です。ソケットでは拒否されます
割り込み	Clear はバッファーを破棄しますが、フィードバックはありません	Interrupt → text_spoken / text_remaining を含む SpeechInterrupted
ストリーム中の再設定	不可（接続時に固定）	可能 — Configure で speed のみ更新
speed	0.7～1.5。Aura-2 の英語とスペイン語のみ	0.05 刻みで 0.5～1.5。テキストにポーズマーカーが含まれる場合は 1.15 が上限です（それを超えると PAUSE_SPEED_CAP_EXCEEDED）。発音ルールについてはインライン制御を参照してください
expressivity	非対応	-2～2、デフォルトは 0（ベータ版。接続時に固定）
インライン制御	発音 \{"word":"...","pronounce":"<IPA>"\}（Aura-2 の英語とスペイン語で GA、入力は最大 2000 文字、speed と併用可能）。ポーズ制御はありません	発音（アーリーアクセス、両方のトランスポート）は speed が正確に 1.0 の場合のみ使用可能。バッチでは CONTROL_COMBINATION_INVALID、ソケットでは DATA-0002 が返されます。ポーズ \{pause:500ms\} はバッチのみで、500～3000 ms、100 ms 刻み、リクエストごとに最大 8 個
Voice Agent の provider.version	v1（プロバイダーを指定した場合のデフォルト）	v2（必須）

次の場合は Aura（/v1/speak）を選択してください。

• 英語以外の言語、または特定の Aura 音声が必要な場合
• Voice Agent 内で圧縮出力（mp3、opus、flac、aac）が必要な場合。Flux TTS は INVALID_SETTINGS を返します。バッチ REST では、両ファミリーがこれらのエンコーディングを提供します
• すでに Aura を使用していて、Flux TTS に乗り換える理由がない場合。v1 に変更はありません

次の場合は Flux TTS（/v2/speak）を選択してください。

• 音声エージェント、電話アシスタント、またはカスタマーサービスボットを構築する場合
• LLM のトークンをスピーカーにリアルタイムでストリーミングし、最初の音声が出るまでの時間を最短にしたい場合
• ユーザーが応答の途中で割り込む可能性があり、実際に聞こえた内容を把握する必要がある場合
• 状態を自分で管理せずに、ターンをまたいでトーンを維持したい場合
• Flux TTS 音声で固定音声（IVR プロンプト、通知）を事前に生成する場合 — バッチ REST トランスポートを使用してください

Aura から移行しますか？公式の Migrating from Aura to Flux TTS ガイドと Batch vs Streaming をご覧ください。

API ドメイン

ドメイン	REST	WebSocket	リファレンス
Listen v1 — STT、Nova モデル	POST /v1/listen	wss://api.deepgram.com/v1/listen	listen.md
Listen v2 — STT、Flux STT（会話型）	—	wss://api.deepgram.com/v2/listen	listen.md
Speak v1 — TTS、Aura モデル	POST /v1/speak	wss://api.deepgram.com/v1/speak	speak.md
Speak v2 — TTS、Flux TTS（ターンベース）	POST /v2/speak	wss://api.deepgram.com/v2/speak	speak.md
Voice Agent	GET agent.deepgram.com/v1/agent/settings/think/models; 再利用可能なエージェント設定は /v1/projects/{project_id}/agents（GET、POST）および /v1/projects/{project_id}/agents/{agent_id}（GET、PUT、DELETE）にあります。エージェント変数は /v1/projects/{project_id}/agent-variables（GET、POST）および /v1/projects/{project_id}/agent-variables/{variable_id}（GET、PATCH、DELETE）にあります	wss://agent.deepgram.com/v1/agent/converse	agent.md
Read（Intelligence）	POST /v1/read	—	read.md
Models	GET /v1/models、GET /v1/models/{model_id}、GET /v1/projects/{project_id}/models、GET /v1/projects/{project_id}/models/{model_id}。いずれかの一覧取得で include_outdated=true を指定すると、最新ではないモデルバージョンも返されます	なし	models.md
Projects	/v1/projects/*	—	projects.md
Auth	POST /v1/auth/grant	—	auth.md
セルフホスト	/v1/projects/*/self-hosted/*	—	self-hosted.md

よくある間違いとその回避方法

すべての API

1. Voice Agent と v2 のセッション中の更新を除き、機能フラグはクエリパラメーターです。 /v1/listen、/v2/listen、/v1/speak、/v2/speak では、初期オプションを URL に指定します。Listen ではリクエストボディに音声（REST）または音声フレーム（WebSocket）を含めます。Speak ではテキストを含めます（REST の JSON text フィールド、または WebSocket の Speak メッセージ）。例外として、/v1/agent/converse には URL クエリパラメーターがなく、すべての設定は Settings メッセージに指定します。また、/v2/listen は接続後に Configure メッセージをサポートしており、セッション中に EOT しきい値、keyterms、言語ヒント、numerals を更新できます。さらに、/v2/speak は speed のみを更新する Configure メッセージをサポートしています。なお、/v2/listen のパラメーターセットは /v1/listen よりかなり少なく、smart_format、diarize_model、punctuate などのフラグは使用できません。

2. レート制限はリクエスト総数ではなく、同時接続数に適用されます。 429 はリクエスト量が多すぎることではなく、開いたままの接続が同時に多すぎることを示します。話者分離など、計算負荷の高い機能を使うと、同時接続数の上限はさらに低くなります。制限は API キー単位ではなくプロジェクト単位で適用され、リージョンによって異なります。リージョンごとの同時接続数の表は、API Rate Limits のページをご確認ください。

STT WebSocket (/v1/listen)

3. KeepAlive はバイナリではなくテキストフレームとして送信してください。 音声が 10 秒間途切れると接続が閉じられます。無音の間は 3～5 秒ごとに {"type":"KeepAlive"} をテキスト（JSON）フレームとして送信してください。バイナリフレームとして送信すると、無視されるのではなく、音声パイプラインが詰まって文字起こしが遅延します。

4. 空のバイトペイロードは絶対に送信しないでください。 /v1/listen に長さゼロのバイナリフレームを送信すると、クローズとして扱われ、接続が終了します。送信前に、音声パケットにデータが含まれていることを必ず確認してください。

5. encoding は実際の音声形式と一致させてください。 encoding=linear16 を指定しながら opus を送信すると、DATA-0000 エラーが発生するか、出力が文字化けします。コンテナ形式（mp3、wav、ogg）を送信する場合は、encoding を省略してください。Deepgram が自動的に検出します。

6. 再接続時にタイムスタンプはリセットされます。 WebSocket 接続を新たに確立するたびに、タイムスタンプは 00:00:00 から再開します。リアルタイムアプリでは、再接続をまたいでタイムスタンプのオフセットを保持してください。そうしないと、文字起こしのタイムラインが気付かないうちに破損します。

TTS WebSocket (/v1/speak)

7. 空のテキストは送信しないでください。 text フィールドが空の Speak メッセージを送信すると、400 エラーが返されます。送信前に必ず入力を検証してください。

8. 文字数レート制限（DATA-0001）が発生した場合は、再試行ではなく送信速度を落としてください。 このエラーが発生した場合は、テキストチャンクの送信速度を下げてください。すぐに再試行すると、問題がさらに悪化します。

Flux TTS（/v2/speak）

9. modelは必須で、flux-*の音声を指定する必要があります。 /v1/speakとは異なり、デフォルト値はありません。modelを指定せずに接続またはリクエストすると、拒否されます。/v2/speakではAuraの文字列が拒否され、Fluxの音声は/v1/speakでは提供されません。この2つのファミリーが混在することはありません。モデル文字列はflux-{voice}-{language}の形式です。例：flux-alexis-en。バージョン部分はありません。Flux STTと同様に、世代は安定した名前のまま更新されていきます。

10. Flushはターンを終了します。v1形式のバッファーフラッシュではありません。 Finalizeはなく、その役割はFlushに統合されています。フラッシュする前から音声のストリーミングが自動的に始まるため、テキストを送るのを待たないでください。ターン終了のシグナルにはFlushedではなく、そのターンのSpeechMetadataを使用してください。これはターンの音声がすべて送信された後に一度だけ届き、課金とタイミングのカウントを含むため、クライアント側で文字数や再生時間を追跡する必要はありません。サーバーがターンのspeech_idを割り当てます。自分で送信しないでください。

11. ストリーミングでは生の音声のみを扱い、認識できないものはすべて拒否されます。 WebSocketはコンテナ化されていない音声を出力するため、encodingにはlinear16（デフォルト）、mulaw、alawのみを指定できます。圧縮形式およびコンテナ形式のエンコーディング（mp3、opus、flac、aac）と、container、bit_rate、callback、callback_method、priorityパラメーターはバッチ専用です。これらをソケットに送信すると接続に失敗し、未知のパラメーターやスペルミスのあるパラメーターを送信した場合も同様です。圧縮出力が必要な場合は、バッチRESTトランスポートを使用してください。

12. 別々の生成結果をつなぐときは空白を挿入してください。サーバー側では挿入されません。 合成前にテキストの正規化が行われますが、連続するSpeakメッセージはそのまま連結されます。"Hello world."の後に"How are you?"を送信すると、"Hello world.How are you?"として処理され、文の境界にアーティファクトが生じます。返信、ツール呼び出しの結果、次の返信をつなぐときは、半角スペースを1つ（または空白を使わない言語では適切な区切り）追加してください。プレーンテキストを送信してください。SSMLは解釈されず、Flux TTSが認識するマークアップは、エスケープされた独自のインライン制御だけです。発音指定\{"word":"...","pronounce":"<IPA>"\}は両方のトランスポートで利用できます（早期アクセス）が、speedが1.0の場合に限られます。一方、一時停止マーカー\{pause:500ms\}はバッチ専用です。ソケットで一時停止マーカーを使う場合、またはspeedが1.0以外のソケットで発音制御を使う場合、DATA-0002で接続に失敗します。バッチのPOST /v2/speakでは、同じ違反が400エラーとなり、err_codeに該当するルール名が設定されます。CONTROL_COMBINATION_INVALID（一時停止との併用、またはspeedが1.0以外の発音指定）、PAUSE_SPEED_CAP_EXCEEDED（speedが1.15を超える場合の一時停止マーカー）、BREAK_OUT_OF_RANGE（500〜3000 msの範囲外の一時停止）、BREAK_INCREMENT_INVALID（100 ms刻みではない一時停止）、BREAKS_LIMIT_EXCEEDED（一時停止マーカーが8個を超える、またはテキストを挟まずに2つ連続する場合）、BREAK_SYNTAX_INVALID（バックスラッシュのない単純なマーカーや、エスケープされた構造化マーカーなど、不正な形式のマーカー）。speedがちょうど1.0の場合は速度制御として扱われないため、これらの違反は発生しません。速度、一時停止、発音を参照してください。

音声エージェント（/v1/agent/converse）

13. 音声を送信する前に、Settings メッセージを送信してください。 エージェントは、Settings の設定を受信して確認するまで、すべてのメッセージを無視します。メッセージの順序は厳密に守る必要があります。

14. agent.speak.provider.version は TTS の系統を選択します。また、agent.speak を省略すると Flux TTS が使用されます。 Flux TTS には version を v2 に、Aura には v1 に設定してください。プロバイダーを指定して version を省略した場合、デフォルトは v1 です。ただし、agent.speak 全体を省略すると、エージェントは flux-kit-en 音声の Flux TTS をデフォルトで使用します。系統を切り替える場合は、version と model を同時に変更してください。v1 での flux-* モデル、または v2 での aura-* モデルは無効です。

    { "agent": { "speak": { "provider": { "type": "deepgram", "version": "v2", "model": "flux-alexis-en" } } } }
    

15. GET /v1/agent/settings/think/models は api.deepgram.com ではなく、agent.deepgram.com にあります。 agent.think.provider で指定できる LLM の一覧を取得する GET /v1/agent/settings/think/models は、api.deepgram.com では 404 を返し、agent.deepgram.com では 200 を返します。同じキー、同じパスで、異なるのはホストだけです。そのため、ベース URL をハードコードしたクライアントでは、機能が存在しないように見える 404 が気づかないうちに発生します。3 つのリージョン別 api.* ホストでも利用できます。

Flux STT モデル（/v2/listen）

16. /v2/listen と flux-general-* モデルを使用してください。 提供されているモデルは 2 つです。flux-general-en（英語）と、language_hint／language_hints を受け付ける唯一のモデルである flux-general-multi（多言語）です。/v1/listen は Flux STT をサポートしておらず、model=flux だけでは有効な値になりません。コンテナ化された音声には、language または encoding パラメーターを含めないでください。

17. セッション中に EOT のしきい値、キーターム、言語ヒント、numerals を更新するには、Configure を使用してください。 /v1/listen とは異なり、Flux STT は接続後の再設定に対応しているため、ターン検出の感度を変更したり、新しいキータームの重み付けを上げたり、言語検出の重み付けを変更したり（language_hints は flux-general-multi のみ）、PIN や注文番号のために numerals をオンにしたりする際に、再接続する必要はありません。

    { "type": "Configure", "thresholds": { "eot_threshold": 0.8, "eot_timeout_ms": 3000 }, "keyterms": ["Deepgram"] }
    

    サーバーは、送信したフィールドだけでなく、numerals も含めた有効な設定全体をエコーする ConfigureSuccess、または拒否された設定を示す code と description を含む ConfigureFailure を返します。省略したしきい値フィールドには、現在の値が維持されます。

18. ターン外での ForceEndTurn はエラーではなく Warning であり、ソケットは開いたままです。 ターンが進行していないときに {"type":"ForceEndTurn"} を送信すると、{"type":"Warning","code":"FORCE_END_TURN_NO_ACTIVE_TURN","description":"Received ForceEndTurn while no turn was active; the request was ignored."} が返され、接続は継続します。これを致命的なエラーとして扱ったり、再接続したりしないでください。メッセージ形式（ListenV2Warning：code、description、request_id、sequence_id）については references/listen.md を参照してください。ここでの code は任意の文字列であり、FORCE_END_TURN_NO_ACTIVE_TURN などの個別のコードはForce End Turn のドキュメントに記載されています。ForceEndTurn がターンの途中で処理されると、結果の TurnInfo には trigger: "manual" を伴う event: "EndOfTurn" が含まれます。trigger は model | manual | timeout で、EndOfTurn にのみ表示されます。また、値が追加される可能性がある列挙型のため、認識できない値も許容してください。

Nova diarization（/v1/listen）

19. diarize_modelを使用し、diarizeと一緒に送信しないでください。 diarizeは非推奨です。diarize_modelは話者ダイアライゼーションを有効にすると同時にバージョンを選択するため、diarize=trueを併せて指定する必要はありません。両方を送信するとリクエストは失敗します：400 "diarize_model cannot be used together with diarize or diarize_version." バッチ処理ではlatest、v1、v2（現在、latestはv2）、ストリーミングではlatestまたはv1を指定できます。話者ダイアライゼーションが有効な場合、metadata.diarize_infoに実際に実行されたモデル（{"model_uuid": …, "arch": "v2"}）が報告されます。これがlatestがどのバージョンに解決されたかを確認する唯一の方法です。

テキストおよび音声インテリジェンス（/v1/read、/v1/listen）

20. /v1/readではlanguageが必須で、ほかの何よりも先に検証されます。 デフォルト値はありません。省略すると、400 INVALID_QUERY_PARAMETERが返され、メッセージは"Failed to deserialize query parameters: missing field language"となり、リクエスト内のほかの問題がすべて隠れてしまいます。対応言語は英語のみです。language=multiは拒否され、en-USは受け付けられますが、応答ではenとして返されます。知っておくべき/v1/readの仕様がさらに2つあります。JSONボディにはtextまたはurlのどちらか一方のみを指定します（両方またはどちらも指定しない場合はPAYLOAD_ERRORとなり、音声を指定するとREMOTE_CONTENT_ERRORになるため、urlはプレーンテキストのドキュメントを指している必要があります）。また、POSTのみ対応です（GETとWebSocketへのアップグレードはいずれも405を返します）。/v1/readのsummarizeはtrueだけでなくv2も受け付けます。結果のパスはエンドポイントによって異なります。/v1/readはresults.summary.textを、/v1/listenはresults.summary.shortを返すため、両方を処理するコードでは分岐が必要です（どちらもsentimentはresults.sentimentsに対応します）。

21. Novaのストリーミングソケットで動作するのはdetect_entitiesのみです。ほかの4つはそれぞれ異なる3種類の方法で失敗します。 detect_entities=trueはサポートされており、各Resultsメッセージの最上位にあるchannelの隣にentitiesが配置されます。channel.alternatives[0]の内側ではありません。ほかの4つは録音済み音声のみ対応です。summarizeはハンドシェイクで400 "Summarization is not available for streaming."を返して失敗します。topicsとintentsは403 UNAUTHORIZED_FEATURES_REQUESTEDで失敗します。同じキーで録音済み音声のtopics／intentsリクエストが200を返す場合でも、キーの権限に問題があるように見えるエラーです。そして、落とし穴なのがsentimentです。ハンドシェイクは成功し、エラーも送信されず、結果にセンチメントが表示されることもありません。

認証

22. JWTのTTLが適用されるのは最初のハンドシェイクのみです。 トークンのデフォルトの有効期間は30秒です。WebSocket接続が確立された後は、トークンの期限が切れても接続は閉じません。トークンが必要なのはアップグレードリクエストのみです。

SDK固有のスキル

このapiスキルでは、SDK間で共通する製品仕様（エンドポイント、クエリパラメーター、メッセージ形式）を扱います。各言語に適したコード（インポート、非同期パターン、ビルダーAPI、よくあるエラー）を確認するには、SDK固有のスキルをインストールしてください。各Deepgram SDKは、deepgram-{lang}-{product}という名前の製品スキルを7つ公開しています（例：deepgram-python-speech-to-text、deepgram-js-voice-agent）。deepgram-{lang}-というプレフィックスにより、複数のSDKのスキルをインストールする場合に名前が衝突しません。

# Install all skills from a specific SDK
npx skills add deepgram/deepgram-python-sdk     # Python
npx skills add deepgram/deepgram-js-sdk         # JavaScript / TypeScript
npx skills add deepgram/deepgram-java-sdk       # Java
npx skills add deepgram/deepgram-go-sdk         # Go
npx skills add deepgram/deepgram-rust-sdk       # Rust
npx skills add deepgram/deepgram-dotnet-sdk     # C# / .NET

# Or install a specific product skill from one SDK (note the deepgram-{lang}- prefix)
npx skills add deepgram/deepgram-python-sdk --skill deepgram-python-speech-to-text
npx skills add deepgram/deepgram-js-sdk     --skill deepgram-js-voice-agent

SwiftおよびKotlin SDKのスキルは、該当するリポジトリが公開されておらず、npx skills addでアクセスできないため、一覧には含まれていません。ブラウザーで作業する場合は、browser-agentスキルを開いてください。npmで公開されている4つのBrowser Agent SDKパッケージ（@deepgram/agents、@deepgram/react、@deepgram/ui、@deepgram/agents-widget）について説明しています。

関連する Deepgram スキル

スキル	目的
recipes	言語ごと、機能ごとの最小限の実行可能なスニペット
examples	サードパーティプラットフォーム（Twilio、LiveKit など）との完全な統合例
starters	実行可能なスターターアプリ（フレームワーク × 機能のマトリックス）
docs	Deepgram ドキュメントの参照
audio-intelligence	/v1/listen の summarize、sentiment、topics、intents、detect_entities パラメーター
text-intelligence	既に用意しているテキスト向けの POST /v1/read
browser-agent	ブラウザーでエージェントを実行するための Browser Agent SDK パッケージ
cli	シェルおよび CI 作業向けの deepctl
self-hosted	独自の GPU で Deepgram を実行する方法
setup-mcp	Deepgram MCP サーバーのインストール

ドキュメント

• API リファレンス
• 音声テキスト変換のスタートガイド
• テキスト音声変換ドキュメント（Aura）
• Flux TTS の概要
• Voice Agent ドキュメント
• Voice Agent TTS モデル
• Audio Intelligence
• セルフホスト型デプロイ
• リージョン別エンドポイント
• カスタムエンドポイント
• API レート制限：すべての API のリージョン別同時実行数テーブル。制限は API キーごとではなく、プロジェクトごとに適用されます
• 同時実行数のレート制限について