将文本合成为音频

要将文本合成为音频，请调用服务的 /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 (query parameter, 可选的 string)

指定请求的音频格式或 MIME 类型，服务将使用此种格式返回音频。 您还可以使用 HTTP Accept 请求头来指定此值。 请对该自变量进行 URL 编码，使其成为 accept 查询参数。 默认情况下，该服务以 audio/ogg;codecs=opus 格式返回音频。 更多信息，请参阅 使用音频格式。

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

voice (query parameter, 可选的 string)

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

customization_id (query parameter, 可选的 string)

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

rate_percentage (query parameter, 可选的 integer)

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

pitch_percentage (query parameter, 可选的 integer)

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

spell_out_mode (query parameter, 可选的 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 (request header, 可选的 string)

将客户ID与请求传递的数据相关联。 有关更多信息，请参阅信息安全。

X-Watson-Learning-Opt-Out (request header, 可选的 boolean)

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

如果在 /v1/synthesize 方法的输入中指定了无效的查询参数或 JSON 字段，那么服务会返回 Warnings 响应头，用于描述并列出每个无效的自变量。 尽管出现警告，请求仍会成功。

指定输入文本

POST 和 GET /v1/synthesize 两种方法都接受纯文本输入或带有SSML注释的文本。 这两个版本的主要区别在于如何指定要合成的文本。 下面的示例都传递了纯文本 Hello world。

• POST /v1/synthesize 方法接受请求主体中的输入文本。 您可以通过简单的JSON结构指定输入，其中包含纯文本或SSML。 此外，还必须为 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 编码。

  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 正确且格式无误。 因此，不管输入是否包含 SSML，都必须对输入文本中存在的任何 XML 控制字符进行转义。 请使用表 1 中的等效转义字符串或字符编码而不是指示的字符。

有关服务如何验证输入文本的更多信息，请参阅 SSML 验证。

输入文本示例

以下示例说明了如何使用 HTTP 接口的任一方法来指定输入文本。 此外，还说明了如何对 XML 控制字符进行转义。 出于可读性目的，示例包含换行符。 但在实际输入中，不要包含换行符。

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