打开连接

可以通过 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} 是服务实例的唯一标识。

文档中的示例将 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 (所需 string)

传递有效的访问令牌以向服务认证。 必须使用未到期的访问令牌。

• IBM Cloud通过Identity and Access Management（IAM）访问令牌来验证服务。 通过调用传递的是 IAM 访问令牌，而不是传递 API 密钥。 更多信息，请参见 验证至 IBM Cloud。
• IBM Cloud Pak for Data 传递访问令牌，就像在xml-ph-0001@deepl.internal请求中传递xml-ph-0000@deepl.internal标头一样。IBM Software Hub 传递访问令牌，就像在 请求中传递 标头一样。HTTP Authorization 更多信息，请参见 验证至 IBM Cloud Pak for Data。

voice (可选的 string)

指定音频中读文本的声音。 使用 /v1/voices 方法来获取受支持声音的当前列表。 省略参数，使用默认语音。 有关更多信息，请参阅 语言和语音 以及 使用默认语音。

customization_id (可选的 string)

指定用于合成的定制模型的全局唯一标识符（GUID）。 指定的定制模型必须与用于合成的声音的语言相匹配。 如果包含定制标识，那么必须使用拥有定制模型的服务实例的凭证来发出请求。 省略此参数可使用没有任何定制的指定声音。 有关更多信息，请参阅了解定制。

rate_percentage (可选的 integer)

指定整个合成请求的全局发言速率。 语速是指服务将文本合成为语音的速度。 语速越快，文字说得越快；语速越低，文字说得越慢。 该参数可更改整个请求的每个语音默认费率。 更多信息，请参阅 修改发言速率。

pitch_percentage (可选的 integer)

指定整个合成请求的全局发言音高。 说话音调代表服务合成的语音语调。 它表示听者感受到的声音音调的高低。 音调越高，语音语调越高；音调越低，语音语调越低。 该参数可更改整个请求中每个声部的默认音高。 更多信息，请参阅 修改说话音调。

spell_out_mode (可选的 string)

*对于德语语音，*指定字符串中各个字符的拼写方式。 默认情况下，该服务拼写单个字符的速度与合成语言文本的速度相同。 You can use the parameter to direct the service to spell out individual characters more slowly, in groups of one (singles), two (pairs), or three (triples). For more information, see 指定字符串的拼写方式.

x-watson-metadata (可选的 string)

将客户标识与通过连接传递的数据相关联。 此参数接受自变量 customer_id={id}，其中 id 是要与数据关联的随机或通用字符串。 必须对该自变量进行 URL 编码，以转入该参数，例如 customer_id%3dmy_customer_ID。 缺省情况下，没有客户标识与数据相关联。 有关更多信息，请参阅信息安全。

x-watson-learning-opt-out (可选的 boolean)

IBM Cloud 指示服务是否记录通过连接发送的请求和结果。 要阻止 IBM 访问您的数据以进行一般服务改进，请为此参数指定 true。 选择退出会指示IBM在磁盘中不写入您请求的用户数据（文本或音频）。 您也可以在账户级别选择退出。 有关更多信息，请参阅请求日志记录。

以下 JavaScript 代码片段将打开与服务的连接。 对 /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 (所需 string)

提供要合成的文本。 客户机可以传递纯文本或使用语音合成标记语言 (SSML) 进行注释的文本。 客户机在请求中最多可传递 5 KB 的输入文本。 此限制包括指定的任何 SSML。 有关更多信息，请参阅指定输入文本及其后面的各部分内容。 （SSML输入还可以包含 <mark> 元素。 有关更多信息，请参阅 指定 SSML 标记。）

accept (所需 string)

指定请求的音频格式（MIME 类型）。 使用 */* 可请求缺省音频格式 audio/ogg;codecs=opus。 更多信息，请参阅 使用音频格式。

Safari 浏览器不支持 Ogg 音频格式。 如果您在 Safari 浏览器上使用Text to Speech服务，则必须指定不同的格式，以便服务返回音频。

timings (可选的 string[ ])

指定服务将返回输入文本中所有字符串的词计时信息。 服务会返回输入中每个标记的开始时间和结束时间。 将 words 指定为数组的唯一元素，以请求词计时。 指定空数组或省略此参数时，不会收到任何词计时信息。 更多信息，请参阅 生成字定时。 不支持日语输入文本。

以下 JavaScript 代码片段将简单的“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 指示服务正在终止连接，因为服务遇到了阻止其执行请求的意外状况，例如无效自变量。 此返回码还可能指示输入文本太大。

如果套接字关闭并返回错误，那么在关闭之前，服务会向客户机发送格式为 {"error": "Specific error message"} 的参考消息。 此外，对于未知参数，服务会发送非致命警告消息。 有关 WebSocket 返回代码的更多信息，请参阅互联网工程任务组（IETF） 意见征询（RFC）6455。

SDK 的WebSocket实现可以返回不同或额外的响应代码。

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