REST API の v3.0 から v3.1 にコードを移行する

Speech to Text REST API は、ファスト トランスクリプション、バッチ文字起こし、Custom Speech に使用されます。 バージョン 3.0 から 3.1 への変更については、以降のセクションで説明します。

重要

Speech to Text REST API バージョン 2024-11-15 は、一般提供されている最新バージョンです。

• Speech to Text REST API バージョン 2024-05-15-preview の廃止日は後日発表されます。
• Speech to Text REST API v3.0、v3.1、v3.2、3.2-preview.1、3.2-preview.2 は、2026 年 4 月 1 日に廃止されます。

アップグレードの詳細については、Speech to Text REST API の v3.0 から v3.1、v3.1 から v3.2、v3.2 から 2024-11-15 への移行ガイドを参照してください。

基本パス

コードの基本パスを /speechtotext/v3.0 から /speechtotext/v3.1 に更新する必要があります。 たとえば、eastus リージョンの基本モデルを取得するには、https://eastus.api.cognitive.microsoft.com/speechtotext/v3.0/models/base の代わりに https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base を使用します。

その他の変更に注意してください。

• バージョン 3.0 の /models/{id}/copyto 操作 ('/' を含む) は、バージョン 3.1 の /models/{id}:copyto 操作 (':' を含む) に置き換えられます。
• バージョン 3.0 の /webhooks/{id}/ping 操作 ('/' を含む) は、バージョン 3.1 の /webhooks/{id}:ping 操作 (':' を含む) に置き換えられます。
• バージョン 3.0 の /webhooks/{id}/test 操作 ('/' を含む) は、バージョン 3.1 の /webhooks/{id}:test 操作 (':' を含む) に置き換えられます。

詳細については、このガイドで後述する「操作 ID」を参照してください。

バッチ文字起こし

Note

Speech to text REST API v3.1 で作成された文字起こしを取得するのに、Speech to text REST API v3.0 を使用しないでください。 次のようなエラー メッセージが表示されます。「API バージョンを使用してこの文字起こしにアクセスすることはできません。 API バージョン v3.1 以降を使用してください。」

Transcriptions_Create 操作では、次の 3 つのプロパティが追加されます。

• displayFormWordLevelTimestampsEnabled プロパティを使用して、文字起こし結果の表示形式で、単語レベルのタイムスタンプのレポートを有効にできます。 結果は、文字起こしファイルの displayWords プロパティで返されます。
• diarization プロパティを使用して、オプションの diarization (話者の区別) を実行するときに、生成するスピーカー ラベルの最小数と最大数のヒントを指定できます。 この機能により、このサービスで 3 人以上のスピーカーのスピーカー ラベルを生成できるようになりました。 このプロパティを使用するには、diarizationEnabled プロパティをもtrue に設定する必要があります。 v3.1 API では、ダイアライゼーションによって識別できる話者の数が、v3.0 API でサポートされていた 2 話者から増やされています。 パフォーマンスを向上させるには、話者の数を 30 未満にしておくことをお勧めします。
• languageIdentification プロパティを使用すると、文字起こし前の入力で、言語識別の設定を指定できます。 言語識別では、最大 10 個の候補ロケールに対応しています。 返される文字起こしには、認識された言語または指定したロケールの新しい locale プロパティが含まれます。

filter プロパティは、Transcriptions_List、Transcriptions_ListFiles、および Projects_ListTranscriptions の操作に追加されます。 filter 式を使用して、使用可能なリソースのサブセットを選択できます。 displayName、description、createdDateTime、lastActionDateTime、status、および locale でフィルター処理できます。 例: filter=createdDateTime gt 2022-02-01T11:00:00Z

Webhook を使用して文字起こしの状態に関する通知を受信する場合、V3.0 API を介して作成された Webhook は V3.1 文字起こし要求の通知を受信できないことに注意してください。 V3.1 文字起こし要求の通知を受信するには、V3.1 API を介して新しい Webhook エンドポイントを作成する必要があります。

Custom Speech

データセット

データセットの複数のデータ ブロックをアップロードおよび管理するために、次の操作が追加されます。

• Datasets_UploadBlock - データセットのデータ ブロックをアップロードします。 ブロックの最大サイズは 8MiB です。
• Datasets_GetBlocks - このデータセットのアップロードされたブロックの一覧を取得します。
• Datasets_CommitBlocks - ブロックリストをコミットして、データセットのアップロードを完了します。

markdown 内の構造化テキスト データを使用したモデル適応をサポートするために、Datasets_Create 操作で LanguageMarkdown データの種類がサポートされるようになりました。 詳細については、「データセットをアップロードする」を参照してください。

モデル

Models_ListBaseModels 操作と Models_GetBaseModel 操作は、各基本モデルでサポートされている適応の型に関する情報を返します。

"features": {
    "supportsAdaptationsWith": [
        "Acoustic",
        "Language",
        "LanguageMarkdown",
        "Pronunciation"
    ]
}

Models_Create 操作には、新しい customModelWeightPercent パラメーターがあり、カスタム言語モデル (プレーンテキストまたは構造化テキスト データからトレーニング) と基本言語モデルを組み合わせるときに使用する重みを指定できます。 有効な値は、1 から 100 までの整数です。 現在の既定値は 30 です。

この filter プロパティは、次の操作に追加されます。

• Datasets_List
• Datasets_ListFiles
• Endpoints_List
• Evaluations_List
• Evaluations_ListFiles
• Models_ListBaseModels
• Models_ListCustomModels
• Projects_List
• Projects_ListDatasets
• Projects_ListEndpoints
• Projects_ListEvaluations
• Projects_ListModels

filter 式を使用して、使用可能なリソースのサブセットを選択できます。 displayName、description、createdDateTime、lastActionDateTime、status、locale、および kind でフィルター処理できます。 例: filter=locale eq 'en-US'

指定した ID によって識別されるモデルのファイルを取得する Models_ListFiles 操作を追加しました。

モデル (ID で識別) から 1 つの特定のファイル (fileId で識別) を取得する Models_GetFile オペレーションを追加しました。 これにより、トレーニング中に処理されたデータに関する情報を持つ ModelReport ファイルを取得できます。

操作 ID

コードの基本パスを /speechtotext/v3.0 から /speechtotext/v3.1 に更新する必要があります。 たとえば、eastus リージョンの基本モデルを取得するには、https://eastus.api.cognitive.microsoft.com/speechtotext/v3.0/models/base の代わりに https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base を使用します。

バージョン 3.1 の各 operationId の名前の前にオブジェクト名が付きます。 たとえば、"Create Model" の operationId は、バージョン 3.0 の CreateModel からバージョン 3.1 の Models_Create に変更されました。

バージョン 3.0 の /models/{id}/copyto 操作 ('/' を含む) は、バージョン 3.1 の /models/{id}:copyto 操作 (':' を含む) に置き換えられます。

バージョン 3.0 の /webhooks/{id}/ping 操作 ('/' を含む) は、バージョン 3.1 の /webhooks/{id}:ping 操作 (':' を含む) に置き換えられます。

バージョン 3.0 の /webhooks/{id}/test 操作 ('/' を含む) は、バージョン 3.1 の /webhooks/{id}:test 操作 (':' を含む) に置き換えられます。

次のステップ

• Speech to text REST API
• Speech to text REST API v3.1 リファレンス
• Speech to text REST API v3.0 リファレンス