將文字合成為音訊

若要將文字合成為音訊，您可以呼叫服務的兩個 /v1/synthesize 方法版本之一：

• GET /v1/synthesize 方法接受要當作必要 text 查詢參數合成的文字。 要求的大小上限為 8 KB，其中包括輸入文字、指定的任何 SSML 以及 URL 和標頭。
• POST /v1/synthesize 方法接受要在必要的要求內文中當作 JSON 建構合成的文字。 若為 URL 和標頭，要求的大小上限為 8 KB，若為要求內文中傳送的輸入文字，則為 5 KB。 5 KB 限制包括您指定的任何 SSML。

/v1/synthesize 方法的兩個版本一般具有下列參數：

accept （查詢參數，可選字串）

指定所要求的音訊格式或 MIME 類型，服務會以此格式或類型傳回音訊。 您也可以使用 HTTP Accept 要求標頭來指定此值。 將引數以 URL 編碼為 accept 查詢參數。 預設情況下，服務會以 audio/ogg;codecs=opus 的格式傳回音訊。 有關詳細信息，請參閱 使用音訊格式。

Safari 瀏覽器不支援 Ogg 音訊格式。 如果您在 Safari 瀏覽器中使用Text to Speech服務，則必須指定您希望服務傳回音訊的不同格式。

voice （查詢參數，可選字串）

指定要在音訊中說出的文字語音。 請使用 /v1/voices 方法，取得支援的語音現行清單。 省略此參數可使用預設語音。 有關詳細信息，請參閱 語言和語音 和 使用預設語音。

customization_id （查詢參數，可選字串）

指定用於合成的自訂模型的全球唯一識別碼 (GUID)。 指定的自訂模型必須符合用於合成之語音的語言。 如果您包含了自訂作業 ID，則必須使用擁有自訂模型之服務實例的認證來提出要求。 省略此參數，會使用沒有自訂作業的指定語音。 如需相關資訊，請參閱瞭解自訂作業。

rate_percentage (查詢參數，可選整數)

指定整個合成請求的全域語速。 語速是服務說出其合成為語音的文字的速度。 速率越高，文字朗讀越快；較低的速率會導致文字說得更慢。 此參數會變更整個請求的每個語音預設速率。 有關詳細信息，請參閱 修改語速。

pitch_percentage (查詢參數，可選整數)

指定整個合成請求的全域講話音調。 說話音調代表服務合成的語音的語氣。 它代表聽者感知到的音調的高低。 音調越高，講話的音調越高；較低的音調導致以較低的音調說話。 此參數會變更整個請求的每個語音的預設音調。 有關更多信息，請參閱 修改說話音高。

spell_out_mode （查詢參數，可選字串）

*對於德語語音，*指定如何拼寫字串中的各個字元。 預設情況下，該服務以與合成語言文字相同的速率拼出各個字元。 您可以使用此參數指示服務以一個 ( singles )、兩個 ( pairs ) 或三個 ( triples ) 為一組，以較慢的速度拼出單一字元。有關詳細信息，請參閱 指定字串的拼寫方式。

X-Watson-Metadata （請求頭，可選字串）

將客戶 ID 與要求傳送的資料相關聯。 如需相關資訊，請參閱資訊安全。

X-Watson-Learning-Opt-Out （請求標頭，可選布林值）

IBM Cloud 表示服務是否記錄要求和回應資料，以便為未來使用者改善服務。 若要防止 IBM 存取您的資料進行一般服務改善，請將參數指定為 true。 選擇退出將指示IBM不會根據您的請求向磁碟寫入任何使用者資料（文字或音訊）。 您也可以在帳戶層級選擇退出。 如需相關資訊，請參閱要求記載。

如果您指定無效的查詢參數或 JSON 欄位，作為 /v1/synthesize 方法之輸入一部分，則服務會傳回 Warnings 回應標頭，用於說明並列出每個無效的引數。 儘管出現警告，要求仍會成功。

指定輸入文字

POST 和 GET /v1/synthesize 兩種方法都接受純輸入文字或使用 SSML 註釋的文字。 這兩個版本的差異主要在於您如何指定要合成的文字。 以下範例均傳遞純文字 Hello world。

• POST /v1/synthesize 方法接受要求內文中的輸入文字。 您可以使用包含純文字或 SSML 的簡單 JSON 結構指定輸入。 您也必須針對 application/json 標頭指定 Content-Type 的值。

  IBM Cloud

  curl -X POST -u "apikey:{apikey}" \
  --header "Content-Type: application/json" \
  --header "Accept: audio/wav" \
  --output hello_world.wav \
  --data "{\"text\":\"Hello world\"}" \
  "{url}/v1/synthesize?voice=en-US_MichaelV3Voice"
  

  IBM Cloud Pak for Data IBM Software Hub

  curl -X POST \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --header "Accept: audio/wav" \
  --output hello_world.wav \
  --data "{\"text\":\"Hello world\"}" \
  "{url}/v1/synthesize?voice=en-US_MichaelV3Voice"
  

• GET /v1/synthesize 方法接受 text 查詢參數所指定的輸入文字。 您可以指定輸入為純文字或 SSML，兩者都必須是 URL-encoded。

  IBM Cloud

  curl -X GET -u "apikey:{apikey}" \
  --header "Accept: audio/wav" \
  --output hello_world.wav \
  "{url}/v1/synthesize?text=Hello%20world&voice=en-US_MichaelV3Voice"
  

  IBM Cloud Pak for Data IBM Software Hub

  curl -X GET \
  --header "Authorization: Bearer {token}" \
  --header "Accept: audio/wav" \
  --output hello_world.wav \
  "{url}/v1/synthesize?text=Hello%20world&voice=en-US_MichaelV3Voice"""
  

雖然 POST 和 GET 方法提供相等的功能，但使用 POST 方法將輸入文字傳送到服務總是比較安全。 POST 請求在請求正文中傳遞輸入。 GET 請求會公開 URL 中的資料。

標點輸入文字

使用您通常使用的標點符號編寫用於合成的文字。 例如，像正常寫作一樣包括逗號、句號、感嘆號和問號。

該服務在合成文字時考慮標點符號。 例如，逗號和句尾標點符號會透過在生成的合成語音中的適當位置插入停頓來影響音訊。 句末標點符號，如句號、感嘆號和問號也會改變說話的語調和語調。 您也可以使用 SSML 元素來影響演講的這些方面。

指定 SSML 輸入

「語音合成標記語言 (SSML)」是 XML 型標記語言，其設計旨在為語音合成應用程式（例如 Text to Speech 服務）提供文字註釋。 您可以使用 SSML 元素及其屬性，以便更進一步控制合成及產生的音訊輸出。

有關使用 SSML 註釋輸入文字的詳細資訊，請參閱 瞭解 SSML。 有關所有支援的元素和屬性的清單，請參閱 SSML 元素。

跳出 XML 控制字元

因為您可以提交包括 XML 型 SSML 註釋的輸入文字，所以服務會驗證所有輸入，以確保任何 SSML 正確無誤且格式正確。 因此，您必須跳出所有存在於輸入文字中的 XML 控制字元，不論輸入是否包括 SSML。 請使用表 1 的相等跳出字串或字元編碼，而不是指出的字元。

如需服務如何驗證輸入文字的相關資訊，請參閱 SSML 驗證。

輸入文字的範例

下列範例顯示如何使用 HTTP 介面的任一種方法來指定輸入文字。 它們也顯示如何跳出 XML 控制字元。 這些範例包含換行符號，以方便閱讀。 請不要 在實際輸入中包含換行符號。

"What have I learned?" he asked. "Everything!"