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

發行項
04/15/2024

語音轉換文字 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。例如，若要取得區域中的 eastus 基底模型，請使用 https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base 而非 https://eastus.api.cognitive.microsoft.com/speechtotext/v3.0/models/base。

請注意下列其他變更：

/models/{id}/copyto 3.0 版中的作業（包括 '/'）會取代為 /models/{id}:copyto 3.1 版中的作業（包括 '：'）。
/webhooks/{id}/ping 3.0 版中的作業（包括 '/'）會取代為 /webhooks/{id}:ping 3.1 版中的作業（包括 '：'）。
/webhooks/{id}/test 3.0 版中的作業（包括 '/'）會取代為 /webhooks/{id}:test 3.1 版中的作業（包括 '：'）。

如需詳細資訊，請參閱本指南稍後的作業標識符。

批次轉譯

注意

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

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

displayFormWordLevelTimestampsEnabled屬性可用來在轉譯結果的顯示形式上啟用文字層級時間戳的報告。結果會在轉譯檔案的屬性中 displayWords 傳回。
diarization屬性可用來指定在執行選擇性聽寫時產生之說話者標籤數量下限和最大值的提示。透過這項功能，服務現在可以為兩個以上的喇叭產生喇叭標籤。若要使用這個屬性，您也必須將 diarizationEnabled 屬性設定為 true。使用 v3.1 API 時，我們已從 v3.0 API 支援的兩個喇叭中增加可識別的說話者數目。建議將說話者數目保持在 30 歲以下，以提升效能。
languageIdentification屬性可以在轉譯之前指定輸入上語言識別的設定。語言識別最多可支援10個候選地區設定。傳回的轉譯包含所辨識語言或您所提供地區設定的新 locale 屬性。

屬性 filter 會新增至 Transcriptions_List、 Transcriptions_ListFiles和 Projects_ListTranscriptions 作業。表達式 filter 可用來選取可用資源的子集。您可以依 displayName、、description、、lastActionDateTimecreatedDateTimestatus、和 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、、lastActionDateTimecreatedDateTimestatus、、 locale和 kind進行篩選。例如：filter=locale eq 'en-US'

已新增Models_ListFiles作業，以取得指定標識碼所識別之模型的檔案。

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

作業標識碼

3.1 版中每個 operationId 的名稱前面都會加上物件名稱。例如，operationId“建立模型”的從 3.0 版的 CreateModel 變更為 3.1 版中的 Models_Create。

/models/{id}/copyto 3.0 版中的作業（包括 '/'）會取代為 /models/{id}:copyto 3.1 版中的作業（包括 '：'）。

/webhooks/{id}/ping 3.0 版中的作業（包括 '/'）會取代為 /webhooks/{id}:ping 3.1 版中的作業（包括 '：'）。

/webhooks/{id}/test 3.0 版中的作業（包括 '/'）會取代為 /webhooks/{id}:test 3.1 版中的作業（包括 '：'）。

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

基底路徑

批次轉譯

自訂語音

資料集

模型

作業標識碼

下一步

其他資源