Dubbing quickstart

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

https://www.youtube-nocookie.com/embed/GSk5JyiT4sU?rel=0

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.

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
JavaScript
```
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.
Python
TypeScript
Python
pip install elevenlabs pip install python-dotenv
Install the ElevenLabs CLI. Homebrew (macOS) and Scoop (Windows) are recommended.
Homebrew (macOS)
Homebrew (macOS)
brew install elevenlabs/tap/elevenlabs
Scoop (Windows)
Scoop (Windows)
scoop bucket add elevenlabs https://github.com/elevenlabs/scoop-bucket scoop install elevenlabs
npm
npm
npm install -g @elevenlabs/cli
curl
curl
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/elevenlabs/cli/releases/latest/download/elevenlabs-cli-installer.sh | sh
Working with an AI coding assistant? Run elevenlabs generate-skills in your project to write a SKILL.md for every command group into skills/, so your assistant knows the CLI's full surface without you pasting docs. Use --output-dir to put them elsewhere. This reads the CLI's own embedded API definition, so it needs no API key and works offline — and it stays in step with whichever CLI version you have installed.
Then authenticate — this opens your browser to authorize the CLI:
Bash
elevenlabs auth login
The Python example uses the requests library to download the dubbed audio. Install it with pip install requests.

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:

Python

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

Then run it:

Python

python example.py

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

The CLI mirrors the same flow. Each step prints JSON — copy the project_id and language_id from the responses into the next command, and poll the get commands until the status settles.

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

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.

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

Search documentation

Help Center

Dubbing quickstart

Using the Dubbing API

Handling failures

Next steps

Help Center