> For the documentation index, fetch https://sync.so/docs/llms.txt. Append .md to a page URL for Markdown. Documentation-search MCP: https://sync.so/docs/_mcp/server.

# Guia da API de Dublagem de Vídeo

> Guia passo a passo para construir um pipeline de dublagem de vídeo com a API de lip sync da sync. labs. Combine TTS com lipsync para dublagem multilíngue usando Python ou TypeScript.

A dublagem de vídeo combina áudio traduzido com vídeo sincronizado nos lábios para que o conteúdo dublado pareça natural no idioma alvo. Você pode usar o fluxo de dublagem embutido da Sync Labs com `dubParams`, ou fornecer o áudio traduzido você mesmo e usar a Sync Labs apenas para a etapa de lipsync.

## Pré-requisitos

* Uma [chave de API da Sync Labs](https://sync.so/settings/api-keys)
* Um vídeo fonte (URL ou arquivo enviado)
* Para dublagem embutida: áudio fonte no arquivo de vídeo
* Para dublagem manual: áudio traduzido no idioma alvo (de um serviço TTS ou ator de voz humano)

Instale o SDK para sua linguagem:

```bash
# Python
pip install syncsdk

# TypeScript
npm i @sync.so/sdk
```

Configure sua chave de API:

```bash
export SYNC_API_KEY="your-api-key"
```

## Dublagem via API embutida com `dubParams`

Use `dubParams` quando quiser que a Sync Labs extraia o áudio fonte do vídeo, traduza e duble via ElevenLabs, e então execute o lipsync no resultado dublado. Este é o caminho mais simples quando seu vídeo de entrada já possui áudio fonte.

Quando `dubParams` estiver presente:

* forneça uma única entrada `video` com áudio
* defina `dubParams.targetLang` para o código do idioma alvo, como `"es"`, `"fr"` ou `"hi"`
* opcionalmente defina `dubParams.sourceLang`; omita ou use `"auto"` para detecção automática do idioma fonte
* `dubParams.numSpeakers` está obsoleto e é ignorado  -  Dublagem v2 detecta os falantes automaticamente
* não inclua uma entrada de áudio separada para a faixa traduzida; entradas de áudio são ignoradas enquanto a dublagem estiver ativada

**`dub_with_params.ts`**

```typescript dub_with_params.ts
import { SyncClient } from "@sync.so/sdk";

const sync = new SyncClient();

const response = await sync.generations.create({
    input: [
        {
            type: "video",
            url: "https://your-cdn.com/original-video-with-audio.mp4",
        },
    ],
    model: "lipsync-2",
    dubParams: {
        providerName: "elevenlabs",
        targetLang: "es",
        sourceLang: "auto",
    },
});

console.log(`Dubbing job submitted: ${response.id}`);
```

> **Note**
>
> A dublagem embutida é suportada pela ElevenLabs. Se o vídeo não tiver áudio fonte utilizável, forneça seu próprio áudio traduzido e siga o pipeline manual abaixo.

## Pipeline Manual de Dublagem

#### Prepare seu áudio traduzido

Gere áudio traduzido usando um serviço de texto para fala como ElevenLabs, Google Cloud TTS ou Amazon Polly. Você também pode usar um ator de voz humano. O áudio deve estar hospedado em uma URL publicamente acessível.

Se você já tem um arquivo de áudio traduzido, faça o upload para seu serviço de hospedagem e obtenha a URL.

#### Envie para a API da Sync Labs

Envie o vídeo fonte e o áudio traduzido para a API da Sync Labs. A API gera novos movimentos labiais que correspondem ao áudio traduzido.

**`dub.ts`**

```typescript dub.ts
import { SyncClient } from "@sync.so/sdk";

const sync = new SyncClient();

// Source video with original language
const videoUrl = "https://your-cdn.com/original-video.mp4";
// Translated audio in target language
const dubbedAudioUrl = "https://your-cdn.com/translated-audio-spanish.wav";

const response = await sync.generations.create({
    input: [
        { type: "video", url: videoUrl },
        { type: "audio", url: dubbedAudioUrl },
    ],
    model: "lipsync-2",
    options: { sync_mode: "cut_off" },
});

const jobId = response.id;
console.log(`Dubbing job submitted: ${jobId}`);
```

**`dub.py`**

```python dub.py
import time
from sync import Sync
from sync.common import Audio, Video, GenerationOptions

sync = Sync()

# Source video with original language
video_url = "https://your-cdn.com/original-video.mp4"
# Translated audio in target language
dubbed_audio_url = "https://your-cdn.com/translated-audio-spanish.wav"

response = sync.generations.create(
    input=[
        Video(url=video_url),
        Audio(url=dubbed_audio_url),
    ],
    model="lipsync-2",
    options=GenerationOptions(sync_mode="cut_off"),
)

job_id = response.id
print(f"Dubbing job submitted: {job_id}")
```

#### Verifique o status até a conclusão

Verifique o status da geração até que ela seja concluída. Para sistemas de produção, use [webhooks](/api-reference/guides/webhooks) em vez de polling.

```typescript
let generation = await sync.generations.get(jobId);
while (!["COMPLETED", "FAILED", "REJECTED"].includes(generation.status)) {
    console.log(`Status: ${generation.status}`);
    await new Promise((r) => setTimeout(r, 10000));
    generation = await sync.generations.get(jobId);
}

if (generation.status === "COMPLETED") {
    console.log(`Dubbed video ready: ${generation.outputUrl}`);
} else {
    console.log(`Dubbing failed for job ${jobId}`);
}
```

```python
generation = sync.generations.get(job_id)
while generation.status not in ["COMPLETED", "FAILED", "REJECTED"]:
    print(f"Status: {generation.status}")
    time.sleep(10)
    generation = sync.generations.get(job_id)

if generation.status == "COMPLETED":
    print(f"Dubbed video ready: {generation.output_url}")
else:
    print(f"Dubbing failed for job {job_id}")
```

#### Baixe o vídeo dublado

O `output_url` (Python) ou `outputUrl` (TypeScript) contém um link direto para o vídeo dublado. Baixe-o ou envie para seu pipeline de entrega.

## Usando a Integração ElevenLabs

A Sync Labs possui uma integração embutida com ElevenLabs que lida com texto para fala e lipsync em uma única chamada de API. Em vez de gerar áudio separadamente, você passa o texto traduzido diretamente.

**`dub_with_elevenlabs.ts`**

```typescript dub_with_elevenlabs.ts
import { SyncClient } from "@sync.so/sdk";

const sync = new SyncClient();

const response = await sync.generations.create({
    input: [
        {
            type: "video",
            url: "https://your-cdn.com/original-video.mp4",
        },
        {
            type: "text",
            provider: {
                name: "elevenlabs",
                voiceId: "EXAVITQu4vr4xnSDxMaL",
                script: "Hola, bienvenidos a nuestra plataforma. Hoy les mostraremos las nuevas funciones.",
                stability: 0.5,
                similarityBoost: 0.75,
            },
        },
    ],
    model: "lipsync-2",
    options: { sync_mode: "cut_off" },
});

console.log(`Job ID: ${response.id}`);
```

**`dub_with_elevenlabs.py`**

```python dub_with_elevenlabs.py
from sync import Sync
from sync.common import Video, TTS, GenerationOptions

sync = Sync()

response = sync.generations.create(
    input=[
        Video(url="https://your-cdn.com/original-video.mp4"),
        TTS(
            provider={
                "name": "elevenlabs",
                "voiceId": "EXAVITQu4vr4xnSDxMaL",
                "script": "Hola, bienvenidos a nuestra plataforma. Hoy les mostraremos las nuevas funciones.",
                "stability": 0.5,
                "similarityBoost": 0.75,
            }
        ),
    ],
    model="lipsync-2",
    options=GenerationOptions(sync_mode="cut_off"),
)

print(f"Job ID: {response.id}")
```

> **Note**
>
> O campo `script` tem um máximo de 5.000 caracteres por geração. Para scripts mais longos, divida-os em segmentos. Veja a página de [Integrações](/docs/product/integrations) para detalhes da configuração do ElevenLabs.

## Idiomas Suportados

Os modelos de lipsync da Sync Labs são independentes de idioma. Eles funcionam com áudio em qualquer idioma  -  os modelos analisam as formas da boca a partir da forma de onda do áudio, não o idioma em si. Se seu áudio traduzido for claro e bem produzido, a saída do lipsync corresponderá.

Para o fluxo embutido `dubParams`, escolha um dos códigos `targetLang` suportados na Referência da API. Se precisar de um idioma fora dessa lista ou quiser mais controle sobre a tradução, gere ou grave o áudio traduzido separadamente e use o pipeline manual acima.

Para um tutorial completo do pipeline de tradução (transcrição, tradução, TTS e lipsync), veja o [Guia da API de Tradução de Vídeo](/tutorials/video-translation-api-guide).

## Dublagem com Múltiplos Falantes

Para vídeos com múltiplos falantes, use a API de segmentos para atribuir diferentes faixas de áudio a diferentes intervalos de tempo. Cada segmento pode referenciar uma entrada de áudio separada com uma voz distinta.

```python
from sync import Sync
from sync.common import Audio, Video

sync = Sync()

response = sync.generations.create(
    input=[
        Video(url="https://your-cdn.com/interview.mp4"),
        Audio(url="https://your-cdn.com/speaker-a-spanish.wav", ref_id="speaker_a"),
        Audio(url="https://your-cdn.com/speaker-b-spanish.wav", ref_id="speaker_b"),
    ],
    segments=[
        {"startTime": 0, "endTime": 15, "audioInput": {"refId": "speaker_a"}},
        {"startTime": 15, "endTime": 30, "audioInput": {"refId": "speaker_b"}},
    ],
    model="lipsync-2",
)
```

Veja o [Guia de Segmentos](/developer-guides/segments) para documentação completa e mais exemplos.

## Dicas de desempenho

#### Use webhooks para produção

Substitua o polling por [webhooks](/api-reference/guides/webhooks) em pipelines de produção. Você recebe uma notificação POST quando o trabalho é concluído, eliminando chamadas de API desnecessárias.

#### Use processamento em lote para dublagem em massa

Dublando uma biblioteca inteira de vídeos? A [API de lotes](/api-reference/guides/batch-processing) permite enviar até 500 gerações em uma única operação com prazo de 24 horas.

#### Escolha o modelo certo

Use **[lipsync-2](/models/lipsync)** para a maioria dos trabalhos de dublagem. Use **[sync-3](/models/sync-3)** para dublagem com qualidade de produção, cenas complexas, obstruções, ângulos de perfil ou saída 4K. Troque para **[lipsync-2-pro](/models/lipsync)** quando precisar de detalhes faciais premium a um preço menor que o sync-3.

#### Combine a duração do áudio

Defina `sync_mode` para controlar o que acontece quando as durações do áudio e do vídeo diferem. `cut_off` corta o áudio excedente. `bounce` repete o vídeo para combinar a duração do áudio. Veja [modo Sync](/developer-guides/sync-mode) para a matriz completa de comportamentos.