--- updatedAt: 2025-05-28T00:13:21.000Z agentTools: projectIndex: https://docs.wellsaidlabs.com/llms.txt --- # Using Replacement Libraries The WellSaid Replacements endpoints allow you to create [Replacement Libraries](https://docs.wellsaidlabs.com/reference/post_replacement-libraries) and then [Create Replacements](https://docs.wellsaidlabs.com/reference/post_replacement-libraries-library-id-replacements) and store those in your library. You can bulk upload your list of replacements using CSV or JSON and then [get a list](https://docs.wellsaidlabs.com/reference/get_replacement-libraries-library-id-replacements) of all your replacements in a given library. Replacements can be stored as [Respellings](https://docs.wellsaidlabs.com/reference/respellings) which provide our models with precise pronunciation instructions and you can query for optimal pronunciations using our [Respelling Suggestions](https://docs.wellsaidlabs.com/reference/get_respelling-suggestions) call. ## How do you use the endpoint? ### **[Create a Replacement Library](https://docs.wellsaidlabs.com/reference/post_replacement-libraries)** 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: ```bash curl --location 'https://api.wellsaidlabs.com/v1/tts/replacement_libraries' \ --header 'X-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: ```json { "library_id": "YOUR_LIBRARY_ID" } ``` **[Get Lists of Libraries](https://docs.wellsaidlabs.com/reference/get_replacement-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: ```bash curl --request GET \ --url \ --header 'X-API-KEY: ' \ ``` **Response** Below is an example of a successful response showing one avatar with the following structure:\{ ```json { "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](https://docs.wellsaidlabs.com/reference/post_replacement-libraries-library-id-replacements)** 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](https://help.wellsaidlabs.com/respellings) 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_id`of the Library you want to add your replacement(s) to : `https://api.wellsaidlabs.com/v1/tts/post_clips` An example `curl` command: ```bash curl --request POST \ --url https://api.wellsaidlabs.com/v1/tts/replacement_libraries/c1b7c009-904d-48c2-a2d6-4249863cb995/replacements \ --header 'X-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: ```json { "replacement_id": "YOUR_REPLACEMENT_ID" } ``` **[Get Lists of Replacements](https://docs.wellsaidlabs.com/reference/get_replacement-libraries-library-id-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: ```bash curl --request GET \ --url \ --header 'X-API-KEY: ' \ ``` **Response** Below is an example of a successful response showing one avatar with the following structure:\{ ```json { "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](https://docs.wellsaidlabs.com/reference/respellings) which provide our models with precise pronunciation instructions and you can query for optimal pronunciations using our [Respelling Suggestions](https://docs.wellsaidlabs.com/reference/get_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: ```bash curl --request POST \ --url https://api.wellsaidlabs.com/v1/tts/stream \ --header 'X-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.