ElevenLabs Install & Auth

Overview

Set up the ElevenLabs SDK and configure API key authentication. ElevenLabs uses a single API key (

xi-api-key

api.elevenlabs.io

Prerequisites

• Node.js 18+ or Python 3.10+
• ElevenLabs account (free tier works) at https://elevenlabs.io
• API key from Profile > API Keys in the ElevenLabs dashboard

Instructions

Step 1: Install the SDK

Node.js (official package:

@elevenlabs/elevenlabs-js

npm install @elevenlabs/elevenlabs-js
# or
pnpm add @elevenlabs/elevenlabs-js

Python (official package:

elevenlabs

pip install elevenlabs

Step 2: Configure API Key

# Set environment variable (all SDKs auto-detect this)
export ELEVENLABS_API_KEY="sk_your_key_here"

# Or create .env file
echo 'ELEVENLABS_API_KEY=sk_your_key_here' >> .env

Add to

.gitignore

.env
.env.local
.env.*.local

Step 3: Initialize the Client

TypeScript:

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const client = new ElevenLabsClient({
  apiKey: process.env.ELEVENLABS_API_KEY,
  // Optional: configure retries (default: 2)
  maxRetries: 3,
  // Optional: configure timeout in seconds
  timeoutInSeconds: 30,
});

Python:

import os
from elevenlabs.client import ElevenLabsClient

client = ElevenLabsClient(
    api_key=os.environ.get("ELEVENLABS_API_KEY")
)

Step 4: Verify Connection

TypeScript:

async function verifyConnection() {
  // List available voices to confirm auth works
  const voices = await client.voices.getAll();
  console.log(`Connected. ${voices.voices.length} voices available.`);

  // Check subscription/quota
  const user = await client.user.get();
  console.log(`Plan: ${user.subscription.tier}`);
  console.log(`Characters used: ${user.subscription.character_count}/${user.subscription.character_limit}`);
}

verifyConnection().catch(console.error);

Python:

def verify_connection():
    voices = client.voices.get_all()
    print(f"Connected. {len(voices.voices)} voices available.")

    user = client.user.get()
    print(f"Plan: {user.subscription.tier}")
    print(f"Characters used: {user.subscription.character_count}/{user.subscription.character_limit}")

verify_connection()

cURL (raw API):

curl -s https://api.elevenlabs.io/v1/user \
  -H "xi-api-key: ${ELEVENLABS_API_KEY}" | jq '.subscription.tier'

Output

• SDK installed in

  node_modules

  or

  site-packages

• API key stored in

  .env

  (git-ignored)
• Successful voice listing confirms authentication
• Subscription tier and character quota displayed

Error Handling

invalid_api_key

ENOTFOUND api.elevenlabs.io

MODULE_NOT_FOUND

npm install @elevenlabs/elevenlabs-js

quota_exceeded

API Key Best Practices

• Never hardcode keys in source files
• Use separate keys for dev/staging/prod
• Rotate keys quarterly via the dashboard
• The

  xi-api-key

  header is used for REST calls; SDKs handle this automatically
• Free tier: 10,000 characters/month, Starter: 30,000, Creator: 100,000

Resources

• ElevenLabs API Introduction
• ElevenLabs JS SDK
• ElevenLabs Python SDK
• API Key Management

Next Steps

After auth is confirmed, proceed to

elevenlabs-hello-world