deepgram-python-audio-intelligence

Deepgram Audio Intelligence の使用（Python SDK）

/v1/listen の文字起こしに適用される分析オーバーレイ：要約、トピック、インテント、感情、言語検出、話者分離、編集、エンティティ。STT と同じエンドポイント／同じクライアントメソッドを使用し、パラメーターで機能を有効にします。

この製品を使用する場合

• 音声（ファイル、URL、ライブストリーム）があり、文字起こしと併せて分析結果も取得したい場合。
• REST が主な方法です。ほとんどの分析機能は REST 専用です。

別のスキルを使用する場合：

• 分析なしで純粋な文字起こしが必要な場合 → deepgram-python-speech-to-text。
• 入力がすでに文字起こし済みのテキストの場合 → deepgram-python-text-intelligence（/v1/read）。
• 会話のターンテイキングが必要な場合 → deepgram-python-conversational-stt。
• 完全な対話型エージェントが必要な場合 → deepgram-python-voice-agent。

機能の利用可否：REST と WSS

機能	REST	WSS
diarize	はい	はい
redact	はい	はい
punctuate, smart_format	はい	はい
エンティティ検出	はい	はい
summarize	はい	いいえ
topics	はい	いいえ
intents	はい	いいえ
sentiment	はい	いいえ
detect_language	はい	いいえ
custom_topic / custom_intent	はい	いいえ

WSS 専用のサブセットについては、deepgram-python-speech-to-text と同じコードパスを使用します。

認証

from dotenv import load_dotenv
load_dotenv()

from deepgram import DeepgramClient
client = DeepgramClient()

ヘッダー：Authorization: Token <api_key>。

クイックスタート — REST での全分析機能

response = client.listen.v1.media.transcribe_url(
    url="https://dpgr.am/spacewalk.wav",
    model="nova-3",
    smart_format=True,
    punctuate=True,
    diarize=True,              # speaker separation
    summarize="v2",            # "v2" for the current model; True also accepted on /v1/listen
    topics=True,
    intents=True,
    sentiment=True,
    detect_language=True,
    redact=["pci", "pii"],     # or Sequence[str]
    language="en-US",
)

r = response.results
print("transcript:", r.channels[0].alternatives[0].transcript)
print("summary:",    r.summary)
print("topics:",     r.topics)
print("intents:",    r.intents)
print("sentiments:", r.sentiments)
print("detected_language:", r.channels[0].detected_language)

# Speaker diarization
for word in r.channels[0].alternatives[0].words or []:
    speaker = getattr(word, "speaker", None)
    if speaker is not None:
        print(f"Speaker {speaker}: {word.word}")

クイックスタート — REST ファイル

with open("call.wav", "rb") as f:
    audio = f.read()

response = client.listen.v1.media.transcribe_file(
    request=audio,
    model="nova-3",
    diarize=True,
    redact=["pii"],
    summarize="v2",
    topics=True,
)

クイックスタート — 単語レベルのタイミング付き話者分離

1 回のリクエストで話者の分離と単語レベルのタイムスタンプを有効にし、単語ごとのオブジェクトを反復処理して、タイミング付きの話者ラベル付き文字起こしを作成します。

response = client.listen.v1.media.transcribe_url(
    url="https://dpgr.am/spacewalk.wav",
    model="nova-3",
    diarize=True,        # tag each word with a speaker id
    smart_format=True,   # punctuated_word for cleaner output
    punctuate=True,
)

words = response.results.channels[0].alternatives[0].words or []

# Per-word: speaker, timestamps, confidence
for w in words:
    speaker = getattr(w, "speaker", None)
    text = w.punctuated_word or w.word
    print(f"[speaker {speaker}] {text}  ({w.start:.2f}s–{w.end:.2f}s, conf={w.confidence:.2f})")

# Group consecutive words by speaker into utterances
from itertools import groupby
for speaker, group in groupby(words, key=lambda w: getattr(w, "speaker", None)):
    text = " ".join((w.punctuated_word or w.word) for w in group)
    print(f"Speaker {speaker}: {text}")

各エントリーで利用できる単語ごとのフィールド：

フィールド	型	説明
word	str	小文字のトークン
punctuated_word	str | None	スマートフォーマットで大文字・小文字や句読点を適用したトークン（smart_format=True の場合）
start, end	float	音声内のタイムスタンプ（秒）
confidence	float	信頼度（0.0～1.0）
speaker	int | None	話者 ID（diarize=True の場合）。話者分離が無効の場合は None
speaker_confidence	float | None	話者 ID の信頼度

より高いレベルの内訳を取得するには、utterances=True を設定して、response.results.utterances にあらかじめグループ化された話者ターンを取得します。話者ターンの境界ごとに整理された paragraphs ビューを取得するには、paragraphs=True を設定します。

クイックスタート — WSS サブセット（話者分離／編集／エンティティのみ）

import threading
from deepgram.core.events import EventType

with client.listen.v1.connect(model="nova-3", diarize=True, redact=["pii"]) as conn:
    conn.on(EventType.MESSAGE, lambda m: print(m))
    threading.Thread(target=conn.start_listening, daemon=True).start()
    for chunk in audio_chunks:
        conn.send_media(chunk)
    conn.send_finalize()

主なパラメーター

summarize、topics、intents、sentiment、detect_language、diarize、redact、custom_topic、custom_topic_mode、custom_intent、custom_intent_mode、detect_entities に加え、標準的な STT パラメーター（model、language、encoding、sample_rate など）。

現在の生成済み SDK では、redact は src/deepgram/listen/v1/media/client.py で Optional[str] として型指定されています。"pci"、"pii"、"numbers"、"phi" など、単一の編集モードを渡します。転送レベルでは、redact をクエリーパラメーターとして繰り返し指定することで複数モードの編集に対応しています。現在の型は src/deepgram/types/listen_v1redact.py で確認してください。複数のモードが必要な場合は、生のクエリーパラメーターを構築する方法（または複数回呼び出す方法）に切り替えてください。以前の Union[str, Sequence[str]] によるオーバーライドは、.fernignore では引き継がれなくなりました。

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

1. リポジトリ内のリファレンス：reference.md — 「Listen V1 Media」（REST パラメーターにはすべての分析フラグが含まれます）、「Listen V1 Connect」（WSS 対応のサブセット）。
2. OpenAPI（REST）：https://developers.deepgram.com/openapi.yaml
3. AsyncAPI（WSS）：https://developers.deepgram.com/asyncapi.yaml
4. Context7：ライブラリ ID /llmstxt/developers_deepgram_llms_txt。
5. 製品ドキュメント：
   • https://developers.deepgram.com/docs/stt-intelligence-feature-overview
   • https://developers.deepgram.com/docs/summarization
   • https://developers.deepgram.com/docs/topic-detection
   • https://developers.deepgram.com/docs/intent-recognition
   • https://developers.deepgram.com/docs/sentiment-analysis
   • https://developers.deepgram.com/docs/language-detection
   • https://developers.deepgram.com/docs/redaction
   • https://developers.deepgram.com/docs/diarization

注意点

1. /v1/listen の summarize は、ブール値または文字列 "v2" を受け付けます。 現在の要約モデルを固定するには "v2" を使用してください。True も使用できます（デフォルトモデルにマッピングされます）。/v1/read は逆に、ブール値のみを受け付けます。文字起こし済みのテキストを要約する必要がある場合は、deepgram-python-text-intelligence を参照してください。
2. sentiment ／ topics ／ intents ／ summarize ／ detect_language は REST 専用です。 WSS では指定しないでください。無視されるか、拒否されます。
3. sentiment ／ topics ／ intents ／ summarize は英語のみです。
4. すべてのモデルがすべてのオーバーレイに対応しているわけではありません。 Flux ／ Base モデルには制限があります。特別な理由がない限り、nova-3 を使用してください。
5. Redaction の値は pci、pii、phi、numbers などで、任意の文字列は指定できません。
6. custom_topic ／ custom_intent にはモードが必要です（"extended" または "strict"）。
7. 短い音声や品質の低い音声では、話者ダイアライゼーションの精度が低くなります。 30 秒未満のクリップでは、話者の切り替わりが頻繁に発生することがあります。

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

• examples/15-transcription-advanced-options.py — smart_format、punctuate、diarize
• tests/wire/test_listen_v1_media.py — intelligence パラメーターを対象とするワイヤーテスト

関連スキル

• deepgram-python-speech-to-text — 同じエンドポイントを使用する通常の文字起こし
• deepgram-python-text-intelligence — 同じ分析機能をテキスト入力で使用
• deepgram-python-conversational-stt — ターンテイキング用の Flux
• deepgram-python-voice-agent — 対話型アシスタント

中央製品スキル

言語を問わず Deepgram 製品に関する知識（統合された API リファレンス、ドキュメント検索、目的別の実行可能なレシピ、サードパーティ統合のサンプル、MCP のセットアップ）を利用するには、中央スキルをインストールしてください。

npx skills add deepgram/skills

この SDK には言語に適したコードスキルが含まれています。deepgram/skills には言語を問わない製品知識が含まれています（api、docs、recipes、examples、starters、setup-mcp を参照）。