{
  "compilerOptions": {
    "paths": {
      "@elevenlabs/*": ["./src/elevenlabs/*"]
    },
    "moduleResolution": "node16",
    "esModuleInterop": true,
    "target": "ES2020",
    "module": "CommonJS"
  }
}

3. Set your API key as an environment variable:

export ELEVENLABS_API_KEY=your_key_here

4. Import directly from the source root:

import { ElevenLabsClient } from "./src/elevenlabs/Client";
import { play, stream } from "./src/elevenlabs/wrapper";
import { ElevenLabsEnvironment } from "./src/elevenlabs/environments";
import { ElevenLabsError } from "./src/elevenlabs/errors";

Or via the barrel if you keep the path alias:

import { ElevenLabsClient, play, stream, ElevenLabsEnvironment, ElevenLabsError } from "@elevenlabs/index";

Public API

ElevenLabsClient

import { ElevenLabsClient } from "./src/elevenlabs/Client";

const client = new ElevenLabsClient({
  apiKey?: string;           // defaults to process.env.ELEVENLABS_API_KEY
  environment?: ElevenLabsEnvironment;
  maxRetries?: number;       // default 2
  timeoutInSeconds?: number;
});

The main entry point. Exposes every API resource as a property (client.textToSpeech, client.voices, client.dubbing, client.conversationalAi, etc.). Instantiate once and reuse across your application.

ElevenLabsEnvironment

import { ElevenLabsEnvironment } from "./src/elevenlabs/environments";

// Values: ElevenLabsEnvironment.Production (default)

Use this enum when you need to point the client at a non-default base URL (e.g. a proxy or staging environment). Pass it as environment in the client constructor.

ElevenLabsError / ElevenLabsTimeoutError

import { ElevenLabsError, ElevenLabsTimeoutError } from "./src/elevenlabs/errors";

// ElevenLabsError extends Error and carries statusCode, body
// ElevenLabsTimeoutError is thrown when a request exceeds timeoutInSeconds

Use these in catch blocks to distinguish ElevenLabs API errors from generic network failures. The API-specific subclasses (BadRequestError, UnauthorizedError, etc.) live in api/errors/ and extend ElevenLabsError.

play / stream (wrapper)

import { play, stream } from "./src/elevenlabs/wrapper";

await play(audioIterable: AsyncIterable<Uint8Array>): Promise<void>;
await stream(audioIterable: AsyncIterable<Uint8Array>): Promise<void>;

Helper functions for consuming the ReadableStream / async iterable returned by TTS calls. play buffers and plays via MPV. stream pipes audio in real time. Both require MPV and ffmpeg at the system level.

Working examples

Scenario - Convert text to speech and play it

Calls the TTS convert endpoint, which returns an async iterable of audio chunks, then plays it via the play helper.

import { ElevenLabsClient, play } from "./src/elevenlabs/index";

const client = new ElevenLabsClient({
  apiKey: process.env.ELEVENLABS_API_KEY,
});

async function main() {
  const audio = await client.textToSpeech.convert("Xb7hH8MSUJpSbSDYk0k2", {
    text: "Hello from the ElevenLabs Node SDK.",
    modelId: "eleven_multilingual_v2",
  });

  await play(audio);
}

main().catch(console.error);

Scenario - Stream TTS audio in real time

Uses the stream endpoint variant to begin playback before the full audio is generated. Suitable for low-latency applications.

import { ElevenLabsClient, stream } from "./src/elevenlabs/index";

const client = new ElevenLabsClient({ apiKey: process.env.ELEVENLABS_API_KEY });

async function speakStreaming(text: string, voiceId: string) {
  const audioStream = await client.textToSpeech.stream(voiceId, {
    text,
    modelId: "eleven_flash_v2_5",
  });

  await stream(audioStream);
}

speakStreaming("This streams in real time.", "JBFqnCBsd6RMkjVDRZzb").catch(console.error);

Scenario - List available voices with retry config

Fetches all voices on the account. Demonstrates per-request options including custom retry count.

import { ElevenLabsClient } from "./src/elevenlabs/index";
import { ElevenLabsError } from "./src/elevenlabs/errors";

const client = new ElevenLabsClient({ apiKey: process.env.ELEVENLABS_API_KEY });

async function listVoices() {
  try {
    const result = await client.voices.search(
      {},
      { maxRetries: 3 }
    );
    console.log("Available voices:", result.voices.map((v: any) => v.name));
  } catch (err) {
    if (err instanceof ElevenLabsError) {
      console.error("API error", err.statusCode, err.message);
    } else {
      throw err;
    }
  }
}

listVoices();

Scenario - Audio isolation

Strips background noise from an uploaded audio file using the audioIsolation resource.

import { ElevenLabsClient } from "./src/elevenlabs/index";
import * as fs from "fs";

const client = new ElevenLabsClient({ apiKey: process.env.ELEVENLABS_API_KEY });

async function isolate(filePath: string) {
  const fileStream = fs.createReadStream(filePath);

  const result = await client.audioIsolation.convert({
    audio: fileStream,
  });

  const out = fs.createWriteStream("isolated.mp3");
  for await (const chunk of result) {
    out.write(chunk);
  }
  out.end();
  console.log("Written to isolated.mp3");
}

isolate("noisy_audio.mp3").catch(console.error);

File walkthrough

• index.ts - Root barrel; re-exports the ElevenLabs namespace, all wrapper helpers, ElevenLabsEnvironment, and top-level error classes. This is the primary import point.
• Client.ts - Concrete ElevenLabsClient class. Initializes all resource sub-clients (textToSpeech, voices, audioIsolation, dubbing, etc.) as properties.
• BaseClient.ts - Shared HTTP configuration and fetch logic inherited by Client.ts.
• environments.ts - Enum of base URL constants (ElevenLabsEnvironment.Production). Extend here if you proxy API calls.
• version.ts - Exports a single version string; used in User-Agent headers.
• exports.ts - Secondary barrel shim; do not import from this directly.
• errors/ - ElevenLabsError and ElevenLabsTimeoutError; the two non-API-specific error classes.
• api/ - Generated layer: all resource clients, typed request/response interfaces, and HTTP-status-specific error subclasses.
• api/resources/ - One sub-directory per API resource (textToSpeech, voices, dubbing, audioIsolation, etc.), each containing a Client.ts and typed request shapes.
• api/errors/ - HTTP-status error classes (BadRequestError, UnauthorizedError, NotFoundError, etc.).
• api/types/ - Shared type definitions used across multiple resources.
• core/ - Low-level HTTP transport, streaming, retry/backoff, and header utilities.
• serialization/ - Encode/decode helpers that sit between resource clients and the wire.
• wrapper/ - Hand-authored helpers (play, stream) not generated by Fern.

Common pitfalls and fixes

• Missing ELEVENLABS_API_KEY: Client silently constructs but every request returns 401; always assert process.env.ELEVENLABS_API_KEY is set before constructing the client.
• play() throws "mpv not found": MPV is a system binary, not an npm package; install it with brew install mpv or apt install mpv and ensure it is on PATH.
• ESM/CJS mismatch: The source targets CommonJS; if your project uses "type": "module" in package.json, set "module": "NodeNext" and "moduleResolution": "NodeNext" in tsconfig.json, or add "type": "commonjs" to the vendored source directory.
• node-fetch version conflict: The source expects node-fetch v2 (CommonJS-compatible); do not install v3+ which is ESM-only, or you will get ERR_REQUIRE_ESM at runtime.
• Streaming responses not consumed: Failing to iterate or pipe the returned async iterable will leave the underlying socket open; always await play(), await stream(), or consume the iterable with a for await loop.
• Retry storms on 429: Default maxRetries is 2; if you share one client instance across many concurrent requests, pass maxRetries: 0 and implement your own rate-limit queue to avoid amplifying 429 responses.

Vibe-coding prompt template

I have vendored the ElevenLabs Node.js SDK source (upstream: @elevenlabs/elevenlabs-js@2.46.0)
into my project under `src/elevenlabs/`. The integration guide is in `USAGE.md`.

Please help me integrate it step by step:

1. Read `USAGE.md` to understand the public API and available exports.
2. Read `src/elevenlabs/index.ts` to confirm what is exported at the root.
3. Read `src/elevenlabs/Client.ts` to see all resource namespaces available on ElevenLabsClient.
4. Add the required npm dependencies (`command-exists`, `node-fetch`, `ws`) to my package.json.
5. Create a singleton client module at `src/lib/elevenlabs.ts` that instantiates ElevenLabsClient
   using `process.env.ELEVENLABS_API_KEY` and exports it for reuse.
6. Wire up the following feature in my project: [DESCRIBE YOUR FEATURE HERE].
7. Add error handling using ElevenLabsError from `src/elevenlabs/errors/`.
8. Show me the final TypeScript files, referencing only exports documented in USAGE.md.

License and credit

The source is derived from the official ElevenLabs SDK. See source/LICENSE if present for the exact license terms. Upstream package: @elevenlabs/elevenlabs-js published by ElevenLabs. Refer to https://elevenlabs.io/docs/api-reference for the full HTTP API reference.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Automation, Utilities & Developer Tools

Free