> 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.

# Guida rapida al doppiaggio

Questa guida mostra come doppiare un file multimediale in un'altra lingua con l'API di doppiaggio. In questo esempio crei un progetto di doppiaggio da un file audio in inglese e generi un doppiaggio in spagnolo.

Un progetto di doppiaggio ha due parti: un **progetto**, che contiene una sorgente multimediale e la relativa trascrizione, e una o più **lingue di destinazione**, ognuna delle quali produce un output doppiato in una singola lingua. Crei un progetto, attendi che la sorgente venga trascritta, aggiungi una lingua e poi scarichi il doppiaggio completato.

> **Note**
>
> La creazione di un progetto comporta l'addebito anticipato di una lingua — il costo minimo di un progetto di doppiaggio.
> Questo prepagamento copre la prima lingua di destinazione: la prima lingua che aggiungi lo utilizza e ogni
> lingua aggiuntiva viene addebitata separatamente. Consulta [Quanto costa il doppiaggio?](/docs/it/help-center/product/dubbing/how-much-does-dubbing-cost) per i dettagli.

Le lingue sono specificate come tag BCP-47, ad esempio `es` o `fr-CA`. Consulta le [lingue e i dialetti supportati](/docs/it/overview/capabilities/dubbing#supported-languages) per tutti i valori accettati.

## Uso dell'API di doppiaggio

#### Crea una chiave API

[Crea qui una chiave API nella dashboard](https://elevenlabs.io/app/settings/api-keys), che userai per [accedere all'API](/docs/it/api-reference/authentication) in modo sicuro.

Archivia la chiave come secret gestito e passala agli SDK come variabile d'ambiente tramite un file `.env` oppure direttamente nella configurazione della tua app, a seconda delle tue preferenze.

**`.env`**

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

#### Installa l'SDK

#### SDK

Useremo anche la libreria `dotenv` per caricare la nostra chiave API da una variabile d'ambiente.

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

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

#### CLI

Installa la CLI di ElevenLabs. Consigliamo 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**
>
> Lavori con un assistente di coding IA? Esegui `elevenlabs generate-skills` nel tuo progetto per creare un
> file `SKILL.md` per ogni gruppo di comandi in `skills/`, così il tuo assistente conosce tutte le funzionalità della CLI
> senza che tu debba incollare la documentazione. Usa `--output-dir` per inserirli altrove. Il comando legge la definizione API
> integrata della CLI, quindi non richiede una chiave API e funziona offline — inoltre rimane allineato
> alla versione della CLI che hai installato.

Poi autentica la CLI: si aprirà il browser per autorizzarla.

```bash
elevenlabs auth login
```

> **Note**
>
> L'esempio Python usa la libreria `requests` per scaricare l'audio doppiato. Installala
> con `pip install requests`.

#### Effettua la richiesta API

#### SDK

Crea un nuovo file denominato `example.py` o `example.mts`, a seconda del linguaggio scelto, e aggiungi il codice seguente:

```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**
>
> L'URL di download in `outputs.lossless_audio` è firmato e scade circa un'ora dopo la sua
> emissione. Se è scaduto, recupera nuovamente la lingua per ottenere un nuovo URL.

Poi eseguilo:

```python
python example.py
```

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

L'audio doppiato viene salvato in `dubbed.wav` nella directory di lavoro.

#### CLI

La CLI segue lo stesso flusso. Ogni passaggio stampa JSON: copia `project_id` e
`language_id` dalle risposte nel comando successivo ed esegui il polling dei comandi `get`
finché lo stato non si stabilizza.

```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>"
```

L'audio doppiato viene salvato in `dubbed.wav` nella directory di lavoro.

## Gestione degli errori

Se l'aggiunta di una lingua non riesce, aggiungi di nuovo la stessa lingua al progetto esistente anziché crearne uno nuovo. Il progetto e la sua sorgente trascritta sono riutilizzabili, quindi riprovare con la lingua è più rapido ed evita di pagare una seconda volta il [costo minimo di una lingua](/docs/it/help-center/product/dubbing/how-much-does-dubbing-cost).

Crea un nuovo progetto solo se il progetto stesso raggiunge lo stato `failed` durante la preparazione, il che significa che la sorgente non ha potuto essere trascritta. Controlla il file o l'URL sorgente, quindi crea un nuovo progetto.

> **Tip**
>
> I workspace Enterprise possono rivedere e correggere la trascrizione sorgente prima di aggiungere una lingua, ottenendo
> traduzioni più accurate. Consulta [Perfeziona e rigenera un doppiaggio](/docs/it/eleven-api/guides/how-to/dubbing/refine-and-regenerate).

## Passaggi successivi

#### [Usa la tua trascrizione](/docs/it/eleven-api/guides/how-to/dubbing/bring-your-own-transcript)

Crea un progetto da una trascrizione esistente e fornisci le tue traduzioni

#### [Perfeziona e rigenera un doppiaggio](/docs/it/eleven-api/guides/how-to/dubbing/refine-and-regenerate)

Modifica la trascrizione sorgente e le traduzioni, quindi rigenera il doppiaggio

#### [Doppia in più lingue](/docs/it/eleven-api/guides/how-to/dubbing/multiple-languages)

Aggiungi più lingue di destinazione a un singolo progetto

#### [Riferimento API](/docs/it/api-reference/dubbing/create-project)

Esplora tutti i parametri e i formati di risposta dell'API di doppiaggio