ElevenLabs Install & Auth Skill

ElevenLabs Install & Auth

Overview

Set up the ElevenLabs SDK and configure API key authentication. ElevenLabs uses a single API key (xi-api-key header) for all endpoints at 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

| Error | HTTP | Cause | Solution | |-------|------|-------|----------| | invalid_api_key | 401 | Key missing, expired, or malformed | Regenerate at elevenlabs.io > Profile > API Keys | | ENOTFOUND api.elevenlabs.io | N/A | DNS/network failure | Check internet; ensure outbound HTTPS on port 443 | | MODULE_NOT_FOUND | N/A | SDK not installed | Run npm install @elevenlabs/elevenlabs-js | | quota_exceeded | 401 | Character limit reached for billing period | Upgrade plan or wait for reset |

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

Next Steps

After auth is confirmed, proceed to elevenlabs-hello-world for your first text-to-speech generation.

Agent Skills: ElevenLabs Install & Auth

Install this agent skill to your local

Skill Files