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

[アーティクル]
11/13/2024

Speech to Text REST API は、ファストトランスクリプション、バッチ文字起こし、カスタム音声において使用されます。この記事では、バージョン 3.1 から 3.2 への変更について説明します。

重要

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.1 から /speechtotext/v3.2 に更新する必要があります。たとえば、eastus リージョンの基本モデルを取得するには、https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base の代わりに https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base を使用します。

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

バッチ文字起こし

重要

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

下位互換性の制限事項

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

言語識別モード

LanguageIdentificationMode は、candidateLocales と speechModelMapping の兄弟として LanguageIdentificationProperties に追加されます。言語識別に使用できるモードは、Continuous または Single です。継続的な言語識別が既定です。詳細については、言語識別に関する記事を参照してください。

Whisper モデル

Azure AI Speech では、Speech to Text REST API v3.2 を介した OpenAI の Whisper モデルがサポートされるようになりました。詳細については、「バッチ文字起こしを作成する」ガイドを参照してください。

Note

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

Custom Speech

重要

基本モデルが 2023 年 10 月 1 日以降に作成された場合、カスタム音声モデルのトレーニングに対して課金されます。基本モデルが 2023 年 10 月より前に作成された場合、トレーニングに対して課金は行われません。詳細については、「Azure AI Speech の価格」を参照してください。

2023 年 10 月 1 日以降にモデルが作成されたかどうかをプログラムで判断するには、バージョン 3.2 で新しく追加されたchargedForAdaptation プロパティを使用します。

カスタム表示テキストの書式設定

カスタム表示テキストの書式設定データを使用したモデル適応をサポートするために、Datasets_Create 操作で OutputFormatting データの種類がサポートされます。詳細については、「データセットをアップロードする」を参照してください。

Lexical と Display 列挙値を含む OutputFormatType の定義を追加しました。

"OutputFormatType": {
    "title": "OutputFormatType",
    "enum": [
        "Lexical",
        "Display"
    ],
    "type": "string",
    "x-ms-enum": {
        "name": "OutputFormatType",
        "modelAsString": true,
        "values": [
            {
                "value": "Lexical",
                "description": "Model provides the transcription output without formatting."
            },
            {
                "value": "Display",
                "description": "Model supports display formatting transcriptions output or endpoints."
            }
        ]
    }
},

OutputFormattingData 列挙値は、FileKind (入力データの型) に追加されます。

BaseModelFeatures に supportedOutputFormat プロパティが追加されました。このプロパティは、BaseModel 定義内にあります。

"BaseModelFeatures": {
    "title": "BaseModelFeatures",
    "description": "Features supported by the model.",
    "type": "object",
    "allOf": [
        {
            "$ref": "#/definitions/SharedModelFeatures"
        }
    ],
    "properties": {
        "supportsAdaptationsWith": {
            "description": "Supported dataset kinds to adapt the model.",
            "type": "array",
            "items": {
                "$ref": "#/definitions/DatasetKind"
            },
            "readOnly": true
        },
        "supportedOutputFormat": {
            "description": "Supported output formats.",
            "type": "array",
            "items": {
                "$ref": "#/definitions/OutputFormatType"
            },
            "readOnly": true
        }
    }
},

適応に対する課金

BaseModelProperties に chargeForAdaptation プロパティが追加されました。このプロパティは、BaseModel 定義内にあります。

重要

chargeForAdaptation の値が true の場合は、モデルのトレーニングに対して課金されます。値が false の場合は、モデルのトレーニングに対して課金されません。モデルのトレーニングに対して課金されるかどうかをプログラムで判断するには、作成日の代わりに chargeForAdaptation プロパティを使用します。

"BaseModelProperties": {
    "title": "BaseModelProperties",
    "type": "object",
    "properties": {
        "deprecationDates": {
            "$ref": "#/definitions/BaseModelDeprecationDates"
        },
        "features": {
            "$ref": "#/definitions/BaseModelFeatures"
        },
        "chargeForAdaptation": {
            "description": "A value indicating whether model adaptation is charged.",
            "type": "boolean",
            "readOnly": true
        }
    }
},

テキスト正規化

DatasetProperties に textNormalizationKind プロパティが追加されました。

TextNormalizationKind のエンティティ定義: テキスト正規化の種類。

既定値: 既定のテキスト正規化 (たとえば、en-US では 'two to three' は '2 to 3' に置き換えられます)。
なし: 入力テキストにテキスト正規化は適用されません。この値は、アップロード前にテキストを正規化する場合にのみ使用するオーバーライドオプションです。

評価プロパティ

EvaluationProperties プロパティにトークン数プロパティとトークンエラープロパティが追加されました。

correctTokenCount1: model1 によって正しく認識されたトークンの数。
tokenCount1: model1 によって処理されたトークンの数。
tokenDeletionCount1: model1 によって認識されたトークンのうち削除の数。
tokenErrorRate1: model1 における認識のトークンエラー率。
tokenInsertionCount1: model1 によって認識されたトークンのうち挿入の数。
tokenSubstitutionCount1: model1 によって認識されたトークンのうち代入の数。
correctTokenCount2: model2 によって正しく認識されたトークンの数。
tokenCount2: model2 によって処理されたトークンの数。
tokenDeletionCount2: model2 によって認識されたトークンのうち削除の数。
tokenErrorRate2: model2 における認識のトークンエラー率。
tokenInsertionCount2: model2 によって認識されたトークンのうち挿入の数。
tokenSubstitutionCount2: model2 によって認識されたトークンのうち代入の数。

モデルのコピー

次の変更は、モデルをコピーするシナリオに対して行われます。

新しい Models_Copy 操作が追加されました。新しいコピー操作のスキーマを次に示します: "$ref": "#/definitions/ModelCopyAuthorization"
Models_CopyTo 操作が非推奨になりました。非推奨のコピー操作のスキーマを次に示します: "$ref": "#/definitions/ModelCopy"
"$ref": "#/definitions/ModelCopyAuthorization" を返す新しいModels_AuthorizeCopy 操作が追加されました。この返されたエンティティは、新しい Models_Copy 操作で使用できます。

次のように ModelCopyAuthorization の新しいエンティティ定義を追加しました。

"ModelCopyAuthorization": {
    "title": "ModelCopyAuthorization",
    "required": [
        "expirationDateTime",
        "id",
        "sourceResourceId",
        "targetResourceEndpoint",
        "targetResourceId",
        "targetResourceRegion"
    ],
    "type": "object",
    "properties": {
        "targetResourceRegion": {
            "description": "The region (aka location) of the target speech resource (e.g., westus2).",
            "minLength": 1,
            "type": "string"
        },
        "targetResourceId": {
            "description": "The Azure Resource ID of the target speech resource.",
            "minLength": 1,
            "type": "string"
        },
        "targetResourceEndpoint": {
            "description": "The endpoint (base url) of the target resource (with custom domain name when it is used).",
            "minLength": 1,
            "type": "string"
        },
        "sourceResourceId": {
            "description": "The Azure Resource ID of the source speech resource.",
            "minLength": 1,
            "type": "string"
        },
        "expirationDateTime": {
            "format": "date-time",
            "description": "The expiration date of this copy authorization.",
            "type": "string"
        },
        "id": {
            "description": "The ID of this copy authorization.",
            "minLength": 1,
            "type": "string"
        }
    }
},

次のように ModelCopyAuthorizationDefinition の新しいエンティティ定義を追加しました。

"ModelCopyAuthorizationDefinition": {
    "title": "ModelCopyAuthorizationDefinition",
    "required": [
        "sourceResourceId"
    ],
    "type": "object",
    "properties": {
        "sourceResourceId": {
            "description": "The Azure Resource ID of the source speech resource.",
            "minLength": 1,
            "type": "string"
        }
    }
},

CustomModelLinks コピープロパティ

新しい copy プロパティを追加しました。

copyTo URI: 古いモデルコピーアクションの場所。詳細については、Models_CopyTo 操作を参照してください。
copy URI: モデルコピーアクションの場所。詳細については、Models_Copy 操作を参照してください。

"CustomModelLinks": {
    "title": "CustomModelLinks",
    "type": "object",
    "properties": {
      "copyTo": {
        "format": "uri",
        "description": "The location to the obsolete model copy action. See operation \"Models_CopyTo\" for more details.",
        "type": "string",
        "readOnly": true
      },
      "copy": {
        "format": "uri",
        "description": "The location to the model copy action. See operation \"Models_Copy\" for more details.",
        "type": "string",
        "readOnly": true
      },
      "files": {
        "format": "uri",
        "description": "The location to get all files of this entity. See operation \"Models_ListFiles\" for more details.",
        "type": "string",
        "readOnly": true
      },
      "manifest": {
        "format": "uri",
        "description": "The location to get a manifest for this model to be used in the on-prem container. See operation \"Models_GetCustomModelManifest\" for more details.",
        "type": "string",
        "readOnly": true
      }
    },
    "readOnly": true
},

次の方法で共有

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

基本パス

バッチ文字起こし

下位互換性の制限事項

言語識別モード

Whisper モデル

Custom Speech

カスタム表示テキストの書式設定

適応に対する課金

テキスト正規化

評価プロパティ

モデルのコピー

CustomModelLinks コピープロパティ

操作 ID

次のステップ

フィードバック

その他のリソース

次の方法で共有

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

基本パス

バッチ文字起こし

下位互換性の制限事項

言語識別モード

Whisper モデル

Custom Speech

カスタム表示テキストの書式設定

適応に対する課金

テキスト正規化

評価プロパティ

モデルのコピー

CustomModelLinks コピー プロパティ

操作 ID

次のステップ

フィードバック

その他のリソース

CustomModelLinks コピープロパティ