Dubbing quickstart | ElevenLabs Documentation

This guide shows you how to dub a media file into another language with the Dubbing API. In this example you create a dubbing project from an English audio file and generate a Spanish dub.

A dubbing project has two parts: a project, which holds one source of media and its transcript, and one or more language targets, each producing a dubbed output in a single language. You create a project, wait for its source to be transcribed, add a language, then download the finished dub.

Creating a project charges you for one language up front — a dubbing project’s minimum charge. This prepays your first language target: the first language you add consumes it, and each additional language is charged separately. See How much does Dubbing cost? for details.

Languages are specified as BCP-47 tags, for example es or fr-CA. See the supported languages and dialects for all accepted values.

Using the Dubbing API

Create an API key

Create an API key in the dashboard here, which you’ll use to securely access the API.

Store the key as a managed secret and pass it to the SDKs either as a environment variable via an .env file, or directly in your app’s configuration depending on your preference.

.env

1 ELEVENLABS_API_KEY=<your_api_key_here>

Install the SDK

SDK

CLI

We’ll also use the dotenv library to load our API key from an environment variable.

1 pip install elevenlabs
2 pip install python-dotenv

The Python example uses the requests library to download the dubbed audio. Install it with pip install requests.

Make the API request

SDK

CLI

Create a new file named example.py or example.mts, depending on your language of choice, and add the following code:

1 # example.py
2 import os
3 import time
4 import requests
5 from dotenv import load_dotenv
6 from elevenlabs.client import ElevenLabs
7 
8 load_dotenv()
9 
10 elevenlabs = ElevenLabs(
11     api_key=os.getenv("ELEVENLABS_API_KEY"),
12 )
13 
14 # 1. Create a project from a source URL
15 project = elevenlabs.dubbing.project.create(
16     source_url="https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3",
17     source_language="en",
18     reference="Quickstart dub",
19 )
20 
21 # 2. Wait for the source media to be transcribed
22 while True:
23     project = elevenlabs.dubbing.project.get(project.project_id)
24     if project.status == "ready":
25         break
26     if project.status == "failed":
27         raise RuntimeError("Project preparation failed")
28     print("Preparing project...")
29     time.sleep(5)
30 
31 # 3. Add a Spanish language target
32 language = elevenlabs.dubbing.project.language.create(
33     project.project_id,
34     target_language="es",
35 )
36 
37 # 4. Wait for the dub to finish generating
38 while True:
39     language = elevenlabs.dubbing.project.language.get(
40         project.project_id, language.language_id
41     )
42     if language.status == "completed":
43         break
44     if language.status == "failed":
45         raise RuntimeError("Dub generation failed")
46     print("Generating dub...")
47     time.sleep(5)
48 
49 # 5. Download the dubbed audio from the signed URL
50 audio = requests.get(language.outputs.lossless_audio)
51 with open("dubbed.wav", "wb") as f:
52     f.write(audio.content)
53 
54 print("Saved dubbed audio to dubbed.wav")

The download URL in outputs.lossless_audio is signed and expires about an hour after it is issued. Fetch the language again to get a fresh URL if it has expired.

Then run it:

1 python example.py

The dubbed audio is saved to dubbed.wav in your working directory.

Handling failures

If adding a language does not succeed, add the same language to the existing project again rather than creating a new project. The project and its transcribed source are reusable, so retrying the language is faster and avoids paying the one-language minimum charge a second time.

Only create a new project if the project itself reaches failed while preparing, which means its source could not be transcribed. Check the source file or URL, then create a new project.

Enterprise workspaces can review and correct the source transcript before adding a language, which produces more accurate translations. See Refine and regenerate a dub.

Next steps

Bring your own transcript

Create a project from an existing transcript and supply your own translations

Refine and regenerate a dub

Edit the source transcript and translations, then regenerate the dub

Dub into multiple languages

Add several target languages to a single project

API reference

Explore all Dubbing API parameters and response formats