ElevenLabs Dubbing

Doblaje con ElevenLabs

Dobla audio o video a otros idiomas mientras preservas las voces de los hablantes originales. Crea un proyecto desde un archivo o URL, revisa y edita la transcripción fuente, agrega uno o más idiomas objetivo, refina las traducciones por segmento y regenera las salidas.

Importante: Usa la API de Proyectos de Doblaje — elevenlabs.dubbing.project.* en los SDKs, o los endpoints REST /v1/dubbing/project. No uses la superficie de doblaje v1 heredada (client.dubbing.create(), client.dubbing.get(), client.dubbing.audio.get(), o rutas /v1/dubbing simples) — esa es la API de doblaje anterior, ahora en Heredado en la referencia de la API.

Configuración, antes de escribir cualquier código: si ELEVENLABS_API_KEY no está configurada para este proyecto, ejecuta npx -y @elevenlabs/cli@latest onboard init desde la carpeta de la aplicación primero y sigue lo que imprime: inicia sesión del usuario y almacena una clave para el proyecto, para que nadie la copie manualmente. De lo contrario, consulta la Guía de Instalación. La CLI de elevenlabs y los SDKs leen ELEVENLABS_API_KEY automáticamente; la URL base REST es https://api.elevenlabs.io con tu clave API en el encabezado xi-api-key.

Conceptos

Concepto	Significado
Proyecto	Una fuente de medios (archivo o URL) más su transcripción fuente. Preparado (transcrito) una vez, luego permanece en ready mientras agregas idiomas.
Transcripción fuente	Segmentos editables (texto, hablante, tiempo) transcritos desde la fuente. La única fuente de verdad desde la que se traduce cada idioma.
Idioma (objetivo)	Un idioma de salida doblado. Cada uno tiene su propia transcripción (segmentos fuente + una traducción por segmento) y su propia salida de audio doblado.
Revisiones	Contadores monótonos independientes. La revision del proyecto aumenta con ediciones en la transcripción fuente; la revision de un idioma aumenta con ediciones de traducción o ediciones fuente que lo afectan. El output_revision de un idioma es la revisión con la que se generó su audio actual — cuando está detrás de revision, la salida está desactualizada.

Orden de operaciones recomendado: finaliza la transcripción fuente antes de agregar idiomas. Las traducciones se producen a partir de la fuente, por lo que corregir la fuente primero significa que cada idioma comienza con el texto correcto — editar la fuente después de que un idioma se complete lo marca como stale y requiere una regeneración (con costo).

Empresarial: La edición de transcripciones y la regeneración están disponibles solo para espacios de trabajo empresariales. La creación de proyectos, la adición de idiomas y la descarga de doblajes funcionan en todos los planes.

Flujo de trabajo

1. Crear el proyecto desde un archivo o URL → queued
2. Consultar el proyecto hasta que esté ready
3. Revisar y finalizar la transcripción fuente (editar/agregar/eliminar segmentos)
4. Agregar un idioma por objetivo → queued → processing → completed
5. Descargar los outputs.lossless_audio de cada idioma cuando esté completed
6. Refinar las traducciones por segmento si es necesario → el idioma pasa a stale
7. Regenerar el idioma → completed nuevamente con salida fresca

Inicio Rápido (Python)

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

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

# 1. Crear un proyecto desde un archivo local (o pasa source_url=... en lugar de file)
with open("promo.mp4", "rb") as f:
    project = elevenlabs.dubbing.project.create(
        file=f,
        source_language="en",
        reference="Video promocional Q3",
    )

# 2. Esperar a que el medio fuente sea transcrito
while True:
    project = elevenlabs.dubbing.project.get(project.project_id)
    if project.status == "ready":
        break
    if project.status == "failed":
        raise RuntimeError("La preparación del proyecto falló")
    time.sleep(5)

# 3. Agregar un idioma objetivo español
language = elevenlabs.dubbing.project.language.create(
    project.project_id,
    target_language="es",
)

# 4. Esperar a que termine la generación del doblaje
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 generación del doblaje falló")
    time.sleep(5)

# 5. Descargar el audio doblado (URL firmada, válida ~1 hora — vuelve a obtener el idioma para una nueva)
audio = requests.get(language.outputs.lossless_audio)
with open("promo_es.wav", "wb") as f:
    f.write(audio.content)

Inicio Rápido (JavaScript)

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

const elevenlabs = new ElevenLabsClient();

// 1. Crear un proyecto (sourceUrl mostrado; también se admite carga de archivos)
let project = await elevenlabs.dubbing.project.create({
  sourceUrl: "https://example.com/promo.mp4",
  sourceLanguage: "en",
  reference: "Video promocional Q3",
});

// 2. Esperar a que el medio fuente sea transcrito
while (true) {
  project = await elevenlabs.dubbing.project.get(project.projectId);
  if (project.status === "ready") break;
  if (project.status === "failed") throw new Error("La preparación del proyecto falló");
  await new Promise((resolve) => setTimeout(resolve, 5000));
}

// 3. Agregar un idioma objetivo español
let language = await elevenlabs.dubbing.project.language.create(project.projectId, {
  targetLanguage: "es",
});

// 4. Esperar a que termine la generación del doblaje
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 generación del doblaje falló");
  await new Promise((resolve) => setTimeout(resolve, 5000));
}

// 5. Descargar el audio doblado desde la URL firmada
const response = await fetch(language.outputs!.losslessAudio!);
await writeFile("promo_es.wav", Buffer.from(await response.arrayBuffer()));

Inicio Rápido (CLI)

La CLI de elevenlabs lee ELEVENLABS_API_KEY del entorno automáticamente.

# 1. Crear un proyecto (usa --source-url "https://..." en lugar de --file para doblar desde una URL)
elevenlabs dubbing project create --file promo.mp4 --source-language en
# → {"project_id": "proj_...", "status": "queued", ...}

# 2. Consultar hasta que el estado sea "ready"
elevenlabs dubbing project get --project-id proj_...

# 3. Agregar un idioma objetivo
elevenlabs dubbing project language create --project-id proj_... --target-language es

# 4. Consultar el idioma hasta que esté "completed", luego descargar outputs.lossless_audio
elevenlabs dubbing project language get --project-id proj_... --language-id lang_...

Opciones de Creación

elevenlabs dubbing project create (REST: POST /v1/dubbing/project, multipart/form-data) toma file o source_url (no ambos):

Campo	Requerido	Notas
file	uno de file/source_url	Medio fuente a doblar (audio o video), hasta 3 GiB
source_url	uno de file/source_url	URL pública para obtener el medio fuente
source_language	no	Código ISO 639 (ej. en). Omitir para detección automática — el idioma detectado se reporta en el campo language de la transcripción fuente
reference	no	Etiqueta libre para identificar el proyecto (máx. 500 caracteres)
model_id	no	dubbing_v2 (predeterminado)
target_language	no	Opcionalmente encolar el primer idioma objetivo al crear; agregar más con language.create
keyterms	no	Términos para sesgar la transcripción/traducción (nombres de productos/marcas). Hasta 1000 términos; cada uno máximo 50 caracteres y 5 palabras; no se permiten <>{}[]\. Repite el campo una vez por término en multipart

Editar la Transcripción Fuente

Una vez que el proyecto está ready, lee la transcripción, luego corrígela antes de agregar idiomas. Cada edición aumenta la revision del proyecto. Cada segmento tiene un id estable usado para editarlo o eliminarlo. (Solo espacios de trabajo empresariales.)

# Leer la transcripción fuente
transcript = elevenlabs.dubbing.project.transcript.get(project_id)

# Corregir el texto de un segmento — enviar solo los campos a cambiar (text, speaker_id, start_s, end_s)
elevenlabs.dubbing.project.transcript.update_segment(
    project_id,
    segment_id=transcript.segments[0].id,
    text="Bienvenidos a nuestra última demostración de producto.",
)

# Agregar un segmento (reutiliza un speaker_id existente para que se doble con la voz de ese hablante)
added = elevenlabs.dubbing.project.transcript.create_segment(
    project_id,
    text="Gracias por ver.",
    speaker_id=transcript.segments[0].speaker_id,
    start_s=40.0,
    end_s=42.0,
)

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

A través de la CLI: elevenlabs dubbing project transcript get --project-id proj_..., luego actualiza un segmento solo con los campos cambiados (--text, --speaker-id, --start-s, --end-s):

elevenlabs dubbing project transcript update_segment \
  --project-id proj_... --segment-id seg_... \
  --text "Bienvenidos a nuestra última demostración de producto."

Refinar Traducciones y Regenerar

La transcripción de un idioma empareja cada segmento fuente con su translation (null = aún no traducido; los ids de segmento coinciden con la fuente). Edita una sola traducción, luego regenera. (Solo espacios de trabajo empresariales.)

# Leer las traducciones del idioma
target = elevenlabs.dubbing.project.language.transcript.get(project_id, language_id)

# Refinar una sola traducción (pasa translation=None para limpiarla y marcar para retraducción)
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.",
)

# Regenerar el doblaje desde la transcripción actual (con costo como una generación)
elevenlabs.dubbing.project.language.transcript.regenerate(project_id, language_id)

A través de la CLI: elevenlabs dubbing project language transcript update_segment --project-id proj_... --language-id lang_... --segment-id seg_... --translation "...", luego elevenlabs dubbing project language transcript regenerate --project-id proj_... --language-id lang_... (devuelve 202 Accepted).

Una edición de traducción afecta solo a ese idioma. Después de la edición, un idioma completed se vuelve stale — sigue sirviendo su salida anterior hasta que regeneres. Consulta hasta que esté completed; output_revision entonces es igual a revision y outputs.lossless_audio refleja la transcripción actual.

Doblaje a Múltiples Idiomas

Agrega un idioma objetivo por idioma — cada uno se genera de forma independiente. Rastréalos todos con language.list en lugar de consultar uno por uno:

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)

Estados

Proyecto:

Estado	Significado
queued	Creado; obtención y preparación de fuente encoladas
preparing	Preparación (transcripción) en ejecución
ready	Transcripción fuente disponible; agregar/generar idiomas. Los proyectos permanecen ready — el progreso por idioma vive en los idiomas
failed	Preparación falló (ej. fuente no pudo obtenerse o decodificarse)

Idioma:

Estado	Significado
queued	Esperando a que el proyecto esté ready, o a un trabajador de generación
processing	El doblaje se está generando
completed	Terminado; outputs poblado con una URL de descarga firmada (válida ~1 hora — vuelve a obtener para una nueva)
stale	Anteriormente completado, pero la transcripción cambió; mantiene la última salida hasta que se regenere
failed	Generación falló

Puedes agregar un idioma antes de que el proyecto esté ready — permanece queued y comienza automáticamente una vez que el proyecto se vuelve ready. Agregar un idioma acepta opcionalmente model_id (por defecto el del proyecto) y voice_settings (ej. {"cloning_strength": 7}, rango 0–10, por defecto 7 — controla cuán fuertemente los hablantes doblados clonan las voces fuente).

Manejo de Errores

• 401: Clave API inválida
• 409 Conflict en regenerate: El proyecto no está ready o el idioma no está estable (ej. ya generando) — espera y reintenta
• URL de descarga expirada: outputs.lossless_audio está firmada y es válida ~1 hora; vuelve a obtener el idioma para una URL nueva
• Edición de transcripción / regeneración no disponible: Estos endpoints son solo empresariales — en otros planes, crea el proyecto con una fuente finalizada y agrega idiomas directamente

Referencias

• Guía de Instalación
• Referencia de API — cada endpoint con esquemas completos de solicitud/respuesta y nombres de métodos SDK