共用方式為

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

  • 發行項

重要

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

Batch 合成 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 MB。

當您建立新的批次合成作業時，需要這個屬性。 當您取得合成作業時，這個屬性不會包含在回應中。
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 錯誤的範例要求，因為 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."
  }
}

下一步