ElevenLabs API Wrapper
Wrapper for the ElevenLabs API
Check out the npm page!
Requirements
How to use
- Create a new project
- Use
npm install @arellak/elevenlabs-wrapper
to install the package
// import ElevenLabs Wrapper
import ElevenLabs from "@arellak/elevenlabs-wrapper";
// Create a new instance of ElevenLabs
const elevenLabs = new ElevenLabs(
{
apiKey: "YOUR_API_KEY",
outputFolder: "./output"
}
);
Constructor Options
Option |
Type |
Description |
default |
notes |
apiKey |
string |
Your ElevenLabs API Key |
undefined |
- |
outputFolder |
string |
folder where files will be saved |
./output |
created automatically if it doesn't exist |
Methods
// Converts text to speech, saves the file to the output folder and returns the relative path to the file.
// Output file is in the following format: TTS_date-time.mp3
// Returns an object with the following structure: { code: CODE, message: "STATUS_MESSAGE" }
await elevenLabs.tts(
text,
voiceId,
optionalPath = "",
modelId = "eleven_multilingual_v2",
voiceSettings = {
stability: 0.5,
similarity_boost: 0.75
},
params = {
output_format: "mp3_44100_128",
optimize_streaming_latency: 0
}
);
Option |
Type |
Description |
default |
notes |
text |
string |
text to be converted to speech |
undefined |
- |
voiceId |
string |
voice id to be used |
undefined |
- |
optionalPath |
string |
optional path to save the file to |
"" |
- |
modelId |
string |
model id to be used |
eleven_multilingual_v2 |
[eleven_monolingual_v1, eleven_multilingual_v2] |
voiceSettings |
object |
voice settings |
{stability: 0.5, similarity_boost: 0.75} |
{stability, similarity_boost, style, use_speaker_boost} |
params |
object |
additional params |
{output_format: "mp3_44100_128", optimize_streaming_latency: 0} |
- |
### Streaming Latencies
0 (default) = No optimization.
1 = Some optimization.
2 = More optimization.
3 = Max optimization.
4 = Max optimizations & text normalizer off.
// Returns the remaining letters you have left for the month
await elevenLabs.getRemainingLetters();
// Returns all the available models
await elevenLabs.getModels();
// Returns all the available voices
await elevenLabs.getVoices();
// Returns all the voices you created yourself
await elevenLabs.getCustomVoices();
// Returns the IDs and names of the voices you created yourself
// Example: { name:"My Voice", id:"123456789" }
await elevenLabs.getCustomVoiceIds();
// Returns default settings for voices
await elevenLabs.getDefaultVoiceSettings();
// Returns settings for a specific voice
await elevenLabs.getVoiceSettings(voiceId);
// Returns a given voice
await eleveawait nLabs.getVoice(voiceId);
// Returns the sample names and IDs for a given voice
// Example: { name:"My Sample", sampleId:"123456789" }
await elevenLabs.getSampleIds(voiceId);
// Downloads audio for a given sample from a given voice
// Saves it to the output folder specified in the constructor and returns the relative path to the file.
// Output file is in the following format: SAMPLE_date-time.mp3
// Optional Path is the same as in the tts method.
// Returns an object with the following structure: { code: CODE, message: "STATUS_MESSAGE" }
await elevenLabs.getAudioFromSample(voiceId, sampleId, optionalPath = "");
// Returns the history for the given Account
await elevenLabs.getHistory();
// Returns the data for the given historyItemId
await elevenLabs.getHistoryItem(historyItemId);
// Downloads the audio for the given historyItemId
// Saves it to the output folder specified in the constructor and returns the relative path to the file.
// Output file is in the following format: HISTORY_date-time.mp3
// Optional Path is the same as in the tts method.
// Returns an object with the following structure: { code: CODE, message: "STATUS_MESSAGE" }
await elevenLabs.getAudioFromHistoryItem(historyItemId, optionalPath = "");
// Download an array of history items
// Saves them to the output folder specified in the constructor and returns an array of relative paths to the files.
// Optional Path is the same as in the tts method.
// Output files are in the following format: HISTORY_date-time.zip
await elevenLabs.downloadHistoryItems(historyItemIds, optionalPath = "");
// Returns information about the user's account
await elevenLabs.getUserInfo();
// Returns the user's subscription information
await elevenLabs.getUserSubscriptionInfo();
await elevenLabs.getProjects();
await elevenLabs.getProjectById("ID");
// Additional parameters:
// acxVolumeNormalization = false, author = "", fromDocument = "", fromUrl = "", isbnNumber = "", qualityPreset = "standard", title = ""
await elevenLabs.addProject("DEFAULT_MODEL_ID", "DEFAULT_PARAGRAPH_VOICE_ID", "DEFAULT_TITLE_VOICE_ID", "NAME", "PRONOUNCIATION_DICTIONARY_LOCATORS");
await elevenLabs.deleteProject("PROJECT_ID");
await elevenLabs.convertProject("PROJECT_ID");
await elevenLabs.getProjectSnapshots("PROJECT_ID");
await elevenLabs.streamProjectAudio("PROJECT_ID", "PROJECT_SNAPSHOT_ID");
await elevenLabs.getChapters("PROJECT_ID");
await elevenLabs.getChapterById("PROJECT_ID", "CHAPTER_ID");
await elevenLabs.deleteChapter("PROJECT_ID", "CHAPTER_ID");
await elevenLabs.convertChapter("PROJECT_ID", "CHAPTER_ID");
await elevenLabs.getChapterSnapshots("PROJECT_ID", "CHAPTER_ID");
await elevenLabs.streamChapterAudio("PROJECT_ID", "CHAPTER_ID", "CHAPTER_SNAPSHOT_ID");
// Edit voice settings for a given voice
await elevenLabs.editVoiceSettings(voiceId, voiceSettings);
Option |
Type |
Description |
default |
notes |
voiceId |
string |
voice id to be used |
undefined |
- |
voiceSettings |
object |
voice settings |
{stability: 0.5, similarity_boost: 0.75} |
{stability, similarity_boost, style, use_speaker_boost} |
// Add a new voice with the given name, description, file paths and labels
// Returns the voice id
await elevenLabs.addVoice(name, filePaths, optionalSettings);
Option |
Type |
Description |
default |
notes |
required |
name |
string |
name of the voice |
undefined |
- |
yes |
filePaths |
array |
array of file paths |
undefined |
- |
yes |
optionalSettings |
object |
optional settings |
{} |
{description, labels} |
no |
// Usage example
const newVoiceId = await elevenLabs.addVoice(
"TEST NAME",
[
"./output/test3.mp3",
],
{
labels: {
age: "early 20s"
},
description: "test description",
},
);
// Edit the voice with a given name and voice id
// include the optional settings you want to change
// returns status code if it was successful
await elevenLabs.editVoice(name, voiceId, optionalSettings);
Option |
Type |
Description |
default |
notes |
required |
name |
string |
name of the voice |
undefined |
- |
yes |
voiceId |
string |
voice id to be used |
undefined |
- |
yes |
optionalSettings |
object |
optional settings |
{} |
{description, file paths, labels} |
no |
// Usage example
const editedVoice = await elevenLabs.editVoice(
"TEST NAME",
"YOUR_VOICE_ID",
{
filePaths: [
"./output/test3.mp3",
],
labels: {
age: "early 20s",
},
},
);
// Deletes a voice
await elevenLabs.deleteVoice(voiceId);
Option |
Type |
Description |
default |
notes |
voiceId |
string |
voice id to be used |
undefined |
- |
// Deletes a sample with a given voice id and sample id
await elevenLabs.deleteSample(voiceId, sampleId);
Option |
Type |
Description |
default |
notes |
voiceId |
string |
voice id to be used |
undefined |
- |
sampleId |
string |
sample id to be used |
undefined |
- |
// Deletes a history item with a given history item id
await elevenLabs.deleteHistoryItem(historyItemId);
Option |
Type |
Description |
default |
notes |
historyItemId |
string |
history item id to be used |
undefined |
- |
Need help?
Discord: @arellak
E-Mail: nimble0@protonmail.com
FAQ
How do I get an API Key?
- Register an Account at ElevenLabs.
- Click on the image on the top right.
- Click on "Profile"
- Show the API Key and copy it
How do I get a voice id?
After registering an account and having a paid subscription, you can create your own custom voice on the website.
If you don't want to use a custom voice, you can use the default voices. You can find the IDs for the default voices by using the ElevenLabs.getVoices()
method.
If you want to use a custom voice, you can use the ElevenLabs.getCustomVoiceIds()
method to get the IDs for your custom voices.
Something doesn't work. What should I do?
- Check if you have the latest version of the package installed.
- Did you follow all the steps at the beginning of this Readme?
- Did you enter your API Key correctly?
- Did you enter the correct voice ID?
If you did all the above and you are sure it's a problem with the package, please contact me on Discord, via E-Mail or create an issue.
If you think it's a problem with ElevenLabs, please contact them directly since I'm not affiliated with them.
License
MIT
Credits
ElevenLabs for the API