TTS Voice Controls

Aura-2 Controls enable fine-grained adjustments to speech output, allowing you to modify speaking speed and override pronunciation for specific words. These controls are designed for enterprise use cases requiring precise voice quality for industry-specific terminology, brand names, and complex content.

Speed control

Adjust the speaking rate of generated audio. Speed control modifies the pace of speech while maintaining natural prosody and voice quality.

Parameters

Example request

$
curl --request POST \
>
     --header "Content-Type: application/json" \
>
     --header "Authorization: Token DEEPGRAM_API_KEY" \
>
     --output your_output_file.mp3 \
>
     --data '{"text":"Hello, how can I help you today?"}' \
>
     --url "https://api.deepgram.com/v1/speak?model=aura-2-thalia-en&speed=0.9"

Speed values

Pronunciation control

Override the default pronunciation of specific words using International Phonetic Alphabet (IPA) notation.

Syntax

Pronunciation overrides are specified inline within the text using escaped JSON objects:

\{"word": "dupilumab", "pronounce": "duːˈpɪljuːmæb"\}

Where:

• word is the original text (used for billing and display)
• pronounce is the IPA phonetic transcription
• Curly braces must be escaped with backslashes (\{ and \})

Example request

$
curl -X POST "https://api.deepgram.com/v1/speak?model=aura-2-thalia-en&speed=0.8" \
>
     -H "Authorization: token DEEPGRAM_API_KEY" \
>
     -H "Content-Type: application/json" \
>
     --output your_output_file.mp3 \
>
     -d '{"text": "Take \\{\"word\": \"Azathioprine\", \"pronounce\": \"æzəˈθaɪəpriːn\"\\} twice daily with \\{\"word\": \"dupilumab\", \"pronounce\": \"duːˈpɪljuːmæb\"\\}."}'

Common use cases

Validation rules

Combining controls

Speed and pronunciation controls can be used together in the same request.

Healthcare example

1
from deepgram import DeepgramClient
2
from deepgram.core.request_options import RequestOptions
3
4
client = DeepgramClient(api_key="YOUR_API_KEY")
5
6
# Speed control via request_options
7
request_opts = RequestOptions(additional_query_parameters={"speed": "0.8"})
8
9
# Inline IPA replacements with escaped curly braces
10
text = r'Take \{"word": "Azathioprine", "pronounce": "æzəˈθaɪəpriːn"\} twice daily with \{"word": "dupilumab", "pronounce": "duːˈpɪljuːmæb"\}.'
11
12
response = client.speak.v1.audio.generate(
13
    text=text,
14
    model="aura-2-thalia-en",
15
    encoding="mp3",
16
    request_options=request_opts
17
)
18
19
audio_bytes = b"".join(response)
20
with open("medical_instructions.mp3", "wb") as f:
21
    f.write(audio_bytes)

Brand consistency example

1
from deepgram import DeepgramClient
2
3
client = DeepgramClient(api_key="YOUR_API_KEY")
4
5
# Ensure consistent brand pronunciation with escaped braces
6
text = 'Visit \\{"word": "Hermès", "pronounce": "ɛərˈmɛz"\\} for the latest collection.'
7
8
response = client.speak.v1.audio.generate(
9
    text=text,
10
    model="aura-2-thalia-en",
11
    encoding="mp3"
12
)
13
14
audio_bytes = b"".join(response)
15
with open("brand_pronunciation.mp3", "wb") as f:
16
    f.write(audio_bytes)

IPA reference

Vowels (American English)

Consonants

Stress markers

Billing

Example: Hello, \{"word": "Mr.", "pronounce": "ˈmɪstɚ"\} Bond. is billed as Hello, Mr. Bond. (16 characters)

Response headers

HTTP/1.1 200 OK
content-type: audio/mpeg
dg-request-id: req_xyz789
dg-model-name: aura-2-thalia-en
dg-char-count: 47
dg-pronunciations-applied: 2
dg-speed-used: 0.8

Error handling

Speed out of range

1
{"err_code": "speed_out_of_range", "err_msg": "Speed must be between 0.7 and 1.5"}

Invalid pronunciation

1
{"err_code": "pronunciation_invalid", "err_msg": "Invalid IPA notation for 'azathioprine'"}

Limits

Early access scope