建立批次謄寫

發行項
10/16/2024

使用批次轉譯時，您會在批次中提交音訊資料。服務會謄寫音訊資料，並將結果儲存在儲存體容器中。然後，您可以從儲存體容器擷取結果。

重要

新定價適用於使用語音轉換文字 REST API v3.2 的批次謄寫。如需詳細資訊，請參閱定價指南。

必要條件

您需要標準 (S0) 語音資源。不支援免費資源 (F0)。

建立謄寫作業

若要建立批次謄寫作業，請使用語音轉換文字 REST API 的 Transcriptions_Create (英文) 作業。根據下列指示來建構要求本文：

您必須設定 contentContainerUrl 或 contentUrls 屬性。如需批次謄寫的 Azure Blob 儲存體詳細資訊，請參閱找出用於批次謄寫的音訊檔案。
設定必要的 locale 屬性。此值應該符合要轉譯之音訊資料的預期地區設定。稍後無法變更地區設定。
設定必要的 displayName 屬性。選擇稍後可參考的謄寫名稱。謄寫名稱不一定要是唯一的，而且稍後可以變更。
或者，若要選擇使用基本模型以外的模型，請將 model 屬性設定為模型識別碼。如需詳細資訊，請參閱使用自訂模型和使用 Whisper 模型。
或者，您可以選擇將 wordLevelTimestampsEnabled 屬性設定為 true，以在轉譯結果中啟用文字層級時間戳記。預設值是 false。對於 Whisper 模型，請改為設定 displayFormWordLevelTimestampsEnabled 屬性。 Whisper 是僅顯示模型，因此在轉譯中不會填入辭彙欄位。
選擇設定 languageIdentification 屬性。根據支援的語言清單比較識別音訊中的口說語言時，會使用語言識別。如果您設定 languageIdentification 屬性，則也必須設定 languageIdentification.candidateLocales 候選地區設定。

如需詳細資訊，請參閱要求設定選項。

使用 URI 提出 HTTP POST 要求，如下列 Transcriptions_Create 範例所示。

以您的語音資源金鑰取代 YourSubscriptionKey。
將 YourServiceRegion 取代為您的語音資源區域。
如先前所述設定要求本文屬性。

curl -v -X POST -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey" -H "Content-Type: application/json" -d '{
  "contentUrls": [
    "https://crbn.us/hello.wav",
    "https://crbn.us/whatstheweatherlike.wav"
  ],
  "locale": "en-US",
  "displayName": "My Transcription",
  "model": null,
  "properties": {
    "wordLevelTimestampsEnabled": true,
    "languageIdentification": {
      "candidateLocales": [
        "en-US", "de-DE", "es-ES"
      ],
    }
  },
}'  "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions"

您應該會收到下列格式的回應本文：

{
  "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/db474955-ab85-4c6c-ba6e-3bfe63d041ba",
  "model": {
    "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/5988d691-0893-472c-851e-8e36a0fe7aaf"
  },
  "links": {
    "files": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/db474955-ab85-4c6c-ba6e-3bfe63d041ba/files"
  },
  "properties": {
    "diarizationEnabled": false,
    "wordLevelTimestampsEnabled": true,
    "channels": [
      0,
      1
    ],
    "punctuationMode": "DictatedAndAutomatic",
    "profanityFilterMode": "Masked",
    "languageIdentification": {
      "candidateLocales": [
        "en-US",
        "de-DE",
        "es-ES"
      ]
    }
  },
  "lastActionDateTime": "2024-05-21T14:18:06Z",
  "status": "NotStarted",
  "createdDateTime": "2024-05-21T14:18:06Z",
  "locale": "en-US",
  "displayName": "My Transcription"
}

回應本文中最上層 self 屬性是謄寫的 URI。使用此 URI 來取得 (英文) 詳細資料，例如謄寫和謄寫報表檔案的 URI。您也可使用此 URI 來更新 (英文) 或刪除 (英文) 謄寫。

您可以使用 Transcriptions_Get (英文) 作業查詢謄寫的狀態。

在您擷取結果之後，定期從服務呼叫 Transcriptions_Delete。或者，設定 timeToLive 屬性以確保最終刪除結果。

提示

您也可以在 GitHub (英文) 上使用 Python、C# 或 Node.js 來嘗試使用批次謄寫 API。

若要建立謄寫，請使用 spx batch transcription create 命令。根據下列指示來建構要求參數：

設定必要的 content 參數。您可以指定以逗號分隔的個別檔案清單，或是整個容器的 URL。如需批次謄寫的 Azure Blob 儲存體詳細資訊，請參閱找出用於批次謄寫的音訊檔案。
設定必要的 language 屬性。此值應該符合要轉譯之音訊資料的預期地區設定。稍後無法變更地區設定。語音 CLI language 參數會對應至 JSON 要求和回應中的 locale 屬性。
設定必要的 name 屬性。選擇稍後可參考的謄寫名稱。謄寫名稱不一定要是唯一的，而且稍後可以變更。語音 CLI name 參數會對應至 JSON 要求和回應中的 displayName 屬性。

以下是建立謄寫作業的範例語音 CLI 命令：

spx batch transcription create --name "My Transcription" --language "en-US" --content https://crbn.us/hello.wav,https://crbn.us/whatstheweatherlike.wav

您應該會收到下列格式的回應本文：

{
  "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/7f4232d5-9873-47a7-a6f7-4a3f00d00dc0",
  "model": {
    "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/5988d691-0893-472c-851e-8e36a0fe7aaf"
  },
  "links": {
    "files": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions/7f4232d5-9873-47a7-a6f7-4a3f00d00dc0/files"
  },
  "properties": {
    "diarizationEnabled": false,
    "wordLevelTimestampsEnabled": false,
    "channels": [
      0,
      1
    ],
    "punctuationMode": "DictatedAndAutomatic",
    "profanityFilterMode": "Masked"
  },
  "lastActionDateTime": "2024-05-21T14:21:59Z",
  "status": "NotStarted",
  "createdDateTime": "2024-05-21T14:21:59Z",
  "locale": "en-US",
  "displayName": "My Transcription",
  "description": ""
}

回應本文中最上層 self 屬性是謄寫的 URI。使用此 URI 來取得 (英文) 詳細資料，例如謄寫和謄寫報表檔案的 URI。您也可使用此 URI 來更新或刪除謄寫。

如需謄寫的語音 CLI 說明，請執行下列命令：

spx help batch transcription

要求設定選項

以下是一些屬性選項，可在呼叫 Transcriptions_Create (英文) 作業時用來設定謄寫。您可以在相同的頁面上找到更多範例，例如建立具有語言識別的謄寫。

屬性	說明
`channels`	要處理的通道號碼陣列。預設會謄寫通道 `0` 和 `1`。
`contentContainerUrl`	您可以提交個別音訊檔案或整個儲存體容器。您必須使用 `contentContainerUrl` 或 `contentUrls` 屬性指定音訊資料位置。如需批次謄寫的 Azure Blob 儲存體詳細資訊，請參閱找出用於批次謄寫的音訊檔案。回應中不會傳回這個屬性。
`contentUrls`	您可以提交個別音訊檔案或整個儲存體容器。您必須使用 `contentContainerUrl` 或 `contentUrls` 屬性指定音訊資料位置。如需詳細資訊，請參閱找出用於批次謄寫的音訊檔案。回應中不會傳回這個屬性。
`destinationContainerUrl`	結果可以儲存在 Azure 容器中。如果您未指定容器，語音服務會將結果儲存在由 Microsoft 管理的容器中。刪除謄寫作業時，也會一併刪除謄寫結果資料。如需支援的安全性案例等詳細資訊，請參閱指定目的地容器 URL。
`diarization`	表示語音服務應該嘗試對輸入進行自動分段標記分析，其應該是包含多個聲音的單聲道。此功能不適用於立體聲錄製。自動分段標記是在音訊資料中區分說話者的程序。批次管線可以在單聲道錄製上辨識和分隔多個說話者。指定可能會說話的人員數目下限和上限。您也必須將 `diarizationEnabled` 屬性設定為 `true`。轉譯檔案會包含每個已轉譯片語的 `speaker` 項目。當您預期有三個或多個說話者時，您必須使用這個屬性。若為兩個說話者，將 `diarizationEnabled` 屬性設定為 `true` 已足夠。如需屬性使用方式的範例，請參閱 Transcriptions_Create。自動分段標記的說話者數目上限必須小於 36，且大於或等於 `minCount` 屬性。如需範例，請參閱 Transcriptions_Create。選取此屬性時，每個檔案的來源音訊長度不能超過 240 分鐘。注意：此屬性僅適用於語音轉換文字 REST API 3.1 版和更新版本。如果您使用任何舊版來設定此屬性，例如 3.0 版，則會忽略此屬性，而且只會識別兩個說話者。
`diarizationEnabled`	指定語音服務應該嘗試對輸入進行自動分段標記分析，其應該是包含兩個聲音的單聲道。預設值是 `false`。若為三個以上聲音，您也需要使用屬性 `diarization`。僅適用於語音轉換文字 REST API 3.1 版和更新版本。選取此屬性時，每個檔案的來源音訊長度不能超過 240 分鐘。
`displayName`	批次謄寫的名稱。選擇一個您稍後可以與之關聯的名稱。顯示名稱不一定要是唯一的。此屬性是必要項。
`displayFormWordLevelTimestampsEnabled`	指定是否要在轉譯結果的顯示表單上包含文字層級時間戳記。結果會在轉譯檔案的 `displayWords` 屬性中傳回。預設值是 `false`。注意：此屬性僅適用於語音轉換文字 REST API 3.1 版和更新版本。
`languageIdentification`	根據支援的語言清單比較識別音訊中的口說語言時，會使用語言識別。如果您設定 `languageIdentification` 屬性，則也必須設定其封入 `candidateLocales` 屬性。
`languageIdentification.candidateLocales`	語言識別的候選地區設定，例如 `"properties": { "languageIdentification": { "candidateLocales": ["en-US", "de-DE", "es-ES"]}}`。支援至少 2 個和最多 10 個候選地區設定，包括轉譯的主要地區設定。
`locale`	批次謄寫的地區設定。此值應該符合要轉譯之音訊資料的預期地區設定。稍後無法變更此地區設定。此屬性是必要項。
`model`	您可以將 `model` 屬性設定為使用特定基本模型或自訂語音模型。如果未指定 `model`，則會使用地區設定的預設基底模型。如需詳細資訊，請參閱使用自訂模型和使用 Whisper 模型。
`profanityFilterMode`	指定如何處理辨識結果中的不雅內容。接受的值為 `None` (會停用粗話過濾)、`Masked` (會以星號取代粗話)、`Removed` (會移除結果中的所有粗話) 或 `Tags` (會新增粗話標籤)。預設值是 `Masked`。
`punctuationMode`	指定如何處理辨識結果中的標點符號。接受的值為 `None` (會停用標點符號)、`Dictated` (會明確表示 (讀出) 標點符號)、`Automatic` (讓解碼器處理標點符號)，或 `DictatedAndAutomatic` (會使用聽寫和自動標點符號)。預設值是 `DictatedAndAutomatic`。此屬性不適用於 Whisper 模型。
`timeToLive`	建立謄寫作業後的一段持續時間，之後系統便會自動刪除謄寫結果。此值是 ISO 8601 編碼的持續時間。例如，指定 `PT12H` 代表 12 小時。或者，您可以在擷取轉譯結果之後定期呼叫 Transcriptions_Delete。
`wordLevelTimestampsEnabled`	指定是否要將文字層級時間戳記包括在輸出中。預設值是 `false`。此屬性不適用於 Whisper 模型。 Whisper 是僅顯示模型，因此在轉譯中不會填入辭彙欄位。

如需謄寫設定選項的語音 CLI 說明，請執行下列命令：

spx help batch transcription create advanced

使用自訂模型

批次謄寫會針對您指定的地區設定使用預設基底模型。您不需要設定任何屬性來使用預設基底模型。

或者，您可以選擇修改先前的建立轉譯範例，方法是將 model 屬性設定為使用特定基本模型或自訂語音模型。

curl -v -X POST -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey" -H "Content-Type: application/json" -d '{
  "contentUrls": [
    "https://crbn.us/hello.wav",
    "https://crbn.us/whatstheweatherlike.wav"
  ],
  "locale": "en-US",
  "displayName": "My Transcription",
  "model": {
    "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/5988d691-0893-472c-851e-8e36a0fe7aaf"
  },
  "properties": {
    "wordLevelTimestampsEnabled": true,
  },
}'  "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions"

spx batch transcription create --name "My Transcription" --language "en-US" --content https://crbn.us/hello.wav,https://crbn.us/whatstheweatherlike.wav --model "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/5988d691-0893-472c-851e-8e36a0fe7aaf"

若要使用自訂語音模型進行批次轉譯，您需要該模型的 URI。回應本文中最上層 self 屬性是模型的 URI。您可以在建立或取得模型時擷取模型位置。如需詳細資訊，請參閱建立模型中的 JSON 回應範例。

提示

無需託管部署端點，也能將自訂語音與批次謄寫服務搭配使用。如果自訂語音模型僅用於批次轉譯，則可節省資源。

過期模型的批次轉譯要求會失敗，並傳回 4xx 錯誤。將 model 屬性設定為基本模型或未過期的自訂模型。否則，請勿包含 model 屬性，以一律使用最新的基底模型。如需詳細資訊，請參閱選擇模型和自訂語音模型生命週期。

使用 Whisper 模型

Azure AI 語音使用批次轉譯 API 來支援 OpenAI 的 Whisper 模型。您可以使用 Whisper 模型進行批次轉譯。

注意

Azure OpenAI 服務也支援 OpenAI 的 Whisper 模型，透過同步 REST API 進行語音轉換文字。若要深入了解，請參閱使用 Azure OpenAI Whisper 模型進行語音轉換文字。如需何時使用 Azure AI 語音與 Azure OpenAI 服務的相關資訊，請參閱什麼是 Whisper 模型？

若要使用 Whisper 模型進行批次轉譯，您必須設定 model 屬性。 Whisper 是僅顯示模型，因此在回應中不會填入辭彙欄位。

重要

對於 Whisper 模型，您應該一律使用語音轉換文字 API 3.2 版。

在澳大利亞東部、美國中部、美國東部、美國中北部、美國中南部、東南亞和西歐區域支援使用 Whisper 模型進行批次謄寫。

您可以提出 Models_ListBaseModels 要求，以取得所有地區設定的可用基底模型。

提出 HTTP GET 要求，如下列 eastus 區域的範例所示。以您的語音資源金鑰取代 YourSubscriptionKey。如果您使用不同的區域，請取代 eastus。

curl -v -X GET "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base" -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey"

依預設，只會傳回 100 個最舊的基本模型。使用 skip 和 top 查詢參數逐頁查看結果。例如，下列要求會在第一個 100 個基本模型之後傳回下一個 100 個基本模型。

curl -v -X GET "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base?skip=100&top=100" -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey"

請確定您在其中一個支援區域中設定語音資源的設定變數。您可以執行 spx csr list --base 命令來取得所有地區設定的可用基底模型。

spx csr list --base --api-version v3.2

Whisper 模型的 displayName 屬性包含 "Whisper"，如此範例所示。 Whisper 是僅顯示模型，因此在轉譯中不會填入辭彙欄位。

{
  "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/e418c4a9-9937-4db7-b2c9-8afbff72d950",
  "links": {
    "manifest": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/e418c4a9-9937-4db7-b2c9-8afbff72d950/manifest"
  },
  "properties": {
    "deprecationDates": {
      "adaptationDateTime": "2025-04-15T00:00:00Z",
      "transcriptionDateTime": "2026-04-15T00:00:00Z"
    },
    "features": {
      "supportsTranscriptions": true,
      "supportsEndpoints": false,
      "supportsTranscriptionsOnSpeechContainers": false,
      "supportsAdaptationsWith": [
        "Acoustic"
      ],
      "supportedOutputFormats": [
        "Display"
      ]
    },
    "chargeForAdaptation": true
  },
  "lastActionDateTime": "2024-02-29T15:53:28Z",
  "status": "Succeeded",
  "createdDateTime": "2024-02-29T15:46:07Z",
  "locale": "en-US",
  "displayName": "20240228 Whisper Large V2",
  "description": "OpenAI Whisper Model in Azure AI Speech (Whisper v2-large)"
},

設定完整模型 URI，如 eastus 區域的此範例所示。以您的語音資源金鑰取代 YourSubscriptionKey。如果您使用不同的區域，請取代 eastus。

curl -v -X POST -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey" -H "Content-Type: application/json" -d '{
  "contentUrls": [
    "https://crbn.us/hello.wav",
    "https://crbn.us/whatstheweatherlike.wav"
  ],
  "locale": "en-US",
  "displayName": "My Transcription",
  "model": {
    "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/e418c4a9-9937-4db7-b2c9-8afbff72d950"
  },
  "properties": {
    "wordLevelTimestampsEnabled": true,
  },
}'  "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions"

設定完整模型 URI，如 eastus 區域的此範例所示。如果您使用不同的區域，請取代 eastus。

spx batch transcription create --name "My Transcription" --language "en-US" --content https://crbn.us/hello.wav,https://crbn.us/whatstheweatherlike.wav --model "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/e418c4a9-9937-4db7-b2c9-8afbff72d950" --api-version v3.2

指定目的地容器 URL

謄寫結果可以儲存在 Azure 容器中。如果您未指定容器，語音服務會將結果儲存在由 Microsoft 管理的容器中。在該情況下，刪除謄寫作業時，也會一併刪除謄寫結果資料。

您可以使用批次謄寫建立要求中的 destinationContainerUrl 選項，將批次謄寫結果儲存至可寫入的 Azure Blob 儲存體容器。此選項僅使用臨機操作 SAS URI，且不支援受信任的 Azure 服務安全性機制。此選項也不支援以存取原則為基礎的 SAS。 目的地容器的儲存體帳戶資源必須允許所有外部流量。

若要使用受信任的 Azure 服務安全性機制將轉譯結果儲存在 Azure Blob 儲存體容器中，請考慮使用自備儲存體 (BYOS)。如需詳細資訊，請參閱使用自備儲存體 (BYOS) 語音資源將語音轉為文字。

共用方式為

建立批次謄寫

必要條件

建立謄寫作業

要求設定選項

使用自訂模型

使用 Whisper 模型

指定目的地容器 URL

意見反應

其他資源

共用方式為

建立批次謄寫

必要條件

建立謄寫作業

要求設定選項

使用自訂模型

使用 Whisper 模型

指定目的地容器 URL

相關內容

意見反應

其他資源