Tutorials

Dubbing quickstart

Learn how to dub audio and video files across languages using the Dubbing API.

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

1

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
ELEVENLABS_API_KEY=<your_api_key_here>
2

Install the SDK

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

pip install elevenlabs
pip install python-dotenv

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

3

Make the API request

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

# 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")

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:

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