deepgram-js-audio-intelligence

Deepgram Audio Intelligence の使用方法（JavaScript / TypeScript SDK）

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

この製品を使用するケース

• 音声があり、文字起こしとともに分析結果を返したい場合。
• REST が主な方法です。WebSocket では一部のインテリジェンス機能のみサポートされています。

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

• 文字起こしの出力のみが必要な場合 → deepgram-js-speech-to-text。
• すでにテキストがあり、そのテキストを分析したい場合 → deepgram-js-text-intelligence。
• Flux のターンテイキングが必要な場合 → deepgram-js-conversational-stt。
• 完全なインタラクティブ音声エージェントが必要な場合 → deepgram-js-voice-agent。

機能の対応状況：REST と WSS

機能	REST	WSS
diarize	はい	はい
redact	はい	はい
detect_entities	はい	はい
punctuate, smart_format	はい	はい
summarize	はい	現在の WSS 接続引数では非対応
topics	はい	いいえ
intents	はい	いいえ
sentiment	はい	いいえ
detect_language	はい	いいえ

認証

require("dotenv").config();

const { DeepgramClient } = require("@deepgram/sdk");

const deepgramClient = new DeepgramClient({
  apiKey: process.env.DEEPGRAM_API_KEY,
});

クイックスタート — 分析機能を使った REST

examples/22-transcription-advanced-options.ts より：

const data = await deepgramClient.listen.v1.media.transcribeUrl({
  url: "https://dpgr.am/spacewalk.wav",
  model: "nova-3",
  language: "en",
  punctuate: true,
  paragraphs: true,
  utterances: true,
  smart_format: true,
  sentiment: true,
  topics: true,
  custom_topic: "custom_topic",
  custom_topic_mode: "extended",
  intents: true,
  custom_intent: "custom_intent",
  custom_intent_mode: "extended",
  detect_entities: true,
  detect_language: true,
  diarize: true,
  keyterm: ["keyword1", "keyword2"],
  redact: ["pci", "ssn"],
});

クイックスタート — WSS 対応機能の一部

examples/07-transcription-live-websocket.ts から始め、同じソケットフローを維持しつつ、接続引数には diarize、redact、detect_entities など、WSS でサポートされているインテリジェンスフラグのみを使用します。

const deepgramConnection = await deepgramClient.listen.v1.createConnection({
  model: "nova-3",
  diarize: true,
  redact: "pci",
  detect_entities: true,
});

主なパラメーター／API インターフェース

• 分析フラグ：summarize、topics、intents、sentiment、detect_language、detect_entities、diarize、redact、custom_topic、custom_topic_mode、custom_intent、custom_intent_mode。
• 標準の STT フラグも引き続き適用されます：model、language、encoding、sample_rate、punctuate、smart_format、utterances、paragraphs、multichannel。
• リポジトリの例にある Nova-3 固有のバイアス指定には、keywords ではなく keyterm を使用しています。

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

1. リポジトリ内のリファレンス：reference.md → Listen V1 Media。WSS 対応機能の一部の動作は src/CustomClient.ts および src/api/resources/listen/resources/v1/client/{Client,Socket}.ts に記載されています。
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 は単純なブール値ではなく、バージョン指定が必要です。 生成された REST インターフェースと例では "v2" が指定されています。
2. ほとんどのインテリジェンスフラグは REST のみで利用できます。 現在の WSS 接続引数では、topics、intents、sentiment、summarize、detect_language は公開されていません。
3. 実際の redact の型は、生成されたエイリアスよりも柔軟です。 ListenV1Redact 自体は単なる文字列エイリアスですが、例では ["pci", "ssn"] のような配列を渡しています。
4. Nova-3 のバイアス指定には keyterm を使用してください。 examples/22-transcription-advanced-options.ts では、Nova-3 は keywords に対応していないことが明記されています。
5. モデル／機能の対応状況は製品側で決まります。 多数のオーバーレイを組み合わせる場合は、nova-3 が最も安全な選択肢です。
6. 話者分離の品質は、音声品質と長さによって異なります。 短いクリップやノイズの多いクリップでは、話者の判定が頻繁に変わります。

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

• examples/22-transcription-advanced-options.ts
• examples/04-transcription-prerecorded-url.ts
• examples/05-transcription-prerecorded-file.ts
• examples/07-transcription-live-websocket.ts

製品知識のセントラルスキル

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

npx skills add deepgram/skills

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