elevenlabs-api

ElevenLabs API Skill

A comprehensive guide to performing various audio production tasks such as high-quality speech generation, sound effects, and voice cloning using the ElevenLabs AI API.

📥 Download Skill

# NPX로 플러그인 설치 (권장)
npx dlabs install media-fx

# 또는 전체 플러그인 설치
npx dlabs install

🔐 Authentication Setup

Issuing an API Key

ElevenLabs websiteCreate an account at
Issue a new API key in Profile → API Keys
Store the API key securely

Setting Environment Variables

~/.claude/auth/elevenlabs.env Create file:

# ElevenLabs API Key
ELEVENLABS_API_KEY=your_api_key_here

# Optional: Base URL (기본값: https://api.elevenlabs.io/v1/)
ELEVENLABS_BASE_URL=https://api.elevenlabs.io/v1/

Load credentials:

# Secure auth loader를 사용한 안전한 로드
source ~/.claude/skills/auth-loader/scripts/secure-load-auth.sh elevenlabs

# 또는 직접 로드
source ~/.claude/auth/elevenlabs.env

🎯 Key Features

1. Text-to-Speech (TTS)

Converts text into natural speech.

Endpoint:

POST https://api.elevenlabs.io/v1/text-to-speech/{voice_id}

Basic usage:

curl -X POST "https://api.elevenlabs.io/v1/text-to-speech/21m00Tcm4TlvDq8ikWAM" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "안녕하세요. ElevenLabs AI 음성입니다.",
    "model_id": "eleven_multilingual_v2",
    "voice_settings": {
      "stability": 0.5,
      "similarity_boost": 0.75,
      "style": 0.0,
      "use_speaker_boost": true
    }
  }' \
  --output speech.mp3

Key parameters:

Parameter	Type	Default	Description
`text`	string	required	Text to convert
`model_id`	string	eleven_multilingual_v2	Model ID to use
`voice_settings.stability`	float	0.5	Emotion range (0–1, lower means greater emotional variation)
`voice_settings.similarity_boost`	float	0.75	Similarity to the original voice (0–1)
`voice_settings.style`	float	0.0	Style emphasis (0–1)
`voice_settings.speed`	float	1.0	Playback speed (0.5–2.0)
`voice_settings.use_speaker_boost`	boolean	true	Voice similarity enhancement (increases latency)

Query parameters:

Parameter	Type	Default	Description
`enable_logging`	boolean	true	Enable history recording
`optimize_streaming_latency`	integer	None	Streaming latency optimization (0–4)
`output_format`	string	mp3_44100_128	Output audio format

Output format options:

MP3: mp3_22050_32, mp3_44100_128, mp3_44100_192 등
Opus: opus_48000_128, opus_48000_192 등
PCM: pcm_16000, pcm_24000, pcm_44100 등
WAV: wav_16000, wav_44100, wav_48000 등

2. Streaming TTS (WebSocket)

Generates speech with real-time streaming.

Endpoint:

wss://api.elevenlabs.io/v1/text-to-speech/{voice_id}/stream

Example:

import websocket
import json

def on_message(ws, message):
    # 오디오 청크 수신
    with open("stream_output.mp3", "ab") as f:
        f.write(message)

def on_open(ws):
    # 텍스트 전송
    ws.send(json.dumps({
        "text": "스트리밍 음성 테스트입니다.",
        "voice_settings": {
            "stability": 0.5,
            "similarity_boost": 0.75
        }
    }))

ws = websocket.WebSocketApp(
    f"wss://api.elevenlabs.io/v1/text-to-speech/21m00Tcm4TlvDq8ikWAM/stream",
    header=[f"xi-api-key: {os.getenv('ELEVENLABS_API_KEY')}"],
    on_message=on_message,
    on_open=on_open
)
ws.run_forever()

3. Sound Effects

Generates sound effects from a text description.

Endpoint:

POST https://api.elevenlabs.io/v1/sound-generation

Basic usage:

curl -X POST "https://api.elevenlabs.io/v1/sound-generation" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "경쾌한 종소리와 박수 소리",
    "duration_seconds": 5.0,
    "prompt_influence": 0.3,
    "model_id": "eleven_text_to_sound_v2"
  }' \
  --output sound_effect.mp3

Key parameters:

Parameter	Type	Constraint	Description
`text`	string	required	Sound description
`duration_seconds`	float	0.5~30.0	Length of the sound to generate (seconds)
`prompt_influence`	float	0.0~1.0	Prompt influence (default: 0.3)
`model_id`	string	—	eleven_text_to_sound_v2 recommended
`loop`	boolean	false	Generate looping sound (supported only by v2)

Usage examples:

Game sound effects: "gunshots and explosions"
Movie sound: "rain and thunder"
Foley sound: "footsteps and doors opening and closing"
Ambient sound: "birdsong and wind in the forest"

4. Voice Management

Retrieves and manages available voices.

4.1 Retrieve Voice List

Endpoint:

GET https://api.elevenlabs.io/v1/voices

Basic usage:

curl -X GET "https://api.elevenlabs.io/v1/voices" \
  -H "xi-api-key: $ELEVENLABS_API_KEY"

Query parameters:

Parameter	Type	Description
`page_size`	integer	Number of results per page (default: 30)
`page_token`	string	Pagination token
`voice_ids`	array	Retrieve a list of specific Voice IDs (up to 100)

Response example:

{
  "voices": [
    {
      "voice_id": "21m00Tcm4TlvDq8ikWAM",
      "name": "Rachel",
      "category": "premade",
      "labels": {
        "accent": "american",
        "age": "young",
        "gender": "female",
        "use case": "narration"
      }
    }
  ],
  "has_more": false,
  "next_page_token": null
}

4.2 Retrieve a Specific Voice

Endpoint:

GET https://api.elevenlabs.io/v1/voices/{voice_id}

Basic usage:

curl -X GET "https://api.elevenlabs.io/v1/voices/21m00Tcm4TlvDq8ikWAM" \
  -H "xi-api-key: $ELEVENLABS_API_KEY"

4.3 Download voice sample audio

Endpoint:

GET https://api.elevenlabs.io/v1/voices/{voice_id}/samples/{sample_id}/audio

Basic usage:

curl -X GET "https://api.elevenlabs.io/v1/voices/21m00Tcm4TlvDq8ikWAM/samples/sample123/audio" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  --output voice_sample.mp3

5. Voice Cloning

Train on the user's voice to create a custom voice.

5.1 Instant Voice Cloning (IVC)

Endpoint:

POST https://api.elevenlabs.io/v1/voices/add

Basic usage (file upload):

curl -X POST "https://api.elevenlabs.io/v1/voices/add" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -F "name=My Custom Voice" \
  -F "description=클론된 음성" \
  -F "files=@sample1.mp3" \
  -F "files=@sample2.mp3" \
  -F "files=@sample3.mp3"

Requirements:

At least 1 audio sample, 3-5 recommended
Each sample: at least 30 seconds, 1-2 minutes recommended
Clean audio quality, minimal background noise
Include a variety of emotions and tones

5.2 Professional Voice Cloning (PVC)

Creates a higher-quality voice clone. Requires the Creator plan or higher.

PVC vs IVC comparison:

IVC: Fast and simple voice clone (takes 1-5 minutes)
PVC: High-quality precision voice clone (requires 30+ minutes of audio, higher accuracy)

API workflow:

Step 1: Create PVC

curl -X POST "https://api.elevenlabs.io/v1/voices/add/pvc" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Professional Voice",
    "description": "고품질 음성 클론",
    "language": "ko"
  }'

Response:

{
  "voice_id": "pvc_voice_id_here",
  "status": "created"
}

Step 2: Upload audio/video samples

# 여러 샘플 업로드 (30분 이상 권장)
curl -X POST "https://api.elevenlabs.io/v1/voices/pvc/{voice_id}/samples" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -F "file=@recording1.mp3" \
  -F "file=@recording2.mp3" \
  -F "file=@recording3.mp4"

Step 3: Speaker separation (for multi-speaker samples)

# 화자 분리 요청
curl -X POST "https://api.elevenlabs.io/v1/voices/pvc/{voice_id}/samples/{sample_id}/speakers/separate" \
  -H "xi-api-key: $ELEVENLABS_API_KEY"

# 분리 상태 확인
curl -X GET "https://api.elevenlabs.io/v1/voices/pvc/{voice_id}/samples/{sample_id}/speakers" \
  -H "xi-api-key: $ELEVENLABS_API_KEY"

# 분리된 화자 선택
curl -X PATCH "https://api.elevenlabs.io/v1/voices/pvc/{voice_id}/samples/{sample_id}" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "speaker_id": "speaker_1"
  }'

Step 4: Identity Verification

Option A: CAPTCHA method

# CAPTCHA 이미지 요청
curl -X GET "https://api.elevenlabs.io/v1/voices/pvc/{voice_id}/verification/captcha" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  --output captcha.png

# CAPTCHA 텍스트를 읽고 녹음한 후 검증
curl -X POST "https://api.elevenlabs.io/v1/voices/pvc/{voice_id}/verification/captcha/verify" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -F "recording=@captcha_recording.mp3"

Option B: Request manual verification

curl -X POST "https://api.elevenlabs.io/v1/voices/pvc/{voice_id}/verification/request" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "verification_method": "manual"
  }'

Step 5: Start model training

curl -X POST "https://api.elevenlabs.io/v1/voices/pvc/{voice_id}/train" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "eleven_multilingual_v2"
  }'

Step 6: Check training progress

curl -X GET "https://api.elevenlabs.io/v1/voices/{voice_id}" \
  -H "xi-api-key: $ELEVENLABS_API_KEY"

Response:

{
  "voice_id": "pvc_voice_id_here",
  "name": "My Professional Voice",
  "status": "training",
  "training_progress": 45,
  "estimated_completion": "2026-02-11T10:30:00Z"
}

Status after completion:

{
  "voice_id": "pvc_voice_id_here",
  "status": "ready",
  "training_progress": 100
}

Requirements:

Plan: Creator or higher
Audio length: At least 30 minutes (more improves quality)
Audio quality: Professional microphone recommended, minimal background noise
Variety: Include a variety of emotions, tones, and speeds
Number of samples: Split into multiple samples (10-20 recommended)

Training time:

Typically takes 2-6 hours
Varies depending on the amount and quality of samples

6. History Management

View and manage the generated audio history.

6.1 View history list

Endpoint:

GET https://api.elevenlabs.io/v1/history

Basic usage:

curl -X GET "https://api.elevenlabs.io/v1/history?page_size=10" \
  -H "xi-api-key: $ELEVENLABS_API_KEY"

6.2 Download history audio

Endpoint:

GET https://api.elevenlabs.io/v1/history/{history_item_id}/audio

Basic usage:

curl -X GET "https://api.elevenlabs.io/v1/history/history123/audio" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  --output history_audio.mp3

6.3 Delete history item

Endpoint:

DELETE https://api.elevenlabs.io/v1/history/{history_item_id}

Basic usage:

curl -X DELETE "https://api.elevenlabs.io/v1/history/history123" \
  -H "xi-api-key: $ELEVENLABS_API_KEY"

🔧 Advanced features

Multilingual support

ElevenLabs supports more than 29 languages.

Specify language code (ISO 639-1):

curl -X POST "https://api.elevenlabs.io/v1/text-to-speech/21m00Tcm4TlvDq8ikWAM" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "こんにちは、ElevenLabsです。",
    "model_id": "eleven_multilingual_v2",
    "language_code": "ja"
  }' \
  --output japanese_speech.mp3

Supported languages:

Korean (ko), English (en), Japanese (ja), Chinese (zh)
Spanish (es), French (fr), German (de), Italian (it)
Portuguese (pt), Russian (ru), Arabic (ar), Hindi (hi)
Many other languages supported

Context continuity

Specify the previous/next text to ensure natural connections.

curl -X POST "https://api.elevenlabs.io/v1/text-to-speech/21m00Tcm4TlvDq8ikWAM" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "이것이 현재 문장입니다.",
    "previous_text": "이것이 이전 문장입니다.",
    "next_text": "이것이 다음 문장입니다.",
    "model_id": "eleven_multilingual_v2"
  }' \
  --output context_speech.mp3

Pronunciation Dictionary

Apply custom pronunciation rules.

curl -X POST "https://api.elevenlabs.io/v1/text-to-speech/21m00Tcm4TlvDq8ikWAM" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "AWS는 아마존 웹 서비스입니다.",
    "model_id": "eleven_multilingual_v2",
    "pronunciation_dictionary_locators": [
      {
        "pronunciation_dictionary_id": "dict_id_123",
        "version_id": "v1"
      }
    ]
  }' \
  --output custom_pronunciation.mp3

Deterministic Sampling (Seed)

Generate reproducible output for the same input.

curl -X POST "https://api.elevenlabs.io/v1/text-to-speech/21m00Tcm4TlvDq8ikWAM" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "재현 가능한 음성입니다.",
    "model_id": "eleven_multilingual_v2",
    "seed": 12345
  }' \
  --output deterministic_speech.mp3

📊 Check Usage and Quota

Endpoint:

GET https://api.elevenlabs.io/v1/user/subscription

Basic usage:

curl -X GET "https://api.elevenlabs.io/v1/user/subscription" \
  -H "xi-api-key: $ELEVENLABS_API_KEY"

Example response:

{
  "tier": "free",
  "character_count": 5000,
  "character_limit": 10000,
  "can_extend_character_limit": true,
  "allowed_to_extend_character_limit": true,
  "next_character_count_reset_unix": 1709251200,
  "voice_limit": 3,
  "professional_voice_limit": 0,
  "can_use_instant_voice_cloning": true
}

🛠️ SDK Usage (Optional)

Python SDK

Installation:

pip install elevenlabs

Basic usage:

from elevenlabs import ElevenLabs, VoiceSettings

client = ElevenLabs(api_key="your_api_key")

# Text-to-Speech
audio = client.text_to_speech.convert(
    voice_id="21m00Tcm4TlvDq8ikWAM",
    text="안녕하세요, ElevenLabs입니다.",
    model_id="eleven_multilingual_v2",
    voice_settings=VoiceSettings(
        stability=0.5,
        similarity_boost=0.75,
        style=0.0,
        use_speaker_boost=True
    )
)

# 파일 저장
with open("output.mp3", "wb") as f:
    f.write(audio)

Node.js SDK

Installation:

npm install @elevenlabs/elevenlabs-js

Basic usage:

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

const client = new ElevenLabs({
  apiKey: "your_api_key",
});

// Text-to-Speech
const audio = await client.textToSpeech.convert({
  voiceId: "21m00Tcm4TlvDq8ikWAM",
  text: "안녕하세요, ElevenLabs입니다.",
  modelId: "eleven_multilingual_v2",
  voiceSettings: {
    stability: 0.5,
    similarityBoost: 0.75,
    style: 0.0,
    useSpeakerBoost: true,
  },
});

// 파일 저장
import fs from "fs";
const buffer = await audio.arrayBuffer();
fs.writeFileSync("output.mp3", Buffer.from(buffer));

💡 Best Practices

1. Optimize Voice Settings

Stability: 0.3–0.7 recommended (lower means more emotional variation)
Similarity (similarity_boost): 0.7–0.9 recommended (higher means closer to the original)
Style: 0.0–0.5 recommended (higher means more exaggerated)
Speed: 0.8–1.2 recommended (natural range)

2. Choose Output Format

MP3: General purpose, small file size
WAV/PCM: High-quality editing, post-processing work
Opus: Low bandwidth, streaming optimized

3. Cost Optimization

enable_logging=falseto disable history recording
Only when necessary, use_speaker_boost=true use
Appropriate output_format selection (sample rate vs quality)

4. Error Handling

Common error codes:

401 Unauthorized: API key error
422 Unprocessable Entity: Invalid request parameters
429 Too Many Requests: Request limit exceeded
500 Internal Server Error: Server error

Retry logic:

for i in {1..3}; do
  if curl -X POST "https://api.elevenlabs.io/v1/text-to-speech/..." \
    -H "xi-api-key: $ELEVENLABS_API_KEY" \
    --output output.mp3 --fail; then
    break
  fi
  echo "재시도 $i/3..."
  sleep 2
done

🔗 References

Official documentation: ElevenLabs API Documentation
API Explorer: Interactive API Testing
Voice Library: Pre-made Voices
Sound Effects Guide: Sound Effects Documentation
Pricing: Plan Comparison
Status Page: API Status

📞 Support and Community

Discord: ElevenLabs Community
Support: support@elevenlabs.io
GitHub: ElevenLabs SDKs

About this skill

📥 Download Skill

🔐 Authentication Setup

Issuing an API Key

Setting Environment Variables

🎯 Key Features

1. Text-to-Speech (TTS)

2. Streaming TTS (WebSocket)

3. Sound Effects

4. Voice Management

4.1 Retrieve Voice List

4.2 Retrieve a Specific Voice

4.3 Download voice sample audio

5. Voice Cloning

5.1 Instant Voice Cloning (IVC)

5.2 Professional Voice Cloning (PVC)

6. History Management

6.1 View history list

6.2 Download history audio

6.3 Delete history item

🔧 Advanced features

Multilingual support

Context continuity

Pronunciation Dictionary

Deterministic Sampling (Seed)

📊 Check Usage and Quota

🛠️ SDK Usage (Optional)

Python SDK

Node.js SDK

💡 Best Practices

1. Optimize Voice Settings

2. Choose Output Format

3. Cost Optimization

4. Error Handling

🔗 References

📞 Support and Community