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.

Availability

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

Sourcing IPA transcriptions

A few rules of thumb for producing IPA for your own vocabulary:

• Short lists (<20 words): generate with an LLM and validate by ear.
• Longer lists: use authoritative dictionaries that publish IPA directly:
  • Cambridge Dictionary
  • Collins Dictionary
  • Oxford English Dictionary

Best practices:

• Always validate by ear. IPA that looks correct on the page can still sound off when synthesized — listen to the output before shipping.
• Match the dialect. UK and US pronunciations differ (e.g., schedule, aluminum). Make sure the IPA you choose matches the voice and audience you’re targeting.

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