elevenlabs/skills

Doublage ElevenLabs

Doublez un fichier audio ou vidéo dans d'autres langues tout en conservant les voix des locuteurs d'origine. Créez un projet à partir d'un fichier ou d'une URL, révisez et éditez la transcription source, ajoutez une ou plusieurs langues cibles, affinez les traductions par segment et régénérez les sorties.

Important : Utilisez l'API Dubbing Projects — elevenlabs.dubbing.project.* dans les SDK, ou les endpoints REST /v1/dubbing/project. N'utilisez pas l'ancienne surface de doublage v1 (client.dubbing.create(), client.dubbing.get(), client.dubbing.audio.get(), ou les routes /v1/dubbing seules) — il s'agit de l'ancienne API de doublage, désormais sous Legacy dans la référence API.

Configuration, avant d'écrire du code : si ELEVENLABS_API_KEY n'est pas définie pour ce projet, exécutez npx -y @elevenlabs/cli@latest onboard init depuis le dossier de l'application et suivez les instructions : cela connecte l'utilisateur et stocke une clé pour le projet, évitant ainsi de copier une clé manuellement. Sinon, consultez le Guide d'installation. Le CLI elevenlabs et les SDK lisent ELEVENLABS_API_KEY automatiquement ; l'URL de base REST est https://api.elevenlabs.io avec votre clé API dans l'en-tête xi-api-key.

Concepts

Concept	Signification
Projet	Une source de média (fichier ou URL) plus sa transcription source. Préparée (transcrite) une fois, puis en ready pendant que vous ajoutez des langues.
Transcription source	Segments modifiables (texte, locuteur, timing) transcrits à partir de la source. La source unique de vérité à partir de laquelle chaque langue est traduite.
Langue (cible)	Une langue de sortie doublée. Chacune a sa propre transcription (segments source + une traduction par segment) et son propre fichier audio doublé.
Révisions	Compteurs monotones indépendants. La revision du projet augmente lors des modifications de la transcription source ; la revision d'une langue augmente lors des modifications de traduction ou des modifications source qui l'affectent. La output_revision d'une langue est la révision à partir de laquelle son audio actuel a été généré — lorsqu'elle est en retard sur revision, la sortie est obsolète.

Ordre recommandé des opérations : finalisez la transcription source avant d'ajouter des langues. Les traductions sont produites à partir de la source, donc corriger la source en premier garantit que chaque langue part du bon texte — modifier la source après qu'une langue est terminée la marque stale et nécessite une régénération (facturée).

Enterprise : L'édition de transcription et la régénération sont disponibles uniquement pour les espaces de travail Enterprise. La création de projets, l'ajout de langues et le téléchargement de doublages fonctionnent sur tous les plans.

Flux de travail

1. Créez le projet à partir d'un fichier ou d'une URL → queued
2. Interrogez le projet jusqu'à ready
3. Révisez et finalisez la transcription source (éditer/ajouter/supprimer des segments)
4. Ajoutez une langue par cible → queued → processing → completed
5. Téléchargez le outputs.lossless_audio de chaque langue une fois completed
6. Affinez les traductions par segment si nécessaire → la langue passe stale
7. Régénérez la langue → completed à nouveau avec une sortie fraîche

Démarrage rapide (Python)

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

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

# 1. Créez un projet à partir d'un fichier local (ou passez source_url=... au lieu de file)
with open("promo.mp4", "rb") as f:
    project = elevenlabs.dubbing.project.create(
        file=f,
        source_language="en",
        reference="Vidéo marketing Q3",
    )

# 2. Attendez que le média source soit transcrit
while True:
    project = elevenlabs.dubbing.project.get(project.project_id)
    if project.status == "ready":
        break
    if project.status == "failed":
        raise RuntimeError("La préparation du projet a échoué")
    time.sleep(5)

# 3. Ajoutez une langue cible espagnole
language = elevenlabs.dubbing.project.language.create(
    project.project_id,
    target_language="es",
)

# 4. Attendez que le doublage soit généré
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("La génération du doublage a échoué")
    time.sleep(5)

# 5. Téléchargez l'audio doublé (URL signée, valide ~1 heure — récupérez la langue pour une URL fraîche)
audio = requests.get(language.outputs.lossless_audio)
with open("promo_es.wav", "wb") as f:
    f.write(audio.content)

Démarrage rapide (JavaScript)

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

const elevenlabs = new ElevenLabsClient();

// 1. Créez un projet (sourceUrl montré ; le téléversement de fichier est également pris en charge)
let project = await elevenlabs.dubbing.project.create({
  sourceUrl: "https://example.com/promo.mp4",
  sourceLanguage: "en",
  reference: "Vidéo marketing Q3",
});

// 2. Attendez que le média source soit transcrit
while (true) {
  project = await elevenlabs.dubbing.project.get(project.projectId);
  if (project.status === "ready") break;
  if (project.status === "failed") throw new Error("La préparation du projet a échoué");
  await new Promise((resolve) => setTimeout(resolve, 5000));
}

// 3. Ajoutez une langue cible espagnole
let language = await elevenlabs.dubbing.project.language.create(project.projectId, {
  targetLanguage: "es",
});

// 4. Attendez que le doublage soit généré
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("La génération du doublage a échoué");
  await new Promise((resolve) => setTimeout(resolve, 5000));
}

// 5. Téléchargez l'audio doublé depuis l'URL signée
const response = await fetch(language.outputs!.losslessAudio!);
await writeFile("promo_es.wav", Buffer.from(await response.arrayBuffer()));

Démarrage rapide (CLI)

Le CLI elevenlabs lit ELEVENLABS_API_KEY depuis l'environnement automatiquement.

# 1. Créez un projet (utilisez --source-url "https://..." au lieu de --file pour doubler depuis une URL)
elevenlabs dubbing project create --file promo.mp4 --source-language en
# → {"project_id": "proj_...", "status": "queued", ...}

# 2. Interrogez jusqu'à ce que le statut soit "ready"
elevenlabs dubbing project get --project-id proj_...

# 3. Ajoutez une langue cible
elevenlabs dubbing project language create --project-id proj_... --target-language es

# 4. Interrogez la langue jusqu'à "completed", puis téléchargez outputs.lossless_audio
elevenlabs dubbing project language get --project-id proj_... --language-id lang_...

Options de création

elevenlabs dubbing project create (REST : POST /v1/dubbing/project, multipart/form-data) prend soit file soit source_url (pas les deux) :

Champ	Requis	Notes
file	l'un de file/source_url	Média source à doubler (audio ou vidéo), jusqu'à 3 GiB
source_url	l'un de file/source_url	URL publique pour récupérer le média source
source_language	non	Code ISO 639 (par exemple en). Omettez pour détection automatique — la langue détectée est rapportée dans le champ language de la transcription source
reference	non	Libellé libre pour identifier le projet (max 500 caractères)
model_id	non	dubbing_v2 (par défaut)
target_language	non	Optionnellement mettre en file d'attente la première langue cible à la création ; ajoutez-en d'autres avec language.create
keyterms	non	Termes pour biaiser la transcription/traduction (noms de produits/marques). Jusqu'à 1000 termes ; chaque terme au plus 50 caractères et 5 mots ; <>{}[]\ non autorisés. Répétez le champ une fois par terme en multipart

Édition de la transcription source

Une fois que le projet est ready, lisez la transcription, puis corrigez-la avant d'ajouter des langues. Chaque modification augmente la revision du projet. Chaque segment a un id stable utilisé pour le modifier ou le supprimer. (Espaces de travail Enterprise uniquement.)

# Lire la transcription source
transcript = elevenlabs.dubbing.project.transcript.get(project_id)

# Corriger le texte d'un segment — envoyer uniquement les champs à modifier (text, speaker_id, start_s, end_s)
elevenlabs.dubbing.project.transcript.update_segment(
    project_id,
    segment_id=transcript.segments[0].id,
    text="Bienvenue dans notre dernière démonstration produit.",
)

# Ajouter un segment (réutiliser un speaker_id existant pour que le doublage utilise la voix de ce locuteur)
added = elevenlabs.dubbing.project.transcript.create_segment(
    project_id,
    text="Merci d'avoir regardé.",
    speaker_id=transcript.segments[0].speaker_id,
    start_s=40.0,
    end_s=42.0,
)

# Supprimer un segment
elevenlabs.dubbing.project.transcript.delete_segment(project_id, segment_id=added.segment.id)

Via le CLI : elevenlabs dubbing project transcript get --project-id proj_..., puis mettez à jour un segment avec uniquement les champs modifiés (--text, --speaker-id, --start-s, --end-s) :

elevenlabs dubbing project transcript update_segment \
  --project-id proj_... --segment-id seg_... \
  --text "Bienvenue dans notre dernière démonstration produit."

Affinage des traductions et régénération

La transcription d'une langue associe chaque segment source à sa traduction (null = pas encore traduit ; les identifiants de segment correspondent à la source). Modifiez une seule traduction, puis régénérez. (Espaces de travail Enterprise uniquement.)

# Lire les traductions de la langue
target = elevenlabs.dubbing.project.language.transcript.get(project_id, language_id)

# Affiner une seule traduction (passer translation=None pour l'effacer et la marquer pour retraduction)
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.",
)

# Régénérer le doublage à partir de la transcription actuelle (facturé comme une génération)
elevenlabs.dubbing.project.language.transcript.regenerate(project_id, language_id)

Via le CLI : elevenlabs dubbing project language transcript update_segment --project-id proj_... --language-id lang_... --segment-id seg_... --translation "...", puis elevenlabs dubbing project language transcript regenerate --project-id proj_... --language-id lang_... (renvoie 202 Accepted).

Une modification de traduction n'affecte que cette langue. Après la modification, une langue completed devient stale — elle continue de servir sa sortie précédente jusqu'à la régénération. Interrogez jusqu'à completed ; output_revision est alors égal à revision et outputs.lossless_audio reflète la transcription actuelle.

Doublage en plusieurs langues

Ajoutez une langue cible par langue — chacune se génère indépendamment. Suivez-les toutes avec language.list au lieu d'interroger une par une :

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)

États

Projet :

Statut	Signification
queued	Créé ; récupération source + préparation en file d'attente
preparing	Préparation (transcription) en cours
ready	Transcription source disponible ; ajoutez/générez des langues. Les projets restent ready — la progression par langue vit sur les langues
failed	La préparation a échoué (par exemple, la source n'a pas pu être récupérée ou décodée)

Langue :

Statut	Signification
queued	En attente du passage du projet à ready, ou d'un worker de génération
processing	Le doublage est en cours de génération
completed	Terminé ; outputs renseigné avec une URL de téléchargement signée (valide ~1 heure — récupérez à nouveau pour une URL fraîche)
stale	Précédemment terminé, mais la transcription a changé ; conserve la dernière sortie jusqu'à régénération
failed	La génération a échoué

Vous pouvez ajouter une langue avant que le projet ne soit ready — elle reste queued et démarre automatiquement une fois le projet ready. L'ajout d'une langue accepte un model_id optionnel (par défaut celui du projet) et des voice_settings (par exemple {"cloning_strength": 7}, plage 0–10, par défaut 7 — contrôle la force avec laquelle les voix des locuteurs doublés clonent les voix source).

Gestion des erreurs

• 401 : Clé API invalide
• 409 Conflit lors de la régénération : Le projet n'est pas ready ou la langue n'est pas stable (par exemple déjà en cours de génération) — attendez et réessayez
• URL de téléchargement expirée : outputs.lossless_audio est signé et valide ~1 heure ; récupérez la langue pour une URL fraîche
• Édition de transcription / régénération indisponible : Ces endpoints sont réservés à Enterprise — sur d'autres plans, créez le projet avec une source finalisée et ajoutez les langues directement

Références

• Guide d'installation
• Référence API — chaque endpoint avec les schémas de requête/réponse complets et les noms de méthodes SDK