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

  • [アーティクル]

重要

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

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

Note

バッチ トランスクリプトを使用するには、標準 (S0) の Speech リソースを使用する必要があります。 無料リソース (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 を設定する必要もあります。

詳細については、要求の構成オプションに関する記事を参照してください。

HTTP POST 要求は、以下の Transcriptions_Create の例に示したように URI を使用して行います。 YourSubscriptionKey は実際の Speech リソース キーに、YourServiceRegion は実際の 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": ""
}

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

文字起こしに関する音声 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 プロパティ以上であることが必要です (例を参照)。 この機能は、ステレオ録音では使用できません。

このプロパティが選択されている場合、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 特定の基本モデルまたは Custom Speech モデルを使用するように 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

カスタム モデルの使用

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

必要に応じて、特定の基本モデルまたは Custom Speech モデルを使用するように 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"

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

ヒント

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

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

Whisper モデルの使用

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

Note

Azure OpenAI Service では、同期 REST API を使用した音声テキスト変換用の OpenAI の Whisper モデルもサポートしています。 詳細については、クイックスタートを参照してください。 Azure AI 音声と Azure OpenAI Service の使い分けの詳細については、「Whisper モデルとは?」を確認してください。

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

重要

Whisper モデルは現在プレビュー段階です。 また、Whisper モデルに対しては Speech to text 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.1/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.1/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.1

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

{
  "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2-preview.1/models/base/d9cbeee6-582b-47ad-b5c1-6226583c92b6",
  "links": {
    "manifest": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2-preview.1/models/base/d9cbeee6-582b-47ad-b5c1-6226583c92b6/manifest"
  },
  "properties": {
    "deprecationDates": {
      "adaptationDateTime": "2024-10-15T00:00:00Z",
      "transcriptionDateTime": "2025-10-15T00:00:00Z"
    },
    "features": {
      "supportsTranscriptions": true,
      "supportsEndpoints": false,
      "supportsTranscriptionsOnSpeechContainers": false,
      "supportsAdaptationsWith": [],
      "supportedOutputFormats": [
        "Display"
      ]
    },
    "chargeForAdaptation": false
  },
  "lastActionDateTime": "2023-07-19T12:46:27Z",
  "status": "Succeeded",
  "createdDateTime": "2023-07-19T12:39:52Z",
  "locale": "en-US",
  "displayName": "20230707 Whisper Preview",
  "description": "en-US base model"
},

この例に示すように、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.1/models/base/d9cbeee6-582b-47ad-b5c1-6226583c92b6"
  },
  "properties": {
    "wordLevelTimestampsEnabled": true,
  },
}'  "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2-preview.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.2-preview.1/models/base/d9cbeee6-582b-47ad-b5c1-6226583c92b6" --api-version v3.2-preview.1

宛先コンテナー URL

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

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

文字起こしの結果を、信頼された Azure サービスのセキュリティ メカニズム経由で Azure BLOB ストレージ コンテナーに格納する場合は、ストレージ持ち込み (BYOS) の使用を検討する必要があります。 この記事では、BYOS 対応 Speech リソースを Batch 文字起こしに使用する方法の詳細を参照してください。

次のステップ