So you wanna make custom voices, huh? Well you've come to the right place.
If any of the documentation is out of place or issues occur, please submit a PR or create an issue. I downgraded the repo from JDK 17 to JDK 11 as well.
Maven
To add elevenlabs-api
to your Maven project, use:
<dependency>
<groupId>net.andrewcpu.elevenlabs</groupId>
<artifactId>elevenlabs-api</artifactId>
<version>2.0-SNAPSHOT</version>
</dependency>
The most up-to date package information can be found on the Packages tab
JAR
Compiled JARs are available via the Releases tab
To access your ElevenLabs API key, head to the official website, you can view your xi-api-key
using the 'Profile' tab on the website.
To set up your ElevenLabs API key, you must register it with the ElevenLabsAPI Java API like below:
ElevenLabs.setApiKey("YOUR_API_KEY_HERE");
For any public repository security, you should store your API key in an environment variable, or external from your source code.
ElevenLabs Website: https://elevenlabs.io
ElevenLabs API Documentation: https://api.elevenlabs.io/docs
To retrieve your list of accessible Voices, you can statically utilize Voice#getVoices()
. This will return both ElevenLab's pregenerated Voice
models, as well as any personal Voices
you have generated.
List<Voice> voices = Voice.getVoices();
ElevenLabs provides a default VoiceSettings
configuration which can be accessed statically from VoiceSettings#getDefaultVoiceSettings()
This is a network request.
VoiceSettings.getDefaultVoiceSettings();
Retrieving voices via their voiceId
can be done in a few different ways.
The first retrieves a Voice
by voiceId
and by default includes the settings.
Voice.get(String voiceId);
If you don't wish to retrieve the Voice
model with its default settings included, you can use the Voice#get(String voiceId, boolean withSettings)
function. By specifying false
for withSettings
, you will receive a voice object without its default VoiceSettings
. (They can be loaded later with Voice#fetchSettings()
, or not at all by providing a VoiceSettings
object when generating TTS)
Voice.get(String voiceId, boolean withSettings);
To delete a Voice
, you can utilize the Voice#delete()
function. This will delete a voice from the ElevenLabs API.
Voice voice;
voice.delete();
There may be times when the default VoiceSettings
parameters are changed externally from the API (Via the main website or another integrated system), to retrieve and apply the most up to date VoiceSettings
object to a Voice
, you can use the Voice#fetchSettings()
function. (This is a network request, and it updates the object you're acting upon)
Voice voice;
voice.fetchSettings(); // requests updated settings from ElevenLabs
A VoiceSettings
object can be modified and updated in a Voice
.
The Voice#updateVoiceSettings(VoiceSettings settings)
function updates the default voice parameters to use when generating speech. (This is a network request, and updates the object you're acting upon.)
Voice voice;
voice.updateVoiceSettings(VoiceSettings settings);
To edit an existing Voice
model, you can load the Voice
into a VoiceBuilder
with the VoiceBuilder#fromVoice(Voice voice)
function.
The fromVoice(Voice voice)
function will add all the current values stored in a Voice
object directly into the VoiceBuilder
. (Meaning you do not have to redefine existing settings)
You'll also see that the Creating a Voice section utilizes this same VoiceBuilder
class, except it uses the VoiceBuilder#create()
function, instead of the VoiceBuilder#edit()
function.
When editing a voice, you must use VoiceBuilder.edit()
Voice voice;
VoiceBuilder builder = VoiceBuilder.fromVoice(voice); // load the existing voice into the builder
builder.withLabel("key", "value"); // add a new label
builder.removeLabel("oldKey");
builder.withFile(new File("someAudioFile.mp3")); // add a new audio sample
voice = builder.edit(); // edit voice & return updated voice object
To generate a new Voice
model from the API, you can use the VoiceBuilder
class to assemble the required parameters for a Voice
model.
Some things to remember:
- All
Voice
objects must have a name. (There can only be ONE name for aVoice
) - At least 1 file (
Voice
Sample) must be provided withVoiceBuilder#withFile()
- Labels are not required, but are helpful. As many labels as you like may be applied to a
Voice
.
Voice voice;
VoiceBuilder builder = new VoiceBuilder();
builder.withName("Voice name");
builder.withFile(new File("sample1.mp3"));
builder.withFile(new File("sample2.mp3"));
builder.withLabel("accent", "American");
voice = builder.create();
To generate an audio file with a given Voice
, you can utilize the Voice#generate(...)
functions.
Depending on how you access your Voice
, (with or without settings), will decide whether you can use the implicit voiceSettings
or if you have to specify the VoiceSettings
object to use. Unless explicitly requesting the Voice
without settings, every Voice
object SHOULD contain its default VoiceSettings
.
Voice voice;
File file = voice.generate(String text);
File file = voice.generate(String text, VoiceSettings settings);
File file = voice.generate(String text, String model, VoiceSettings settings);
File file = voice.generate(String text, String model);
InputStream inputStream = voice.generateStream(String text);
InputStream inputStream = voice.generateStream(String text, VoiceSettings settings);
InputStream inputStream = voice.generateStream(String text, String model, VoiceSettings settings);
InputStream inputStream = voice.generateStream(String text, String model);
A Sample
is used as the training data for a given Voice
model.
To access the sample(s) for a given Voice
, you can utilize Voice#getSamples()
.
Voice voice;
List<Sample> samples = voice.getSamples();
You can download a Sample
via the Sample#downloadAudio(File outputFile)
function.
The File
parameter of downloadAudio()
is the location of where you want to locally download the sample.
Voice voice;
File file = voice.getSamples().get(0).downloadAudio();
Deleting a Sample
is easy. This action makes a network request.
Sample sample;
sample.delete();
Your ElevenLabs History
is a collection of all of your previous TTS generations.
To get your ElevenLabs generation History
, you can utilize History#get()
. (You can also retrieve your History
from a User
object, with User#getHistory()
)
History history = History.get();
To retrieve a HistoryItem
from your History
, you can use History#getHistoryItem(String itemId)
.
History history;
HistoryItem item = history.getHistoryItem("itemId");
The official API of ElevenLabs provides an endpoint for downloading multiple HistoryItem
's as a ZIP file. To download such items, you can pass a String[]
containing the HistoryItem
IDs, OR you can provide a List<HistoryItem>
parameter.
History history;
File download = history.downloadHistory(new String[]{"item-id1", "item-id2"});
File download = history.downloadHistory(List<HistoryItem> historyItems);
You can utilize the HistoryItem#delete()
function to delete a HistoryItem
from ElevenLabs.
HistoryItem item;
item.delete();
By default, a HistoryItem
contains the voiceId
of the Voice
used to generate it. The getVoice()
function will send a request to the ElevenLabs API to retrieve the voice object. (See also Voice.get()
and Voice.getVoices()
)
HistoryItem item;
Voice voice = item.getVoice();
A HistoryItem
is a previous TTS generation. You can download the generation as an MP3 file by executing the downloadAudio()
function. The return value is the tmp File
location of your download.
HistoryItem item;
File file = item.downloadAudio();
A Subscription
contains all the relevant data to manage your API usage (character usage, next billing cycle, etc.)
Subscription subscription = Subscription.get();
This endpoint will return the User
associated with a given API key.
User user = User.get();
This error indicates a malformed request to the ElevenLabs API. The exception should provide the location of any syntactically incorrect parameters within the request.
As specified on the official ElevenLabs API Documentation, their API is experimental and all endpoints are subject to change. Depending on how they modify their API, may break this library. Should you notice any API changes / library errors, feel free to submit an issue or a PR.
If you like what you see, give it a star! :)
Unit tests have been created, these endpoints are destructive and not included in the testing:
- deleteHistoryItem - WONT TEST
- deleteSample - WONT TEST
- deleteVoice - WONT TEST
- editVoiceSettings - WONT TEST
- createVoice - WONT TEST
- editVoice - WONT TEST
To run the unit tests yourself, you have to clone this repo and update the ElevenLabsTest.java file with your API key and your voice to test on.
Thanks to ElevenLabs for making an awesome tool 🥂