> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# Guia rápido de Dublagem

Este guia mostra como dublar um arquivo de mídia para outro idioma com a API de Dublagem. Neste exemplo, você cria um projeto de dublagem a partir de um arquivo de áudio em inglês e gera uma dublagem em espanhol.

Um projeto de dublagem tem duas partes: um **projeto**, que contém uma mídia de origem e sua transcrição, e um ou mais **idiomas de destino**, cada um produzindo uma saída dublada em um único idioma. Você cria um projeto, espera a transcrição da origem, adiciona um idioma e baixa a dublagem finalizada.

> **Note**
>
> A criação de um projeto cobra antecipadamente por um idioma — a cobrança mínima de um projeto de
> dublagem. Isso paga antecipadamente seu primeiro idioma de destino: o primeiro idioma adicionado o
> consome, e cada idioma adicional é cobrado separadamente. Consulte [Quanto custa a Dublagem?](/docs/pt/help-center/product/dubbing/how-much-does-dubbing-cost) para saber mais.

Os idiomas são especificados como tags BCP-47, por exemplo, `es` ou `fr-CA`. Consulte os [idiomas e dialetos compatíveis](/docs/pt/overview/capabilities/dubbing#supported-languages) para ver todos os valores aceitos.

## Usar a API de Dublagem

#### Criar uma chave de API

[Crie uma chave de API no painel aqui](https://elevenlabs.io/app/settings/api-keys), que você usará para [acessar a API](/docs/pt/api-reference/authentication) com segurança.

Armazene a chave como um segredo gerenciado e passe-a aos SDKs como uma variável de ambiente por meio de um arquivo `.env` ou diretamente na configuração do seu app, conforme sua preferência.

**`.env`**

```js title=".env"
ELEVENLABS_API_KEY=<your_api_key_here>
```

#### Instalar o SDK

#### SDK

Também usaremos a biblioteca `dotenv` para carregar nossa chave de API de uma variável de ambiente.

```python
pip install elevenlabs
pip install python-dotenv
```

```typescript
npm install @elevenlabs/elevenlabs-js
npm install dotenv
```

#### CLI

Instale a CLI da ElevenLabs. Recomendamos Homebrew (macOS) e Scoop (Windows).

**`Homebrew (macOS)`**

```bash title="Homebrew (macOS)"
brew install elevenlabs/tap/elevenlabs
```

**`Scoop (Windows)`**

```powershell title="Scoop (Windows)"
scoop bucket add elevenlabs https://github.com/elevenlabs/scoop-bucket
scoop install elevenlabs
```

**`npm`**

```bash title="npm"
npm install -g @elevenlabs/cli
```

**`curl`**

```bash title="curl"
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/elevenlabs/cli/releases/latest/download/elevenlabs-cli-installer.sh | sh
```

> **Tip**
>
> Está trabalhando com um assistente de programação com IA? Execute `elevenlabs generate-skills` no seu projeto para criar um
> `SKILL.md` para cada grupo de comandos em `skills/`, para que seu assistente conheça toda a superfície da CLI
> sem que você precise colar a documentação. Use `--output-dir` para colocá-los em outro lugar. Isso lê a própria
> definição de API incorporada da CLI, portanto não precisa de chave de API e funciona off-line — além de acompanhar
> a versão da CLI que você tiver instalado.

Em seguida, autentique-se — isso abrirá seu navegador para autorizar a CLI:

```bash
elevenlabs auth login
```

> **Note**
>
> O exemplo em Python usa a biblioteca `requests` para baixar o áudio dublado. Instale-a
> com `pip install requests`.

#### Fazer a solicitação à API

#### SDK

Crie um novo arquivo chamado `example.py` ou `example.mts`, dependendo da linguagem escolhida, e adicione o código a seguir:

```python maxLines=0
# example.py
import os
import time
import requests
from dotenv import load_dotenv
from elevenlabs.client import ElevenLabs

load_dotenv()

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

# 1. Create a project from a source URL
project = elevenlabs.dubbing.project.create(
    source_url="https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3",
    source_language="en",
    reference="Quickstart dub",
)

# 2. Wait for the source media to be transcribed
while True:
    project = elevenlabs.dubbing.project.get(project.project_id)
    if project.status == "ready":
        break
    if project.status == "failed":
        raise RuntimeError("Project preparation failed")
    print("Preparing project...")
    time.sleep(5)

# 3. Add a Spanish language target
language = elevenlabs.dubbing.project.language.create(
    project.project_id,
    target_language="es",
)

# 4. Wait for the dub to finish generating
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("Dub generation failed")
    print("Generating dub...")
    time.sleep(5)

# 5. Download the dubbed audio from the signed URL
audio = requests.get(language.outputs.lossless_audio)
with open("dubbed.wav", "wb") as f:
    f.write(audio.content)

print("Saved dubbed audio to dubbed.wav")
```

```typescript maxLines=0
// example.mts
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import { writeFile } from "fs/promises";
import "dotenv/config";

const elevenlabs = new ElevenLabsClient();

// 1. Create a project from a source URL
let project = await elevenlabs.dubbing.project.create({
  sourceUrl:
    "https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3",
  sourceLanguage: "en",
  reference: "Quickstart dub",
});

// 2. Wait for the source media to be transcribed
while (true) {
  project = await elevenlabs.dubbing.project.get(project.projectId);
  if (project.status === "ready") break;
  if (project.status === "failed") throw new Error("Project preparation failed");
  console.log("Preparing project...");
  await new Promise((resolve) => setTimeout(resolve, 5000));
}

// 3. Add a Spanish language target
let language = await elevenlabs.dubbing.project.language.create(project.projectId, {
  targetLanguage: "es",
});

// 4. Wait for the dub to finish generating
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("Dub generation failed");
  console.log("Generating dub...");
  await new Promise((resolve) => setTimeout(resolve, 5000));
}

// 5. Download the dubbed audio from the signed URL
const response = await fetch(language.outputs!.losslessAudio!);
const buffer = Buffer.from(await response.arrayBuffer());
await writeFile("dubbed.wav", buffer);

console.log("Saved dubbed audio to dubbed.wav");
```

> **Note**
>
> A URL de download em `outputs.lossless_audio` é assinada e expira cerca de uma hora após
> ser emitida. Busque o idioma novamente para obter uma URL nova caso ela tenha expirado.

Em seguida, execute-o:

```python
python example.py
```

```typescript
npx tsx example.mts
```

O áudio dublado é salvo em `dubbed.wav` no seu diretório de trabalho.

#### CLI

A CLI segue o mesmo fluxo. Cada etapa imprime JSON — copie o `project_id` e o
`language_id` das respostas para o próximo comando e consulte os comandos `get`
até o status ser definido.

```bash
# 1. Create a project from a source URL (note the returned project_id)
elevenlabs dubbing project create \
  --source-url https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3 \
  --source-language en \
  --reference "Quickstart dub"

# 2. Poll until the project status is "ready"
elevenlabs dubbing project get --project-id <project_id> --query status

# 3. Add a Spanish language target (note the returned language_id)
elevenlabs dubbing project language create --project-id <project_id> --target-language es

# 4. Poll until the language status is "completed"
elevenlabs dubbing project language get \
  --project-id <project_id> --language-id <language_id> --query status

# 5. Get the signed download URL, then save the dubbed audio
elevenlabs dubbing project language get \
  --project-id <project_id> --language-id <language_id> --query outputs.lossless_audio

curl -o dubbed.wav "<lossless_audio_url>"
```

O áudio dublado é salvo em `dubbed.wav` no seu diretório de trabalho.

## Lidar com falhas

Se adicionar um idioma não funcionar, adicione o mesmo idioma novamente ao projeto existente em vez de criar um novo projeto. O projeto e sua origem transcrita podem ser reutilizados, então tentar novamente o idioma é mais rápido e evita pagar a [cobrança mínima de um idioma](/docs/pt/help-center/product/dubbing/how-much-does-dubbing-cost) uma segunda vez.

Crie um novo projeto apenas se o próprio projeto atingir `failed` durante a preparação, o que significa que sua origem não pôde ser transcrita. Verifique o arquivo ou URL de origem e crie um novo projeto.

> **Tip**
>
> Workspaces Enterprise podem revisar e corrigir a transcrição de origem antes de adicionar um idioma,
> o que gera traduções mais precisas. Consulte [Refinar e gerar novamente uma dublagem](/docs/pt/eleven-api/guides/how-to/dubbing/refine-and-regenerate).

## Próximas etapas

#### [Usar sua própria transcrição](/docs/pt/eleven-api/guides/how-to/dubbing/bring-your-own-transcript)

Crie um projeto a partir de uma transcrição existente e forneça suas próprias traduções

#### [Refinar e gerar novamente uma dublagem](/docs/pt/eleven-api/guides/how-to/dubbing/refine-and-regenerate)

Edite a transcrição e as traduções de origem e gere novamente a dublagem

#### [Dublar em vários idiomas](/docs/pt/eleven-api/guides/how-to/dubbing/multiple-languages)

Adicione vários idiomas de destino a um único projeto

#### [Referência da API](/docs/pt/api-reference/dubbing/create-project)

Explore todos os parâmetros e formatos de resposta da API de Dublagem