mcpField
S
speech-to-text

speech-to-text

github.com/deepgram開発2763 回インストール6 日前に更新
リポジトリ

speech-to-text について

DeepgramのSkillで、開発者がNovaまたはFlux STTを選び、最初の文字起こしリクエストを行う手順を案内します。モデル選択、エンドポイント、主な違いに焦点を当て、詳細なパラメーターは別の`api` Skillを参照します。

主な機能

  1. 01NovaとFlux STTの比較
  2. 02エンドポイントとモデルの選択
  3. 03録音音声の文字起こし開始
  4. 04WebSocketでの音声ストリーミング
  5. 05ターン検出の設定

活用シーン

  1. 01録音音声の文字起こし
  2. 02字幕の生成
  3. 03ターン検出付き音声インターフェースの構築
  4. 04Deepgram音声モデルの選択

インストール

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

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

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

詳細

Deepgram Speech-to-Text

Deepgram は、2 つのエンドポイントで 2 系統のモデルを使って音声を書き起こします。まずモデル系統を選んでください。エンドポイント、パラメーター、メッセージ形式は、すべてその選択に応じて決まります。このスキルでは最初のリクエストを動作させ、次に開くスキルを案内します。パラメーターの詳細なリファレンスは繰り返しません。詳しくは api スキルを参照してください。

まずモデル系統を選ぶ

NovaFlux STT
モデル名nova-3（nova-3-general のエイリアス）、nova-3-medical、nova-3-pharmaflux-general-en（英語）、flux-general-multi（10 言語）
エンドポイント/v1/listen、REST および WebSocket/v2/listen、WebSocket のみ
出力文字起こしストリームターンの状態と各ターンの文字起こしを含む TurnInfo イベント
ターン検出組み込み機能なし。エンドポイント処理と独自のロジックを使います組み込み：StartOfTurn、EagerEndOfTurn、TurnResumed、EndOfTurn
書式設定と分析smart_format、diarize_model、summarize、sentiment、topics、intents、編集単語のタイムスタンプ、numerals、redact（numbers または aggressive_numbers）、keyterm、profanity_filter、mip_opt_out、tag。スマート書式設定と話者分離には非対応
言語language=<code>、またはコードスイッチングには language=multi。language_hint で言語を優先しますモデル名で言語が選択されます。language_hint で flux-general-multi の言語を優先します

選択の目安：

  • 録音済みファイルの文字起こし、キャプションや字幕の生成、話者ラベルや要約、感情分析が必要な場合、またはフレーズの終了を独自のコードで判断する音声ストリーミングには、Nova を選んでください。
  • 人がソフトウェアに話しかけ、ソフトウェアが発話の終了を認識する必要がある場合は、Flux STT を選んでください。音声エージェント、電話アシスタント、IVR、エージェント支援などが該当します。Flux に録音済み音声モードはありません。
  • Deepgram に言語モデルの実行と応答の読み上げも行わせたい場合は、どちらも選ばないでください。これは別のホスト agent.deepgram.com から提供される Voice Agent API です。voice-agent スキルを開いてください。

最初のリクエスト：録音済みファイルで Nova を使う

https://console.deepgram.com でキーを作成し、DEEPGRAM_API_KEY としてエクスポートします。キーは Token スキームを使用して Authorization ヘッダーに指定します。必ず model を渡してください。指定しない場合、API は base にフォールバックします。

curl -s -X POST 'https://api.deepgram.com/v1/listen?model=nova-3&smart_format=true' \
  -H "Authorization: Token $DEEPGRAM_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://dpgr.am/spacewalk.wav"}'

文字起こし結果は results.channels[0].alternatives[0].transcript にあります。ローカルファイルを送信するには、Content-Type を音声の種類（例：audio/wav）に設定し、JSON ボディを使わずに --data-binary @file.wav を渡します。

Nova でよく使うオプションは、すべて /v1/listen のクエリパラメーターです。

  • smart_format=true は句読点、段落、数値の書式を追加します。punctuate も有効になるため、両方を設定しないでください。
  • diarize_model=latest は話者をラベル付けします。非推奨の diarize=true に代わるもので、両方を設定したリクエストは拒否されます。ストリーミングで使用できるのは latest と v1 のみです。
  • language=multi は、Nova-3 の多言語対応 55 言語をまたぐコードスイッチングされた音声を文字起こしします。単一の言語コードも使用できます。デフォルトは en です。
  • language_hint=<code> は言語ごとに繰り返し指定します（language_hint=en&language_hint=es）。言語を制限せず、想定される言語に language=multi を寄せます。他の language と併用すると無視されます。Nova-3 の多言語対応リストにないコードを指定すると 400 エラーになります（ストリーミング時は WebSocket ハンドシェイクが拒否されます）。ヒントはストリームの開始から終了まで固定されます。レスポンスでは正規化されたヒントが languages_hinted に返されます。
  • keyterm=<term> は人名、製品用語、専門用語を強調します。Nova-3 と Flux STT でのみ受け付けられます。Nova-2 など他のモデルでは、代わりに keywords を使用します。用語ごとにパラメーターを繰り返してください。リクエスト内のすべてのキータームを合わせた上限は 500 トークンです。超過すると Keyterm limit exceeded でリクエストが失敗します。Deepgram は、重要な 20～50 個の用語に絞り、上限を十分に下回るよう推奨しています。カンマ、セミコロン、term:weight は拒否されません。API は値全体を単一のリテラル用語として扱うため、強調したい用語が意図どおりに強調されません。
  • summarize=v2、sentiment=true、topics=true、intents=true は音声インテリジェンス機能を追加します。録音済みの英語音声でのみ実行されます。
  • ライブストリーミングでは wss://api.deepgram.com/v1/listen?model=nova-3、同じ Authorization ヘッダー、バイナリ音声フレームを使用します。無音時には、キープアライブのページに記載されているとおり、3～5 秒ごとにテキストフレームとして {"type":"KeepAlive"} を送信します。音声または KeepAlive が 10 秒間届かないと、接続は NET-0001 で閉じられます。終了時には {"type":"CloseStream"} を送信します。ストリーム中に語彙や書式を変更するには、{"type":"Configure","keyterms":["routing number"],"features":{"numerals":true}} を送信します。keyterms はリスト全体を置き換えます（keyterm クエリパラメーターも含みます。[] はリストを消去し、省略または null の場合は維持されます）。Nova-3 モデルでのみ動作します。features は numerals などのブール値を切り替えます。次のメッセージを送信する前に、ConfigureSuccess または ConfigureFailure を待ってください。失敗（CONFIGURE_KEYTERMS_NOT_SUPPORTED、CONFIGURE_KEYTERM_LIMIT_EXCEEDED、CONFIGURE_ALREADY_PENDING、CONFIGURE_INTERNAL_ERROR）した場合、メッセージの内容は何も適用されず、ストリームは継続します。リージョン内ホストでも同じパスと同じキーを使用します：wss://api.eu.deepgram.com/v1/listen、wss://api.au.deepgram.com/v1/listen、wss://api.in.deepgram.com/v1/listen。

Flux STT：ターン検出に対応した会話音声

WebSocket で接続します。Flux には REST エンドポイントがありません。

wss://api.deepgram.com/v2/listen?model=flux-general-en&encoding=linear16&sample_rate=16000

同じ Authorization: Token ヘッダーを送信します。音声はモノラルでなければなりません。生音声（linear16、linear32、mulaw、alaw、opus、ogg-opus）の場合は encoding と sample_rate が必須です。WAV、Ogg、WebM コンテナーの場合は、どちらも省略してください。80 ms のチャンクを送信します。Flux STT には KeepAlive メッセージがありません。代わりに WebSocket ping を使用し、タイムアウトは 60 秒です。リージョン内で処理するには、同じキーで wss://api.eu.deepgram.com/v2/listen、wss://api.au.deepgram.com/v2/listen、または wss://api.in.deepgram.com/v2/listen を使用します。

/v2/listen の次の 2 つのクエリパラメーターに注目してください。

  • redactにはnumbersまたはaggressive_numbersを指定します。それ以外の値を指定すると、ハンドシェイクは400で失敗します。伏字にされた範囲はそれぞれ単一の*になり、[REDACTED]やエンティティタグにはなりません。
  • profanity_filter=trueは、language=multiを含め、/v2/listenで機能します。

サーバーはConnectedを送信し、その後にTurnInfoメッセージを連続して送信します。各メッセージには、event、turn_index、transcript、タイムスタンプ付きのwords、end_of_turn_confidenceが含まれます。eventの値は次のとおりです。

  • Update：ターン進行中、音声約0.25秒ごとに送信されます。
  • StartOfTurn：話者が話し始めました。これを使ってエージェントに割り込ませます（バージイン）。
  • EndOfTurn：話者が話し終えました。トランスクリプトをLLMに送信します。triggerにはmodel、manual、timeoutのいずれかが含まれます。
  • EagerEndOfTurnとTurnResumed：eager_eot_thresholdを設定した場合にのみ送信されます。前者で返信の下書きを始め、後者でキャンセルします。EndOfTurnのトランスクリプトは、EagerEndOfTurnのトランスクリプトと完全に一致します。エンドツーエンドのレイテンシーが約100～200 ms短縮される代わりに、LLMの呼び出しは50～70％増加します。まずはEndOfTurnのみを使ってください。

ターン検出を調整する3つのクエリパラメーターは、以下のConfigureメッセージを使ってストリーム中に変更することもできます。

パラメーター範囲デフォルト効果
eot_threshold0.5～1.00.7EndOfTurnに必要な信頼度です。1.0にすると、モデルによる検出を無効にします。
eager_eot_threshold0.3～0.9未設定EagerEndOfTurnを有効にします。値を小さくすると、より早く発生しますが、誤検出が増えます。eot_threshold以下である必要があります。
eot_timeout_ms500～600005000信頼度にかかわらず、EndOfTurnを強制する無音時間です。

クライアント制御メッセージは、それぞれJSONテキストフレームです。

  • {"type":"Configure","thresholds":{"eot_threshold":0.8},"keyterms":["Deepgram"],"numerals":true} は、再接続せずにしきい値、キーターム、language_hints、またはnumeralsを変更します。
    • 形式とアトミック性：ターン検出のしきい値は、例のようにthresholdsの下に指定します。省略したフィールドは現在の値が維持されます。1つのメッセージに含まれるすべてのフィールドは、まとめて適用されるか、まったく適用されないかのいずれかです。検証に失敗するフィールドが1つでもあると、どのフィールドも適用されません。
    • keyterms：配列はリスト全体を置き換え、プレーンな語句を最大100個まで指定できます（term:weight構文は使用できません）。
    • language_hints：[]を指定するとヒントがクリアされ、自動検出に戻ります。フィールドを省略するかnullを送信すると、現在のヒントが維持されます。
    • numerals：numeralsクエリパラメーターの値を初期値とし、Flux STTが更新を処理した後に送信する文字起こしに適用されます。すでに送信済みの文字起こしには適用されません。JSONのブール値である必要があります。文字列の"true"はスキーマ検証に失敗し、Flux STTはコードUNPARSABLE_CLIENT_MESSAGEを含むErrorを返して、接続を閉じます。
    • 応答は、numeralsを含む有効な設定全体をエコーするConfigureSuccessか、拒否されたフィールドを示すcodeとdescriptionを含み、以前の設定を維持するConfigureFailureです。
  • {"type":"ForceEndTurn"}（2026年8月28日追加）は、プッシュ・トゥ・トークのリリース、DTMFトーン、送信ボタンなど、独自のシグナルで現在のターンを終了します。Flux STTは"trigger":"manual"を含むEndOfTurnを送信します。アクティブなターンがない場合、このメッセージは無視され、コードFORCE_END_TURN_NO_ACTIVE_TURNを含むWarningが返されます。すべてのターンを自分で制御するには、eot_threshold=1.0を設定し、バックストップとしてeot_timeout_msを高く保ちます（"trigger":"timeout"）。
    • SDKのメソッド：JS 5.9.0はsendForceEndTurn、Python 7.8.0はsend_force_end_turn、Java 0.9.0はsendForceEndTurn、Go 3.8.0はForceEndTurn()、Rust 0.10.1はforce_end_turn()、.NET 7.1.0はインターフェースではなく具象クラスFluxWebSocketClientのSendForceEndTurn()です。
  • {"type":"CloseStream"}は、受信済みの音声のデコードを完了し、対応するUpdateメッセージを送信してから、WebSocketのクローズステータスコードを指定せずに接続を閉じます。アクティブなターンは終了しません。EndOfTurnは送信されないため、最後のメッセージは中間のUpdateになります。最終的な文字起こしでターンを終了するには、先にForceEndTurnを送信してからCloseStreamを送信します。メッセージは順番に処理されるため、ターンが終了した後に接続が閉じます。逆の順で送信すると、ForceEndTurnは効果がありません。

英語以外の通話や複数言語が混在する通話では、model=flux-general-multiを使用し、必要に応じてlanguage_hint=<code>パラメーターを繰り返し指定します（例：language_hint=en&language_hint=es）。ヒントを指定しない場合、モデルが言語を自動検出します。この場合、TurnInfoにはlanguagesとlanguages_hintedが含まれます。numeralsはflux-general-enのすべての数値を書式設定します。flux-general-multiでは、英語、スペイン語、フランス語、ドイツ語、ロシア語、ポルトガル語、イタリア語、オランダ語の数値を書式設定し、ヒンディー語と日本語の数値は発話どおりに保持します。

よくある間違い

  1. Authorization: Bearer <api key> を指定すると 401 が返ります。API キーには Authorization: Token <key> を使います。Bearer は、POST /v1/auth/grant が発行する短期間有効な JWT にのみ使います。
  2. {"err_code":"INSUFFICIENT_PERMISSIONS","err_msg":"Project does not have access to the requested model."} を含む 403 は、モデル名のスペルミスと、プロジェクトが使用できない実在のモデルの両方で返されます。本文には request_id が含まれます。アクセスを申請する前に、スペルを確認してください。GET https://api.deepgram.com/v1/models には公開カタログが、GET /v1/projects/{project_id}/models にはプロジェクトのモデルが一覧表示されます。nova-3-conversational というモデルはありません。会話音声には Flux（flux-general-en）を使います。公開カタログには Flux のモデル名が掲載されていないため、Flux のドキュメントで確認してください。
  3. /v1/listen では Flux は動作せず、model=flux も有効な値ではありません。flux-general-en または flux-general-multi を指定して、/v2/listen を使ってください。
  4. Flux での language=en または language=multi は誤りです。言語はモデル名で選択します。/v2/listen の language_hint は flux-general-multi でのみ受け付けられ、ほかのモデルでは 400 が返されます。
  5. コンテナ形式の音声（WAV、Ogg、WebM）に encoding または sample_rate を設定すると、エラーや文字化けした出力が発生します。どちらも省略し、コンテナに形式を指定させてください。
  6. /v1/listen で ForceEndTurn を使うとエラーが返されます。この機能は Flux でのみ使用できます。
  7. /v2/listen では smart_format、diarize、およびインテリジェンスのパラメーターは使用できません。話者ラベルと要約には Nova を使います。
  8. バイナリフレームとして送信された KeepAlive は正しく処理されません。制御メッセージはテキストフレームで、音声はバイナリフレームで送信してください。
  9. {"type":"Configure","features":{"numerals":true}} は /v1/listen の形式です。Flux STT は features のネストを受け付けず、接続を閉じます。/v2/listen では numerals をトップレベルのフィールドとして送信し、{"type":"Configure","numerals":true} としてください。

料金

Deepgram の音声テキスト化の料金は、音声の分数単位で課金されます。料金は変更されるため、スキルではなく https://deepgram.com/pricing で確認してください。

別のスキルを使う場合

  • すべてのパラメーター、レスポンススキーマ、またはメッセージフィールドが必要な場合：api スキル、ファイル references/listen.md。
  • トピックに関するドキュメントページを見たい場合：docs スキル。このスキルが参照しているページは、Sources に記載されています。
  • UI を備えた実行可能なアプリが必要な場合：starters スキル（transcription、live-transcription、flux の各機能）。
  • 50 行未満の単一機能のスニペットが必要な場合：recipes スキル、https://github.com/deepgram/recipes。
  • Deepgram を Twilio、LiveKit、Pipecat、LangChain、またはその他のプラットフォームに組み込む場合：examples スキル。
  • 言語に適した SDK コードが必要な場合：Nova 用の deepgram-{js,python,java,go,rust,dotnet}-speech-to-text と、Flux STT 用の deepgram-{lang}-conversational-stt を、該当する SDK リポジトリからインストールしてください（npx skills add deepgram/deepgram-python-sdk など）。
  • SDK からストリーム中に Configure を使って numerals を指定したい場合：deepgram-{lang}-conversational-stt スキルでは扱っていないため、このスキルの Configure の箇条書きにあるメッセージ形式を使用してください。JavaScript SDK は 5.13.0 から送信できます（socket.sendConfigure({type:"Configure", numerals:true})）。Python SDK は 7.11.0 から（connection.send_configure(ListenV2Configure(numerals=True))）、Java SDK は 0.10.2 から（sendConfigure(ListenV2Configure.builder().numerals(true).build())）、.NET SDK は 7.2.0 から（Flux の ConfigureSchema の Numerals）対応しています。
  • Go（3.10.0 まで）または Rust（0.14.0 まで）の SDK で、ストリーム中に numerals を指定したい場合：Flux の Configure 型には numerals フィールドがないため、生の JSON Configure メッセージを送信するか、接続 URL に numerals を設定してください。
  • SDK から Nova /v1/listen の Configure メッセージまたは language_hint を使いたい場合：JS は 5.15.0 から Configure、5.16.0 から ConfigureSuccess、ConfigureFailure、language_hint に対応しています。Python は 7.13.0 から Configure、7.14.0 から応答、7.15.0 から language_hint に対応しています。Java は 0.11.1 から Configure、0.11.2 から応答と languageHint に対応しています。.NET 7.2.0 は SendConfigure 経由で Configure を送信できますが、応答の型はありません（独自のドキュメントによると、拒否は Error として届きます）。また、/v1/listen の language_hint には対応していません。Go と Rust はいずれもこれらに対応していないため、生の JSON を送信し、URL に language_hint を自分で追加してください。
  • 文字起こしだけでなく分析（/v1/listen の summarize、sentiment、topics、intents、detect_entities）も必要な場合：audio-intelligence スキルを使ってください。すでにあるテキストの場合は、/v1/read と text-intelligence スキルを使ってください。
  • テキスト読み上げまたは音声エージェント一式が必要な場合：text-to-speech または voice-agent スキル。
  • アプリケーションコードではなくシェルコマンドが必要な場合：cli スキル。
  • コーディングツールからドキュメントを検索可能にしたい場合：setup-mcp スキル。

参照資料

コメント

Markdown 対応