ElevenLabs-DotNet
3.4.1
dotnet add package ElevenLabs-DotNet --version 3.4.1
NuGet\Install-Package ElevenLabs-DotNet -Version 3.4.1
<PackageReference Include="ElevenLabs-DotNet" Version="3.4.1" />
paket add ElevenLabs-DotNet --version 3.4.1
#r "nuget: ElevenLabs-DotNet, 3.4.1"
// Install ElevenLabs-DotNet as a Cake Addin #addin nuget:?package=ElevenLabs-DotNet&version=3.4.1 // Install ElevenLabs-DotNet as a Cake Tool #tool nuget:?package=ElevenLabs-DotNet&version=3.4.1
ElevenLabs-DotNet
A non-official Eleven Labs voice synthesis RESTful client.
I am not affiliated with ElevenLabs and an account with api access is required.
All copyrights, trademarks, logos, and assets are the property of their respective owners.
Requirements
- This library targets .NET 8.0 and above.
- It should work across console apps, winforms, wpf, asp.net, etc.
- It should also work across Windows, Linux, and Mac.
Getting started
Install from NuGet
Install package ElevenLabs-DotNet
from Nuget. Here's how via command line:
Install-Package ElevenLabs-DotNet
dotnet add package ElevenLabs-DotNet
Looking to use ElevenLabs in the Unity Game Engine? Check out our unity package on OpenUPM:
Documentation
Table of Contents
Authentication
There are 3 ways to provide your API keys, in order of precedence:
- Pass keys directly with constructor
- Load key from configuration file
- Use System Environment Variables
Pass keys directly with constructor
var api = new ElevenLabsClient("yourApiKey");
Or create a ElevenLabsAuthentication
object manually
var api = new ElevenLabsClient(new ElevenLabsAuthentication("yourApiKey"));
Load key from configuration file
Attempts to load api keys from a configuration file, by default .elevenlabs
in the current directory, optionally traversing up the directory tree or in the user's home directory.
To create a configuration file, create a new text file named .elevenlabs
and containing the line:
Json format
{
"apiKey": "yourApiKey",
}
You can also load the file directly with known path by calling a static method in Authentication:
var api = new ElevenLabsClient(ElevenLabsAuthentication.LoadFromDirectory("your/path/to/.elevenlabs"));;
Use System Environment Variables
Use your system's environment variables specify an api key to use.
- Use
ELEVEN_LABS_API_KEY
for your api key.
var api = new ElevenLabsClient(ElevenLabsAuthentication.LoadFromEnv());
API Proxy
Using either the ElevenLabs-DotNet or com.rest.elevenlabs packages directly in your front-end app may expose your API keys and other sensitive information. To mitigate this risk, it is recommended to set up an intermediate API that makes requests to ElevenLabs on behalf of your front-end app. This library can be utilized for both front-end and intermediary host configurations, ensuring secure communication with the ElevenLabs API.
Front End Example
In the front end example, you will need to securely authenticate your users using your preferred OAuth provider. Once the user is authenticated, exchange your custom auth token with your API key on the backend.
Follow these steps:
- Setup a new project using either the ElevenLabs-DotNet or com.rest.elevenlabs packages.
- Authenticate users with your OAuth provider.
- After successful authentication, create a new
ElevenLabsAuthentication
object and pass in the custom token. - Create a new
ElevenLabsClientSettings
object and specify the domain where your intermediate API is located. - Pass your new
auth
andsettings
objects to theElevenLabsClient
constructor when you create the client instance.
Here's an example of how to set up the front end:
var authToken = await LoginAsync();
var auth = new ElevenLabsAuthentication(authToken);
var settings = new ElevenLabsClientSettings(domain: "api.your-custom-domain.com");
var api = new ElevenLabsClient(auth, settings);
This setup allows your front end application to securely communicate with your backend that will be using the ElevenLabs-DotNet-Proxy, which then forwards requests to the ElevenLabs API. This ensures that your ElevenLabs API keys and other sensitive information remain secure throughout the process.
Back End Example
In this example, we demonstrate how to set up and use ElevenLabsProxyStartup
in a new ASP.NET Core web app. The proxy server will handle authentication and forward requests to the ElevenLabs API, ensuring that your API keys and other sensitive information remain secure.
- Create a new ASP.NET Core minimal web API project.
- Add the ElevenLabs-DotNet nuget package to your project.
- Powershell install:
Install-Package ElevenLabs-DotNet-Proxy
- Dotnet install:
dotnet add package ElevenLabs-DotNet-Proxy
- Manually editing .csproj:
<PackageReference Include="ElevenLabs-DotNet-Proxy" />
- Powershell install:
- Create a new class that inherits from
AbstractAuthenticationFilter
and override theValidateAuthentication
method. This will implement theIAuthenticationFilter
that you will use to check user session token against your internal server. - In
Program.cs
, create a new proxy web application by callingElevenLabsProxyStartup.CreateWebApplication
method, passing your customAuthenticationFilter
as a type argument. - Create
ElevenLabsAuthentication
andElevenLabsClientSettings
as you would normally with your API keys, org id, or Azure settings.
public partial class Program
{
private class AuthenticationFilter : AbstractAuthenticationFilter
{
public override async Task ValidateAuthenticationAsync(IHeaderDictionary request)
{
await Task.CompletedTask; // remote resource call
// You will need to implement your own class to properly test
// custom issued tokens you've setup for your end users.
if (!request["xi-api-key"].ToString().Contains(TestUserToken))
{
throw new AuthenticationException("User is not authorized");
}
}
}
public static void Main(string[] args)
{
var auth = ElevenLabsAuthentication.LoadFromEnv();
var client = new ElevenLabsClient(auth);
ElevenLabsProxyStartup.CreateWebApplication<AuthenticationFilter>(args, client).Run();
}
}
Once you have set up your proxy server, your end users can now make authenticated requests to your proxy api instead of directly to the ElevenLabs API. The proxy server will handle authentication and forward requests to the ElevenLabs API, ensuring that your API keys and other sensitive information remain secure.
Text to Speech
Convert text to speech.
var api = new ElevenLabsClient();
var text = "The quick brown fox jumps over the lazy dog.";
var voice = (await api.VoicesEndpoint.GetAllVoicesAsync()).FirstOrDefault();
var request = new TextToSpeechRequest(voice, text);
var voiceClip = await api.TextToSpeechEndpoint.TextToSpeechAsync(request);
await File.WriteAllBytesAsync($"{voiceClip.Id}.mp3", voiceClip.ClipData.ToArray());
Stream Text To Speech
Stream text to speech.
var api = new ElevenLabsClient();
var text = "The quick brown fox jumps over the lazy dog.";
var voice = (await api.VoicesEndpoint.GetAllVoicesAsync()).FirstOrDefault();
string fileName = "myfile.mp3";
using var outputFileStream = File.OpenWrite(fileName);
var request = new TextToSpeechRequest(voice, text);
var voiceClip = await api.TextToSpeechEndpoint.TextToSpeechAsync(request,
partialClipCallback: async (partialClip) =>
{
// Write the incoming data to the output file stream.
// Alternatively you can play this clip data directly.
await outputFileStream.WriteAsync(partialClip.ClipData);
});
Voices
Access to voices created either by the user or ElevenLabs.
Get Shared Voices
Gets a list of shared voices in the public voice library.
var api = new ElevenLabsClient();
var results = await ElevenLabsClient.SharedVoicesEndpoint.GetSharedVoicesAsync();
foreach (var voice in results.Voices)
{
Console.WriteLine($"{voice.OwnerId} | {voice.VoiceId} | {voice.Date} | {voice.Name}");
}
Get All Voices
Gets a list of all available voices available to your account.
var api = new ElevenLabsClient();
var allVoices = await api.VoicesEndpoint.GetAllVoicesAsync();
foreach (var voice in allVoices)
{
Console.WriteLine($"{voice.Id} | {voice.Name} | similarity boost: {voice.Settings?.SimilarityBoost} | stability: {voice.Settings?.Stability}");
}
Get Default Voice Settings
Gets the global default voice settings.
var api = new ElevenLabsClient();
var result = await api.VoicesEndpoint.GetDefaultVoiceSettingsAsync();
Console.WriteLine($"stability: {result.Stability} | similarity boost: {result.SimilarityBoost}");
Get Voice
var api = new ElevenLabsClient();
var voice = await api.VoicesEndpoint.GetVoiceAsync("voiceId");
Console.WriteLine($"{voice.Id} | {voice.Name} | {voice.PreviewUrl}");
Edit Voice Settings
Edit the settings for a specific voice.
var api = new ElevenLabsClient();
var success = await api.VoicesEndpoint.EditVoiceSettingsAsync(voice, new VoiceSettings(0.7f, 0.7f));
Console.WriteLine($"Was successful? {success}");
Add Voice
var api = new ElevenLabsClient();
var labels = new Dictionary<string, string>
{
{ "accent", "american" }
};
var audioSamplePaths = new List<string>();
var voice = await api.VoicesEndpoint.AddVoiceAsync("Voice Name", audioSamplePaths, labels);
Edit Voice
var api = new ElevenLabsClient();
var labels = new Dictionary<string, string>
{
{ "age", "young" }
};
var audioSamplePaths = new List<string>();
var success = await api.VoicesEndpoint.EditVoiceAsync(voice, audioSamplePaths, labels);
Console.WriteLine($"Was successful? {success}");
Delete Voice
var api = new ElevenLabsClient();
var success = await api.VoicesEndpoint.DeleteVoiceAsync(voiceId);
Console.WriteLine($"Was successful? {success}");
Samples
Access to your samples, created by you when cloning voices.
Download Voice Sample
var api = new ElevenLabsClient();
var voiceClip = await api.VoicesEndpoint.DownloadVoiceSampleAsync(voice, sample);
await File.WriteAllBytesAsync($"{voiceClip.Id}.mp3", voiceClip.ClipData.ToArray());
Delete Voice Sample
var api = new ElevenLabsClient();
var success = await api.VoicesEndpoint.DeleteVoiceSampleAsync(voiceId, sampleId);
Console.WriteLine($"Was successful? {success}");
Dubbing
Dub
Dubs provided audio or video file into given language.
var api = new ElevenLabsClient();
// from URI
var request = new DubbingRequest(new Uri("https://youtu.be/Zo5-rhYOlNk"), "ja", "en", 1, true);
// from file
var request = new DubbingRequest(filePath, "es", "en", 1);
var metadata = await api.DubbingEndpoint.DubAsync(request, progress: new Progress<DubbingProjectMetadata>(metadata =>
{
switch (metadata.Status)
{
case "dubbing":
Console.WriteLine($"Dubbing for {metadata.DubbingId} in progress... Expected Duration: {metadata.ExpectedDurationSeconds:0.00} seconds");
break;
case "dubbed":
Console.WriteLine($"Dubbing for {metadata.DubbingId} complete in {metadata.TimeCompleted.TotalSeconds:0.00} seconds!");
break;
default:
Console.WriteLine($"Status: {metadata.Status}");
break;
}
}));
Get Dubbing Metadata
Returns metadata about a dubbing project, including whether it’s still in progress or not.
var api = new ElevenLabsClient();
var metadata = api.await GetDubbingProjectMetadataAsync("dubbing-id");
Get Dubbed File
Returns dubbed file as a streamed file.
[!NOTE] Videos will be returned in MP4 format and audio only dubs will be returned in MP3.
var assetsDir = Path.GetFullPath("../../../Assets");
var dubbedPath = new FileInfo(Path.Combine(assetsDir, $"online.dubbed.{request.TargetLanguage}.mp4"));
{
await using var fs = File.Open(dubbedPath.FullName, FileMode.Create);
await foreach (var chunk in ElevenLabsClient.DubbingEndpoint.GetDubbedFileAsync(metadata.DubbingId, request.TargetLanguage))
{
await fs.WriteAsync(chunk);
}
}
Get Transcript for Dub
Returns transcript for the dub in the desired format.
var assetsDir = Path.GetFullPath("../../../Assets");
var transcriptPath = new FileInfo(Path.Combine(assetsDir, $"online.dubbed.{request.TargetLanguage}.srt"));
{
var transcriptFile = await api.DubbingEndpoint.GetTranscriptForDubAsync(metadata.DubbingId, request.TargetLanguage);
await File.WriteAllTextAsync(transcriptPath.FullName, transcriptFile);
}
Delete Dubbing Project
Deletes a dubbing project.
var api = new ElevenLabsClient();
await api.DubbingEndpoint.DeleteDubbingProjectAsync("dubbing-id");
SFX Generation
API that converts text into sounds & uses the most advanced AI audio model ever.
var api = new ElevenLabsClient();
var request = new SoundGenerationRequest("Star Wars Light Saber parry");
var clip = await api.SoundGenerationEndpoint.GenerateSoundAsync(request);
History
Access to your previously synthesized audio clips including its metadata.
Get History
Get metadata about all your generated audio.
var api = new ElevenLabsClient();
var historyItems = await api.HistoryEndpoint.GetHistoryAsync();
foreach (var item in historyItems.OrderBy(historyItem => historyItem.Date))
{
Console.WriteLine($"{item.State} {item.Date} | {item.Id} | {item.Text.Length} | {item.Text}");
}
Get History Item
Get information about a specific item.
var api = new ElevenLabsClient();
var historyItem = await api.HistoryEndpoint.GetHistoryItemAsync(voiceClip.Id);
Download History Audio
var api = new ElevenLabsClient();
var voiceClip = await api.HistoryEndpoint.DownloadHistoryAudioAsync(historyItem);
await File.WriteAllBytesAsync($"{voiceClip.Id}.mp3", voiceClip.ClipData.ToArray());
Download History Items
Downloads the last 100 history items, or the collection of specified items.
var api = new ElevenLabsClient();
var voiceClips = await api.HistoryEndpoint.DownloadHistoryItemsAsync();
Delete History Item
var api = new ElevenLabsClient();
var success = await api.HistoryEndpoint.DeleteHistoryItemAsync(historyItem);
Console.WriteLine($"Was successful? {success}");
User
Access to your user Information and subscription status.
Get User Info
Gets information about your user account with ElevenLabs.
var api = new ElevenLabsClient();
var userInfo = await api.UserEndpoint.GetUserInfoAsync();
Get Subscription Info
Gets information about your subscription with ElevenLabs.
var api = new ElevenLabsClient();
var subscriptionInfo = await api.UserEndpoint.GetSubscriptionInfoAsync();
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
-
net8.0
- No dependencies.
NuGet packages (2)
Showing the top 2 NuGet packages that depend on ElevenLabs-DotNet:
Package | Downloads |
---|---|
FrostAura.Libraries.Intelligence.Semantic.Core
FrostAura Semantic Core provides structures and utilities to build language and hybrid applications. |
|
ElevenLabs-DotNet-Proxy
A simple Proxy API gateway for ElevenLabs-DotNet to make authenticated requests from a front end application without exposing your API keys. |
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
3.4.1 | 1,237 | 11/25/2024 |
3.4.0 | 91 | 11/25/2024 |
3.1.0 | 4,668 | 9/14/2024 |
3.0.3 | 119 | 9/14/2024 |
3.0.2 | 374 | 9/3/2024 |
3.0.1 | 99 | 9/2/2024 |
3.0.0 | 283 | 9/2/2024 |
2.2.1 | 23,210 | 5/9/2024 |
2.2.0 | 200 | 5/6/2024 |
2.1.1 | 3,500 | 2/15/2024 |
2.1.0 | 2,315 | 11/29/2023 |
2.0.3 | 930 | 11/15/2023 |
2.0.2 | 171 | 11/14/2023 |
2.0.1 | 134 | 11/11/2023 |
2.0.0 | 267 | 10/29/2023 |
1.3.6 | 2,146 | 9/28/2023 |
1.3.5 | 1,428 | 7/14/2023 |
1.3.4 | 1,748 | 5/29/2023 |
1.3.3 | 563 | 5/21/2023 |
1.3.2 | 422 | 5/12/2023 |
1.3.0 | 212 | 5/1/2023 |
1.2.1 | 174 | 4/30/2023 |
1.2.0 | 170 | 4/30/2023 |
1.1.1 | 380 | 3/26/2023 |
1.1.0 | 208 | 3/26/2023 |
1.0.4 | 240 | 3/24/2023 |
1.0.3 | 242 | 3/13/2023 |
1.0.2 | 218 | 3/12/2023 |
1.0.1 | 228 | 3/11/2023 |
1.0.0 | 255 | 3/11/2023 |
Version 3.4.1
- Removed text length check in TextToSpeechRequest
Version 3.4.0
- Added additional request properties for TextToSpeechRequest
- previous_text, next_text, previous_request_ids, next_request_ids, languageCode, withTimestamps
- Added support for transcription timestamps in TextToSpeechResponse
- Added support for language code in TextToSpeechRequest
Version 3.1.0
- Refactored TextToSpeechEndpoint endpoint to accept TextToSpeechRequest object
- Added text encoding options to TextToSpeechRequest
- Added previous text input parameter to TextToSpeechRequest
Version 3.0.3
- Fix DubbingRequest.DropBackgroundAudio flag not properly being set
- Added DubbingRequest.UseProfanityFilter flag
Version 3.0.2
- Cleanup and polish for Dubbing API
Version 3.0.1
- Updated Models
Version 3.0.0
- Updated to .NET 8.0
- Added ability to specify fully customizable domain proxies
- Added environment variable parsing for ELEVENLABS_API_KEY
- Added SoundEffects API endpoints
- Added Dubbing API endpoints
- Updated default models
- Fixed adding and editing voices
Version 2.2.1
- Misc formatting changes
Version 2.2.0
- Changed ElevenLabsClient to be IDisposable
- The ElevenLabsClient must now be disposed if you do not pass your own HttpClient
- Updated ElevenLabsClientSettings to accept custom domains
- Added filesystemless overloads for uploading audio clips
Version 2.1.1
- Added VoicesEndpoint.GetAllVoicesAsync overload that allows skipping downloading the voice settings
Version 2.1.0
- Added ElevenLabsClient.EnableDebug option to enable and disable for all endpoints
- Synced changes from unity package
- Updated unit test
Version 2.0.3
- Fixed text to speech streaming
Version 2.0.2
- Added the u-law format
Version 2.0.1
- Pass some cancellation tokens to internals
Version 2.0.0
Refactoring to support latest API changes
- Biggest Change is the new VoiceClip signature for all endpoints which contains all the information about the generated clip.
- Refactored HistoryEndpoint
- Made HistoryInfo public
- GetHistoryAsync now returns HistoryInfo and contains additional pageSize and startAfter properties
- Added GetHistoryItemAsync
- Renamed GetHistoryAudioAsync -> DownloadHistoryAudioAsync
- DownloadHistoryItemsAsync now returns a list of VoiceClips, and no longer asks for saveDirectory
- HistoryItem.TextHash was modified to generate hash based on item id, instead of voiceId
- Refactored ModelsEndpoint
- Added Model.MultiLingualV2
- Refactored TextToSpeechEndpoint
- Refactored TextToSpeechAsync
- Removed saveDirectory parameter
- Removed deleteCachedFile parameter
- Added outputFormat parameter
- Changed return type to VoiceClip
- Refactored StreamTextToSpeechAsync
- Removed saveDirectory parameter
- Removed deleteCachedFile parameter
- Added outputFormat
- Added partialClipCallback for queuing and playing partial clips as they are received
- Refactored VoiceGenerationEndpoint
- Renamed GenerateVoiceAsync -> GenerateVoicePreviewAsync
- Removed saveDirectory parameter
- Renamed GeneratedVoiceRequest -> GeneratedVoicePreviewRequest
- Refactored VoicesEndpoint
- Preserve default values in VoiceSettings
- Refactored GetVoiceAsync
- withSettings parameter is now false by default per API
- Renamed GetVoiceSampleAsync -> DownloadVoiceSampleAsync
- Changed return type to VoiceClip
- Removed saveDirectory parameter
Version 1.3.6
- Added Voice.HighQualityBaseModelIds
- Added CreateVoiceRequest.Description
Version 1.3.5
- Updated voice settings
Version 1.3.4
- Added VoiceSettings setters for convience
- Added voice validation in tts endpoint
Version 1.3.3
- Assign default voice names
- Get voice details if missing in tts
Version 1.3.2
- Added voice equality operators
- Added better parameter validation checks in Endpoints
Version 1.3.0
- Added ModelsEndpoint
- Updated TextToSpeech.TextToSpeechAsync with optional Model parameter. Defaults to eleven_monolingual_v1
Version 1.2.1
- Updated docs
Version 1.2.0
- Added ability to create voice from Id
- Refactored internal extension classes
- Fixed auth parsing
- Added ability to load configuration file from specific path
- Added optional parameter deleteCachedFile to TextToSpeechEndpoint.TextToSpeechAsync. Default is false
Version 1.1.0
- Added support for ElevenLabs-DotNet-Proxy
Version 1.0.4
- Updated docs
- Removed exception when sample item path is null or whitespace
Version 1.0.3
- Updated DownloadHistoryItemsAsync to download all items if no ids are specified
- Updated docs
Version 1.0.2
- Added VoiceGenerationEndpoint
- Added unit tests for voice design and instant voice cloning
- Updated docs
Version 1.0.1
- Updated docs
Version 1.0.0
- Initial Release!