Python SDK

pip install deepdub

from deepdub import DeepdubClient

# Option 1: Pass API key directly
client = DeepdubClient(api_key="dd-your-api-key")

# Option 2: Use DEEPDUB_API_KEY environment variable
# export DEEPDUB_API_KEY=dd-your-api-key
client = DeepdubClient()

audio_data = client.tts(
    text="Hello, welcome to Deepdub!",
    voice_prompt_id="your-voice-id",
    model="dd-etts-2.5",
    locale="en-US"
)

with open("output.mp3", "wb") as f:
    f.write(audio_data)

audio_data = client.tts(
    text="This demonstrates all available TTS parameters.",
    voice_prompt_id="your-voice-id",
    model="dd-etts-2.5",
    locale="en-US",
    format="mp3",
    temperature=0.7,
    variance=0.6,
    tempo=1.1,
    seed=42,
    prompt_boost=True,
    sample_rate=44100,
    accent_base_locale="en-US",
    accent_locale="fr-FR",
    accent_ratio=0.3,
)

with open("output.mp3", "wb") as f:
    f.write(audio_data)

from pathlib import Path

audio_data = client.tts(
    text="Cloning a voice from an audio sample.",
    voice_reference=Path("reference_audio.mp3"),
    model="dd-etts-2.5",
    locale="en-US",
)

with open("cloned_output.mp3", "wb") as f:
    f.write(audio_data)

response = client.tts_retro(
    text="Generate this audio for later retrieval.",
    voice_prompt_id="your-voice-id",
    model="dd-etts-2.5",
    locale="en-US"
)

audio_url = response["url"]
print(f"Audio available at: {audio_url}")

import asyncio
from deepdub import DeepdubClient

client = DeepdubClient(api_key="dd-your-api-key")

async def stream_audio():
    async with client.async_connect() as conn:
        audio = bytearray()
        async for chunk in conn.async_tts(
            text="Streaming audio in real time!",
            voice_prompt_id="your-voice-id",
            model="dd-etts-2.5",
            format="mp3",
        ):
            audio.extend(chunk)

        with open("streamed.mp3", "wb") as f:
            f.write(audio)

asyncio.run(stream_audio())

import asyncio
from deepdub import DeepdubClient

client = DeepdubClient(api_key="dd-your-api-key")

async def generate_multiple():
    async with client.async_connect() as conn:
        async def generate_one(text, filename):
            audio = bytearray()
            async for chunk in conn.async_tts(
                text=text,
                voice_prompt_id="your-voice-id",
                model="dd-etts-2.5",
                format="mp3",
            ):
                audio.extend(chunk)
            with open(filename, "wb") as f:
                f.write(audio)

        await asyncio.gather(
            generate_one("First sentence.", "out1.mp3"),
            generate_one("Second sentence.", "out2.mp3"),
            generate_one("Third sentence.", "out3.mp3"),
        )

asyncio.run(generate_multiple())

import asyncio
from deepdub import DeepdubClient

client = DeepdubClient(api_key="dd-your-api-key")

async def streaming_input():
    async with client.async_stream_connect(
        model="dd-etts-2.5",
        locale="en-US",
        voice_prompt_id="your-voice-id",
        format="wav",
        sample_rate=16000,
    ) as conn:
        await conn.async_stream_text("Hello, ")
        await conn.async_stream_text("this is streamed ")
        await conn.async_stream_text("text input.")

        while True:
            audio = await conn.async_stream_recv_audio()
            if audio is None:
                break
            # Process audio chunk...

asyncio.run(streaming_input())

import asyncio
from pathlib import Path
from deepdub import DeepdubClient

client = DeepdubClient(api_key="dd-your-api-key")

async def classify():
    async with client.async_connect() as conn:
        result = await conn.gender_classify(
            audio_data=Path("speaker_sample.wav"),
            sample_rate=16000,
            timeout=5.0,
        )
        print(result)

asyncio.run(classify())

voices = client.list_voices()

for voice in voices.get("voicePrompts", []):
    print(f"{voice['id']}: {voice.get('name', voice.get('title', 'Untitled'))}")

from pathlib import Path

response = client.add_voice(
    data=Path("voice_sample.wav"),
    name="Professional Narrator",
    gender="female",
    locale="en-US",
    publish=False,
    speaking_style="Neutral",
    age=30,
)

print(f"Created voice: {response}")

# List available voices
deepdub list-voices

# Upload a new voice
deepdub add-voice \
  --file path/to/audio.mp3 \
  --name "My Voice" \
  --gender male \
  --locale en-US

# Generate text-to-speech
deepdub tts \
  --text "Hello from the CLI!" \
  --voice-prompt-id your-voice-id

# Set API key via flag or environment
deepdub --api-key dd-your-key tts --text "Hello!"
export DEEPDUB_API_KEY=dd-your-key

from deepdub import DeepdubClient
import requests

client = DeepdubClient(api_key="dd-your-api-key")

try:
    audio = client.tts(
        text="Hello!",
        voice_prompt_id="your-voice-id",
    )
except requests.exceptions.HTTPError as e:
    if e.response.status_code == 401:
        print("Invalid API key")
    elif e.response.status_code == 400:
        print("Invalid request parameters")
    else:
        print(f"API error: {e}")
except ValueError as e:
    print(f"Validation error: {e}")

try:
    async with client.async_connect() as conn:
        async for chunk in conn.async_tts(text="Hello!", voice_prompt_id="id"):
            pass
except Exception as e:
    error_msg = str(e)
    # Possible errors: "Rate limit exceeded", "Insufficient credits", etc.
    print(f"WebSocket error: {error_msg}")