バッチ文字起こしを作成する

[アーティクル]
04/15/2024

バッチ文字起こしでは、音声データをバッチで送信します。サービスではオーディオデータを文字起こしし、その結果をストレージコンテナーに格納します。その後、ストレージコンテナーから結果を取得できます。

重要

新しい価格は、Speech to text REST API v3.2 を使用したバッチ文字起こしに対して有効です。詳細については、価格ガイドを参照してください。

前提条件

Speech SDK がインストールされている。
標準 (S0) 音声リソース。無料リソース (F0) はサポートされていません。

文字起こしジョブを作成する

文字起こしを作成するには、Speech to text REST API の Transcriptions_Create 操作を使用します。次の手順に従って要求本文を作成します。

contentContainerUrl プロパティまたは contentUrls プロパティを設定する必要があります。バッチ文字起こし用の Azure BLOB ストレージの詳細については、「バッチ文字起こし用のオーディオファイルを検索する」を参照してください。
必須の locale プロパティを設定します。この値は、文字起こしする音声データの想定されるロケールと一致する必要があります。後でロケールを変更することはできません。
必須の displayName プロパティを設定します。後で参照できる文字起こしの名前を選択します。文字起こしの名前は一意である必要はなく、後で変更できます。
必要に応じて、基本モデル以外のモデルを使用するには、model プロパティをモデル ID に設定します。詳細については、「カスタムモデルを使用する」および「Whisper モデルを使用する」を参照してください。
必要に応じて、wordLevelTimestampsEnabled プロパティを true に設定して、文字起こし結果で単語レベルのタイムスタンプを有効にします。既定値は false です。 Whisper モデルの場合は、代わりに displayFormWordLevelTimestampsEnabled プロパティを設定します。 Whisper は表示専用モデルであるため、文字起こしでは字句フィールドは設定されません。
必要に応じて、languageIdentification プロパティを設定します。言語識別は、サポートされている言語の一覧と照合する際に、オーディオで話されている言語を識別するために使用されます。 languageIdentification プロパティを設定する場合は、候補ロケールで languageIdentification.candidateLocales を設定する必要もあります。

詳細については、「要求の構成オプション」を参照してください。

以下の Transcriptions_Create の例に示すように、URI を使用する HTTP POST 要求を行います。

YourSubscriptionKey をSpeech リソースキーに置き換えます。
YourServiceRegion を Azure Cognitive Service for Speech リソースのリージョンに置き換えます。
前に説明したように、要求本文のプロパティを設定します。

curl -v -X POST -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey" -H "Content-Type: application/json" -d '{
  "contentUrls": [
    "https://crbn.us/hello.wav",
    "https://crbn.us/whatstheweatherlike.wav"
  ],
  "locale": "en-US",
  "displayName": "My Transcription",
  "model": null,
  "properties": {
    "wordLevelTimestampsEnabled": true,
    "languageIdentification": {
      "candidateLocales": [
        "en-US", "de-DE", "es-ES"
      ],
    }
  },
}'  "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/v3.1/transcriptions"

応答本文は次の形式で返されます。

{
  "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/transcriptions/db474955-ab85-4c6c-ba6e-3bfe63d041ba",
  "model": {
    "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base/13fb305e-09ad-4bce-b3a1-938c9124dda3"
  },
  "links": {
    "files": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/transcriptions/db474955-ab85-4c6c-ba6e-3bfe63d041ba/files"
  },
  "properties": {
    "diarizationEnabled": false,
    "wordLevelTimestampsEnabled": true,
    "channels": [
      0,
      1
    ],
    "punctuationMode": "DictatedAndAutomatic",
    "profanityFilterMode": "Masked",
    "languageIdentification": {
      "candidateLocales": [
        "en-US",
        "de-DE",
        "es-ES"
      ]
    }
  },
  "lastActionDateTime": "2022-10-21T14:18:06Z",
  "status": "NotStarted",
  "createdDateTime": "2022-10-21T14:18:06Z",
  "locale": "en-US",
  "displayName": "My Transcription"
}

応答本文の最上位の self プロパティは文字起こしの URI です。この URI を使用して、文字起こしや文字起こしレポートファイルの URI などの詳細を取得します。また、この URI は、文字起こしの更新または削除にも使います。

Transcriptions_Get 操作を実行して、文字起こしの状態を照会できます。

結果を取得した後は、サービスから Transcriptions_Delete を定期的に呼び出します。または、timeToLive プロパティを設定して、確実に結果が最終的に削除されるようにします。

文字起こしを作成するには、spx batch transcription create コマンドを使用します。次の手順に従って要求パラメーターを作成します。

必須の content パラメーターを設定します。個々のファイルのセミコロン区切りのリストまたはコンテナー全体の URL を指定できます。バッチ文字起こし用の Azure BLOB ストレージの詳細については、「バッチ文字起こし用のオーディオファイルを検索する」を参照してください。
必須の language プロパティを設定します。この値は、文字起こしする音声データの想定されるロケールと一致する必要があります。後でロケールを変更することはできません。 Speech CLI language パラメーターは、JSON 要求と応答の locale プロパティに対応します。
必須の name プロパティを設定します。後で参照できる文字起こしの名前を選択します。文字起こしの名前は一意である必要はなく、後で変更できます。 Speech CLI name パラメーターは、JSON 要求と応答の displayName プロパティに対応します。

文字起こしジョブを作成する音声 CLI コマンドの例を次に示します:

spx batch transcription create --name "My Transcription" --language "en-US" --content https://crbn.us/hello.wav;https://crbn.us/whatstheweatherlike.wav

応答本文は次の形式で返されます。

{
  "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/transcriptions/7f4232d5-9873-47a7-a6f7-4a3f00d00dc0",
  "model": {
    "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base/13fb305e-09ad-4bce-b3a1-938c9124dda3"
  },
  "links": {
    "files": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/transcriptions/7f4232d5-9873-47a7-a6f7-4a3f00d00dc0/files"
  },
  "properties": {
    "diarizationEnabled": false,
    "wordLevelTimestampsEnabled": false,
    "channels": [
      0,
      1
    ],
    "punctuationMode": "DictatedAndAutomatic",
    "profanityFilterMode": "Masked"
  },
  "lastActionDateTime": "2022-10-21T14:21:59Z",
  "status": "NotStarted",
  "createdDateTime": "2022-10-21T14:21:59Z",
  "locale": "en-US",
  "displayName": "My Transcription",
  "description": ""
}

文字起こしに関する音声 CLI ヘルプを表示するには、次のコマンドを実行します:

spx help batch transcription

要求の構成オプション

Transcriptions_Create 操作を呼び出すときに文字起こしを構成するために使用できるいくつかのプロパティオプションを次に示します。

プロパティ	説明
`channels`	処理するチャネル番号の配列。チャネル `0` と `1` は既定で文字起こしされます。
`contentContainerUrl`	個々の音声ファイルまたはストレージコンテナー全体を送信できます。音声データの場所は、`contentContainerUrl` または `contentUrls` プロパティを使用して指定する必要があります。バッチ文字起こし用の Azure BLOB ストレージの詳細については、「バッチ文字起こし用のオーディオファイルを検索する」を参照してください。このプロパティは、応答では返されません。
`contentUrls`	個々の音声ファイルまたはストレージコンテナー全体を送信できます。音声データの場所は、`contentContainerUrl` または `contentUrls` プロパティを使用して指定する必要があります。詳細については、「バッチ文字起こし用のオーディオファイルを検索する」を参照してください。このプロパティは、応答では返されません。
`destinationContainerUrl`	結果は、Azure コンテナーに格納できます。コンテナーを指定しないと、Speech サービスにより、結果は Microsoft が管理するコンテナーに格納されます。文字起こしジョブを削除すると、文字起こしの結果データも削除されます。サポートされているセキュリティシナリオなどの詳細については、「宛先コンテナー URL を指定する」を参照してください。
`diarization`	複数の音声を含むモノラルチャネルであることが予測される入力に対して、音声サービスがダイアライゼーション分析を実行することを示します。この機能は、ステレオ録音では使用できません。ダイアライゼーションは、オーディオデータ内の話者を分離するプロセスです。バッチパイプラインは、モノラルチャンネルレコーディングで複数の話者を認識および分離できます。話し中である可能性があるユーザーの最小数と最大数を指定します。また、この `diarizationEnabled` プロパティを `true` に設定する必要があります。文字起こしファイルには、文字起こしされたフレーズごとに `speaker` エントリが含まれています。 3 人以上の話者が予想される場合、このプロパティを使用する必要があります。話者 2 人の場合、`diarizationEnabled` プロパティを `true` に設定するだけで十分です。プロパティの使用方法の例については、「Transcriptions_Create」を参照してください。ダイアライゼーションの話者の最大数は 36 未満で、さらに `minSpeakers` プロパティ以上であることが必要です。例については、「Transcriptions_Create」を参照してください。このプロパティが選択されている場合、1 ファイルで 240 分を超える長さのソースオーディオは使用できません。注: このプロパティは、Speech to text REST API バージョン 3.1 以降でのみ使用できます。このプロパティに以前のバージョン (バージョン 3.0 など) を設定しても無視され、2 人の話者のみが識別されます。
`diarizationEnabled`	2 つの音声を含むモノラルチャネルであることが予測される入力に対して、音声サービスでダイアライゼーション分析を実行することを指定します。既定値は `false` です。音声が 3 つ以上の場合は、プロパティ `diarization` を使用する必要もあります。 Speech to Text REST API バージョン 3.1 以降でのみ使用します。このプロパティが選択されている場合、1 ファイルで 240 分を超える長さのソースオーディオは使用できません。
`displayName`	バッチ文字起こしの名前。後で参照できる名前を選択してください。表示名が一意である必要はありません。このプロパティは必須です。
`displayFormWordLevelTimestampsEnabled`	文字起こし結果の表示形式に単語レベルのタイムスタンプを含めるかどうかを指定します。結果は、文字起こしファイルの `displayWords` プロパティで返されます。既定値は `false` です。注: このプロパティは、Speech to text REST API バージョン 3.1 以降でのみ使用できます。
`languageIdentification`	言語識別は、サポートされている言語の一覧と照合する際に、オーディオで話されている言語を識別するために使用されます。 `languageIdentification` プロパティを設定する場合は、その囲まれた `candidateLocales` プロパティも設定する必要があります。
`languageIdentification.candidateLocales`	`"properties": { "languageIdentification": { "candidateLocales": ["en-US", "de-DE", "es-ES"]}}` などの言語識別の候補ロケール。文字起こし用のメインロケールを含め、最小 2 個から最大 10 個の候補ロケールがサポートされています。
`locale`	バッチ文字起こしのロケール。この値は、文字起こしする音声データの想定されるロケールと一致する必要があります。ロケールを後から変更することはできません。このプロパティは必須です。
`model`	特定の基本モデルまたはカスタム音声モデルを使用するように `model` プロパティを設定できます。 `model` を指定しない場合、ロケールの既定のベースモデルが使われます。詳細については、「カスタムモデルを使用する」および「Whisper モデルを使用する」を参照してください。
`profanityFilterMode`	認識結果内の不適切な表現をどう扱うかを指定します。指定できる値は、`None` (不適切な表現のフィルターを無効にする)、`Masked` (不適切な表現をアスタリスクに置き換える)、`Removed` (すべての不適切な表現を結果から除去する)、または `Tags` (不適切な表現のタグを追加する) です。既定値は `Masked` です。
`punctuationMode`	認識結果内の句読点をどう扱うかを指定します。指定できる値は、`None` (句読点を無効にする)、`Dictated` (明示的な (音声指示の) 句読点を暗黙指定する)、`Automatic` (デコーダーで句読点を処理する)、または `DictatedAndAutomatic` (口述指示および自動の句読点を使用する) です。既定値は `DictatedAndAutomatic` です。このプロパティは、Whisper モデルには適用できません。
`timeToLive`	文字起こしジョブが作成されてから、文字起こしの結果が自動的に削除されるまでの期間。値は ISO 8601 でエンコードされた期間です。たとえば、12 時間なら `PT12H` を指定します。代わりに、文字起こしの結果を取得した後に Transcriptions_Delete を定期的に呼び出すこともできます。
`wordLevelTimestampsEnabled`	単語レベルのタイムスタンプを出力に含めるかどうかを指定します。既定値は `false` です。このプロパティは、Whisper モデルには適用できません。 Whisper は表示専用モデルであるため、文字起こしでは字句フィールドは設定されません。

文字起こしに関する構成オプションに関する音声 CLI ヘルプを表示するには、次のコマンドを実行します:

spx help batch transcription create advanced

カスタムモデルを使用する

バッチ文字起こしでは、指定したロケールに既定の基本モデルが使用されます。既定の基本モデルを使用するためにプロパティを設定する必要はありません。

必要に応じて、特定の基本モデルまたはカスタム音声モデルを使用するように model プロパティを設定することで、前の文字起こしの作成の例を変更できます。

curl -v -X POST -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey" -H "Content-Type: application/json" -d '{
  "contentUrls": [
    "https://crbn.us/hello.wav",
    "https://crbn.us/whatstheweatherlike.wav"
  ],
  "locale": "en-US",
  "displayName": "My Transcription",
  "model": {
    "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base/1aae1070-7972-47e9-a977-87e3b05c457d"
  },
  "properties": {
    "wordLevelTimestampsEnabled": true,
  },
}'  "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/v3.1/transcriptions"

spx batch transcription create --name "My Transcription" --language "en-US" --content https://crbn.us/hello.wav;https://crbn.us/whatstheweatherlike.wav --model "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base/1aae1070-7972-47e9-a977-87e3b05c457d"

バッチ文字起こしにカスタム音声モデルを使用するには、モデルの URI が必要です。応答本文の最上位の self プロパティはモデルの URI です。モデルを作成または取得するときに、モデルの場所を取得できます。詳細については、「モデルの作成」にある JSON 応答の例を参照してください。

ヒント

バッチ文字起こしサービスで Custom Speech を使用するには、ホストされたデプロイエンドポイントは必要ありません。カスタム音声モデルをバッチ文字起こしにのみ使用する場合は、リソースを節約できます。

廃止されたモデルのバッチ文字起こし要求は、4xx エラーで失敗します。 model プロパティを、まだ期限切れになっていない基本モデルまたはカスタムモデルに設定します。それ以外の場合は、最新の基本モデルを常に使用する model プロパティを含めないでください。詳細については、「モデルの選択」および「カスタム音声モデルのライフサイクル」を参照してください。

Whisper モデルを使用する

Azure AI 音声は、バッチ文字起こし API を介した OpenAI の Whisper モデルをサポートしています。バッチ文字起こしに Whisper モデルを使用できます。

Note

Azure OpenAI Service では、同期 REST API を使用した音声テキスト変換用の OpenAI の Whisper モデルもサポートしています。詳細については、「Azure OpenAI の Whisper モデルを使った音声テキスト変換」を参照してください。どのような場合に Azure AI 音声とAzure OpenAI Service を使用するかについては、「Whisper モデルとは?」を参照してください

バッチ文字起こしに Whisper モデルを使用するには、model プロパティを設定する必要があります。 Whisper は表示専用モデルであるため、応答では字句フィールドは設定されません。

重要

Whisper モデルに対しては音声テキスト変換 API のバージョン 3.2を常に使用する必要があります。

バッチ文字起こしによる Whisper モデルは、オーストラリア東部、米国中部、米国東部、米国中北部、米国中南部、東南アジア、西ヨーロッパの各リージョンでサポートされています。

Models_ListBaseModels 要求を行って、すべてのロケールで使用可能な基本モデルを取得できます。

次の例に示すように、eastus リージョンに対して HTTP GET 要求を行います。 YourSubscriptionKey をSpeech リソースキーに置き換えます。別のリージョンを使用している場合は、eastus を置き換えます。

curl -v -X GET "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2-preview.2/models/base" -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey"

既定では、最も古い 100 個の基本モデルのみが返されます。 skip および top クエリパラメーターを使用して、結果ページ間を移動します。たとえば、次の要求は、最初の 100 個の基本モデルの後、次の 100 個の基本モデルを返します。

curl -v -X GET "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2-preview.2/models/base?skip=100&top=100" -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey"

サポートされているリージョンのいずれかの音声リソースの構成変数を設定していることを確認します。 spx csr list --base コマンドを実行して、すべてのロケールで使用可能な基本モデルを取得できます。

spx csr list --base --api-version v3.2-preview.2

この例に示すように、Whisper モデルの displayName プロパティには "Whisper" が含まれています。 Whisper は表示専用モデルであるため、文字起こしでは字句フィールドは設定されません。

{
  "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2-preview.2/models/base/e418c4a9-9937-4db7-b2c9-8afbff72d950",
  "links": {
    "manifest": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2-preview.2/models/base/e418c4a9-9937-4db7-b2c9-8afbff72d950/manifest"
  },
  "properties": {
    "deprecationDates": {
      "adaptationDateTime": "2025-04-15T00:00:00Z",
      "transcriptionDateTime": "2026-04-15T00:00:00Z"
    },
    "features": {
      "supportsTranscriptions": true,
      "supportsEndpoints": false,
      "supportsTranscriptionsOnSpeechContainers": false,
      "supportsAdaptationsWith": [
        "Acoustic"
      ],
      "supportedOutputFormats": [
        "Display"
      ]
    },
    "chargeForAdaptation": true
  },
  "lastActionDateTime": "2024-02-29T15:53:28Z",
  "status": "Succeeded",
  "createdDateTime": "2024-02-29T15:46:07Z",
  "locale": "en-US",
  "displayName": "20240228 Whisper Large V2",
  "description": "OpenAI Whisper Model in Azure AI Speech (Whisper v2-large)"
},

この例に示すように、eastus リージョンに対して完全なモデル URI を設定します。 YourSubscriptionKey をSpeech リソースキーに置き換えます。別のリージョンを使用している場合は、eastus を置き換えます。

curl -v -X POST -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey" -H "Content-Type: application/json" -d '{
  "contentUrls": [
    "https://crbn.us/hello.wav",
    "https://crbn.us/whatstheweatherlike.wav"
  ],
  "locale": "en-US",
  "displayName": "My Transcription",
  "model": {
    "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2-preview.2/models/base/d9cbeee6-582b-47ad-b5c1-6226583c92b6"
  },
  "properties": {
    "wordLevelTimestampsEnabled": true,
  },
}'  "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2-preview.2/transcriptions"

spx batch transcription create --name "My Transcription" --language "en-US" --content https://crbn.us/hello.wav;https://crbn.us/whatstheweatherlike.wav --model "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2-preview.2/models/base/d9cbeee6-582b-47ad-b5c1-6226583c92b6" --api-version v3.2-preview.2

宛先コンテナー URL を指定する

文字起こし結果は、Azure コンテナーに格納できます。コンテナーを指定しないと、Speech サービスにより、結果は Microsoft が管理するコンテナーに格納されます。その場合、文字起こしジョブを削除すると、文字起こしの結果データも削除されます。

バッチ文字起こし作成要求でオプション destinationContainerUrl を使用して、バッチ文字起こしの結果を書き込み可能な Azure BLOB ストレージコンテナーに格納できます。このオプションはアドホック SAS URI を使用しているのみで、信頼された Azure サービスのセキュリティメカニズムはサポートしていません。このオプションでは、アクセスポリシーベースの SAS もサポートされていません。 宛先コンテナーのストレージアカウントリソースによって、すべての外部トラフィックが許可される必要があります。

文字起こしの結果を、信頼された Azure サービスのセキュリティメカニズムを使用して Azure BLOB ストレージコンテナーに保存する場合は、ストレージ持ち込み (BYOS) の使用を検討する必要があります。詳細については、「音声テキスト変換に Bring Your Own Storage (BYOS) の Azure Cognitive Service for Speech リソースを使用する」を参照してください。