將程式代碼從長音訊 API 遷移至 Batch 合成 API

  • 發行項

Batch 合成 API 提供長格式文字到語音轉換的異步合成。 本文說明從長音訊 API 升級至 Batch 合成 API 的優點，以及如何執行這項操作的詳細數據。

重要

批次合成 API 已正式推出。 長音訊 API 將於 2027 年 4 月 1 日淘汰。

基底路徑和版本

將端點從 https://YourSpeechRegion.customvoice.api.speech.microsoft.com 更新為 https://YourSpeechRegion.api.cognitive.microsoft.com ，或者您可以改用自定義網域： https://{customDomainName}.cognitiveservices.azure.com/。

將程式代碼中的基底路徑從 /texttospeech/v3.0/longaudiosynthesis 更新為 /texttospeech/batchsyntheses。

將版本從基底路徑更新為查詢字串/texttospeech/v3.0/longaudiosynthesis。?api-version=2024-04-01

例如，若要列出區域中語音資源的 eastus 合成作業，請使用 https://eastus.api.cognitive.microsoft.com/texttospeech/batchsyntheses?api-version=2024-04-01 而非 https://eastus.customvoice.api.speech.microsoft.com/api/texttospeech/v3.0/longaudiosynthesis。

區域與端點

批次合成 API 可在更多 語音區域中使用。

長音訊 API 僅限於下列區域：

區域 端點
澳大利亞東部 https://australiaeast.customvoice.api.speech.microsoft.com
美國東部 https://eastus.customvoice.api.speech.microsoft.com
印度中部 https://centralindia.customvoice.api.speech.microsoft.com
美國中南部 https://southcentralus.customvoice.api.speech.microsoft.com
東南亞 https://southeastasia.customvoice.api.speech.microsoft.com
英國南部 https://uksouth.customvoice.api.speech.microsoft.com
西歐 https://westeurope.customvoice.api.speech.microsoft.com

語音清單

批次合成 API 支援所有文字轉換語音的語音和樣式。

長音訊 API 僅限於 GET 要求 https://<endpoint>/api/texttospeech/v3.0/longaudiosynthesis/voices傳回的一組語音。

文字輸入

批次合成文字輸入會以最多 2 MB 的 JSON 承載傳送。

長音訊 API 文字輸入會從符合下列需求的檔案上傳：

  • 一個純文字 （.txt） 或 SSML 文字 （.txt） 檔案編碼為 UTF-8 與位元組順序標記 （BOM） 。 請勿使用壓縮檔案，例如 ZIP。 如果您有多個輸入檔案，則必須提交多個要求。
  • 針對 SSML 文字，包含超過 400 個字元的純文字或 400 個可計費字元，以及小於 1 萬個段落。 如果是純文本，每個段落都會以新行分隔。 針對 SSML 文字，會將每個 SSML 片段視為段落。 以不同的段落分隔 SSML 部分。

透過 Batch 合成 API，您可以使用任何 支援的 SSML 元素，包括 audio、 mstts:backgroundaudio和 lexicon 元素。 長音訊 API 不支援 audio、 mstts:backgroundaudio和 lexicon 元素。

音訊輸出格式

批次合成 API 支援所有文字轉換語音的音訊輸出格式。

長音訊 API 僅限於下列一組音訊輸出格式。 長音訊語音的取樣速率為 24kHz，而不是 48kHz。 合成時，可透過上取樣或下取樣來取得其他取樣率。

  • riff-8khz-16bit-mono-pcm
  • riff-16khz-16bit-mono-pcm
  • riff-24khz-16bit-mono-pcm
  • riff-48khz-16bit-mono-pcm
  • audio-16khz-32kbitrate-mono-mp3
  • audio-16khz-64kbitrate-mono-mp3
  • audio-16khz-128kbitrate-mono-mp3
  • audio-24khz-48kbitrate-mono-mp3
  • audio-24khz-96kbitrate-mono-mp3
  • audio-24khz-160kbitrate-mono-mp3

取得結果

使用批次合成 API 時，請使用 HTTP GET 批次合成回應之 屬性的 URL outputs.result 。 結果位於 ZIP 檔案中，其中包含音訊 （例如 0001.wav）、摘要和偵錯詳細數據。

長音訊 API 文字輸入和結果會透過兩個不同的內容 URL 傳回，如下列範例所示。 其中一個具有 "kind": "LongAudioSynthesisScript"，是已提交的輸入腳本。 另一個具有 "kind": "LongAudioSynthesisResult"，則是此要求的結果。 這兩個 ZIP 檔案都可以從其 links.contentUrl 屬性中的 URL 下載。

清除資源

批次合成 API 最多可支援 300 個沒有「成功」或「失敗」狀態的批次合成作業。 語音服務會將每個合成歷程記錄保留最多 31 天，或要求 timeToLiveInHours 屬性的持續時間，以較快的方式出現。 合成作業的自動刪除日期和時間 (其狀態為「成功」或「失敗」) 等於 lastActionDateTime + timeToLiveInHours 屬性。

長音訊 API 限制為每個 Azure 訂用帳戶要求 20,000 個。 語音服務不會自動移除作業歷程記錄。 您必須先移除先前的作業執行歷程記錄，才能提出其他超過限制的新要求。

下一步