rodrvc/personal-brand

Dublagem ElevenLabs

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

Importante: Use a API de Projetos de Dublagem — elevenlabs.dubbing.project.* nos SDKs, ou os endpoints REST /v1/dubbing/project. Não use a superfície de dublagem legada 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 Legado na referência da API.

Configuração: Veja o Guia de Instalação. A URL base REST é https://api.elevenlabs.io com sua chave API no cabeçalho xi-api-key; os SDKs leem ELEVENLABS_API_KEY automaticamente.

Conceitos

Conceito	Significado
Projeto	Uma fonte de mídia (arquivo ou URL) mais sua transcrição de origem. Preparado (transcrito) uma vez, depois fica em ready enquanto você adiciona idiomas.
Transcrição de origem	Segmentos editáveis (texto, locutor, tempo) transcritos da fonte. A única fonte da verdade a partir da qual cada idioma é traduzido.
Idioma (alvo)	Uma saída de dublagem em um idioma. Cada um tem sua própria transcrição (segmentos de origem + uma tradução por segmento) e seu próprio áudio dublado de saída.
Revisões	Contadores monotônicos independentes. A revision do projeto é incrementada em edições na transcrição de origem; a revision de um idioma é incrementada em edições de tradução ou edições de origem 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 de operações recomendada: finalize a transcrição de origem antes de adicionar qualquer idioma. As traduções são produzidas a partir da origem, então corrigir a origem primeiro significa que cada idioma começa com o texto correto — editar a origem após um idioma ser concluído o marca como stale e requer uma regeneração (cobrada).

Empresarial: Edição de transcrição e regeneração estão disponíveis apenas para contas empresariais. 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. Consulte o projeto até ready
3. Revise e finalize a transcrição de origem (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 fica stale
7. Regenere o idioma → completed novamente com uma nova saída

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 a transcrição da mídia de origem
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 (espanhol)
language = elevenlabs.dubbing.project.language.create(
    project.project_id,
    target_language="es",
)

# 4. Aguarde a conclusão da dublagem
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 por ~1 hora — busque o idioma novamente para uma nova URL)
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://exemplo.com/promo.mp4",
  sourceLanguage: "en",
  reference: "Vídeo de marketing Q3",
});

// 2. Aguarde a transcrição da mídia de origem
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 (espanhol)
let language = await elevenlabs.dubbing.project.language.create(project.projectId, {
  targetLanguage: "es",
});

// 4. Aguarde a conclusão da dublagem
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 (cURL)

# 1. Crie um projeto (use -F "source_url=https://..." em vez de file para dublar a partir de uma URL)
curl -X POST "https://api.elevenlabs.io/v1/dubbing/project" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -F "[email protected]" \
  -F "source_language=en"
# → {"project_id": "proj_...", "status": "queued", ...}

# 2. Consulte até o status ser "ready"
curl "https://api.elevenlabs.io/v1/dubbing/project/proj_..." \
  -H "xi-api-key: $ELEVENLABS_API_KEY"

# 3. Adicione um idioma alvo
curl -X POST "https://api.elevenlabs.io/v1/dubbing/project/proj_.../language" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_language": "es"}'

# 4. Consulte o idioma até "completed", então baixe outputs.lossless_audio
curl "https://api.elevenlabs.io/v1/dubbing/project/proj_.../language/lang_..." \
  -H "xi-api-key: $ELEVENLABS_API_KEY"

Opções de Criação

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

Campo	Obrigatório	Notas
file	um de file/source_url	Mídia de origem para dublar (áudio ou vídeo), até 3 GiB
source_url	um de file/source_url	URL pública para buscar a mídia de origem
source_language	não	Código ISO 639 (ex.: en). Omitir para detecção automática — o idioma detectado é informado no campo language da transcrição de origem
reference	não	Rótulo livre para identificar o projeto em seu sistema (máx. 500 caracteres)
model_id	não	dubbing_v2 (padrão)
target_language	não	Opcionalmente, enfileira 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é 100 termos de 200 caracteres cada; repita o campo uma vez por termo em multipart

Editando a Transcrição de Origem

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

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

# Corrija o texto de um segmento — envie apenas os campos a serem alterados (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 desse locutor)
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 REST: GET /v1/dubbing/project/{project_id}/transcript, depois PATCH .../transcript/segment/{segment_id} com apenas os campos alterados:

curl -X PATCH "https://api.elevenlabs.io/v1/dubbing/project/{project_id}/transcript/segment/{segment_id}" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \
  -d '{"text": "Bem-vindo à nossa mais recente demonstração de produto."}'

Refinando Traduções e Regenerando

A transcrição de um idioma emparelha cada segmento de origem com sua translation (null = ainda não traduzido; ids de segmento correspondem aos da origem). Edite uma tradução e, em seguida, regenere. (Apenas contas empresariais.)

# 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 marcar 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.",
)

# Regere a dublagem a partir da transcrição atual (cobrada como uma geração)
elevenlabs.dubbing.project.language.transcript.regenerate(project_id, language_id)

Via REST: PATCH /v1/dubbing/project/{project_id}/language/{language_id}/transcript/segment/{segment_id} com {"translation": "..."}, depois POST .../language/{language_id}/transcript/regenerate (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. Consulte até completed; output_revision então será igual a revision e outputs.lossless_audio refletirá a transcrição atual.

Dublagem em Múltiplos Idiomas

Adicione um idioma alvo por idioma — cada um gera independentemente. Acompanhe 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 enfileirados
preparing	Preparação (transcrição) em execução
ready	Transcrição de origem disponível; adicione/gere idiomas. Projetos permanecem ready — o progresso por idioma reside nos idiomas
failed	Falha na preparação (ex.: a fonte não pôde ser buscada ou decodificada)

Idioma:

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

Você pode adicionar um idioma antes do projeto estar ready — ele fica 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 quão fortemente os locutores dublados clonam as vozes de origem).

Tratamento de Erros

• 401: Chave API inválida
• 409 Conflict ao regenerar: O projeto não está ready ou o idioma não está estabilizado (ex.: já gerando) — aguarde e tente novamente
• URL de download expirado: outputs.lossless_audio é assinado e válido ~1 hora; busque o idioma novamente para uma URL nova
• Edição de transcrição / regeneração indisponível: Esses endpoints são exclusivos para empresas — 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 do SDK