将代码从 REST API 的 v3.0 迁移到 v3.1

项目
10/08/2024

语音转文本 REST API 用于批量听录和自定义语音识别。以下部分介绍了从版本 3.0 到 3.1 的更改。

重要

语音转文本 REST API v3.2 是正式发布的最新版本。预览版本 3.2-preview.1 和 3.2-preview.2* 将于 2024 年 9 月移除。语音转文本 REST API v3.1 即将停用，具体日期有待宣布。语音转文本 REST API v3.0 将于 2026 年 4 月 1 日停用。

基础路径

必须在代码中将基础路径从 /speechtotext/v3.0 更新为 /speechtotext/v3.1。例如，若要获取 chinanorth2 区域中的基础模型，请使用 https://chinanorth2.api.cognitive.azure.cn/speechtotext/v3.1/models/base 而非 https://chinanorth2.api.cognitive.azure.cn/speechtotext/v3.0/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。

批量听录

注意

请勿使用语音转文本 REST API v3.0 检索通过语音转文本 REST API v3.1 创建的听录。你将看到如下错误消息：“API 版本不能用于访问此听录。请使用 API v3.1 或更高版本。”

在 Transcriptions_Create 操作中，添加了以下三个属性：

displayFormWordLevelTimestampsEnabled 属性可用于在听录结果的显示窗体上启用报告单词级时间戳的功能。结果在听录文件的 displayWords 属性中返回。
diarization 属性可用于指定要在执行可选分割聚类（说话人分离）时生成的最小和最大说话人标签数的提示。借助此功能，该服务现在可以为两个以上的说话人生成说话人标签。若要使用此属性，还必须将 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 API 创建一个新的 Webhook 终结点，以便接收 V3.1 听录请求的通知。

自定义语音

数据集

添加了以下操作，用于上传和管理数据集的多个数据块：

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 属性将添加到以下操作：

filter 表达式可用于选择可用资源的子集。可以按 displayName、description、createdDateTime、lastActionDateTime、status、locale 和 kind 进行筛选。例如： filter=locale eq 'en-US'

添加了 Models_ListFiles 操作，以获取通过给定 ID 标识的模型的文件。

添加了 Models_GetFile 操作，用于从模型（使用 ID 进行标识）获取一个特定文件（使用 fileId 进行标识）。这样你便可以检索 ModelReport 文件，该文件提供有关训练期间处理的数据的信息。

操作 ID

版本 3.1 中每个 operationId 的名称都以对象名称作为前缀。例如，对于“创建模型”，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 操作（包括“:”）。

通过

将代码从 REST API 的 v3.0 迁移到 v3.1

基础路径

批量听录

自定义语音

数据集

模型

操作 ID

后续步骤

其他资源