Dubbing

Dub audio and video content into different languages while preserving voice characteristics and timing

Overview

The Dubbing API allows you to automatically dub audio and video content into different languages while preserving the original voice characteristics, emotion, and timing.

Methods

create()

Create a new dubbing project from an audio or video file.

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")

response = client.dubbing.create(
    file=open("video.mp4", "rb"),
    name="My Video Dub",
    source_lang="en",
    target_lang="es",
    num_speakers=2
)

print(f"Dubbing ID: {response.dubbing_id}")
print(f"Status: {response.status}")

file · core.File

The audio or video file to dub. Either file or source_url must be provided.

source_url · str

URL of the source video/audio file. Either file or source_url must be provided.

name · str

Name of the dubbing project for identification purposes.

source_lang · str

Source language. Expects a valid ISO 639-1 or ISO 639-3 language code (e.g., “en”, “es”, “fr”, “de”).

target_lang · str

The target language to dub the content into. Expects a valid ISO 639-1 or ISO 639-3 language code.

target_accent · str

[Experimental] An accent to apply when selecting voices from the library and to inform translation dialect preferences.

num_speakers · int

Number of speakers to use for dubbing. Set to 0 to automatically detect the number of speakers. If specified, helps the model identify distinct speakers.

watermark · bool

Whether to apply a watermark to the output video.

start_time · int

Start time of the source video/audio file in seconds. Use to dub only a portion of the content.

end_time · int

End time of the source video/audio file in seconds. Use to dub only a portion of the content.

highest_resolution · bool

Whether to use the highest resolution available for video output.

drop_background_audio · bool

Advanced setting. Whether to drop background audio from the final dub. Can improve dub quality for content that shouldn’t have background tracks, such as speeches or monologues.

use_profanity_filter · bool

[BETA] Whether transcripts should have profanities censored with the word [censored].

dubbing_studio · bool

Whether to prepare the dub for edits in dubbing studio or as a dubbing resource.

disable_voice_cloning · bool

Instead of using voice cloning, use a similar voice from the ElevenLabs Voice Library. Voices used from the library count towards workspace custom voice limits. Using this feature requires the add_voice_from_voice_library permission.

mode · str

The mode for running the dubbing job:

• automatic (default) - Automatic processing
• manual - Manual mode with CSV transcript (experimental, not recommended for production)

csv_file · core.File

CSV file containing manual transcript for dubbing. Only used when mode="manual".

csv_fps · float

Frames per second to use when parsing a CSV file. If not provided, FPS will be inferred from timecodes.

foreground_audio_file · core.File

Custom foreground audio file to use in the dub.

background_audio_file · core.File

Custom background audio file to use in the dub.

request_options · RequestOptions

Request-specific configuration.

return · DoDubbingResponse

Response containing:

• dubbing_id (str) - Unique identifier for the dubbing project
• status (str) - Current status of the dubbing job
• expected_duration_sec (int) - Expected processing time in seconds

---

get()

Get metadata about a dubbing project, including its current status.

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")

metadata = client.dubbing.get(dubbing_id="dub_abc123")

print(f"Status: {metadata.status}")
print(f"Progress: {metadata.progress}%")

if metadata.status == "completed":
    print(f"Output URL: {metadata.target_video_url}")

dubbing_id · str · required

ID of the dubbing project to retrieve.

request_options · RequestOptions

Request-specific configuration.

return · DubbingMetadataResponse

Metadata containing:

• dubbing_id (str) - Project ID
• status (str) - Current status (dubbing, dubbed, completed, failed)
• progress (float) - Completion progress percentage
• target_video_url (str) - URL to download the dubbed video (when completed)
• source_lang (str) - Source language code
• target_lang (str) - Target language code
• created_at (datetime) - Project creation timestamp

---

list()

List all dubbing projects you have access to.

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")

response = client.dubbing.list(
    page_size=20,
    dubbing_status="completed",
    filter_by_creator="personal"
)

for dub in response.items:
    print(f"{dub.name}: {dub.status}")

# Pagination
if response.next_cursor:
    next_page = client.dubbing.list(cursor=response.next_cursor)

cursor · str

Cursor for pagination. Used to fetch the next page of results. Returned in the response.

page_size · int

Maximum number of dubs to return. Cannot exceed 200, defaults to 100.

dubbing_status · str

Filter by dubbing status:

• dubbing - Currently processing
• dubbed - Dubbing complete, awaiting finalization
• completed - Fully completed
• failed - Failed processing

filter_by_creator · str

Filter by creator:

• personal - Only dubs created by you
• shared - Only dubs shared with you

order_by · str

Field to order results by. Currently supports created_at.

order_direction · str

Order direction:

• ASCENDING - Oldest first
• DESCENDING - Newest first (default)

request_options · RequestOptions

Request-specific configuration.

return · DubbingMetadataPageResponseModel

Paginated response containing:

• items (List[DubbingMetadata]) - List of dubbing projects
• next_cursor (str) - Cursor for next page (if available)
• has_more (bool) - Whether more results exist

---

delete()

Delete a dubbing project.

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")

response = client.dubbing.delete(dubbing_id="dub_abc123")
print(f"Deleted: {response.success}")

dubbing_id · str · required

ID of the dubbing project to delete.

request_options · RequestOptions

Request-specific configuration.

return · DeleteDubbingResponseModel

Response containing:

• success (bool) - Whether deletion was successful

---

Async Methods

All methods have async equivalents:

import asyncio
from elevenlabs import AsyncElevenLabs

client = AsyncElevenLabs(api_key="YOUR_API_KEY")

async def create_dub():
    response = await client.dubbing.create(
        file=open("video.mp4", "rb"),
        source_lang="en",
        target_lang="es"
    )
    
    # Poll for completion
    while True:
        metadata = await client.dubbing.get(response.dubbing_id)
        if metadata.status == "completed":
            print(f"Done! Download from: {metadata.target_video_url}")
            break
        await asyncio.sleep(5)

asyncio.run(create_dub())

Use Cases

• Content localization: Dub videos for international audiences
• E-learning: Translate educational content while preserving instructor’s voice characteristics
• Marketing: Adapt promotional videos for different markets
• Entertainment: Localize movies, TV shows, and podcasts
• Accessibility: Make content available in multiple languages