创建和管理定制条目

定制模型存在后，下一步是以词/转换项对的格式添加定制条目，以定义指定的词在合成期间如何发音。这些定义会覆盖服务的缺省常规发音规则。可以一次添加和查询一个或多个词的转换项，并且可以删除不再需要的各个词。熟悉定制接口后，可以一次性处理多个词，这比逐词处理要方便得多。对于拥有定制模型的服务实例，您必须使用该实例的凭证，才能利用需要其定制标识的任何方法。

有关适用于定制条目的规则和限制的更多信息，请参阅用于创建定制条目的规则。

不要使用需要进行 URL 编码的字符。例如，不要在名称中使用空格、斜杠、反斜杠、冒号、与号、双引号、加号、等号、问号等。该服务并不禁止使用这些字符，但由于它们在任何地方使用都必须经过 URL 编码，因此强烈建议不要使用。

向定制模型添加单个词

要向定制模型添加单个词/转换项对，请使用 PUT /v1/customizations/{customization_id}/words/{word} 方法。可在此方法的 URL 中指定要添加的词。通过单个 translation 属性提供词的转换项作为 JSON 对象。向模型中已存在的词添加新的转换项会覆盖该词的现有转换项。

可以使用近似读音方法或音标方法（或这两者的组合）来提供转换项。对于音标转换项，可以使用国际音标 (IPA) 或 IBM 符号音标表示法 (SPR) 格式。以下示例使用不同的方法将词 IEEE 的等效转换项添加到定制模型。所需的 Content-Type 报头将输入类型标识为 application-json。

**近似读音：**对于此示例，近似读音方法是最简单的方法：

IBM Cloud

curl -X PUT -u "apikey:{apikey}" \
--header "Content-Type: application/json" \
--data "{\"translation\":\"I triple E\"}" \
"{url}/v1/customizations/{customization_id}/words/IEEE"

IBM Cloud Pak for Data IBM Software Hub

curl -X PUT \
--header "Authorization: Bearer {token}" \
--header "Content-Type: application/json" \
--data "{\"translation\":\"I triple E\"}" \
"{url}/v1/customizations/{customization_id}/words/IEEE"

国际音标：国际音标要求使用 <phoneme> 元素，其中 alphabet 属性设置为 ipa，ph 属性以国际音标格式定义：

IBM Cloud

curl -X PUT -u "apikey:{apikey}" \
--header "Content-Type: application/json" \
--data "{\"translation\":\"<phoneme alphabet=\\\"ipa\\\" ph=\\\"aɪ.tɹˈɨpəl.ˈi\\\"></phoneme>\"}" \
"{url}/v1/customizations/{customization_id}/words/IEEE"

IBM Cloud Pak for Data IBM Software Hub

curl -X PUT \
--header "Authorization: Bearer {token}" \
--header "Content-Type: application/json" \
--data "{\"translation\":\"<phoneme alphabet=\\\"ipa\\\" ph=\\\"aɪ.tɹˈɨpəl.ˈi\\\"></phoneme>\"}" \
"{url}/v1/customizations/{customization_id}/words/IEEE"

语音 IBM SPR：S PR使用 <phoneme> 元素，其中 alphabet 属性设置为 ibm，ph 属性以SPR格式定义：

IBM Cloud

curl -X PUT -u "apikey:{apikey}" \
--header "Content-Type: application/json" \
--data "{\"translation\":\"<phoneme alphabet=\\\"ibm\\\" ph=\\\"1Y.tr1Ipxl.1i\\\"></phoneme>\"}" \
"{url}/v1/customizations/{customization_id}/words/IEEE"

IBM Cloud Pak for Data IBM Software Hub

curl -X PUT \
--header "Authorization: Bearer {token}" \
--header "Content-Type: application/json" \
--data "{\"translation\":\"<phoneme alphabet=\\\"ibm\\\" ph=\\\"1Y.tr1Ipxl.1i\\\"></phoneme>\"}" \
"{url}/v1/customizations/{customization_id}/words/IEEE"

向定制模型添加多个词

要一次向定制模型添加一个或多个词，请使用 POST /v1/customizations/{customization_id}/words 方法。指定要作为词/转换项对的 JSON 数组添加到定制模型的条目。所需的 Content-Type 报头将输入类型标识为 application-json。

以下示例向定制模型添加了词 NCAA 和 iPhone 的常见近似读音转换项：

IBM Cloud

curl -X POST -u "apikey:{apikey}" \
--header "Content-Type: application/json" \
--data "{\"words\": [{\"word\":\"NCAA\", \"translation\":\"N C double A\"}, {\"word\":\"iPhone\", \"translation\":\"I phone\"}]}" \
"{url}/v1/customizations/{customization_id}/words"

IBM Cloud Pak for Data IBM Software Hub

curl -X POST \
--header "Authorization: Bearer {token}" \
--header "Content-Type: application/json" \
--data "{\"words\": [{\"word\":\"NCAA\", \"translation\":\"N C double A\"}, {\"word\":\"iPhone\", \"translation\":\"I phone\"}]}" \
"{url}/v1/customizations/{customization_id}/words"

在请求主体中发送的 JSON 内容等同于以下内容：

{
  "words": [
    {"word":"NCAA", "translation":"N C double A"},
    {"word":"iPhone", "translation":"I phone"}
  ]
}

如更新定制模型中所述，还可以使用 POST /v1/customizations/{customization_id} 方法向定制模型添加词。以下示例使用此方法来添加与先前示例相同的两个词；但不对模型的元数据进行任何更改。除了 URL 外，这两种方法完全相同。

IBM Cloud

curl -X POST -u "apikey:{apikey}" \
--header "Content-Type: application/json" \
--data "{\"words\": [{\"word\":\"NCAA\", \"translation\":\"N C double A\"}, {\"word\":\"iPhone\", \"translation\":\"I phone\"}]}" \
"{url}/v1/customizations/{customization_id}"

IBM Cloud Pak for Data IBM Software Hub

curl -X POST \
--header "Authorization: Bearer {token}" \
--header "Content-Type: application/json" \
--data "{\"words\": [{\"word\":\"NCAA\", \"translation\":\"N C double A\"}, {\"word\":\"iPhone\", \"translation\":\"I phone\"}]}" \
"{url}/v1/customizations/{customization_id}"

向日语定制模型添加词

在日语定制模型中创建词的条目时，额外注意事项和额外的 part_of_speech 字段适用；有关更多信息，请参阅使用日语条目。指定日语定制条目的词性，如下所示：

对于 PUT /v1/customizations/{customization_id}/words/{word} 方法，传递以下格式的 JSON 对象：
```
{
  "translation": "value",
  "part_of_speech": "value"
}
```

对于 POST /v1/customizations/{customization_id}/words 和 POST customizations/{customization_id} 方法，请传递类似于以下内容的 JSON 对象：

{
  "words": [
    {
      "word": "value",
      "translation": "value",
      "part_of_speech": "value"
    }
    . . .
  ]
}

以下 PUT /v1/customizations/{customization_id}/words/{word} 方法的示例将 URL 编码的双字节字符串转换为 NY 的名词（Mesi ） ニューヨーク （英文为 New York ）。如果未定义此定制转换项，那么字符串将被读成 enu wai。

近似读音：

IBM Cloud

curl -X PUT -u "apikey:{apikey}" \
--header "Content-Type: application/json" \
--data "{\"translation\":\"ニューヨーク\", \"part_of_speech\":\"Mesi\"}" \
"{url}/v1/customizations/{customization_id}/words/%EF%BC%AE%EF%BC%B9"

IBM Cloud Pak for Data IBM Software Hub

curl -X PUT \
--header "Authorization: Bearer {token}" \
--header "Content-Type: application/json" \
--data "{\"translation\":\"ニューヨーク\", \"part_of_speech\":\"Mesi\"}" \
"{url}/v1/customizations/{customization_id}/words/%EF%BC%AE%EF%BC%B9"

音标 IPA：

IBM Cloud

curl -X PUT -u "apikey:{apikey}" \
--header "Content-Type: application/json" \
--data "{\"translation\":\"<phoneme alphabet=\\\"ipa\\\" ph=\\\"ɲɯːjoːkɯ\\\"></phoneme>\", \"part_of_speech\":\"Mesi\"}" \
"{url}/v1/customizations/{customization_id}/words/%EF%BC%AE%EF%BC%B9"

IBM Cloud Pak for Data IBM Software Hub

curl -X PUT \
--header "Authorization: Bearer {token}" \
--header "Content-Type: application/json" \
--data "{\"translation\":\"<phoneme alphabet=\\\"ipa\\\" ph=\\\"ɲɯːjoːkɯ\\\"></phoneme>\", \"part_of_speech\":\"Mesi\"}" \
"{url}/v1/customizations/{customization_id}/words/%EF%BC%AE%EF%BC%B9"

音标 IBM SPR：

IBM Cloud

curl -X PUT -u "apikey:{apikey}" \
--header "Content-Type: application/json" \
--data "{\"translation\":\"<phoneme alphabet=\\\"ibm\\\" ph=\\\"nyu:yo:ku\\\"></phoneme>\", \"part_of_speech\":\"Mesi\"}" \
"{url}/v1/customizations/{customization_id}/words/%EF%BC%AE%EF%BC%B9"

IBM Cloud Pak for Data IBM Software Hub

curl -X PUT \
--header "Authorization: Bearer {token}" \
--header "Content-Type: application/json" \
--data "{\"translation\":\"<phoneme alphabet=\\\"ibm\\\" ph=\\\"nyu:yo:ku\\\"></phoneme>\", \"part_of_speech\":\"Mesi\"}" \
"{url}/v1/customizations/{customization_id}/words/%EF%BC%AE%EF%BC%B9"

查询定制模型中的单个词

要查询定制模型中单个词的转换项，请使用 GET /v1/customizations/{customization_id}/words/{word} 方法。可在此方法的 URL 中指定该词。转换项将按照定制模型（近似读音或音标）中所定义的内容返回。

以下示例可查询定制模型中 IEEE 这个词的转换项：

IBM Cloud

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/customizations/{customization_id}/words/IEEE"

IBM Cloud Pak for Data IBM Software Hub

curl -X GET \
--header "Authorization: Bearer {token}" \
"{url}/v1/customizations/{customization_id}/words/IEEE"

如果该词在模型中有近似读音转换项，那么示例会返回以下 JSON 输出：

{
  "translation": "I triple E"
}

查询定制模型中的所有词

要查看在定制模型中定义的所有词的转换项，请使用 GET /v1/customizations/{customization_id}/words 方法。以下示例使用此方法列出定制模型中的条目，该模型包含三个词的近似读音转换项：

IBM Cloud

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/customizations/{customization_id}/words"

IBM Cloud Pak for Data IBM Software Hub

curl -X GET \
--header "Authorization: Bearer {token}" \
"{url}/v1/customizations/{customization_id}/words"

此方法返回具有以下数据的 JSON 数组。对于日语定制模型，输出会包含各个词的词性。

{
  "words": [
    {
      "word": "IEEE",
      "translation": "I triple E"
    },
    {
      "word": "NCAA",
      "translation": "N C double A"
    },
    {
      "word": "iPhone",
      "translation": "I phone"
    }
  ]
}

如查询定制模型中所述，您还可以使用 GET /v1/customizations/{customization_id} 方法来查看定制模型的元数据和词：

IBM Cloud

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/customizations/{customization_id}"

IBM Cloud Pak for Data IBM Software Hub

curl -X GET \
--header "Authorization: Bearer {token}" \
"{url}/v1/customizations/{customization_id}"

此方法返回以下格式的 JSON 输出。由于此示例和上一个示例指定的定制模型相同，因此两个示例的输出中的词数组完全相同。

{
  "customization_id": "64f4807f-a5f1-5867-924f-7bba1a84fe97",
  "owner": "297cfd08-330a-22ba-93ce-1a73f454dd98",
  "created": "2016-07-15T19:15:17.926Z",
  "name": "Test",
  "language": "en-US",
  "description": "Customization test",
  "last_modified": "2016-07-15T19:46:01.387Z",
  "words": [
    {
      "word": "IEEE",
      "translation": "I triple E"
    },
    {
      "word": "NCAA",
      "translation": "N C double A"
    },
    {
      "word": "iPhone",
      "translation": "I phone"
    }
  ]
}

查询某种语言的词

要查询词的发音，请使用 GET /v1/pronunciation 方法。指定声音以获取该声音在该语言中的发音。缺省情况下，此方法会返回基于服务的常规发音规则的发音，但您还可以请求针对指定定制模型的发音。此方法包括四个查询参数，可用于指定要返回的信息：

必需的 text 参数指定要返回其发音的词。
可选的 voice 参数允许指定发音所用的语言。您可以指定其中一个声音（例如，en-US_LisaV3Voice）以指示所需的语言；同一语言（例如，en-US）的所有声音都会返回相同的发音。默认情况下，会返回默认语音语言的发音。有关更多信息，请参阅使用默认语音。
可选的 format 参数允许指定发音的音标格式：ipa 或 ibm。缺省情况下，发音以 IPA 格式返回。
可选的 customization_id 参数允许指定要为其返回发音的定制模型。如果未在指定的定制模型中定义该词，那么服务将返回模型所用语言的缺省发音。省略该参数可查看未进行任何定制的指定声音的转换项。不要同时指定声音和定制模型。

此方法非常有用，因为它允许您查询任何语言的词，并且此方法无需定制标识，因此对您可以查看的词没有限制。在编写新词的音标转换项时，此方法会特别有用；您可以将其用于获取现有词的发音，然后将其用作新转换项的基础，这比从头开始创建转换项要方便得多。

以下示例以默认的IPA格式获取单词 IEEE 的读音：

IBM Cloud

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/pronunciation?text=IEEE"

IBM Cloud Pak for Data IBM Software Hub

curl -X GET \
--header "Authorization: Bearer {token}" \
"{url}/v1/pronunciation?text=IEEE"

答复显示了发音的 IPA 符号：

{
  "pronunciation": ".ˈaɪ .ˈi .ˈi .ˈi"
}

以下示例将输入词 IEEE 的近似读音转换项，并获取 IBM SPR 格式的音标等效项。获取近似读音转换项的音标发音是一种特别有趣的编写音标转换项的方法。在以下示例中，对词的空格进行了 URL 编码。

IBM Cloud

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/pronunciation?text=i%20triple%20e&format=ibm"

IBM Cloud Pak for Data IBM Software Hub

curl -X GET \
--header "Authorization: Bearer {token}" \
"{url}/v1/pronunciation?text=i%20triple%20e&format=ibm"

答案中显示了 SPR 的发音符号：

{
  "pronunciation": "1Y.tr1Ipxl.1i"
}

从定制模型中删除词

要从定制模型中删除词，请使用 DELETE /v1/customizations/{customization_id}/words/{word} 方法。可在此方法的 URL 中指定要删除的词。只能删除单个词；不能使用一个方法来删除多个词。

以下示例将从指定的定制模型中删除词 IEEE：

IBM Cloud

curl -X DELETE -u "apikey:{apikey}" \
"{url}/v1/customizations/{customization_id}/words/IEEE"

IBM Cloud Pak for Data IBM Software Hub

curl -X DELETE \
--header "Authorization: Bearer {token}" \
"{url}/v1/customizations/{customization_id}/words/IEEE"