Managing custom prompts

The Tune by Example feature is beta functionality that is supported only for US English custom models and voices.

Tune by Example includes methods for listing all custom prompts for a custom model, for getting information about an individual prompt, and for deleting a prompt. These methods are in addition to the POST /v1/customizations/{customization_id}/prompts/{prompt_id} method for adding a prompt to a custom model; for more information, see Add a custom prompt.

Listing custom prompts

Tune be Example provides two methods for listing information about the custom prompts for a specified custom model:

The GET /v1/customizations/{customization_id}/prompts method lists information about all custom prompts that are defined for a custom model.
The GET /v1/customizations/{customization_id}/prompts/{prompt_id} method lists information about a specific custom prompt from a custom model. Use this method to poll the service about the status of a request to add a prompt to a custom model.

The first method returns a prompts array that lists all of the prompts for a custom model. For each prompt that is listed in the array, the service provides the same information as it does for an individual prompt:

prompt is the user-specified text of the prompt that was provided when the prompt was created.
prompt_id is the user-specified identifier of the prompt that was provided at the prompt's creation. The prompt ID is used to identify the prompt in requests to the service, including in the SSML of speech synthesis requests.
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. This is the initial status of all prompts.
- available indicates that the service successfully validated the prompt. The prompt 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.
speaker_id is the GUID of the speaker model that is associated with the prompt. The service omits the field if no speaker ID is associated with the prompt.

When listing all prompts for a custom model, the prompts array is empty if the model contains no prompts.

List all custom prompts example

The following example lists all custom prompts that are included in the custom model that has the specified customization ID:

IBM Cloud

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

IBM Cloud Pak for Data

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

The model contains three custom prompts. The first two prompts are associated with the same speaker; the first is available and ready to use, and the service is still processing the second. The third prompt, which is available, is associated with a different speaker.

{
  "prompts": [
    {
      "prompt": "Hello and welcome!",
      "prompt_id": "greeting",
      "status": "available",
      "speaker_id": "56367f89-546d-4b37-891e-4eb0c13cc833"
    },
    {
      "prompt": "How can I help you today?",
      "prompt_id": "help",
      "status": "processing",
      "speaker_id": "56367f89-546d-4b37-891e-4eb0c13cc833"
    },
    {
      "prompt": "I am sorry to hear that.",
      "prompt_id": "sorry",
      "status": "available",
      "speaker_id": "323e4476-63de-9825-7cd7-8120e45f8331"
    }
  ]
}

List a specific custom prompt example

The following example returns information about just the first custom prompt from the previous listing:

IBM Cloud

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

IBM Cloud Pak for Data

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

The response duplicates the information from the previous example:

{
  "prompt": "Hello and welcome!",
  "prompt_id": "greeting",
  "status": "available",
  "speaker_id": "56367f89-546d-4b37-891e-4eb0c13cc833"
}

Deleting a custom prompt

To delete a custom prompt from a custom model, use the DELETE /v1/customizations/{customization_id}/prompts/{prompt_id} method. Using a nonexistent or deleted custom prompt in a speech synthesis request causes the service to return a 400 response code. Make sure that you do not attempt to use a deleted prompt in production.

Delete a custom prompt example

The following example deletes the specified custom prompt from the custom model that has specified customization ID:

IBM Cloud

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

IBM Cloud Pak for Data

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