elevenlabs/skills

Dublagem ElevenLabs

Duble áudio ou vídeo em outros idiomas enquanto preserva as vozes originais dos falantes. Crie um projeto a partir de um arquivo ou URL, revise e edite a transcrição fonte, adicione um ou mais idiomas-alvo, refine traduções por segmento e regenere as saídas.

Importante: Use a API de Dubbing Projects — elevenlabs.dubbing.project.* nos SDKs, ou os endpoints REST /v1/dubbing/project. Não use a superfície legada de dublagem v1 (client.dubbing.create(), client.dubbing.get(), client.dubbing.audio.get(), ou rotas /v1/dubbing simples) — essa é a API de dublagem mais antiga, agora em Legacy na referência da API.

Configuração, antes de escrever qualquer código: se ELEVENLABS_API_KEY não estiver definida para este projeto, execute npx -y @elevenlabs/cli@latest onboard init a partir da pasta do aplicativo primeiro e siga o que ele imprime: ele autentica o usuário e armazena uma chave para o projeto, para que ninguém a copie manualmente. Caso contrário, veja o Guia de Instalação. A CLI elevenlabs e os SDKs leem ELEVENLABS_API_KEY automaticamente; a URL base REST é https://api.elevenlabs.io com sua chave de API no cabeçalho xi-api-key.

Conceitos

Conceito	Significado
Projeto	Uma fonte de mídia (arquivo ou URL) mais sua transcrição fonte. Preparada (transcrita) uma vez, então permanece em ready enquanto você adiciona idiomas.
Transcrição fonte	Segmentos editáveis (texto, falante, tempo) transcritos da fonte. A única fonte da verdade da qual cada idioma é traduzido.
Idioma (alvo)	Um idioma de saída dublado. Cada um tem sua própria transcrição (segmentos fonte + uma tradução por segmento) e sua própria saída de áudio dublado.
Revisões	Contadores monotônicos independentes. A revision do projeto aumenta com edições na transcrição fonte; a revision de um idioma aumenta com edições de tradução ou edições na fonte que o afetam. A output_revision de um idioma é a revisão a partir da qual seu áudio atual foi gerado — quando está atrás da revision, a saída está desatualizada.

Ordem recomendada de operações: finalize a transcrição fonte antes de adicionar qualquer idioma. As traduções são produzidas a partir da fonte, então corrigir a fonte primeiro significa que cada idioma começa a partir do texto correto — editar a fonte após um idioma ser concluído o marca como stale e requer uma regeneração (cobrada).

Enterprise: A edição de transcrição e regeneração estão disponíveis apenas para workspaces enterprise. Criar projetos, adicionar idiomas e baixar dublagens funcionam em todos os planos.

Fluxo de Trabalho

1. Crie o projeto a partir de um arquivo ou URL → queued
2. Aguarde o projeto até ready
3. Revise e finalize a transcrição fonte (edite/adicione/exclua segmentos)
4. Adicione um idioma por alvo → queued → processing → completed
5. Baixe o outputs.lossless_audio de cada idioma quando completed
6. Refine as traduções por segmento, se necessário → o idioma vai para stale
7. Regenere o idioma → completed novamente com saída nova

Início Rápido (Python)

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

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

# 1. Crie um projeto a partir de um arquivo local (ou passe source_url=... em vez de file)
with open("promo.mp4", "rb") as f:
    project = elevenlabs.dubbing.project.create(
        file=f,
        source_language="en",
        reference="Vídeo de marketing Q3",
    )

# 2. Aguarde até que a mídia fonte seja transcrita
while True:
    project = elevenlabs.dubbing.project.get(project.project_id)
    if project.status == "ready":
        break
    if project.status == "failed":
        raise RuntimeError("Falha na preparação do projeto")
    time.sleep(5)

# 3. Adicione um idioma alvo em espanhol
language = elevenlabs.dubbing.project.language.create(
    project.project_id,
    target_language="es",
)

# 4. Aguarde até que a dublagem termine de ser gerada
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("Falha na geração da dublagem")
    time.sleep(5)

# 5. Baixe o áudio dublado (URL assinada, válida ~1 hora — reobtenha o idioma para uma nova)
audio = requests.get(language.outputs.lossless_audio)
with open("promo_es.wav", "wb") as f:
    f.write(audio.content)

Início Rápido (JavaScript)

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

const elevenlabs = new ElevenLabsClient();

// 1. Crie um projeto (sourceUrl mostrado; upload de arquivo também é suportado)
let project = await elevenlabs.dubbing.project.create({
  sourceUrl: "https://example.com/promo.mp4",
  sourceLanguage: "en",
  reference: "Vídeo de marketing Q3",
});

// 2. Aguarde até que a mídia fonte seja transcrita
while (true) {
  project = await elevenlabs.dubbing.project.get(project.projectId);
  if (project.status === "ready") break;
  if (project.status === "failed") throw new Error("Falha na preparação do projeto");
  await new Promise((resolve) => setTimeout(resolve, 5000));
}

// 3. Adicione um idioma alvo em espanhol
let language = await elevenlabs.dubbing.project.language.create(project.projectId, {
  targetLanguage: "es",
});

// 4. Aguarde até que a dublagem termine de ser gerada
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("Falha na geração da dublagem");
  await new Promise((resolve) => setTimeout(resolve, 5000));
}

// 5. Baixe o áudio dublado da URL assinada
const response = await fetch(language.outputs!.losslessAudio!);
await writeFile("promo_es.wav", Buffer.from(await response.arrayBuffer()));

Início Rápido (CLI)

A CLI elevenlabs lê ELEVENLABS_API_KEY do ambiente automaticamente.

# 1. Crie um projeto (use --source-url "https://..." em vez de --file para dublar a partir de uma URL)
elevenlabs dubbing project create --file promo.mp4 --source-language en
# → {"project_id": "proj_...", "status": "queued", ...}

# 2. Aguarde até que o status seja "ready"
elevenlabs dubbing project get --project-id proj_...

# 3. Adicione um idioma alvo
elevenlabs dubbing project language create --project-id proj_... --target-language es

# 4. Aguarde o idioma até "completed", depois baixe outputs.lossless_audio
elevenlabs dubbing project language get --project-id proj_... --language-id lang_...

Opções de Criação

elevenlabs dubbing project create (REST: POST /v1/dubbing/project, multipart/form-data) aceita ou file ou source_url (não ambos):

Campo	Obrigatório	Notas
file	um de file/source_url	Mídia fonte a dublar (áudio ou vídeo), até 3 GiB
source_url	um de file/source_url	URL pública para buscar a mídia fonte
source_language	não	Código ISO 639 (ex.: en). Omita para detecção automática — o idioma detectado é relatado no campo language da transcrição fonte
reference	não	Rótulo livre para identificar o projeto (máx. 500 caracteres)
model_id	não	dubbing_v2 (padrão)
target_language	não	Opcionalmente prepare o primeiro idioma alvo na criação; adicione mais com language.create
keyterms	não	Termos para enviesar a transcrição/tradução (nomes de produtos/marcas). Até 1000 termos; cada um com no máximo 50 caracteres e 5 palavras; <>{}[]\ não permitidos. Repita o campo uma vez por termo em multipart

Editando a Transcrição Fonte

Quando o projeto estiver ready, leia a transcrição e corrija-a antes de adicionar idiomas. Cada edição aumenta a revision do projeto. Cada segmento tem um id estável usado para editá-lo ou excluí-lo. (Apenas workspaces enterprise.)

# Leia a transcrição fonte
transcript = elevenlabs.dubbing.project.transcript.get(project_id)

# Corrija o texto de um segmento — envie apenas os campos a alterar (text, speaker_id, start_s, end_s)
elevenlabs.dubbing.project.transcript.update_segment(
    project_id,
    segment_id=transcript.segments[0].id,
    text="Bem-vindo à nossa mais recente demonstração de produto.",
)

# Adicione um segmento (reutilize um speaker_id existente para que seja dublado com a voz daquele falante)
added = elevenlabs.dubbing.project.transcript.create_segment(
    project_id,
    text="Obrigado por assistir.",
    speaker_id=transcript.segments[0].speaker_id,
    start_s=40.0,
    end_s=42.0,
)

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

Via CLI: elevenlabs dubbing project transcript get --project-id proj_..., em seguida, atualize um segmento com apenas os campos alterados (--text, --speaker-id, --start-s, --end-s):

elevenlabs dubbing project transcript update_segment \
  --project-id proj_... --segment-id seg_... \
  --text "Bem-vindo à nossa mais recente demonstração de produto."

Refinando Traduções e Regenerando

A transcrição de um idioma emparelha cada segmento fonte com sua translation (null = ainda não traduzido; ids de segmento correspondem à fonte). Edite uma única tradução e depois regenere. (Apenas workspaces enterprise.)

# Leia as traduções do idioma
target = elevenlabs.dubbing.project.language.transcript.get(project_id, language_id)

# Refine uma única tradução (passe translation=None para limpá-la e marcá-la para retradução)
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.",
)

# Regenerate o dub a partir da transcrição atual (cobrado como uma geração)
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 "...", depois elevenlabs dubbing project language transcript regenerate --project-id proj_... --language-id lang_... (retorna 202 Accepted).

Uma edição de tradução afeta apenas aquele idioma. Após a edição, um idioma completed se torna stale — ele continua servindo sua saída anterior até que você regenere. Aguarde até completed; output_revision então será igual a revision e outputs.lossless_audio refletirá a transcrição atual.

Dublagem em Vários Idiomas

Adicione um idioma alvo por idioma — cada um gera independentemente. Rastreie todos com language.list em vez de consultar um por um:

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

Projeto:

Status	Significado
queued	Criado; busca da fonte + preparação enfileirada
preparing	Preparação (transcrição) em execução
ready	Transcrição fonte disponível; adicione/gere idiomas. Projetos permanecem ready — o progresso por idioma está nos idiomas
failed	Preparação falhou (ex.: fonte não pôde ser buscada ou decodificada)

Idioma:

Status	Significado
queued	Aguardando o projeto se tornar ready, ou um trabalhador de geração
processing	A dublagem está sendo gerada
completed	Concluído; outputs preenchido com uma URL de download assinada (válida ~1 hora — reobtenha para uma nova)
stale	Anteriormente concluído, mas a transcrição mudou; mantém a última saída até ser regenerado
failed	Geração falhou

Você pode adicionar um idioma antes do projeto estar ready — ele permanece queued e inicia automaticamente quando o projeto se torna ready. Adicionar um idioma aceita model_id opcional (padrão é o do projeto) e voice_settings (ex.: {"cloning_strength": 7}, intervalo 0–10, padrão 7 — controla o quanto os falantes dublados clonam as vozes fonte).

Tratamento de Erros

• 401: Chave de API inválida
• 409 Conflict na regeneração: O projeto não está ready ou o idioma não está estabelecido (ex.: já gerando) — aguarde e tente novamente
• URL de download expirada: outputs.lossless_audio é assinada e válida ~1 hora; reobtenha o idioma para uma URL nova
• Edição de transcrição / regeneração indisponível: Esses endpoints são apenas para enterprise — em outros planos, crie o projeto com uma fonte finalizada e adicione idiomas diretamente

Referências

• Guia de Instalação
• Referência da API — todos os endpoints com esquemas completos de requisição/resposta e nomes de métodos SDK