Using Replacement Libraries

The WellSaid Replacements endpoints allow you to create Replacement Libraries and then Create Replacements and store those in your library. You can bulk upload your list of replacements using CSV or JSON and then get a list of all your replacements in a given library.

Replacements can be stored as Respellings which provide our models with precise pronunciation instructions and you can query for optimal pronunciations using our Respelling Suggestions call.

How do you use the endpoint?

Create a Replacement Library

Replacement Libraries allow you to store a list of replacements that can then be passed as a variable to our TTS models. When this variable is found, we will analyze the text for any replacements and do a find and replace with what is in the library, formatting it correctly for the destination model.

To create a Replacement Library Make a POST request to this URL, including your API key in the header:

https://api.wellsaidlabs.com/v1/tts/replacement_libraries/{library_id}/replacements

An example curl command:

curl --location 'https://api.wellsaidlabs.com/v1/tts/replacement_libraries' \
--header 'X-API-KEY: <YOUR_API_KEY>'
--header 'accept: */*' \
--header 'content-type: application/json' \
--data '
{
  "name": "My first Library"
}

Response

Below is an example of a successful response showing one avatar with the following structure:

{
"library_id": "YOUR_LIBRARY_ID"
}

Get Lists of Libraries

Make a GET request to this URL, including your API key in the header:

https://api.wellsaidlabs.com/v1/tts/replacement_libraries

An example curl command:

curl --request GET \
     --url <https://api.wellsaidlabs.com/v1/tts/replacement_libraries> \
     --header 'X-API-KEY: <YOUR_API_KEY>' \

Response

Below is an example of a successful response showing one avatar with the following structure:{

{
  "count": 1,
  "libraries": [
    {
      "library_id": "YOUR_LIBRARY_ID",
      "name": "My first Library"
    }
  ]
}

Details of response

Field	type	notes
count	integer	Total count of libraries created for your account
libraries	array	An array of all libraries you have created
library_id	string	The ID for a library
name	string	The name of the library

Add Replacement To Library

Replacements allow you to specify any word and provide an alternative pronunciation of that word. This replacement text can either be a phonetic_respelling which must by formatted using WellSaid's Respelling System to be accepted as a replacement. Alternatively you can provide your own suggestion to the model where you would set the phonetic_respelling value to FALSE.

To create a Replacement Make a POST request to this URL, including your API key in the header and the library_idof the Library you want to add your replacement(s) to :

https://api.wellsaidlabs.com/v1/tts/post_clips

An example curl command:

curl --request POST \
     --url https://api.wellsaidlabs.com/v1/tts/replacement_libraries/c1b7c009-904d-48c2-a2d6-4249863cb995/replacements \
     --header 'X-API-KEY: <YOUR_API_KEY>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "original": "pizza",
  "replacement_text": "PEET-suh",
  "is_phonetic_respelling": true,
  "enabled": true
}
'

Response

Below is an example of a successful response showing one avatar with the following structure:

{
"replacement_id": "YOUR_REPLACEMENT_ID"
}

Get Lists of Replacements

Make a GET request to this URL, including your API key in the header:

https://api.wellsaidlabs.com/v1/tts/replacement_libraries/{library_id}/replacements

An example curl command:

curl --request GET \
     --url <https://api.wellsaidlabs.com/v1/tts/replacement_libraries/{library_id}/replacements> \
     --header 'X-API-KEY: <YOUR_API_KEY>' \

Response

Below is an example of a successful response showing one avatar with the following structure:{

{
  "count": 1,
  "library_id": "YOUR_LIBRARY_ID",
  "replacements": [
    {
      "enabled": true,
      "is_phonetic_respelling": true,
      "library_id": "YOUR_LIBRARY_ID",
      "original": "pizza",
      "replacement_id": "YOUR_REPLACEMENT_ID",
      "replacement_text": "PEET-suh"
    }
  ]
}

Details of response

Field	type	notes
count	integer	Total count of libraries created for your account
library_id	string	The ID for a library
replacements	array	Array that contains all replacements in this library
enabled	boolean	The ability to turn on an off a replacement when passing a library to a TTS endpoint
is_phonetic_respelling	boolean	Replacements can be stored as Respellings which provide our models with precise pronunciation instructions and you can query for optimal pronunciations using our Respelling Suggestions call
original	string	The original word you want to add the replacement for
replacement_id	string	The ID for the replacement
replacement_text	string	the replacement text you want used when this replacement is enabled, this text is what WellSaid will send to the model.

How to use a Library with TTS?

Now when you make a request to any of our TTS endpoints, you can include the library_ids value and we will adjust the provided text with any replacements we find in the libraries you provide.

An example curl command:

curl --request POST \
     --url https://api.wellsaidlabs.com/v1/tts/stream \
     --header 'X-API-KEY: <YOUR_API_KEY>' \
     --header 'accept: */*' \
     --header 'content-type: application/json' \
     --data '
{
  "speaker_id": 7,
  "text": "I love pizza",
  "library_ids":"YOUR_LIBRARY_ID"
}
'

WellSaid handles the find and replace and formatting aspects for all your replacements before we send the final text to the models.