elevenlabs / elevenlabs-js

The official JavaScript (Node) library for ElevenLabs Text to Speech.

ElevenLabs JS Library

The official JS API for ElevenLabs text-to-speech software. Eleven brings the most compelling, rich and lifelike voices to creators and developers in just a few lines of code.

📖 API & Docs

Check out the HTTP API documentation.

⚙️ Install

npm install elevenlabs
# or 
yarn add elevenlabs

🗣️ Usage

We support two main models: the newest eleven_multilingual_v2, a single foundational model supporting 29 languages including English, Chinese, Spanish, Hindi, Portuguese, French, German, Japanese, Arabic, Korean, Indonesian, Italian, Dutch, Turkish, Polish, Swedish, Filipino, Malay, Russian, Romanian, Ukrainian, Greek, Czech, Danish, Finnish, Bulgarian, Croatian, Slovak, and Tamil; and eleven_monolingual_v1, a low-latency model specifically trained for English speech.

import { ElevenLabsClient, play } from "elevenlabs";

const elevenlabs = new ElevenLabsClient({
  apiKey: "YOUR_API_KEY" // Defaults to process.env.ELEVENLABS_API_KEY
})

const audio = await elevenlabs.generate({
  voice: "Rachel",
  text: "Hello! 你好! Hola! नमस्ते! Bonjour! こんにちは! مرحبا! 안녕하세요! Ciao! Cześć! Привіт! வணக்கம்!",
  model_id: "eleven_multilingual_v2"
});

await play(audio);

Play

Don't forget to unmute the player!

audio.3.webm

🗣️ Voices

List all your available voices with voices().

import { ElevenLabsClient } from "elevenlabs";

const elevenlabs = new ElevenLabsClient({
  apiKey: "YOUR_API_KEY" // Defaults to process.env.ELEVENLABS_API_KEY
})
const voices = await elevenlabs.voices.getAll();

Show output

    {
      voices: [
        {
          voice_id: '21m00Tcm4TlvDq8ikWAM',
          name: 'Rachel',
          samples: null,
          category: 'premade',
          fine_tuning: [Object],
          labels: [Object],
          description: null,
          preview_url: 'https://storage.googleapis.com/eleven-public-prod/premade/voices/21m00Tcm4TlvDq8ikWAM/df6788f9-5c96-470d-8312-aab3b3d8f50a.mp3',
          available_for_tiers: [],
          settings: null,
          sharing: null,
          high_quality_base_model_ids: []
        },
        {
          voice_id: '29vD33N1CtxCmqQRPOHJ',
          name: 'Drew',
          samples: null,
          category: 'premade',
          fine_tuning: [Object],
          labels: [Object],
          description: null,
          preview_url: 'https://storage.googleapis.com/eleven-public-prod/premade/voices/29vD33N1CtxCmqQRPOHJ/e8b52a3f-9732-440f-b78a-16d5e26407a1.mp3',
          available_for_tiers: [],
          settings: null,
          sharing: null,
          high_quality_base_model_ids: []
        },
        ...
      ]
    }

🚿 Streaming

Stream audio in real-time, as it's being generated.

const audioStream = await elevenlabs.generate({
  stream: true,
  voice: "Bella",
  text: "This is a... streaming voice",
  model_id: "eleven_multilingual_v2"
});

stream(audioStream)

Retries

This Node SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long as the request is deemed retriable and the number of retry attempts has not grown larger than the configured retry limit (default: 2).

A request is deemed retriable when any of the following HTTP status codes is returned:

• 408 (Timeout)
• 409 (Conflict)
• 429 (Too Many Requests)
• 5XX (Internal Server Errors)

Use the maxRetries request option to configure this behavior.

const response = await elevenlabs.voices.getAll({
  maxRetries: 0 // override maxRetries at the request level
});

Timeouts

The SDK defaults to a 60 second timout. Use the timeoutInSeconds option to configure this behavior.

const response = elevenlabs.voices.getAll({
  timeoutInSeconds: 30 // override timeout to 30s
});

Runtime compatiblity

The SDK defaults to node-fetch but will use the global fetch client if present. The SDK works in the following runtimes:

The following runtimes are supported:

• Node.js 15+
• Vercel
• Cloudflare Workers
• Deno v1.25+
• Bun 1.0+

Customizing Fetch client

The SDK provides a way for you to customize the underlying HTTP client / Fetch function. If you're running in an unsupported environment, this provides a way for you to break the glass and ensure the SDK works.

import { ElevenLabsClient } from "elevenlabs";

const elevenlabs = new ElevenLabsClient({
  apiKey: "...",
  fetcher: // provide your implementation here
});

Elevenlabs Namespace

All of the ElevenLabs models are nested within the ElevenLabs namespace.

Languages Supported

We support 29 languages and 100+ accents. Explore all languages.

Contributing

While we value open-source contributions to this SDK, this library is generated programmatically. Additions made directly to this library would have to be moved over to our generation code, otherwise they would be overwritten upon the next generated release. Feel free to open a PR as a proof of concept, but know that we will not be able to merge it as-is. We suggest opening an issue first to discuss with us!

On the other hand, contributions to the README are always very welcome!

elevenlabs-js's Issues

Serious issues when generating speeches for German language

Several issues appear when generating speeches for the German language:

• In German texts, numbers and dates will ALWAYS be spoken in English
• In German texts, English names and English words, that actually should be spoken in English and pronounced that way, were spoken in German, which sounds weird
• when too many non-german words occur within a sentence, like French names, the speaker turns into English dialect
• the same happens the longer a text is

It would be necessary to provide the target language as a specific setting to "tell" the models which language to be expected. Auto classification of the underlying language doesn't work at the moment and probably can't work in the long term thanks to the integration of English words and names naturally in other native languages (anglicisms).

Add an example for voices.add in the readme

Would love to know how to create a voice using this lib. Thanks.

Ways to set stream to false when using elevenlabs.textToSpeech.convert

Hi, I was trying below code, but its always streaming is there a way to pass down some props to fetcher so that we can also get a normal response?

const audio = await elevenlabs.textToSpeech.convert(voice.voice_id, {
    text,
    model_id: 'eleven_multilingual_v2',
    output_format: 'mp3_22050_32',
    voice_settings: {
      stability: 0.1,
      similarity_boost: 0.3,
      style: 0.2,
    },
})

Thank you!

Something is broken in v `0.1.6`

There's an error in the latest version 0.1.6 @dsinghvi. When I try to fetch voices with await elevenlabs.voices.getAll(), I get the error:

ElevenLabsError: fetchFn is not a function
    at Voices.eval (webpack-internal:///(action-browser)/./node_modules/elevenlabs/api/resources/voices/client/Client.js:104:27)
    at Generator.next (<anonymous>)
    at fulfilled (webpack-internal:///(action-browser)/./node_modules/elevenlabs/api/resources/voices/client/Client.js:31:58)
    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
ElevenLabsError: fetchFn is not a function
    at Voices.eval (webpack-internal:///(action-browser)/./node_modules/elevenlabs/api/resources/voices/client/Client.js:104:27)
    at Generator.next (<anonymous>)
    at fulfilled (webpack-internal:///(action-browser)/./node_modules/elevenlabs/api/resources/voices/client/Client.js:31:58)
    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)

I've reverted to 0.1.5, and it works fine. I just thought you should know. Thank you.

Errors in Nuxt web app

@dsinghvi I'm attempting to write a simple Nuxt app to call the API but am running into errors. Does this mean it's not currently possible to use elevenlabs.js in the browser?

Errors (abbreviated for readability):

Module "child_process" has been externalized for browser compatibility. Cannot access "child_process.exec" in client code. See https://vitejs.dev/guide/troubleshooting.html#module-externalized-for-browser-compatibility for more details. [elevenlabs.js:7204:19]

Module "fs" has been externalized for browser compatibility. Cannot access "fs.access" in client code. [elevenlabs.js:7217:19]

Module "os" has been externalized for browser compatibility. Cannot access "os.constants" in client code. [elevenlabs.js:8007:19]

Uncaught TypeError: _os.constants is undefined

From the above referenced vite.dev site:

Module externalized for browser compatibility

When you use a Node.js module in the browser, Vite will output the following warning.
Module "fs" has been externalized for browser compatibility. Cannot access "fs.readFile" in client code.
This is because Vite does not automatically polyfill Node.js modules.

We recommend avoiding Node.js modules for browser code to reduce the bundle size, although you can add polyfills manually. If the module is imported from a third-party library (that's meant to be used in the browser), it's advised to report the issue to the respective library.

Streaming input

Hey! It's nice to have a JS library, thanks! I'd like to know if it's in your plans to add streaming input as the Python library has?

API Key not being passed

I don't think the API key is being passed to the API. I have tried both the .env method and declaring it directly in code. Getting a 401 response.

Streaming using elevenlabs.generate is not working

Following your recent documentation on the README, it states streaming generated audio can be done via the below:

I've attempted to achieve this with the code below

    const audioStream = await elevenlabs.generate({
        stream: true,
        voice: "Liam",
        text: "This is a... streaming voice",
        model_id: "eleven_multilingual_v2"
    });
        

    stream(audioStream)

This doesn't seem to work, now when I am using play() and playing it directly, with the stream: false set (or not defined), it works fine, however the second I go to stream it, it seems to throw an error in my node application:

node:internal/process/promises:288
            triggerUncaughtException(err, true /* fromPromise */);
            ^

[UnhandledPromiseRejection: This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). The promise rejected with the reason "null".] {
  code: 'ERR_UNHANDLED_REJECTION'
}

Node.js v18.12.1

Any suggestions? I've attempted to try and catch this error but I can't seem to find anything of value from it.

Update:

Okay so I've managed to get a more specific error than just "null"

node:internal/process/promises:288
            triggerUncaughtException(err, true /* fromPromise */);
            ^

Error: write EPIPE
    at afterWriteDispatched (node:internal/stream_base_commons:160:15)
    at writeGeneric (node:internal/stream_base_commons:151:3)
    at Socket._writeGeneric (node:net:917:11)
    at Socket._write (node:net:929:8)
    at writeOrBuffer (node:internal/streams/writable:392:12)
    at _write (node:internal/streams/writable:333:10)
    at Writable.write (node:internal/streams/writable:337:10)
    at D:\Development\ai-assistant\node_modules\elevenlabs\wrapper\stream.js:42:74
    at Generator.next (<anonymous>)
    at fulfilled (D:\Development\ai-assistant\node_modules\elevenlabs\wrapper\stream.js:5:58) {
  errno: -4047,
  code: 'EPIPE',
  syscall: 'write'
}

Node JS SDK NPM Run start Error

When install Node JS SDK, I encounter an error.

Steps to reproduce:

1. In node folder, run npm install and fill the .env file.
2. Run npm run start or npx tsx src/index. It should return the following error

> start
> tsx src/index.ts

xxx\node_modules\elevenlabs\api\resources\pronunciationDictionary\client\Client.js:98
                        throw new errors.ElevenLabsError({
                              ^

ElevenLabsError: Status code: 400
Body: {
  "detail": {
    "status": "Unable to parse lexicon file",
    "message": "Unable to parse lexicon file. Lexicon file formatted incorrectly"
  }
}
    at PronunciationDictionary.<anonymous> xxx\node_modules\elevenlabs\api\resources\pronunciationDictionary\client\Client.js:98:31)
    at Generator.next (<anonymous>)
    at fulfilled (xxx\node_modules\elevenlabs\api\resources\pronunciationDictionary\client\Client.js:31:58)
    at process.processTicksAndRejections (node:internal/process/task_queues:95:5) {
  statusCode: 400,
  body: {
    detail: {
      status: 'Unable to parse lexicon file',
      message: 'Unable to parse lexicon file. Lexicon file formatted incorrectly'
    }
  }
}

Node.js v18.16.0

Feature Request: Add Language Selection Capability to API for Inference

Feature Request

Summary:
The current version of the ElevenLabs API does not allow users to specify a language during inference. This feature would be incredibly beneficial for developers working on multilingual applications, ensuring that the generated output adheres to the desired language, especially in contexts where the input data might be ambiguous or multilingual.

Description:
In many applications, especially those handling user-generated content, the language of the input data can vary significantly. The ability to explicitly specify the target language for inference would enhance the API's flexibility and accuracy in generating appropriate responses. This is particularly crucial for applications serving global user bases across multiple languages.

Proposed Solution:
Introduce a new parameter in the API request for inference, named language, which allows developers to specify the desired language for the output. The parameter should accept ISO language codes (e.g., 'en' for English, 'fr' for French) and should be optional. If not specified, the API can default to its current behavior of inferring the language from the input data.

Example Usage with Proposed Feature:

import { ElevenLabsClient } from "elevenlabs";

const elevenlabs = new ElevenLabsClient({
  apiKey: "YOUR_API_KEY" // Defaults to process.env.ELEVENLABS_API_KEY
});

const audio = await elevenlabs.generate({
  voice: "Rachel",
  text: "Hello!",
  language: "en", // Specifying the language as English
  model_id: "eleven_multilingual_v2"
});

Do you use the correct method to make a stream output?

elevenlabs-js/src/wrapper/ElevenLabsClient.ts

Lines 70 to 74 in 895b619

	if (isGenerateAudioStream(request)) {
	return await this.textToSpeech.convert(voiceId, request, requestOptions);
	} else {
	return await this.textToSpeech.convert(voiceId, request, requestOptions);
	}

Issues with some missing exports

Hi! Thanks for creating a JS equivalent of the Python SDK.

I was giving it a quick spin and tried to test in a local TypeScript environment but kept getting the error: Module '"elevenlabs"' has no exported member 'play'. The same applies to stream.

For the apiKey argument:

Even the generate property does not exist:

---

The same error occurs even when the SDK is imported into a Reactjs environment. Is there something I'm missing or some type definitions we need to install for the SDK? Everything seems to be set up correctly on my end.

NextJS - Can't resolve 'child_process'

In a very simple implementation:

"use client";

import { ElevenLabsClient, play } from "elevenlabs";

export default async function Audio(props: any) {
  const elevenlabs = new ElevenLabsClient({
    apiKey: "process.env.ELEVENLABS_API_KEY",
  });
  const audio = await elevenlabs.generate({
    voice: "Rachel",
    text: "We support two main models.",
    model_id: "eleven_multilingual_v2",
  });
  await play(audio);
  return <div>Placeholder</div>;
}

This error is persistent.

./node_modules/command-exists/lib/command-exists.js:3:0
Module not found: Can't resolve 'child_process'

https://nextjs.org/docs/messages/module-not-found

Import trace for requested module:
./node_modules/command-exists/index.js
./node_modules/elevenlabs/wrapper/play.js
./node_modules/elevenlabs/wrapper/index.js
./node_modules/elevenlabs/index.js
./components/Audio.tsx
./components/ChatMessageBubble.tsx
./components/ChatWindow.tsx

I can change the config every which way and it doesn't resolve the issue.

For example, in package.config, I can set:

  "browser": {
    "fs": false,
    "child_process": false
  },

However, then it shows the following error.

cannot destructure property 'signals' of '_os.constants' as it is undefined

---

These are the details of my project:

"engines": {
  "node": ">=18"
},
  "dependencies": {
   ...
   "elevenlabs": "^0.2.2",
   "next": "^14.0.1",
   "react": "18.2.0",
   "react-dom": "18.2.0",
   ...
  },