> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintrust.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# ElevenLabs

> Trace ElevenLabs SDK calls in Braintrust to debug audio generation, evaluate models, and monitor production usage

[ElevenLabs](https://elevenlabs.io/) is a voice AI platform providing text-to-speech and speech-to-text. Braintrust traces ElevenLabs SDK calls, including speech generation, streaming audio, timestamped audio, and transcription.

**TypeScript**

## Setup

Install the Braintrust and `@elevenlabs/elevenlabs-js` packages, then set your API keys. Requires `@elevenlabs/elevenlabs-js` v2.67.0 or later.

**1. Install packages**

```bash pnpm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
pnpm add braintrust @elevenlabs/elevenlabs-js
```

```bash npm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
npm install braintrust @elevenlabs/elevenlabs-js
```

**2. Set environment variables**

```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
BRAINTRUST_API_KEY=<your-braintrust-api-key>
ELEVENLABS_API_KEY=<your-elevenlabs-api-key>

# For organizations on the EU data plane, use https://api-eu.braintrust.dev
# For self-hosted deployments, use your data plane URL
# BRAINTRUST_API_URL=<your-braintrust-api-url>
```

## Auto-instrumentation

To trace ElevenLabs SDK calls without modifying your application code, initialize Braintrust normally, then run your app with Braintrust's import hook to patch the ElevenLabs SDK at runtime.

**1. Initialize Braintrust and call ElevenLabs**

```javascript title="trace-elevenlabs-auto.js" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
import { initLogger } from "braintrust";
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

initLogger({
  projectName: "elevenlabs-example",
  apiKey: process.env.BRAINTRUST_API_KEY,
});

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

const audio = await client.textToSpeech.convert(
  "<voice-id>", // Replace with your ElevenLabs voice ID
  {
    text: "Braintrust traces all your AI calls.",
    modelId: "eleven_flash_v2_5",
  },
);

for await (const chunk of audio) {
  // process audio chunk
}
```

**2. Run with the import hook**

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
node --import braintrust/hook.mjs trace-elevenlabs-auto.js
```

The auto-instrumentation example uses plain JavaScript so `node --import` can run the file directly. The Braintrust APIs work the same in TypeScript projects. Compile your TypeScript to JavaScript and run the compiled file with the import hook, or [run TypeScript directly](https://docs.braintrust.dev/instrument/trace-llm-calls.md#auto-instrumentation) with a TypeScript loader.

> [!NOTE]
>
> If you're using a bundler, see [Trace LLM calls](https://docs.braintrust.dev/instrument/trace-llm-calls.md#auto-instrumentation) for plugin and loader setup.

## Manual instrumentation

To trace ElevenLabs clients manually, wrap them yourself with `wrapElevenLabs()`. Use this when you want to instrument specific clients individually rather than all of them globally.

```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
import { initLogger, wrapElevenLabs } from "braintrust";
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

initLogger({
  projectName: "elevenlabs-example",
  apiKey: process.env.BRAINTRUST_API_KEY,
});

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

const audio = await client.textToSpeech.convert(
  "<voice-id>", // Replace with your ElevenLabs voice ID
  {
    text: "Braintrust traces all your AI calls.",
    modelId: "eleven_flash_v2_5",
  },
);

for await (const chunk of audio) {
  // process audio chunk
}
```

## What Braintrust traces

Braintrust patches the `@elevenlabs/elevenlabs-js` SDK and creates an LLM-typed span per call:

* Text-to-speech spans (`elevenlabs.textToSpeech.convert`): input text, voice ID, and model as metadata. Generated audio is attached as a Braintrust attachment with content type `audio/mpeg`.
* Streaming text-to-speech spans (`elevenlabs.textToSpeech.stream`): same as above, with `time_to_first_token` captured for the first audio chunk.
* Timestamped text-to-speech spans (`elevenlabs.textToSpeech.convertWithTimestamps`, `elevenlabs.textToSpeech.streamWithTimestamps`): same fields as their non-timestamped counterparts, including word-level timing data.
* Transcription spans (`elevenlabs.speechToText.convert`): audio input and model as metadata. Transcript text is captured as output.
* Errors captured on every call.

> [!NOTE]
>
> Webhook transcription and Speech Engine sessions are not instrumented.

## Resources

* [ElevenLabs JavaScript SDK](https://github.com/elevenlabs/elevenlabs-js).
* [ElevenLabs API reference](https://elevenlabs.io/docs/api-reference).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.