文字轉換語音的批次合成屬性

發行項
10/16/2024

重要

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

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

當您建立新的批次合成作業時，需要 JSON 格式的某些屬性。其他屬性是選擇性的。批次合成回應包含其他屬性，以提供合成狀態和結果的相關資訊。例如，outputs.result 屬性包含具有音訊輸出和記錄的批次合成結果檔位置。

批次合成屬性

下表說明批次合成屬性。

屬性	說明
`createdDateTime`	建立批次合成作業的日期和時間。這個屬性是唯讀的。
`customVoices`	自訂語音名稱及其部署 ID 的對應。例如：`"customVoices": {"your-custom-voice-name": "502ac834-6537-4bc3-9fd6-140114daa66d"}` 您可以在 `synthesisConfig.voice` (當 `inputKind` 設為 `"PlainText"` 時) 或在 `inputs` 的 SSML 文字內 (當 `inputKind` 設為 `"SSML"` 時) 使用語音名稱。必須使用此屬性來使用自訂語音。如果您嘗試使用此處未定義的自訂語音，則服務會傳回錯誤。
`description`	批次合成的描述。這個屬性為選擇性。
`id`	您傳入路徑的批次合成作業識別碼。這是路徑中的必要屬性。
`inputs`	要合成的純文字或 SSML。當 `inputKind` 設為 `"PlainText"` 時，請提供純文字，如下所示：`"inputs": [{"text": "The rainbow has seven colors."}]`。當 `inputKind` 設為 `"SSML"` 時，請提供語音合成標記語言 (SSML) 格式的文字，如下所示：`"inputs": [{"text": "<speak version='\''1.0'\'' xml:lang='\''en-US'\''><voice xml:lang='\''en-US'\'' xml:gender='\''Female'\'' name='\''en-US-AvaMultilingualNeural'\''>The rainbow has seven colors.</voice></speak>"}]`。如果您想要多個音訊輸出檔案，請包含最多 1,000 個文字物件。以下是應該合成為兩個音訊輸出檔案的輸入文字範例：`"inputs": [{"text": "synthesize this to a file"},{"text": "synthesize this to another file"}]`。不過，如果 `properties.concatenateResult` 屬性設為 `true`，則每個合成的結果都會寫入同一個音訊輸出檔案。您不必為新段落分隔文字輸入。在任何的文字輸入 (最多 1,000 個) 內，您可以使用 "\r\n" (換行符號) 字串來指定新的段落。以下是應該合成至同一個音訊輸出檔的兩個段落的輸入文字範例：`"inputs": [{"text": "synthesize this to a file\r\nsynthesize this to another paragraph in the same file"}]` 沒有段落限制，但 JSON 承載大小上限 (包括所有文字輸入及其他屬性) 為 2 GB。當您建立新的批次合成作業時，需要這個屬性。當您取得合成作業時，這個屬性不會包含在回應中。
`internalId`	內部批次合成作業標識碼。這個屬性是唯讀的。
`lastActionDateTime`	`status` 屬性值變更的最近日期和時間。這個屬性是唯讀的。
`outputs.result`	含音訊輸出和記錄的批次合成結果檔的位置。這個屬性是唯讀的。
`properties`	一組已定義的選擇性批次合成組態設定。
`properties.sizeInBytes`	音訊輸出大小 (位元組)。這個屬性是唯讀的。
`properties.billingDetails`	`customNeuralCharacters` 與 `neuralCharacters` (預建) 聲音所處理和計費的字數。這個屬性是唯讀的。
`properties.concatenateResult`	判斷是否串連結果。此選用的 `bool` 值 ("true" 或 "false") 預設為 "false"。
`properties.decompressOutputFiles`	判斷是否要解壓縮目的地容器中的合成結果檔案。僅在設定 `destinationContainerUrl` 屬性時，才能設定這個屬性。此選用的 `bool` 值 ("true" 或 "false") 預設為 "false"。
`properties.destinationContainerUrl`	批次合成結果可以儲存在可寫入的 Azure 容器中。如果您未指定含共用存取簽章 (SAS) 權杖的容器 URI，則語音服務會將結果儲存在 Microsoft 所管理的容器中。不支援具有預存存取原則的 SAS。刪除合成作業時，也會刪除結果資料。當您取得合成作業時，回應中不會包含此選用的屬性。
`properties.destinationPath`	可以儲存批次合成結果的前置詞路徑。如果您未指定前置字路徑，則預設前置詞路徑為 `YourSpeechResourceId/YourSynthesisId`。僅在設定 `destinationContainerUrl` 屬性時，才能設定這個選用屬性。
`properties.durationInMilliseconds`	以毫秒為單位的音訊輸出持續時間。這個屬性是唯讀的。
`properties.failedAudioCount`	音訊輸出的批次合成輸入計數失敗。這個屬性是唯讀的。
`properties.outputFormat`	音訊輸出格式。如需接受值的相關資訊，請參閱音訊輸出格式。預設的輸出格式是 `riff-24khz-16bit-mono-pcm`。
`properties.sentenceBoundaryEnabled`	判斷是否要產生句子界限資料。此選用的 `bool` 值 ("true" 或 "false") 預設為 "false"。如果要求句子界限資料，則會在結果資料 ZIP 檔案中包含相對應的 `[nnnn].sentence.json` 檔案。
`properties.succeededAudioCount`	音訊輸出的批次合成輸入計數成功。這個屬性是唯讀的。
`properties.timeToLiveInHours`	當合成結果會自動刪除時，建立合成作業之後的持續時間 (小時)。此選用的設定依預設為 `744` (31 天)。存留時間上限為 31 天。合成作業的自動刪除日期和時間 (其狀態為「成功」或「失敗」) 等於 `lastActionDateTime` + `timeToLiveInHours` 屬性。否則，您可以呼叫刪除合成方法，以更快移除作業。
`properties.wordBoundaryEnabled`	判斷是否要產生字組界限資料。此選用的 `bool` 值 ("true" 或 "false") 預設為 "false"。如果要求字組界限資料，則會在結果資料 ZIP 檔案中包含相對應的 `[nnnn].word.json` 檔案。
`status`	批次合成處理狀態。狀態應該會從 "NotStarted" 進展為 "Running"，最後會進展為 "Succeeded" 或 "Failed"。這個屬性是唯讀的。
`synthesisConfig`	用於純文字批次合成的組態設定。此屬性僅在 `inputKind` 設為 `"PlainText"` 時才適用。
`synthesisConfig.backgroundAudio`	每個音訊輸出的背景音訊。此選用的屬性僅在 `inputKind` 設為 `"PlainText"` 時才適用。
`synthesisConfig.backgroundAudio.fadein`	背景音訊淡入的持續時間 (以毫秒為單位)。預設值為 `0`，等同於沒有淡入。接受的值：`0` 到 `10000` (含)。如需詳細資訊，請參閱語音合成標記語言 (SSML) 文件中新增背景音訊底下的屬性資料表。會忽略無效值。此選用的屬性僅在 `inputKind` 設為 `"PlainText"` 時才適用。
`synthesisConfig.backgroundAudio.fadeout`	背景音訊淡出的持續時間 (以毫秒為單位)。預設值為 `0`，相當於不淡出。接受的值： `0` 到 `10000` (含)。如需詳細資訊，請參閱語音合成標記語言 (SSML) 文件中新增背景音訊底下的屬性資料表。會忽略無效值。此選用的屬性僅在 `inputKind` 設為 `"PlainText"` 時才適用。
`synthesisConfig.backgroundAudio.src`	背景音訊檔案的 URI 位置。如需詳細資訊，請參閱語音合成標記語言 (SSML) 文件中新增背景音訊底下的屬性資料表。會忽略無效值。設定 `synthesisConfig.backgroundAudio` 時，需要這個屬性。
`synthesisConfig.backgroundAudio.volume`	背景音訊檔案的音量。接受的值：`0` 到 `100` (含)。預設值是 `1`。如需詳細資訊，請參閱語音合成標記語言 (SSML) 文件中新增背景音訊底下的屬性資料表。會忽略無效值。此選用的屬性僅在 `inputKind` 設為 `"PlainText"` 時才適用。
`synthesisConfig.pitch`	音訊輸出的音調。如需接受值的相關資訊，請參閱語音合成標記語言 (SSML) 文件中的調整韻律表格。會忽略無效值。此選用的屬性僅在 `inputKind` 設為 `"PlainText"` 時才適用。
`synthesisConfig.rate`	音訊輸出的速率。如需接受值的相關資訊，請參閱語音合成標記語言 (SSML) 文件中的調整韻律表格。會忽略無效值。此選用的屬性僅在 `inputKind` 設為 `"PlainText"` 時才適用。
`synthesisConfig.role`	對於某些語音，您可以調整說話的角色扮演。該語音可以模仿不同的年齡和性別，但語音名稱不會變更。例如，男性語音可以提高音調並變更語調以模仿女性聲音，但語音名稱不變。如果您的語音缺少或不支援該角色，則會忽略此屬性。如需每個語音可用樣式的相關資訊，請參閱語音樣式和角色。此選用的屬性僅在 `inputKind` 設為 `"PlainText"` 時才適用。
`synthesisConfig.speakerProfileId`	個人語音的說話者設定檔標識碼。如需可用個人語音基本模型名稱的詳細資訊，請參閱整合個人語音。如需如何取得說話者設定檔標識碼的詳細資訊，請參閱語言和語音支援。當 `inputKind` 設為 `"PlainText"` 時需要此屬性。
`synthesisConfig.style`	對於某些語音，您可以調整說話風格來表達不同情緒 (例如愉快、同理、平靜)。您可以針對不同案例進行語音最佳化 (例如客戶服務、新聞廣播、語音助理)。如需每個語音可用樣式的相關資訊，請參閱語音樣式和角色。此選用的屬性僅在設定 `synthesisConfig.style` 時才適用。
`synthesisConfig.styleDegree`	說話風格的強度。您可以指定較強烈或較柔和的風格，讓語音更有感情或更柔和。接受的值涵蓋範圍：0.01 到 2。預設值為 1，代表的是預先定義的風格強度。最小單位是 0.01，會讓語音略微傾向目標風格。值為 2 則會讓預設風格強度加倍。如果語音缺少或不支援風格等級，則會忽略此屬性。如需每個語音可用樣式的相關資訊，請參閱語音樣式和角色。此選用的屬性僅在 `inputKind` 設為 `"PlainText"` 時才適用。
`synthesisConfig.voice`	說出音訊輸出的語音。如需可用預先組建神經語音的相關資訊，請參閱語言和語音支援。若要使用自訂語音，您必須在 `customVoices` 屬性中指定有效的自訂語音和部署 ID 對應。若要使用個人語音，您必須指定 `synthesisConfig.speakerProfileId` 屬性。當 `inputKind` 設為 `"PlainText"` 時需要此屬性。
`synthesisConfig.volume`	音訊輸出的音量。如需接受值的相關資訊，請參閱語音合成標記語言 (SSML) 文件中的調整韻律表格。會忽略無效值。此選用的屬性僅在 `inputKind` 設為 `"PlainText"` 時才適用。
`inputKind`	指出 `inputs` 文字屬性是否應為純文字或 SSML。可能不區分大小寫的值是 "PlainText" 和 "SSML"。當 `inputKind` 設為 `"PlainText"` 時，您也必須設定 `synthesisConfig` 語音屬性。此屬性是必要項。

批次合成延遲和最佳做法

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

批次合成的延遲

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

批次合成的延遲如下所示 (大約)：

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

最佳作法

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

HTTP 狀態碼

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

HTTP 200 正常

HTTP 200 OK 表示要求成功。

HTTP 201 Created

HTTP 201 Created 表示建立批次合成要求 (透過 HTTP POST) 成功。

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."
  }
}

共用方式為