將程式碼從 REST API 的 v3.0 遷移至 v3.1

文章
06/13/2024

語音轉換文字 REST API 可用來進行批次轉譯與自訂語音。如下面各節所述，從 3.0 版變更為 3.1 版。

重要

語音轉換文字 REST API v3.2 是正式運作的最新版本。 2024 年 9 月將會移除預覽 3.2-preview.1 和 3.2-preview.2* 版。語音轉換文字 REST API v3.1 將在宣佈的日期淘汰。語音轉換文字 REST API v3.0 將於 2026 年 4 月 1 日淘汰。

基底路徑

您必須將程式碼中的基底路徑從 /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 作業 (包含 ':') 所取代。

如需詳細資訊，請參閱本指南後面的作業識別碼。

批次轉譯

注意

請勿使用語音轉換文字 REST API v3.0 來擷取透過語音轉換文字 REST API v3.1 建立的謄寫。您會看到如下的錯誤訊息：「API 版本無法用來存取此轉譯。請使用 API 版本 v3.1 或更高版本。

在 Transcriptions_Create 作業中，新增了下列三個屬性：

displayFormWordLevelTimestampsEnabled 屬性可用來在轉譯結果的顯示表單上啟用文字層級時間戳記的報告。結果會在轉譯檔案的 displayWords 屬性中傳回。
diarization 屬性可用來指定語者標籤的最小數目和最大數目提示，以在執行選擇性自動分段 (語者分離) 時產生。透過這項功能，服務現在能夠為兩個以上的說話者產生說話者標籤。若要使用這個屬性，您也必須將 diarizationEnabled 屬性設定為 true。使用 API 版本 v3.1 時，我們已從 API 版本 v3.0 支援的兩個說話者中增加可識別的說話者數目。建議將說話者數目保持在 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 - 上傳資料集的資料區塊。區塊的大小上限為 8MB。
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 作業，以取得由指定識別碼識別的模型檔案。

已新增 Models_GetFile 作業，以從模型 (以識別碼識別) 取得一個特定檔案 (以 fileId 識別)。這可讓您擷取 ModelReport 檔案，以提供定型期間處理之資料的資訊。

作業識別碼

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 作業 (包含 ':') 所取代。

分享方式：