elevenlabs/skills

ElevenLabs Dubbing (Übersetzung)

Übersetzen Sie Audio oder Video in andere Sprachen unter Beibehaltung der Stimmen der Originalsprecher. Erstellen Sie ein Projekt aus einer Datei oder URL, überprüfen und bearbeiten Sie das Quellentranskript, fügen Sie eine oder mehrere Zielsprachen hinzu, verfeinern Sie Übersetzungen pro Segment und generieren Sie Ausgaben neu.

Wichtig: Verwenden Sie die Dubbing Projects API – elevenlabs.dubbing.project.* in den SDKs oder die /v1/dubbing/project REST-Endpunkte. Verwenden Sie nicht die veraltete v1-Dubbing-Oberfläche (client.dubbing.create(), client.dubbing.get(), client.dubbing.audio.get() oder die nackten /v1/dubbing-Routen) – dies ist die ältere Dubbing-API, die jetzt unter „Legacy" in der API-Referenz zu finden ist.

Setup, bevor Sie Code schreiben: Wenn ELEVENLABS_API_KEY für dieses Projekt nicht festgelegt ist, führen Sie npx -y @elevenlabs/cli@latest onboard init aus dem App-Ordner aus und folgen Sie den Anweisungen: Es meldet den Benutzer an und speichert einen Schlüssel für das Projekt, sodass niemand einen manuell kopieren muss. Andernfalls lesen Sie die Installationsanleitung. Die elevenlabs-CLI und die SDKs lesen ELEVENLABS_API_KEY automatisch; die REST-Basis-URL ist https://api.elevenlabs.io mit Ihrem API-Schlüssel im xi-api-key-Header.

Konzepte

Konzept	Bedeutung
Projekt	Eine Medienquelle (Datei oder URL) plus ihr Quellentranskript. Einmal vorbereitet (transkribiert), bleibt es im Status ready, während Sie Sprachen hinzufügen.
Quellentranskript	Bearbeitbare Segmente (Text, Sprecher, Zeitangabe), die aus der Quelle transkribiert wurden. Die einzige Quelle der Wahrheit, von der jede Sprache übersetzt wird.
Sprache (Ziel)	Eine ausgegebene Synchronisationssprache. Jede hat ihr eigenes Transkript (Quellsegmente + eine Übersetzung pro Segment) und eine eigene synchronisierte Audioausgabe.
Revisionen	Unabhängige monotone Zähler. Die revision des Projekts wird bei Bearbeitungen des Quellentranskripts erhöht; die revision einer Sprache wird bei Übersetzungsbearbeitungen oder Quellbearbeitungen erhöht, die sie betreffen. Die output_revision einer Sprache ist die Revision, aus der das aktuelle Audio generiert wurde – wenn sie hinter der revision liegt, ist die Ausgabe veraltet.

Empfohlene Reihenfolge der Vorgänge: Finalisieren Sie das Quellentranskript bevor Sie Sprachen hinzufügen. Übersetzungen werden aus der Quelle erstellt, daher führt die Korrektur der Quelle zuerst dazu, dass jede Sprache vom richtigen Text ausgeht – die Bearbeitung der Quelle nach Abschluss einer Sprache markiert sie als stale und erfordert eine (kostenpflichtige) Neugenerierung.

Enterprise: Transkriptbearbeitung und Neugenerierung sind nur für Enterprise-Workspaces verfügbar. Das Erstellen von Projekten, das Hinzufügen von Sprachen und das Herunterladen von Synchronisationen funktionieren mit allen Tarifen.

Workflow

1. Projekt erstellen aus einer Datei oder URL → queued
2. Auf das Projekt warten, bis es ready ist
3. Quellentranskript überprüfen und finalisieren (Segmente bearbeiten/hinzufügen/löschen)
4. Eine Sprache pro Ziel hinzufügen → queued → processing → completed
5. outputs.lossless_audio jeder Sprache herunterladen, wenn completed
6. Übersetzungen pro Segment verfeinern, falls nötig → die Sprache wird stale
7. Die Sprache neu generieren → completed mit neuer Ausgabe

Schnellstart (Python)

import os
import time
import requests
from elevenlabs.client import ElevenLabs

elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY"))

# 1. Projekt aus einer lokalen Datei erstellen (oder source_url=... anstelle von file)
with open("promo.mp4", "rb") as f:
    project = elevenlabs.dubbing.project.create(
        file=f,
        source_language="en",
        reference="Q3-Marketingvideo",
    )

# 2. Warten, bis das Quellmedium transkribiert ist
while True:
    project = elevenlabs.dubbing.project.get(project.project_id)
    if project.status == "ready":
        break
    if project.status == "failed":
        raise RuntimeError("Projektvorbereitung fehlgeschlagen")
    time.sleep(5)

# 3. Spanische Sprachziel hinzufügen
language = elevenlabs.dubbing.project.language.create(
    project.project_id,
    target_language="es",
)

# 4. Warten, bis die Synchronisation fertig generiert ist
while True:
    language = elevenlabs.dubbing.project.language.get(
        project.project_id, language.language_id
    )
    if language.status == "completed":
        break
    if language.status == "failed":
        raise RuntimeError("Synchronisation fehlgeschlagen")
    time.sleep(5)

# 5. Synchronisiertes Audio herunterladen (signierte URL, ca. 1 Stunde gültig – Sprache erneut abrufen für eine neue)
audio = requests.get(language.outputs.lossless_audio)
with open("promo_es.wav", "wb") as f:
    f.write(audio.content)

Schnellstart (JavaScript)

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

const elevenlabs = new ElevenLabsClient();

// 1. Projekt erstellen (sourceUrl wird gezeigt; Datei-Upload wird ebenfalls unterstützt)
let project = await elevenlabs.dubbing.project.create({
  sourceUrl: "https://example.com/promo.mp4",
  sourceLanguage: "en",
  reference: "Q3-Marketingvideo",
});

// 2. Warten, bis das Quellmedium transkribiert ist
while (true) {
  project = await elevenlabs.dubbing.project.get(project.projectId);
  if (project.status === "ready") break;
  if (project.status === "failed") throw new Error("Projektvorbereitung fehlgeschlagen");
  await new Promise((resolve) => setTimeout(resolve, 5000));
}

// 3. Spanische Sprachziel hinzufügen
let language = await elevenlabs.dubbing.project.language.create(project.projectId, {
  targetLanguage: "es",
});

// 4. Warten, bis die Synchronisation fertig generiert ist
while (true) {
  language = await elevenlabs.dubbing.project.language.get(project.projectId, language.languageId);
  if (language.status === "completed") break;
  if (language.status === "failed") throw new Error("Synchronisation fehlgeschlagen");
  await new Promise((resolve) => setTimeout(resolve, 5000));
}

// 5. Synchronisiertes Audio von der signierten URL herunterladen
const response = await fetch(language.outputs!.losslessAudio!);
await writeFile("promo_es.wav", Buffer.from(await response.arrayBuffer()));

Schnellstart (CLI)

Die elevenlabs-CLI liest ELEVENLABS_API_KEY automatisch aus der Umgebung.

# 1. Projekt erstellen (verwenden Sie --source-url "https://..." anstelle von --file, um von einer URL zu synchronisieren)
elevenlabs dubbing project create --file promo.mp4 --source-language en
# → {"project_id": "proj_...", "status": "queued", ...}

# 2. Abfragen, bis der Status "ready" ist
elevenlabs dubbing project get --project-id proj_...

# 3. Zielsprache hinzufügen
elevenlabs dubbing project language create --project-id proj_... --target-language es

# 4. Sprache abfragen, bis "completed", dann outputs.lossless_audio herunterladen
elevenlabs dubbing project language get --project-id proj_... --language-id lang_...

Erstellungsoptionen

elevenlabs dubbing project create (REST: POST /v1/dubbing/project, multipart/form-data) akzeptiert entweder file oder source_url (nicht beide):

Feld	Erforderlich	Hinweise
file	eines von file/source_url	Quellmedium zum Synchronisieren (Audio oder Video), bis zu 3 GiB
source_url	eines von file/source_url	Öffentliche URL zum Abrufen des Quellmediums
source_language	nein	ISO 639-Code (z.B. en). Ohne Angabe automatische Erkennung – die erkannte Sprache wird im Feld language des Quellentranskripts gemeldet
reference	nein	Frei formatiertes Label zur Identifizierung des Projekts auf Ihrer Seite (max. 500 Zeichen)
model_id	nein	dubbing_v2 (Standard)
target_language	nein	Optional das erste Sprachziel bei der Erstellung in die Warteschlange stellen; weitere mit language.create hinzufügen
keyterms	nein	Begriffe, um die Transkription/Übersetzung zu beeinflussen (Produkt-/Markennamen). Bis zu 1000 Begriffe; jeder max. 50 Zeichen und 5 Wörter; <>{}[]\ nicht erlaubt. Wiederholen Sie das Feld einmal pro Begriff in multipart

Bearbeiten des Quellentranskripts

Sobald das Projekt ready ist, lesen Sie das Transkript und korrigieren Sie es, bevor Sie Sprachen hinzufügen. Jede Bearbeitung erhöht die revision des Projekts. Jedes Segment hat eine stabile id, die zum Bearbeiten oder Löschen verwendet wird. (Nur Enterprise-Workspaces.)

# Quellentranskript lesen
transcript = elevenlabs.dubbing.project.transcript.get(project_id)

# Text eines Segments korrigieren – nur die zu ändernden Felder senden (text, speaker_id, start_s, end_s)
elevenlabs.dubbing.project.transcript.update_segment(
    project_id,
    segment_id=transcript.segments[0].id,
    text="Willkommen zu unserer neuesten Produktdemo.",
)

# Segment hinzufügen (eine vorhandene speaker_id wiederverwenden, damit es mit der Stimme dieses Sprechers synchronisiert wird)
added = elevenlabs.dubbing.project.transcript.create_segment(
    project_id,
    text="Vielen Dank fürs Zuschauen.",
    speaker_id=transcript.segments[0].speaker_id,
    start_s=40.0,
    end_s=42.0,
)

# Segment löschen
elevenlabs.dubbing.project.transcript.delete_segment(project_id, segment_id=added.segment.id)

Via CLI: elevenlabs dubbing project transcript get --project-id proj_..., dann ein Segment mit nur den geänderten Feldern aktualisieren (--text, --speaker-id, --start-s, --end-s):

elevenlabs dubbing project transcript update_segment \
  --project-id proj_... --segment-id seg_... \
  --text "Willkommen zu unserer neuesten Produktdemo."

Übersetzungen verfeinern und neu generieren

Das Transkript einer Sprache paart jedes Quellsegment mit seiner translation (null = noch nicht übersetzt; Segment-IDs stimmen mit der Quelle überein). Bearbeiten Sie eine einzelne Übersetzung und generieren Sie dann neu. (Nur Enterprise-Workspaces.)

# Übersetzungen der Sprache lesen
target = elevenlabs.dubbing.project.language.transcript.get(project_id, language_id)

# Einzelne Übersetzung verfeinern (translation=None übergeben, um sie zu löschen und zur Neuübersetzung zu markieren)
elevenlabs.dubbing.project.language.transcript.update_segment(
    project_id,
    language_id,
    segment_id=target.segments[0].id,
    translation="Bienvenido a nuestra última demostración de producto.",
)

# Die Synchronisation aus dem aktuellen Transkript neu generieren (wie eine Generation abgerechnet)
elevenlabs.dubbing.project.language.transcript.regenerate(project_id, language_id)

Via CLI: elevenlabs dubbing project language transcript update_segment --project-id proj_... --language-id lang_... --segment-id seg_... --translation "...", dann elevenlabs dubbing project language transcript regenerate --project-id proj_... --language-id lang_... (gibt 202 Accepted zurück).

Eine Übersetzungsbearbeitung betrifft nur diese Sprache. Nach der Bearbeitung wird eine completed-Sprache zu stale – sie liefert weiterhin die vorherige Ausgabe, bis Sie neu generieren. Abfragen, bis completed; dann ist output_revision gleich revision und outputs.lossless_audio spiegelt das aktuelle Transkript wider.

Synchronisieren in mehrere Sprachen

Fügen Sie ein Sprachziel pro Sprache hinzu – jedes wird unabhängig generiert. Verfolgen Sie alle mit language.list, anstatt sie einzeln abzufragen:

for lang in ["es", "fr", "de", "ja"]:
    elevenlabs.dubbing.project.language.create(project_id, target_language=lang)

while True:
    result = elevenlabs.dubbing.project.language.list(project_id)
    if not any(l.status in ("queued", "processing") for l in result.languages):
        break
    time.sleep(5)

Zustände

Projekt:

Status	Bedeutung
queued	Erstellt; Quellabruf + Vorbereitung in die Warteschlange gestellt
preparing	Vorbereitung (Transkription) läuft
ready	Quellentranskript verfügbar; Sprachen hinzufügen/generieren. Projekte bleiben ready – der Fortschritt pro Sprache lebt in den Sprachen
failed	Vorbereitung fehlgeschlagen (z.B. Quelle konnte nicht abgerufen oder dekodiert werden)

Sprache:

Status	Bedeutung
queued	Wartet darauf, dass das Projekt ready wird, oder auf einen Generierungsarbeiter
processing	Die Synchronisation wird generiert
completed	Abgeschlossen; outputs mit einer signierten Download-URL (ca. 1 Stunde gültig – erneut abrufen für eine neue)
stale	Zuvor abgeschlossen, aber das Transkript hat sich geändert; behält die letzte Ausgabe bis zur Neugenerierung
failed	Generierung fehlgeschlagen

Sie können eine Sprache hinzufügen, bevor das Projekt ready ist – sie bleibt queued und startet automatisch, sobald das Projekt ready wird. Das Hinzufügen einer Sprache akzeptiert optional model_id (standardmäßig die des Projekts) und voice_settings (z.B. {"cloning_strength": 7}, Bereich 0–10, Standardwert 7 – steuert, wie stark synchronisierte Sprecher die Quellstimmen klonen).

Fehlerbehandlung

• 401: Ungültiger API-Schlüssel
• 409 Conflict bei Neugenerierung: Das Projekt ist nicht ready oder die Sprache ist nicht abgeschlossen (z.B. bereits in Generierung) – warten und wiederholen
• Abgelaufene Download-URL: outputs.lossless_audio ist signiert und ca. 1 Stunde gültig; erneutes Abrufen der Sprache für eine neue URL
• Transkriptbearbeitung/Neugenerierung nicht verfügbar: Diese Endpunkte sind nur für Enterprise – bei anderen Tarifen das Projekt mit einer finalisierten Quelle erstellen und Sprachen direkt hinzufügen

Referenzen

• Installationsanleitung
• API-Referenz – jeder Endpunkt mit vollständigen Request/Response-Schemata und SDK-Methodennamen