通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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

  • 项目

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

重要

语音转文本 REST API 版本 2024-11-15 是正式发布的最新版本。

  • 语音转文本 REST API 版本 2024-05-15-preview 即将停用，具体日期有待宣布。
  • 语音转文本 REST API v3.0、v3.1、v3.2、3.2-preview.1 和 3.2-preview.2 将于 2026 年 4 月 1 日停用。

有关升级的详细信息，请参阅语音转文本 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.1/models/base 而非 https://eastus.api.cognitive.microsoft.com/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 听录请求的通知。

自定义语音

数据集

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

为了支持使用 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

必须在代码中将基础路径从 /speechtotext/v3.0 更新为 /speechtotext/v3.1。 例如，若要获取 eastus 区域中的基础模型，请使用 https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base 而非 https://eastus.api.cognitive.microsoft.com/speechtotext/v3.0/models/base。

版本 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 操作（包括“:”）。

后续步骤