Imported from JHamidun/claude-code-config-pack (.claude/skills/elevenlabs/SKILL.md). Install upstream with npx skills add JHamidun/claude-code-config-pack --skill elevenlabs. Copyright stays with the author.

ElevenLabs API Skill

Overview

Expert skill for text-to-speech, voice cloning, sound effects, and audio AI using ElevenLabs - the most advanced voice AI platform.

API Key

# ~/.claude/.credentials.master.env — впиши САМ КЛЮЧ, не код на Python
ELEVENLABS_API_KEY=ВСТАВЬ_СЮДА_СВОЙ_КЛЮЧ   # https://elevenlabs.io/app/settings/api-keys

Строка ELEVENLABS_API_KEY=os.getenv('ELEVENLABS_API_KEY') ключ НЕ настраивает: это непустое значение, любая проверка if not key сочтёт ключ заданным, запрос уйдёт с этим текстом и вернётся 401 без объяснения. В коде читай ключ через os.getenv('ELEVENLABS_API_KEY'), а в файле должен лежать сам ключ. Файл не подгружается сам: load_dotenv(Path.home()/'.claude'/'.credentials.master.env').

Свой голос (клон)

Пак не поставляется ни с каким голосом. Идентификатор держится в окружении, а не в тексте навыка: он привязан к конкретному аккаунту и в чужой установке всё равно не сработает — а прописанный в коде чужой id молча уедет в API и вернёт невнятный 404.

ELEVENLABS_VOICE_ID_RU=<YOUR_VOICE_ID>   # в ~/.claude/.credentials.master.env

Где взять свой: https://elevenlabs.io/app/voice-lab → свой голос → ID (кнопка копирования рядом с названием). Программно — GET /v1/voices; клонированные помечены категорией cloned:

curl -s https://api.elevenlabs.io/v1/voices -H "xi-api-key: $ELEVENLABS_API_KEY" \
  | python -c "import sys,json; [print(v['voice_id'], v['category'], v['name']) for v in json.load(sys.stdin)['voices']]"

Голоса ещё нет — сначала обучи клон (client.voices.ivc.create, раздел «Instant Voice Cloning» ниже); как собрать чистый датасет на 2-3 минуты — scripts/voice_dataset.py (только stdlib + ffmpeg в PATH), как вырезать чужие реплики — scripts/isolate_speaker.py. Второму нужны пакеты, и импортирует он их лениво — то есть упадёт ModuleNotFoundError уже в середине разбора файла, поставь заранее: pip install librosa numpy scikit-learn soundfile (плюс тот же ffmpeg). Не хочешь свой голос — возьми любой стоковый id из каталога ElevenLabs (примеры в разделе «EN voices on RU» ниже), всё остальное в навыке работает так же.

Локальная альтернатива (экономия кредитов): для массовой/черновой RU-озвучки, длинных аудиокниг, dictation и офлайн — см. references/local-voicebox-eval.md (Voicebox / Chatterbox / Qwen3-TTS на видеокарте с 16 ГБ памяти, без обращений к API). ElevenLabs остаётся каноном для флагманской озвучки, звуковых эффектов и музыки.

When to Use ElevenLabs

Best for:

• Text-to-speech (TTS) generation
• Voice cloning (instant & professional)
• Sound effects generation
• Speech-to-speech voice conversion
• Dubbing & localization
• Real-time voice agents

Advantages:

• Most natural-sounding voices
• 70+ languages support
• Ultra-low latency (75ms with Flash)
• Voice cloning from 1 minute of audio
• Emotional expression control

Dependencies

pip install elevenlabs

Models

Basic Usage

Setup Client

from elevenlabs import ElevenLabs
import os

client = ElevenLabs(api_key=os.getenv('ELEVENLABS_API_KEY'))

Text-to-Speech

def text_to_speech(text: str, voice_id: str = "JBFqnCBsd6RMkjVDRZzb",
                   model: str = "eleven_multilingual_v2"):
    """Generate speech from text."""

    audio = client.text_to_speech.convert(
        text=text,
        voice_id=voice_id,
        model_id=model,
        output_format="mp3_44100_128",
        voice_settings={
            "stability": 0.5,
            "similarity_boost": 0.75,
            "style": 0,
            "use_speaker_boost": True
        }
    )

    # Save to file
    with open("output.mp3", "wb") as f:
        for chunk in audio:
            f.write(chunk)

    return "output.mp3"

Streaming TTS (Real-time)

def stream_speech(text: str, voice_id: str):
    """Stream speech for real-time playback."""

    audio_stream = client.text_to_speech.stream(
        text=text,
        voice_id=voice_id,
        model_id="eleven_flash_v2_5",  # Best for streaming
        output_format="mp3_44100_128"
    )

    # Play directly
    from elevenlabs.play import play
    play(audio_stream)

Music Generation (client.music.compose)

ENDPOINT: client.music.compose(prompt, music_length_ms, force_instrumental, model_id) — добавлено 2026-05-31, params исправлены 2026-06-06 (production-used).

Quickstart

from elevenlabs import ElevenLabs
import os

client = ElevenLabs(api_key=os.environ['ELEVENLABS_API_KEY'])

result = client.music.compose(
    prompt='Tense underscore, sub-bass pulse, sparse percussion, no vocals',
    music_length_ms=30000,     # ← НЕ length_ms! (см. ниже)
    force_instrumental=True,    # инструментал без вокала
    model_id='music_v1',
)

with open('bgm.mp3', 'wb') as f:
    for chunk in result:
        f.write(chunk)

Hard limits + param names

• CRITICAL — имя параметра длины = music_length_ms, НЕ length_ms. length_ms=... → TypeError: MusicClient.compose() got an unexpected keyword argument 'length_ms' (проверено в проде, июнь 2026).
• Инструментал — через force_instrumental=True (надёжнее, чем «no vocals» в тексте промпта).
• model_id='music_v1'.
• ~30 seconds на одну генерацию (длиннее режь на сегменты с narrative handoff, см. video-generation skills/video-generation/references/audio.md).
• Output: MP3 stream. Generation time: 10-30 sec wall-clock.

CRITICAL: Named-artist policy

Любой prompt со ссылкой на named artist → content_policy_violation. Это всегда падает:

• 'in the style of [Named Artist]'
• '[Artist]-style vocal'
• 'sounds like [Track] by [Artist]'
• '[Composer] cinematic'

Workaround = ТОЛЬКО descriptor substitution. Никаких имён.

Длинные треки (>30s)

Генерируй 2 сегмента по 30s с narrative handoff в prompt'е, концатенируй БЕЗ crossfade (jarring на музыке):

seg1 = client.music.compose(prompt='Dark mystery cinematic underscore, low strings, builds slowly', music_length_ms=30000, force_instrumental=True, model_id='music_v1')
seg2 = client.music.compose(prompt='Continues from dark mystery, transitions into battle, percussion enters, brass swells', music_length_ms=30000, force_instrumental=True, model_id='music_v1')
# ffmpeg -i seg1.mp3 -i seg2.mp3 -filter_complex "[0:a][1:a]concat=n=2:v=0:a=1[out]" -map "[out]" full.mp3

Когда что использовать

Production voice IDs

Свой клонированный голос — рабочие настройки

audio = client.text_to_speech.convert(
    voice_id=os.getenv('ELEVENLABS_VOICE_ID_RU'),   # свой голос — из окружения
    text='Сегодня разберём, как…',
    model_id='eleven_multilingual_v2',
    voice_settings={
        'stability': 0.55,
        'similarity_boost': 0.80,
        'style': 0.15,
        'use_speaker_boost': True,
    },
)

Отклонения от этих параметров → voice cracks, потеря тембра, over-acting. Не править без причины.

EN voices on RU — эмпирически лучше native RU

Английские voice IDs через eleven_multilingual_v2 на русском тексте дают тембр заметно лучше native RU voices. Подтверждено на коротких вертикальных роликах.

Voice settings ranges (общие)

Тестируй 5-10 voice IDs с identical text прежде чем commit к final.

Instant Voice Cloning

from io import BytesIO

def clone_voice(name: str, audio_files: list):
    """
    Clone voice from audio samples.

    Requirements:
        - Minimum 1 minute of clean audio
        - Best results with 2-3 minutes
    """
    files = [BytesIO(open(f, "rb").read()) for f in audio_files]

    voice = client.voices.ivc.create(
        name=name,
        files=files,
        remove_background_noise=True
    )

    return voice.voice_id

Sound Effects Generation

def generate_sound_effect(description: str, duration: int = 10):
    """
    Generate sound effect from text description.

    Max duration: 22 seconds
    """
    audio = client.text_to_sound_effects.convert(
        text=description,
        duration_seconds=duration,
        prompt_influence=0.5
    )

    with open("effect.mp3", "wb") as f:
        for chunk in audio:
            f.write(chunk)

    return "effect.mp3"

# Examples:
# "Cinematic braam for movie trailer"
# "Forest ambience with birds chirping"
# "Spaceship engine humming"

Speech-to-Speech (Voice Changer)

def change_voice(audio_path: str, target_voice_id: str):
    """Convert voice in audio to target voice."""

    with open(audio_path, "rb") as audio_file:
        result = client.speech_to_speech.convert(
            voice_id=target_voice_id,
            audio=audio_file,
            model_id="eleven_multilingual_sts_v2",
            remove_background_noise=True
        )

    with open("voice_changed.mp3", "wb") as f:
        for chunk in result:
            f.write(chunk)

    return "voice_changed.mp3"

List Available Voices

def get_voices():
    """Get all available voices."""

    voices = client.voices.search(page_size=100)

    for voice in voices.voices:
        print(f"{voice.name}: {voice.voice_id}")

    return voices.voices

Voice Settings

Output Formats

• mp3_22050_32 - Low quality
• mp3_44100_128 - Standard (default)
• mp3_44100_192 - High quality (Creator+)
• pcm_16000, pcm_44100 - Raw PCM
• opus_48000_64 - Opus codec

API Pricing

Quick Reference

Tips

1. eleven_flash_v2_5 - лучший для real-time (75ms latency)
2. eleven_multilingual_v2 - лучшее качество для записей
3. Для voice cloning нужно минимум 1 минута чистого аудио
4. stability=0.5 - оптимальный баланс эмоций
5. Sound effects до 22 секунд максимум
6. Поддержка 70+ языков