WebSocket 介面

開啟連線

您可以透過 WebSocket Secure (WSS) 通訊協定來呼叫 /v1/synthesize 方法，以開啟與服務的連線。 此方法可用於下列端點：

wss://api.{location}.text-to-speech.watson.cloud.ibm.com/instances/{instance_id}/v1/synthesize

其中 {location} 指出管理應用程式的位置：

• us-south，適用於達拉斯
• us-east，適用於華盛頓特區
• eu-de，適用於法蘭克福
• au-syd，適用於雪梨
• jp-tok，適用於東京
• eu-gb，適用於倫敦
• kr-seo，適用於首爾

而 {instance_id} 是服務實例的唯一 ID。

文件中的範例將 wss://api.{location}.text-to-speech.watson.cloud.ibm.com/instances/{instance_id} 縮寫為 {ws_url}。 因此所有 WebSocket 範例都會以 {ws_url}/v1/synthesize 方式呼叫方法。

WebSocket 用戶端使用下列查詢參數呼叫 /v1/synthesize 方法，以建立與服務的認證連線：

access_token （必填字串）

傳遞有效的存取記號以向服務鑑別。 您必須在存取記號到期之前使用它。

• [IBM Cloud] {: tag-ibm-cloud}傳遞Identity and Access Management(IAM) 存取權杖以透過服務進行身份驗證。 您會傳遞 IAM 存取記號，而不是使用呼叫來傳遞 API 金鑰。 如需詳細資訊，請參閱 驗證 IBM Cloud。
• IBM Cloud Pak for DataIBM Software Hub 傳送存取權標，就像 請求的 標頭一樣。HTTP Authorization 如需詳細資訊，請參閱 驗證 IBM Cloud Pak for Data。

voice （可選字串）

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

customization_id （可選字串）

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

rate_percentage （可選整數）

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

pitch_percentage （可選整數）

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

spell_out_mode （可選字串）

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

x-watson-metadata （可選字串）

建立客戶 ID 與透過連線傳遞之資料的關聯。 此參數接受引數 customer_id={id}，其中 id 是要與資料相關聯的隨機或通用字串。 您必須將引數以 URL 編碼為參數，例如，customer_id%3dmy_customer_ID。 依預設，沒有客戶 ID 與資料相關聯。 如需相關資訊，請參閱資訊安全。

x-watson-learning-opt-out （可選布林值）

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

JavaScript 程式碼的下列 Snippet 會開啟與服務的連線。 呼叫 /v1/synthesize 方法會傳遞 voice 和 access_token 查詢參數，而前者會引導服務使用美式英文 Allison 語音。 一旦建立連線，就會定義事件監聽器 (onOpen(), onClose() 等等) 來回應服務的事件。

var access_token = '{access_token}';
var wsURI = '{ws_url}/v1/synthesize'
  + '?access_token=' + access_token
  + '&voice=en-US_AllisonV3Voice';
var websocket = new WebSocket(wsURI);

websocket.onopen = function(evt) { onOpen(evt) };
websocket.onclose = function(evt) { onClose(evt) };
websocket.onmessage = function(evt) { onMessage(evt) };
websocket.onerror = function(evt) { onError(evt) };

傳送輸入文字

若要合成文字，用戶端會傳送簡單的 JSON 文字訊息給服務，並附上下列參數：

text （必填字串）

提供要合成的文字。 用戶端可以傳遞純文字，或使用「語音合成標記語言 (SSML)」註釋的文字。 用戶端可以搭配要求最多傳送 5 KB 的輸入文字。 此限制包括您指定的任何 SSML。 如需相關資訊，請參閱指定輸入文字，以及其後的小節。 (SSML 輸入也可以包含 <mark> 元素）。 如需相關資訊，請參閱 指定音訊格式。）

accept （必填字串）

指定音訊的要求格式（MIME 類型）。 請使用 */* 來要求預設音訊格式，即 audio/ogg;codecs=opus。 有關詳細信息，請參閱 使用音訊格式。

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

timings （可選字串[ ])

指定服務要針對輸入文字的所有字串傳回字組計時資訊。 服務會傳回一個輸入記號的開始及結束時間。 請指定 words 作為陣列的 lone 元素，來要求字組計時。 指定空陣列或省略參數，則不接收字組計時。 有關更多信息，請參閱 生成單字計時。 不支援日文輸入文字。

JavaScript 程式碼的下列 Snippet 會傳遞簡單的“Hello world”訊息作為輸入文字，並要求音訊的預設格式。 這些呼叫包含在為用戶端定義的 onOpen() 函式中，以確保只有在連線建立後才會傳送。

function onOpen(evt) {
  var message = {
    text: 'Hello world',
    accept: '*/*'
  };
  websocket.send(JSON.stringify(message));
}

服務會傳送一則文字訊息確認音訊回應的格式，來回應此訊息。 下列回應確認預設音訊格式。

{
  'binary_streams': [
    {
      content_type: 'audio/ogg;codecs=opus'
    }
  ]
}

接收回應

在確認音訊格式之後，服務會以指示的格式將合成音訊當作二進位資料串流傳送。 對於包含標頭的音訊格式（例如，audio/wav 和 audio/ogg），服務會在傳送音訊資料之前傳回標頭。 標頭可以跨越多個二進位回應。 對於所有音訊格式，用戶端需要附加來自服務的所有二進位回應，才能組合完整的音訊回應。

除了傳送確認所要求音訊格式的文字訊息外，服務也可以傳送具有警告或錯誤的文字訊息。 服務也會傳送一個以上的文字訊息，而文字訊息中在下列情況會包含計時資訊：

• 輸入文字包含一個或多個 SSML <mark> 元素。
• 您指定 timings 參數與要求搭配。

用戶端可以處理文字訊息，方法是予以回應、顯示，或擷取以供應用程式使用（例如，如果它們包含標記位置）。

服務在完成合成輸入文字，並傳送所有二進位和文字訊息時，會自動關閉 WebSocket 連線。 以下簡單的 onMessage() 函式會根據服務接收到的文字和二進位訊息類型，將其附加到適當的變數中。 onClose() 函數執行時，已收到整個音訊串流，且服務不會傳送進一步的二進位或文字訊息。

var messages;
var audioStream;

function onMessage(evt) {
  if (typeof evt.data === string) {
    messages += evt.data;
  } else {
    console.log('Received ' + evt.data.size() + ' binary bytes');
    audioStream += evt.data;
  }
}

function onClose(evt) {
  // The service's response is complete.
}

WebSocket 回覆碼

服務可以透過 WebSocket 連線，將下列回覆碼傳送至用戶端：

• 1000 指出正常關閉連線，這表示已完成建立連線的目的。
• 1002 指出由於通訊協定錯誤，服務正在關閉連線。
• 1006 指出連線異常關閉。
• 1009 指出訊框大小超出 4 MB 限制。
• 1011 指出服務正在終止連線，因為它遇到的非預期狀況阻止它完成要求，例如無效的引數。 回覆碼也可以指出輸入文字太大。

如果 Socket 由於錯誤而關閉，則服務會在關閉之前，將表單 {"error": "Specific error message"} 的參考訊息傳送給用戶端。 服務也會針對不明參數傳送不嚴重的警告訊息。 有關 WebSocket 回傳碼的詳細資訊，請參閱 Internet Engineering Task Force (IETF) Request for Comments(RFC)6455。

SDK 的WebSocket實作可以傳回不同或附加的回應代碼。

{
  "warnings": "Unknown arguments: invalid-parameter."
}