Managing speaker models

Listing all speaker models

To list all of the speaker models that are defined for a service instance, use the GET /v1/speakers method. The method returns a speakers array that provides the following information for each speaker model:

• speaker_id indicates the speaker model's Globally Unique Identifier (GUID). The GUID is used to identify the speaker in calls to the service.
• name is the user-specified name that was assigned to the speaker model when it was created.

The array is empty if no speaker models are defined for the service instance.

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

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

{
  "speakers": [
    {
      "speaker_id": "56367f89-546d-4b37-891e-4eb0c13cc833",
      "name": "speaker_one"
    },
    {
      "speaker_id": "323e4476-63de-9825-7cd7-8120e45f8331",
      "name": "speaker_two"
    }
  ]
}

Listing the custom prompts for a speaker model

To list all of the custom prompts that are associated with a speaker model, use the GET /v1/speakers/{speaker_id} method. Pass the GUID of the desired speaker model for the indicated path parameter.

The method returns a customizations array that lists all of the custom prompts for the speaker model organized by customization_id. For each customization ID, the method returns the following information:

• prompt is the user-specified text of the prompt.
• prompt_id is the user-specified identifier of the prompt. The ID is used to identify the prompt in calls to the service.
• status is the current status of the prompt:
  • processing indicates that the service received the request to add the prompt and is processing the prompt.
  • available indicates that the service successfully validated the prompt, which is now ready for use in a speech synthesis request.
  • failed indicates that the service's validation of the prompt failed. The status of the prompt includes an error field that describes the reason for the failure.

The customizations array is empty if the speaker model is not associated with any custom prompts.

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/speakers/{speaker_id}"

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

{
  "customizations": [
    {
      "customization_id": "9937efc0-5341-b436-77e1-9923f6e693a1",
      "prompts": [
        {
          "prompt": "Hello and welcome!",
          "prompt_id": "greeting",
          "status": "available"
        },
        {
          "prompt": "How can I help you today?",
          "prompt_id": "help",
          "status": "processing"
        }
      ]
    },
    {
      "customization_id": "82f4809a-bf63-89a6-52ca-22731fe467ba",
      "prompts": [
        {
          "prompt": "Thank you and good-bye!",
          "prompt_id": "goodbye",
          "status": "available"
        },
        {
          "prompt": "I do not understand that response.",
          "prompt_id": "do_not_understand",
          "status": "available"
        }
      ]
    }
  ]
}

Deleting a speaker model

To delete a speaker model, use the DELETE /v1/speakers/{speaker_id} method. Deleting a speaker model does not affect any prompts that are associated with the deleted speaker. The prosodic data that defines the quality of a prompt is established when the prompt is created. A prompt is static and remains unaffected by deletion of its associated speaker. However, the prompt cannot be resubmitted or updated with its original speaker once that speaker is deleted.

curl -X DELETE -u "apikey:{apikey}" \
"{url}/v1/speakers/{speaker_id}"

curl -X DELETE \
--header "Authorization: Bearer {token}" \
"{url}/v1/speakers/{speaker_id}"