deepgram-python-conversational-stt

Deepgram Conversational STT / Flux の使用方法（Python SDK）

/v2/listen でターンを認識するストリーミング STT を利用できます。会話音声向けに最適化されており、ターン終了検出、早期 EOT、割り込みのシナリオに対応しています。

この製品を使用する場面

• 会話型 UI を構築しており、明示的なターン境界が必要な場合。
• Flux モデル（人間同士、または人間とエージェントの会話向けに最適化）を使用する場合。
• v1 の utterance_end より低レイテンシーでターンシグナルを取得したい場合。

次の場合は別のスキルを使用してください：

• 汎用の文字起こし（字幕、バッチ処理、非会話形式）が必要な場合 → deepgram-python-speech-to-text。
• 対話型エージェント全体（STT + LLM + TTS）が必要な場合 → deepgram-python-voice-agent。
• 分析（要約／感情分析）が必要な場合 → deepgram-python-audio-intelligence。

認証

import os
from dotenv import load_dotenv
load_dotenv()

from deepgram import DeepgramClient
client = DeepgramClient(api_key=os.environ["DEEPGRAM_API_KEY"])

ヘッダー：Authorization: Token <api_key>。WSS のみ対応しており、v2 には REST パスはありません。

クイックスタート

import threading, time
from pathlib import Path
from deepgram.core.events import EventType
from deepgram.listen.v2.types import (
    ListenV2CloseStream,
    ListenV2Connected,
    ListenV2FatalError,
    ListenV2TurnInfo,
)

with client.listen.v2.connect(
    model="flux-general-en",
    encoding="linear16",
    sample_rate="16000",
) as conn:

    def on_message(m):
        if isinstance(m, ListenV2TurnInfo):
            print(f"turn {m.turn_index} [{m.event}] {m.transcript}")
        elif isinstance(m, dict):                     # untyped fallback
            if m.get("type") == "TurnInfo":
                print(f"turn {m.get('turn_index')} [{m.get('event')}] {m.get('transcript')}")
        else:
            print(f"event: {getattr(m, 'type', type(m).__name__)}")

    conn.on(EventType.OPEN,    lambda _: print("open"))
    conn.on(EventType.MESSAGE, on_message)
    conn.on(EventType.CLOSE,   lambda _: print("close"))
    conn.on(EventType.ERROR,   lambda e: print(f"err: {type(e).__name__}: {e}"))

    def send_audio():
        for chunk in mic_chunks():                     # 80ms recommended
            conn.send_media(chunk)
            time.sleep(0.01)
        conn.send_close_stream(ListenV2CloseStream(type="CloseStream"))

    threading.Thread(target=send_audio, daemon=True).start()
    conn.start_listening()

主なパラメーター

パラメーター	備考
model	flux-general-en（英語）または flux-general-multi（多言語）。必須で、Flux モデルを指定する必要があります
encoding	linear16、mulaw など。コンテナー形式の音声では省略します
sample_rate	SDK のシグネチャでは文字列です（例："16000"）
eager_eot_threshold	この信頼度でターン終了を早期に通知します
eot_threshold	ターン終了の主な信頼度です。信頼度に基づく終了を抑制するには "1.0" を設定します
eot_timeout_ms	時間ベースのフォールバックによるターン終了です。eot_threshold="1.0" の場合も適用されます
keyterm	ドメイン固有のキーワードを優先します
mip_opt_out, tag	メタデータ／プライバシーフラグ
language_hint	flux-general-multi でのみ使用できます
authorization, request_options	認証またはリクエストオプションを上書きします

v2 には language パラメーターはありません。言語はモデル（flux-general-en）で指定するか、multi モデルで language_hint を使用して指定します。

アプリケーション側でターンを制御する場合は、eot_threshold="1.0" と十分に大きな eot_timeout_ms を設定してから、アクティブなターンに対して conn.send_force_end_turn() を呼び出します。ForceEndTurn を使用するには、デプロイメントで有効化する必要があります。examples/16-transcription-force-end-turn.py を参照してください。

イベント（サーバー → クライアント）

• ListenV2Connected — 接続が確立されました
• ListenV2ConfigureSuccess / ListenV2ConfigureFailure — セッション中の設定変更
• ListenV2TurnInfo — ターンごとの文字起こしとイベント（Update、EndOfTurn、EagerEndOfTurn、...）、および turn_index
• ListenV2FatalError — 致命的エラー

クライアントメッセージ：ListenV2Media、ListenV2Configure、ListenV2ForceEndTurn、ListenV2CloseStream。

非同期版

from deepgram import AsyncDeepgramClient
client = AsyncDeepgramClient()

async with client.listen.v2.connect(model="flux-general-en", ...) as conn:
    # same .on(...) handlers, then:
    await conn.start_listening()

API リファレンス（階層別）

1. リポジトリ内のリファレンス：reference.md の「Listen V2 Connect」。
2. AsyncAPI（WSS）：https://developers.deepgram.com/asyncapi.yaml
3. Context7：ライブラリ ID /llmstxt/developers_deepgram_llms_txt。
4. 製品ドキュメント：
   • https://developers.deepgram.com/reference/speech-to-text/listen-flux
   • https://developers.deepgram.com/docs/flux/quickstart
   • https://developers.deepgram.com/docs/flux/language-prompting

注意点

1. /v1/listen ではなく /v2/listen を使用してください。 ルートが異なり、クライアントのパスも異なります（listen.v2 と listen.v1）。
2. Flux モデルのみ使用できます。 nova-3、base などは拒否されます。flux-general-en または flux-general-multi を使用してください。
3. language パラメーターはありません。 言語はモデルの選択によって設定されます。flux-general-multi では language_hint を使用してください。
4. SDK では sample_rate は文字列です（例："16000"）。
5. ターン検出の遅延を最小限にするには、約80ミリ秒の音声チャンクを送信してください。
6. send_close_stream(ListenV2CloseStream(type="CloseStream")) で閉じてください。send_finalize は使用しないでください（これは v1 用です）。
7. メッセージは型付きオブジェクトまたは生の dict で届く場合があります。SDK は未知の型に construct_type を使用するタグ付きユニオンを使います。両方の分岐を処理してください（.fernignore 内の socket_client.py のパッチを参照）。
8. socket_client.py にはパッチが適用されており、変更しないでください（.fernignore → src/deepgram/listen/v2/socket_client.py を参照）。再生成時にこの手動パッチを上書きしないでください。再生成ワークフローで指示されている場合を除き、他の listen/v2 ファイルは生成ファイルとして扱ってください。
9. コンテナー化された音声（WAV、OGG など）では、encoding／sample_rate を省略してください。サーバーがコンテナーからそれらを検出します。

このリポジトリ内のサンプルファイル

• examples/14-transcription-live-websocket-v2.py
• tests/manual/listen/v2/connect/main.py

関連スキル

• deepgram-python-speech-to-text — 汎用の v1 音声テキスト変換（REST + WSS）
• deepgram-python-voice-agent — 対話型アシスタント一式

中核となるプロダクトスキル

言語を問わず Deepgram のプロダクトに関する知識を得るには、統合 API リファレンス、ドキュメント検索機能、実行可能な目的別レシピ、サードパーティー連携のサンプル、MCP のセットアップを含む中核スキルをインストールしてください。

npx skills add deepgram/skills

この SDK には各言語の慣習に沿ったコードスキルが含まれています。一方、deepgram/skills には言語を問わないプロダクト知識が含まれています（api、docs、recipes、examples、starters、setup-mcp を参照）。