ElevenLabs JS

https://github.com/elevenlabs/elevenlabs-js
Admin
The official Node.js SDK for ElevenLabs, enabling developers to integrate lifelike AI voices into...
Tokens:249,484
Snippets:1,825
Trust Score:9.5
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Full session example

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/_autodocs/api-reference/RealtimeConnection.md

Complete example of connecting to the realtime speech-to-text API, registering event listeners for session start, partial and committed transcripts, and errors, then sending audio chunks and committing. Demonstrates the on, send, commit, and close methods.

```typescript
import { AudioFormat, RealtimeEvents } from "@elevenlabs/elevenlabs-js";

const connection = await client.speechToText.realtime.connect({
    modelId: "scribe_v2_realtime",
    audioFormat: AudioFormat.PCM_16000,
    sampleRate: 16000,
});

connection.on(RealtimeEvents.SESSION_STARTED, ({ session_id, config }) => {
    console.log("session", session_id, config.model_id);
});

connection.on(RealtimeEvents.PARTIAL_TRANSCRIPT, (data) => process.stdout.write(data.text));

connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT, (data) => {
    console.log("\nfinal:", data.text);
    connection.close();
});

// Handle errors — payload is either a server message or a native Error
connection.on(RealtimeEvents.ERROR, (error) => {
    if ("message_type" in error) {
        console.error("server error:", error.message_type, error.error);
    } else {
        console.error("websocket error:", error.message);
    }
});

// Feed audio chunks
for (const chunk of audioChunks) {
    connection.send({ audioBase64: chunk });
}
connection.commit();
```

--------------------------------

### Play audio with play()

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/_autodocs/api-reference/PlayAndStream.md

Example of using the play function with the ElevenLabsClient to convert text to speech and play the audio. Requires ffplay from ffmpeg to be installed.

```ts
import { ElevenLabsClient, play } from "@elevenlabs/elevenlabs-js";

const audio = await client.textToSpeech.convert("Xb7hH8MSUJpSbSDYk0k2", {
    text: "Hello! 你好!",
    modelId: "eleven_multilingual_v2",
});

await play(audio); // requires ffplay (brew install ffmpeg)
```

--------------------------------

### Conversation example with startSession

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/_autodocs/api-reference/Conversation.md

Creates a `Conversation` instance with an agent ID, authentication, client, audio interface, and callbacks, then starts the session. The `startSession()` method resolves on WebSocket open.

```typescript
const conversation = new Conversation({
    agentId: "agent_id",
    requiresAuth: true,
    client: elevenlabs,
    audioInterface: new DefaultAudioInterface(),
    callbackUserTranscript: (t) => console.log("user:", t),
    callbackAgentResponse: (r) => console.log("agent:", r),
});

await conversation.startSession();
```

--------------------------------

### Example — full session

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/_autodocs/api-reference/RealtimeConnection.md

A complete example demonstrating how to connect, listen to events, send audio chunks, and close the connection.

```APIDOC
## Example — full session

### Description
A complete example demonstrating how to connect, listen to events, send audio chunks, and close the connection.

### Code
```ts
import { AudioFormat, RealtimeEvents } from "@elevenlabs/elevenlabs-js";

const connection = await client.speechToText.realtime.connect({
    modelId: "scribe_v2_realtime",
    audioFormat: AudioFormat.PCM_16000,
    sampleRate: 16000,
});

connection.on(RealtimeEvents.SESSION_STARTED, ({ session_id, config }) => {
    console.log("session", session_id, config.model_id);
});

connection.on(RealtimeEvents.PARTIAL_TRANSCRIPT, (data) => process.stdout.write(data.text));

connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT, (data) => {
    console.log("\nfinal:", data.text);
    connection.close();
});

// Handle errors — payload is either a server message or a native Error
connection.on(RealtimeEvents.ERROR, (error) => {
    if ("message_type" in error) {
        console.error("server error:", error.message_type, error.error);
    } else {
        console.error("websocket error:", error.message);
    }
});

// Feed audio chunks
for (const chunk of audioChunks) {
    connection.send({ audioBase64: chunk });
}
connection.commit();
```
```

--------------------------------

### Convert a chapter using client.studio.projects.chapters.convert

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Starts conversion of a specific chapter. Requires a project_id and chapter_id, both strings. The example uses placeholder IDs.

```typescript
await client.studio.projects.chapters.convert("21m00Tcm4TlvDq8ikWAM", "21m00Tcm4TlvDq8ikWAM");
```

--------------------------------

### SpeechEngineServer.start()

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/_autodocs/api-reference/SpeechEngine.md

Starts the WebSocket server. Throws an error if already started or if no API key is available unless disableAuth is set.

```APIDOC
## `SpeechEngineServer.start()`

### Description
Starts the WebSocket server. Throws `Error("Server is already started")` if already started, and throws an `Error` if no API key is available unless `disableAuth` is set. When `disableAuth: true` it logs a `console.warn` and accepts any connection.

### Method
start

### Signature
`start(): void`

### Parameters
None

### Returns
void

### Errors
- Throws `Error("Server is already started")` if already started.
- Throws `Error` if no API key is available and `disableAuth` is not set.
```

--------------------------------

### Stream audio with stream()

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/_autodocs/api-reference/PlayAndStream.md

Example of using the stream function with the ElevenLabsClient to stream text-to-speech audio. Requires mpv to be installed.

```ts
import { stream } from "@elevenlabs/elevenlabs-js";

const audioStream = await client.textToSpeech.stream("JBFqnCBsd6RMkjVDRZzb", {
    text: "This is a... streaming voice",
    modelId: "eleven_multilingual_v2",
});

await stream(audioStream); // requires mpv (brew install mpv)
```

--------------------------------

### startSession()

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/_autodocs/api-reference/Conversation.md

Opens the WebSocket, sends conversation_initiation_client_data, and starts the audio interface. Resolves on WebSocket open and throws an error if the session is already started.

```APIDOC
## startSession()

### Description
Opens the WebSocket, sends conversation_initiation_client_data, and starts the audio interface. Resolves on WebSocket open and throws an error if the session is already started.

### Method
`public async startSession(): Promise<void>`

### Parameters
None

### Returns
`Promise<void>` - Resolves when the WebSocket is open.

### Errors
- Throws `Error("Session already started")` if the session is already running.
```

--------------------------------

### Example: convertWithTimestamps usage

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/_autodocs/api-reference/TextToSpeechClient.md

Example call to `convertWithTimestamps` with a voice ID, text, model, and output format, then iterating over the character alignment arrays to log each character and its start time.

```typescript
const result = await client.textToSpeech.convertWithTimestamps("21m00Tcm4TlvDq8ikWAM", {
    text: "This is a test for the API of ElevenLabs.",
    modelId: "eleven_multilingual_v2",
    outputFormat: "pcm_16000",
});

// result.alignment.characters — character-level alignment
const chars = result.alignment?.characters ?? [];
const starts = result.alignment?.characterStartTimesSeconds ?? [];
for (let i = 0; i < chars.length; i++) {
    console.log(chars[i], starts[i]);
}
```

--------------------------------

### Create a new Productions order

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Creates a new Productions order in the workspace. The order starts in the open state and can be configured with items before submission. The example passes sandbox: false.

```typescript
await client.productions.orders.create({
    sandbox: false
});
```

--------------------------------

### compose example

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/_autodocs/api-reference/Music.md

Example of using the compose method to generate music from a prompt. The returned ReadableStream can be piped or saved.

```typescript
const audioStream = await client.music.compose({
    prompt: "upbeat electronic dance music",
    musicLengthMs: 60000,
});
// pipe / save the ReadableStream
```

--------------------------------

### SpeechEngineServer usage example

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/_autodocs/api-reference/SpeechEngine.md

Creates a SpeechEngine.Server instance with a port, engineId, API key from environment, and an onTranscript callback that sends a response via session.sendResponse(). Calls start() and later stop().

```typescript
const server = new SpeechEngine.Server({
    port: 3001,
    engineId: "seng_123",
    apiKey: process.env.ELEVENLABS_API_KEY,
    async onTranscript(transcript, signal, session) {
        session.sendResponse(await generateLLMResponse(transcript, { signal }));
    },
});
server.start();
// later: await server.stop();
```

--------------------------------

### Microphone/audio-buffer streaming example

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/_autodocs/api-reference/ScribeRealtime.md

Connects with `modelId: "scribe_v2_realtime"`, PCM 16000 audio format, and sample rate 16000. Attaches event listeners for session started, committed transcript, and error, then sends audio data.

```typescript
import { AudioFormat, RealtimeEvents } from "@elevenlabs/elevenlabs-js";

const connection = await client.speechToText.realtime.connect({
    modelId: "scribe_v2_realtime",
    audioFormat: AudioFormat.PCM_16000,
    sampleRate: 16000,
});

connection.on(RealtimeEvents.SESSION_STARTED, () => console.log("started"));
connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT, (data) => {
    console.log(data.text);
});
connection.on(RealtimeEvents.ERROR, (e) => console.error(e));

connection.send({ audioBase64: pcmBase64, sampleRate: 16000 });
```

--------------------------------

### fetch() example usage

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/_autodocs/api-reference/ElevenLabsClient.md

Example of making a raw passthrough request to an endpoint not yet in the SDK. Uses client.fetch with a relative path, method, body, headers, and a timeout override.

```typescript
// Raw passthrough to an endpoint not yet in the SDK
const res = await client.fetch("v1/custom-endpoint", {
    method: "POST",
    body: JSON.stringify({ foo: "bar" }),
    headers: { "Content-Type": "application/json" },
}, {
    timeoutInSeconds: 10,
});

const data = await res.json();
```

--------------------------------

### convert example

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/_autodocs/api-reference/TextToSpeechClient.md

Example of calling `client.textToSpeech.convert` with a voice ID and request body, specifying model, output format, and voice settings.

```typescript
const audio = await client.textToSpeech.convert("Xb7hH8MSUJpSbSDYk0k2", {
    text: "Hello world",
    modelId: "eleven_multilingual_v2",
    outputFormat: "mp3_44100_128",
    voiceSettings: { stability: 0.5, similarityBoost: 0.75 },
});
```

--------------------------------

### Get Audio Native player settings with client.audioNative.getSettings()

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Get player settings for a specific project. Requires the project ID as a string.

```typescript
await client.audioNative.getSettings("21m00Tcm4TlvDq8ikWAM");
```

--------------------------------

### Get signed URL for authorized conversation

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Calls `client.conversationalAi.conversations.getSignedUrl` to obtain a signed URL to start a conversation with an agent that requires authorization. The example passes an `agentId` and optional parameters like `includeConversationId`, `branchId`, `versionId`, `environment`, and `debugEventsRequest`.

```typescript
await client.conversationalAi.conversations.getSignedUrl({
    agentId: "agent_3701k3ttaq12ewp8b7qv5rfyszkz",
    includeConversationId: true,
    branchId: "branch_id",
    versionId: "version_id",
    environment: "environment",
    debugEventsRequest: true
});
```

--------------------------------

### share usage example

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/_autodocs/api-reference/VoicesClient.md

Example of using the `share` method to add a shared voice to the user's collection, providing the public user ID, voice ID, and a new name.

```typescript
const res = await client.voices.share(
    "63e06b7e7cafdc46be4d2e0b3f045940231ae058d508589653d74d1265a574ca",
    "21m00Tcm4TlvDq8ikWAM",
    { newName: "John Smith" },
);
```

--------------------------------

### GET /v1/conversations/get-signed-url

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Get a signed URL to start a conversation with an agent that requires authorization.

```APIDOC
## GET /v1/conversations/get-signed-url

### Description
Get a signed url to start a conversation with an agent that requires authorization.

### Method
GET

### Endpoint
/v1/conversations/get-signed-url

### Parameters
#### Query Parameters
- **agent_id** (string) - Required - The ID of the agent.
- **include_conversation_id** (boolean) - Optional - Whether to include the conversation ID in the signed URL.
- **branch_id** (string) - Optional - The branch ID.
- **version_id** (string) - Optional - The version ID.
- **environment** (string) - Optional - The environment.
- **debug_events_request** (boolean) - Optional - Whether to include debug events.

### Request Example
```typescript
await client.conversationalAi.conversations.getSignedUrl({
    agentId: "agent_3701k3ttaq12ewp8b7qv5rfyszkz",
    includeConversationId: true,
    branchId: "branch_id",
    versionId: "version_id",
    environment: "environment",
    debugEventsRequest: true
});
```

### Response
#### Success Response (200)
- **signed_url** (string) - The signed URL.

#### Response Example
```json
{
  "signed_url": "https://..."
}
```
```

--------------------------------

### Get agent test folder by ID

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Gets an agent test folder by its ID, including its folder path. The `folder_id` is a string, typically starting with 'tfld_'.

```typescript
await client.conversationalAi.tests.folders.get("tfld_7301khxdkycse5f88fzjdtrterzm");
```

--------------------------------

### AudioInterface.start

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/_autodocs/api-reference/Conversation.md

Starts the audio interface, providing an input callback for audio buffers.

```APIDOC
## AudioInterface.start

### Description
Starts the audio interface, providing an input callback for audio buffers.

### Method
start

### Signature
`abstract start(inputCallback: (audio: Buffer) => void): void`

### Parameters
- **inputCallback** (function) - Required - Callback that receives audio buffers (16-bit PCM mono at 16 kHz).
```

--------------------------------

### client.studio.projects.convert()

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Starts conversion of a Studio project and all of its chapters.

```APIDOC
## client.studio.projects.convert(project_id)

### Description
Starts conversion of a Studio project and all of its chapters.

### Method
POST

### Endpoint
/v1/studio/{project_id}/convert

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project to be used. You can use the [List projects](/docs/api-reference/studio/get-projects) endpoint to list all the available projects.

#### Request Options
- **requestOptions** (ProjectsClient.RequestOptions) - Optional - Request options.

### Request Example
```typescript
await client.studio.projects.convert("21m00Tcm4TlvDq8ikWAM");
```

### Response
#### Success Response (200)
- **project** (object) - The converted project.

#### Response Example
```json
{
  "project": {}
}
```
```

--------------------------------

### Get content of a knowledge base document

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Retrieves the entire content of a document from the knowledge base. The example uses a placeholder `documentation_id`.

```typescript
await client.conversationalAi.knowledgeBase.documents.getContent("documentation_id");
```

--------------------------------

### Example: create and attach a speech engine

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/_autodocs/api-reference/SpeechEngine.md

Shows how to create a speech engine with a WebSocket URL and attach it to an HTTP server, handling transcripts with a callback that sends a response.

```typescript
const engine = await client.speechEngine.create({
    name: "My engine",
    speechEngine: { wsUrl: "wss://your-server.com/ws" },
});
engine.attach(httpServer, "/api/speech-engine/ws", {
    async onTranscript(transcript, signal, session) {
        session.sendResponse(await llm.generate(transcript, { signal }));
    },
});
```

--------------------------------

### client.studio.projects.create()

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Creates a new Studio project, it can be either initialized as blank, from a document or from a URL.

```APIDOC
## client.studio.projects.create({ ...params })

### Description
Creates a new Studio project, it can be either initialized as blank, from a document or from a URL.

### Method
POST

### Endpoint
/v1/studio

### Parameters
#### Request Body
- **name** (string) - Required - The name of the project.

#### Request Options
- **requestOptions** (ProjectsClient.RequestOptions) - Optional - Request options.

### Request Example
```typescript
await client.studio.projects.create({
    name: "name"
});
```

### Response
#### Success Response (200)
- **project** (object) - The created project.

#### Response Example
```json
{
  "project": {}
}
```
```

--------------------------------

### Create image generation with client.flows.image.create

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Starts an image generation using the selected model. The example uses the bytedance-seedream-5-lite model with a prompt describing a corgi on a beach.

```typescript
await client.flows.image.create({
    modelId: "bytedance-seedream-5-lite",
    prompt: "A corgi in a tiny lifeguard chair on a sunlit beach at golden hour, photorealistic"
});
```

--------------------------------

### Create a podcast with client.studio.createPodcast

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Creates and auto-converts a podcast project. The LLM cost is covered by ElevenLabs, but audio generation is charged. Requires a model ID, mode configuration with host and guest voice IDs, and a source (text or other).

```typescript
await client.studio.createPodcast({
    modelId: "eleven_multilingual_v2",
    mode: {
        type: "conversation",
        conversation: {
            hostVoiceId: "aw1NgEzBg83R7vgmiJt6",
            guestVoiceId: "aw1NgEzBg83R7vgmiJt7"
        }
    },
    source: {
        type: "text",
        text: "This is a test podcast."
    }
});
```

--------------------------------

### Create a music finetune with client.music.finetunes.create

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Creates a new music finetune. The request requires a name and a primary genre.

```typescript
await client.music.finetunes.create({
    name: "name",
    primaryGenre: "primary_genre"
});
```

--------------------------------

### Get an agent with client.conversationalAi.agents.get

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Retrieves the configuration for an agent by its ID. The example uses a sample agent ID and includes optional `versionId` and `branchId` parameters. Returns a `GetAgentResponseModel`.

```typescript
await client.conversationalAi.agents.get("agent_3701k3ttaq12ewp8b7qv5rfyszkz", {
    versionId: "version_id",
    branchId: "branch_id"
});
```

--------------------------------

### Create Audio Native project with client.audioNative.create()

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Creates an Audio Native enabled project, optionally starts conversion, and returns project ID and embeddable HTML snippet. Requires a request object with a 'name' property.

```typescript
await client.audioNative.create({
    name: "name"
});
```

--------------------------------

### Get agents depending on a knowledge base document

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Retrieves a list of agents that depend on a specific knowledge base document. The example includes `dependentType`, `pageSize`, and `cursor` parameters.

```typescript
await client.conversationalAi.knowledgeBase.documents.getAgents("21m00Tcm4TlvDq8ikWAM", {
    dependentType: "direct",
    pageSize: 1,
    cursor: "cursor"
});
```

--------------------------------

### client.conversationalAi.mcpServers.create()

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Creates a new MCP server configuration in the workspace.

```APIDOC
## client.conversationalAi.mcpServers.create({ ...params })

### Description
Create a new MCP server configuration in the workspace.

### Method
create

### Endpoint
client.conversationalAi.mcpServers.create({ ...params })

### Parameters
- **request** (ElevenLabs.conversationalAi.McpServerRequestModel) - Required - The request model containing the MCP server configuration.
- **requestOptions** (McpServersClient.RequestOptions) - Optional - Request options.

### Request Example
```typescript
await client.conversationalAi.mcpServers.create({
    config: {
        url: "url",
        name: "name"
    }
});
```

### Response
#### Success Response
- **result** (ElevenLabs.McpServerResponseModel) - The created MCP server configuration.

```

--------------------------------

### Create a music composition plan with client.music.compositionPlan.create

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Creates a composition plan for music generation. This endpoint does not cost credits but is subject to rate limiting based on your tier. The request requires a 'prompt' string.

```typescript
await client.music.compositionPlan.create({
    prompt: "prompt"
});
```

--------------------------------

### Get agents depending on multiple knowledge base documents

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Retrieves a list of agents that depend on any of the given knowledge base documents. The example includes `dependentType`, `pageSize`, `cursor`, and `documentIds` parameters.

```typescript
await client.conversationalAi.knowledgeBase.documents.getBulkAgents({
    dependentType: "direct",
    pageSize: 1,
    cursor: "cursor",
    documentIds: ["21m00Tcm4TlvDq8ikWAM", "31m00Tcm4TlvDq8ikWBM"]
});
```

--------------------------------

### Create Studio Project

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Creates a new Studio project, either blank, from a document, or from a URL. Requires a name parameter.

```typescript
await client.studio.projects.create({
    name: "name"
});
```

--------------------------------

### Get WebRTC session token

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Calls `client.conversationalAi.conversations.getWebrtcToken` to obtain a WebRTC session token for real-time communication. The example includes an `agentId` and optional parameters like `participantName`, `branchId`, `versionId`, `environment`, and `debugEventsRequest`.

```typescript
await client.conversationalAi.conversations.getWebrtcToken({
    agentId: "agent_3701k3ttaq12ewp8b7qv5rfyszkz",
    participantName: "participant_name",
    branchId: "branch_id",
    versionId: "version_id",
    environment: "environment",
    debugEventsRequest: true
});
```

--------------------------------

### get usage

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Fetch the transcript for one of the languages in a dub. The `dubbing_id` is the ID of the dubbing project, and `language_code` is the ISO-693 language code; use 'source' to fetch the transcript of the original media. The `format_type` parameter is set to 'srt' in this example.

```typescript
await client.dubbing.transcripts.get("dubbing_id", "source", "srt");
```

--------------------------------

### List chapter snapshots with client.studio.projects.chapters.snapshots.list

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Gets information about all snapshots of a chapter. Each snapshot can be downloaded as audio, and a snapshot is automatically created whenever a chapter is converted. Requires the project ID and chapter ID.

```typescript
await client.studio.projects.chapters.snapshots.list("21m00Tcm4TlvDq8ikWAM", "21m00Tcm4TlvDq8ikWAM");
```

--------------------------------

### client.studio.projects.list()

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Returns a list of your Studio projects with metadata.

```APIDOC
## client.studio.projects.list()

### Description
Returns a list of your Studio projects with metadata.

### Method
GET

### Endpoint
/v1/studio

### Parameters
#### Request Options
- **requestOptions** (ProjectsClient.RequestOptions) - Optional - Request options.

### Request Example
```typescript
await client.studio.projects.list();
```

### Response
#### Success Response (200)
- **projects** (array) - List of projects.

#### Response Example
```json
{
  "projects": []
}
```
```

--------------------------------

### Basic ElevenLabsClient instantiation

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/_autodocs/configuration.md

Creates a basic ElevenLabsClient instance using the API key from the environment variable ELEVENLABS_API_KEY.

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

--------------------------------

### List conversational AI users

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Calls the `client.conversationalAi.users.list` method to get distinct users from conversations with pagination. Accepts parameters like agent ID, branch ID, call start times, search, page size, sort options, and cursor.

```typescript
await client.conversationalAi.users.list({
    agentId: "agent_id",
    branchId: "branch_id",
    callStartBeforeUnix: 1,
    callStartAfterUnix: 1,
    search: "search",
    pageSize: 1,
    sortBy: "last_contact_unix_secs",
    sortDirection: "asc",
    cursor: "cursor"
});
```

--------------------------------

### Get or create RAG indexes with client.conversationalAi.knowledgeBase.getOrCreateRagIndexes

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Retrieves and/or creates RAG indexes for multiple knowledge base documents in a single request. Maximum 100 items per request. The example passes an items array with documentId, createIfMissing, and model.

```typescript
await client.conversationalAi.knowledgeBase.getOrCreateRagIndexes({
    items: [{
            documentId: "document_id",
            createIfMissing: true,
            model: "e5_mistral_7b_instruct"
        }]
});
```

--------------------------------

### client.music.finetunes.create

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Create a new music finetune with a name and primary genre.

```APIDOC
## client.music.finetunes.create

### Description
Create a new music finetune.

### Method
create

### Endpoint
client.music.finetunes.create

### Parameters
#### Request Body
- **name** (string) - Required - The name of the finetune.
- **primaryGenre** (string) - Required - The primary genre of the finetune.

### Request Example
```typescript
await client.music.finetunes.create({
    name: "name",
    primaryGenre: "primary_genre"
});
```

### Response
#### Success Response
- **MusicFinetuneResponseModel** - The created music finetune.

```

--------------------------------

### Create dubbing project with client.dubbing.project.create

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Creates a dubbing project from an uploaded file or source URL. Returns before the source is fetched; the project starts 'queued' and becomes 'ready' after transcription. Incurs a minimum charge for one language. Recommended to pass webhook_ids for notifications.

```typescript
await client.dubbing.project.create({
    sourceUrl: "https://example.com/promo.mp4",
    sourceLanguage: "en",
    reference: "Q3 marketing video"
});
```

--------------------------------

### Install dependencies with yarn install

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/CONTRIBUTING.md

Installs project dependencies using yarn. Requires Node.js 20 or higher and the yarn package manager.

```bash
yarn install
```

--------------------------------

### client.flows.templates.runs.create

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Starts a run of a flows template, with options to pin a version, set inputs, and configure a webhook.

```APIDOC
## client.flows.templates.runs.create(template_id, { ...params })

### Description
Start a run of a flows template. Pass `version_id` to pin a snapshot, or omit it / pass `latest` to run the latest published version. Set input values under `inputs`, keyed by input port id. The response is the run in its initial state, with every output already listed under its port id in `outputs`. Include `webhook` to receive a `flows_template_run` event carrying the finished run once its `status` is `completed` or `failed`; this is the recommended way to wait. Without one, fetch `GET /v1/flows/templates/{template_id}/runs/{run_id}` at a modest interval until the `status` is terminal.

### Method
create

### Endpoint
client.flows.templates.runs.create

### Parameters
#### Path Parameters
- **template_id** (string) - Required - The ID of the template, as shown in the ElevenLabs app or by `GET /v1/flows/templates`.

#### Request Body
- **inputs** (object) - Required - Input values keyed by input port id.
- **versionId** (string) - Optional - Version ID to pin a snapshot, or `latest` to run the latest published version.
- **webhook** (object) - Optional - Webhook configuration to receive a `flows_template_run` event.

### Request Example
```typescript
await client.flows.templates.runs.create("template_id", {
    inputs: {
        "prompt": "a corgi on a surfboard",
        "reference": {
            type: "asset",
            assetId: "5xM2KqOnZyce22SPZ9d4"
        }
    },
    versionId: "latest",
    webhook: {
        type: "all"
    }
});
```

### Response
#### Success Response
- **ElevenLabs.TemplateRunResponse** - The run in its initial state, with every output listed under its port id in `outputs`.
```

--------------------------------

### GET /v1/convai/tests/invocations/{test_invocation_id}

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Gets a test invocation by ID.

```APIDOC
## [GET] /v1/convai/tests/invocations/{test_invocation_id}

### Description
Gets a test invocation by ID.

### Method
GET

### Endpoint
/v1/convai/tests/invocations/{test_invocation_id}

### Parameters
#### Path Parameters
- **test_invocation_id** (string) - Required - The id of a test invocation. This is returned when tests are run.

### Request Example
```typescript
await client.conversationalAi.tests.invocations.get("test_invocation_id");
```

### Response
#### Success Response (200)
- **GetTestSuiteInvocationResponseModel** - The response model containing the test invocation details.

#### Response Example
```json
{
  "test_invocation": {}
}
```
```

--------------------------------

### POST /v1/studio/projects/{project_id}/chapters/{chapter_id}/convert

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Starts conversion of a specific chapter.

```APIDOC
## [POST] /v1/studio/projects/{project_id}/chapters/{chapter_id}/convert

### Description
Starts conversion of a specific chapter.

### Method
POST

### Endpoint
/v1/studio/projects/{project_id}/chapters/{chapter_id}/convert

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project to be used. You can use the [List projects](/docs/api-reference/studio/get-projects) endpoint to list all the available projects.
- **chapter_id** (string) - Required - The ID of the chapter to be used. You can use the [List project chapters](/docs/api-reference/studio/get-chapters) endpoint to list all the available chapters.

### Request Example
```typescript
await client.studio.projects.chapters.convert("21m00Tcm4TlvDq8ikWAM", "21m00Tcm4TlvDq8ikWAM");
```

### Response
#### Success Response (200)
- **ConvertChapterResponseModel** - The response model for the conversion operation.

```

--------------------------------

### get(tag_id, requestOptions)

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Get a conversation tag by ID.

```APIDOC
## get(tag_id, requestOptions)

### Description
Get a conversation tag by ID.

### Method
SDK Method

### Endpoint
client.conversationalAi.conversations.tags.get

### Parameters
#### Path Parameters
- **tag_id** (string) - Required - The ID of the tag.

### Request Example
```typescript
await client.conversationalAi.conversations.tags.get("tag_id");
```

### Response
#### Success Response
- Returns ElevenLabs.ConversationTagResponseModel.
```

--------------------------------

### client.conversationalAi.mcpServers.list()

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Retrieves all MCP server configurations available in the workspace.

```APIDOC
## client.conversationalAi.mcpServers.list()

### Description
Retrieve all MCP server configurations available in the workspace.

### Method
list

### Endpoint
client.conversationalAi.mcpServers.list()

### Parameters
- **requestOptions** (McpServersClient.RequestOptions) - Optional - Request options.

### Request Example
```typescript
await client.conversationalAi.mcpServers.list();
```

### Response
#### Success Response
- **result** (ElevenLabs.McpServersResponseModel) - The list of MCP server configurations.

```

--------------------------------

### GET client.conversationalAi.agents.procedures.drafts.get

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Get user's draft for a procedure.

```APIDOC
## GET client.conversationalAi.agents.procedures.drafts.get

### Description
Get user's draft for a procedure.

### Method
GET

### Endpoint
client.conversationalAi.agents.procedures.drafts.get

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - Agent ID to get the procedure draft from
- **branch_id** (string) - Required - Branch ID to get the procedure draft from
- **procedure_id** (string) - Required - The procedure ID

#### Request Options
- **requestOptions** (DraftsClient.RequestOptions) - Optional - Request options

### Request Example
```typescript
await client.conversationalAi.agents.procedures.drafts.get("agent_3701k3ttaq12ewp8b7qv5rfyszkz", "agtbranch_0901k4aafjxxfxt93gd841r7tv5t", "agtprc_6qbpwdq8n01bxhk44bgjy6f10ck3");
```

### Response
#### Success Response
- **ElevenLabs.ProcedureDraftResponseModel** - The procedure draft response model
```

--------------------------------

### GET /v1/convai/users

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Get distinct users from conversations with pagination.

```APIDOC
## GET /v1/convai/users

### Description
Get distinct users from conversations with pagination.

### Method
GET

### Endpoint
/v1/convai/users

### Parameters
#### Query Parameters
- **agentId** (string) - Optional - Agent ID.
- **branchId** (string) - Optional - Branch ID.
- **callStartBeforeUnix** (number) - Optional - Filter by call start before Unix timestamp.
- **callStartAfterUnix** (number) - Optional - Filter by call start after Unix timestamp.
- **search** (string) - Optional - Search query.
- **pageSize** (number) - Optional - Number of items per page.
- **sortBy** (string) - Optional - Sort field.
- **sortDirection** (string) - Optional - Sort direction.
- **cursor** (string) - Optional - Cursor for pagination.

### Request Example
```typescript
await client.conversationalAi.users.list({
    agentId: "agent_id",
    branchId: "branch_id",
    callStartBeforeUnix: 1,
    callStartAfterUnix: 1,
    search: "search",
    pageSize: 1,
    sortBy: "last_contact_unix_secs",
    sortDirection: "asc",
    cursor: "cursor"
});
```

### Response
#### Success Response (200)
- **items** (array) - List of users.
- **nextCursor** (string) - Cursor for next page.

#### Response Example
```json
{
  "items": [],
  "nextCursor": "string"
}
```
```

--------------------------------

### POST /v1/music/composition-plan

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/_autodocs/endpoints.md

Creates a composition plan for music generation. This is a nested endpoint under client.music.compositionPlan.create.

```APIDOC
## POST /v1/music/composition-plan

### Description
Creates a composition plan for music generation. This is a nested endpoint under client.music.compositionPlan.create.

### Method
POST

### Endpoint
/v1/music/composition-plan

### Parameters
#### Request Body
- (not specified in source) - Required - The request body for creating a composition plan.

### Response
#### Success Response
- (not specified in source)

```

--------------------------------

### GET /v1/workspace/resources/{resource_id}

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Gets the metadata of a workspace resource by its ID.

```APIDOC
## GET /v1/workspace/resources/{resource_id}

### Description
Gets the metadata of a resource by ID.

### Method
GET

### Endpoint
/v1/workspace/resources/{resource_id}

### Parameters
#### Path Parameters
- **resource_id** (string) - Required - The ID of the target resource.

#### Query Parameters
- **resourceType** (string) - Required - The type of the resource (e.g., "voice").

### Request Example
```typescript
await client.workspace.resources.get("resource_id", {
    resourceType: "voice"
});
```

### Response
#### Success Response (200)
- **resource** (ElevenLabs.ResourceMetadataResponseModel) - The metadata of the resource.

#### Response Example
```json
{
  "resource": {}
}
```
```

--------------------------------

### URL streaming with ffmpeg example

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/_autodocs/api-reference/ScribeRealtime.md

Connects using a URL. ffmpeg is spawned automatically to convert the source to 16 kHz mono PCM. Requires ffmpeg in PATH.

```typescript
const connection = await client.speechToText.realtime.connect({
    modelId: "scribe_v2_realtime",
    url: "https://example.com/stream.mp3", // ffmpeg converts to 16kHz mono PCM
});
```

--------------------------------

### GET /v1/conversations/get-webrtc-token

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Get a WebRTC session token for real-time communication.

```APIDOC
## GET /v1/conversations/get-webrtc-token

### Description
Get a WebRTC session token for real-time communication.

### Method
GET

### Endpoint
/v1/conversations/get-webrtc-token

### Parameters
#### Query Parameters
- **agent_id** (string) - Required - The ID of the agent.
- **participant_name** (string) - Optional - The name of the participant.
- **branch_id** (string) - Optional - The branch ID.
- **version_id** (string) - Optional - The version ID.
- **environment** (string) - Optional - The environment.
- **debug_events_request** (boolean) - Optional - Whether to include debug events.

### Request Example
```typescript
await client.conversationalAi.conversations.getWebrtcToken({
    agentId: "agent_3701k3ttaq12ewp8b7qv5rfyszkz",
    participantName: "participant_name",
    branchId: "branch_id",
    versionId: "version_id",
    environment: "environment",
    debugEventsRequest: true
});
```

### Response
#### Success Response (200)
- **token** (string) - The WebRTC session token.

#### Response Example
```json
{
  "token": "..."
}
```
```

--------------------------------

### client.studio.createPodcast({ ...params }) -> ElevenLabs.PodcastProjectResponseModel

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Create and auto-convert a podcast project. Currently, the LLM cost is covered by us but you will still be charged for the audio generation. In the future, you will be charged for both the LLM and audio generation costs.

```APIDOC
## client.studio.createPodcast({ ...params }) -> ElevenLabs.PodcastProjectResponseModel

### Description
Create and auto-convert a podcast project. Currently, the LLM cost is covered by us but you will still be charged for the audio generation. In the future, you will be charged for both the LLM and audio generation costs.

### Method
POST

### Endpoint
/studio/podcasts

### Parameters
#### Request Body
- **modelId** (string) - Required - The model ID to use for the podcast
- **mode** (object) - Required - The mode of the podcast (conversation or other types)
- **source** (object) - Required - The source content for the podcast

### Request Example
```typescript
await client.studio.createPodcast({
    modelId: "eleven_multilingual_v2",
    mode: {
        type: "conversation",
        conversation: {
            hostVoiceId: "aw1NgEzBg83R7vgmiJt6",
            guestVoiceId: "aw1NgEzBg83R7vgmiJt7"
        }
    },
    source: {
        type: 
```

--------------------------------

### get

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Gets an agent test folder by ID, including its folder path.

```APIDOC
## get

### Description
Gets an agent test folder by ID, including its folder path.

### Method
GET

### Endpoint
/v1/convai/agent-testing/folders/{folder_id}

### Parameters
#### Path Parameters
- **folder_id** (string) - Required - The folder ID.

### Request Example
```typescript
await client.conversationalAi.tests.folders.get("tfld_7301khxdkycse5f88fzjdtrterzm");
```

### Response
#### Success Response (200)
- **ElevenLabs.GetAgentTestFolderResponseModel** - The folder details including its path.

```

--------------------------------

### GET /v1/convai/phone-numbers/{phone_number_id}/sip-messages

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Get SIP messages for a phone number.

```APIDOC
## GET /v1/convai/phone-numbers/{phone_number_id}/sip-messages

### Description
Get SIP messages for a phone number.

### Method
GET

### Endpoint
/v1/convai/phone-numbers/{phone_number_id}/sip-messages

### Parameters
#### Path Parameters
- **phone_number_id** (string) - Required - The phone number ID. This is returned when a phone number is imported.

#### Query Parameters
- **pageSize** (number) - Optional - The number of results to return per page.
- **cursor** (string) - Optional - Pagination cursor.

### Request Example
```typescript
await client.conversationalAi.phoneNumbers.getSipMessages("TeaqRRdTcIfIu2i7BYfT", {
    pageSize: 1,
    cursor: "cursor"
});
```

### Response
#### Success Response (200)
- Returns `ElevenLabs.GetSipLogMessagesResponse` (response schema not provided in source).

#### Response Example
(Not provided in source)
```

--------------------------------

### get

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Get details about a specific documentation making up the agent's knowledge base.

```APIDOC
## get

### Description
Get details about a specific documentation making up the agent's knowledge base.

### Method
GET

### Endpoint
/v1/convai/knowledge-base/{documentation_id}

### Parameters
#### Path Parameters
- **documentation_id** (string) - Required - The id of a document from the knowledge base. This is returned on document addition.

#### Query Parameters
- **agentId** (string) - Optional - The ID of the agent.

### Request Example
```typescript
await client.conversationalAi.knowledgeBase.documents.get("21m00Tcm4TlvDq8ikWAM", {
    agentId: "agent_id"
});
```

### Response
#### Success Response (200)
- **DocumentsGetResponse** - The response model for getting a document.

#### Response Example
```json
{
  "id": "string",
  "name": "string"
}
```
```

--------------------------------

### Create chapter with client.studio.projects.chapters.create

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Creates a new chapter either as blank or from a URL. Requires project_id and a request object with a name.

```typescript
await client.studio.projects.chapters.create("21m00Tcm4TlvDq8ikWAM", {
    name: "Chapter 1"
});
```

--------------------------------

### client.studio.projects.chapters.create

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Creates a new chapter either as blank or from a URL.

```APIDOC
## client.studio.projects.chapters.create(project_id, { ...params })

### Description
Creates a new chapter either as blank or from a URL.

### Method
POST

### Endpoint
/studio/projects/{project_id}/chapters

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the Studio project.

#### Request Body
- **name** (string) - Required - The name of the chapter.

### Request Example
```typescript
await client.studio.projects.chapters.create("21m00Tcm4TlvDq8ikWAM", {
    name: "Chapter 1"
});
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the created chapter.

#### Response Example
```json
{
  "id": "21m00Tcm4TlvDq8ikWAM"
}
```
```

--------------------------------

### Get agent response test by ID

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Gets an agent response test by its ID.

```typescript
await client.conversationalAi.tests.get("TeaqRRdTcIfIu2i7BYfT");
```

--------------------------------

### Convert Studio Project

Source: https://github.com/elevenlabs/elevenlabs-js/blob/main/reference.md

Starts conversion of a Studio project and all of its chapters. Requires project_id.

```typescript
await client.studio.projects.convert("21m00Tcm4TlvDq8ikWAM");
```
Tokens:
Raw