文字到語音轉換的批次合成 API

發行項
04/07/2024

Batch 合成 API 可以異步合成大量的文字輸入（長和短）。發行者和音訊內容平台可以在批次中建立長音訊內容。例如：有聲書、新聞文章和文件。批次合成 API 可以建立超過 10 分鐘的合成音訊。

重要

Batch 合成 API 已正式推出。長音訊 API 將於 2027 年 4 月 1 日淘汰。如需詳細資訊，請參閱移轉至批次合成 API。

批次合成 API 是非同步的，不會即時傳回合成的音訊。您提交文字檔以進行合成、輪詢狀態，並在狀態指出成功時下載音訊輸出。文字輸入必須是純文字或語音合成標記語言 (SSML) 文字。

此圖表提供工作流程的高階概觀。

Batch 合成 API 工作流程的圖表。

提示

您也可以使用語音 SDK 來建立超過 10 分鐘的合成音訊，方法是逐一查看文字並以區塊合成。如需 C# 範例，請參閱 GitHub。

您可以使用下列 REST API 作業來進行批次合成：

作業	方法	REST API 呼叫
建立批次合成	`PUT`	texttospeech/batchsyntheses/YourSynthesisId
取得批次合成	`GET`	texttospeech/batchsyntheses/YourSynthesisId
列出批次合成	`GET`	texttospeech/batchsyntheses
刪除批次合成	`DELETE`	texttospeech/batchsyntheses/YourSynthesisId

如需程式碼範例，請參閱 GitHub。

建立批次合成

若要提交批次合成要求，請根據下列指示建構 HTTP PUT 要求路徑和本文：

設定必要的 inputKind 屬性。
如果 inputKind 屬性設定為 "PlainText"，則您也必須在 synthesisConfig 中設定 voice 屬性。在下列範例中，inputKind 會設定為 "SSML"，因此 synthesisConfig 不會設定。
您可以選擇性地設定 description、timeToLiveInHours 及其他屬性。如需詳細資訊，請參閱批次合成屬性。

注意

將接受的 JSON 承載大小上限為 2 MB。每個語音資源最多可以有 300 個批次合成作業同時執行。

在路徑設定必要的 YourSynthesisId 。 YourSynthesisId必須是唯一的。長度必須為 3-64，只包含數位、字母、連字元、底線和點，開頭和結尾為字母或數位。

使用 URI 提出 HTTP PUT 要求，如下列範例所示。以您的語音資源金鑰取代 YourSpeechKey、以您的語音資源區域取代 YourSpeechRegion，並設定要求本文屬性，如前所述。

curl -v -X PUT -H "Ocp-Apim-Subscription-Key: YourSpeechKey" -H "Content-Type: application/json" -d '{
    "description": "my ssml test",
    "inputKind": "SSML",
    "inputs": [
        {
            "content": "<speak version=\"1.0\" xml:lang=\"en-US\"><voice name=\"en-US-JennyNeural\">The rainbow has seven colors.</voice></speak>"
        }
    ],
    "properties": {
        "outputFormat": "riff-24khz-16bit-mono-pcm",
        "wordBoundaryEnabled": false,
        "sentenceBoundaryEnabled": false,
        "concatenateResult": false,
        "decompressOutputFiles": false
    }
}'  "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01"

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

{
  "id": "YourSynthesisId",
  "internalId": "7ab84171-9070-4d3b-88d4-1b8cc1cb928a",
  "status": "NotStarted",
  "createdDateTime": "2024-03-12T07:23:18.0097387Z",
  "lastActionDateTime": "2024-03-12T07:23:18.0097388Z",
  "inputKind": "SSML",
  "customVoices": {},
  "properties": {
    "timeToLiveInHours": 744,
    "outputFormat": "riff-24khz-16bit-mono-pcm",
    "concatenateResult": false,
    "decompressOutputFiles": false,
    "wordBoundaryEnabled": false,
    "sentenceBoundaryEnabled": false
  }
}

status 屬性應會從 NotStarted 狀態進展到 Running，最後進展到 Succeeded 或 Failed。您可以定期呼叫 GET 批次合成 API，直到傳回的狀態變為 Succeeded 或 Failed 為止。

取得批次合成

若要取得批次合成作業的狀態，請使用 URI 來提出 HTTP GET 要求，如下列範例所示。將取代 YourSpeechKey 為您的語音資源密鑰，並將取代 YourSpeechRegion 為您的語音資源區域。

curl -v -X GET "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"

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

{
  "id": "YourSynthesisId",
  "internalId": "7ab84171-9070-4d3b-88d4-1b8cc1cb928a",
  "status": "Succeeded",
  "createdDateTime": "2024-03-12T07:23:18.0097387Z",
  "lastActionDateTime": "2024-03-12T07:23:18.7979669",
  "inputKind": "SSML",
  "customVoices": {},
  "properties": {
    "timeToLiveInHours": 744,
    "outputFormat": "riff-24khz-16bit-mono-pcm",
    "concatenateResult": false,
    "decompressOutputFiles": false,
    "wordBoundaryEnabled": false,
    "sentenceBoundaryEnabled": false,
    "sizeInBytes": 120000,
    "succeededAudioCount": 1,
    "failedAudioCount": 0,
    "durationInMilliseconds": 2500,
    "billingDetails": {
      "neuralCharacters": 29
    }
  },
  "outputs": {
    "result": "https://stttssvcuse.blob.core.windows.net/batchsynthesis-output/29f2105f997c4bfea176d39d05ff201e/YourSynthesisId/results.zip?SAS_Token"
  }
}

從 outputs.result 中，您可以下載包含音訊 (例如 0001.wav)、摘要和偵錯詳細資料的 ZIP 檔案。如需詳細資訊，請參閱批次合成結果。

列出批次合成

若要列出語音資源的所有批次合成作業，請使用 URI 來提出 HTTP GET 要求，如下列範例所示。以您的語音資源金鑰取代 YourSpeechKey，而以您的語音資源區域取代 YourSpeechRegion。您可以選擇性地在 skip 網址設定和 maxpagesize （最多 100 個）查詢參數。 skip 的預設值為 0，而 maxpagesize 的預設值為 100。

curl -v -X GET "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses?api-version=2024-04-01&skip=1&maxpagesize=2" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"

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

{
  "value": [
    {
      "id": "my-job-03",
      "internalId": "5f7e9ab6-2c92-4dcb-b5ee-ec0983ee4db0",
      "status": "Succeeded",
      "createdDateTime": "2024-03-12T07:28:32.5690441Z",
      "lastActionDateTime": "2024-03-12T07:28:33.0042293",
      "inputKind": "SSML",
      "customVoices": {},
      "properties": {
        "timeToLiveInHours": 744,
        "outputFormat": "riff-24khz-16bit-mono-pcm",
        "concatenateResult": false,
        "decompressOutputFiles": false,
        "wordBoundaryEnabled": false,
        "sentenceBoundaryEnabled": false,
        "sizeInBytes": 120000,
        "succeededAudioCount": 1,
        "failedAudioCount": 0,
        "durationInMilliseconds": 2500,
        "billingDetails": {
          "neuralCharacters": 29
        }
      },
      "outputs": {
        "result": "https://stttssvcuse.blob.core.windows.net/batchsynthesis-output/29f2105f997c4bfea176d39d05ff201e/my-job-03/results.zip?SAS_Token"
      }
    },
    {
      "id": "my-job-02",
      "internalId": "5577585f-4710-4d4f-aab6-162d14bd7ee0",
      "status": "Succeeded",
      "createdDateTime": "2024-03-12T07:28:29.6418211Z",
      "lastActionDateTime": "2024-03-12T07:28:30.0910306",
      "inputKind": "SSML",
      "customVoices": {},
      "properties": {
        "timeToLiveInHours": 744,
        "outputFormat": "riff-24khz-16bit-mono-pcm",
        "concatenateResult": false,
        "decompressOutputFiles": false,
        "wordBoundaryEnabled": false,
        "sentenceBoundaryEnabled": false,
        "sizeInBytes": 120000,
        "succeededAudioCount": 1,
        "failedAudioCount": 0,
        "durationInMilliseconds": 2500,
        "billingDetails": {
          "neuralCharacters": 29
        }
      },
      "outputs": {
        "result": "https://stttssvcuse.blob.core.windows.net/batchsynthesis-output/29f2105f997c4bfea176d39d05ff201e/my-job-02/results.zip?SAS_Token"
      }
    }
  ],
  "nextLink": "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses?skip=3&maxpagesize=2&api-version=2024-04-01"
}

從 outputs.result 中，您可以下載包含音訊 (例如 0001.wav)、摘要和偵錯詳細資料的 ZIP 檔案。如需詳細資訊，請參閱批次合成結果。

json 回應中的 value 屬性會列出您的合成要求。此清單為分頁，頁面大小上限為 100。 "nextLink" 屬性會視需要提供，以取得編頁清單的下一頁。

刪除批次合成

在擷取音訊輸出結果之後，刪除批次合成作業歷程記錄。語音服務會將批次合成歷程記錄保留最多 31 天，或要求 timeToLiveInHours 屬性的持續時間，以較快的方式出現。合成作業的自動刪除日期和時間 (其狀態為「成功」或「失敗」) 等於 lastActionDateTime + timeToLiveInHours 屬性。

若要刪除批次合成作業，請使用 URI 來提出 HTTP DELETE 要求，如下列範例所示。以您的批次合成 ID 取代 YourSynthesisId、以您的語音資源金鑰取代 YourSpeechKey，並以您的語音資源區域取代 YourSpeechRegion。

curl -v -X DELETE "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"

如果刪除要求成功，回應標頭會包含 HTTP/1.1 204 No Content 。

批次合成結果

取得批次合成作業 (status 為「成功」) 後，即可下載音訊輸出結果。使用來自取得批次合成回應的 outputs.result 屬性的 URL。

若要取得批次合成結果檔案，請使用 URI 來提出 HTTP GET 要求，如下列範例所示。以來自取得批次合成回應的 outputs.result 屬性的 URL 取代 YourOutputsResultUrl。以您的語音資源金鑰取代 YourSpeechKey。

curl -v -X GET "YourOutputsResultUrl" -H "Ocp-Apim-Subscription-Key: YourSpeechKey" > results.zip

結果會在一個 ZIP 檔案中，其中包含音訊 (例如 0001.wav)、摘要和偵錯詳細資料。每個檔名的編號前置詞 (如下的 [nnnn] 所示)，與建立批次合成時所使用的文字輸入順序相同。

注意

[nnnn].debug.json 檔案包含合成結果 ID 及其他可能有助於疑難排解的資訊。它所包含的屬性可能會變更，因此您不應該採用 JSON 格式的任何相依性。

摘要檔案包含每個文字輸入的合成結果。以下為範例 summary.json 檔案：

{
  "jobID": "7ab84171-9070-4d3b-88d4-1b8cc1cb928a",
  "status": "Succeeded",
  "results": [
    {
      "contents": [
        "<speak version=\"1.0\" xml:lang=\"en-US\"><voice name=\"en-US-JennyNeural\">The rainbow has seven colors.</voice></speak>"
      ],
      "status": "Succeeded",
      "audioFileName": "0001.wav",
      "properties": {
        "sizeInBytes": "120000",
        "durationInMilliseconds": "2500"
      }
    }
  ]
}

如果已要求句子界限數據（"sentenceBoundaryEnabled": true），則結果中會包含對應的 [nnnn].sentence.json 檔案。同樣地，如果要求字邊界數據（"wordBoundaryEnabled": true），則會在結果中包含對應的 [nnnn].word.json 檔案。

以下是音訊位移和持續 (毫秒) 的範例字組資料檔案：

[
  {
    "Text": "The",
    "AudioOffset": 50,
    "Duration": 137
  },
  {
    "Text": "rainbow",
    "AudioOffset": 200,
    "Duration": 350
  },
  {
    "Text": "has",
    "AudioOffset": 562,
    "Duration": 175
  },
  {
    "Text": "seven",
    "AudioOffset": 750,
    "Duration": 300
  },
  {
    "Text": "colors",
    "AudioOffset": 1062,
    "Duration": 625
  },
  {
    "Text": ".",
    "AudioOffset": 1700,
    "Duration": 100
  }
]

批次合成延遲和最佳做法

使用批次合成來產生合成語音時，請務必考慮所涉及的延遲，並遵循最佳做法來達成最佳結果。

批次合成的延遲

批次合成中的延遲取決於各種因素，包括輸入文字的複雜度、批次中的輸入數目，以及基礎硬體的處理功能。

批次合成的延遲如下所示（大約）：

合成語音輸出的 50% 延遲在 10-20 秒內。
合成語音輸出的 95% 延遲是在 120 秒內。

最佳作法

考慮應用程式的批次合成時，建議您評估延遲是否符合您的需求。如果延遲符合您所需的效能，批次合成可能是適合的選擇。不過，如果延遲不符合您的需求，您可能會考慮使用即時 API。

HTTP 狀態碼

本節詳細說明來自批次合成 API 的 HTTP 回應碼和訊息。

HTTP 200 正常

HTTP 200 OK 表示要求成功。

HTTP 201 Created

HTTP 201 建立表示建立批次合成要求（透過 HTTP PUT）成功。

HTTP 204 error

HTTP 204 error 表示要求成功，但資源不存在。例如：

您嘗試取得或刪除不存在的合成作業。
您已成功刪除合成作業。

HTTP 400 error

以下是可能導致 400 error 的範例：

outputFormat 不受支援或無效。請提供有效的格式值，或保留 outputFormat 空白以使用預設設定。
要求的文字輸入數目超過10,000的限制。
您嘗試使用無效的部署 ID 或未成功部署的自訂語音。請確定語音資源可以存取自訂語音，而且已成功部署自訂語音。您也必須確定 {"your-custom-voice-name": "your-deployment-ID"} 的對應在批次合成要求中是正確的。
您嘗試使用 F0 語音資源，但該區域僅支援標準語音資源定價層。
您嘗試建立新的批次合成作業，超過 300 個作用中作業的限制。每個語音資源最多可以有 300 個沒有「成功」或「失敗」狀態的批次合成作業。

HTTP 404 錯誤

無法找到指定的實體。請確定合成識別碼正確無誤。

HTTP 429 error

最近的要求太多。每個用戶端應用程式最多可針對每個語音資源每10秒提交100個要求。請降低每秒的要求數。

HTTP 500 錯誤

HTTP 500 Internal Server Error 表示要求失敗。回應本文會包含錯誤訊息。

HTTP error 範例

以下是導致 HTTP 400 錯誤的範例要求，因為 inputs 需要屬性才能建立作業。

curl -v -X PUT -H "Ocp-Apim-Subscription-Key: YourSpeechKey" -H "Content-Type: application/json" -d '{
    "inputKind": "SSML"
}'  "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01"

在這裡情況下，回應標頭會包含 HTTP/1.1 400 Bad Request。

回應本文類似下列 JSON 範例：

{
  "error": {
    "code": "BadRequest",
    "message": "The inputs is required."
  }
}

文字到語音轉換的批次合成 API

建立批次合成

取得批次合成

列出批次合成

刪除批次合成

批次合成結果

批次合成延遲和最佳做法

批次合成的延遲

最佳作法

HTTP 狀態碼

HTTP 200 正常

HTTP 201 Created

HTTP 204 error

HTTP 400 error

HTTP 404 錯誤

HTTP 429 error

HTTP 500 錯誤

HTTP error 範例

下一步

其他資源