Overview The Dubbing API allows you to automatically translate and dub audio or video files into different languages while preserving the original speaker’s voice characteristics and timing.
Create a Dubbing Project Dub a video or audio file into a target language:
from elevenlabs.client import ElevenLabs client = ElevenLabs( api_key = "YOUR_API_KEY" ) response = client.dubbing.create( file = open ( "video.mp4" , "rb" ), name = "My First Dub" , source_lang = "en" , target_lang = "es" , num_speakers = 1 ) print ( f "Dubbing ID: { response.dubbing_id } " ) print ( f "Expected duration: { response.expected_duration_sec } s" )
From URL Dub content directly from a URL:
response = client.dubbing.create( source_url = "https://example.com/video.mp4" , name = "URL Dubbing Project" , source_lang = "en" , target_lang = "fr" , num_speakers = 2 )
Parameters The audio or video file to dub (either file or source_url required).
URL of the source video/audio file (either file or source_url required).
Name of the dubbing project.
Source language. Expects a valid ISO 639-1 or ISO 639-3 language code.
Target language to dub the content into. Expects a valid ISO 639-1 or ISO 639-3 language code.
Number of speakers in the content. Set to 0 to automatically detect.
[Experimental] An accent to apply when selecting voices from the library.
Whether to apply watermark to the output video.
Start time of the source video/audio file in seconds.
End time of the source video/audio file in seconds.
Whether to use the highest resolution available.
Whether to drop background audio from the final dub. Can improve quality for speeches or monologues.
[BETA] Whether transcripts should have profanities censored with ‘[censored]’.
Whether to prepare dub for edits in dubbing studio.
Use similar voices from the ElevenLabs Voice Library instead of voice cloning.
Check Dubbing Status Monitor the progress of your dubbing project:
metadata = client.dubbing.get( dubbing_id = "your-dubbing-id" ) print ( f "Status: { metadata.status } " ) print ( f "Name: { metadata.name } " ) print ( f "Source language: { metadata.source_language } " ) print ( f "Target language: { metadata.target_language } " )
Wait for Completion Poll until dubbing is complete:
import time def wait_for_dubbing ( client , dubbing_id , max_wait = 600 ): """Wait for dubbing to complete""" start_time = time.time() while time.time() - start_time < max_wait: metadata = client.dubbing.get(dubbing_id) if metadata.status == "dubbed" : print ( "Dubbing complete!" ) return metadata elif metadata.status == "dubbing" : print ( f "Still processing... ( { metadata.status } )" ) time.sleep( 10 ) else : print ( f "Status: { metadata.status } " ) time.sleep( 5 ) raise TimeoutError ( "Dubbing took too long" ) metadata = wait_for_dubbing(client, response.dubbing_id)
Download Dubbed Audio Retrieve the dubbed audio file:
# Get the dubbed audio for the target language audio_data = client.dubbing.audio.get( dubbing_id = "your-dubbing-id" , language_code = "es" ) # Save to file with open ( "dubbed_audio.mp4" , "wb" ) as f: for chunk in audio_data: f.write(chunk)
List Dubbing Projects Retrieve all your dubbing projects:
response = client.dubbing.list( page_size = 10 , dubbing_status = "dubbed" , order_direction = "DESCENDING" ) for dub in response.dubbings: print ( f " { dub.name } : { dub.status } " ) # Pagination if response.next_cursor: next_page = client.dubbing.list( cursor = response.next_cursor, page_size = 10 )
Delete a Dubbing Project Remove a dubbing project:
response = client.dubbing.delete( dubbing_id = "your-dubbing-id" ) print ( f "Deleted: { response.success } " )
Advanced Options Automatic Speaker Detection Let the system detect the number of speakers:
response = client.dubbing.create( file = open ( "podcast.mp3" , "rb" ), name = "Podcast Dub" , source_lang = "en" , target_lang = "de" , num_speakers = 0 # Auto-detect )
Segment-Specific Dubbing Dub only a portion of the content:
response = client.dubbing.create( file = open ( "long_video.mp4" , "rb" ), name = "Video Segment" , source_lang = "en" , target_lang = "ja" , start_time = 60 , # Start at 1 minute end_time = 180 , # End at 3 minutes num_speakers = 1 )
Drop Background Audio Improve clarity for speech-only content:
response = client.dubbing.create( file = open ( "speech.mp3" , "rb" ), name = "Clean Speech" , source_lang = "en" , target_lang = "it" , drop_background_audio = True , # Remove background audio num_speakers = 1 )
Use Voice Library Instead of Cloning response = client.dubbing.create( file = open ( "video.mp4" , "rb" ), name = "Library Voices" , source_lang = "en" , target_lang = "pt" , disable_voice_cloning = True , # Use Voice Library num_speakers = 2 )
Complete Example Full workflow from creation to download:
import time from elevenlabs.client import ElevenLabs client = ElevenLabs( api_key = "YOUR_API_KEY" ) # Create dubbing project print ( "Creating dubbing project..." ) response = client.dubbing.create( file = open ( "interview.mp4" , "rb" ), name = "Interview Spanish Dub" , source_lang = "en" , target_lang = "es" , num_speakers = 2 , highest_resolution = True ) dubbing_id = response.dubbing_id print ( f "Dubbing ID: { dubbing_id } " ) # Wait for completion print ( "Waiting for dubbing to complete..." ) while True : metadata = client.dubbing.get(dubbing_id) print ( f "Status: { metadata.status } " ) if metadata.status == "dubbed" : break elif metadata.status in [ "error" , "failed" ]: raise Exception ( f "Dubbing failed: { metadata.error_message } " ) time.sleep( 10 ) # Download the dubbed video print ( "Downloading dubbed content..." ) audio_data = client.dubbing.audio.get( dubbing_id = dubbing_id, language_code = "es" ) with open ( "interview_spanish.mp4" , "wb" ) as f: for chunk in audio_data: f.write(chunk) print ( "Dubbing complete!" )
Async Support All operations support async:
import asyncio from elevenlabs.client import AsyncElevenLabs async def dub_content (): client = AsyncElevenLabs( api_key = "YOUR_API_KEY" ) response = await client.dubbing.create( file = open ( "video.mp4" , "rb" ), name = "Async Dub" , source_lang = "en" , target_lang = "fr" , num_speakers = 1 ) return response.dubbing_id dubbing_id = asyncio.run(dub_content())
Supported Languages Dubbing supports 30+ languages. Use ISO 639-1 or ISO 639-3 codes:
English: en
Spanish: es
French: fr
German: de
Italian: it
Portuguese: pt
Japanese: ja
Korean: ko
And many more…
Use Cases
Content Localization Reach global audiences with dubbed content
E-Learning Make educational content accessible worldwide
Marketing Videos Create multilingual marketing campaigns
Entertainment Dub movies, shows, and podcasts
Best Practices
Provide accurate speaker counts for better results
Use drop_background_audio=True for speech-only content
Enable highest_resolution=True for video content
Set appropriate start/end times for long content
Use automatic speaker detection (num_speakers=0) when unsure
Dubbing is a resource-intensive operation and may take several minutes depending on content length and complexity.