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.

• Getting Started

  • Installation
  • Setting up your API Key

• Voices

  • Accessing your List of Available Voices
  • Accessing the Default Voice Settings
  • Getting a Voice by ID
  • Deleting a voice
  • Retrieving an Updated VoiceSettings for a Voice
  • Updating the VoiceSettings for a Voice
  • Editing a Voice
  • Creating a Voice
  • Generating Audio

• Samples

  • Accessing Voice Samples
  • Downloading a Sample
  • Deleting a Sample

• History

  • Getting Generation History
  • Getting a History Item
  • Downloading History
  • Deleting a HistoryItem
  • Requesting the Voice for a HistoryItem
  • Downloading a HistoryItem Audio

• User Management

  • Getting your Subscription
  • Getting your User

• Exceptions

  • ElevenLabsAPINotInitiatedException
  • ElevenLabsValidationException

• Misc

• Links to ElevenLabs

  • 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 a Voice)
• At least 1 file (Voice Sample) must be provided with VoiceBuilder#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 🥂