---
type: skill
name: elevenlabs-api
agent_ready: true
schema_version: 1
bundle_skill: true
bundle_version: "0.28.0"
scope: anwender
default_active:
  allgemein: false
  content: true
  business: false
  beratung: false
  automation: true
  image: false
conflicts_with: []
depends_on: []
description: "Batch-TTS und Scribe-Sprach-zu-Text Wrapper-Skill für ElevenLabs /v1/text-to-speech und /v1/speech-to-text Endpoints. Music-Endpoint als Stub für v0.19.0 reserviert. Konsumiert _lib/api_keys.get_elevenlabs_key. Verwende, wenn ein Workflow Wort-Timestamps aus Audio braucht (Scribe) oder eine synthetische Voiceover-Audio-Datei (TTS, Premade-Voice). Sub-Skill-Routing: scribe / tts / music. NICHT für Conversational-AI-Agents (siehe agents_elevenlabs Vault-Skill)."
trigger_words:
  - elevenlabs
  - elevenlabs-api
  - text-to-speech
  - tts
  - voiceover
  - scribe
  - wort-timestamps
  - transkription
  - sprachsynthese
---

# elevenlabs-api

Dieser Skill kapselt drei ElevenLabs-Pfade als Bundle-Wrapper: Sprachsynthese aus Text (TTS), Transkription von Audio mit Wort-Timestamps (Scribe) und einen reservierten Music-Stub für v0.19.0. Der Skill liest den API-Key ausschließlich über `_lib/api_keys.get_elevenlabs_key` und gibt den Wert niemals weiter. Alle Pfade laufen offline-fähig (keine Netz-Abhängigkeit im eval-Lauf, nur bei echten API-Calls).

---

## Routing

Drei Sub-Skill-Pfade stehen zur Verfügung:

| Sub-Skill | Aufgabe | Endpoint | Status |
|---|---|---|---|
| `elevenlabs-api tts` | Synthetische Voiceover-Audio aus Text erzeugen | `/v1/text-to-speech/{voice_id}` | aktiv |
| `elevenlabs-api scribe` | Audio transkribieren mit Wort-Timestamps | `/v1/speech-to-text` | aktiv |
| `elevenlabs-api music` | Musikstück aus Prompt generieren | TBD | Stub v0.18.0, Vollausbau v0.19.0 |

Aufruf-Beispiele:

```bash
# TTS — Voiceover aus Text
python scripts/generate_tts.py --text "Willkommen im Podcast." --output out.mp3

# Scribe — Transkription mit Timestamps
python scripts/generate_scribe.py --input aufnahme.mp3 --output transkript.json

# Music — nur Stub, wirft NotImplementedError
python scripts/generate_music.py
```

---

## Voice-ID-Konvention

Nur Premade-Voices aus der ElevenLabs Voice Library. Kein Voice-Cloning (HARD-LOCK §8.2, v0.18.0).

Die `voice_id` kommt aus `skill.config.yaml` (Key `voice_id`). Default-Wert aus `skill.config.example.yaml`:

```
JBFqnCBsd6RMkjVDRZzb  (George — tief, ruhig, narrativ)
```

Weitere Premade-Voice-Empfehlungen und Endpoint-Details: `references/tts.md`.

---

## Music-Pfad in v0.19.0 geplant

`elevenlabs-api music` ist in v0.18.0 als Stub reserviert. `scripts/generate_music.py` wirft beim Import sofort `NotImplementedError`. Der Endpoint-Vertrag und die Account-Tier-Anforderungen werden vor v0.19.0 gegen die ElevenLabs-Doku verifiziert.

Geplante Inputs: Prompt-String, Dauer in Sekunden, optionale Genre-Hints.
Details zur Skizze: `references/music.md`.

---

## Pflichten

- **API-Key-Existenz-Check vor jedem Tool-Aufruf.** `scripts/find_api_key.py` gibt nur "OK" + Länge aus, niemals den Wert.
- **Keinen Key-Wert loggen, ausgeben oder in Fehlermeldungen exponieren.**
- **Umgebungsvariable `ELEVENLABS_API_KEY`** muss gesetzt sein. Konfigurierbar über `skill.config.yaml` → `api_key_env_var`.
- Bei fehlendem Key: Anwender auf `assets/README.md` hinweisen, nicht selbst eine `.env` anlegen.
- Kein Live-API-Call in Eval-Läufen (`run_evals.py` arbeitet ausschließlich offline).

---

## Verknüpfungen

- `[[_lib/api_keys.py]]` — Foundation-Layer, liefert `get_elevenlabs_key`
- `[[.maintainer/docs/V0.17.11-WAVE-J-ARCHITECTURE-SPEC]]` — Architektur-Entscheidungen für diesen Skill (§3 transitive Indirektion, §8.1 Music-Stub, §8.2 Premade-Only)
- `[[agents_elevenlabs]]` — Vault-Skill für Conversational-AI-Agents; abgrenzen: `elevenlabs-api` ist Batch-Wrapper, kein Conversation-Agent
