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

發行項
10/16/2024

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

重要

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

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

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

批次合成 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。

在路徑設定必要的 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。您可以選擇在 URL 中設定 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 為「成功」) 後，即可下載音訊輸出結果。使用來自批次合成 GET 回應的 outputs.result 屬性的 URL。

若要取得批次合成結果檔案，請使用 URI 來提出 HTTP GET 要求，如下列範例所示。以來自批次合成 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 Created 表示批次合成建立要求 (透過 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 語音資源，但該區域僅支援標準語音資源定價層。

HTTP 404 錯誤

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

HTTP 429 error

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

HTTP 500 錯誤

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

HTTP error 範例

以下是導致 HTTP 400 error 的範例要求，因為需要 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 範例

下一步

意見反應

其他資源