将代码从 REST API 的 v3.0 迁移到 v3.1
语音转文本 REST API 用于批量听录和自定义语音识别。 以下部分介绍了从版本 3.0 到 3.1 的更改。
重要
语音转文本 REST API v3.2 以预览版提供。 语音转文本 REST API v3.1 已正式发布。 语音转文本 REST API v3.0 将于 2026 年 4 月 1 日停用。 有关详细信息，请参阅语音转文本 REST API v3.0 到 v3.1 和 v3.1 到 v3.2 迁移指南。
基础路径
必须在代码中将基础路径从 /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 属性将添加到以下操作：
- 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'
添加了 Models_ListFiles 操作，以获取通过给定 ID 标识的模型的文件。
添加了 Models_GetFile 操作，用于从模型（使用 ID 进行标识）获取一个特定文件（使用 fileId 进行标识）。 这样你便可以检索 ModelReport 文件，该文件提供有关训练期间处理的数据的信息。
操作 ID
必须在代码中将基础路径从 /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.1 中每个 operationId 的名称都以对象名称作为前缀。 例如，对于“创建模型”，operationId 从版本 3.0 中的 CreateModel 更改为版本 3.1 中的 Models_Create。
1 版本 3.0 中的 /models/{id}/copyto 操作（包括“/”）替换为版本 3.1 中的 /models/{id}:copyto 操作（包括“:”）。
2 版本 3.0 中的 /webhooks/{id}/ping 操作（包括“/”）替换为版本 3.1 中的 /webhooks/{id}:ping 操作（包括“:”）。
3 版本 3.0 中的 /webhooks/{id}/test 操作（包括“/”）替换为版本 3.1 中的 /webhooks/{id}:test 操作（包括“:”）。