Elevenlabs Ruby Gem

A Ruby client for the ElevenLabs Text-to-Speech API.
This gem provides an easy-to-use interface for:

Listing available voices
Fetching details about a voice
Creating a custom voice (with uploaded sample files)
Editing an existing voice
Deleting a voice
Converting text to speech and retrieving the generated audio

All requests are handled via Faraday.

Features
Installation
Usage
- Basic Example
- Rails Integration
  - Store API Key in Rails Credentials
  - Rails Initializer
  - Controller Example
Endpoints
Error Handling
Development
Contributing
License

Features

Simple and intuitive API client for ElevenLabs.
Multipart file uploads for training custom voices.
Automatic authentication via API key configuration.
Error handling with custom exceptions.
Rails integration support (including credentials storage).

Installation

Add the gem to your Gemfile:

gem "elevenlabs"

Then run:

bundle install

Or install it directly using:

gem install elevenlabs

Usage Basic Example (Standalone Ruby)

require "elevenlabs"

# 1. Configure the gem globally (Optional)
Elevenlabs.configure do |config|
  config.api_key = "YOUR_API_KEY"
end

# 2. Initialize a client (will use configured API key)
client = Elevenlabs::Client.new

# 3. List available voices
voices = client.list_voices
puts voices # JSON response with voices

# 4. Convert text to speech
voice_id = "YOUR_VOICE_ID"
text = "Hello from Elevenlabs!"
audio_data = client.text_to_speech(voice_id, text)

# 5. Save the audio file
File.open("output.mp3", "wb") { |f| f.write(audio_data) }
puts "Audio file saved to output.mp3"

Note: You can override the API key per request:

client = Elevenlabs::Client.new(api_key: "DIFFERENT_API_KEY")

Rails Integration Store API Key in Rails Credentials

Open your encrypted credentials:

EDITOR=vim rails credentials:edit

Add the ElevenLabs API key:

eleven_labs:
  api_key: YOUR_SECURE_KEY

Save and exit. Rails will securely encrypt your API key.

Rails Initializer Create an initializer file: config/initializers/elevenlabs.rb

# config/initializers/elevenlabs.rb
require "elevenlabs"

Rails.application.config.to_prepare do
  Elevenlabs.configure do |config|
    config.api_key = Rails.application.credentials.dig(:eleven_labs, :api_key)
  end
end

Now you can simply call:

client = Elevenlabs::Client.new

without manually providing an API key.

Endpoints

List Voices

client.list_voices
# => { "voices" => [...] }

Get Voice Details

client.get_voice("VOICE_ID")
# => { "voice_id" => "...", "name" => "...", ... }

Create a Custom Voice

sample_files = [File.open("sample1.mp3", "rb")]
client.create_voice("Custom Voice", sample_files, description: "My custom AI voice")
# => JSON response with new voice details

Check if a voice is banned?

sample_files = [File.open("trump.mp3", "rb")]
client.create_voice("Donald Trump", sample_files, description: "My Trump Voice")
  => {"voice_id"=>"<RETURNED_VOICE_ID>", "requires_verification"=>false}
  trump= "<RETURNED_VOICE_ID>"
  client.banned? trump
=> true

Edit a Voice

client.edit_voice("VOICE_ID", name: "Updated Voice Name")
# => JSON response with updated details

Delete a Voice

client.delete_voice("VOICE_ID")
# => JSON response acknowledging deletion

Convert Text to Speech

audio_data = client.text_to_speech("VOICE_ID", "Hello world!")
File.open("output.mp3", "wb") { |f| f.write(audio_data) }

8 Stream Text to Speech stream from terminal

Mac: brew install sox
Linux: sudo apt install sox

IO.popen("play -t mp3 -", "wb") do |audio_pipe| # Notice "wb" (write binary)
  client.text_to_speech_stream("VOICE_ID", "Some text to stream back in chunks") do |chunk|
    audio_pipe.write(chunk.b) # Ensure chunk is written as binary
  end
end

Error Handling When the API returns an error, the gem raises specific exceptions:

Exception Meaning Elevenlabs::BadRequestError Invalid request parameters Elevenlabs::AuthenticationError Invalid API key Elevenlabs::NotFoundError Resource (voice) not found Elevenlabs::APIError General API failure Example:

begin
  client.text_to_speech("INVALID_VOICE_ID", "Test")
rescue Elevenlabs::AuthenticationError => e
  puts "Invalid API key: #{e.message}"
rescue Elevenlabs::NotFoundError => e
  puts "Voice not found: #{e.message}"
rescue Elevenlabs::APIError => e
  puts "General error: #{e.message}"
end

Development Clone this repository

git clone https://github.com/your-username/elevenlabs.git
cd elevenlabs

Install dependencies

bundle install

Build the gem

gem build elevenlabs.gemspec

Install the gem locally

gem install ./elevenlabs-0.0.3.gem

Contributing Contributions are welcome! Please follow these steps:

Fork the repository Create a feature branch (git checkout -b feature/my-new-feature) Commit your changes (git commit -am 'Add new feature') Push to your branch (git push origin feature/my-new-feature) Create a Pull Request describing your changes For bug reports, please open an issue with details.

License This project is licensed under the MIT License. See the LICENSE file for details.

⭐ Thank you for using the Elevenlabs Ruby Gem! If you have any questions or suggestions, feel free to open an issue or submit a Pull Request!

elevenlabs

Runtime

Elevenlabs Ruby Gem

Table of Contents

Features

Installation

elevenlabs